blob: ed09c32e05fec7b720cf6d89d59cbfd62801bd1f [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 Tarreau04df1122011-04-08 00:56:41 +02007 2011/04/08
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 :
17 This document is formated with 80 columns per line, with even number of
18 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
Willy Tarreauc57f0e22009-05-10 13:12:33 +020050
514. Proxies
524.1. Proxy keywords matrix
534.2. Alphabetically sorted keywords reference
54
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +0100555. Server and default-server options
Willy Tarreauc57f0e22009-05-10 13:12:33 +020056
576. HTTP header manipulation
58
Cyril Bonté7d38afb2010-02-03 20:41:26 +0100597. Using ACLs and pattern extraction
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200607.1. Matching integers
617.2. Matching strings
627.3. Matching regular expressions (regexes)
637.4. Matching IPv4 addresses
647.5. Available matching criteria
657.5.1. Matching at Layer 4 and below
667.5.2. Matching contents at Layer 4
677.5.3. Matching at Layer 7
687.6. Pre-defined ACLs
697.7. Using ACLs to form conditions
Cyril Bonté7d38afb2010-02-03 20:41:26 +0100707.8. Pattern extraction
Willy Tarreauc57f0e22009-05-10 13:12:33 +020071
728. Logging
738.1. Log levels
748.2. Log formats
758.2.1. Default log format
768.2.2. TCP log format
778.2.3. HTTP log format
788.3. Advanced logging options
798.3.1. Disabling logging of external tests
808.3.2. Logging before waiting for the session to terminate
818.3.3. Raising log level upon errors
828.3.4. Disabling logging of successful connections
838.4. Timing events
848.5. Session state at disconnection
858.6. Non-printable characters
868.7. Capturing HTTP cookies
878.8. Capturing HTTP headers
888.9. Examples of logs
89
909. Statistics and monitoring
919.1. CSV format
929.2. Unix Socket commands
93
94
951. Quick reminder about HTTP
96----------------------------
97
98When haproxy is running in HTTP mode, both the request and the response are
99fully analyzed and indexed, thus it becomes possible to build matching criteria
100on almost anything found in the contents.
101
102However, it is important to understand how HTTP requests and responses are
103formed, and how HAProxy decomposes them. It will then become easier to write
104correct rules and to debug existing configurations.
105
106
1071.1. The HTTP transaction model
108-------------------------------
109
110The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100111to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200112from the client to the server, a request is sent by the client on the
113connection, the server responds and the connection is closed. A new request
114will involve a new connection :
115
116 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
117
118In this mode, called the "HTTP close" mode, there are as many connection
119establishments as there are HTTP transactions. Since the connection is closed
120by the server after the response, the client does not need to know the content
121length.
122
123Due to the transactional nature of the protocol, it was possible to improve it
124to avoid closing a connection between two subsequent transactions. In this mode
125however, it is mandatory that the server indicates the content length for each
126response so that the client does not wait indefinitely. For this, a special
127header is used: "Content-length". This mode is called the "keep-alive" mode :
128
129 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
130
131Its advantages are a reduced latency between transactions, and less processing
132power required on the server side. It is generally better than the close mode,
133but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200134a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200135
136A last improvement in the communications is the pipelining mode. It still uses
137keep-alive, but the client does not wait for the first response to send the
138second request. This is useful for fetching large number of images composing a
139page :
140
141 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
142
143This can obviously have a tremendous benefit on performance because the network
144latency is eliminated between subsequent requests. Many HTTP agents do not
145correctly support pipelining since there is no way to associate a response with
146the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100147server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200148
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200149By default HAProxy operates in a tunnel-like mode with regards to persistent
150connections: for each connection it processes the first request and forwards
151everything else (including additional requests) to selected server. Once
152established, the connection is persisted both on the client and server
153sides. Use "option http-server-close" to preserve client persistent connections
154while handling every incoming request individually, dispatching them one after
155another to servers, in HTTP close mode. Use "option httpclose" to switch both
156sides to HTTP close mode. "option forceclose" and "option
157http-pretend-keepalive" help working around servers misbehaving in HTTP close
158mode.
159
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200160
1611.2. HTTP request
162-----------------
163
164First, let's consider this HTTP request :
165
166 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100167 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200168 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
169 2 Host: www.mydomain.com
170 3 User-agent: my small browser
171 4 Accept: image/jpeg, image/gif
172 5 Accept: image/png
173
174
1751.2.1. The Request line
176-----------------------
177
178Line 1 is the "request line". It is always composed of 3 fields :
179
180 - a METHOD : GET
181 - a URI : /serv/login.php?lang=en&profile=2
182 - a version tag : HTTP/1.1
183
184All of them are delimited by what the standard calls LWS (linear white spaces),
185which are commonly spaces, but can also be tabs or line feeds/carriage returns
186followed by spaces/tabs. The method itself cannot contain any colon (':') and
187is limited to alphabetic letters. All those various combinations make it
188desirable that HAProxy performs the splitting itself rather than leaving it to
189the user to write a complex or inaccurate regular expression.
190
191The URI itself can have several forms :
192
193 - A "relative URI" :
194
195 /serv/login.php?lang=en&profile=2
196
197 It is a complete URL without the host part. This is generally what is
198 received by servers, reverse proxies and transparent proxies.
199
200 - An "absolute URI", also called a "URL" :
201
202 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
203
204 It is composed of a "scheme" (the protocol name followed by '://'), a host
205 name or address, optionally a colon (':') followed by a port number, then
206 a relative URI beginning at the first slash ('/') after the address part.
207 This is generally what proxies receive, but a server supporting HTTP/1.1
208 must accept this form too.
209
210 - a star ('*') : this form is only accepted in association with the OPTIONS
211 method and is not relayable. It is used to inquiry a next hop's
212 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100213
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200214 - an address:port combination : 192.168.0.12:80
215 This is used with the CONNECT method, which is used to establish TCP
216 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
217 other protocols too.
218
219In a relative URI, two sub-parts are identified. The part before the question
220mark is called the "path". It is typically the relative path to static objects
221on the server. The part after the question mark is called the "query string".
222It is mostly used with GET requests sent to dynamic scripts and is very
223specific to the language, framework or application in use.
224
225
2261.2.2. The request headers
227--------------------------
228
229The headers start at the second line. They are composed of a name at the
230beginning of the line, immediately followed by a colon (':'). Traditionally,
231an LWS is added after the colon but that's not required. Then come the values.
232Multiple identical headers may be folded into one single line, delimiting the
233values with commas, provided that their order is respected. This is commonly
234encountered in the "Cookie:" field. A header may span over multiple lines if
235the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
236define a total of 3 values for the "Accept:" header.
237
238Contrary to a common mis-conception, header names are not case-sensitive, and
239their values are not either if they refer to other header names (such as the
240"Connection:" header).
241
242The end of the headers is indicated by the first empty line. People often say
243that it's a double line feed, which is not exact, even if a double line feed
244is one valid form of empty line.
245
246Fortunately, HAProxy takes care of all these complex combinations when indexing
247headers, checking values and counting them, so there is no reason to worry
248about the way they could be written, but it is important not to accuse an
249application of being buggy if it does unusual, valid things.
250
251Important note:
252 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
253 in the middle of headers by LWS in order to join multi-line headers. This
254 is necessary for proper analysis and helps less capable HTTP parsers to work
255 correctly and not to be fooled by such complex constructs.
256
257
2581.3. HTTP response
259------------------
260
261An HTTP response looks very much like an HTTP request. Both are called HTTP
262messages. Let's consider this HTTP response :
263
264 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100265 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200266 1 HTTP/1.1 200 OK
267 2 Content-length: 350
268 3 Content-Type: text/html
269
Willy Tarreau816b9792009-09-15 21:25:21 +0200270As a special case, HTTP supports so called "Informational responses" as status
271codes 1xx. These messages are special in that they don't convey any part of the
272response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100273continue to post its request for instance. In the case of a status 100 response
274the requested information will be carried by the next non-100 response message
275following the informational one. This implies that multiple responses may be
276sent to a single request, and that this only works when keep-alive is enabled
277(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
278correctly forward and skip them, and only process the next non-100 response. As
279such, these messages are neither logged nor transformed, unless explicitly
280state otherwise. Status 101 messages indicate that the protocol is changing
281over the same connection and that haproxy must switch to tunnel mode, just as
282if a CONNECT had occurred. Then the Upgrade header would contain additional
283information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200284
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200285
2861.3.1. The Response line
287------------------------
288
289Line 1 is the "response line". It is always composed of 3 fields :
290
291 - a version tag : HTTP/1.1
292 - a status code : 200
293 - a reason : OK
294
295The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200296 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200297 - 2xx = OK, content is following (eg: 200, 206)
298 - 3xx = OK, no content following (eg: 302, 304)
299 - 4xx = error caused by the client (eg: 401, 403, 404)
300 - 5xx = error caused by the server (eg: 500, 502, 503)
301
302Please refer to RFC2616 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100303"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200304found there, but it's a common practice to respect the well-established
305messages. It can be composed of one or multiple words, such as "OK", "Found",
306or "Authentication Required".
307
308Haproxy may emit the following status codes by itself :
309
310 Code When / reason
311 200 access to stats page, and when replying to monitoring requests
312 301 when performing a redirection, depending on the configured code
313 302 when performing a redirection, depending on the configured code
314 303 when performing a redirection, depending on the configured code
315 400 for an invalid or too large request
316 401 when an authentication is required to perform the action (when
317 accessing the stats page)
318 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
319 408 when the request timeout strikes before the request is complete
320 500 when haproxy encounters an unrecoverable internal error, such as a
321 memory allocation failure, which should never happen
322 502 when the server returns an empty, invalid or incomplete response, or
323 when an "rspdeny" filter blocks the response.
324 503 when no server was available to handle the request, or in response to
325 monitoring requests which match the "monitor fail" condition
326 504 when the response timeout strikes before the server responds
327
328The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3294.2).
330
331
3321.3.2. The response headers
333---------------------------
334
335Response headers work exactly like request headers, and as such, HAProxy uses
336the same parsing function for both. Please refer to paragraph 1.2.2 for more
337details.
338
339
3402. Configuring HAProxy
341----------------------
342
3432.1. Configuration file format
344------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200345
346HAProxy's configuration process involves 3 major sources of parameters :
347
348 - the arguments from the command-line, which always take precedence
349 - the "global" section, which sets process-wide parameters
350 - the proxies sections which can take form of "defaults", "listen",
351 "frontend" and "backend".
352
Willy Tarreau0ba27502007-12-24 16:55:16 +0100353The configuration file syntax consists in lines beginning with a keyword
354referenced in this manual, optionally followed by one or several parameters
355delimited by spaces. If spaces have to be entered in strings, then they must be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100356preceded by a backslash ('\') to be escaped. Backslashes also have to be
Willy Tarreau0ba27502007-12-24 16:55:16 +0100357escaped by doubling them.
358
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200359
3602.2. Time format
361----------------
362
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100363Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100364values are generally expressed in milliseconds (unless explicitly stated
365otherwise) but may be expressed in any other unit by suffixing the unit to the
366numeric value. It is important to consider this because it will not be repeated
367for every keyword. Supported units are :
368
369 - us : microseconds. 1 microsecond = 1/1000000 second
370 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
371 - s : seconds. 1s = 1000ms
372 - m : minutes. 1m = 60s = 60000ms
373 - h : hours. 1h = 60m = 3600s = 3600000ms
374 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
375
376
Patrick Mezard35da19c2010-06-12 17:02:47 +02003772.3. Examples
378-------------
379
380 # Simple configuration for an HTTP proxy listening on port 80 on all
381 # interfaces and forwarding requests to a single backend "servers" with a
382 # single server "server1" listening on 127.0.0.1:8000
383 global
384 daemon
385 maxconn 256
386
387 defaults
388 mode http
389 timeout connect 5000ms
390 timeout client 50000ms
391 timeout server 50000ms
392
393 frontend http-in
394 bind *:80
395 default_backend servers
396
397 backend servers
398 server server1 127.0.0.1:8000 maxconn 32
399
400
401 # The same configuration defined with a single listen block. Shorter but
402 # less expressive, especially in HTTP mode.
403 global
404 daemon
405 maxconn 256
406
407 defaults
408 mode http
409 timeout connect 5000ms
410 timeout client 50000ms
411 timeout server 50000ms
412
413 listen http-in
414 bind *:80
415 server server1 127.0.0.1:8000 maxconn 32
416
417
418Assuming haproxy is in $PATH, test these configurations in a shell with:
419
Willy Tarreauccb289d2010-12-11 20:19:38 +0100420 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200421
422
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004233. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200424--------------------
425
426Parameters in the "global" section are process-wide and often OS-specific. They
427are generally set once for all and do not need being changed once correct. Some
428of them have command-line equivalents.
429
430The following keywords are supported in the "global" section :
431
432 * Process management and security
433 - chroot
434 - daemon
435 - gid
436 - group
437 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100438 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200439 - nbproc
440 - pidfile
441 - uid
442 - ulimit-n
443 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200444 - stats
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200445 - node
446 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100447 - unix-bind
Willy Tarreaud72758d2010-01-12 10:42:19 +0100448
Willy Tarreau6a06a402007-07-15 20:15:28 +0200449 * Performance tuning
450 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200451 - maxconnrate
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100452 - maxpipes
Willy Tarreau6a06a402007-07-15 20:15:28 +0200453 - noepoll
454 - nokqueue
455 - nopoll
456 - nosepoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100457 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200458 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200459 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200460 - tune.chksize
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100461 - tune.maxaccept
462 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200463 - tune.maxrewrite
Willy Tarreaue803de22010-01-21 17:43:04 +0100464 - tune.rcvbuf.client
465 - tune.rcvbuf.server
466 - tune.sndbuf.client
467 - tune.sndbuf.server
Willy Tarreaud72758d2010-01-12 10:42:19 +0100468
Willy Tarreau6a06a402007-07-15 20:15:28 +0200469 * Debugging
470 - debug
471 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200472
473
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004743.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200475------------------------------------
476
477chroot <jail dir>
478 Changes current directory to <jail dir> and performs a chroot() there before
479 dropping privileges. This increases the security level in case an unknown
480 vulnerability would be exploited, since it would make it very hard for the
481 attacker to exploit the system. This only works when the process is started
482 with superuser privileges. It is important to ensure that <jail_dir> is both
483 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100484
Willy Tarreau6a06a402007-07-15 20:15:28 +0200485daemon
486 Makes the process fork into background. This is the recommended mode of
487 operation. It is equivalent to the command line "-D" argument. It can be
488 disabled by the command line "-db" argument.
489
490gid <number>
491 Changes the process' group ID to <number>. It is recommended that the group
492 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
493 be started with a user belonging to this group, or with superuser privileges.
494 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100495
Willy Tarreau6a06a402007-07-15 20:15:28 +0200496group <group name>
497 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
498 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100499
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200500log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200501 Adds a global syslog server. Up to two global servers can be defined. They
502 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100503 configured with "log global".
504
505 <address> can be one of:
506
Willy Tarreau2769aa02007-12-27 18:26:09 +0100507 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100508 no port is specified, 514 is used by default (the standard syslog
509 port).
510
David du Colombier24bb5f52011-03-17 10:40:23 +0100511 - An IPv6 address followed by a colon and optionally a UDP port. If
512 no port is specified, 514 is used by default (the standard syslog
513 port).
514
Robert Tsai81ae1952007-12-05 10:47:29 +0100515 - A filesystem path to a UNIX domain socket, keeping in mind
516 considerations for chroot (be sure the path is accessible inside
517 the chroot) and uid/gid (be sure the path is appropriately
518 writeable).
519
520 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200521
522 kern user mail daemon auth syslog lpr news
523 uucp cron auth2 ftp ntp audit alert cron2
524 local0 local1 local2 local3 local4 local5 local6 local7
525
526 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200527 all messages are sent. If a maximum level is specified, only messages with a
528 severity at least as important as this level will be sent. An optional minimum
529 level can be specified. If it is set, logs emitted with a more severe level
530 than this one will be capped to this level. This is used to avoid sending
531 "emerg" messages on all terminals on some default syslog configurations.
532 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200533
534 emerg alert crit err warning notice info debug
535
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100536log-send-hostname [<string>]
537 Sets the hostname field in the syslog header. If optional "string" parameter
538 is set the header is set to the string contents, otherwise uses the hostname
539 of the system. Generally used if one is not relaying logs through an
540 intermediate syslog server or for simply customizing the hostname printed in
541 the logs.
542
Kevinm48936af2010-12-22 16:08:21 +0000543log-tag <string>
544 Sets the tag field in the syslog header to this string. It defaults to the
545 program name as launched from the command line, which usually is "haproxy".
546 Sometimes it can be useful to differentiate between multiple processes
547 running on the same host.
548
Willy Tarreau6a06a402007-07-15 20:15:28 +0200549nbproc <number>
550 Creates <number> processes when going daemon. This requires the "daemon"
551 mode. By default, only one process is created, which is the recommended mode
552 of operation. For systems limited to small sets of file descriptors per
553 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
554 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
555
556pidfile <pidfile>
557 Writes pids of all daemons into file <pidfile>. This option is equivalent to
558 the "-p" command line argument. The file must be accessible to the user
559 starting the process. See also "daemon".
560
Willy Tarreaufbee7132007-10-18 13:53:22 +0200561stats socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>]
Willy Tarreau6162db22009-10-10 17:13:00 +0200562 [level <level>]
563
Willy Tarreaufbee7132007-10-18 13:53:22 +0200564 Creates a UNIX socket in stream mode at location <path>. Any previously
565 existing socket will be backed up then replaced. Connections to this socket
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100566 will return various statistics outputs and even allow some commands to be
Willy Tarreau6162db22009-10-10 17:13:00 +0200567 issued. Please consult section 9.2 "Unix Socket commands" for more details.
568
569 An optional "level" parameter can be specified to restrict the nature of
570 the commands that can be issued on the socket :
571 - "user" is the least privileged level ; only non-sensitive stats can be
572 read, and no change is allowed. It would make sense on systems where it
573 is not easy to restrict access to the socket.
574
575 - "operator" is the default level and fits most common uses. All data can
Willy Tarreau3c92c5f2011-08-28 09:45:47 +0200576 be read, and only non-sensitive changes are permitted (eg: clear max
Willy Tarreau6162db22009-10-10 17:13:00 +0200577 counters).
578
579 - "admin" should be used with care, as everything is permitted (eg: clear
580 all counters).
Willy Tarreaua8efd362008-01-03 10:19:15 +0100581
582 On platforms which support it, it is possible to restrict access to this
583 socket by specifying numerical IDs after "uid" and "gid", or valid user and
584 group names after the "user" and "group" keywords. It is also possible to
585 restrict permissions on the socket by passing an octal value after the "mode"
586 keyword (same syntax as chmod). Depending on the platform, the permissions on
587 the socket will be inherited from the directory which hosts it, or from the
588 user the process is started with.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200589
590stats timeout <timeout, in milliseconds>
591 The default timeout on the stats socket is set to 10 seconds. It is possible
592 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100593 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200594
595stats maxconn <connections>
596 By default, the stats socket is limited to 10 concurrent connections. It is
597 possible to change this value with "stats maxconn".
598
Willy Tarreau6a06a402007-07-15 20:15:28 +0200599uid <number>
600 Changes the process' user ID to <number>. It is recommended that the user ID
601 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
602 be started with superuser privileges in order to be able to switch to another
603 one. See also "gid" and "user".
604
605ulimit-n <number>
606 Sets the maximum number of per-process file-descriptors to <number>. By
607 default, it is automatically computed, so it is recommended not to use this
608 option.
609
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100610unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
611 [ group <group> ] [ gid <gid> ]
612
613 Fixes common settings to UNIX listening sockets declared in "bind" statements.
614 This is mainly used to simplify declaration of those UNIX sockets and reduce
615 the risk of errors, since those settings are most commonly required but are
616 also process-specific. The <prefix> setting can be used to force all socket
617 path to be relative to that directory. This might be needed to access another
618 component's chroot. Note that those paths are resolved before haproxy chroots
619 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
620 all have the same meaning as their homonyms used by the "bind" statement. If
621 both are specified, the "bind" statement has priority, meaning that the
622 "unix-bind" settings may be seen as process-wide default settings.
623
Willy Tarreau6a06a402007-07-15 20:15:28 +0200624user <user name>
625 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
626 See also "uid" and "group".
627
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200628node <name>
629 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
630
631 This statement is useful in HA configurations where two or more processes or
632 servers share the same IP address. By setting a different node-name on all
633 nodes, it becomes easy to immediately spot what server is handling the
634 traffic.
635
636description <text>
637 Add a text that describes the instance.
638
639 Please note that it is required to escape certain characters (# for example)
640 and this text is inserted into a html page so you should avoid using
641 "<" and ">" characters.
642
Willy Tarreau6a06a402007-07-15 20:15:28 +0200643
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006443.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200645-----------------------
646
647maxconn <number>
648 Sets the maximum per-process number of concurrent connections to <number>. It
649 is equivalent to the command-line argument "-n". Proxies will stop accepting
650 connections when this limit is reached. The "ulimit-n" parameter is
651 automatically adjusted according to this value. See also "ulimit-n".
652
Willy Tarreau81c25d02011-09-07 15:17:21 +0200653maxconnrate <number>
654 Sets the maximum per-process number of connections per second to <number>.
655 Proxies will stop accepting connections when this limit is reached. It can be
656 used to limit the global capacity regardless of each frontend capacity. It is
657 important to note that this can only be used as a service protection measure,
658 as there will not necessarily be a fair share between frontends when the
659 limit is reached, so it's a good idea to also limit each frontend to some
660 value close to its expected share. Also, lowering tune.maxaccept can improve
661 fairness.
662
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100663maxpipes <number>
664 Sets the maximum per-process number of pipes to <number>. Currently, pipes
665 are only used by kernel-based tcp splicing. Since a pipe contains two file
666 descriptors, the "ulimit-n" value will be increased accordingly. The default
667 value is maxconn/4, which seems to be more than enough for most heavy usages.
668 The splice code dynamically allocates and releases pipes, and can fall back
669 to standard copy, so setting this value too low may only impact performance.
670
Willy Tarreau6a06a402007-07-15 20:15:28 +0200671noepoll
672 Disables the use of the "epoll" event polling system on Linux. It is
673 equivalent to the command-line argument "-de". The next polling system
674 used will generally be "poll". See also "nosepoll", and "nopoll".
675
676nokqueue
677 Disables the use of the "kqueue" event polling system on BSD. It is
678 equivalent to the command-line argument "-dk". The next polling system
679 used will generally be "poll". See also "nopoll".
680
681nopoll
682 Disables the use of the "poll" event polling system. It is equivalent to the
683 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100684 It should never be needed to disable "poll" since it's available on all
Willy Tarreau6a06a402007-07-15 20:15:28 +0200685 platforms supported by HAProxy. See also "nosepoll", and "nopoll" and
686 "nokqueue".
687
688nosepoll
689 Disables the use of the "speculative epoll" event polling system on Linux. It
690 is equivalent to the command-line argument "-ds". The next polling system
691 used will generally be "epoll". See also "nosepoll", and "nopoll".
692
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100693nosplice
694 Disables the use of kernel tcp splicing between sockets on Linux. It is
695 equivalent to the command line argument "-dS". Data will then be copied
696 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100697 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100698 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
699 be used. This option makes it easier to globally disable kernel splicing in
700 case of doubt. See also "option splice-auto", "option splice-request" and
701 "option splice-response".
702
Willy Tarreaufe255b72007-10-14 23:09:26 +0200703spread-checks <0..50, in percent>
704 Sometimes it is desirable to avoid sending health checks to servers at exact
705 intervals, for instance when many logical servers are located on the same
706 physical server. With the help of this parameter, it becomes possible to add
707 some randomness in the check interval between 0 and +/- 50%. A value between
708 2 and 5 seems to show good results. The default value remains at 0.
709
Willy Tarreau27a674e2009-08-17 07:23:33 +0200710tune.bufsize <number>
711 Sets the buffer size to this size (in bytes). Lower values allow more
712 sessions to coexist in the same amount of RAM, and higher values allow some
713 applications with very large cookies to work. The default value is 16384 and
714 can be changed at build time. It is strongly recommended not to change this
715 from the default value, as very low values will break some services such as
716 statistics, and values larger than default size will increase memory usage,
717 possibly causing the system to run out of memory. At least the global maxconn
718 parameter should be decreased by the same factor as this one is increased.
719
Willy Tarreau43961d52010-10-04 20:39:20 +0200720tune.chksize <number>
721 Sets the check buffer size to this size (in bytes). Higher values may help
722 find string or regex patterns in very large pages, though doing so may imply
723 more memory and CPU usage. The default value is 16384 and can be changed at
724 build time. It is not recommended to change this value, but to use better
725 checks whenever possible.
726
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100727tune.maxaccept <number>
728 Sets the maximum number of consecutive accepts that a process may perform on
729 a single wake up. High values give higher priority to high connection rates,
730 while lower values give higher priority to already established connections.
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100731 This value is limited to 100 by default in single process mode. However, in
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100732 multi-process mode (nbproc > 1), it defaults to 8 so that when one process
733 wakes up, it does not take all incoming connections for itself and leaves a
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100734 part of them to other processes. Setting this value to -1 completely disables
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100735 the limitation. It should normally not be needed to tweak this value.
736
737tune.maxpollevents <number>
738 Sets the maximum amount of events that can be processed at once in a call to
739 the polling system. The default value is adapted to the operating system. It
740 has been noticed that reducing it below 200 tends to slightly decrease
741 latency at the expense of network bandwidth, and increasing it above 200
742 tends to trade latency for slightly increased bandwidth.
743
Willy Tarreau27a674e2009-08-17 07:23:33 +0200744tune.maxrewrite <number>
745 Sets the reserved buffer space to this size in bytes. The reserved space is
746 used for header rewriting or appending. The first reads on sockets will never
747 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
748 bufsize, though that does not make much sense since there are rarely large
749 numbers of headers to add. Setting it too high prevents processing of large
750 requests or responses. Setting it too low prevents addition of new headers
751 to already large requests or to POST requests. It is generally wise to set it
752 to about 1024. It is automatically readjusted to half of bufsize if it is
753 larger than that. This means you don't have to worry about it when changing
754 bufsize.
755
Willy Tarreaue803de22010-01-21 17:43:04 +0100756tune.rcvbuf.client <number>
757tune.rcvbuf.server <number>
758 Forces the kernel socket receive buffer size on the client or the server side
759 to the specified value in bytes. This value applies to all TCP/HTTP frontends
760 and backends. It should normally never be set, and the default size (0) lets
761 the kernel autotune this value depending on the amount of available memory.
762 However it can sometimes help to set it to very low values (eg: 4096) in
763 order to save kernel memory by preventing it from buffering too large amounts
764 of received data. Lower values will significantly increase CPU usage though.
765
766tune.sndbuf.client <number>
767tune.sndbuf.server <number>
768 Forces the kernel socket send buffer size on the client or the server side to
769 the specified value in bytes. This value applies to all TCP/HTTP frontends
770 and backends. It should normally never be set, and the default size (0) lets
771 the kernel autotune this value depending on the amount of available memory.
772 However it can sometimes help to set it to very low values (eg: 4096) in
773 order to save kernel memory by preventing it from buffering too large amounts
774 of received data. Lower values will significantly increase CPU usage though.
775 Another use case is to prevent write timeouts with extremely slow clients due
776 to the kernel waiting for a large part of the buffer to be read before
777 notifying haproxy again.
778
Willy Tarreau6a06a402007-07-15 20:15:28 +0200779
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007803.3. Debugging
781--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200782
783debug
784 Enables debug mode which dumps to stdout all exchanges, and disables forking
785 into background. It is the equivalent of the command-line argument "-d". It
786 should never be used in a production configuration since it may prevent full
787 system startup.
788
789quiet
790 Do not display any message during startup. It is equivalent to the command-
791 line argument "-q".
792
Emeric Brunf099e792010-09-27 12:05:28 +0200793
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007943.4. Userlists
795--------------
796It is possible to control access to frontend/backend/listen sections or to
797http stats by allowing only authenticated and authorized users. To do this,
798it is required to create at least one userlist and to define users.
799
800userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100801 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100802 used to store authentication & authorization data for independent customers.
803
804group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +0100805 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100806 attach users to this group by using a comma separated list of names
807 proceeded by "users" keyword.
808
Cyril Bontéf0c60612010-02-06 14:44:47 +0100809user <username> [password|insecure-password <password>]
810 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100811 Adds user <username> to the current userlist. Both secure (encrypted) and
812 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +0100813 evaluated using the crypt(3) function so depending of the system's
814 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100815 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
816 DES-based method of crypting passwords.
817
818
819 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +0100820 userlist L1
821 group G1 users tiger,scott
822 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100823
Cyril Bontéf0c60612010-02-06 14:44:47 +0100824 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
825 user scott insecure-password elgato
826 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100827
Cyril Bontéf0c60612010-02-06 14:44:47 +0100828 userlist L2
829 group G1
830 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100831
Cyril Bontéf0c60612010-02-06 14:44:47 +0100832 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
833 user scott insecure-password elgato groups G1,G2
834 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100835
836 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200837
Emeric Brunf099e792010-09-27 12:05:28 +0200838
8393.5. Peers
840--------------
841It is possible to synchronize server entries in stick tables between several
842haproxy instances over TCP connections in a multi-master fashion. Each instance
843pushes its local updates and insertions to remote peers. Server IDs are used to
844identify servers remotely, so it is important that configurations look similar
845or at least that the same IDs are forced on each server on all participants.
846Interrupted exchanges are automatically detected and recovered from the last
847known point. In addition, during a soft restart, the old process connects to
848the new one using such a TCP connection to push all its entries before the new
849process tries to connect to other peers. That ensures very fast replication
850during a reload, it typically takes a fraction of a second even for large
851tables.
852
853peers <peersect>
854 Creates a new peer list with name <peersect>. It is an independant section,
855 which is referenced by one or more stick-tables.
856
857peer <peername> <ip>:<port>
858 Defines a peer inside a peers section.
859 If <peername> is set to the local peer name (by default hostname, or forced
860 using "-L" command line option), haproxy will listen for incoming remote peer
861 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
862 to join the remote peer, and <peername> is used at the protocol level to
863 identify and validate the remote peer on the server side.
864
865 During a soft restart, local peer <ip>:<port> is used by the old instance to
866 connect the new one and initiate a complete replication (teaching process).
867
868 It is strongly recommended to have the exact same peers declaration on all
869 peers and to only rely on the "-L" command line argument to change the local
870 peer name. This makes it easier to maintain coherent configuration files
871 across all peers.
872
873Example:
874 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100875 peer haproxy1 192.168.0.1:1024
876 peer haproxy2 192.168.0.2:1024
877 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +0200878
879 backend mybackend
880 mode tcp
881 balance roundrobin
882 stick-table type ip size 20k peers mypeers
883 stick on src
884
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100885 server srv1 192.168.0.30:80
886 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +0200887
888
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008894. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +0200890----------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100891
Willy Tarreau6a06a402007-07-15 20:15:28 +0200892Proxy configuration can be located in a set of sections :
893 - defaults <name>
894 - frontend <name>
895 - backend <name>
896 - listen <name>
897
898A "defaults" section sets default parameters for all other sections following
899its declaration. Those default parameters are reset by the next "defaults"
900section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +0100901section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200902
903A "frontend" section describes a set of listening sockets accepting client
904connections.
905
906A "backend" section describes a set of servers to which the proxy will connect
907to forward incoming connections.
908
909A "listen" section defines a complete proxy with its frontend and backend
910parts combined in one section. It is generally useful for TCP-only traffic.
911
Willy Tarreau0ba27502007-12-24 16:55:16 +0100912All proxy names must be formed from upper and lower case letters, digits,
913'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
914case-sensitive, which means that "www" and "WWW" are two different proxies.
915
916Historically, all proxy names could overlap, it just caused troubles in the
917logs. Since the introduction of content switching, it is mandatory that two
918proxies with overlapping capabilities (frontend/backend) have different names.
919However, it is still permitted that a frontend and a backend share the same
920name, as this configuration seems to be commonly encountered.
921
922Right now, two major proxy modes are supported : "tcp", also known as layer 4,
923and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100924bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +0100925protocol, and can interact with it by allowing, blocking, switching, adding,
926modifying, or removing arbitrary contents in requests or responses, based on
927arbitrary criteria.
928
Willy Tarreau0ba27502007-12-24 16:55:16 +0100929
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009304.1. Proxy keywords matrix
931--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100932
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200933The following list of keywords is supported. Most of them may only be used in a
934limited set of section types. Some of them are marked as "deprecated" because
935they are inherited from an old syntax which may be confusing or functionally
936limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100937marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200938option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +0200939and must be disabled for a specific instance. Such options may also be prefixed
940with "default" in order to restore default settings regardless of what has been
941specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100942
Willy Tarreau6a06a402007-07-15 20:15:28 +0200943
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100944 keyword defaults frontend listen backend
945------------------------------------+----------+----------+---------+---------
946acl - X X X
947appsession - - X X
948backlog X X X -
949balance X - X X
950bind - X X -
951bind-process X X X X
952block - X X X
953capture cookie - X X -
954capture request header - X X -
955capture response header - X X -
956clitimeout (deprecated) X X X -
957contimeout (deprecated) X - X X
958cookie X - X X
959default-server X - X X
960default_backend X X X -
961description - X X X
962disabled X X X X
963dispatch - - X X
964enabled X X X X
965errorfile X X X X
966errorloc X X X X
967errorloc302 X X X X
968-- keyword -------------------------- defaults - frontend - listen -- backend -
969errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +0200970force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100971fullconn X - X X
972grace X X X X
973hash-type X - X X
974http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +0100975http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +0200976http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100977http-request - X X X
978id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +0200979ignore-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100980log X X X X
981maxconn X X X -
982mode X X X X
983monitor fail - X X -
984monitor-net X X X -
985monitor-uri X X X -
986option abortonclose (*) X - X X
987option accept-invalid-http-request (*) X X X -
988option accept-invalid-http-response (*) X - X X
989option allbackups (*) X - X X
990option checkcache (*) X - X X
991option clitcpka (*) X X X -
992option contstats (*) X X X -
993option dontlog-normal (*) X X X -
994option dontlognull (*) X X X -
995option forceclose (*) X X X X
996-- keyword -------------------------- defaults - frontend - listen -- backend -
997option forwardfor X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +0200998option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +0200999option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001000option http-server-close (*) X X X X
1001option http-use-proxy-header (*) X X X -
1002option httpchk X - X X
1003option httpclose (*) X X X X
1004option httplog X X X X
1005option http_proxy (*) X X X X
1006option independant-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001007option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001008option log-health-checks (*) X - X X
1009option log-separate-errors (*) X X X -
1010option logasap (*) X X X -
1011option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001012option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001013option nolinger (*) X X X X
1014option originalto X X X X
1015option persist (*) X - X X
1016option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001017option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001018option smtpchk X - X X
1019option socket-stats (*) X X X -
1020option splice-auto (*) X X X X
1021option splice-request (*) X X X X
1022option splice-response (*) X X X X
1023option srvtcpka (*) X - X X
1024option ssl-hello-chk X - X X
1025-- keyword -------------------------- defaults - frontend - listen -- backend -
1026option tcp-smart-accept (*) X X X -
1027option tcp-smart-connect (*) X - X X
1028option tcpka X X X X
1029option tcplog X X X X
1030option transparent (*) X - X X
1031persist rdp-cookie X - X X
1032rate-limit sessions X X X -
1033redirect - X X X
1034redisp (deprecated) X - X X
1035redispatch (deprecated) X - X X
1036reqadd - X X X
1037reqallow - X X X
1038reqdel - X X X
1039reqdeny - X X X
1040reqiallow - X X X
1041reqidel - X X X
1042reqideny - X X X
1043reqipass - X X X
1044reqirep - X X X
1045reqisetbe - X X X
1046reqitarpit - X X X
1047reqpass - X X X
1048reqrep - X X X
1049-- keyword -------------------------- defaults - frontend - listen -- backend -
1050reqsetbe - X X X
1051reqtarpit - X X X
1052retries X - X X
1053rspadd - X X X
1054rspdel - X X X
1055rspdeny - X X X
1056rspidel - X X X
1057rspideny - X X X
1058rspirep - X X X
1059rsprep - X X X
1060server - - X X
1061source X - X X
1062srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001063stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001064stats auth X - X X
1065stats enable X - X X
1066stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001067stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001068stats realm X - X X
1069stats refresh X - X X
1070stats scope X - X X
1071stats show-desc X - X X
1072stats show-legends X - X X
1073stats show-node X - X X
1074stats uri X - X X
1075-- keyword -------------------------- defaults - frontend - listen -- backend -
1076stick match - - X X
1077stick on - - X X
1078stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001079stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001080stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001081tcp-request connection - X X -
1082tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001083tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001084tcp-response content - - X X
1085tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001086timeout check X - X X
1087timeout client X X X -
1088timeout clitimeout (deprecated) X X X -
1089timeout connect X - X X
1090timeout contimeout (deprecated) X - X X
1091timeout http-keep-alive X X X X
1092timeout http-request X X X X
1093timeout queue X - X X
1094timeout server X - X X
1095timeout srvtimeout (deprecated) X - X X
1096timeout tarpit X X X X
1097transparent (deprecated) X - X X
1098use_backend - X X -
1099------------------------------------+----------+----------+---------+---------
1100 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001101
Willy Tarreau0ba27502007-12-24 16:55:16 +01001102
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011034.2. Alphabetically sorted keywords reference
1104---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001105
1106This section provides a description of each keyword and its usage.
1107
1108
1109acl <aclname> <criterion> [flags] [operator] <value> ...
1110 Declare or complete an access list.
1111 May be used in sections : defaults | frontend | listen | backend
1112 no | yes | yes | yes
1113 Example:
1114 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1115 acl invalid_src src_port 0:1023
1116 acl local_dst hdr(host) -i localhost
1117
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001118 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001119
1120
Cyril Bontéb21570a2009-11-29 20:04:48 +01001121appsession <cookie> len <length> timeout <holdtime>
1122 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001123 Define session stickiness on an existing application cookie.
1124 May be used in sections : defaults | frontend | listen | backend
1125 no | no | yes | yes
1126 Arguments :
1127 <cookie> this is the name of the cookie used by the application and which
1128 HAProxy will have to learn for each new session.
1129
Cyril Bontéb21570a2009-11-29 20:04:48 +01001130 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001131 checked in each cookie value.
1132
1133 <holdtime> this is the time after which the cookie will be removed from
1134 memory if unused. If no unit is specified, this time is in
1135 milliseconds.
1136
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001137 request-learn
1138 If this option is specified, then haproxy will be able to learn
1139 the cookie found in the request in case the server does not
1140 specify any in response. This is typically what happens with
1141 PHPSESSID cookies, or when haproxy's session expires before
1142 the application's session and the correct server is selected.
1143 It is recommended to specify this option to improve reliability.
1144
Cyril Bontéb21570a2009-11-29 20:04:48 +01001145 prefix When this option is specified, haproxy will match on the cookie
1146 prefix (or URL parameter prefix). The appsession value is the
1147 data following this prefix.
1148
1149 Example :
1150 appsession ASPSESSIONID len 64 timeout 3h prefix
1151
1152 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1153 the appsession value will be XXXX=XXXXX.
1154
1155 mode This option allows to change the URL parser mode.
1156 2 modes are currently supported :
1157 - path-parameters :
1158 The parser looks for the appsession in the path parameters
1159 part (each parameter is separated by a semi-colon), which is
1160 convenient for JSESSIONID for example.
1161 This is the default mode if the option is not set.
1162 - query-string :
1163 In this mode, the parser will look for the appsession in the
1164 query string.
1165
Willy Tarreau0ba27502007-12-24 16:55:16 +01001166 When an application cookie is defined in a backend, HAProxy will check when
1167 the server sets such a cookie, and will store its value in a table, and
1168 associate it with the server's identifier. Up to <length> characters from
1169 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001170 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1171 the mode used). If a known value is found, the client will be directed to the
1172 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001173 applied. Cookies are automatically removed from memory when they have been
1174 unused for a duration longer than <holdtime>.
1175
1176 The definition of an application cookie is limited to one per backend.
1177
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001178 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1179 unless you know what you do : memory is not shared between the
1180 processes, which can result in random behaviours.
1181
Willy Tarreau0ba27502007-12-24 16:55:16 +01001182 Example :
1183 appsession JSESSIONID len 52 timeout 3h
1184
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001185 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1186 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001187
1188
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001189backlog <conns>
1190 Give hints to the system about the approximate listen backlog desired size
1191 May be used in sections : defaults | frontend | listen | backend
1192 yes | yes | yes | no
1193 Arguments :
1194 <conns> is the number of pending connections. Depending on the operating
1195 system, it may represent the number of already acknowledged
1196 connections, of non-acknowledged ones, or both.
1197
1198 In order to protect against SYN flood attacks, one solution is to increase
1199 the system's SYN backlog size. Depending on the system, sometimes it is just
1200 tunable via a system parameter, sometimes it is not adjustable at all, and
1201 sometimes the system relies on hints given by the application at the time of
1202 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1203 to the listen() syscall. On systems which can make use of this value, it can
1204 sometimes be useful to be able to specify a different value, hence this
1205 backlog parameter.
1206
1207 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1208 used as a hint and the system accepts up to the smallest greater power of
1209 two, and never more than some limits (usually 32768).
1210
1211 See also : "maxconn" and the target operating system's tuning guide.
1212
1213
Willy Tarreau0ba27502007-12-24 16:55:16 +01001214balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001215balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001216 Define the load balancing algorithm to be used in a backend.
1217 May be used in sections : defaults | frontend | listen | backend
1218 yes | no | yes | yes
1219 Arguments :
1220 <algorithm> is the algorithm used to select a server when doing load
1221 balancing. This only applies when no persistence information
1222 is available, or when a connection is redispatched to another
1223 server. <algorithm> may be one of the following :
1224
1225 roundrobin Each server is used in turns, according to their weights.
1226 This is the smoothest and fairest algorithm when the server's
1227 processing time remains equally distributed. This algorithm
1228 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001229 on the fly for slow starts for instance. It is limited by
1230 design to 4128 active servers per backend. Note that in some
1231 large farms, when a server becomes up after having been down
1232 for a very short time, it may sometimes take a few hundreds
1233 requests for it to be re-integrated into the farm and start
1234 receiving traffic. This is normal, though very rare. It is
1235 indicated here in case you would have the chance to observe
1236 it, so that you don't worry.
1237
1238 static-rr Each server is used in turns, according to their weights.
1239 This algorithm is as similar to roundrobin except that it is
1240 static, which means that changing a server's weight on the
1241 fly will have no effect. On the other hand, it has no design
1242 limitation on the number of servers, and when a server goes
1243 up, it is always immediately reintroduced into the farm, once
1244 the full map is recomputed. It also uses slightly less CPU to
1245 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001246
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001247 leastconn The server with the lowest number of connections receives the
1248 connection. Round-robin is performed within groups of servers
1249 of the same load to ensure that all servers will be used. Use
1250 of this algorithm is recommended where very long sessions are
1251 expected, such as LDAP, SQL, TSE, etc... but is not very well
1252 suited for protocols using short sessions such as HTTP. This
1253 algorithm is dynamic, which means that server weights may be
1254 adjusted on the fly for slow starts for instance.
1255
Willy Tarreau0ba27502007-12-24 16:55:16 +01001256 source The source IP address is hashed and divided by the total
1257 weight of the running servers to designate which server will
1258 receive the request. This ensures that the same client IP
1259 address will always reach the same server as long as no
1260 server goes down or up. If the hash result changes due to the
1261 number of running servers changing, many clients will be
1262 directed to a different server. This algorithm is generally
1263 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001264 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001265 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001266 static by default, which means that changing a server's
1267 weight on the fly will have no effect, but this can be
1268 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001269
1270 uri The left part of the URI (before the question mark) is hashed
1271 and divided by the total weight of the running servers. The
1272 result designates which server will receive the request. This
1273 ensures that a same URI will always be directed to the same
1274 server as long as no server goes up or down. This is used
1275 with proxy caches and anti-virus proxies in order to maximize
1276 the cache hit rate. Note that this algorithm may only be used
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001277 in an HTTP backend. This algorithm is static by default,
1278 which means that changing a server's weight on the fly will
1279 have no effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001280
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001281 This algorithm support two optional parameters "len" and
1282 "depth", both followed by a positive integer number. These
1283 options may be helpful when it is needed to balance servers
1284 based on the beginning of the URI only. The "len" parameter
1285 indicates that the algorithm should only consider that many
1286 characters at the beginning of the URI to compute the hash.
1287 Note that having "len" set to 1 rarely makes sense since most
1288 URIs start with a leading "/".
1289
1290 The "depth" parameter indicates the maximum directory depth
1291 to be used to compute the hash. One level is counted for each
1292 slash in the request. If both parameters are specified, the
1293 evaluation stops when either is reached.
1294
Willy Tarreau0ba27502007-12-24 16:55:16 +01001295 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001296 the query string of each HTTP GET request.
1297
1298 If the modifier "check_post" is used, then an HTTP POST
1299 request entity will be searched for the parameter argument,
Willy Tarreau61a21a32011-03-01 20:35:49 +01001300 when it is not found in a query string after a question mark
1301 ('?') in the URL. Optionally, specify a number of octets to
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001302 wait for before attempting to search the message body. If the
1303 entity can not be searched, then round robin is used for each
1304 request. For instance, if your clients always send the LB
1305 parameter in the first 128 bytes, then specify that. The
1306 default is 48. The entity data will not be scanned until the
1307 required number of octets have arrived at the gateway, this
1308 is the minimum of: (default/max_wait, Content-Length or first
1309 chunk length). If Content-Length is missing or zero, it does
1310 not need to wait for more data than the client promised to
1311 send. When Content-Length is present and larger than
1312 <max_wait>, then waiting is limited to <max_wait> and it is
1313 assumed that this will be enough data to search for the
1314 presence of the parameter. In the unlikely event that
1315 Transfer-Encoding: chunked is used, only the first chunk is
1316 scanned. Parameter values separated by a chunk boundary, may
1317 be randomly balanced if at all.
1318
1319 If the parameter is found followed by an equal sign ('=') and
1320 a value, then the value is hashed and divided by the total
1321 weight of the running servers. The result designates which
1322 server will receive the request.
1323
1324 This is used to track user identifiers in requests and ensure
1325 that a same user ID will always be sent to the same server as
1326 long as no server goes up or down. If no value is found or if
1327 the parameter is not found, then a round robin algorithm is
1328 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001329 backend. This algorithm is static by default, which means
1330 that changing a server's weight on the fly will have no
1331 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001332
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001333 hdr(<name>) The HTTP header <name> will be looked up in each HTTP request.
Benoitaffb4812009-03-25 13:02:10 +01001334 Just as with the equivalent ACL 'hdr()' function, the header
1335 name in parenthesis is not case sensitive. If the header is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001336 absent or if it does not contain any value, the roundrobin
Benoitaffb4812009-03-25 13:02:10 +01001337 algorithm is applied instead.
1338
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001339 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001340 reducing the hash algorithm to the main domain part with some
1341 specific headers such as 'Host'. For instance, in the Host
1342 value "haproxy.1wt.eu", only "1wt" will be considered.
1343
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001344 This algorithm is static by default, which means that
1345 changing a server's weight on the fly will have no effect,
1346 but this can be changed using "hash-type".
1347
Emeric Brun736aa232009-06-30 17:56:00 +02001348 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001349 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001350 The RDP cookie <name> (or "mstshash" if omitted) will be
1351 looked up and hashed for each incoming TCP request. Just as
1352 with the equivalent ACL 'req_rdp_cookie()' function, the name
1353 is not case-sensitive. This mechanism is useful as a degraded
1354 persistence mode, as it makes it possible to always send the
1355 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001356 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001357 used instead.
1358
1359 Note that for this to work, the frontend must ensure that an
1360 RDP cookie is already present in the request buffer. For this
1361 you must use 'tcp-request content accept' rule combined with
1362 a 'req_rdp_cookie_cnt' ACL.
1363
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001364 This algorithm is static by default, which means that
1365 changing a server's weight on the fly will have no effect,
1366 but this can be changed using "hash-type".
1367
Simon Hormanab814e02011-06-24 14:50:20 +09001368 See also the rdp_cookie pattern fetch function.
1369
Willy Tarreau0ba27502007-12-24 16:55:16 +01001370 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001371 algorithms. Right now, only "url_param" and "uri" support an
1372 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001373
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001374 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001375 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001376
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001377 The load balancing algorithm of a backend is set to roundrobin when no other
1378 algorithm, mode nor option have been set. The algorithm may only be set once
1379 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001380
1381 Examples :
1382 balance roundrobin
1383 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001384 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001385 balance hdr(User-Agent)
1386 balance hdr(host)
1387 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001388
1389 Note: the following caveats and limitations on using the "check_post"
1390 extension with "url_param" must be considered :
1391
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001392 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001393 to determine if the parameters will be found in the body or entity which
1394 may contain binary data. Therefore another method may be required to
1395 restrict consideration of POST requests that have no URL parameters in
1396 the body. (see acl reqideny http_end)
1397
1398 - using a <max_wait> value larger than the request buffer size does not
1399 make sense and is useless. The buffer size is set at build time, and
1400 defaults to 16 kB.
1401
1402 - Content-Encoding is not supported, the parameter search will probably
1403 fail; and load balancing will fall back to Round Robin.
1404
1405 - Expect: 100-continue is not supported, load balancing will fall back to
1406 Round Robin.
1407
1408 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1409 If the entire parameter value is not present in the first chunk, the
1410 selection of server is undefined (actually, defined by how little
1411 actually appeared in the first chunk).
1412
1413 - This feature does not support generation of a 100, 411 or 501 response.
1414
1415 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001416 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001417 white space or control characters are found, indicating the end of what
1418 might be a URL parameter list. This is probably not a concern with SGML
1419 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001420
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001421 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1422 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001423
1424
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001425bind [<address>]:<port_range> [, ...]
1426bind [<address>]:<port_range> [, ...] interface <interface>
1427bind [<address>]:<port_range> [, ...] mss <maxseg>
1428bind [<address>]:<port_range> [, ...] transparent
1429bind [<address>]:<port_range> [, ...] id <id>
1430bind [<address>]:<port_range> [, ...] name <name>
1431bind [<address>]:<port_range> [, ...] defer-accept
Willy Tarreau71c814e2010-10-29 21:56:16 +02001432bind [<address>]:<port_range> [, ...] accept-proxy
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001433bind /<path> [, ...]
1434bind /<path> [, ...] mode <mode>
1435bind /<path> [, ...] [ user <user> | uid <uid> ]
1436bind /<path> [, ...] [ group <user> | gid <gid> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001437 Define one or several listening addresses and/or ports in a frontend.
1438 May be used in sections : defaults | frontend | listen | backend
1439 no | yes | yes | no
1440 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001441 <address> is optional and can be a host name, an IPv4 address, an IPv6
1442 address, or '*'. It designates the address the frontend will
1443 listen on. If unset, all IPv4 addresses of the system will be
1444 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001445 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001446
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001447 <port_range> is either a unique TCP port, or a port range for which the
1448 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001449 above. The port is mandatory for TCP listeners. Note that in
1450 the case of an IPv6 address, the port is always the number
1451 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001452 - a numerical port (ex: '80')
1453 - a dash-delimited ports range explicitly stating the lower
1454 and upper bounds (ex: '2000-2100') which are included in
1455 the range.
1456
1457 Particular care must be taken against port ranges, because
1458 every <address:port> couple consumes one socket (= a file
1459 descriptor), so it's easy to consume lots of descriptors
1460 with a simple range, and to run out of sockets. Also, each
1461 <address:port> couple must be used only once among all
1462 instances running on a same system. Please note that binding
1463 to ports lower than 1024 generally require particular
1464 privileges to start the program, which are independant of
1465 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001466
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001467 <path> is a UNIX socket path beginning with a slash ('/'). This is
1468 alternative to the TCP listening port. Haproxy will then
1469 receive UNIX connections on the socket located at this place.
1470 The path must begin with a slash and by default is absolute.
1471 It can be relative to the prefix defined by "unix-bind" in
1472 the global section. Note that the total length of the prefix
1473 followed by the socket path cannot exceed some system limits
1474 for UNIX sockets, which commonly are set to 107 characters.
1475
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001476 <interface> is an optional physical interface name. This is currently
1477 only supported on Linux. The interface must be a physical
1478 interface, not an aliased interface. When specified, all
1479 addresses on the same line will only be accepted if the
1480 incoming packet physically come through the designated
1481 interface. It is also possible to bind multiple frontends to
1482 the same address if they are bound to different interfaces.
1483 Note that binding to a physical interface requires root
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001484 privileges. This parameter is only compatible with TCP
1485 sockets.
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001486
Willy Tarreaube1b9182009-06-14 18:48:19 +02001487 <maxseg> is an optional TCP Maximum Segment Size (MSS) value to be
1488 advertised on incoming connections. This can be used to force
1489 a lower MSS for certain specific ports, for instance for
1490 connections passing through a VPN. Note that this relies on a
1491 kernel feature which is theorically supported under Linux but
1492 was buggy in all versions prior to 2.6.28. It may or may not
Willy Tarreau48a7e722010-12-24 15:26:39 +01001493 work on other operating systems. It may also not change the
1494 advertised value but change the effective size of outgoing
1495 segments. The commonly advertised value on Ethernet networks
1496 is 1460 = 1500(MTU) - 40(IP+TCP). If this value is positive,
1497 it will be used as the advertised MSS. If it is negative, it
1498 will indicate by how much to reduce the incoming connection's
1499 advertised MSS for outgoing segments. This parameter is only
1500 compatible with TCP sockets.
Willy Tarreaube1b9182009-06-14 18:48:19 +02001501
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02001502 <id> is a persistent value for socket ID. Must be positive and
1503 unique in the proxy. An unused value will automatically be
1504 assigned if unset. Can only be used when defining only a
1505 single socket.
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02001506
1507 <name> is an optional name provided for stats
1508
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001509 <mode> is the octal mode used to define access permissions on the
1510 UNIX socket. It can also be set by default in the global
1511 section's "unix-bind" statement. Note that some platforms
1512 simply ignore this.
1513
1514 <user> is the name of user that will be marked owner of the UNIX
1515 socket. It can also be set by default in the global
1516 section's "unix-bind" statement. Note that some platforms
1517 simply ignore this.
1518
1519 <group> is the name of a group that will be used to create the UNIX
1520 socket. It can also be set by default in the global section's
1521 "unix-bind" statement. Note that some platforms simply ignore
1522 this.
1523
1524 <uid> is the uid of user that will be marked owner of the UNIX
1525 socket. It can also be set by default in the global section's
1526 "unix-bind" statement. Note that some platforms simply ignore
1527 this.
1528
1529 <gid> is the gid of a group that will be used to create the UNIX
1530 socket. It can also be set by default in the global section's
1531 "unix-bind" statement. Note that some platforms simply ignore
1532 this.
1533
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001534 transparent is an optional keyword which is supported only on certain
1535 Linux kernels. It indicates that the addresses will be bound
1536 even if they do not belong to the local machine. Any packet
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001537 targeting any of these addresses will be caught just as if
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001538 the address was locally configured. This normally requires
1539 that IP forwarding is enabled. Caution! do not use this with
1540 the default address '*', as it would redirect any traffic for
1541 the specified port. This keyword is available only when
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001542 HAProxy is built with USE_LINUX_TPROXY=1. This parameter is
1543 only compatible with TCP sockets.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001544
Willy Tarreau59f89202010-10-02 11:54:00 +02001545 defer-accept is an optional keyword which is supported only on certain
Willy Tarreaucb6cd432009-10-13 07:34:14 +02001546 Linux kernels. It states that a connection will only be
1547 accepted once some data arrive on it, or at worst after the
1548 first retransmit. This should be used only on protocols for
1549 which the client talks first (eg: HTTP). It can slightly
1550 improve performance by ensuring that most of the request is
1551 already available when the connection is accepted. On the
1552 other hand, it will not be able to detect connections which
1553 don't talk. It is important to note that this option is
1554 broken in all kernels up to 2.6.31, as the connection is
1555 never accepted until the client talks. This can cause issues
1556 with front firewalls which would see an established
1557 connection while the proxy will only see it in SYN_RECV.
1558
Willy Tarreau71c814e2010-10-29 21:56:16 +02001559 accept-proxy is an optional keyword which enforces use of the PROXY
1560 protocol over any connection accepted by this listener. The
1561 PROXY protocol dictates the layer 3/4 addresses of the
1562 incoming connection to be used everywhere an address is used,
1563 with the only exception of "tcp-request connection" rules
1564 which will only see the real connection address. Logs will
1565 reflect the addresses indicated in the protocol, unless it is
1566 violated, in which case the real address will still be used.
1567 This keyword combined with support from external components
1568 can be used as an efficient and reliable alternative to the
1569 X-Forwarded-For mechanism which is not always reliable and
1570 not even always usable.
1571
Willy Tarreau0ba27502007-12-24 16:55:16 +01001572 It is possible to specify a list of address:port combinations delimited by
1573 commas. The frontend will then listen on all of these addresses. There is no
1574 fixed limit to the number of addresses and ports which can be listened on in
1575 a frontend, as well as there is no limit to the number of "bind" statements
1576 in a frontend.
1577
1578 Example :
1579 listen http_proxy
1580 bind :80,:443
1581 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001582 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001583
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001584 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreau71c814e2010-10-29 21:56:16 +02001585 documentation.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001586
1587
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001588bind-process [ all | odd | even | <number 1-32> ] ...
1589 Limit visibility of an instance to a certain set of processes numbers.
1590 May be used in sections : defaults | frontend | listen | backend
1591 yes | yes | yes | yes
1592 Arguments :
1593 all All process will see this instance. This is the default. It
1594 may be used to override a default value.
1595
1596 odd This instance will be enabled on processes 1,3,5,...31. This
1597 option may be combined with other numbers.
1598
1599 even This instance will be enabled on processes 2,4,6,...32. This
1600 option may be combined with other numbers. Do not use it
1601 with less than 2 processes otherwise some instances might be
1602 missing from all processes.
1603
1604 number The instance will be enabled on this process number, between
1605 1 and 32. You must be careful not to reference a process
1606 number greater than the configured global.nbproc, otherwise
1607 some instances might be missing from all processes.
1608
1609 This keyword limits binding of certain instances to certain processes. This
1610 is useful in order not to have too many processes listening to the same
1611 ports. For instance, on a dual-core machine, it might make sense to set
1612 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1613 and 'even' instances.
1614
1615 At the moment, it is not possible to reference more than 32 processes using
1616 this keyword, but this should be more than enough for most setups. Please
1617 note that 'all' really means all processes and is not limited to the first
1618 32.
1619
1620 If some backends are referenced by frontends bound to other processes, the
1621 backend automatically inherits the frontend's processes.
1622
1623 Example :
1624 listen app_ip1
1625 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001626 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001627
1628 listen app_ip2
1629 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001630 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001631
1632 listen management
1633 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001634 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001635
1636 See also : "nbproc" in global section.
1637
1638
Willy Tarreau0ba27502007-12-24 16:55:16 +01001639block { if | unless } <condition>
1640 Block a layer 7 request if/unless a condition is matched
1641 May be used in sections : defaults | frontend | listen | backend
1642 no | yes | yes | yes
1643
1644 The HTTP request will be blocked very early in the layer 7 processing
1645 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001646 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001647 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001648 conditions are met or not met. There is no fixed limit to the number of
1649 "block" statements per instance.
1650
1651 Example:
1652 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1653 acl invalid_src src_port 0:1023
1654 acl local_dst hdr(host) -i localhost
1655 block if invalid_src || local_dst
1656
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001657 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001658
1659
1660capture cookie <name> len <length>
1661 Capture and log a cookie in the request and in the response.
1662 May be used in sections : defaults | frontend | listen | backend
1663 no | yes | yes | no
1664 Arguments :
1665 <name> is the beginning of the name of the cookie to capture. In order
1666 to match the exact name, simply suffix the name with an equal
1667 sign ('='). The full name will appear in the logs, which is
1668 useful with application servers which adjust both the cookie name
1669 and value (eg: ASPSESSIONXXXXX).
1670
1671 <length> is the maximum number of characters to report in the logs, which
1672 include the cookie name, the equal sign and the value, all in the
1673 standard "name=value" form. The string will be truncated on the
1674 right if it exceeds <length>.
1675
1676 Only the first cookie is captured. Both the "cookie" request headers and the
1677 "set-cookie" response headers are monitored. This is particularly useful to
1678 check for application bugs causing session crossing or stealing between
1679 users, because generally the user's cookies can only change on a login page.
1680
1681 When the cookie was not presented by the client, the associated log column
1682 will report "-". When a request does not cause a cookie to be assigned by the
1683 server, a "-" is reported in the response column.
1684
1685 The capture is performed in the frontend only because it is necessary that
1686 the log format does not change for a given frontend depending on the
1687 backends. This may change in the future. Note that there can be only one
1688 "capture cookie" statement in a frontend. The maximum capture length is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001689 configured in the sources by default to 64 characters. It is not possible to
Willy Tarreau0ba27502007-12-24 16:55:16 +01001690 specify a capture in a "defaults" section.
1691
1692 Example:
1693 capture cookie ASPSESSION len 32
1694
1695 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001696 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001697
1698
1699capture request header <name> len <length>
1700 Capture and log the first occurrence of the specified request header.
1701 May be used in sections : defaults | frontend | listen | backend
1702 no | yes | yes | no
1703 Arguments :
1704 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001705 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001706 appear in the requests, with the first letter of each word in
1707 upper case. The header name will not appear in the logs, only the
1708 value is reported, but the position in the logs is respected.
1709
1710 <length> is the maximum number of characters to extract from the value and
1711 report in the logs. The string will be truncated on the right if
1712 it exceeds <length>.
1713
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001714 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001715 value will be added to the logs between braces ('{}'). If multiple headers
1716 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001717 in the same order they were declared in the configuration. Non-existent
1718 headers will be logged just as an empty string. Common uses for request
1719 header captures include the "Host" field in virtual hosting environments, the
1720 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001721 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001722 environments to find where the request came from.
1723
1724 Note that when capturing headers such as "User-agent", some spaces may be
1725 logged, making the log analysis more difficult. Thus be careful about what
1726 you log if you know your log parser is not smart enough to rely on the
1727 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001728
1729 There is no limit to the number of captured request headers, but each capture
1730 is limited to 64 characters. In order to keep log format consistent for a
1731 same frontend, header captures can only be declared in a frontend. It is not
1732 possible to specify a capture in a "defaults" section.
1733
1734 Example:
1735 capture request header Host len 15
1736 capture request header X-Forwarded-For len 15
1737 capture request header Referrer len 15
1738
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001739 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001740 about logging.
1741
1742
1743capture response header <name> len <length>
1744 Capture and log the first occurrence of the specified response header.
1745 May be used in sections : defaults | frontend | listen | backend
1746 no | yes | yes | no
1747 Arguments :
1748 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001749 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001750 appear in the response, with the first letter of each word in
1751 upper case. The header name will not appear in the logs, only the
1752 value is reported, but the position in the logs is respected.
1753
1754 <length> is the maximum number of characters to extract from the value and
1755 report in the logs. The string will be truncated on the right if
1756 it exceeds <length>.
1757
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001758 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001759 result will be added to the logs between braces ('{}') after the captured
1760 request headers. If multiple headers are captured, they will be delimited by
1761 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001762 the configuration. Non-existent headers will be logged just as an empty
1763 string. Common uses for response header captures include the "Content-length"
1764 header which indicates how many bytes are expected to be returned, the
1765 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001766
1767 There is no limit to the number of captured response headers, but each
1768 capture is limited to 64 characters. In order to keep log format consistent
1769 for a same frontend, header captures can only be declared in a frontend. It
1770 is not possible to specify a capture in a "defaults" section.
1771
1772 Example:
1773 capture response header Content-length len 9
1774 capture response header Location len 15
1775
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001776 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001777 about logging.
1778
1779
Cyril Bontéf0c60612010-02-06 14:44:47 +01001780clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001781 Set the maximum inactivity time on the client side.
1782 May be used in sections : defaults | frontend | listen | backend
1783 yes | yes | yes | no
1784 Arguments :
1785 <timeout> is the timeout value is specified in milliseconds by default, but
1786 can be in any other unit if the number is suffixed by the unit,
1787 as explained at the top of this document.
1788
1789 The inactivity timeout applies when the client is expected to acknowledge or
1790 send data. In HTTP mode, this timeout is particularly important to consider
1791 during the first phase, when the client sends the request, and during the
1792 response while it is reading data sent by the server. The value is specified
1793 in milliseconds by default, but can be in any other unit if the number is
1794 suffixed by the unit, as specified at the top of this document. In TCP mode
1795 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1796 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001797 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001798 losses by specifying timeouts that are slightly above multiples of 3 seconds
1799 (eg: 4 or 5 seconds).
1800
1801 This parameter is specific to frontends, but can be specified once for all in
1802 "defaults" sections. This is in fact one of the easiest solutions not to
1803 forget about it. An unspecified timeout results in an infinite timeout, which
1804 is not recommended. Such a usage is accepted and works but reports a warning
1805 during startup because it may results in accumulation of expired sessions in
1806 the system if the system's timeouts are not configured either.
1807
1808 This parameter is provided for compatibility but is currently deprecated.
1809 Please use "timeout client" instead.
1810
Willy Tarreau036fae02008-01-06 13:24:40 +01001811 See also : "timeout client", "timeout http-request", "timeout server", and
1812 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001813
1814
Cyril Bontéf0c60612010-02-06 14:44:47 +01001815contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001816 Set the maximum time to wait for a connection attempt to a server to succeed.
1817 May be used in sections : defaults | frontend | listen | backend
1818 yes | no | yes | yes
1819 Arguments :
1820 <timeout> is the timeout value is specified in milliseconds by default, but
1821 can be in any other unit if the number is suffixed by the unit,
1822 as explained at the top of this document.
1823
1824 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001825 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01001826 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01001827 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
1828 connect timeout also presets the queue timeout to the same value if this one
1829 has not been specified. Historically, the contimeout was also used to set the
1830 tarpit timeout in a listen section, which is not possible in a pure frontend.
1831
1832 This parameter is specific to backends, but can be specified once for all in
1833 "defaults" sections. This is in fact one of the easiest solutions not to
1834 forget about it. An unspecified timeout results in an infinite timeout, which
1835 is not recommended. Such a usage is accepted and works but reports a warning
1836 during startup because it may results in accumulation of failed sessions in
1837 the system if the system's timeouts are not configured either.
1838
1839 This parameter is provided for backwards compatibility but is currently
1840 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
1841 instead.
1842
1843 See also : "timeout connect", "timeout queue", "timeout tarpit",
1844 "timeout server", "contimeout".
1845
1846
Willy Tarreau55165fe2009-05-10 12:02:55 +02001847cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001848 [ postonly ] [ preserve ] [ domain <domain> ]*
Willy Tarreau996a92c2010-10-13 19:30:47 +02001849 [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001850 Enable cookie-based persistence in a backend.
1851 May be used in sections : defaults | frontend | listen | backend
1852 yes | no | yes | yes
1853 Arguments :
1854 <name> is the name of the cookie which will be monitored, modified or
1855 inserted in order to bring persistence. This cookie is sent to
1856 the client via a "Set-Cookie" header in the response, and is
1857 brought back by the client in a "Cookie" header in all requests.
1858 Special care should be taken to choose a name which does not
1859 conflict with any likely application cookie. Also, if the same
1860 backends are subject to be used by the same clients (eg:
1861 HTTP/HTTPS), care should be taken to use different cookie names
1862 between all backends if persistence between them is not desired.
1863
1864 rewrite This keyword indicates that the cookie will be provided by the
1865 server and that haproxy will have to modify its value to set the
1866 server's identifier in it. This mode is handy when the management
1867 of complex combinations of "Set-cookie" and "Cache-control"
1868 headers is left to the application. The application can then
1869 decide whether or not it is appropriate to emit a persistence
1870 cookie. Since all responses should be monitored, this mode only
1871 works in HTTP close mode. Unless the application behaviour is
1872 very complex and/or broken, it is advised not to start with this
1873 mode for new deployments. This keyword is incompatible with
1874 "insert" and "prefix".
1875
1876 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02001877 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001878
Willy Tarreaua79094d2010-08-31 22:54:15 +02001879 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001880 server. When used without the "preserve" option, if the server
1881 emits a cookie with the same name, it will be remove before
1882 processing. For this reason, this mode can be used to upgrade
1883 existing configurations running in the "rewrite" mode. The cookie
1884 will only be a session cookie and will not be stored on the
1885 client's disk. By default, unless the "indirect" option is added,
1886 the server will see the cookies emitted by the client. Due to
1887 caching effects, it is generally wise to add the "nocache" or
1888 "postonly" keywords (see below). The "insert" keyword is not
1889 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001890
1891 prefix This keyword indicates that instead of relying on a dedicated
1892 cookie for the persistence, an existing one will be completed.
1893 This may be needed in some specific environments where the client
1894 does not support more than one single cookie and the application
1895 already needs it. In this case, whenever the server sets a cookie
1896 named <name>, it will be prefixed with the server's identifier
1897 and a delimiter. The prefix will be removed from all client
1898 requests so that the server still finds the cookie it emitted.
1899 Since all requests and responses are subject to being modified,
1900 this mode requires the HTTP close mode. The "prefix" keyword is
1901 not compatible with "rewrite" and "insert".
1902
Willy Tarreaua79094d2010-08-31 22:54:15 +02001903 indirect When this option is specified, no cookie will be emitted to a
1904 client which already has a valid one for the server which has
1905 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001906 it will be removed, unless the "preserve" option is also set. In
1907 "insert" mode, this will additionally remove cookies from the
1908 requests transmitted to the server, making the persistence
1909 mechanism totally transparent from an application point of view.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001910
1911 nocache This option is recommended in conjunction with the insert mode
1912 when there is a cache between the client and HAProxy, as it
1913 ensures that a cacheable response will be tagged non-cacheable if
1914 a cookie needs to be inserted. This is important because if all
1915 persistence cookies are added on a cacheable home page for
1916 instance, then all customers will then fetch the page from an
1917 outer cache and will all share the same persistence cookie,
1918 leading to one server receiving much more traffic than others.
1919 See also the "insert" and "postonly" options.
1920
1921 postonly This option ensures that cookie insertion will only be performed
1922 on responses to POST requests. It is an alternative to the
1923 "nocache" option, because POST responses are not cacheable, so
1924 this ensures that the persistence cookie will never get cached.
1925 Since most sites do not need any sort of persistence before the
1926 first POST which generally is a login request, this is a very
1927 efficient method to optimize caching without risking to find a
1928 persistence cookie in the cache.
1929 See also the "insert" and "nocache" options.
1930
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001931 preserve This option may only be used with "insert" and/or "indirect". It
1932 allows the server to emit the persistence cookie itself. In this
1933 case, if a cookie is found in the response, haproxy will leave it
1934 untouched. This is useful in order to end persistence after a
1935 logout request for instance. For this, the server just has to
1936 emit a cookie with an invalid value (eg: empty) or with a date in
1937 the past. By combining this mechanism with the "disable-on-404"
1938 check option, it is possible to perform a completely graceful
1939 shutdown because users will definitely leave the server after
1940 they logout.
1941
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001942 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001943 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01001944 name. If the domain begins with a dot, the browser is allowed to
1945 use it for any host ending with that name. It is also possible to
1946 specify several domain names by invoking this option multiple
1947 times. Some browsers might have small limits on the number of
1948 domains, so be careful when doing that. For the record, sending
1949 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001950
Willy Tarreau996a92c2010-10-13 19:30:47 +02001951 maxidle This option allows inserted cookies to be ignored after some idle
1952 time. It only works with insert-mode cookies. When a cookie is
1953 sent to the client, the date this cookie was emitted is sent too.
1954 Upon further presentations of this cookie, if the date is older
1955 than the delay indicated by the parameter (in seconds), it will
1956 be ignored. Otherwise, it will be refreshed if needed when the
1957 response is sent to the client. This is particularly useful to
1958 prevent users who never close their browsers from remaining for
1959 too long on the same server (eg: after a farm size change). When
1960 this option is set and a cookie has no date, it is always
1961 accepted, but gets refreshed in the response. This maintains the
1962 ability for admins to access their sites. Cookies that have a
1963 date in the future further than 24 hours are ignored. Doing so
1964 lets admins fix timezone issues without risking kicking users off
1965 the site.
1966
1967 maxlife This option allows inserted cookies to be ignored after some life
1968 time, whether they're in use or not. It only works with insert
1969 mode cookies. When a cookie is first sent to the client, the date
1970 this cookie was emitted is sent too. Upon further presentations
1971 of this cookie, if the date is older than the delay indicated by
1972 the parameter (in seconds), it will be ignored. If the cookie in
1973 the request has no date, it is accepted and a date will be set.
1974 Cookies that have a date in the future further than 24 hours are
1975 ignored. Doing so lets admins fix timezone issues without risking
1976 kicking users off the site. Contrary to maxidle, this value is
1977 not refreshed, only the first visit date counts. Both maxidle and
1978 maxlife may be used at the time. This is particularly useful to
1979 prevent users who never close their browsers from remaining for
1980 too long on the same server (eg: after a farm size change). This
1981 is stronger than the maxidle method in that it forces a
1982 redispatch after some absolute delay.
1983
Willy Tarreau0ba27502007-12-24 16:55:16 +01001984 There can be only one persistence cookie per HTTP backend, and it can be
1985 declared in a defaults section. The value of the cookie will be the value
1986 indicated after the "cookie" keyword in a "server" statement. If no cookie
1987 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001988
Willy Tarreau0ba27502007-12-24 16:55:16 +01001989 Examples :
1990 cookie JSESSIONID prefix
1991 cookie SRV insert indirect nocache
1992 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02001993 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01001994
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02001995 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001996 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001997
Willy Tarreau983e01e2010-01-11 18:42:06 +01001998
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001999default-server [param*]
2000 Change default options for a server in a backend
2001 May be used in sections : defaults | frontend | listen | backend
2002 yes | no | yes | yes
2003 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002004 <param*> is a list of parameters for this server. The "default-server"
2005 keyword accepts an important number of options and has a complete
2006 section dedicated to it. Please refer to section 5 for more
2007 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002008
Willy Tarreau983e01e2010-01-11 18:42:06 +01002009 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002010 default-server inter 1000 weight 13
2011
2012 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002013
Willy Tarreau983e01e2010-01-11 18:42:06 +01002014
Willy Tarreau0ba27502007-12-24 16:55:16 +01002015default_backend <backend>
2016 Specify the backend to use when no "use_backend" rule has been matched.
2017 May be used in sections : defaults | frontend | listen | backend
2018 yes | yes | yes | no
2019 Arguments :
2020 <backend> is the name of the backend to use.
2021
2022 When doing content-switching between frontend and backends using the
2023 "use_backend" keyword, it is often useful to indicate which backend will be
2024 used when no rule has matched. It generally is the dynamic backend which
2025 will catch all undetermined requests.
2026
Willy Tarreau0ba27502007-12-24 16:55:16 +01002027 Example :
2028
2029 use_backend dynamic if url_dyn
2030 use_backend static if url_css url_img extension_img
2031 default_backend dynamic
2032
Willy Tarreau2769aa02007-12-27 18:26:09 +01002033 See also : "use_backend", "reqsetbe", "reqisetbe"
2034
Willy Tarreau0ba27502007-12-24 16:55:16 +01002035
2036disabled
2037 Disable a proxy, frontend or backend.
2038 May be used in sections : defaults | frontend | listen | backend
2039 yes | yes | yes | yes
2040 Arguments : none
2041
2042 The "disabled" keyword is used to disable an instance, mainly in order to
2043 liberate a listening port or to temporarily disable a service. The instance
2044 will still be created and its configuration will be checked, but it will be
2045 created in the "stopped" state and will appear as such in the statistics. It
2046 will not receive any traffic nor will it send any health-checks or logs. It
2047 is possible to disable many instances at once by adding the "disabled"
2048 keyword in a "defaults" section.
2049
2050 See also : "enabled"
2051
2052
Willy Tarreau5ce94572010-06-07 14:35:41 +02002053dispatch <address>:<port>
2054 Set a default server address
2055 May be used in sections : defaults | frontend | listen | backend
2056 no | no | yes | yes
2057 Arguments : none
2058
2059 <address> is the IPv4 address of the default server. Alternatively, a
2060 resolvable hostname is supported, but this name will be resolved
2061 during start-up.
2062
2063 <ports> is a mandatory port specification. All connections will be sent
2064 to this port, and it is not permitted to use port offsets as is
2065 possible with normal servers.
2066
Willy Tarreau787aed52011-04-15 06:45:37 +02002067 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002068 server can take the connection. In the past it was used to forward non
2069 persistent connections to an auxiliary load balancer. Due to its simple
2070 syntax, it has also been used for simple TCP relays. It is recommended not to
2071 use it for more clarity, and to use the "server" directive instead.
2072
2073 See also : "server"
2074
2075
Willy Tarreau0ba27502007-12-24 16:55:16 +01002076enabled
2077 Enable a proxy, frontend or backend.
2078 May be used in sections : defaults | frontend | listen | backend
2079 yes | yes | yes | yes
2080 Arguments : none
2081
2082 The "enabled" keyword is used to explicitly enable an instance, when the
2083 defaults has been set to "disabled". This is very rarely used.
2084
2085 See also : "disabled"
2086
2087
2088errorfile <code> <file>
2089 Return a file contents instead of errors generated by HAProxy
2090 May be used in sections : defaults | frontend | listen | backend
2091 yes | yes | yes | yes
2092 Arguments :
2093 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002094 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002095
2096 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002097 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002098 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002099 error pages, and to use absolute paths, since files are read
2100 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002101
2102 It is important to understand that this keyword is not meant to rewrite
2103 errors returned by the server, but errors detected and returned by HAProxy.
2104 This is why the list of supported errors is limited to a small set.
2105
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002106 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2107
Willy Tarreau0ba27502007-12-24 16:55:16 +01002108 The files are returned verbatim on the TCP socket. This allows any trick such
2109 as redirections to another URL or site, as well as tricks to clean cookies,
2110 force enable or disable caching, etc... The package provides default error
2111 files returning the same contents as default errors.
2112
Willy Tarreau59140a22009-02-22 12:02:30 +01002113 The files should not exceed the configured buffer size (BUFSIZE), which
2114 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2115 not to put any reference to local contents (eg: images) in order to avoid
2116 loops between the client and HAProxy when all servers are down, causing an
2117 error to be returned instead of an image. For better HTTP compliance, it is
2118 recommended that all header lines end with CR-LF and not LF alone.
2119
Willy Tarreau0ba27502007-12-24 16:55:16 +01002120 The files are read at the same time as the configuration and kept in memory.
2121 For this reason, the errors continue to be returned even when the process is
2122 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002123 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002124 403 status code and interrogating a blocked URL.
2125
2126 See also : "errorloc", "errorloc302", "errorloc303"
2127
Willy Tarreau59140a22009-02-22 12:02:30 +01002128 Example :
2129 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2130 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2131 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2132
Willy Tarreau2769aa02007-12-27 18:26:09 +01002133
2134errorloc <code> <url>
2135errorloc302 <code> <url>
2136 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2137 May be used in sections : defaults | frontend | listen | backend
2138 yes | yes | yes | yes
2139 Arguments :
2140 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002141 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002142
2143 <url> it is the exact contents of the "Location" header. It may contain
2144 either a relative URI to an error page hosted on the same site,
2145 or an absolute URI designating an error page on another site.
2146 Special care should be given to relative URIs to avoid redirect
2147 loops if the URI itself may generate the same error (eg: 500).
2148
2149 It is important to understand that this keyword is not meant to rewrite
2150 errors returned by the server, but errors detected and returned by HAProxy.
2151 This is why the list of supported errors is limited to a small set.
2152
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002153 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2154
Willy Tarreau2769aa02007-12-27 18:26:09 +01002155 Note that both keyword return the HTTP 302 status code, which tells the
2156 client to fetch the designated URL using the same HTTP method. This can be
2157 quite problematic in case of non-GET methods such as POST, because the URL
2158 sent to the client might not be allowed for something other than GET. To
2159 workaround this problem, please use "errorloc303" which send the HTTP 303
2160 status code, indicating to the client that the URL must be fetched with a GET
2161 request.
2162
2163 See also : "errorfile", "errorloc303"
2164
2165
2166errorloc303 <code> <url>
2167 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2168 May be used in sections : defaults | frontend | listen | backend
2169 yes | yes | yes | yes
2170 Arguments :
2171 <code> is the HTTP status code. Currently, HAProxy is capable of
2172 generating codes 400, 403, 408, 500, 502, 503, and 504.
2173
2174 <url> it is the exact contents of the "Location" header. It may contain
2175 either a relative URI to an error page hosted on the same site,
2176 or an absolute URI designating an error page on another site.
2177 Special care should be given to relative URIs to avoid redirect
2178 loops if the URI itself may generate the same error (eg: 500).
2179
2180 It is important to understand that this keyword is not meant to rewrite
2181 errors returned by the server, but errors detected and returned by HAProxy.
2182 This is why the list of supported errors is limited to a small set.
2183
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002184 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2185
Willy Tarreau2769aa02007-12-27 18:26:09 +01002186 Note that both keyword return the HTTP 303 status code, which tells the
2187 client to fetch the designated URL using the same HTTP GET method. This
2188 solves the usual problems associated with "errorloc" and the 302 code. It is
2189 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002190 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002191
2192 See also : "errorfile", "errorloc", "errorloc302"
2193
2194
Willy Tarreau4de91492010-01-22 19:10:05 +01002195force-persist { if | unless } <condition>
2196 Declare a condition to force persistence on down servers
2197 May be used in sections: defaults | frontend | listen | backend
2198 no | yes | yes | yes
2199
2200 By default, requests are not dispatched to down servers. It is possible to
2201 force this using "option persist", but it is unconditional and redispatches
2202 to a valid server if "option redispatch" is set. That leaves with very little
2203 possibilities to force some requests to reach a server which is artificially
2204 marked down for maintenance operations.
2205
2206 The "force-persist" statement allows one to declare various ACL-based
2207 conditions which, when met, will cause a request to ignore the down status of
2208 a server and still try to connect to it. That makes it possible to start a
2209 server, still replying an error to the health checks, and run a specially
2210 configured browser to test the service. Among the handy methods, one could
2211 use a specific source IP address, or a specific cookie. The cookie also has
2212 the advantage that it can easily be added/removed on the browser from a test
2213 page. Once the service is validated, it is then possible to open the service
2214 to the world by returning a valid response to health checks.
2215
2216 The forced persistence is enabled when an "if" condition is met, or unless an
2217 "unless" condition is met. The final redispatch is always disabled when this
2218 is used.
2219
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002220 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002221 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002222
2223
Willy Tarreau2769aa02007-12-27 18:26:09 +01002224fullconn <conns>
2225 Specify at what backend load the servers will reach their maxconn
2226 May be used in sections : defaults | frontend | listen | backend
2227 yes | no | yes | yes
2228 Arguments :
2229 <conns> is the number of connections on the backend which will make the
2230 servers use the maximal number of connections.
2231
Willy Tarreau198a7442008-01-17 12:05:32 +01002232 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002233 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002234 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002235 load. The server will then always accept at least <minconn> connections,
2236 never more than <maxconn>, and the limit will be on the ramp between both
2237 values when the backend has less than <conns> concurrent connections. This
2238 makes it possible to limit the load on the servers during normal loads, but
2239 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002240 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002241
Willy Tarreaufbb78422011-06-05 15:38:35 +02002242 Since it's hard to get this value right, haproxy automatically sets it to
2243 10% of the sum of the maxconns of all frontends that may branch to this
2244 backend. That way it's safe to leave it unset.
2245
Willy Tarreau2769aa02007-12-27 18:26:09 +01002246 Example :
2247 # The servers will accept between 100 and 1000 concurrent connections each
2248 # and the maximum of 1000 will be reached when the backend reaches 10000
2249 # connections.
2250 backend dynamic
2251 fullconn 10000
2252 server srv1 dyn1:80 minconn 100 maxconn 1000
2253 server srv2 dyn2:80 minconn 100 maxconn 1000
2254
2255 See also : "maxconn", "server"
2256
2257
2258grace <time>
2259 Maintain a proxy operational for some time after a soft stop
2260 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002261 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002262 Arguments :
2263 <time> is the time (by default in milliseconds) for which the instance
2264 will remain operational with the frontend sockets still listening
2265 when a soft-stop is received via the SIGUSR1 signal.
2266
2267 This may be used to ensure that the services disappear in a certain order.
2268 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002269 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002270 needed by the equipment to detect the failure.
2271
2272 Note that currently, there is very little benefit in using this parameter,
2273 and it may in fact complicate the soft-reconfiguration process more than
2274 simplify it.
2275
Willy Tarreau0ba27502007-12-24 16:55:16 +01002276
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002277hash-type <method>
2278 Specify a method to use for mapping hashes to servers
2279 May be used in sections : defaults | frontend | listen | backend
2280 yes | no | yes | yes
2281 Arguments :
2282 map-based the hash table is a static array containing all alive servers.
2283 The hashes will be very smooth, will consider weights, but will
2284 be static in that weight changes while a server is up will be
2285 ignored. This means that there will be no slow start. Also,
2286 since a server is selected by its position in the array, most
2287 mappings are changed when the server count changes. This means
2288 that when a server goes up or down, or when a server is added
2289 to a farm, most connections will be redistributed to different
2290 servers. This can be inconvenient with caches for instance.
2291
Willy Tarreau798a39c2010-11-24 15:04:29 +01002292 avalanche this mechanism uses the default map-based hashing described
2293 above but applies a full avalanche hash before performing the
2294 mapping. The result is a slightly less smooth hash for most
2295 situations, but the hash becomes better than pure map-based
2296 hashes when the number of servers is a multiple of the size of
2297 the input set. When using URI hash with a number of servers
2298 multiple of 64, it's desirable to change the hash type to
2299 this value.
2300
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002301 consistent the hash table is a tree filled with many occurrences of each
2302 server. The hash key is looked up in the tree and the closest
2303 server is chosen. This hash is dynamic, it supports changing
2304 weights while the servers are up, so it is compatible with the
2305 slow start feature. It has the advantage that when a server
2306 goes up or down, only its associations are moved. When a server
2307 is added to the farm, only a few part of the mappings are
2308 redistributed, making it an ideal algorithm for caches.
2309 However, due to its principle, the algorithm will never be very
2310 smooth and it may sometimes be necessary to adjust a server's
2311 weight or its ID to get a more balanced distribution. In order
2312 to get the same distribution on multiple load balancers, it is
2313 important that all servers have the same IDs.
2314
2315 The default hash type is "map-based" and is recommended for most usages.
2316
2317 See also : "balance", "server"
2318
2319
Willy Tarreau0ba27502007-12-24 16:55:16 +01002320http-check disable-on-404
2321 Enable a maintenance mode upon HTTP/404 response to health-checks
2322 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002323 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002324 Arguments : none
2325
2326 When this option is set, a server which returns an HTTP code 404 will be
2327 excluded from further load-balancing, but will still receive persistent
2328 connections. This provides a very convenient method for Web administrators
2329 to perform a graceful shutdown of their servers. It is also important to note
2330 that a server which is detected as failed while it was in this mode will not
2331 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2332 will immediately be reinserted into the farm. The status on the stats page
2333 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002334 option only works in conjunction with the "httpchk" option. If this option
2335 is used with "http-check expect", then it has precedence over it so that 404
2336 responses will still be considered as soft-stop.
2337
2338 See also : "option httpchk", "http-check expect"
2339
2340
2341http-check expect [!] <match> <pattern>
2342 Make HTTP health checks consider reponse contents or specific status codes
2343 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02002344 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01002345 Arguments :
2346 <match> is a keyword indicating how to look for a specific pattern in the
2347 response. The keyword may be one of "status", "rstatus",
2348 "string", or "rstring". The keyword may be preceeded by an
2349 exclamation mark ("!") to negate the match. Spaces are allowed
2350 between the exclamation mark and the keyword. See below for more
2351 details on the supported keywords.
2352
2353 <pattern> is the pattern to look for. It may be a string or a regular
2354 expression. If the pattern contains spaces, they must be escaped
2355 with the usual backslash ('\').
2356
2357 By default, "option httpchk" considers that response statuses 2xx and 3xx
2358 are valid, and that others are invalid. When "http-check expect" is used,
2359 it defines what is considered valid or invalid. Only one "http-check"
2360 statement is supported in a backend. If a server fails to respond or times
2361 out, the check obviously fails. The available matches are :
2362
2363 status <string> : test the exact string match for the HTTP status code.
2364 A health check respose will be considered valid if the
2365 response's status code is exactly this string. If the
2366 "status" keyword is prefixed with "!", then the response
2367 will be considered invalid if the status code matches.
2368
2369 rstatus <regex> : test a regular expression for the HTTP status code.
2370 A health check respose will be considered valid if the
2371 response's status code matches the expression. If the
2372 "rstatus" keyword is prefixed with "!", then the response
2373 will be considered invalid if the status code matches.
2374 This is mostly used to check for multiple codes.
2375
2376 string <string> : test the exact string match in the HTTP response body.
2377 A health check respose will be considered valid if the
2378 response's body contains this exact string. If the
2379 "string" keyword is prefixed with "!", then the response
2380 will be considered invalid if the body contains this
2381 string. This can be used to look for a mandatory word at
2382 the end of a dynamic page, or to detect a failure when a
2383 specific error appears on the check page (eg: a stack
2384 trace).
2385
2386 rstring <regex> : test a regular expression on the HTTP response body.
2387 A health check respose will be considered valid if the
2388 response's body matches this expression. If the "rstring"
2389 keyword is prefixed with "!", then the response will be
2390 considered invalid if the body matches the expression.
2391 This can be used to look for a mandatory word at the end
2392 of a dynamic page, or to detect a failure when a specific
2393 error appears on the check page (eg: a stack trace).
2394
2395 It is important to note that the responses will be limited to a certain size
2396 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2397 Thus, too large responses may not contain the mandatory pattern when using
2398 "string" or "rstring". If a large response is absolutely required, it is
2399 possible to change the default max size by setting the global variable.
2400 However, it is worth keeping in mind that parsing very large responses can
2401 waste some CPU cycles, especially when regular expressions are used, and that
2402 it is always better to focus the checks on smaller resources.
2403
2404 Last, if "http-check expect" is combined with "http-check disable-on-404",
2405 then this last one has precedence when the server responds with 404.
2406
2407 Examples :
2408 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002409 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002410
2411 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002412 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002413
2414 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002415 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002416
2417 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002418 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002419
Willy Tarreaubd741542010-03-16 18:46:54 +01002420 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002421
2422
Willy Tarreauef781042010-01-27 11:53:01 +01002423http-check send-state
2424 Enable emission of a state header with HTTP health checks
2425 May be used in sections : defaults | frontend | listen | backend
2426 yes | no | yes | yes
2427 Arguments : none
2428
2429 When this option is set, haproxy will systematically send a special header
2430 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2431 how they are seen by haproxy. This can be used for instance when a server is
2432 manipulated without access to haproxy and the operator needs to know whether
2433 haproxy still sees it up or not, or if the server is the last one in a farm.
2434
2435 The header is composed of fields delimited by semi-colons, the first of which
2436 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2437 checks on the total number before transition, just as appears in the stats
2438 interface. Next headers are in the form "<variable>=<value>", indicating in
2439 no specific order some values available in the stats interface :
2440 - a variable "name", containing the name of the backend followed by a slash
2441 ("/") then the name of the server. This can be used when a server is
2442 checked in multiple backends.
2443
2444 - a variable "node" containing the name of the haproxy node, as set in the
2445 global "node" variable, otherwise the system's hostname if unspecified.
2446
2447 - a variable "weight" indicating the weight of the server, a slash ("/")
2448 and the total weight of the farm (just counting usable servers). This
2449 helps to know if other servers are available to handle the load when this
2450 one fails.
2451
2452 - a variable "scur" indicating the current number of concurrent connections
2453 on the server, followed by a slash ("/") then the total number of
2454 connections on all servers of the same backend.
2455
2456 - a variable "qcur" indicating the current number of requests in the
2457 server's queue.
2458
2459 Example of a header received by the application server :
2460 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2461 scur=13/22; qcur=0
2462
2463 See also : "option httpchk", "http-check disable-on-404"
2464
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002465http-request { allow | deny | auth [realm <realm>] }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002466 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002467 Access control for Layer 7 requests
2468
2469 May be used in sections: defaults | frontend | listen | backend
2470 no | yes | yes | yes
2471
2472 These set of options allow to fine control access to a
2473 frontend/listen/backend. Each option may be followed by if/unless and acl.
2474 First option with matched condition (or option without condition) is final.
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002475 For "deny" a 403 error will be returned, for "allow" normal processing is
2476 performed, for "auth" a 401/407 error code is returned so the client
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002477 should be asked to enter a username and password.
2478
2479 There is no fixed limit to the number of http-request statements per
2480 instance.
2481
2482 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002483 acl nagios src 192.168.129.3
2484 acl local_net src 192.168.0.0/16
2485 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002486
Cyril Bonté78caf842010-03-10 22:41:43 +01002487 http-request allow if nagios
2488 http-request allow if local_net auth_ok
2489 http-request auth realm Gimme if local_net auth_ok
2490 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002491
Cyril Bonté78caf842010-03-10 22:41:43 +01002492 Example:
2493 acl auth_ok http_auth_group(L1) G1
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002494
Cyril Bonté78caf842010-03-10 22:41:43 +01002495 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002496
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002497 See also : "stats http-request", section 3.4 about userlists and section 7
2498 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002499
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002500id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02002501 Set a persistent ID to a proxy.
2502 May be used in sections : defaults | frontend | listen | backend
2503 no | yes | yes | yes
2504 Arguments : none
2505
2506 Set a persistent ID for the proxy. This ID must be unique and positive.
2507 An unused ID will automatically be assigned if unset. The first assigned
2508 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002509
2510
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002511ignore-persist { if | unless } <condition>
2512 Declare a condition to ignore persistence
2513 May be used in sections: defaults | frontend | listen | backend
2514 no | yes | yes | yes
2515
2516 By default, when cookie persistence is enabled, every requests containing
2517 the cookie are unconditionally persistent (assuming the target server is up
2518 and running).
2519
2520 The "ignore-persist" statement allows one to declare various ACL-based
2521 conditions which, when met, will cause a request to ignore persistence.
2522 This is sometimes useful to load balance requests for static files, which
2523 oftenly don't require persistence. This can also be used to fully disable
2524 persistence for a specific User-Agent (for example, some web crawler bots).
2525
2526 Combined with "appsession", it can also help reduce HAProxy memory usage, as
2527 the appsession table won't grow if persistence is ignored.
2528
2529 The persistence is ignored when an "if" condition is met, or unless an
2530 "unless" condition is met.
2531
2532 See also : "force-persist", "cookie", and section 7 about ACL usage.
2533
2534
Willy Tarreau2769aa02007-12-27 18:26:09 +01002535log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002536log <address> <facility> [<level> [<minlevel>]]
Willy Tarreau2769aa02007-12-27 18:26:09 +01002537 Enable per-instance logging of events and traffic.
2538 May be used in sections : defaults | frontend | listen | backend
2539 yes | yes | yes | yes
2540 Arguments :
2541 global should be used when the instance's logging parameters are the
2542 same as the global ones. This is the most common usage. "global"
2543 replaces <address>, <facility> and <level> with those of the log
2544 entries found in the "global" section. Only one "log global"
2545 statement may be used per instance, and this form takes no other
2546 parameter.
2547
2548 <address> indicates where to send the logs. It takes the same format as
2549 for the "global" section's logs, and can be one of :
2550
2551 - An IPv4 address optionally followed by a colon (':') and a UDP
2552 port. If no port is specified, 514 is used by default (the
2553 standard syslog port).
2554
David du Colombier24bb5f52011-03-17 10:40:23 +01002555 - An IPv6 address followed by a colon (':') and optionally a UDP
2556 port. If no port is specified, 514 is used by default (the
2557 standard syslog port).
2558
Willy Tarreau2769aa02007-12-27 18:26:09 +01002559 - A filesystem path to a UNIX domain socket, keeping in mind
2560 considerations for chroot (be sure the path is accessible
2561 inside the chroot) and uid/gid (be sure the path is
2562 appropriately writeable).
2563
2564 <facility> must be one of the 24 standard syslog facilities :
2565
2566 kern user mail daemon auth syslog lpr news
2567 uucp cron auth2 ftp ntp audit alert cron2
2568 local0 local1 local2 local3 local4 local5 local6 local7
2569
2570 <level> is optional and can be specified to filter outgoing messages. By
2571 default, all messages are sent. If a level is specified, only
2572 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002573 will be sent. An optional minimum level can be specified. If it
2574 is set, logs emitted with a more severe level than this one will
2575 be capped to this level. This is used to avoid sending "emerg"
2576 messages on all terminals on some default syslog configurations.
2577 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002578
2579 emerg alert crit err warning notice info debug
2580
2581 Note that up to two "log" entries may be specified per instance. However, if
2582 "log global" is used and if the "global" section already contains 2 log
2583 entries, then additional log entries will be ignored.
2584
2585 Also, it is important to keep in mind that it is the frontend which decides
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002586 what to log from a connection, and that in case of content switching, the log
2587 entries from the backend will be ignored. Connections are logged at level
2588 "info".
2589
2590 However, backend log declaration define how and where servers status changes
2591 will be logged. Level "notice" will be used to indicate a server going up,
2592 "warning" will be used for termination signals and definitive service
2593 termination, and "alert" will be used for when a server goes down.
2594
2595 Note : According to RFC3164, messages are truncated to 1024 bytes before
2596 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002597
2598 Example :
2599 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002600 log 127.0.0.1:514 local0 notice # only send important events
2601 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreau2769aa02007-12-27 18:26:09 +01002602
2603
2604maxconn <conns>
2605 Fix the maximum number of concurrent connections on a frontend
2606 May be used in sections : defaults | frontend | listen | backend
2607 yes | yes | yes | no
2608 Arguments :
2609 <conns> is the maximum number of concurrent connections the frontend will
2610 accept to serve. Excess connections will be queued by the system
2611 in the socket's listen queue and will be served once a connection
2612 closes.
2613
2614 If the system supports it, it can be useful on big sites to raise this limit
2615 very high so that haproxy manages connection queues, instead of leaving the
2616 clients with unanswered connection attempts. This value should not exceed the
2617 global maxconn. Also, keep in mind that a connection contains two buffers
2618 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
2619 consumed per established connection. That means that a medium system equipped
2620 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
2621 properly tuned.
2622
2623 Also, when <conns> is set to large values, it is possible that the servers
2624 are not sized to accept such loads, and for this reason it is generally wise
2625 to assign them some reasonable connection limits.
2626
2627 See also : "server", global section's "maxconn", "fullconn"
2628
2629
2630mode { tcp|http|health }
2631 Set the running mode or protocol of the instance
2632 May be used in sections : defaults | frontend | listen | backend
2633 yes | yes | yes | yes
2634 Arguments :
2635 tcp The instance will work in pure TCP mode. A full-duplex connection
2636 will be established between clients and servers, and no layer 7
2637 examination will be performed. This is the default mode. It
2638 should be used for SSL, SSH, SMTP, ...
2639
2640 http The instance will work in HTTP mode. The client request will be
2641 analyzed in depth before connecting to any server. Any request
2642 which is not RFC-compliant will be rejected. Layer 7 filtering,
2643 processing and switching will be possible. This is the mode which
2644 brings HAProxy most of its value.
2645
2646 health The instance will work in "health" mode. It will just reply "OK"
2647 to incoming connections and close the connection. Nothing will be
2648 logged. This mode is used to reply to external components health
2649 checks. This mode is deprecated and should not be used anymore as
2650 it is possible to do the same and even better by combining TCP or
2651 HTTP modes with the "monitor" keyword.
2652
2653 When doing content switching, it is mandatory that the frontend and the
2654 backend are in the same mode (generally HTTP), otherwise the configuration
2655 will be refused.
2656
2657 Example :
2658 defaults http_instances
2659 mode http
2660
2661 See also : "monitor", "monitor-net"
2662
Willy Tarreau0ba27502007-12-24 16:55:16 +01002663
Cyril Bontéf0c60612010-02-06 14:44:47 +01002664monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01002665 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002666 May be used in sections : defaults | frontend | listen | backend
2667 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01002668 Arguments :
2669 if <cond> the monitor request will fail if the condition is satisfied,
2670 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002671 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01002672 are met, for instance a low number of servers both in a
2673 backend and its backup.
2674
2675 unless <cond> the monitor request will succeed only if the condition is
2676 satisfied, and will fail otherwise. Such a condition may be
2677 based on a test on the presence of a minimum number of active
2678 servers in a list of backends.
2679
2680 This statement adds a condition which can force the response to a monitor
2681 request to report a failure. By default, when an external component queries
2682 the URI dedicated to monitoring, a 200 response is returned. When one of the
2683 conditions above is met, haproxy will return 503 instead of 200. This is
2684 very useful to report a site failure to an external component which may base
2685 routing advertisements between multiple sites on the availability reported by
2686 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002687 criterion. Note that "monitor fail" only works in HTTP mode. Both status
2688 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002689
2690 Example:
2691 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01002692 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01002693 acl site_dead nbsrv(dynamic) lt 2
2694 acl site_dead nbsrv(static) lt 2
2695 monitor-uri /site_alive
2696 monitor fail if site_dead
2697
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002698 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002699
2700
2701monitor-net <source>
2702 Declare a source network which is limited to monitor requests
2703 May be used in sections : defaults | frontend | listen | backend
2704 yes | yes | yes | no
2705 Arguments :
2706 <source> is the source IPv4 address or network which will only be able to
2707 get monitor responses to any request. It can be either an IPv4
2708 address, a host name, or an address followed by a slash ('/')
2709 followed by a mask.
2710
2711 In TCP mode, any connection coming from a source matching <source> will cause
2712 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002713 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01002714 forwarding the connection to a remote server.
2715
2716 In HTTP mode, a connection coming from a source matching <source> will be
2717 accepted, the following response will be sent without waiting for a request,
2718 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
2719 enough for any front-end HTTP probe to detect that the service is UP and
2720 running without forwarding the request to a backend server.
2721
2722 Monitor requests are processed very early. It is not possible to block nor
2723 divert them using ACLs. They cannot be logged either, and it is the intended
2724 purpose. They are only used to report HAProxy's health to an upper component,
2725 nothing more. Right now, it is not possible to set failure conditions on
2726 requests caught by "monitor-net".
2727
Willy Tarreau95cd2832010-03-04 23:36:33 +01002728 Last, please note that only one "monitor-net" statement can be specified in
2729 a frontend. If more than one is found, only the last one will be considered.
2730
Willy Tarreau2769aa02007-12-27 18:26:09 +01002731 Example :
2732 # addresses .252 and .253 are just probing us.
2733 frontend www
2734 monitor-net 192.168.0.252/31
2735
2736 See also : "monitor fail", "monitor-uri"
2737
2738
2739monitor-uri <uri>
2740 Intercept a URI used by external components' monitor requests
2741 May be used in sections : defaults | frontend | listen | backend
2742 yes | yes | yes | no
2743 Arguments :
2744 <uri> is the exact URI which we want to intercept to return HAProxy's
2745 health status instead of forwarding the request.
2746
2747 When an HTTP request referencing <uri> will be received on a frontend,
2748 HAProxy will not forward it nor log it, but instead will return either
2749 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
2750 conditions defined with "monitor fail". This is normally enough for any
2751 front-end HTTP probe to detect that the service is UP and running without
2752 forwarding the request to a backend server. Note that the HTTP method, the
2753 version and all headers are ignored, but the request must at least be valid
2754 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
2755
2756 Monitor requests are processed very early. It is not possible to block nor
2757 divert them using ACLs. They cannot be logged either, and it is the intended
2758 purpose. They are only used to report HAProxy's health to an upper component,
2759 nothing more. However, it is possible to add any number of conditions using
2760 "monitor fail" and ACLs so that the result can be adjusted to whatever check
2761 can be imagined (most often the number of available servers in a backend).
2762
2763 Example :
2764 # Use /haproxy_test to report haproxy's status
2765 frontend www
2766 mode http
2767 monitor-uri /haproxy_test
2768
2769 See also : "monitor fail", "monitor-net"
2770
Willy Tarreau0ba27502007-12-24 16:55:16 +01002771
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002772option abortonclose
2773no option abortonclose
2774 Enable or disable early dropping of aborted requests pending in queues.
2775 May be used in sections : defaults | frontend | listen | backend
2776 yes | no | yes | yes
2777 Arguments : none
2778
2779 In presence of very high loads, the servers will take some time to respond.
2780 The per-instance connection queue will inflate, and the response time will
2781 increase respective to the size of the queue times the average per-session
2782 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01002783 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002784 the queue, and slowing down other users, and the servers as well, because the
2785 request will eventually be served, then aborted at the first error
2786 encountered while delivering the response.
2787
2788 As there is no way to distinguish between a full STOP and a simple output
2789 close on the client side, HTTP agents should be conservative and consider
2790 that the client might only have closed its output channel while waiting for
2791 the response. However, this introduces risks of congestion when lots of users
2792 do the same, and is completely useless nowadays because probably no client at
2793 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01002794 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002795 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01002796 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002797 of being the single component to break rare but valid traffic is extremely
2798 low, which adds to the temptation to be able to abort a session early while
2799 still not served and not pollute the servers.
2800
2801 In HAProxy, the user can choose the desired behaviour using the option
2802 "abortonclose". By default (without the option) the behaviour is HTTP
2803 compliant and aborted requests will be served. But when the option is
2804 specified, a session with an incoming channel closed will be aborted while
2805 it is still possible, either pending in the queue for a connection slot, or
2806 during the connection establishment if the server has not yet acknowledged
2807 the connection request. This considerably reduces the queue size and the load
2808 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01002809 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002810
2811 If this option has been enabled in a "defaults" section, it can be disabled
2812 in a specific instance by prepending the "no" keyword before it.
2813
2814 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
2815
2816
Willy Tarreau4076a152009-04-02 15:18:36 +02002817option accept-invalid-http-request
2818no option accept-invalid-http-request
2819 Enable or disable relaxing of HTTP request parsing
2820 May be used in sections : defaults | frontend | listen | backend
2821 yes | yes | yes | no
2822 Arguments : none
2823
2824 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2825 means that invalid characters in header names are not permitted and cause an
2826 error to be returned to the client. This is the desired behaviour as such
2827 forbidden characters are essentially used to build attacks exploiting server
2828 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2829 server will emit invalid header names for whatever reason (configuration,
2830 implementation) and the issue will not be immediately fixed. In such a case,
2831 it is possible to relax HAProxy's header name parser to accept any character
2832 even if that does not make sense, by specifying this option.
2833
2834 This option should never be enabled by default as it hides application bugs
2835 and open security breaches. It should only be deployed after a problem has
2836 been confirmed.
2837
2838 When this option is enabled, erroneous header names will still be accepted in
2839 requests, but the complete request will be captured in order to permit later
2840 analysis using the "show errors" request on the UNIX stats socket. Doing this
2841 also helps confirming that the issue has been solved.
2842
2843 If this option has been enabled in a "defaults" section, it can be disabled
2844 in a specific instance by prepending the "no" keyword before it.
2845
2846 See also : "option accept-invalid-http-response" and "show errors" on the
2847 stats socket.
2848
2849
2850option accept-invalid-http-response
2851no option accept-invalid-http-response
2852 Enable or disable relaxing of HTTP response parsing
2853 May be used in sections : defaults | frontend | listen | backend
2854 yes | no | yes | yes
2855 Arguments : none
2856
2857 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2858 means that invalid characters in header names are not permitted and cause an
2859 error to be returned to the client. This is the desired behaviour as such
2860 forbidden characters are essentially used to build attacks exploiting server
2861 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2862 server will emit invalid header names for whatever reason (configuration,
2863 implementation) and the issue will not be immediately fixed. In such a case,
2864 it is possible to relax HAProxy's header name parser to accept any character
2865 even if that does not make sense, by specifying this option.
2866
2867 This option should never be enabled by default as it hides application bugs
2868 and open security breaches. It should only be deployed after a problem has
2869 been confirmed.
2870
2871 When this option is enabled, erroneous header names will still be accepted in
2872 responses, but the complete response will be captured in order to permit
2873 later analysis using the "show errors" request on the UNIX stats socket.
2874 Doing this also helps confirming that the issue has been solved.
2875
2876 If this option has been enabled in a "defaults" section, it can be disabled
2877 in a specific instance by prepending the "no" keyword before it.
2878
2879 See also : "option accept-invalid-http-request" and "show errors" on the
2880 stats socket.
2881
2882
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002883option allbackups
2884no option allbackups
2885 Use either all backup servers at a time or only the first one
2886 May be used in sections : defaults | frontend | listen | backend
2887 yes | no | yes | yes
2888 Arguments : none
2889
2890 By default, the first operational backup server gets all traffic when normal
2891 servers are all down. Sometimes, it may be preferred to use multiple backups
2892 at once, because one will not be enough. When "option allbackups" is enabled,
2893 the load balancing will be performed among all backup servers when all normal
2894 ones are unavailable. The same load balancing algorithm will be used and the
2895 servers' weights will be respected. Thus, there will not be any priority
2896 order between the backup servers anymore.
2897
2898 This option is mostly used with static server farms dedicated to return a
2899 "sorry" page when an application is completely offline.
2900
2901 If this option has been enabled in a "defaults" section, it can be disabled
2902 in a specific instance by prepending the "no" keyword before it.
2903
2904
2905option checkcache
2906no option checkcache
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002907 Analyze all server responses and block requests with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002908 May be used in sections : defaults | frontend | listen | backend
2909 yes | no | yes | yes
2910 Arguments : none
2911
2912 Some high-level frameworks set application cookies everywhere and do not
2913 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002914 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002915 high risk of session crossing or stealing between users traversing the same
2916 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02002917 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002918
2919 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002920 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01002921 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002922 response to check if there's a risk of caching a cookie on a client-side
2923 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01002924 to the client are :
2925 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002926 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01002927 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002928 - all those that come from a POST request, provided that the server has not
2929 set a 'Cache-Control: public' header ;
2930 - those with a 'Pragma: no-cache' header
2931 - those with a 'Cache-control: private' header
2932 - those with a 'Cache-control: no-store' header
2933 - those with a 'Cache-control: max-age=0' header
2934 - those with a 'Cache-control: s-maxage=0' header
2935 - those with a 'Cache-control: no-cache' header
2936 - those with a 'Cache-control: no-cache="set-cookie"' header
2937 - those with a 'Cache-control: no-cache="set-cookie,' header
2938 (allowing other fields after set-cookie)
2939
2940 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01002941 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002942 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002943 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002944 that admins are informed that there's something to be fixed.
2945
2946 Due to the high impact on the application, the application should be tested
2947 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002948 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002949 production, as it will report potentially dangerous application behaviours.
2950
2951 If this option has been enabled in a "defaults" section, it can be disabled
2952 in a specific instance by prepending the "no" keyword before it.
2953
2954
2955option clitcpka
2956no option clitcpka
2957 Enable or disable the sending of TCP keepalive packets on the client side
2958 May be used in sections : defaults | frontend | listen | backend
2959 yes | yes | yes | no
2960 Arguments : none
2961
2962 When there is a firewall or any session-aware component between a client and
2963 a server, and when the protocol involves very long sessions with long idle
2964 periods (eg: remote desktops), there is a risk that one of the intermediate
2965 components decides to expire a session which has remained idle for too long.
2966
2967 Enabling socket-level TCP keep-alives makes the system regularly send packets
2968 to the other end of the connection, leaving it active. The delay between
2969 keep-alive probes is controlled by the system only and depends both on the
2970 operating system and its tuning parameters.
2971
2972 It is important to understand that keep-alive packets are neither emitted nor
2973 received at the application level. It is only the network stacks which sees
2974 them. For this reason, even if one side of the proxy already uses keep-alives
2975 to maintain its connection alive, those keep-alive packets will not be
2976 forwarded to the other side of the proxy.
2977
2978 Please note that this has nothing to do with HTTP keep-alive.
2979
2980 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
2981 client side of a connection, which should help when session expirations are
2982 noticed between HAProxy and a client.
2983
2984 If this option has been enabled in a "defaults" section, it can be disabled
2985 in a specific instance by prepending the "no" keyword before it.
2986
2987 See also : "option srvtcpka", "option tcpka"
2988
2989
Willy Tarreau0ba27502007-12-24 16:55:16 +01002990option contstats
2991 Enable continuous traffic statistics updates
2992 May be used in sections : defaults | frontend | listen | backend
2993 yes | yes | yes | no
2994 Arguments : none
2995
2996 By default, counters used for statistics calculation are incremented
2997 only when a session finishes. It works quite well when serving small
2998 objects, but with big ones (for example large images or archives) or
2999 with A/V streaming, a graph generated from haproxy counters looks like
3000 a hedgehog. With this option enabled counters get incremented continuously,
3001 during a whole session. Recounting touches a hotpath directly so
3002 it is not enabled by default, as it has small performance impact (~0.5%).
3003
3004
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003005option dontlog-normal
3006no option dontlog-normal
3007 Enable or disable logging of normal, successful connections
3008 May be used in sections : defaults | frontend | listen | backend
3009 yes | yes | yes | no
3010 Arguments : none
3011
3012 There are large sites dealing with several thousand connections per second
3013 and for which logging is a major pain. Some of them are even forced to turn
3014 logs off and cannot debug production issues. Setting this option ensures that
3015 normal connections, those which experience no error, no timeout, no retry nor
3016 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
3017 mode, the response status code is checked and return codes 5xx will still be
3018 logged.
3019
3020 It is strongly discouraged to use this option as most of the time, the key to
3021 complex issues is in the normal logs which will not be logged here. If you
3022 need to separate logs, see the "log-separate-errors" option instead.
3023
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003024 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003025 logging.
3026
3027
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003028option dontlognull
3029no option dontlognull
3030 Enable or disable logging of null connections
3031 May be used in sections : defaults | frontend | listen | backend
3032 yes | yes | yes | no
3033 Arguments : none
3034
3035 In certain environments, there are components which will regularly connect to
3036 various systems to ensure that they are still alive. It can be the case from
3037 another load balancer as well as from monitoring systems. By default, even a
3038 simple port probe or scan will produce a log. If those connections pollute
3039 the logs too much, it is possible to enable option "dontlognull" to indicate
3040 that a connection on which no data has been transferred will not be logged,
3041 which typically corresponds to those probes.
3042
3043 It is generally recommended not to use this option in uncontrolled
3044 environments (eg: internet), otherwise scans and other malicious activities
3045 would not be logged.
3046
3047 If this option has been enabled in a "defaults" section, it can be disabled
3048 in a specific instance by prepending the "no" keyword before it.
3049
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003050 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003051
3052
3053option forceclose
3054no option forceclose
3055 Enable or disable active connection closing after response is transferred.
3056 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003057 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003058 Arguments : none
3059
3060 Some HTTP servers do not necessarily close the connections when they receive
3061 the "Connection: close" set by "option httpclose", and if the client does not
3062 close either, then the connection remains open till the timeout expires. This
3063 causes high number of simultaneous connections on the servers and shows high
3064 global session times in the logs.
3065
3066 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003067 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003068 to respond. This option implicitly enables the "httpclose" option. Note that
3069 this option also enables the parsing of the full request and response, which
3070 means we can close the connection to the server very quickly, releasing some
3071 resources earlier than with httpclose.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003072
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003073 This option may also be combined with "option http-pretend-keepalive", which
3074 will disable sending of the "Connection: close" header, but will still cause
3075 the connection to be closed once the whole response is received.
3076
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003077 If this option has been enabled in a "defaults" section, it can be disabled
3078 in a specific instance by prepending the "no" keyword before it.
3079
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003080 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003081
3082
Willy Tarreau87cf5142011-08-19 22:57:24 +02003083option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003084 Enable insertion of the X-Forwarded-For header to requests sent to servers
3085 May be used in sections : defaults | frontend | listen | backend
3086 yes | yes | yes | yes
3087 Arguments :
3088 <network> is an optional argument used to disable this option for sources
3089 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003090 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003091 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003092
3093 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3094 their client address. This is sometimes annoying when the client's IP address
3095 is expected in server logs. To solve this problem, the well-known HTTP header
3096 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3097 This header contains a value representing the client's IP address. Since this
3098 header is always appended at the end of the existing header list, the server
3099 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003100 the server's manual to find how to enable use of this standard header. Note
3101 that only the last occurrence of the header must be used, since it is really
3102 possible that the client has already brought one.
3103
Willy Tarreaud72758d2010-01-12 10:42:19 +01003104 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003105 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003106 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3107 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003108 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3109 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003110
3111 Sometimes, a same HAProxy instance may be shared between a direct client
3112 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3113 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3114 header for a known source address or network by adding the "except" keyword
3115 followed by the network address. In this case, any source IP matching the
3116 network will not cause an addition of this header. Most common uses are with
3117 private networks or 127.0.0.1.
3118
Willy Tarreau87cf5142011-08-19 22:57:24 +02003119 Alternatively, the keyword "if-none" states that the header will only be
3120 added if it is not present. This should only be used in perfectly trusted
3121 environment, as this might cause a security issue if headers reaching haproxy
3122 are under the control of the end-user.
3123
Willy Tarreauc27debf2008-01-06 08:57:02 +01003124 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003125 least one of them uses it, the header will be added. Note that the backend's
3126 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02003127 both are defined. In the case of the "if-none" argument, if at least one of
3128 the frontend or the backend does not specify it, it wants the addition to be
3129 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003130
Willy Tarreau87cf5142011-08-19 22:57:24 +02003131 It is important to note that by default, HAProxy works in tunnel mode and
3132 only inspects the first request of a connection, meaning that only the first
3133 request will have the header appended, which is certainly not what you want.
3134 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3135 "http-server-close" options is set when using this option.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003136
Ross Westaf72a1d2008-08-03 10:51:45 +02003137 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003138 # Public HTTP address also used by stunnel on the same machine
3139 frontend www
3140 mode http
3141 option forwardfor except 127.0.0.1 # stunnel already adds the header
3142
Ross Westaf72a1d2008-08-03 10:51:45 +02003143 # Those servers want the IP Address in X-Client
3144 backend www
3145 mode http
3146 option forwardfor header X-Client
3147
Willy Tarreau87cf5142011-08-19 22:57:24 +02003148 See also : "option httpclose", "option http-server-close",
3149 "option forceclose"
Willy Tarreauc27debf2008-01-06 08:57:02 +01003150
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003151
Willy Tarreau96e31212011-05-30 18:10:30 +02003152option http-no-delay
3153no option http-no-delay
3154 Instruct the system to favor low interactive delays over performance in HTTP
3155 May be used in sections : defaults | frontend | listen | backend
3156 yes | yes | yes | yes
3157 Arguments : none
3158
3159 In HTTP, each payload is unidirectional and has no notion of interactivity.
3160 Any agent is expected to queue data somewhat for a reasonably low delay.
3161 There are some very rare server-to-server applications that abuse the HTTP
3162 protocol and expect the payload phase to be highly interactive, with many
3163 interleaved data chunks in both directions within a single request. This is
3164 absolutely not supported by the HTTP specification and will not work across
3165 most proxies or servers. When such applications attempt to do this through
3166 haproxy, it works but they will experience high delays due to the network
3167 optimizations which favor performance by instructing the system to wait for
3168 enough data to be available in order to only send full packets. Typical
3169 delays are around 200 ms per round trip. Note that this only happens with
3170 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
3171 affected.
3172
3173 When "option http-no-delay" is present in either the frontend or the backend
3174 used by a connection, all such optimizations will be disabled in order to
3175 make the exchanges as fast as possible. Of course this offers no guarantee on
3176 the functionality, as it may break at any other place. But if it works via
3177 HAProxy, it will work as fast as possible. This option should never be used
3178 by default, and should never be used at all unless such a buggy application
3179 is discovered. The impact of using this option is an increase of bandwidth
3180 usage and CPU usage, which may significantly lower performance in high
3181 latency environments.
3182
3183
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003184option http-pretend-keepalive
3185no option http-pretend-keepalive
3186 Define whether haproxy will announce keepalive to the server or not
3187 May be used in sections : defaults | frontend | listen | backend
3188 yes | yes | yes | yes
3189 Arguments : none
3190
3191 When running with "option http-server-close" or "option forceclose", haproxy
3192 adds a "Connection: close" header to the request forwarded to the server.
3193 Unfortunately, when some servers see this header, they automatically refrain
3194 from using the chunked encoding for responses of unknown length, while this
3195 is totally unrelated. The immediate effect is that this prevents haproxy from
3196 maintaining the client connection alive. A second effect is that a client or
3197 a cache could receive an incomplete response without being aware of it, and
3198 consider the response complete.
3199
3200 By setting "option http-pretend-keepalive", haproxy will make the server
3201 believe it will keep the connection alive. The server will then not fall back
3202 to the abnormal undesired above. When haproxy gets the whole response, it
3203 will close the connection with the server just as it would do with the
3204 "forceclose" option. That way the client gets a normal response and the
3205 connection is correctly closed on the server side.
3206
3207 It is recommended not to enable this option by default, because most servers
3208 will more efficiently close the connection themselves after the last packet,
3209 and release its buffers slightly earlier. Also, the added packet on the
3210 network could slightly reduce the overall peak performance. However it is
3211 worth noting that when this option is enabled, haproxy will have slightly
3212 less work to do. So if haproxy is the bottleneck on the whole architecture,
3213 enabling this option might save a few CPU cycles.
3214
3215 This option may be set both in a frontend and in a backend. It is enabled if
3216 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau22a95342010-09-29 14:31:41 +02003217 This option may be compbined with "option httpclose", which will cause
3218 keepalive to be announced to the server and close to be announced to the
3219 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003220
3221 If this option has been enabled in a "defaults" section, it can be disabled
3222 in a specific instance by prepending the "no" keyword before it.
3223
3224 See also : "option forceclose" and "option http-server-close"
3225
Willy Tarreauc27debf2008-01-06 08:57:02 +01003226
Willy Tarreaub608feb2010-01-02 22:47:18 +01003227option http-server-close
3228no option http-server-close
3229 Enable or disable HTTP connection closing on the server side
3230 May be used in sections : defaults | frontend | listen | backend
3231 yes | yes | yes | yes
3232 Arguments : none
3233
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003234 By default, when a client communicates with a server, HAProxy will only
3235 analyze, log, and process the first request of each connection. Setting
3236 "option http-server-close" enables HTTP connection-close mode on the server
3237 side while keeping the ability to support HTTP keep-alive and pipelining on
3238 the client side. This provides the lowest latency on the client side (slow
3239 network) and the fastest session reuse on the server side to save server
3240 resources, similarly to "option forceclose". It also permits non-keepalive
3241 capable servers to be served in keep-alive mode to the clients if they
3242 conform to the requirements of RFC2616. Please note that some servers do not
3243 always conform to those requirements when they see "Connection: close" in the
3244 request. The effect will be that keep-alive will never be used. A workaround
3245 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003246
3247 At the moment, logs will not indicate whether requests came from the same
3248 session or not. The accept date reported in the logs corresponds to the end
3249 of the previous request, and the request time corresponds to the time spent
3250 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01003251 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3252 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01003253
3254 This option may be set both in a frontend and in a backend. It is enabled if
3255 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003256 It is worth noting that "option forceclose" has precedence over "option
3257 http-server-close" and that combining "http-server-close" with "httpclose"
3258 basically achieve the same result as "forceclose".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003259
3260 If this option has been enabled in a "defaults" section, it can be disabled
3261 in a specific instance by prepending the "no" keyword before it.
3262
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003263 See also : "option forceclose", "option http-pretend-keepalive",
3264 "option httpclose" and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003265
3266
Willy Tarreau88d349d2010-01-25 12:15:43 +01003267option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01003268no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01003269 Make use of non-standard Proxy-Connection header instead of Connection
3270 May be used in sections : defaults | frontend | listen | backend
3271 yes | yes | yes | no
3272 Arguments : none
3273
3274 While RFC2616 explicitly states that HTTP/1.1 agents must use the
3275 Connection header to indicate their wish of persistent or non-persistent
3276 connections, both browsers and proxies ignore this header for proxied
3277 connections and make use of the undocumented, non-standard Proxy-Connection
3278 header instead. The issue begins when trying to put a load balancer between
3279 browsers and such proxies, because there will be a difference between what
3280 haproxy understands and what the client and the proxy agree on.
3281
3282 By setting this option in a frontend, haproxy can automatically switch to use
3283 that non-standard header if it sees proxied requests. A proxied request is
3284 defined here as one where the URI begins with neither a '/' nor a '*'. The
3285 choice of header only affects requests passing through proxies making use of
3286 one of the "httpclose", "forceclose" and "http-server-close" options. Note
3287 that this option can only be specified in a frontend and will affect the
3288 request along its whole life.
3289
Willy Tarreau844a7e72010-01-31 21:46:18 +01003290 Also, when this option is set, a request which requires authentication will
3291 automatically switch to use proxy authentication headers if it is itself a
3292 proxied request. That makes it possible to check or enforce authentication in
3293 front of an existing proxy.
3294
Willy Tarreau88d349d2010-01-25 12:15:43 +01003295 This option should normally never be used, except in front of a proxy.
3296
3297 See also : "option httpclose", "option forceclose" and "option
3298 http-server-close".
3299
3300
Willy Tarreaud63335a2010-02-26 12:56:52 +01003301option httpchk
3302option httpchk <uri>
3303option httpchk <method> <uri>
3304option httpchk <method> <uri> <version>
3305 Enable HTTP protocol to check on the servers health
3306 May be used in sections : defaults | frontend | listen | backend
3307 yes | no | yes | yes
3308 Arguments :
3309 <method> is the optional HTTP method used with the requests. When not set,
3310 the "OPTIONS" method is used, as it generally requires low server
3311 processing and is easy to filter out from the logs. Any method
3312 may be used, though it is not recommended to invent non-standard
3313 ones.
3314
3315 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
3316 which is accessible by default on almost any server, but may be
3317 changed to any other URI. Query strings are permitted.
3318
3319 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
3320 but some servers might behave incorrectly in HTTP 1.0, so turning
3321 it to HTTP/1.1 may sometimes help. Note that the Host field is
3322 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
3323 after "\r\n" following the version string.
3324
3325 By default, server health checks only consist in trying to establish a TCP
3326 connection. When "option httpchk" is specified, a complete HTTP request is
3327 sent once the TCP connection is established, and responses 2xx and 3xx are
3328 considered valid, while all other ones indicate a server failure, including
3329 the lack of any response.
3330
3331 The port and interval are specified in the server configuration.
3332
3333 This option does not necessarily require an HTTP backend, it also works with
3334 plain TCP backends. This is particularly useful to check simple scripts bound
3335 to some dedicated ports using the inetd daemon.
3336
3337 Examples :
3338 # Relay HTTPS traffic to Apache instance and check service availability
3339 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
3340 backend https_relay
3341 mode tcp
3342 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
3343 server apache1 192.168.1.1:443 check port 80
3344
3345 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003346 "option pgsql-check", "http-check" and the "check", "port" and
3347 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01003348
3349
Willy Tarreauc27debf2008-01-06 08:57:02 +01003350option httpclose
3351no option httpclose
3352 Enable or disable passive HTTP connection closing
3353 May be used in sections : defaults | frontend | listen | backend
3354 yes | yes | yes | yes
3355 Arguments : none
3356
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003357 By default, when a client communicates with a server, HAProxy will only
3358 analyze, log, and process the first request of each connection. If "option
3359 httpclose" is set, it will check if a "Connection: close" header is already
3360 set in each direction, and will add one if missing. Each end should react to
3361 this by actively closing the TCP connection after each transfer, thus
3362 resulting in a switch to the HTTP close mode. Any "Connection" header
3363 different from "close" will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003364
3365 It seldom happens that some servers incorrectly ignore this header and do not
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003366 close the connection eventhough they reply "Connection: close". For this
3367 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
3368 it is possible to use the "option forceclose" which actively closes the
3369 request connection once the server responds. Option "forceclose" also
3370 releases the server connection earlier because it does not have to wait for
3371 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003372
3373 This option may be set both in a frontend and in a backend. It is enabled if
3374 at least one of the frontend or backend holding a connection has it enabled.
3375 If "option forceclose" is specified too, it has precedence over "httpclose".
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003376 If "option http-server-close" is enabled at the same time as "httpclose", it
3377 basically achieves the same result as "option forceclose".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003378
3379 If this option has been enabled in a "defaults" section, it can be disabled
3380 in a specific instance by prepending the "no" keyword before it.
3381
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003382 See also : "option forceclose", "option http-server-close" and
3383 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003384
3385
Emeric Brun3a058f32009-06-30 18:26:00 +02003386option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003387 Enable logging of HTTP request, session state and timers
3388 May be used in sections : defaults | frontend | listen | backend
3389 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02003390 Arguments :
3391 clf if the "clf" argument is added, then the output format will be
3392 the CLF format instead of HAProxy's default HTTP format. You can
3393 use this when you need to feed HAProxy's logs through a specific
3394 log analyser which only support the CLF format and which is not
3395 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003396
3397 By default, the log output format is very poor, as it only contains the
3398 source and destination addresses, and the instance name. By specifying
3399 "option httplog", each log line turns into a much richer format including,
3400 but not limited to, the HTTP request, the connection timers, the session
3401 status, the connections numbers, the captured headers and cookies, the
3402 frontend, backend and server name, and of course the source address and
3403 ports.
3404
3405 This option may be set either in the frontend or the backend.
3406
Emeric Brun3a058f32009-06-30 18:26:00 +02003407 If this option has been enabled in a "defaults" section, it can be disabled
3408 in a specific instance by prepending the "no" keyword before it. Specifying
3409 only "option httplog" will automatically clear the 'clf' mode if it was set
3410 by default.
3411
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003412 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003413
Willy Tarreau55165fe2009-05-10 12:02:55 +02003414
3415option http_proxy
3416no option http_proxy
3417 Enable or disable plain HTTP proxy mode
3418 May be used in sections : defaults | frontend | listen | backend
3419 yes | yes | yes | yes
3420 Arguments : none
3421
3422 It sometimes happens that people need a pure HTTP proxy which understands
3423 basic proxy requests without caching nor any fancy feature. In this case,
3424 it may be worth setting up an HAProxy instance with the "option http_proxy"
3425 set. In this mode, no server is declared, and the connection is forwarded to
3426 the IP address and port found in the URL after the "http://" scheme.
3427
3428 No host address resolution is performed, so this only works when pure IP
3429 addresses are passed. Since this option's usage perimeter is rather limited,
3430 it will probably be used only by experts who know they need exactly it. Last,
3431 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01003432 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02003433 be analyzed.
3434
3435 If this option has been enabled in a "defaults" section, it can be disabled
3436 in a specific instance by prepending the "no" keyword before it.
3437
3438 Example :
3439 # this backend understands HTTP proxy requests and forwards them directly.
3440 backend direct_forward
3441 option httpclose
3442 option http_proxy
3443
3444 See also : "option httpclose"
3445
Willy Tarreau211ad242009-10-03 21:45:07 +02003446
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003447option independant-streams
3448no option independant-streams
3449 Enable or disable independant timeout processing for both directions
3450 May be used in sections : defaults | frontend | listen | backend
3451 yes | yes | yes | yes
3452 Arguments : none
3453
3454 By default, when data is sent over a socket, both the write timeout and the
3455 read timeout for that socket are refreshed, because we consider that there is
3456 activity on that socket, and we have no other means of guessing if we should
3457 receive data or not.
3458
3459 While this default behaviour is desirable for almost all applications, there
3460 exists a situation where it is desirable to disable it, and only refresh the
3461 read timeout if there are incoming data. This happens on sessions with large
3462 timeouts and low amounts of exchanged data such as telnet session. If the
3463 server suddenly disappears, the output data accumulates in the system's
3464 socket buffers, both timeouts are correctly refreshed, and there is no way
3465 to know the server does not receive them, so we don't timeout. However, when
3466 the underlying protocol always echoes sent data, it would be enough by itself
3467 to detect the issue using the read timeout. Note that this problem does not
3468 happen with more verbose protocols because data won't accumulate long in the
3469 socket buffers.
3470
3471 When this option is set on the frontend, it will disable read timeout updates
3472 on data sent to the client. There probably is little use of this case. When
3473 the option is set on the backend, it will disable read timeout updates on
3474 data sent to the server. Doing so will typically break large HTTP posts from
3475 slow lines, so use it with caution.
3476
3477 See also : "timeout client" and "timeout server"
3478
3479
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003480option ldap-check
3481 Use LDAPv3 health checks for server testing
3482 May be used in sections : defaults | frontend | listen | backend
3483 yes | no | yes | yes
3484 Arguments : none
3485
3486 It is possible to test that the server correctly talks LDAPv3 instead of just
3487 testing that it accepts the TCP connection. When this option is set, an
3488 LDAPv3 anonymous simple bind message is sent to the server, and the response
3489 is analyzed to find an LDAPv3 bind response message.
3490
3491 The server is considered valid only when the LDAP response contains success
3492 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
3493
3494 Logging of bind requests is server dependent see your documentation how to
3495 configure it.
3496
3497 Example :
3498 option ldap-check
3499
3500 See also : "option httpchk"
3501
3502
Willy Tarreau211ad242009-10-03 21:45:07 +02003503option log-health-checks
3504no option log-health-checks
3505 Enable or disable logging of health checks
3506 May be used in sections : defaults | frontend | listen | backend
3507 yes | no | yes | yes
3508 Arguments : none
3509
3510 Enable health checks logging so it possible to check for example what
3511 was happening before a server crash. Failed health check are logged if
3512 server is UP and succeeded health checks if server is DOWN, so the amount
3513 of additional information is limited.
3514
3515 If health check logging is enabled no health check status is printed
3516 when servers is set up UP/DOWN/ENABLED/DISABLED.
3517
3518 See also: "log" and section 8 about logging.
3519
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003520
3521option log-separate-errors
3522no option log-separate-errors
3523 Change log level for non-completely successful connections
3524 May be used in sections : defaults | frontend | listen | backend
3525 yes | yes | yes | no
3526 Arguments : none
3527
3528 Sometimes looking for errors in logs is not easy. This option makes haproxy
3529 raise the level of logs containing potentially interesting information such
3530 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
3531 level changes from "info" to "err". This makes it possible to log them
3532 separately to a different file with most syslog daemons. Be careful not to
3533 remove them from the original file, otherwise you would lose ordering which
3534 provides very important information.
3535
3536 Using this option, large sites dealing with several thousand connections per
3537 second may log normal traffic to a rotating buffer and only archive smaller
3538 error logs.
3539
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003540 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003541 logging.
3542
Willy Tarreauc27debf2008-01-06 08:57:02 +01003543
3544option logasap
3545no option logasap
3546 Enable or disable early logging of HTTP requests
3547 May be used in sections : defaults | frontend | listen | backend
3548 yes | yes | yes | no
3549 Arguments : none
3550
3551 By default, HTTP requests are logged upon termination so that the total
3552 transfer time and the number of bytes appear in the logs. When large objects
3553 are being transferred, it may take a while before the request appears in the
3554 logs. Using "option logasap", the request gets logged as soon as the server
3555 sends the complete headers. The only missing information in the logs will be
3556 the total number of bytes which will indicate everything except the amount
3557 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003558 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01003559 "Content-Length" response header so that the logs at least indicate how many
3560 bytes are expected to be transferred.
3561
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003562 Examples :
3563 listen http_proxy 0.0.0.0:80
3564 mode http
3565 option httplog
3566 option logasap
3567 log 192.168.2.200 local3
3568
3569 >>> Feb 6 12:14:14 localhost \
3570 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
3571 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
3572 "GET /image.iso HTTP/1.0"
3573
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003574 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01003575 logging.
3576
3577
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003578option mysql-check [ user <username> ]
3579 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003580 May be used in sections : defaults | frontend | listen | backend
3581 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003582 Arguments :
3583 user <username> This is the username which will be used when connecting
3584 to MySQL server.
3585
3586 If you specify a username, the check consists of sending two MySQL packet,
3587 one Client Authentication packet, and one QUIT packet, to correctly close
3588 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
3589 Error packet. It is a basic but useful test which does not produce error nor
3590 aborted connect on the server. However, it requires adding an authorization
3591 in the MySQL table, like this :
3592
3593 USE mysql;
3594 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
3595 FLUSH PRIVILEGES;
3596
3597 If you don't specify a username (it is deprecated and not recommended), the
3598 check only consists in parsing the Mysql Handshake Initialisation packet or
3599 Error packet, we don't send anything in this mode. It was reported that it
3600 can generate lockout if check is too frequent and/or if there is not enough
3601 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
3602 value as if a connection is established successfully within fewer than MySQL
3603 "max_connect_errors" attempts after a previous connection was interrupted,
3604 the error count for the host is cleared to zero. If HAProxy's server get
3605 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
3606
3607 Remember that this does not check database presence nor database consistency.
3608 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003609
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02003610 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003611
3612 Most often, an incoming MySQL server needs to see the client's IP address for
3613 various purposes, including IP privilege matching and connection logging.
3614 When possible, it is often wise to masquerade the client's IP address when
3615 connecting to the server using the "usesrc" argument of the "source" keyword,
3616 which requires the cttproxy feature to be compiled in, and the MySQL server
3617 to route the client via the machine hosting haproxy.
3618
3619 See also: "option httpchk"
3620
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003621option pgsql-check [ user <username> ]
3622 Use PostgreSQL health checks for server testing
3623 May be used in sections : defaults | frontend | listen | backend
3624 yes | no | yes | yes
3625 Arguments :
3626 user <username> This is the username which will be used when connecting
3627 to PostgreSQL server.
3628
3629 The check sends a PostgreSQL StartupMessage and waits for either
3630 Authentication request or ErrorResponse message. It is a basic but useful
3631 test which does not produce error nor aborted connect on the server.
3632 This check is identical with the "mysql-check".
3633
3634 See also: "option httpchk"
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003635
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003636option nolinger
3637no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003638 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003639 May be used in sections: defaults | frontend | listen | backend
3640 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003641 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003642
3643 When clients or servers abort connections in a dirty way (eg: they are
3644 physically disconnected), the session timeouts triggers and the session is
3645 closed. But it will remain in FIN_WAIT1 state for some time in the system,
3646 using some resources and possibly limiting the ability to establish newer
3647 connections.
3648
3649 When this happens, it is possible to activate "option nolinger" which forces
3650 the system to immediately remove any socket's pending data on close. Thus,
3651 the session is instantly purged from the system's tables. This usually has
3652 side effects such as increased number of TCP resets due to old retransmits
3653 getting immediately rejected. Some firewalls may sometimes complain about
3654 this too.
3655
3656 For this reason, it is not recommended to use this option when not absolutely
3657 needed. You know that you need it when you have thousands of FIN_WAIT1
3658 sessions on your system (TIME_WAIT ones do not count).
3659
3660 This option may be used both on frontends and backends, depending on the side
3661 where it is required. Use it on the frontend for clients, and on the backend
3662 for servers.
3663
3664 If this option has been enabled in a "defaults" section, it can be disabled
3665 in a specific instance by prepending the "no" keyword before it.
3666
3667
Willy Tarreau55165fe2009-05-10 12:02:55 +02003668option originalto [ except <network> ] [ header <name> ]
3669 Enable insertion of the X-Original-To header to requests sent to servers
3670 May be used in sections : defaults | frontend | listen | backend
3671 yes | yes | yes | yes
3672 Arguments :
3673 <network> is an optional argument used to disable this option for sources
3674 matching <network>
3675 <name> an optional argument to specify a different "X-Original-To"
3676 header name.
3677
3678 Since HAProxy can work in transparent mode, every request from a client can
3679 be redirected to the proxy and HAProxy itself can proxy every request to a
3680 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
3681 be lost. This is annoying when you want access rules based on destination ip
3682 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
3683 added by HAProxy to all requests sent to the server. This header contains a
3684 value representing the original destination IP address. Since this must be
3685 configured to always use the last occurrence of this header only. Note that
3686 only the last occurrence of the header must be used, since it is really
3687 possible that the client has already brought one.
3688
3689 The keyword "header" may be used to supply a different header name to replace
3690 the default "X-Original-To". This can be useful where you might already
3691 have a "X-Original-To" header from a different application, and you need
3692 preserve it. Also if your backend server doesn't use the "X-Original-To"
3693 header and requires different one.
3694
3695 Sometimes, a same HAProxy instance may be shared between a direct client
3696 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3697 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3698 header for a known source address or network by adding the "except" keyword
3699 followed by the network address. In this case, any source IP matching the
3700 network will not cause an addition of this header. Most common uses are with
3701 private networks or 127.0.0.1.
3702
3703 This option may be specified either in the frontend or in the backend. If at
3704 least one of them uses it, the header will be added. Note that the backend's
3705 setting of the header subargument takes precedence over the frontend's if
3706 both are defined.
3707
Willy Tarreau87cf5142011-08-19 22:57:24 +02003708 It is important to note that by default, HAProxy works in tunnel mode and
3709 only inspects the first request of a connection, meaning that only the first
3710 request will have the header appended, which is certainly not what you want.
3711 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3712 "http-server-close" options is set when using this option.
Willy Tarreau55165fe2009-05-10 12:02:55 +02003713
3714 Examples :
3715 # Original Destination address
3716 frontend www
3717 mode http
3718 option originalto except 127.0.0.1
3719
3720 # Those servers want the IP Address in X-Client-Dst
3721 backend www
3722 mode http
3723 option originalto header X-Client-Dst
3724
Willy Tarreau87cf5142011-08-19 22:57:24 +02003725 See also : "option httpclose", "option http-server-close",
3726 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02003727
3728
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003729option persist
3730no option persist
3731 Enable or disable forced persistence on down servers
3732 May be used in sections: defaults | frontend | listen | backend
3733 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003734 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003735
3736 When an HTTP request reaches a backend with a cookie which references a dead
3737 server, by default it is redispatched to another server. It is possible to
3738 force the request to be sent to the dead server first using "option persist"
3739 if absolutely needed. A common use case is when servers are under extreme
3740 load and spend their time flapping. In this case, the users would still be
3741 directed to the server they opened the session on, in the hope they would be
3742 correctly served. It is recommended to use "option redispatch" in conjunction
3743 with this option so that in the event it would not be possible to connect to
3744 the server at all (server definitely dead), the client would finally be
3745 redirected to another valid server.
3746
3747 If this option has been enabled in a "defaults" section, it can be disabled
3748 in a specific instance by prepending the "no" keyword before it.
3749
Willy Tarreau4de91492010-01-22 19:10:05 +01003750 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003751
3752
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003753option redispatch
3754no option redispatch
3755 Enable or disable session redistribution in case of connection failure
3756 May be used in sections: defaults | frontend | listen | backend
3757 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003758 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003759
3760 In HTTP mode, if a server designated by a cookie is down, clients may
3761 definitely stick to it because they cannot flush the cookie, so they will not
3762 be able to access the service anymore.
3763
3764 Specifying "option redispatch" will allow the proxy to break their
3765 persistence and redistribute them to a working server.
3766
3767 It also allows to retry last connection to another server in case of multiple
3768 connection failures. Of course, it requires having "retries" set to a nonzero
3769 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01003770
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003771 This form is the preferred form, which replaces both the "redispatch" and
3772 "redisp" keywords.
3773
3774 If this option has been enabled in a "defaults" section, it can be disabled
3775 in a specific instance by prepending the "no" keyword before it.
3776
Willy Tarreau4de91492010-01-22 19:10:05 +01003777 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003778
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003779
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02003780option redis-check
3781 Use redis health checks for server testing
3782 May be used in sections : defaults | frontend | listen | backend
3783 yes | no | yes | yes
3784 Arguments : none
3785
3786 It is possible to test that the server correctly talks REDIS protocol instead
3787 of just testing that it accepts the TCP connection. When this option is set,
3788 a PING redis command is sent to the server, and the response is analyzed to
3789 find the "+PONG" response message.
3790
3791 Example :
3792 option redis-check
3793
3794 See also : "option httpchk"
3795
3796
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003797option smtpchk
3798option smtpchk <hello> <domain>
3799 Use SMTP health checks for server testing
3800 May be used in sections : defaults | frontend | listen | backend
3801 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01003802 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003803 <hello> is an optional argument. It is the "hello" command to use. It can
3804 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
3805 values will be turned into the default command ("HELO").
3806
3807 <domain> is the domain name to present to the server. It may only be
3808 specified (and is mandatory) if the hello command has been
3809 specified. By default, "localhost" is used.
3810
3811 When "option smtpchk" is set, the health checks will consist in TCP
3812 connections followed by an SMTP command. By default, this command is
3813 "HELO localhost". The server's return code is analyzed and only return codes
3814 starting with a "2" will be considered as valid. All other responses,
3815 including a lack of response will constitute an error and will indicate a
3816 dead server.
3817
3818 This test is meant to be used with SMTP servers or relays. Depending on the
3819 request, it is possible that some servers do not log each connection attempt,
3820 so you may want to experiment to improve the behaviour. Using telnet on port
3821 25 is often easier than adjusting the configuration.
3822
3823 Most often, an incoming SMTP server needs to see the client's IP address for
3824 various purposes, including spam filtering, anti-spoofing and logging. When
3825 possible, it is often wise to masquerade the client's IP address when
3826 connecting to the server using the "usesrc" argument of the "source" keyword,
3827 which requires the cttproxy feature to be compiled in.
3828
3829 Example :
3830 option smtpchk HELO mydomain.org
3831
3832 See also : "option httpchk", "source"
3833
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003834
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02003835option socket-stats
3836no option socket-stats
3837
3838 Enable or disable collecting & providing separate statistics for each socket.
3839 May be used in sections : defaults | frontend | listen | backend
3840 yes | yes | yes | no
3841
3842 Arguments : none
3843
3844
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003845option splice-auto
3846no option splice-auto
3847 Enable or disable automatic kernel acceleration on sockets in both directions
3848 May be used in sections : defaults | frontend | listen | backend
3849 yes | yes | yes | yes
3850 Arguments : none
3851
3852 When this option is enabled either on a frontend or on a backend, haproxy
3853 will automatically evaluate the opportunity to use kernel tcp splicing to
3854 forward data between the client and the server, in either direction. Haproxy
3855 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003856 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003857 are not much aggressive in order to limit excessive use of splicing. This
3858 option requires splicing to be enabled at compile time, and may be globally
3859 disabled with the global option "nosplice". Since splice uses pipes, using it
3860 requires that there are enough spare pipes.
3861
3862 Important note: kernel-based TCP splicing is a Linux-specific feature which
3863 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
3864 transfer data between sockets without copying these data to user-space, thus
3865 providing noticeable performance gains and CPU cycles savings. Since many
3866 early implementations are buggy, corrupt data and/or are inefficient, this
3867 feature is not enabled by default, and it should be used with extreme care.
3868 While it is not possible to detect the correctness of an implementation,
3869 2.6.29 is the first version offering a properly working implementation. In
3870 case of doubt, splicing may be globally disabled using the global "nosplice"
3871 keyword.
3872
3873 Example :
3874 option splice-auto
3875
3876 If this option has been enabled in a "defaults" section, it can be disabled
3877 in a specific instance by prepending the "no" keyword before it.
3878
3879 See also : "option splice-request", "option splice-response", and global
3880 options "nosplice" and "maxpipes"
3881
3882
3883option splice-request
3884no option splice-request
3885 Enable or disable automatic kernel acceleration on sockets for requests
3886 May be used in sections : defaults | frontend | listen | backend
3887 yes | yes | yes | yes
3888 Arguments : none
3889
3890 When this option is enabled either on a frontend or on a backend, haproxy
3891 will user kernel tcp splicing whenever possible to forward data going from
3892 the client to the server. It might still use the recv/send scheme if there
3893 are no spare pipes left. This option requires splicing to be enabled at
3894 compile time, and may be globally disabled with the global option "nosplice".
3895 Since splice uses pipes, using it requires that there are enough spare pipes.
3896
3897 Important note: see "option splice-auto" for usage limitations.
3898
3899 Example :
3900 option splice-request
3901
3902 If this option has been enabled in a "defaults" section, it can be disabled
3903 in a specific instance by prepending the "no" keyword before it.
3904
3905 See also : "option splice-auto", "option splice-response", and global options
3906 "nosplice" and "maxpipes"
3907
3908
3909option splice-response
3910no option splice-response
3911 Enable or disable automatic kernel acceleration on sockets for responses
3912 May be used in sections : defaults | frontend | listen | backend
3913 yes | yes | yes | yes
3914 Arguments : none
3915
3916 When this option is enabled either on a frontend or on a backend, haproxy
3917 will user kernel tcp splicing whenever possible to forward data going from
3918 the server to the client. It might still use the recv/send scheme if there
3919 are no spare pipes left. This option requires splicing to be enabled at
3920 compile time, and may be globally disabled with the global option "nosplice".
3921 Since splice uses pipes, using it requires that there are enough spare pipes.
3922
3923 Important note: see "option splice-auto" for usage limitations.
3924
3925 Example :
3926 option splice-response
3927
3928 If this option has been enabled in a "defaults" section, it can be disabled
3929 in a specific instance by prepending the "no" keyword before it.
3930
3931 See also : "option splice-auto", "option splice-request", and global options
3932 "nosplice" and "maxpipes"
3933
3934
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003935option srvtcpka
3936no option srvtcpka
3937 Enable or disable the sending of TCP keepalive packets on the server side
3938 May be used in sections : defaults | frontend | listen | backend
3939 yes | no | yes | yes
3940 Arguments : none
3941
3942 When there is a firewall or any session-aware component between a client and
3943 a server, and when the protocol involves very long sessions with long idle
3944 periods (eg: remote desktops), there is a risk that one of the intermediate
3945 components decides to expire a session which has remained idle for too long.
3946
3947 Enabling socket-level TCP keep-alives makes the system regularly send packets
3948 to the other end of the connection, leaving it active. The delay between
3949 keep-alive probes is controlled by the system only and depends both on the
3950 operating system and its tuning parameters.
3951
3952 It is important to understand that keep-alive packets are neither emitted nor
3953 received at the application level. It is only the network stacks which sees
3954 them. For this reason, even if one side of the proxy already uses keep-alives
3955 to maintain its connection alive, those keep-alive packets will not be
3956 forwarded to the other side of the proxy.
3957
3958 Please note that this has nothing to do with HTTP keep-alive.
3959
3960 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
3961 server side of a connection, which should help when session expirations are
3962 noticed between HAProxy and a server.
3963
3964 If this option has been enabled in a "defaults" section, it can be disabled
3965 in a specific instance by prepending the "no" keyword before it.
3966
3967 See also : "option clitcpka", "option tcpka"
3968
3969
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003970option ssl-hello-chk
3971 Use SSLv3 client hello health checks for server testing
3972 May be used in sections : defaults | frontend | listen | backend
3973 yes | no | yes | yes
3974 Arguments : none
3975
3976 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
3977 possible to test that the server correctly talks SSL instead of just testing
3978 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
3979 SSLv3 client hello messages are sent once the connection is established to
3980 the server, and the response is analyzed to find an SSL server hello message.
3981 The server is considered valid only when the response contains this server
3982 hello message.
3983
3984 All servers tested till there correctly reply to SSLv3 client hello messages,
3985 and most servers tested do not even log the requests containing only hello
3986 messages, which is appreciable.
3987
3988 See also: "option httpchk"
3989
3990
Willy Tarreau9ea05a72009-06-14 12:07:01 +02003991option tcp-smart-accept
3992no option tcp-smart-accept
3993 Enable or disable the saving of one ACK packet during the accept sequence
3994 May be used in sections : defaults | frontend | listen | backend
3995 yes | yes | yes | no
3996 Arguments : none
3997
3998 When an HTTP connection request comes in, the system acknowledges it on
3999 behalf of HAProxy, then the client immediately sends its request, and the
4000 system acknowledges it too while it is notifying HAProxy about the new
4001 connection. HAProxy then reads the request and responds. This means that we
4002 have one TCP ACK sent by the system for nothing, because the request could
4003 very well be acknowledged by HAProxy when it sends its response.
4004
4005 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
4006 sending this useless ACK on platforms which support it (currently at least
4007 Linux). It must not cause any problem, because the system will send it anyway
4008 after 40 ms if the response takes more time than expected to come.
4009
4010 During complex network debugging sessions, it may be desirable to disable
4011 this optimization because delayed ACKs can make troubleshooting more complex
4012 when trying to identify where packets are delayed. It is then possible to
4013 fall back to normal behaviour by specifying "no option tcp-smart-accept".
4014
4015 It is also possible to force it for non-HTTP proxies by simply specifying
4016 "option tcp-smart-accept". For instance, it can make sense with some services
4017 such as SMTP where the server speaks first.
4018
4019 It is recommended to avoid forcing this option in a defaults section. In case
4020 of doubt, consider setting it back to automatic values by prepending the
4021 "default" keyword before it, or disabling it using the "no" keyword.
4022
Willy Tarreaud88edf22009-06-14 15:48:17 +02004023 See also : "option tcp-smart-connect"
4024
4025
4026option tcp-smart-connect
4027no option tcp-smart-connect
4028 Enable or disable the saving of one ACK packet during the connect sequence
4029 May be used in sections : defaults | frontend | listen | backend
4030 yes | no | yes | yes
4031 Arguments : none
4032
4033 On certain systems (at least Linux), HAProxy can ask the kernel not to
4034 immediately send an empty ACK upon a connection request, but to directly
4035 send the buffer request instead. This saves one packet on the network and
4036 thus boosts performance. It can also be useful for some servers, because they
4037 immediately get the request along with the incoming connection.
4038
4039 This feature is enabled when "option tcp-smart-connect" is set in a backend.
4040 It is not enabled by default because it makes network troubleshooting more
4041 complex.
4042
4043 It only makes sense to enable it with protocols where the client speaks first
4044 such as HTTP. In other situations, if there is no data to send in place of
4045 the ACK, a normal ACK is sent.
4046
4047 If this option has been enabled in a "defaults" section, it can be disabled
4048 in a specific instance by prepending the "no" keyword before it.
4049
4050 See also : "option tcp-smart-accept"
4051
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004052
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004053option tcpka
4054 Enable or disable the sending of TCP keepalive packets on both sides
4055 May be used in sections : defaults | frontend | listen | backend
4056 yes | yes | yes | yes
4057 Arguments : none
4058
4059 When there is a firewall or any session-aware component between a client and
4060 a server, and when the protocol involves very long sessions with long idle
4061 periods (eg: remote desktops), there is a risk that one of the intermediate
4062 components decides to expire a session which has remained idle for too long.
4063
4064 Enabling socket-level TCP keep-alives makes the system regularly send packets
4065 to the other end of the connection, leaving it active. The delay between
4066 keep-alive probes is controlled by the system only and depends both on the
4067 operating system and its tuning parameters.
4068
4069 It is important to understand that keep-alive packets are neither emitted nor
4070 received at the application level. It is only the network stacks which sees
4071 them. For this reason, even if one side of the proxy already uses keep-alives
4072 to maintain its connection alive, those keep-alive packets will not be
4073 forwarded to the other side of the proxy.
4074
4075 Please note that this has nothing to do with HTTP keep-alive.
4076
4077 Using option "tcpka" enables the emission of TCP keep-alive probes on both
4078 the client and server sides of a connection. Note that this is meaningful
4079 only in "defaults" or "listen" sections. If this option is used in a
4080 frontend, only the client side will get keep-alives, and if this option is
4081 used in a backend, only the server side will get keep-alives. For this
4082 reason, it is strongly recommended to explicitly use "option clitcpka" and
4083 "option srvtcpka" when the configuration is split between frontends and
4084 backends.
4085
4086 See also : "option clitcpka", "option srvtcpka"
4087
Willy Tarreau844e3c52008-01-11 16:28:18 +01004088
4089option tcplog
4090 Enable advanced logging of TCP connections with session state and timers
4091 May be used in sections : defaults | frontend | listen | backend
4092 yes | yes | yes | yes
4093 Arguments : none
4094
4095 By default, the log output format is very poor, as it only contains the
4096 source and destination addresses, and the instance name. By specifying
4097 "option tcplog", each log line turns into a much richer format including, but
4098 not limited to, the connection timers, the session status, the connections
4099 numbers, the frontend, backend and server name, and of course the source
4100 address and ports. This option is useful for pure TCP proxies in order to
4101 find which of the client or server disconnects or times out. For normal HTTP
4102 proxies, it's better to use "option httplog" which is even more complete.
4103
4104 This option may be set either in the frontend or the backend.
4105
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004106 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004107
4108
Willy Tarreau844e3c52008-01-11 16:28:18 +01004109option transparent
4110no option transparent
4111 Enable client-side transparent proxying
4112 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004113 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004114 Arguments : none
4115
4116 This option was introduced in order to provide layer 7 persistence to layer 3
4117 load balancers. The idea is to use the OS's ability to redirect an incoming
4118 connection for a remote address to a local process (here HAProxy), and let
4119 this process know what address was initially requested. When this option is
4120 used, sessions without cookies will be forwarded to the original destination
4121 IP address of the incoming request (which should match that of another
4122 equipment), while requests with cookies will still be forwarded to the
4123 appropriate server.
4124
4125 Note that contrary to a common belief, this option does NOT make HAProxy
4126 present the client's IP to the server when establishing the connection.
4127
Willy Tarreaua1146052011-03-01 09:51:54 +01004128 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004129 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004130
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004131
Emeric Brun647caf12009-06-30 17:57:00 +02004132persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02004133persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02004134 Enable RDP cookie-based persistence
4135 May be used in sections : defaults | frontend | listen | backend
4136 yes | no | yes | yes
4137 Arguments :
4138 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02004139 default cookie name "msts" will be used. There currently is no
4140 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02004141
4142 This statement enables persistence based on an RDP cookie. The RDP cookie
4143 contains all information required to find the server in the list of known
4144 servers. So when this option is set in the backend, the request is analysed
4145 and if an RDP cookie is found, it is decoded. If it matches a known server
4146 which is still UP (or if "option persist" is set), then the connection is
4147 forwarded to this server.
4148
4149 Note that this only makes sense in a TCP backend, but for this to work, the
4150 frontend must have waited long enough to ensure that an RDP cookie is present
4151 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004152 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02004153 a single "listen" section.
4154
Willy Tarreau61e28f22010-05-16 22:31:05 +02004155 Also, it is important to understand that the terminal server will emit this
4156 RDP cookie only if it is configured for "token redirection mode", which means
4157 that the "IP address redirection" option is disabled.
4158
Emeric Brun647caf12009-06-30 17:57:00 +02004159 Example :
4160 listen tse-farm
4161 bind :3389
4162 # wait up to 5s for an RDP cookie in the request
4163 tcp-request inspect-delay 5s
4164 tcp-request content accept if RDP_COOKIE
4165 # apply RDP cookie persistence
4166 persist rdp-cookie
4167 # if server is unknown, let's balance on the same cookie.
4168 # alternatively, "balance leastconn" may be useful too.
4169 balance rdp-cookie
4170 server srv1 1.1.1.1:3389
4171 server srv2 1.1.1.2:3389
4172
Simon Hormanab814e02011-06-24 14:50:20 +09004173 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
4174 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02004175
4176
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004177rate-limit sessions <rate>
4178 Set a limit on the number of new sessions accepted per second on a frontend
4179 May be used in sections : defaults | frontend | listen | backend
4180 yes | yes | yes | no
4181 Arguments :
4182 <rate> The <rate> parameter is an integer designating the maximum number
4183 of new sessions per second to accept on the frontend.
4184
4185 When the frontend reaches the specified number of new sessions per second, it
4186 stops accepting new connections until the rate drops below the limit again.
4187 During this time, the pending sessions will be kept in the socket's backlog
4188 (in system buffers) and haproxy will not even be aware that sessions are
4189 pending. When applying very low limit on a highly loaded service, it may make
4190 sense to increase the socket's backlog using the "backlog" keyword.
4191
4192 This feature is particularly efficient at blocking connection-based attacks
4193 or service abuse on fragile servers. Since the session rate is measured every
4194 millisecond, it is extremely accurate. Also, the limit applies immediately,
4195 no delay is needed at all to detect the threshold.
4196
4197 Example : limit the connection rate on SMTP to 10 per second max
4198 listen smtp
4199 mode tcp
4200 bind :25
4201 rate-limit sessions 10
4202 server 127.0.0.1:1025
4203
Willy Tarreaua17c2d92011-07-25 08:16:20 +02004204 Note : when the maximum rate is reached, the frontend's status is not changed
4205 but its sockets appear as "WAITING" in the statistics if the
4206 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004207
4208 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
4209
4210
Willy Tarreauf285f542010-01-03 20:03:03 +01004211redirect location <to> [code <code>] <option> [{if | unless} <condition>]
4212redirect prefix <to> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004213 Return an HTTP redirection if/unless a condition is matched
4214 May be used in sections : defaults | frontend | listen | backend
4215 no | yes | yes | yes
4216
4217 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01004218 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004219
Willy Tarreau0140f252008-11-19 21:07:09 +01004220 Arguments :
4221 <to> With "redirect location", the exact value in <to> is placed into
4222 the HTTP "Location" header. In case of "redirect prefix", the
4223 "Location" header is built from the concatenation of <to> and the
4224 complete URI, including the query string, unless the "drop-query"
Willy Tarreaufe651a52008-11-19 21:15:17 +01004225 option is specified (see below). As a special case, if <to>
4226 equals exactly "/" in prefix mode, then nothing is inserted
4227 before the original URI. It allows one to redirect to the same
4228 URL.
Willy Tarreau0140f252008-11-19 21:07:09 +01004229
4230 <code> The code is optional. It indicates which type of HTTP redirection
4231 is desired. Only codes 301, 302 and 303 are supported, and 302 is
4232 used if no code is specified. 301 means "Moved permanently", and
4233 a browser may cache the Location. 302 means "Moved permanently"
4234 and means that the browser should not cache the redirection. 303
4235 is equivalent to 302 except that the browser will fetch the
4236 location with a GET method.
4237
4238 <option> There are several options which can be specified to adjust the
4239 expected behaviour of a redirection :
4240
4241 - "drop-query"
4242 When this keyword is used in a prefix-based redirection, then the
4243 location will be set without any possible query-string, which is useful
4244 for directing users to a non-secure page for instance. It has no effect
4245 with a location-type redirect.
4246
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004247 - "append-slash"
4248 This keyword may be used in conjunction with "drop-query" to redirect
4249 users who use a URL not ending with a '/' to the same one with the '/'.
4250 It can be useful to ensure that search engines will only see one URL.
4251 For this, a return code 301 is preferred.
4252
Willy Tarreau0140f252008-11-19 21:07:09 +01004253 - "set-cookie NAME[=value]"
4254 A "Set-Cookie" header will be added with NAME (and optionally "=value")
4255 to the response. This is sometimes used to indicate that a user has
4256 been seen, for instance to protect against some types of DoS. No other
4257 cookie option is added, so the cookie will be a session cookie. Note
4258 that for a browser, a sole cookie name without an equal sign is
4259 different from a cookie with an equal sign.
4260
4261 - "clear-cookie NAME[=]"
4262 A "Set-Cookie" header will be added with NAME (and optionally "="), but
4263 with the "Max-Age" attribute set to zero. This will tell the browser to
4264 delete this cookie. It is useful for instance on logout pages. It is
4265 important to note that clearing the cookie "NAME" will not remove a
4266 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
4267 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004268
4269 Example: move the login URL only to HTTPS.
4270 acl clear dst_port 80
4271 acl secure dst_port 8080
4272 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01004273 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01004274 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01004275 acl cookie_set hdr_sub(cookie) SEEN=1
4276
4277 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01004278 redirect prefix https://mysite.com if login_page !secure
4279 redirect prefix http://mysite.com drop-query if login_page !uid_given
4280 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01004281 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004282
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004283 Example: send redirects for request for articles without a '/'.
4284 acl missing_slash path_reg ^/article/[^/]*$
4285 redirect code 301 prefix / drop-query append-slash if missing_slash
4286
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004287 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004288
4289
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004290redisp (deprecated)
4291redispatch (deprecated)
4292 Enable or disable session redistribution in case of connection failure
4293 May be used in sections: defaults | frontend | listen | backend
4294 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004295 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004296
4297 In HTTP mode, if a server designated by a cookie is down, clients may
4298 definitely stick to it because they cannot flush the cookie, so they will not
4299 be able to access the service anymore.
4300
4301 Specifying "redispatch" will allow the proxy to break their persistence and
4302 redistribute them to a working server.
4303
4304 It also allows to retry last connection to another server in case of multiple
4305 connection failures. Of course, it requires having "retries" set to a nonzero
4306 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004307
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004308 This form is deprecated, do not use it in any new configuration, use the new
4309 "option redispatch" instead.
4310
4311 See also : "option redispatch"
4312
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004313
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004314reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004315 Add a header at the end of the HTTP request
4316 May be used in sections : defaults | frontend | listen | backend
4317 no | yes | yes | yes
4318 Arguments :
4319 <string> is the complete line to be added. Any space or known delimiter
4320 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004321 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004322
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004323 <cond> is an optional matching condition built from ACLs. It makes it
4324 possible to ignore this rule when other conditions are not met.
4325
Willy Tarreau303c0352008-01-17 19:01:39 +01004326 A new line consisting in <string> followed by a line feed will be added after
4327 the last header of an HTTP request.
4328
4329 Header transformations only apply to traffic which passes through HAProxy,
4330 and not to traffic generated by HAProxy, such as health-checks or error
4331 responses.
4332
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004333 Example : add "X-Proto: SSL" to requests coming via port 81
4334 acl is-ssl dst_port 81
4335 reqadd X-Proto:\ SSL if is-ssl
4336
4337 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
4338 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004339
4340
Willy Tarreau5321c422010-01-28 20:35:13 +01004341reqallow <search> [{if | unless} <cond>]
4342reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004343 Definitely allow an HTTP request if a line matches a regular expression
4344 May be used in sections : defaults | frontend | listen | backend
4345 no | yes | yes | yes
4346 Arguments :
4347 <search> is the regular expression applied to HTTP headers and to the
4348 request line. This is an extended regular expression. Parenthesis
4349 grouping is supported and no preliminary backslash is required.
4350 Any space or known delimiter must be escaped using a backslash
4351 ('\'). The pattern applies to a full line at a time. The
4352 "reqallow" keyword strictly matches case while "reqiallow"
4353 ignores case.
4354
Willy Tarreau5321c422010-01-28 20:35:13 +01004355 <cond> is an optional matching condition built from ACLs. It makes it
4356 possible to ignore this rule when other conditions are not met.
4357
Willy Tarreau303c0352008-01-17 19:01:39 +01004358 A request containing any line which matches extended regular expression
4359 <search> will mark the request as allowed, even if any later test would
4360 result in a deny. The test applies both to the request line and to request
4361 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004362 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004363
4364 It is easier, faster and more powerful to use ACLs to write access policies.
4365 Reqdeny, reqallow and reqpass should be avoided in new designs.
4366
4367 Example :
4368 # allow www.* but refuse *.local
4369 reqiallow ^Host:\ www\.
4370 reqideny ^Host:\ .*\.local
4371
Willy Tarreau5321c422010-01-28 20:35:13 +01004372 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
4373 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004374
4375
Willy Tarreau5321c422010-01-28 20:35:13 +01004376reqdel <search> [{if | unless} <cond>]
4377reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004378 Delete all headers matching a regular expression in an HTTP request
4379 May be used in sections : defaults | frontend | listen | backend
4380 no | yes | yes | yes
4381 Arguments :
4382 <search> is the regular expression applied to HTTP headers and to the
4383 request line. This is an extended regular expression. Parenthesis
4384 grouping is supported and no preliminary backslash is required.
4385 Any space or known delimiter must be escaped using a backslash
4386 ('\'). The pattern applies to a full line at a time. The "reqdel"
4387 keyword strictly matches case while "reqidel" ignores case.
4388
Willy Tarreau5321c422010-01-28 20:35:13 +01004389 <cond> is an optional matching condition built from ACLs. It makes it
4390 possible to ignore this rule when other conditions are not met.
4391
Willy Tarreau303c0352008-01-17 19:01:39 +01004392 Any header line matching extended regular expression <search> in the request
4393 will be completely deleted. Most common use of this is to remove unwanted
4394 and/or dangerous headers or cookies from a request before passing it to the
4395 next servers.
4396
4397 Header transformations only apply to traffic which passes through HAProxy,
4398 and not to traffic generated by HAProxy, such as health-checks or error
4399 responses. Keep in mind that header names are not case-sensitive.
4400
4401 Example :
4402 # remove X-Forwarded-For header and SERVER cookie
4403 reqidel ^X-Forwarded-For:.*
4404 reqidel ^Cookie:.*SERVER=
4405
Willy Tarreau5321c422010-01-28 20:35:13 +01004406 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
4407 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004408
4409
Willy Tarreau5321c422010-01-28 20:35:13 +01004410reqdeny <search> [{if | unless} <cond>]
4411reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004412 Deny an HTTP request if a line matches a regular expression
4413 May be used in sections : defaults | frontend | listen | backend
4414 no | yes | yes | yes
4415 Arguments :
4416 <search> is the regular expression applied to HTTP headers and to the
4417 request line. This is an extended regular expression. Parenthesis
4418 grouping is supported and no preliminary backslash is required.
4419 Any space or known delimiter must be escaped using a backslash
4420 ('\'). The pattern applies to a full line at a time. The
4421 "reqdeny" keyword strictly matches case while "reqideny" ignores
4422 case.
4423
Willy Tarreau5321c422010-01-28 20:35:13 +01004424 <cond> is an optional matching condition built from ACLs. It makes it
4425 possible to ignore this rule when other conditions are not met.
4426
Willy Tarreau303c0352008-01-17 19:01:39 +01004427 A request containing any line which matches extended regular expression
4428 <search> will mark the request as denied, even if any later test would
4429 result in an allow. The test applies both to the request line and to request
4430 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004431 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004432
Willy Tarreauced27012008-01-17 20:35:34 +01004433 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004434 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01004435 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01004436
Willy Tarreau303c0352008-01-17 19:01:39 +01004437 It is easier, faster and more powerful to use ACLs to write access policies.
4438 Reqdeny, reqallow and reqpass should be avoided in new designs.
4439
4440 Example :
4441 # refuse *.local, then allow www.*
4442 reqideny ^Host:\ .*\.local
4443 reqiallow ^Host:\ www\.
4444
Willy Tarreau5321c422010-01-28 20:35:13 +01004445 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
4446 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004447
4448
Willy Tarreau5321c422010-01-28 20:35:13 +01004449reqpass <search> [{if | unless} <cond>]
4450reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004451 Ignore any HTTP request line matching a regular expression in next rules
4452 May be used in sections : defaults | frontend | listen | backend
4453 no | yes | yes | yes
4454 Arguments :
4455 <search> is the regular expression applied to HTTP headers and to the
4456 request line. This is an extended regular expression. Parenthesis
4457 grouping is supported and no preliminary backslash is required.
4458 Any space or known delimiter must be escaped using a backslash
4459 ('\'). The pattern applies to a full line at a time. The
4460 "reqpass" keyword strictly matches case while "reqipass" ignores
4461 case.
4462
Willy Tarreau5321c422010-01-28 20:35:13 +01004463 <cond> is an optional matching condition built from ACLs. It makes it
4464 possible to ignore this rule when other conditions are not met.
4465
Willy Tarreau303c0352008-01-17 19:01:39 +01004466 A request containing any line which matches extended regular expression
4467 <search> will skip next rules, without assigning any deny or allow verdict.
4468 The test applies both to the request line and to request headers. Keep in
4469 mind that URLs in request line are case-sensitive while header names are not.
4470
4471 It is easier, faster and more powerful to use ACLs to write access policies.
4472 Reqdeny, reqallow and reqpass should be avoided in new designs.
4473
4474 Example :
4475 # refuse *.local, then allow www.*, but ignore "www.private.local"
4476 reqipass ^Host:\ www.private\.local
4477 reqideny ^Host:\ .*\.local
4478 reqiallow ^Host:\ www\.
4479
Willy Tarreau5321c422010-01-28 20:35:13 +01004480 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
4481 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004482
4483
Willy Tarreau5321c422010-01-28 20:35:13 +01004484reqrep <search> <string> [{if | unless} <cond>]
4485reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004486 Replace a regular expression with a string in an HTTP request line
4487 May be used in sections : defaults | frontend | listen | backend
4488 no | yes | yes | yes
4489 Arguments :
4490 <search> is the regular expression applied to HTTP headers and to the
4491 request line. This is an extended regular expression. Parenthesis
4492 grouping is supported and no preliminary backslash is required.
4493 Any space or known delimiter must be escaped using a backslash
4494 ('\'). The pattern applies to a full line at a time. The "reqrep"
4495 keyword strictly matches case while "reqirep" ignores case.
4496
4497 <string> is the complete line to be added. Any space or known delimiter
4498 must be escaped using a backslash ('\'). References to matched
4499 pattern groups are possible using the common \N form, with N
4500 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004501 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004502
Willy Tarreau5321c422010-01-28 20:35:13 +01004503 <cond> is an optional matching condition built from ACLs. It makes it
4504 possible to ignore this rule when other conditions are not met.
4505
Willy Tarreau303c0352008-01-17 19:01:39 +01004506 Any line matching extended regular expression <search> in the request (both
4507 the request line and header lines) will be completely replaced with <string>.
4508 Most common use of this is to rewrite URLs or domain names in "Host" headers.
4509
4510 Header transformations only apply to traffic which passes through HAProxy,
4511 and not to traffic generated by HAProxy, such as health-checks or error
4512 responses. Note that for increased readability, it is suggested to add enough
4513 spaces between the request and the response. Keep in mind that URLs in
4514 request line are case-sensitive while header names are not.
4515
4516 Example :
4517 # replace "/static/" with "/" at the beginning of any request path.
4518 reqrep ^([^\ ]*)\ /static/(.*) \1\ /\2
4519 # replace "www.mydomain.com" with "www" in the host name.
4520 reqirep ^Host:\ www.mydomain.com Host:\ www
4521
Willy Tarreau5321c422010-01-28 20:35:13 +01004522 See also: "reqadd", "reqdel", "rsprep", section 6 about HTTP header
4523 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004524
4525
Willy Tarreau5321c422010-01-28 20:35:13 +01004526reqtarpit <search> [{if | unless} <cond>]
4527reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004528 Tarpit an HTTP request containing a line matching a regular expression
4529 May be used in sections : defaults | frontend | listen | backend
4530 no | yes | yes | yes
4531 Arguments :
4532 <search> is the regular expression applied to HTTP headers and to the
4533 request line. This is an extended regular expression. Parenthesis
4534 grouping is supported and no preliminary backslash is required.
4535 Any space or known delimiter must be escaped using a backslash
4536 ('\'). The pattern applies to a full line at a time. The
4537 "reqtarpit" keyword strictly matches case while "reqitarpit"
4538 ignores case.
4539
Willy Tarreau5321c422010-01-28 20:35:13 +01004540 <cond> is an optional matching condition built from ACLs. It makes it
4541 possible to ignore this rule when other conditions are not met.
4542
Willy Tarreau303c0352008-01-17 19:01:39 +01004543 A request containing any line which matches extended regular expression
4544 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01004545 be kept open for a pre-defined time, then will return an HTTP error 500 so
4546 that the attacker does not suspect it has been tarpitted. The status 500 will
4547 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01004548 delay is defined by "timeout tarpit", or "timeout connect" if the former is
4549 not set.
4550
4551 The goal of the tarpit is to slow down robots attacking servers with
4552 identifiable requests. Many robots limit their outgoing number of connections
4553 and stay connected waiting for a reply which can take several minutes to
4554 come. Depending on the environment and attack, it may be particularly
4555 efficient at reducing the load on the network and firewalls.
4556
Willy Tarreau5321c422010-01-28 20:35:13 +01004557 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01004558 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
4559 # block all others.
4560 reqipass ^User-Agent:\.*(Mozilla|MSIE)
4561 reqitarpit ^User-Agent:
4562
Willy Tarreau5321c422010-01-28 20:35:13 +01004563 # block bad guys
4564 acl badguys src 10.1.0.3 172.16.13.20/28
4565 reqitarpit . if badguys
4566
4567 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
4568 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004569
4570
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02004571retries <value>
4572 Set the number of retries to perform on a server after a connection failure
4573 May be used in sections: defaults | frontend | listen | backend
4574 yes | no | yes | yes
4575 Arguments :
4576 <value> is the number of times a connection attempt should be retried on
4577 a server when a connection either is refused or times out. The
4578 default value is 3.
4579
4580 It is important to understand that this value applies to the number of
4581 connection attempts, not full requests. When a connection has effectively
4582 been established to a server, there will be no more retry.
4583
4584 In order to avoid immediate reconnections to a server which is restarting,
4585 a turn-around timer of 1 second is applied before a retry occurs.
4586
4587 When "option redispatch" is set, the last retry may be performed on another
4588 server even if a cookie references a different server.
4589
4590 See also : "option redispatch"
4591
4592
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004593rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004594 Add a header at the end of the HTTP response
4595 May be used in sections : defaults | frontend | listen | backend
4596 no | yes | yes | yes
4597 Arguments :
4598 <string> is the complete line to be added. Any space or known delimiter
4599 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004600 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004601
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004602 <cond> is an optional matching condition built from ACLs. It makes it
4603 possible to ignore this rule when other conditions are not met.
4604
Willy Tarreau303c0352008-01-17 19:01:39 +01004605 A new line consisting in <string> followed by a line feed will be added after
4606 the last header of an HTTP response.
4607
4608 Header transformations only apply to traffic which passes through HAProxy,
4609 and not to traffic generated by HAProxy, such as health-checks or error
4610 responses.
4611
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004612 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
4613 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004614
4615
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004616rspdel <search> [{if | unless} <cond>]
4617rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004618 Delete all headers matching a regular expression in an HTTP response
4619 May be used in sections : defaults | frontend | listen | backend
4620 no | yes | yes | yes
4621 Arguments :
4622 <search> is the regular expression applied to HTTP headers and to the
4623 response line. This is an extended regular expression, so
4624 parenthesis grouping is supported and no preliminary backslash
4625 is required. Any space or known delimiter must be escaped using
4626 a backslash ('\'). The pattern applies to a full line at a time.
4627 The "rspdel" keyword strictly matches case while "rspidel"
4628 ignores case.
4629
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004630 <cond> is an optional matching condition built from ACLs. It makes it
4631 possible to ignore this rule when other conditions are not met.
4632
Willy Tarreau303c0352008-01-17 19:01:39 +01004633 Any header line matching extended regular expression <search> in the response
4634 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02004635 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01004636 client.
4637
4638 Header transformations only apply to traffic which passes through HAProxy,
4639 and not to traffic generated by HAProxy, such as health-checks or error
4640 responses. Keep in mind that header names are not case-sensitive.
4641
4642 Example :
4643 # remove the Server header from responses
4644 reqidel ^Server:.*
4645
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004646 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
4647 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004648
4649
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004650rspdeny <search> [{if | unless} <cond>]
4651rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004652 Block an HTTP response if a line matches a regular expression
4653 May be used in sections : defaults | frontend | listen | backend
4654 no | yes | yes | yes
4655 Arguments :
4656 <search> is the regular expression applied to HTTP headers and to the
4657 response line. This is an extended regular expression, so
4658 parenthesis grouping is supported and no preliminary backslash
4659 is required. Any space or known delimiter must be escaped using
4660 a backslash ('\'). The pattern applies to a full line at a time.
4661 The "rspdeny" keyword strictly matches case while "rspideny"
4662 ignores case.
4663
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004664 <cond> is an optional matching condition built from ACLs. It makes it
4665 possible to ignore this rule when other conditions are not met.
4666
Willy Tarreau303c0352008-01-17 19:01:39 +01004667 A response containing any line which matches extended regular expression
4668 <search> will mark the request as denied. The test applies both to the
4669 response line and to response headers. Keep in mind that header names are not
4670 case-sensitive.
4671
4672 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01004673 block the response before it reaches the client. If a response is denied, it
4674 will be replaced with an HTTP 502 error so that the client never retrieves
4675 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01004676
4677 It is easier, faster and more powerful to use ACLs to write access policies.
4678 Rspdeny should be avoided in new designs.
4679
4680 Example :
4681 # Ensure that no content type matching ms-word will leak
4682 rspideny ^Content-type:\.*/ms-word
4683
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004684 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
4685 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004686
4687
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004688rsprep <search> <string> [{if | unless} <cond>]
4689rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004690 Replace a regular expression with a string in an HTTP response line
4691 May be used in sections : defaults | frontend | listen | backend
4692 no | yes | yes | yes
4693 Arguments :
4694 <search> is the regular expression applied to HTTP headers and to the
4695 response line. This is an extended regular expression, so
4696 parenthesis grouping is supported and no preliminary backslash
4697 is required. Any space or known delimiter must be escaped using
4698 a backslash ('\'). The pattern applies to a full line at a time.
4699 The "rsprep" keyword strictly matches case while "rspirep"
4700 ignores case.
4701
4702 <string> is the complete line to be added. Any space or known delimiter
4703 must be escaped using a backslash ('\'). References to matched
4704 pattern groups are possible using the common \N form, with N
4705 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004706 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004707
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004708 <cond> is an optional matching condition built from ACLs. It makes it
4709 possible to ignore this rule when other conditions are not met.
4710
Willy Tarreau303c0352008-01-17 19:01:39 +01004711 Any line matching extended regular expression <search> in the response (both
4712 the response line and header lines) will be completely replaced with
4713 <string>. Most common use of this is to rewrite Location headers.
4714
4715 Header transformations only apply to traffic which passes through HAProxy,
4716 and not to traffic generated by HAProxy, such as health-checks or error
4717 responses. Note that for increased readability, it is suggested to add enough
4718 spaces between the request and the response. Keep in mind that header names
4719 are not case-sensitive.
4720
4721 Example :
4722 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
4723 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
4724
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004725 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
4726 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004727
4728
David du Colombier486df472011-03-17 10:40:26 +01004729server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004730 Declare a server in a backend
4731 May be used in sections : defaults | frontend | listen | backend
4732 no | no | yes | yes
4733 Arguments :
4734 <name> is the internal name assigned to this server. This name will
4735 appear in logs and alerts.
4736
David du Colombier486df472011-03-17 10:40:26 +01004737 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
4738 resolvable hostname is supported, but this name will be resolved
4739 during start-up. Address "0.0.0.0" or "*" has a special meaning.
4740 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02004741 address as the one from the client connection. This is useful in
4742 transparent proxy architectures where the client's connection is
4743 intercepted and haproxy must forward to the original destination
4744 address. This is more or less what the "transparent" keyword does
4745 except that with a server it's possible to limit concurrency and
4746 to report statistics.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004747
4748 <ports> is an optional port specification. If set, all connections will
4749 be sent to this port. If unset, the same port the client
4750 connected to will be used. The port may also be prefixed by a "+"
4751 or a "-". In this case, the server's port will be determined by
4752 adding this value to the client's port.
4753
4754 <param*> is a list of parameters for this server. The "server" keywords
4755 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004756 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004757
4758 Examples :
4759 server first 10.1.1.1:1080 cookie first check inter 1000
4760 server second 10.1.1.2:1080 cookie second check inter 1000
4761
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004762 See also: "default-server" and section 5 about server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004763
4764
4765source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02004766source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004767source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004768 Set the source address for outgoing connections
4769 May be used in sections : defaults | frontend | listen | backend
4770 yes | no | yes | yes
4771 Arguments :
4772 <addr> is the IPv4 address HAProxy will bind to before connecting to a
4773 server. This address is also used as a source for health checks.
4774 The default value of 0.0.0.0 means that the system will select
4775 the most appropriate address to reach its destination.
4776
4777 <port> is an optional port. It is normally not needed but may be useful
4778 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004779 the system will select a free port. Note that port ranges are not
4780 supported in the backend. If you want to force port ranges, you
4781 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004782
4783 <addr2> is the IP address to present to the server when connections are
4784 forwarded in full transparent proxy mode. This is currently only
4785 supported on some patched Linux kernels. When this address is
4786 specified, clients connecting to the server will be presented
4787 with this address, while health checks will still use the address
4788 <addr>.
4789
4790 <port2> is the optional port to present to the server when connections
4791 are forwarded in full transparent proxy mode (see <addr2> above).
4792 The default value of zero means the system will select a free
4793 port.
4794
Willy Tarreaubce70882009-09-07 11:51:47 +02004795 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
4796 This is the name of a comma-separated header list which can
4797 contain multiple IP addresses. By default, the last occurrence is
4798 used. This is designed to work with the X-Forwarded-For header
4799 and to automatically bind to the the client's IP address as seen
4800 by previous proxy, typically Stunnel. In order to use another
4801 occurrence from the last one, please see the <occ> parameter
4802 below. When the header (or occurrence) is not found, no binding
4803 is performed so that the proxy's default IP address is used. Also
4804 keep in mind that the header name is case insensitive, as for any
4805 HTTP header.
4806
4807 <occ> is the occurrence number of a value to be used in a multi-value
4808 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
4809 in order to specificy which occurrence to use for the source IP
4810 address. Positive values indicate a position from the first
4811 occurrence, 1 being the first one. Negative values indicate
4812 positions relative to the last one, -1 being the last one. This
4813 is helpful for situations where an X-Forwarded-For header is set
4814 at the entry point of an infrastructure and must be used several
4815 proxy layers away. When this value is not specified, -1 is
4816 assumed. Passing a zero here disables the feature.
4817
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004818 <name> is an optional interface name to which to bind to for outgoing
4819 traffic. On systems supporting this features (currently, only
4820 Linux), this allows one to bind all traffic to the server to
4821 this interface even if it is not the one the system would select
4822 based on routing tables. This should be used with extreme care.
4823 Note that using this option requires root privileges.
4824
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004825 The "source" keyword is useful in complex environments where a specific
4826 address only is allowed to connect to the servers. It may be needed when a
4827 private address must be used through a public gateway for instance, and it is
4828 known that the system cannot determine the adequate source address by itself.
4829
4830 An extension which is available on certain patched Linux kernels may be used
4831 through the "usesrc" optional keyword. It makes it possible to connect to the
4832 servers with an IP address which does not belong to the system itself. This
4833 is called "full transparent proxy mode". For this to work, the destination
4834 servers have to route their traffic back to this address through the machine
4835 running HAProxy, and IP forwarding must generally be enabled on this machine.
4836
4837 In this "full transparent proxy" mode, it is possible to force a specific IP
4838 address to be presented to the servers. This is not much used in fact. A more
4839 common use is to tell HAProxy to present the client's IP address. For this,
4840 there are two methods :
4841
4842 - present the client's IP and port addresses. This is the most transparent
4843 mode, but it can cause problems when IP connection tracking is enabled on
4844 the machine, because a same connection may be seen twice with different
4845 states. However, this solution presents the huge advantage of not
4846 limiting the system to the 64k outgoing address+port couples, because all
4847 of the client ranges may be used.
4848
4849 - present only the client's IP address and select a spare port. This
4850 solution is still quite elegant but slightly less transparent (downstream
4851 firewalls logs will not match upstream's). It also presents the downside
4852 of limiting the number of concurrent connections to the usual 64k ports.
4853 However, since the upstream and downstream ports are different, local IP
4854 connection tracking on the machine will not be upset by the reuse of the
4855 same session.
4856
4857 Note that depending on the transparent proxy technology used, it may be
4858 required to force the source address. In fact, cttproxy version 2 requires an
4859 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
4860 IP address because it creates NAT entries which much match the exact outgoing
4861 address. Tproxy version 4 and some other kernel patches which work in pure
4862 forwarding mode generally will not have this limitation.
4863
4864 This option sets the default source for all servers in the backend. It may
4865 also be specified in a "defaults" section. Finer source address specification
4866 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004867 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004868
4869 Examples :
4870 backend private
4871 # Connect to the servers using our 192.168.1.200 source address
4872 source 192.168.1.200
4873
4874 backend transparent_ssl1
4875 # Connect to the SSL farm from the client's source address
4876 source 192.168.1.200 usesrc clientip
4877
4878 backend transparent_ssl2
4879 # Connect to the SSL farm from the client's source address and port
4880 # not recommended if IP conntrack is present on the local machine.
4881 source 192.168.1.200 usesrc client
4882
4883 backend transparent_ssl3
4884 # Connect to the SSL farm from the client's source address. It
4885 # is more conntrack-friendly.
4886 source 192.168.1.200 usesrc clientip
4887
4888 backend transparent_smtp
4889 # Connect to the SMTP farm from the client's source address/port
4890 # with Tproxy version 4.
4891 source 0.0.0.0 usesrc clientip
4892
Willy Tarreaubce70882009-09-07 11:51:47 +02004893 backend transparent_http
4894 # Connect to the servers using the client's IP as seen by previous
4895 # proxy.
4896 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
4897
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004898 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004899 the Linux kernel on www.balabit.com, the "bind" keyword.
4900
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004901
Willy Tarreau844e3c52008-01-11 16:28:18 +01004902srvtimeout <timeout> (deprecated)
4903 Set the maximum inactivity time on the server side.
4904 May be used in sections : defaults | frontend | listen | backend
4905 yes | no | yes | yes
4906 Arguments :
4907 <timeout> is the timeout value specified in milliseconds by default, but
4908 can be in any other unit if the number is suffixed by the unit,
4909 as explained at the top of this document.
4910
4911 The inactivity timeout applies when the server is expected to acknowledge or
4912 send data. In HTTP mode, this timeout is particularly important to consider
4913 during the first phase of the server's response, when it has to send the
4914 headers, as it directly represents the server's processing time for the
4915 request. To find out what value to put there, it's often good to start with
4916 what would be considered as unacceptable response times, then check the logs
4917 to observe the response time distribution, and adjust the value accordingly.
4918
4919 The value is specified in milliseconds by default, but can be in any other
4920 unit if the number is suffixed by the unit, as specified at the top of this
4921 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
4922 recommended that the client timeout remains equal to the server timeout in
4923 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004924 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01004925 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01004926 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01004927
4928 This parameter is specific to backends, but can be specified once for all in
4929 "defaults" sections. This is in fact one of the easiest solutions not to
4930 forget about it. An unspecified timeout results in an infinite timeout, which
4931 is not recommended. Such a usage is accepted and works but reports a warning
4932 during startup because it may results in accumulation of expired sessions in
4933 the system if the system's timeouts are not configured either.
4934
4935 This parameter is provided for compatibility but is currently deprecated.
4936 Please use "timeout server" instead.
4937
4938 See also : "timeout server", "timeout client" and "clitimeout".
4939
4940
Cyril Bonté66c327d2010-10-12 00:14:37 +02004941stats admin { if | unless } <cond>
4942 Enable statistics admin level if/unless a condition is matched
4943 May be used in sections : defaults | frontend | listen | backend
4944 no | no | yes | yes
4945
4946 This statement enables the statistics admin level if/unless a condition is
4947 matched.
4948
4949 The admin level allows to enable/disable servers from the web interface. By
4950 default, statistics page is read-only for security reasons.
4951
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01004952 Note : Consider not using this feature in multi-process mode (nbproc > 1)
4953 unless you know what you do : memory is not shared between the
4954 processes, which can result in random behaviours.
4955
Cyril Bonté23b39d92011-02-10 22:54:44 +01004956 Currently, the POST request is limited to the buffer size minus the reserved
4957 buffer space, which means that if the list of servers is too long, the
4958 request won't be processed. It is recommended to alter few servers at a
4959 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02004960
4961 Example :
4962 # statistics admin level only for localhost
4963 backend stats_localhost
4964 stats enable
4965 stats admin if LOCALHOST
4966
4967 Example :
4968 # statistics admin level always enabled because of the authentication
4969 backend stats_auth
4970 stats enable
4971 stats auth admin:AdMiN123
4972 stats admin if TRUE
4973
4974 Example :
4975 # statistics admin level depends on the authenticated user
4976 userlist stats-auth
4977 group admin users admin
4978 user admin insecure-password AdMiN123
4979 group readonly users haproxy
4980 user haproxy insecure-password haproxy
4981
4982 backend stats_auth
4983 stats enable
4984 acl AUTH http_auth(stats-auth)
4985 acl AUTH_ADMIN http_auth_group(stats-auth) admin
4986 stats http-request auth unless AUTH
4987 stats admin if AUTH_ADMIN
4988
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01004989 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
4990 "bind-process", section 3.4 about userlists and section 7 about
4991 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02004992
4993
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004994stats auth <user>:<passwd>
4995 Enable statistics with authentication and grant access to an account
4996 May be used in sections : defaults | frontend | listen | backend
4997 yes | no | yes | yes
4998 Arguments :
4999 <user> is a user name to grant access to
5000
5001 <passwd> is the cleartext password associated to this user
5002
5003 This statement enables statistics with default settings, and restricts access
5004 to declared users only. It may be repeated as many times as necessary to
5005 allow as many users as desired. When a user tries to access the statistics
5006 without a valid account, a "401 Forbidden" response will be returned so that
5007 the browser asks the user to provide a valid user and password. The real
5008 which will be returned to the browser is configurable using "stats realm".
5009
5010 Since the authentication method is HTTP Basic Authentication, the passwords
5011 circulate in cleartext on the network. Thus, it was decided that the
5012 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005013 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005014
5015 It is also possible to reduce the scope of the proxies which appear in the
5016 report using "stats scope".
5017
5018 Though this statement alone is enough to enable statistics reporting, it is
5019 recommended to set all other settings in order to avoid relying on default
5020 unobvious parameters.
5021
5022 Example :
5023 # public access (limited to this backend only)
5024 backend public_www
5025 server srv1 192.168.0.1:80
5026 stats enable
5027 stats hide-version
5028 stats scope .
5029 stats uri /admin?stats
5030 stats realm Haproxy\ Statistics
5031 stats auth admin1:AdMiN123
5032 stats auth admin2:AdMiN321
5033
5034 # internal monitoring access (unlimited)
5035 backend private_monitoring
5036 stats enable
5037 stats uri /admin?stats
5038 stats refresh 5s
5039
5040 See also : "stats enable", "stats realm", "stats scope", "stats uri"
5041
5042
5043stats enable
5044 Enable statistics reporting with default settings
5045 May be used in sections : defaults | frontend | listen | backend
5046 yes | no | yes | yes
5047 Arguments : none
5048
5049 This statement enables statistics reporting with default settings defined
5050 at build time. Unless stated otherwise, these settings are used :
5051 - stats uri : /haproxy?stats
5052 - stats realm : "HAProxy Statistics"
5053 - stats auth : no authentication
5054 - stats scope : no restriction
5055
5056 Though this statement alone is enough to enable statistics reporting, it is
5057 recommended to set all other settings in order to avoid relying on default
5058 unobvious parameters.
5059
5060 Example :
5061 # public access (limited to this backend only)
5062 backend public_www
5063 server srv1 192.168.0.1:80
5064 stats enable
5065 stats hide-version
5066 stats scope .
5067 stats uri /admin?stats
5068 stats realm Haproxy\ Statistics
5069 stats auth admin1:AdMiN123
5070 stats auth admin2:AdMiN321
5071
5072 # internal monitoring access (unlimited)
5073 backend private_monitoring
5074 stats enable
5075 stats uri /admin?stats
5076 stats refresh 5s
5077
5078 See also : "stats auth", "stats realm", "stats uri"
5079
5080
Willy Tarreaud63335a2010-02-26 12:56:52 +01005081stats hide-version
5082 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005083 May be used in sections : defaults | frontend | listen | backend
5084 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01005085 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005086
Willy Tarreaud63335a2010-02-26 12:56:52 +01005087 By default, the stats page reports some useful status information along with
5088 the statistics. Among them is HAProxy's version. However, it is generally
5089 considered dangerous to report precise version to anyone, as it can help them
5090 target known weaknesses with specific attacks. The "stats hide-version"
5091 statement removes the version from the statistics report. This is recommended
5092 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005093
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005094 Though this statement alone is enough to enable statistics reporting, it is
5095 recommended to set all other settings in order to avoid relying on default
5096 unobvious parameters.
5097
Willy Tarreaud63335a2010-02-26 12:56:52 +01005098 Example :
5099 # public access (limited to this backend only)
5100 backend public_www
5101 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005102 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005103 stats hide-version
5104 stats scope .
5105 stats uri /admin?stats
5106 stats realm Haproxy\ Statistics
5107 stats auth admin1:AdMiN123
5108 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005109
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005110 # internal monitoring access (unlimited)
5111 backend private_monitoring
5112 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005113 stats uri /admin?stats
5114 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01005115
Willy Tarreaud63335a2010-02-26 12:56:52 +01005116 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005117
Willy Tarreau983e01e2010-01-11 18:42:06 +01005118
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02005119stats http-request { allow | deny | auth [realm <realm>] }
5120 [ { if | unless } <condition> ]
5121 Access control for statistics
5122
5123 May be used in sections: defaults | frontend | listen | backend
5124 no | no | yes | yes
5125
5126 As "http-request", these set of options allow to fine control access to
5127 statistics. Each option may be followed by if/unless and acl.
5128 First option with matched condition (or option without condition) is final.
5129 For "deny" a 403 error will be returned, for "allow" normal processing is
5130 performed, for "auth" a 401/407 error code is returned so the client
5131 should be asked to enter a username and password.
5132
5133 There is no fixed limit to the number of http-request statements per
5134 instance.
5135
5136 See also : "http-request", section 3.4 about userlists and section 7
5137 about ACL usage.
5138
5139
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005140stats realm <realm>
5141 Enable statistics and set authentication realm
5142 May be used in sections : defaults | frontend | listen | backend
5143 yes | no | yes | yes
5144 Arguments :
5145 <realm> is the name of the HTTP Basic Authentication realm reported to
5146 the browser. The browser uses it to display it in the pop-up
5147 inviting the user to enter a valid username and password.
5148
5149 The realm is read as a single word, so any spaces in it should be escaped
5150 using a backslash ('\').
5151
5152 This statement is useful only in conjunction with "stats auth" since it is
5153 only related to authentication.
5154
5155 Though this statement alone is enough to enable statistics reporting, it is
5156 recommended to set all other settings in order to avoid relying on default
5157 unobvious parameters.
5158
5159 Example :
5160 # public access (limited to this backend only)
5161 backend public_www
5162 server srv1 192.168.0.1:80
5163 stats enable
5164 stats hide-version
5165 stats scope .
5166 stats uri /admin?stats
5167 stats realm Haproxy\ Statistics
5168 stats auth admin1:AdMiN123
5169 stats auth admin2:AdMiN321
5170
5171 # internal monitoring access (unlimited)
5172 backend private_monitoring
5173 stats enable
5174 stats uri /admin?stats
5175 stats refresh 5s
5176
5177 See also : "stats auth", "stats enable", "stats uri"
5178
5179
5180stats refresh <delay>
5181 Enable statistics with automatic refresh
5182 May be used in sections : defaults | frontend | listen | backend
5183 yes | no | yes | yes
5184 Arguments :
5185 <delay> is the suggested refresh delay, specified in seconds, which will
5186 be returned to the browser consulting the report page. While the
5187 browser is free to apply any delay, it will generally respect it
5188 and refresh the page this every seconds. The refresh interval may
5189 be specified in any other non-default time unit, by suffixing the
5190 unit after the value, as explained at the top of this document.
5191
5192 This statement is useful on monitoring displays with a permanent page
5193 reporting the load balancer's activity. When set, the HTML report page will
5194 include a link "refresh"/"stop refresh" so that the user can select whether
5195 he wants automatic refresh of the page or not.
5196
5197 Though this statement alone is enough to enable statistics reporting, it is
5198 recommended to set all other settings in order to avoid relying on default
5199 unobvious parameters.
5200
5201 Example :
5202 # public access (limited to this backend only)
5203 backend public_www
5204 server srv1 192.168.0.1:80
5205 stats enable
5206 stats hide-version
5207 stats scope .
5208 stats uri /admin?stats
5209 stats realm Haproxy\ Statistics
5210 stats auth admin1:AdMiN123
5211 stats auth admin2:AdMiN321
5212
5213 # internal monitoring access (unlimited)
5214 backend private_monitoring
5215 stats enable
5216 stats uri /admin?stats
5217 stats refresh 5s
5218
5219 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5220
5221
5222stats scope { <name> | "." }
5223 Enable statistics and limit access scope
5224 May be used in sections : defaults | frontend | listen | backend
5225 yes | no | yes | yes
5226 Arguments :
5227 <name> is the name of a listen, frontend or backend section to be
5228 reported. The special name "." (a single dot) designates the
5229 section in which the statement appears.
5230
5231 When this statement is specified, only the sections enumerated with this
5232 statement will appear in the report. All other ones will be hidden. This
5233 statement may appear as many times as needed if multiple sections need to be
5234 reported. Please note that the name checking is performed as simple string
5235 comparisons, and that it is never checked that a give section name really
5236 exists.
5237
5238 Though this statement alone is enough to enable statistics reporting, it is
5239 recommended to set all other settings in order to avoid relying on default
5240 unobvious parameters.
5241
5242 Example :
5243 # public access (limited to this backend only)
5244 backend public_www
5245 server srv1 192.168.0.1:80
5246 stats enable
5247 stats hide-version
5248 stats scope .
5249 stats uri /admin?stats
5250 stats realm Haproxy\ Statistics
5251 stats auth admin1:AdMiN123
5252 stats auth admin2:AdMiN321
5253
5254 # internal monitoring access (unlimited)
5255 backend private_monitoring
5256 stats enable
5257 stats uri /admin?stats
5258 stats refresh 5s
5259
5260 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5261
Willy Tarreaud63335a2010-02-26 12:56:52 +01005262
Willy Tarreauc9705a12010-07-27 20:05:50 +02005263stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01005264 Enable reporting of a description on the statistics page.
5265 May be used in sections : defaults | frontend | listen | backend
5266 yes | no | yes | yes
5267
Willy Tarreauc9705a12010-07-27 20:05:50 +02005268 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01005269 description from global section is automatically used instead.
5270
5271 This statement is useful for users that offer shared services to their
5272 customers, where node or description should be different for each customer.
5273
5274 Though this statement alone is enough to enable statistics reporting, it is
5275 recommended to set all other settings in order to avoid relying on default
5276 unobvious parameters.
5277
5278 Example :
5279 # internal monitoring access (unlimited)
5280 backend private_monitoring
5281 stats enable
5282 stats show-desc Master node for Europe, Asia, Africa
5283 stats uri /admin?stats
5284 stats refresh 5s
5285
5286 See also: "show-node", "stats enable", "stats uri" and "description" in
5287 global section.
5288
5289
5290stats show-legends
5291 Enable reporting additional informations on the statistics page :
5292 - cap: capabilities (proxy)
5293 - mode: one of tcp, http or health (proxy)
5294 - id: SNMP ID (proxy, socket, server)
5295 - IP (socket, server)
5296 - cookie (backend, server)
5297
5298 Though this statement alone is enough to enable statistics reporting, it is
5299 recommended to set all other settings in order to avoid relying on default
5300 unobvious parameters.
5301
5302 See also: "stats enable", "stats uri".
5303
5304
5305stats show-node [ <name> ]
5306 Enable reporting of a host name on the statistics page.
5307 May be used in sections : defaults | frontend | listen | backend
5308 yes | no | yes | yes
5309 Arguments:
5310 <name> is an optional name to be reported. If unspecified, the
5311 node name from global section is automatically used instead.
5312
5313 This statement is useful for users that offer shared services to their
5314 customers, where node or description might be different on a stats page
5315 provided for each customer.
5316
5317 Though this statement alone is enough to enable statistics reporting, it is
5318 recommended to set all other settings in order to avoid relying on default
5319 unobvious parameters.
5320
5321 Example:
5322 # internal monitoring access (unlimited)
5323 backend private_monitoring
5324 stats enable
5325 stats show-node Europe-1
5326 stats uri /admin?stats
5327 stats refresh 5s
5328
5329 See also: "show-desc", "stats enable", "stats uri", and "node" in global
5330 section.
5331
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005332
5333stats uri <prefix>
5334 Enable statistics and define the URI prefix to access them
5335 May be used in sections : defaults | frontend | listen | backend
5336 yes | no | yes | yes
5337 Arguments :
5338 <prefix> is the prefix of any URI which will be redirected to stats. This
5339 prefix may contain a question mark ('?') to indicate part of a
5340 query string.
5341
5342 The statistics URI is intercepted on the relayed traffic, so it appears as a
5343 page within the normal application. It is strongly advised to ensure that the
5344 selected URI will never appear in the application, otherwise it will never be
5345 possible to reach it in the application.
5346
5347 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005348 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005349 It is generally a good idea to include a question mark in the URI so that
5350 intermediate proxies refrain from caching the results. Also, since any string
5351 beginning with the prefix will be accepted as a stats request, the question
5352 mark helps ensuring that no valid URI will begin with the same words.
5353
5354 It is sometimes very convenient to use "/" as the URI prefix, and put that
5355 statement in a "listen" instance of its own. That makes it easy to dedicate
5356 an address or a port to statistics only.
5357
5358 Though this statement alone is enough to enable statistics reporting, it is
5359 recommended to set all other settings in order to avoid relying on default
5360 unobvious parameters.
5361
5362 Example :
5363 # public access (limited to this backend only)
5364 backend public_www
5365 server srv1 192.168.0.1:80
5366 stats enable
5367 stats hide-version
5368 stats scope .
5369 stats uri /admin?stats
5370 stats realm Haproxy\ Statistics
5371 stats auth admin1:AdMiN123
5372 stats auth admin2:AdMiN321
5373
5374 # internal monitoring access (unlimited)
5375 backend private_monitoring
5376 stats enable
5377 stats uri /admin?stats
5378 stats refresh 5s
5379
5380 See also : "stats auth", "stats enable", "stats realm"
5381
5382
Willy Tarreaud63335a2010-02-26 12:56:52 +01005383stick match <pattern> [table <table>] [{if | unless} <cond>]
5384 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005385 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01005386 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005387
5388 Arguments :
5389 <pattern> is a pattern extraction rule as described in section 7.8. It
5390 describes what elements of the incoming request or connection
5391 will be analysed in the hope to find a matching entry in a
5392 stickiness table. This rule is mandatory.
5393
5394 <table> is an optional stickiness table name. If unspecified, the same
5395 backend's table is used. A stickiness table is declared using
5396 the "stick-table" statement.
5397
5398 <cond> is an optional matching condition. It makes it possible to match
5399 on a certain criterion only when other conditions are met (or
5400 not met). For instance, it could be used to match on a source IP
5401 address except when a request passes through a known proxy, in
5402 which case we'd match on a header containing that IP address.
5403
5404 Some protocols or applications require complex stickiness rules and cannot
5405 always simply rely on cookies nor hashing. The "stick match" statement
5406 describes a rule to extract the stickiness criterion from an incoming request
5407 or connection. See section 7 for a complete list of possible patterns and
5408 transformation rules.
5409
5410 The table has to be declared using the "stick-table" statement. It must be of
5411 a type compatible with the pattern. By default it is the one which is present
5412 in the same backend. It is possible to share a table with other backends by
5413 referencing it using the "table" keyword. If another table is referenced,
5414 the server's ID inside the backends are used. By default, all server IDs
5415 start at 1 in each backend, so the server ordering is enough. But in case of
5416 doubt, it is highly recommended to force server IDs using their "id" setting.
5417
5418 It is possible to restrict the conditions where a "stick match" statement
5419 will apply, using "if" or "unless" followed by a condition. See section 7 for
5420 ACL based conditions.
5421
5422 There is no limit on the number of "stick match" statements. The first that
5423 applies and matches will cause the request to be directed to the same server
5424 as was used for the request which created the entry. That way, multiple
5425 matches can be used as fallbacks.
5426
5427 The stick rules are checked after the persistence cookies, so they will not
5428 affect stickiness if a cookie has already been used to select a server. That
5429 way, it becomes very easy to insert cookies and match on IP addresses in
5430 order to maintain stickiness between HTTP and HTTPS.
5431
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005432 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5433 unless you know what you do : memory is not shared between the
5434 processes, which can result in random behaviours.
5435
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005436 Example :
5437 # forward SMTP users to the same server they just used for POP in the
5438 # last 30 minutes
5439 backend pop
5440 mode tcp
5441 balance roundrobin
5442 stick store-request src
5443 stick-table type ip size 200k expire 30m
5444 server s1 192.168.1.1:110
5445 server s2 192.168.1.1:110
5446
5447 backend smtp
5448 mode tcp
5449 balance roundrobin
5450 stick match src table pop
5451 server s1 192.168.1.1:25
5452 server s2 192.168.1.1:25
5453
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005454 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5455 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005456
5457
5458stick on <pattern> [table <table>] [{if | unless} <condition>]
5459 Define a request pattern to associate a user to a server
5460 May be used in sections : defaults | frontend | listen | backend
5461 no | no | yes | yes
5462
5463 Note : This form is exactly equivalent to "stick match" followed by
5464 "stick store-request", all with the same arguments. Please refer
5465 to both keywords for details. It is only provided as a convenience
5466 for writing more maintainable configurations.
5467
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005468 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5469 unless you know what you do : memory is not shared between the
5470 processes, which can result in random behaviours.
5471
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005472 Examples :
5473 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01005474 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005475
5476 # ...is strictly equivalent to this one :
5477 stick match src table pop if !localhost
5478 stick store-request src table pop if !localhost
5479
5480
5481 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
5482 # well as HTTP without cookie. Share the same table between both accesses.
5483 backend http
5484 mode http
5485 balance roundrobin
5486 stick on src table https
5487 cookie SRV insert indirect nocache
5488 server s1 192.168.1.1:80 cookie s1
5489 server s2 192.168.1.1:80 cookie s2
5490
5491 backend https
5492 mode tcp
5493 balance roundrobin
5494 stick-table type ip size 200k expire 30m
5495 stick on src
5496 server s1 192.168.1.1:443
5497 server s2 192.168.1.1:443
5498
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005499 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005500
5501
5502stick store-request <pattern> [table <table>] [{if | unless} <condition>]
5503 Define a request pattern used to create an entry in a stickiness table
5504 May be used in sections : defaults | frontend | listen | backend
5505 no | no | yes | yes
5506
5507 Arguments :
5508 <pattern> is a pattern extraction rule as described in section 7.8. It
5509 describes what elements of the incoming request or connection
5510 will be analysed, extracted and stored in the table once a
5511 server is selected.
5512
5513 <table> is an optional stickiness table name. If unspecified, the same
5514 backend's table is used. A stickiness table is declared using
5515 the "stick-table" statement.
5516
5517 <cond> is an optional storage condition. It makes it possible to store
5518 certain criteria only when some conditions are met (or not met).
5519 For instance, it could be used to store the source IP address
5520 except when the request passes through a known proxy, in which
5521 case we'd store a converted form of a header containing that IP
5522 address.
5523
5524 Some protocols or applications require complex stickiness rules and cannot
5525 always simply rely on cookies nor hashing. The "stick store-request" statement
5526 describes a rule to decide what to extract from the request and when to do
5527 it, in order to store it into a stickiness table for further requests to
5528 match it using the "stick match" statement. Obviously the extracted part must
5529 make sense and have a chance to be matched in a further request. Storing a
5530 client's IP address for instance often makes sense. Storing an ID found in a
5531 URL parameter also makes sense. Storing a source port will almost never make
5532 any sense because it will be randomly matched. See section 7 for a complete
5533 list of possible patterns and transformation rules.
5534
5535 The table has to be declared using the "stick-table" statement. It must be of
5536 a type compatible with the pattern. By default it is the one which is present
5537 in the same backend. It is possible to share a table with other backends by
5538 referencing it using the "table" keyword. If another table is referenced,
5539 the server's ID inside the backends are used. By default, all server IDs
5540 start at 1 in each backend, so the server ordering is enough. But in case of
5541 doubt, it is highly recommended to force server IDs using their "id" setting.
5542
5543 It is possible to restrict the conditions where a "stick store-request"
5544 statement will apply, using "if" or "unless" followed by a condition. This
5545 condition will be evaluated while parsing the request, so any criteria can be
5546 used. See section 7 for ACL based conditions.
5547
5548 There is no limit on the number of "stick store-request" statements, but
5549 there is a limit of 8 simultaneous stores per request or response. This
5550 makes it possible to store up to 8 criteria, all extracted from either the
5551 request or the response, regardless of the number of rules. Only the 8 first
5552 ones which match will be kept. Using this, it is possible to feed multiple
5553 tables at once in the hope to increase the chance to recognize a user on
5554 another protocol or access method.
5555
5556 The "store-request" rules are evaluated once the server connection has been
5557 established, so that the table will contain the real server that processed
5558 the request.
5559
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005560 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5561 unless you know what you do : memory is not shared between the
5562 processes, which can result in random behaviours.
5563
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005564 Example :
5565 # forward SMTP users to the same server they just used for POP in the
5566 # last 30 minutes
5567 backend pop
5568 mode tcp
5569 balance roundrobin
5570 stick store-request src
5571 stick-table type ip size 200k expire 30m
5572 server s1 192.168.1.1:110
5573 server s2 192.168.1.1:110
5574
5575 backend smtp
5576 mode tcp
5577 balance roundrobin
5578 stick match src table pop
5579 server s1 192.168.1.1:25
5580 server s2 192.168.1.1:25
5581
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005582 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5583 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005584
5585
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005586stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02005587 size <size> [expire <expire>] [nopurge] [peers <peersect>]
5588 [store <data_type>]*
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005589 Configure the stickiness table for the current backend
5590 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005591 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005592
5593 Arguments :
5594 ip a table declared with "type ip" will only store IPv4 addresses.
5595 This form is very compact (about 50 bytes per entry) and allows
5596 very fast entry lookup and stores with almost no overhead. This
5597 is mainly used to store client source IP addresses.
5598
David du Colombier9a6d3c92011-03-17 10:40:24 +01005599 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
5600 This form is very compact (about 60 bytes per entry) and allows
5601 very fast entry lookup and stores with almost no overhead. This
5602 is mainly used to store client source IP addresses.
5603
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005604 integer a table declared with "type integer" will store 32bit integers
5605 which can represent a client identifier found in a request for
5606 instance.
5607
5608 string a table declared with "type string" will store substrings of up
5609 to <len> characters. If the string provided by the pattern
5610 extractor is larger than <len>, it will be truncated before
5611 being stored. During matching, at most <len> characters will be
5612 compared between the string in the table and the extracted
5613 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005614 to 32 characters.
5615
5616 binary a table declared with "type binary" will store binary blocks
5617 of <len> bytes. If the block provided by the pattern
5618 extractor is larger than <len>, it will be truncated before
5619 being stored. If the block provided by the pattern extractor
5620 is shorter than <len>, it will be padded by 0. When not
5621 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005622
5623 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005624 "string" type table (See type "string" above). Or the number
5625 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005626 changing this parameter as memory usage will proportionally
5627 increase.
5628
5629 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01005630 value directly impacts memory usage. Count approximately
5631 50 bytes per entry, plus the size of a string if any. The size
5632 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005633
5634 [nopurge] indicates that we refuse to purge older entries when the table
5635 is full. When not specified and the table is full when haproxy
5636 wants to store an entry in it, it will flush a few of the oldest
5637 entries in order to release some space for the new ones. This is
5638 most often the desired behaviour. In some specific cases, it
5639 be desirable to refuse new entries instead of purging the older
5640 ones. That may be the case when the amount of data to store is
5641 far above the hardware limits and we prefer not to offer access
5642 to new clients than to reject the ones already connected. When
5643 using this parameter, be sure to properly set the "expire"
5644 parameter (see below).
5645
Emeric Brunf099e792010-09-27 12:05:28 +02005646 <peersect> is the name of the peers section to use for replication. Entries
5647 which associate keys to server IDs are kept synchronized with
5648 the remote peers declared in this section. All entries are also
5649 automatically learned from the local peer (old process) during a
5650 soft restart.
5651
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005652 NOTE : peers can't be used in multi-process mode.
5653
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005654 <expire> defines the maximum duration of an entry in the table since it
5655 was last created, refreshed or matched. The expiration delay is
5656 defined using the standard time format, similarly as the various
5657 timeouts. The maximum duration is slightly above 24 days. See
5658 section 2.2 for more information. If this delay is not specified,
5659 the session won't automatically expire, but older entries will
5660 be removed once full. Be sure not to use the "nopurge" parameter
5661 if not expiration delay is specified.
5662
Willy Tarreau08d5f982010-06-06 13:34:54 +02005663 <data_type> is used to store additional information in the stick-table. This
5664 may be used by ACLs in order to control various criteria related
5665 to the activity of the client matching the stick-table. For each
5666 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02005667 that the additional data can fit. Several data types may be
5668 stored with an entry. Multiple data types may be specified after
5669 the "store" keyword, as a comma-separated list. Alternatively,
5670 it is possible to repeat the "store" keyword followed by one or
5671 several data types. Except for the "server_id" type which is
5672 automatically detected and enabled, all data types must be
5673 explicitly declared to be stored. If an ACL references a data
5674 type which is not stored, the ACL will simply not match. Some
5675 data types require an argument which must be passed just after
5676 the type between parenthesis. See below for the supported data
5677 types and their arguments.
5678
5679 The data types that can be stored with an entry are the following :
5680 - server_id : this is an integer which holds the numeric ID of the server a
5681 request was assigned to. It is used by the "stick match", "stick store",
5682 and "stick on" rules. It is automatically enabled when referenced.
5683
5684 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
5685 integer which may be used for anything. Most of the time it will be used
5686 to put a special tag on some entries, for instance to note that a
5687 specific behaviour was detected and must be known for future matches.
5688
5689 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
5690 the absolute number of connections received from clients which matched
5691 this entry. It does not mean the connections were accepted, just that
5692 they were received.
5693
5694 - conn_cur : Current Connections. It is a positive 32-bit integer which
5695 stores the concurrent connection counts for the entry. It is incremented
5696 once an incoming connection matches the entry, and decremented once the
5697 connection leaves. That way it is possible to know at any time the exact
5698 number of concurrent connections for an entry.
5699
5700 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5701 integer parameter <period> which indicates in milliseconds the length
5702 of the period over which the average is measured. It reports the average
5703 incoming connection rate over that period, in connections per period. The
5704 result is an integer which can be matched using ACLs.
5705
5706 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
5707 the absolute number of sessions received from clients which matched this
5708 entry. A session is a connection that was accepted by the layer 4 rules.
5709
5710 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5711 integer parameter <period> which indicates in milliseconds the length
5712 of the period over which the average is measured. It reports the average
5713 incoming session rate over that period, in sessions per period. The
5714 result is an integer which can be matched using ACLs.
5715
5716 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
5717 counts the absolute number of HTTP requests received from clients which
5718 matched this entry. It does not matter whether they are valid requests or
5719 not. Note that this is different from sessions when keep-alive is used on
5720 the client side.
5721
5722 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5723 integer parameter <period> which indicates in milliseconds the length
5724 of the period over which the average is measured. It reports the average
5725 HTTP request rate over that period, in requests per period. The result is
5726 an integer which can be matched using ACLs. It does not matter whether
5727 they are valid requests or not. Note that this is different from sessions
5728 when keep-alive is used on the client side.
5729
5730 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
5731 counts the absolute number of HTTP requests errors induced by clients
5732 which matched this entry. Errors are counted on invalid and truncated
5733 requests, as well as on denied or tarpitted requests, and on failed
5734 authentications. If the server responds with 4xx, then the request is
5735 also counted as an error since it's an error triggered by the client
5736 (eg: vulnerability scan).
5737
5738 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5739 integer parameter <period> which indicates in milliseconds the length
5740 of the period over which the average is measured. It reports the average
5741 HTTP request error rate over that period, in requests per period (see
5742 http_err_cnt above for what is accounted as an error). The result is an
5743 integer which can be matched using ACLs.
5744
5745 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
5746 integer which counts the cumulated amount of bytes received from clients
5747 which matched this entry. Headers are included in the count. This may be
5748 used to limit abuse of upload features on photo or video servers.
5749
5750 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5751 integer parameter <period> which indicates in milliseconds the length
5752 of the period over which the average is measured. It reports the average
5753 incoming bytes rate over that period, in bytes per period. It may be used
5754 to detect users which upload too much and too fast. Warning: with large
5755 uploads, it is possible that the amount of uploaded data will be counted
5756 once upon termination, thus causing spikes in the average transfer speed
5757 instead of having a smooth one. This may partially be smoothed with
5758 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
5759 recommended for better fairness.
5760
5761 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
5762 integer which counts the cumulated amount of bytes sent to clients which
5763 matched this entry. Headers are included in the count. This may be used
5764 to limit abuse of bots sucking the whole site.
5765
5766 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
5767 an integer parameter <period> which indicates in milliseconds the length
5768 of the period over which the average is measured. It reports the average
5769 outgoing bytes rate over that period, in bytes per period. It may be used
5770 to detect users which download too much and too fast. Warning: with large
5771 transfers, it is possible that the amount of transferred data will be
5772 counted once upon termination, thus causing spikes in the average
5773 transfer speed instead of having a smooth one. This may partially be
5774 smoothed with "option contstats" though this is not perfect yet. Use of
5775 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02005776
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005777 There is only one stick-table per proxy. At the moment of writing this doc,
5778 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005779 to be required, simply create a dummy backend with a stick-table in it and
5780 reference it.
5781
5782 It is important to understand that stickiness based on learning information
5783 has some limitations, including the fact that all learned associations are
5784 lost upon restart. In general it can be good as a complement but not always
5785 as an exclusive stickiness.
5786
Willy Tarreauc9705a12010-07-27 20:05:50 +02005787 Last, memory requirements may be important when storing many data types.
5788 Indeed, storing all indicators above at once in each entry requires 116 bytes
5789 per entry, or 116 MB for a 1-million entries table. This is definitely not
5790 something that can be ignored.
5791
5792 Example:
5793 # Keep track of counters of up to 1 million IP addresses over 5 minutes
5794 # and store a general purpose counter and the average connection rate
5795 # computed over a sliding window of 30 seconds.
5796 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
5797
5798 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01005799 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005800
5801
Emeric Brun6a1cefa2010-09-24 18:15:17 +02005802stick store-response <pattern> [table <table>] [{if | unless} <condition>]
5803 Define a request pattern used to create an entry in a stickiness table
5804 May be used in sections : defaults | frontend | listen | backend
5805 no | no | yes | yes
5806
5807 Arguments :
5808 <pattern> is a pattern extraction rule as described in section 7.8. It
5809 describes what elements of the response or connection will
5810 be analysed, extracted and stored in the table once a
5811 server is selected.
5812
5813 <table> is an optional stickiness table name. If unspecified, the same
5814 backend's table is used. A stickiness table is declared using
5815 the "stick-table" statement.
5816
5817 <cond> is an optional storage condition. It makes it possible to store
5818 certain criteria only when some conditions are met (or not met).
5819 For instance, it could be used to store the SSL session ID only
5820 when the response is a SSL server hello.
5821
5822 Some protocols or applications require complex stickiness rules and cannot
5823 always simply rely on cookies nor hashing. The "stick store-response"
5824 statement describes a rule to decide what to extract from the response and
5825 when to do it, in order to store it into a stickiness table for further
5826 requests to match it using the "stick match" statement. Obviously the
5827 extracted part must make sense and have a chance to be matched in a further
5828 request. Storing an ID found in a header of a response makes sense.
5829 See section 7 for a complete list of possible patterns and transformation
5830 rules.
5831
5832 The table has to be declared using the "stick-table" statement. It must be of
5833 a type compatible with the pattern. By default it is the one which is present
5834 in the same backend. It is possible to share a table with other backends by
5835 referencing it using the "table" keyword. If another table is referenced,
5836 the server's ID inside the backends are used. By default, all server IDs
5837 start at 1 in each backend, so the server ordering is enough. But in case of
5838 doubt, it is highly recommended to force server IDs using their "id" setting.
5839
5840 It is possible to restrict the conditions where a "stick store-response"
5841 statement will apply, using "if" or "unless" followed by a condition. This
5842 condition will be evaluated while parsing the response, so any criteria can
5843 be used. See section 7 for ACL based conditions.
5844
5845 There is no limit on the number of "stick store-response" statements, but
5846 there is a limit of 8 simultaneous stores per request or response. This
5847 makes it possible to store up to 8 criteria, all extracted from either the
5848 request or the response, regardless of the number of rules. Only the 8 first
5849 ones which match will be kept. Using this, it is possible to feed multiple
5850 tables at once in the hope to increase the chance to recognize a user on
5851 another protocol or access method.
5852
5853 The table will contain the real server that processed the request.
5854
5855 Example :
5856 # Learn SSL session ID from both request and response and create affinity.
5857 backend https
5858 mode tcp
5859 balance roundrobin
5860 # maximum SSL session ID length is 32 bytes.
5861 stick-table type binary len 32 size 30k expire 30m
5862
5863 acl clienthello req_ssl_hello_type 1
5864 acl serverhello rep_ssl_hello_type 2
5865
5866 # use tcp content accepts to detects ssl client and server hello.
5867 tcp-request inspect-delay 5s
5868 tcp-request content accept if clienthello
5869
5870 # no timeout on response inspect delay by default.
5871 tcp-response content accept if serverhello
5872
5873 # SSL session ID (SSLID) may be present on a client or server hello.
5874 # Its length is coded on 1 byte at offset 43 and its value starts
5875 # at offset 44.
5876
5877 # Match and learn on request if client hello.
5878 stick on payload_lv(43,1) if clienthello
5879
5880 # Learn on response if server hello.
5881 stick store-response payload_lv(43,1) if serverhello
5882
5883 server s1 192.168.1.1:443
5884 server s2 192.168.1.1:443
5885
5886 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
5887 extraction.
5888
5889
Willy Tarreaue9656522010-08-17 15:40:09 +02005890tcp-request connection <action> [{if | unless} <condition>]
5891 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02005892 May be used in sections : defaults | frontend | listen | backend
5893 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02005894 Arguments :
5895 <action> defines the action to perform if the condition applies. Valid
5896 actions include : "accept", "reject", "track-sc1", "track-sc2".
5897 See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02005898
Willy Tarreaue9656522010-08-17 15:40:09 +02005899 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005900
5901 Immediately after acceptance of a new incoming connection, it is possible to
5902 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02005903 or dropped or have its counters tracked. Those conditions cannot make use of
5904 any data contents because the connection has not been read from yet, and the
5905 buffers are not yet allocated. This is used to selectively and very quickly
5906 accept or drop connections from various sources with a very low overhead. If
5907 some contents need to be inspected in order to take the decision, the
5908 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005909
Willy Tarreaue9656522010-08-17 15:40:09 +02005910 The "tcp-request connection" rules are evaluated in their exact declaration
5911 order. If no rule matches or if there is no rule, the default action is to
5912 accept the incoming connection. There is no specific limit to the number of
5913 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005914
Willy Tarreaue9656522010-08-17 15:40:09 +02005915 Three types of actions are supported :
5916 - accept :
5917 accepts the connection if the condition is true (when used with "if")
5918 or false (when used with "unless"). The first such rule executed ends
5919 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005920
Willy Tarreaue9656522010-08-17 15:40:09 +02005921 - reject :
5922 rejects the connection if the condition is true (when used with "if")
5923 or false (when used with "unless"). The first such rule executed ends
5924 the rules evaluation. Rejected connections do not even become a
5925 session, which is why they are accounted separately for in the stats,
5926 as "denied connections". They are not considered for the session
5927 rate-limit and are not logged either. The reason is that these rules
5928 should only be used to filter extremely high connection rates such as
5929 the ones encountered during a massive DDoS attack. Under these extreme
5930 conditions, the simple action of logging each event would make the
5931 system collapse and would considerably lower the filtering capacity. If
5932 logging is absolutely desired, then "tcp-request content" rules should
5933 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005934
Willy Tarreaue9656522010-08-17 15:40:09 +02005935 - { track-sc1 | track-sc2 } <key> [table <table>] :
5936 enables tracking of sticky counters from current connection. These
5937 rules do not stop evaluation and do not change default action. Two sets
5938 of counters may be simultaneously tracked by the same connection. The
5939 first "track-sc1" rule executed enables tracking of the counters of the
5940 specified table as the first set. The first "track-sc2" rule executed
5941 enables tracking of the counters of the specified table as the second
5942 set. It is a recommended practice to use the first set of counters for
5943 the per-frontend counters and the second set for the per-backend ones.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005944
Willy Tarreaue9656522010-08-17 15:40:09 +02005945 These actions take one or two arguments :
5946 <key> is mandatory, and defines the criterion the tracking key will
5947 be derived from. At the moment, only "src" is supported. With
5948 it, the key will be the connection's source IPv4 address.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005949
Willy Tarreaue9656522010-08-17 15:40:09 +02005950 <table> is an optional table to be used instead of the default one,
5951 which is the stick-table declared in the current proxy. All
5952 the counters for the matches and updates for the key will
5953 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005954
Willy Tarreaue9656522010-08-17 15:40:09 +02005955 Once a "track-sc*" rule is executed, the key is looked up in the table
5956 and if it is not found, an entry is allocated for it. Then a pointer to
5957 that entry is kept during all the session's life, and this entry's
5958 counters are updated as often as possible, every time the session's
5959 counters are updated, and also systematically when the session ends.
5960 If the entry tracks concurrent connection counters, one connection is
5961 counted for as long as the entry is tracked, and the entry will not
5962 expire during that time. Tracking counters also provides a performance
5963 advantage over just checking the keys, because only one table lookup is
5964 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005965
Willy Tarreaue9656522010-08-17 15:40:09 +02005966 Note that the "if/unless" condition is optional. If no condition is set on
5967 the action, it is simply performed unconditionally. That can be useful for
5968 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005969
Willy Tarreaue9656522010-08-17 15:40:09 +02005970 Example: accept all connections from white-listed hosts, reject too fast
5971 connection without counting them, and track accepted connections.
5972 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005973
Willy Tarreaue9656522010-08-17 15:40:09 +02005974 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005975 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaue9656522010-08-17 15:40:09 +02005976 tcp-request connection track-sc1 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005977
Willy Tarreaue9656522010-08-17 15:40:09 +02005978 Example: accept all connections from white-listed hosts, count all other
5979 connections and reject too fast ones. This results in abusive ones
5980 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005981
Willy Tarreaue9656522010-08-17 15:40:09 +02005982 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
5983 tcp-request connection track-sc1 src
5984 tcp-request connection reject if { sc1_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005985
5986 See section 7 about ACL usage.
5987
Willy Tarreaue9656522010-08-17 15:40:09 +02005988 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005989
5990
Willy Tarreaue9656522010-08-17 15:40:09 +02005991tcp-request content <action> [{if | unless} <condition>]
5992 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02005993 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02005994 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02005995 Arguments :
5996 <action> defines the action to perform if the condition applies. Valid
5997 actions include : "accept", "reject", "track-sc1", "track-sc2".
5998 See "tcp-request connection" above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02005999
Willy Tarreaue9656522010-08-17 15:40:09 +02006000 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02006001
Willy Tarreaue9656522010-08-17 15:40:09 +02006002 A request's contents can be analysed at an early stage of request processing
6003 called "TCP content inspection". During this stage, ACL-based rules are
6004 evaluated every time the request contents are updated, until either an
6005 "accept" or a "reject" rule matches, or the TCP request inspection delay
6006 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02006007
Willy Tarreaue9656522010-08-17 15:40:09 +02006008 The first difference between these rules and "tcp-request connection" rules
6009 is that "tcp-request content" rules can make use of contents to take a
6010 decision. Most often, these decisions will consider a protocol recognition or
6011 validity. The second difference is that content-based rules can be used in
6012 both frontends and backends. In frontends, they will be evaluated upon new
6013 connections. In backends, they will be evaluated once a session is assigned
6014 a backend. This means that a single frontend connection may be evaluated
6015 several times by one or multiple backends when a session gets reassigned
6016 (for instance after a client-side HTTP keep-alive request).
Willy Tarreau62644772008-07-16 18:36:06 +02006017
Willy Tarreaue9656522010-08-17 15:40:09 +02006018 Content-based rules are evaluated in their exact declaration order. If no
6019 rule matches or if there is no rule, the default action is to accept the
6020 contents. There is no specific limit to the number of rules which may be
6021 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02006022
Willy Tarreaue9656522010-08-17 15:40:09 +02006023 Three types of actions are supported :
6024 - accept :
6025 - reject :
6026 - { track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02006027
Willy Tarreaue9656522010-08-17 15:40:09 +02006028 They have the same meaning as their counter-parts in "tcp-request connection"
6029 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02006030
Willy Tarreaue9656522010-08-17 15:40:09 +02006031 Also, it is worth noting that if sticky counters are tracked from a rule
6032 defined in a backend, this tracking will automatically end when the session
6033 releases the backend. That allows per-backend counter tracking even in case
6034 of HTTP keep-alive requests when the backend changes. While there is nothing
6035 mandatory about it, it is recommended to use the track-sc1 pointer to track
6036 per-frontend counters and track-sc2 to track per-backend counters.
Willy Tarreau62644772008-07-16 18:36:06 +02006037
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006038 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02006039 the action, it is simply performed unconditionally. That can be useful for
6040 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02006041
Willy Tarreaue9656522010-08-17 15:40:09 +02006042 It is perfectly possible to match layer 7 contents with "tcp-request content"
6043 rules, but then it is important to ensure that a full request has been
6044 buffered, otherwise no contents will match. In order to achieve this, the
6045 best solution involves detecting the HTTP protocol during the inspection
6046 period.
Willy Tarreau62644772008-07-16 18:36:06 +02006047
6048 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02006049 # Accept HTTP requests containing a Host header saying "example.com"
6050 # and reject everything else.
6051 acl is_host_com hdr(Host) -i example.com
6052 tcp-request inspect-delay 30s
6053 tcp-request content accept if HTTP is_host_com
6054 tcp-request content reject
6055
6056 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02006057 # reject SMTP connection if client speaks first
6058 tcp-request inspect-delay 30s
6059 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006060 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02006061
6062 # Forward HTTPS connection only if client speaks
6063 tcp-request inspect-delay 30s
6064 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006065 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02006066 tcp-request content reject
6067
6068 Example: track per-frontend and per-backend counters, block abusers at the
6069 frontend when the backend detects abuse.
6070
6071 frontend http
6072 # Use General Purpose Couter 0 in SC1 as a global abuse counter
6073 # protecting all our sites
6074 stick-table type ip size 1m expire 5m store gpc0
6075 tcp-request connection track-sc1 src
6076 tcp-request connection reject if { sc1_get_gpc0 gt 0 }
6077 ...
6078 use_backend http_dynamic if { path_end .php }
6079
6080 backend http_dynamic
6081 # if a source makes too fast requests to this dynamic site (tracked
6082 # by SC2), block it globally in the frontend.
6083 stick-table type ip size 1m expire 5m store http_req_rate(10s)
6084 acl click_too_fast sc2_http_req_rate gt 10
6085 acl mark_as_abuser sc1_inc_gpc0
6086 tcp-request content track-sc2 src
6087 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02006088
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006089 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02006090
Willy Tarreaue9656522010-08-17 15:40:09 +02006091 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02006092
6093
6094tcp-request inspect-delay <timeout>
6095 Set the maximum allowed time to wait for data during content inspection
6096 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006097 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02006098 Arguments :
6099 <timeout> is the timeout value specified in milliseconds by default, but
6100 can be in any other unit if the number is suffixed by the unit,
6101 as explained at the top of this document.
6102
6103 People using haproxy primarily as a TCP relay are often worried about the
6104 risk of passing any type of protocol to a server without any analysis. In
6105 order to be able to analyze the request contents, we must first withhold
6106 the data then analyze them. This statement simply enables withholding of
6107 data for at most the specified amount of time.
6108
Willy Tarreaufb356202010-08-03 14:02:05 +02006109 TCP content inspection applies very early when a connection reaches a
6110 frontend, then very early when the connection is forwarded to a backend. This
6111 means that a connection may experience a first delay in the frontend and a
6112 second delay in the backend if both have tcp-request rules.
6113
Willy Tarreau62644772008-07-16 18:36:06 +02006114 Note that when performing content inspection, haproxy will evaluate the whole
6115 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006116 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02006117 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01006118 contents are definitive. If no delay is set, haproxy will not wait at all
6119 and will immediately apply a verdict based on the available information.
6120 Obviously this is unlikely to be very useful and might even be racy, so such
6121 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02006122
6123 As soon as a rule matches, the request is released and continues as usual. If
6124 the timeout is reached and no rule matches, the default policy will be to let
6125 it pass through unaffected.
6126
6127 For most protocols, it is enough to set it to a few seconds, as most clients
6128 send the full request immediately upon connection. Add 3 or more seconds to
6129 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01006130 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02006131 before the server (eg: SMTP), or to wait for a client to talk before passing
6132 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02006133 least the inspection delay, otherwise it will expire first. If the client
6134 closes the connection or if the buffer is full, the delay immediately expires
6135 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02006136
Willy Tarreau55165fe2009-05-10 12:02:55 +02006137 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02006138 "timeout client".
6139
6140
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006141tcp-response content <action> [{if | unless} <condition>]
6142 Perform an action on a session response depending on a layer 4-7 condition
6143 May be used in sections : defaults | frontend | listen | backend
6144 no | no | yes | yes
6145 Arguments :
6146 <action> defines the action to perform if the condition applies. Valid
6147 actions include : "accept", "reject".
6148 See "tcp-request connection" above for their signification.
6149
6150 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
6151
6152 Response contents can be analysed at an early stage of response processing
6153 called "TCP content inspection". During this stage, ACL-based rules are
6154 evaluated every time the response contents are updated, until either an
6155 "accept" or a "reject" rule matches, or a TCP response inspection delay is
6156 set and expires with no matching rule.
6157
6158 Most often, these decisions will consider a protocol recognition or validity.
6159
6160 Content-based rules are evaluated in their exact declaration order. If no
6161 rule matches or if there is no rule, the default action is to accept the
6162 contents. There is no specific limit to the number of rules which may be
6163 inserted.
6164
6165 Two types of actions are supported :
6166 - accept :
6167 accepts the response if the condition is true (when used with "if")
6168 or false (when used with "unless"). The first such rule executed ends
6169 the rules evaluation.
6170
6171 - reject :
6172 rejects the response if the condition is true (when used with "if")
6173 or false (when used with "unless"). The first such rule executed ends
6174 the rules evaluation. Rejected session are immediatly closed.
6175
6176 Note that the "if/unless" condition is optional. If no condition is set on
6177 the action, it is simply performed unconditionally. That can be useful for
6178 for changing the default action to a reject.
6179
6180 It is perfectly possible to match layer 7 contents with "tcp-reponse content"
6181 rules, but then it is important to ensure that a full response has been
6182 buffered, otherwise no contents will match. In order to achieve this, the
6183 best solution involves detecting the HTTP protocol during the inspection
6184 period.
6185
6186 See section 7 about ACL usage.
6187
6188 See also : "tcp-request content", "tcp-response inspect-delay"
6189
6190
6191tcp-response inspect-delay <timeout>
6192 Set the maximum allowed time to wait for a response during content inspection
6193 May be used in sections : defaults | frontend | listen | backend
6194 no | no | yes | yes
6195 Arguments :
6196 <timeout> is the timeout value specified in milliseconds by default, but
6197 can be in any other unit if the number is suffixed by the unit,
6198 as explained at the top of this document.
6199
6200 See also : "tcp-response content", "tcp-request inspect-delay".
6201
6202
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006203timeout check <timeout>
6204 Set additional check timeout, but only after a connection has been already
6205 established.
6206
6207 May be used in sections: defaults | frontend | listen | backend
6208 yes | no | yes | yes
6209 Arguments:
6210 <timeout> is the timeout value specified in milliseconds by default, but
6211 can be in any other unit if the number is suffixed by the unit,
6212 as explained at the top of this document.
6213
6214 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
6215 for check and "timeout check" as an additional read timeout. The "min" is
6216 used so that people running with *very* long "timeout connect" (eg. those
6217 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01006218 (Please also note that there is no valid reason to have such long connect
6219 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
6220 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006221
6222 If "timeout check" is not set haproxy uses "inter" for complete check
6223 timeout (connect + read) exactly like all <1.3.15 version.
6224
6225 In most cases check request is much simpler and faster to handle than normal
6226 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01006227 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006228
6229 This parameter is specific to backends, but can be specified once for all in
6230 "defaults" sections. This is in fact one of the easiest solutions not to
6231 forget about it.
6232
Willy Tarreau41a340d2008-01-22 12:25:31 +01006233 See also: "timeout connect", "timeout queue", "timeout server",
6234 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006235
6236
Willy Tarreau0ba27502007-12-24 16:55:16 +01006237timeout client <timeout>
6238timeout clitimeout <timeout> (deprecated)
6239 Set the maximum inactivity time on the client side.
6240 May be used in sections : defaults | frontend | listen | backend
6241 yes | yes | yes | no
6242 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006243 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006244 can be in any other unit if the number is suffixed by the unit,
6245 as explained at the top of this document.
6246
6247 The inactivity timeout applies when the client is expected to acknowledge or
6248 send data. In HTTP mode, this timeout is particularly important to consider
6249 during the first phase, when the client sends the request, and during the
6250 response while it is reading data sent by the server. The value is specified
6251 in milliseconds by default, but can be in any other unit if the number is
6252 suffixed by the unit, as specified at the top of this document. In TCP mode
6253 (and to a lesser extent, in HTTP mode), it is highly recommended that the
6254 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006255 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01006256 losses by specifying timeouts that are slightly above multiples of 3 seconds
6257 (eg: 4 or 5 seconds).
6258
6259 This parameter is specific to frontends, but can be specified once for all in
6260 "defaults" sections. This is in fact one of the easiest solutions not to
6261 forget about it. An unspecified timeout results in an infinite timeout, which
6262 is not recommended. Such a usage is accepted and works but reports a warning
6263 during startup because it may results in accumulation of expired sessions in
6264 the system if the system's timeouts are not configured either.
6265
6266 This parameter replaces the old, deprecated "clitimeout". It is recommended
6267 to use it to write new configurations. The form "timeout clitimeout" is
6268 provided only by backwards compatibility but its use is strongly discouraged.
6269
6270 See also : "clitimeout", "timeout server".
6271
6272
6273timeout connect <timeout>
6274timeout contimeout <timeout> (deprecated)
6275 Set the maximum time to wait for a connection attempt to a server to succeed.
6276 May be used in sections : defaults | frontend | listen | backend
6277 yes | no | yes | yes
6278 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006279 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006280 can be in any other unit if the number is suffixed by the unit,
6281 as explained at the top of this document.
6282
6283 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006284 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01006285 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01006286 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006287 connect timeout also presets both queue and tarpit timeouts to the same value
6288 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006289
6290 This parameter is specific to backends, but can be specified once for all in
6291 "defaults" sections. This is in fact one of the easiest solutions not to
6292 forget about it. An unspecified timeout results in an infinite timeout, which
6293 is not recommended. Such a usage is accepted and works but reports a warning
6294 during startup because it may results in accumulation of failed sessions in
6295 the system if the system's timeouts are not configured either.
6296
6297 This parameter replaces the old, deprecated "contimeout". It is recommended
6298 to use it to write new configurations. The form "timeout contimeout" is
6299 provided only by backwards compatibility but its use is strongly discouraged.
6300
Willy Tarreau41a340d2008-01-22 12:25:31 +01006301 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
6302 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006303
6304
Willy Tarreaub16a5742010-01-10 14:46:16 +01006305timeout http-keep-alive <timeout>
6306 Set the maximum allowed time to wait for a new HTTP request to appear
6307 May be used in sections : defaults | frontend | listen | backend
6308 yes | yes | yes | yes
6309 Arguments :
6310 <timeout> is the timeout value specified in milliseconds by default, but
6311 can be in any other unit if the number is suffixed by the unit,
6312 as explained at the top of this document.
6313
6314 By default, the time to wait for a new request in case of keep-alive is set
6315 by "timeout http-request". However this is not always convenient because some
6316 people want very short keep-alive timeouts in order to release connections
6317 faster, and others prefer to have larger ones but still have short timeouts
6318 once the request has started to present itself.
6319
6320 The "http-keep-alive" timeout covers these needs. It will define how long to
6321 wait for a new HTTP request to start coming after a response was sent. Once
6322 the first byte of request has been seen, the "http-request" timeout is used
6323 to wait for the complete request to come. Note that empty lines prior to a
6324 new request do not refresh the timeout and are not counted as a new request.
6325
6326 There is also another difference between the two timeouts : when a connection
6327 expires during timeout http-keep-alive, no error is returned, the connection
6328 just closes. If the connection expires in "http-request" while waiting for a
6329 connection to complete, a HTTP 408 error is returned.
6330
6331 In general it is optimal to set this value to a few tens to hundreds of
6332 milliseconds, to allow users to fetch all objects of a page at once but
6333 without waiting for further clicks. Also, if set to a very small value (eg:
6334 1 millisecond) it will probably only accept pipelined requests but not the
6335 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02006336 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01006337
6338 If this parameter is not set, the "http-request" timeout applies, and if both
6339 are not set, "timeout client" still applies at the lower level. It should be
6340 set in the frontend to take effect, unless the frontend is in TCP mode, in
6341 which case the HTTP backend's timeout will be used.
6342
6343 See also : "timeout http-request", "timeout client".
6344
6345
Willy Tarreau036fae02008-01-06 13:24:40 +01006346timeout http-request <timeout>
6347 Set the maximum allowed time to wait for a complete HTTP request
6348 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006349 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01006350 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006351 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01006352 can be in any other unit if the number is suffixed by the unit,
6353 as explained at the top of this document.
6354
6355 In order to offer DoS protection, it may be required to lower the maximum
6356 accepted time to receive a complete HTTP request without affecting the client
6357 timeout. This helps protecting against established connections on which
6358 nothing is sent. The client timeout cannot offer a good protection against
6359 this abuse because it is an inactivity timeout, which means that if the
6360 attacker sends one character every now and then, the timeout will not
6361 trigger. With the HTTP request timeout, no matter what speed the client
6362 types, the request will be aborted if it does not complete in time.
6363
6364 Note that this timeout only applies to the header part of the request, and
6365 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01006366 used anymore. It is used again on keep-alive connections to wait for a second
6367 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01006368
6369 Generally it is enough to set it to a few seconds, as most clients send the
6370 full request immediately upon connection. Add 3 or more seconds to cover TCP
6371 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
6372 generally work on local networks as long as there are no packet losses. This
6373 will prevent people from sending bare HTTP requests using telnet.
6374
6375 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006376 chunk of the incoming request. It should be set in the frontend to take
6377 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
6378 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01006379
Willy Tarreaub16a5742010-01-10 14:46:16 +01006380 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01006381
Willy Tarreau844e3c52008-01-11 16:28:18 +01006382
6383timeout queue <timeout>
6384 Set the maximum time to wait in the queue for a connection slot to be free
6385 May be used in sections : defaults | frontend | listen | backend
6386 yes | no | yes | yes
6387 Arguments :
6388 <timeout> is the timeout value specified in milliseconds by default, but
6389 can be in any other unit if the number is suffixed by the unit,
6390 as explained at the top of this document.
6391
6392 When a server's maxconn is reached, connections are left pending in a queue
6393 which may be server-specific or global to the backend. In order not to wait
6394 indefinitely, a timeout is applied to requests pending in the queue. If the
6395 timeout is reached, it is considered that the request will almost never be
6396 served, so it is dropped and a 503 error is returned to the client.
6397
6398 The "timeout queue" statement allows to fix the maximum time for a request to
6399 be left pending in a queue. If unspecified, the same value as the backend's
6400 connection timeout ("timeout connect") is used, for backwards compatibility
6401 with older versions with no "timeout queue" parameter.
6402
6403 See also : "timeout connect", "contimeout".
6404
6405
6406timeout server <timeout>
6407timeout srvtimeout <timeout> (deprecated)
6408 Set the maximum inactivity time on the server side.
6409 May be used in sections : defaults | frontend | listen | backend
6410 yes | no | yes | yes
6411 Arguments :
6412 <timeout> is the timeout value specified in milliseconds by default, but
6413 can be in any other unit if the number is suffixed by the unit,
6414 as explained at the top of this document.
6415
6416 The inactivity timeout applies when the server is expected to acknowledge or
6417 send data. In HTTP mode, this timeout is particularly important to consider
6418 during the first phase of the server's response, when it has to send the
6419 headers, as it directly represents the server's processing time for the
6420 request. To find out what value to put there, it's often good to start with
6421 what would be considered as unacceptable response times, then check the logs
6422 to observe the response time distribution, and adjust the value accordingly.
6423
6424 The value is specified in milliseconds by default, but can be in any other
6425 unit if the number is suffixed by the unit, as specified at the top of this
6426 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
6427 recommended that the client timeout remains equal to the server timeout in
6428 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006429 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01006430 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01006431 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01006432
6433 This parameter is specific to backends, but can be specified once for all in
6434 "defaults" sections. This is in fact one of the easiest solutions not to
6435 forget about it. An unspecified timeout results in an infinite timeout, which
6436 is not recommended. Such a usage is accepted and works but reports a warning
6437 during startup because it may results in accumulation of expired sessions in
6438 the system if the system's timeouts are not configured either.
6439
6440 This parameter replaces the old, deprecated "srvtimeout". It is recommended
6441 to use it to write new configurations. The form "timeout srvtimeout" is
6442 provided only by backwards compatibility but its use is strongly discouraged.
6443
6444 See also : "srvtimeout", "timeout client".
6445
6446
6447timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01006448 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01006449 May be used in sections : defaults | frontend | listen | backend
6450 yes | yes | yes | yes
6451 Arguments :
6452 <timeout> is the tarpit duration specified in milliseconds by default, but
6453 can be in any other unit if the number is suffixed by the unit,
6454 as explained at the top of this document.
6455
6456 When a connection is tarpitted using "reqtarpit", it is maintained open with
6457 no activity for a certain amount of time, then closed. "timeout tarpit"
6458 defines how long it will be maintained open.
6459
6460 The value is specified in milliseconds by default, but can be in any other
6461 unit if the number is suffixed by the unit, as specified at the top of this
6462 document. If unspecified, the same value as the backend's connection timeout
6463 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01006464 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006465
6466 See also : "timeout connect", "contimeout".
6467
6468
6469transparent (deprecated)
6470 Enable client-side transparent proxying
6471 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006472 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006473 Arguments : none
6474
6475 This keyword was introduced in order to provide layer 7 persistence to layer
6476 3 load balancers. The idea is to use the OS's ability to redirect an incoming
6477 connection for a remote address to a local process (here HAProxy), and let
6478 this process know what address was initially requested. When this option is
6479 used, sessions without cookies will be forwarded to the original destination
6480 IP address of the incoming request (which should match that of another
6481 equipment), while requests with cookies will still be forwarded to the
6482 appropriate server.
6483
6484 The "transparent" keyword is deprecated, use "option transparent" instead.
6485
6486 Note that contrary to a common belief, this option does NOT make HAProxy
6487 present the client's IP to the server when establishing the connection.
6488
Willy Tarreau844e3c52008-01-11 16:28:18 +01006489 See also: "option transparent"
6490
6491
6492use_backend <backend> if <condition>
6493use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006494 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006495 May be used in sections : defaults | frontend | listen | backend
6496 no | yes | yes | no
6497 Arguments :
6498 <backend> is the name of a valid backend or "listen" section.
6499
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006500 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006501
6502 When doing content-switching, connections arrive on a frontend and are then
6503 dispatched to various backends depending on a number of conditions. The
6504 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006505 "use_backend" keyword. While it is normally used with HTTP processing, it can
6506 also be used in pure TCP, either without content using stateless ACLs (eg:
6507 source address validation) or combined with a "tcp-request" rule to wait for
6508 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006509
6510 There may be as many "use_backend" rules as desired. All of these rules are
6511 evaluated in their declaration order, and the first one which matches will
6512 assign the backend.
6513
6514 In the first form, the backend will be used if the condition is met. In the
6515 second form, the backend will be used if the condition is not met. If no
6516 condition is valid, the backend defined with "default_backend" will be used.
6517 If no default backend is defined, either the servers in the same section are
6518 used (in case of a "listen" section) or, in case of a frontend, no server is
6519 used and a 503 service unavailable response is returned.
6520
Willy Tarreau51aecc72009-07-12 09:47:04 +02006521 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006522 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02006523 and backend processing will immediately follow, or the backend will wait for
6524 a complete HTTP request to get in. This feature is useful when a frontend
6525 must decode several protocols on a unique port, one of them being HTTP.
6526
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006527 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006528
Willy Tarreau036fae02008-01-06 13:24:40 +01006529
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010065305. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01006531------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006532
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01006533The "server" and "default-server" keywords support a certain number of settings
6534which are all passed as arguments on the server line. The order in which those
6535arguments appear does not count, and they are all optional. Some of those
6536settings are single words (booleans) while others expect one or several values
6537after them. In this case, the values must immediately follow the setting name.
6538Except default-server, all those settings must be specified after the server's
6539address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02006540
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006541 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01006542 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02006543
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006544The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006545
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006546addr <ipv4>
6547 Using the "addr" parameter, it becomes possible to use a different IP address
6548 to send health-checks. On some servers, it may be desirable to dedicate an IP
6549 address to specific component able to perform complex tests which are more
6550 suitable to health-checks than the application. This parameter is ignored if
6551 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006552
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006553 Supported in default-server: No
6554
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006555backup
6556 When "backup" is present on a server line, the server is only used in load
6557 balancing when all other non-backup servers are unavailable. Requests coming
6558 with a persistence cookie referencing the server will always be served
6559 though. By default, only the first operational backup server is used, unless
6560 the "allbackups" option is set in the backend. See also the "allbackups"
6561 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006562
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006563 Supported in default-server: No
6564
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006565check
6566 This option enables health checks on the server. By default, a server is
6567 always considered available. If "check" is set, the server will receive
6568 periodic health checks to ensure that it is really able to serve requests.
6569 The default address and port to send the tests to are those of the server,
6570 and the default source is the same as the one defined in the backend. It is
6571 possible to change the address using the "addr" parameter, the port using the
6572 "port" parameter, the source address using the "source" address, and the
6573 interval and timers using the "inter", "rise" and "fall" parameters. The
6574 request method is define in the backend using the "httpchk", "smtpchk",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01006575 "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please refer to
6576 those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006577
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006578 Supported in default-server: No
6579
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006580cookie <value>
6581 The "cookie" parameter sets the cookie value assigned to the server to
6582 <value>. This value will be checked in incoming requests, and the first
6583 operational server possessing the same value will be selected. In return, in
6584 cookie insertion or rewrite modes, this value will be assigned to the cookie
6585 sent to the client. There is nothing wrong in having several servers sharing
6586 the same cookie value, and it is in fact somewhat common between normal and
6587 backup servers. See also the "cookie" keyword in backend section.
6588
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006589 Supported in default-server: No
6590
Willy Tarreau96839092010-03-29 10:02:24 +02006591disabled
6592 The "disabled" keyword starts the server in the "disabled" state. That means
6593 that it is marked down in maintenance mode, and no connection other than the
6594 ones allowed by persist mode will reach it. It is very well suited to setup
6595 new servers, because normal traffic will never reach them, while it is still
6596 possible to test the service by making use of the force-persist mechanism.
6597
6598 Supported in default-server: No
6599
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006600error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01006601 If health observing is enabled, the "error-limit" parameter specifies the
6602 number of consecutive errors that triggers event selected by the "on-error"
6603 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006604
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006605 Supported in default-server: Yes
6606
6607 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006608
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006609fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006610 The "fall" parameter states that a server will be considered as dead after
6611 <count> consecutive unsuccessful health checks. This value defaults to 3 if
6612 unspecified. See also the "check", "inter" and "rise" parameters.
6613
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006614 Supported in default-server: Yes
6615
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006616id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02006617 Set a persistent ID for the server. This ID must be positive and unique for
6618 the proxy. An unused ID will automatically be assigned if unset. The first
6619 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006620
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006621 Supported in default-server: No
6622
6623inter <delay>
6624fastinter <delay>
6625downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006626 The "inter" parameter sets the interval between two consecutive health checks
6627 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
6628 It is also possible to use "fastinter" and "downinter" to optimize delays
6629 between checks depending on the server state :
6630
6631 Server state | Interval used
6632 ---------------------------------+-----------------------------------------
6633 UP 100% (non-transitional) | "inter"
6634 ---------------------------------+-----------------------------------------
6635 Transitionally UP (going down), |
6636 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
6637 or yet unchecked. |
6638 ---------------------------------+-----------------------------------------
6639 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
6640 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01006641
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006642 Just as with every other time-based parameter, they can be entered in any
6643 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
6644 serves as a timeout for health checks sent to servers if "timeout check" is
6645 not set. In order to reduce "resonance" effects when multiple servers are
6646 hosted on the same hardware, the health-checks of all servers are started
6647 with a small time offset between them. It is also possible to add some random
6648 noise in the health checks interval using the global "spread-checks"
6649 keyword. This makes sense for instance when a lot of backends use the same
6650 servers.
6651
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006652 Supported in default-server: Yes
6653
6654maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006655 The "maxconn" parameter specifies the maximal number of concurrent
6656 connections that will be sent to this server. If the number of incoming
6657 concurrent requests goes higher than this value, they will be queued, waiting
6658 for a connection to be released. This parameter is very important as it can
6659 save fragile servers from going down under extreme loads. If a "minconn"
6660 parameter is specified, the limit becomes dynamic. The default value is "0"
6661 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
6662 the backend's "fullconn" keyword.
6663
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006664 Supported in default-server: Yes
6665
6666maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006667 The "maxqueue" parameter specifies the maximal number of connections which
6668 will wait in the queue for this server. If this limit is reached, next
6669 requests will be redispatched to other servers instead of indefinitely
6670 waiting to be served. This will break persistence but may allow people to
6671 quickly re-log in when the server they try to connect to is dying. The
6672 default value is "0" which means the queue is unlimited. See also the
6673 "maxconn" and "minconn" parameters.
6674
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006675 Supported in default-server: Yes
6676
6677minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006678 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
6679 limit following the backend's load. The server will always accept at least
6680 <minconn> connections, never more than <maxconn>, and the limit will be on
6681 the ramp between both values when the backend has less than <fullconn>
6682 concurrent connections. This makes it possible to limit the load on the
6683 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006684 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006685 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006686
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006687 Supported in default-server: Yes
6688
Simon Hormanfa461682011-06-25 09:39:49 +09006689non-stick
6690 Never add connections allocated to this sever to a stick-table.
6691 This may be used in conjunction with backup to ensure that
6692 stick-table persistence is disabled for backup servers.
6693
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006694observe <mode>
6695 This option enables health adjusting based on observing communication with
6696 the server. By default this functionality is disabled and enabling it also
6697 requires to enable health checks. There are two supported modes: "layer4" and
6698 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
6699 significant. In layer7, which is only allowed for http proxies, responses
6700 received from server are verified, like valid/wrong http code, unparsable
6701 headers, a timeout, etc.
6702
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006703 Supported in default-server: No
6704
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006705 See also the "check", "on-error" and "error-limit".
6706
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006707on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006708 Select what should happen when enough consecutive errors are detected.
6709 Currently, four modes are available:
6710 - fastinter: force fastinter
6711 - fail-check: simulate a failed check, also forces fastinter (default)
6712 - sudden-death: simulate a pre-fatal failed health check, one more failed
6713 check will mark a server down, forces fastinter
6714 - mark-down: mark the server immediately down and force fastinter
6715
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006716 Supported in default-server: Yes
6717
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006718 See also the "check", "observe" and "error-limit".
6719
Simon Hormane0d1bfb2011-06-21 14:34:58 +09006720on-marked-down <action>
6721 Modify what occurs when a server is marked down.
6722 Currently one action is available:
6723 - shutdown-sessions: Shutdown peer sessions
6724
6725 Actions are disabled by default
6726
6727 Supported in default-server: Yes
6728
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006729port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006730 Using the "port" parameter, it becomes possible to use a different port to
6731 send health-checks. On some servers, it may be desirable to dedicate a port
6732 to a specific component able to perform complex tests which are more suitable
6733 to health-checks than the application. It is common to run a simple script in
6734 inetd for instance. This parameter is ignored if the "check" parameter is not
6735 set. See also the "addr" parameter.
6736
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006737 Supported in default-server: Yes
6738
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006739redir <prefix>
6740 The "redir" parameter enables the redirection mode for all GET and HEAD
6741 requests addressing this server. This means that instead of having HAProxy
6742 forward the request to the server, it will send an "HTTP 302" response with
6743 the "Location" header composed of this prefix immediately followed by the
6744 requested URI beginning at the leading '/' of the path component. That means
6745 that no trailing slash should be used after <prefix>. All invalid requests
6746 will be rejected, and all non-GET or HEAD requests will be normally served by
6747 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006748 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006749 requests are still analysed, making this solution completely usable to direct
6750 users to a remote location in case of local disaster. Main use consists in
6751 increasing bandwidth for static servers by having the clients directly
6752 connect to them. Note: never use a relative location here, it would cause a
6753 loop between the client and HAProxy!
6754
6755 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
6756
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006757 Supported in default-server: No
6758
6759rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006760 The "rise" parameter states that a server will be considered as operational
6761 after <count> consecutive successful health checks. This value defaults to 2
6762 if unspecified. See also the "check", "inter" and "fall" parameters.
6763
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006764 Supported in default-server: Yes
6765
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01006766send-proxy
6767 The "send-proxy" parameter enforces use of the PROXY protocol over any
6768 connection established to this server. The PROXY protocol informs the other
6769 end about the layer 3/4 addresses of the incoming connection, so that it can
6770 know the client's address or the public address it accessed to, whatever the
6771 upper layer protocol. For connections accepted by an "accept-proxy" listener,
6772 the advertised address will be used. Only TCPv4 and TCPv6 address families
6773 are supported. Other families such as Unix sockets, will report an UNKNOWN
6774 family. Servers using this option can fully be chained to another instance of
6775 haproxy listening with an "accept-proxy" setting. This setting must not be
6776 used if the server isn't aware of the protocol. See also the "accept-proxy"
6777 option of the "bind" keyword.
6778
6779 Supported in default-server: No
6780
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006781slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006782 The "slowstart" parameter for a server accepts a value in milliseconds which
6783 indicates after how long a server which has just come back up will run at
6784 full speed. Just as with every other time-based parameter, it can be entered
6785 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
6786 linearly from 0 to 100% during this time. The limitation applies to two
6787 parameters :
6788
6789 - maxconn: the number of connections accepted by the server will grow from 1
6790 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
6791
6792 - weight: when the backend uses a dynamic weighted algorithm, the weight
6793 grows linearly from 1 to 100%. In this case, the weight is updated at every
6794 health-check. For this reason, it is important that the "inter" parameter
6795 is smaller than the "slowstart", in order to maximize the number of steps.
6796
6797 The slowstart never applies when haproxy starts, otherwise it would cause
6798 trouble to running servers. It only applies when a server has been previously
6799 seen as failed.
6800
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006801 Supported in default-server: Yes
6802
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006803source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02006804source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006805source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006806 The "source" parameter sets the source address which will be used when
6807 connecting to the server. It follows the exact same parameters and principle
6808 as the backend "source" keyword, except that it only applies to the server
6809 referencing it. Please consult the "source" keyword for details.
6810
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006811 Additionally, the "source" statement on a server line allows one to specify a
6812 source port range by indicating the lower and higher bounds delimited by a
6813 dash ('-'). Some operating systems might require a valid IP address when a
6814 source port range is specified. It is permitted to have the same IP/range for
6815 several servers. Doing so makes it possible to bypass the maximum of 64k
6816 total concurrent connections. The limit will then reach 64k connections per
6817 server.
6818
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006819 Supported in default-server: No
6820
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006821track [<proxy>/]<server>
6822 This option enables ability to set the current state of the server by
6823 tracking another one. Only a server with checks enabled can be tracked
6824 so it is not possible for example to track a server that tracks another
6825 one. If <proxy> is omitted the current one is used. If disable-on-404 is
6826 used, it has to be enabled on both proxies.
6827
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006828 Supported in default-server: No
6829
6830weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006831 The "weight" parameter is used to adjust the server's weight relative to
6832 other servers. All servers will receive a load proportional to their weight
6833 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02006834 load. The default weight is 1, and the maximal value is 256. A value of 0
6835 means the server will not participate in load-balancing but will still accept
6836 persistent connections. If this parameter is used to distribute the load
6837 according to server's capacity, it is recommended to start with values which
6838 can both grow and shrink, for instance between 10 and 100 to leave enough
6839 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006840
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006841 Supported in default-server: Yes
6842
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006843
68446. HTTP header manipulation
6845---------------------------
6846
6847In HTTP mode, it is possible to rewrite, add or delete some of the request and
6848response headers based on regular expressions. It is also possible to block a
6849request or a response if a particular header matches a regular expression,
6850which is enough to stop most elementary protocol attacks, and to protect
6851against information leak from the internal network. But there is a limitation
6852to this : since HAProxy's HTTP engine does not support keep-alive, only headers
6853passed during the first request of a TCP session will be seen. All subsequent
6854headers will be considered data only and not analyzed. Furthermore, HAProxy
6855never touches data contents, it stops analysis at the end of headers.
6856
Willy Tarreau816b9792009-09-15 21:25:21 +02006857There is an exception though. If HAProxy encounters an "Informational Response"
6858(status code 1xx), it is able to process all rsp* rules which can allow, deny,
6859rewrite or delete a header, but it will refuse to add a header to any such
6860messages as this is not HTTP-compliant. The reason for still processing headers
6861in such responses is to stop and/or fix any possible information leak which may
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006862happen, for instance because another downstream equipment would unconditionally
Willy Tarreau816b9792009-09-15 21:25:21 +02006863add a header, or if a server name appears there. When such messages are seen,
6864normal processing still occurs on the next non-informational messages.
6865
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006866This section covers common usage of the following keywords, described in detail
6867in section 4.2 :
6868
6869 - reqadd <string>
6870 - reqallow <search>
6871 - reqiallow <search>
6872 - reqdel <search>
6873 - reqidel <search>
6874 - reqdeny <search>
6875 - reqideny <search>
6876 - reqpass <search>
6877 - reqipass <search>
6878 - reqrep <search> <replace>
6879 - reqirep <search> <replace>
6880 - reqtarpit <search>
6881 - reqitarpit <search>
6882 - rspadd <string>
6883 - rspdel <search>
6884 - rspidel <search>
6885 - rspdeny <search>
6886 - rspideny <search>
6887 - rsprep <search> <replace>
6888 - rspirep <search> <replace>
6889
6890With all these keywords, the same conventions are used. The <search> parameter
6891is a POSIX extended regular expression (regex) which supports grouping through
6892parenthesis (without the backslash). Spaces and other delimiters must be
6893prefixed with a backslash ('\') to avoid confusion with a field delimiter.
6894Other characters may be prefixed with a backslash to change their meaning :
6895
6896 \t for a tab
6897 \r for a carriage return (CR)
6898 \n for a new line (LF)
6899 \ to mark a space and differentiate it from a delimiter
6900 \# to mark a sharp and differentiate it from a comment
6901 \\ to use a backslash in a regex
6902 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
6903 \xXX to write the ASCII hex code XX as in the C language
6904
6905The <replace> parameter contains the string to be used to replace the largest
6906portion of text matching the regex. It can make use of the special characters
6907above, and can reference a substring which is delimited by parenthesis in the
6908regex, by writing a backslash ('\') immediately followed by one digit from 0 to
69099 indicating the group position (0 designating the entire line). This practice
6910is very common to users of the "sed" program.
6911
6912The <string> parameter represents the string which will systematically be added
6913after the last header line. It can also use special character sequences above.
6914
6915Notes related to these keywords :
6916---------------------------------
6917 - these keywords are not always convenient to allow/deny based on header
6918 contents. It is strongly recommended to use ACLs with the "block" keyword
6919 instead, resulting in far more flexible and manageable rules.
6920
6921 - lines are always considered as a whole. It is not possible to reference
6922 a header name only or a value only. This is important because of the way
6923 headers are written (notably the number of spaces after the colon).
6924
6925 - the first line is always considered as a header, which makes it possible to
6926 rewrite or filter HTTP requests URIs or response codes, but in turn makes
6927 it harder to distinguish between headers and request line. The regex prefix
6928 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
6929 ^[^ \t:]*: matches any header name followed by a colon.
6930
6931 - for performances reasons, the number of characters added to a request or to
6932 a response is limited at build time to values between 1 and 4 kB. This
6933 should normally be far more than enough for most usages. If it is too short
6934 on occasional usages, it is possible to gain some space by removing some
6935 useless headers before adding new ones.
6936
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006937 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006938 without the 'i' letter except that they ignore case when matching patterns.
6939
6940 - when a request passes through a frontend then a backend, all req* rules
6941 from the frontend will be evaluated, then all req* rules from the backend
6942 will be evaluated. The reverse path is applied to responses.
6943
6944 - req* statements are applied after "block" statements, so that "block" is
6945 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01006946 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006947
6948
Willy Tarreaub937b7e2010-01-12 15:27:54 +010069497. Using ACLs and pattern extraction
6950------------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006951
6952The use of Access Control Lists (ACL) provides a flexible solution to perform
6953content switching and generally to take decisions based on content extracted
6954from the request, the response or any environmental status. The principle is
6955simple :
6956
6957 - define test criteria with sets of values
6958 - perform actions only if a set of tests is valid
6959
6960The actions generally consist in blocking the request, or selecting a backend.
6961
6962In order to define a test, the "acl" keyword is used. The syntax is :
6963
6964 acl <aclname> <criterion> [flags] [operator] <value> ...
6965
6966This creates a new ACL <aclname> or completes an existing one with new tests.
6967Those tests apply to the portion of request/response specified in <criterion>
6968and may be adjusted with optional flags [flags]. Some criteria also support
6969an operator which may be specified before the set of values. The values are
6970of the type supported by the criterion, and are separated by spaces.
6971
6972ACL names must be formed from upper and lower case letters, digits, '-' (dash),
6973'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
6974which means that "my_acl" and "My_Acl" are two different ACLs.
6975
6976There is no enforced limit to the number of ACLs. The unused ones do not affect
6977performance, they just consume a small amount of memory.
6978
6979The following ACL flags are currently supported :
6980
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006981 -i : ignore case during matching of all subsequent patterns.
6982 -f : load patterns from a file.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006983 -- : force end of flags. Useful when a string looks like one of the flags.
6984
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006985The "-f" flag is special as it loads all of the lines it finds in the file
6986specified in argument and loads all of them before continuing. It is even
6987possible to pass multiple "-f" arguments if the patterns are to be loaded from
Willy Tarreau58215a02010-05-13 22:07:43 +02006988multiple files. Empty lines as well as lines beginning with a sharp ('#') will
6989be ignored. All leading spaces and tabs will be stripped. If it is absolutely
6990needed to insert a valid pattern beginning with a sharp, just prefix it with a
6991space so that it is not taken for a comment. Depending on the data type and
6992match method, haproxy may load the lines into a binary tree, allowing very fast
6993lookups. This is true for IPv4 and exact string matching. In this case,
6994duplicates will automatically be removed. Also, note that the "-i" flag applies
6995to subsequent entries and not to entries loaded from files preceeding it. For
6996instance :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006997
6998 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
6999
7000In this example, each line of "exact-ua.lst" will be exactly matched against
7001the "user-agent" header of the request. Then each line of "generic-ua" will be
7002case-insensitively matched. Then the word "test" will be insensitively matched
7003too.
7004
7005Note that right now it is difficult for the ACL parsers to report errors, so if
7006a file is unreadable or unparsable, the most you'll get is a parse error in the
7007ACL. Thus, file-based ACLs should only be produced by reliable processes.
7008
Willy Tarreau6a06a402007-07-15 20:15:28 +02007009Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01007010
Willy Tarreau6a06a402007-07-15 20:15:28 +02007011 - integers or integer ranges
7012 - strings
7013 - regular expressions
7014 - IP addresses and networks
7015
7016
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070177.1. Matching integers
7018----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007019
7020Matching integers is special in that ranges and operators are permitted. Note
7021that integer matching only applies to positive values. A range is a value
7022expressed with a lower and an upper bound separated with a colon, both of which
7023may be omitted.
7024
7025For instance, "1024:65535" is a valid range to represent a range of
7026unprivileged ports, and "1024:" would also work. "0:1023" is a valid
7027representation of privileged ports, and ":1023" would also work.
7028
Willy Tarreau62644772008-07-16 18:36:06 +02007029As a special case, some ACL functions support decimal numbers which are in fact
7030two integers separated by a dot. This is used with some version checks for
7031instance. All integer properties apply to those decimal numbers, including
7032ranges and operators.
7033
Willy Tarreau6a06a402007-07-15 20:15:28 +02007034For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01007035operators with ranges does not make much sense and is strongly discouraged.
7036Similarly, it does not make much sense to perform order comparisons with a set
7037of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007038
Willy Tarreau0ba27502007-12-24 16:55:16 +01007039Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007040
7041 eq : true if the tested value equals at least one value
7042 ge : true if the tested value is greater than or equal to at least one value
7043 gt : true if the tested value is greater than at least one value
7044 le : true if the tested value is less than or equal to at least one value
7045 lt : true if the tested value is less than at least one value
7046
Willy Tarreau0ba27502007-12-24 16:55:16 +01007047For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007048
7049 acl negative-length hdr_val(content-length) lt 0
7050
Willy Tarreau62644772008-07-16 18:36:06 +02007051This one matches SSL versions between 3.0 and 3.1 (inclusive) :
7052
7053 acl sslv3 req_ssl_ver 3:3.1
7054
Willy Tarreau6a06a402007-07-15 20:15:28 +02007055
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070567.2. Matching strings
7057---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007058
7059String matching applies to verbatim strings as they are passed, with the
7060exception of the backslash ("\") which makes it possible to escape some
7061characters such as the space. If the "-i" flag is passed before the first
7062string, then the matching will be performed ignoring the case. In order
7063to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01007064before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007065
7066
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070677.3. Matching regular expressions (regexes)
7068-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007069
7070Just like with string matching, regex matching applies to verbatim strings as
7071they are passed, with the exception of the backslash ("\") which makes it
7072possible to escape some characters such as the space. If the "-i" flag is
7073passed before the first regex, then the matching will be performed ignoring
7074the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01007075the "--" flag before the first string. Same principle applies of course to
7076match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007077
7078
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070797.4. Matching IPv4 addresses
7080----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007081
7082IPv4 addresses values can be specified either as plain addresses or with a
7083netmask appended, in which case the IPv4 address matches whenever it is
7084within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007085host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01007086difficult to read and debug configurations. If hostnames are used, you should
7087at least ensure that they are present in /etc/hosts so that the configuration
7088does not depend on any random DNS match at the moment the configuration is
7089parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007090
7091
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070927.5. Available matching criteria
7093--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007094
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070957.5.1. Matching at Layer 4 and below
7096------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007097
7098A first set of criteria applies to information which does not require any
7099analysis of the request or response contents. Those generally include TCP/IP
7100addresses and ports, as well as internal values independant on the stream.
7101
Willy Tarreau6a06a402007-07-15 20:15:28 +02007102always_false
7103 This one never matches. All values and flags are ignored. It may be used as
7104 a temporary replacement for another one when adjusting configurations.
7105
7106always_true
7107 This one always matches. All values and flags are ignored. It may be used as
7108 a temporary replacement for another one when adjusting configurations.
7109
Willy Tarreaud63335a2010-02-26 12:56:52 +01007110avg_queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007111avg_queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007112 Returns the total number of queued connections of the designated backend
7113 divided by the number of active servers. This is very similar to "queue"
7114 except that the size of the farm is considered, in order to give a more
7115 accurate measurement of the time it may take for a new connection to be
7116 processed. The main usage is to return a sorry page to new users when it
7117 becomes certain they will get a degraded service. Note that in the event
7118 there would not be any active server anymore, we would consider twice the
7119 number of queued connections as the measured value. This is a fair estimate,
7120 as we expect one server to get back soon anyway, but we still prefer to send
7121 new traffic to another backend if in better shape. See also the "queue",
7122 "be_conn", and "be_sess_rate" criteria.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01007123
Willy Tarreaua36af912009-10-10 12:02:45 +02007124be_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007125be_conn(<backend>) <integer>
Willy Tarreaua36af912009-10-10 12:02:45 +02007126 Applies to the number of currently established connections on the backend,
7127 possibly including the connection being evaluated. If no backend name is
7128 specified, the current one is used. But it is also possible to check another
7129 backend. It can be used to use a specific farm when the nominal one is full.
7130 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007131
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007132be_id <integer>
7133 Applies to the backend's id. Can be used in frontends to check from which
7134 backend it was called.
7135
Willy Tarreaud63335a2010-02-26 12:56:52 +01007136be_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007137be_sess_rate(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007138 Returns true when the sessions creation rate on the backend matches the
7139 specified values or ranges, in number of new sessions per second. This is
7140 used to switch to an alternate backend when an expensive or fragile one
7141 reaches too high a session rate, or to limit abuse of service (eg. prevent
7142 sucking of an online dictionary).
7143
7144 Example :
7145 # Redirect to an error page if the dictionary is requested too often
7146 backend dynamic
7147 mode http
7148 acl being_scanned be_sess_rate gt 100
7149 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01007150
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007151connslots <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007152connslots(<backend>) <integer>
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007153 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02007154 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007155 usage; see "use_backend" keyword) can be redirected to a different backend.
7156
Willy Tarreau55165fe2009-05-10 12:02:55 +02007157 'connslots' = number of available server connection slots, + number of
7158 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007159
Willy Tarreaua36af912009-10-10 12:02:45 +02007160 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02007161 useful when you have a case of traffic going to one single ip, splitting into
7162 multiple backends (perhaps using acls to do name-based load balancing) and
7163 you want to be able to differentiate between different backends, and their
7164 available "connslots". Also, whereas "nbsrv" only measures servers that are
7165 actually *down*, this acl is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02007166 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007167
Willy Tarreau55165fe2009-05-10 12:02:55 +02007168 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
7169 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
7170 then this acl clearly does not make sense, in which case the value returned
7171 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007172
Willy Tarreaud63335a2010-02-26 12:56:52 +01007173dst <ip_address>
7174 Applies to the local IPv4 address the client connected to. It can be used to
7175 switch to a different backend for some alternative addresses.
Willy Tarreaua36af912009-10-10 12:02:45 +02007176
Willy Tarreaud63335a2010-02-26 12:56:52 +01007177dst_conn <integer>
7178 Applies to the number of currently established connections on the same socket
7179 including the one being evaluated. It can be used to either return a sorry
7180 page before hard-blocking, or to use a specific backend to drain new requests
7181 when the socket is considered saturated. This offers the ability to assign
7182 different limits to different listening ports or addresses. See also the
7183 "fe_conn" and "be_conn" criteria.
7184
7185dst_port <integer>
7186 Applies to the local port the client connected to. It can be used to switch
7187 to a different backend for some alternative ports.
7188
7189fe_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007190fe_conn(<frontend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007191 Applies to the number of currently established connections on the frontend,
7192 possibly including the connection being evaluated. If no frontend name is
7193 specified, the current one is used. But it is also possible to check another
7194 frontend. It can be used to either return a sorry page before hard-blocking,
7195 or to use a specific backend to drain new requests when the farm is
7196 considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
7197 criteria.
7198
7199fe_id <integer>
Cyril Bonté78caf842010-03-10 22:41:43 +01007200 Applies to the frontend's id. Can be used in backends to check from which
Willy Tarreaud63335a2010-02-26 12:56:52 +01007201 frontend it was called.
Willy Tarreaua36af912009-10-10 12:02:45 +02007202
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007203fe_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007204fe_sess_rate(<frontend>) <integer>
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007205 Returns true when the session creation rate on the current or the named
7206 frontend matches the specified values or ranges, expressed in new sessions
7207 per second. This is used to limit the connection rate to acceptable ranges in
7208 order to prevent abuse of service at the earliest moment. This can be
7209 combined with layer 4 ACLs in order to force the clients to wait a bit for
7210 the rate to go down below the limit.
7211
7212 Example :
7213 # This frontend limits incoming mails to 10/s with a max of 100
7214 # concurrent connections. We accept any connection below 10/s, and
7215 # force excess clients to wait for 100 ms. Since clients are limited to
7216 # 100 max, there cannot be more than 10 incoming mails per second.
7217 frontend mail
7218 bind :25
7219 mode tcp
7220 maxconn 100
7221 acl too_fast fe_sess_rate ge 10
7222 tcp-request inspect-delay 100ms
7223 tcp-request content accept if ! too_fast
7224 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01007225
Willy Tarreaud63335a2010-02-26 12:56:52 +01007226nbsrv <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007227nbsrv(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007228 Returns true when the number of usable servers of either the current backend
7229 or the named backend matches the values or ranges specified. This is used to
7230 switch to an alternate backend when the number of servers is too low to
7231 to handle some load. It is useful to report a failure when combined with
7232 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007233
Willy Tarreaud63335a2010-02-26 12:56:52 +01007234queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007235queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007236 Returns the total number of queued connections of the designated backend,
7237 including all the connections in server queues. If no backend name is
7238 specified, the current one is used, but it is also possible to check another
7239 one. This can be used to take actions when queuing goes above a known level,
7240 generally indicating a surge of traffic or a massive slowdown on the servers.
7241 One possible action could be to reject new users but still accept old ones.
7242 See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
7243
Willy Tarreaue9656522010-08-17 15:40:09 +02007244sc1_bytes_in_rate
7245sc2_bytes_in_rate
7246 Returns the average client-to-server bytes rate from the currently tracked
7247 counters, measured in amount of bytes over the period configured in the
7248 table. See also src_bytes_in_rate.
7249
7250sc1_bytes_out_rate
7251sc2_bytes_out_rate
7252 Returns the average server-to-client bytes rate from the currently tracked
7253 counters, measured in amount of bytes over the period configured in the
7254 table. See also src_bytes_out_rate.
7255
Willy Tarreauf73cd112011-08-13 01:45:16 +02007256sc1_clr_gpc0
7257sc2_clr_gpc0
7258 Clears the first General Purpose Counter associated to the currently tracked
7259 counters, and returns its previous value. Before the first invocation, the
7260 stored value is zero, so first invocation will always return zero. The test
7261 can also be used alone and always returns true. This is typically used as a
7262 second ACL in an expression in order to mark a connection when a first ACL
7263 was verified :
7264
7265 # block if 5 consecutive requests continue to come faster than 10 sess
7266 # per second, and reset the counter as soon as the traffic slows down.
7267 acl abuse sc1_http_req_rate gt 10
7268 acl kill sc1_inc_gpc0 gt 5
7269 acl save sc1_clr_gpc0
7270 tcp-request connection accept if !abuse save
7271 tcp-request connection reject if abuse kill
7272
Willy Tarreaue9656522010-08-17 15:40:09 +02007273sc1_conn_cnt
7274sc2_conn_cnt
7275 Returns the cumulated number of incoming connections from currently tracked
7276 counters. See also src_conn_cnt.
7277
7278sc1_conn_cur
7279sc2_conn_cur
7280 Returns the current amount of concurrent connections tracking the same
7281 tracked counters. This number is automatically incremented when tracking
7282 begins and decremented when tracking stops. See also src_conn_cur.
7283
7284sc1_conn_rate
7285sc2_conn_rate
7286 Returns the average connection rate from the currently tracked counters,
7287 measured in amount of connections over the period configured in the table.
7288 See also src_conn_rate.
7289
7290sc1_get_gpc0
7291sc2_get_gpc0
7292 Returns the value of the first General Purpose Counter associated to the
7293 currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0.
7294
7295sc1_http_err_cnt
7296sc2_http_err_cnt
7297 Returns the cumulated number of HTTP errors from the currently tracked
7298 counters. This includes the both request errors and 4xx error responses.
7299 See also src_http_err_cnt.
7300
7301sc1_http_err_rate
7302sc2_http_err_rate
7303 Returns the average rate of HTTP errors from the currently tracked counters,
7304 measured in amount of errors over the period configured in the table. This
7305 includes the both request errors and 4xx error responses. See also
7306 src_http_err_rate.
7307
7308sc1_http_req_cnt
7309sc2_http_req_cnt
7310 Returns the cumulated number of HTTP requests from the currently tracked
7311 counters. This includes every started request, valid or not. See also
7312 src_http_req_cnt.
7313
7314sc1_http_req_rate
7315sc2_http_req_rate
7316 Returns the average rate of HTTP requests from the currently tracked
7317 counters, measured in amount of requests over the period configured in
7318 the table. This includes every started request, valid or not. See also
7319 src_http_req_rate.
7320
7321sc1_inc_gpc0
7322sc2_inc_gpc0
7323 Increments the first General Purpose Counter associated to the currently
7324 tracked counters, and returns its value. Before the first invocation, the
7325 stored value is zero, so first invocation will increase it to 1 and will
7326 return 1. The test can also be used alone and always returns true. This is
7327 typically used as a second ACL in an expression in order to mark a connection
7328 when a first ACL was verified :
7329
7330 acl abuse sc1_http_req_rate gt 10
7331 acl kill sc1_inc_gpc0
7332 tcp-request connection reject if abuse kill
7333
7334sc1_kbytes_in
7335sc2_kbytes_in
7336 Returns the amount of client-to-server data from the currently tracked
7337 counters, measured in kilobytes over the period configured in the table. The
7338 test is currently performed on 32-bit integers, which limits values to 4
7339 terabytes. See also src_kbytes_in.
7340
7341sc1_kbytes_out
7342sc2_kbytes_out
7343 Returns the amount of server-to-client data from the currently tracked
7344 counters, measured in kilobytes over the period configured in the table. The
7345 test is currently performed on 32-bit integers, which limits values to 4
7346 terabytes. See also src_kbytes_out.
7347
7348sc1_sess_cnt
7349sc2_sess_cnt
7350 Returns the cumulated number of incoming connections that were transformed
7351 into sessions, which means that they were accepted by a "tcp-request
7352 connection" rule, from the currently tracked counters. A backend may count
7353 more sessions than connections because each connection could result in many
7354 backend sessions if some HTTP keep-alive is performend over the connection
7355 with the client. See also src_sess_cnt.
7356
7357sc1_sess_rate
7358sc2_sess_rate
7359 Returns the average session rate from the currently tracked counters,
7360 measured in amount of sessions over the period configured in the table. A
7361 session is a connection that got past the early "tcp-request connection"
7362 rules. A backend may count more sessions than connections because each
7363 connection could result in many backend sessions if some HTTP keep-alive is
7364 performend over the connection with the client. See also src_sess_rate.
7365
Willy Tarreaud63335a2010-02-26 12:56:52 +01007366so_id <integer>
7367 Applies to the socket's id. Useful in frontends with many bind keywords.
7368
7369src <ip_address>
7370 Applies to the client's IPv4 address. It is usually used to limit access to
7371 certain resources such as statistics. Note that it is the TCP-level source
7372 address which is used, and not the address of a client behind a proxy.
7373
Willy Tarreauc9705a12010-07-27 20:05:50 +02007374src_bytes_in_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007375src_bytes_in_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007376 Returns the average bytes rate from the connection's source IPv4 address in
7377 the current proxy's stick-table or in the designated stick-table, measured in
7378 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007379 not found, zero is returned. See also sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007380
7381src_bytes_out_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007382src_bytes_out_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007383 Returns the average bytes rate to the connection's source IPv4 address in the
7384 current proxy's stick-table or in the designated stick-table, measured in
7385 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007386 not found, zero is returned. See also sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007387
Willy Tarreauf73cd112011-08-13 01:45:16 +02007388src_clr_gpc0 <integer>
7389src_clr_gpc0(<table>) <integer>
7390 Clears the first General Purpose Counter associated to the connection's
7391 source IPv4 address in the current proxy's stick-table or in the designated
7392 stick-table, and returns its previous value. If the address is not found, an
7393 entry is created and 0 is returned. The test can also be used alone and
7394 always returns true. This is typically used as a second ACL in an expression
7395 in order to mark a connection when a first ACL was verified :
7396
7397 # block if 5 consecutive requests continue to come faster than 10 sess
7398 # per second, and reset the counter as soon as the traffic slows down.
7399 acl abuse src_http_req_rate gt 10
7400 acl kill src_inc_gpc0 gt 5
7401 acl save src_clr_gpc0
7402 tcp-request connection accept if !abuse save
7403 tcp-request connection reject if abuse kill
7404
Willy Tarreauc9705a12010-07-27 20:05:50 +02007405src_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007406src_conn_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007407 Returns the cumulated number of connections initiated from the current
7408 connection's source IPv4 address in the current proxy's stick-table or in
7409 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02007410 See also sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007411
7412src_conn_cur <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007413src_conn_cur(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007414 Returns the current amount of concurrent connections initiated from the
7415 current connection's source IPv4 address in the current proxy's stick-table
7416 or in the designated stick-table. If the address is not found, zero is
Willy Tarreaue9656522010-08-17 15:40:09 +02007417 returned. See also sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007418
7419src_conn_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007420src_conn_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007421 Returns the average connection rate from the connection's source IPv4 address
7422 in the current proxy's stick-table or in the designated stick-table, measured
7423 in amount of connections over the period configured in the table. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02007424 address is not found, zero is returned. See also sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007425
7426src_get_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007427src_get_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007428 Returns the value of the first General Purpose Counter associated to the
7429 connection's source IPv4 address in the current proxy's stick-table or in
7430 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02007431 See also sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007432
7433src_http_err_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007434src_http_err_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007435 Returns the cumulated number of HTTP errors from the current connection's
7436 source IPv4 address in the current proxy's stick-table or in the designated
7437 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreaue9656522010-08-17 15:40:09 +02007438 If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007439
7440src_http_err_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007441src_http_err_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007442 Returns the average rate of HTTP errors from the current connection's source
7443 IPv4 address in the current proxy's stick-table or in the designated stick-
7444 table, measured in amount of errors over the period configured in the table.
7445 This includes the both request errors and 4xx error responses. If the address
Willy Tarreaue9656522010-08-17 15:40:09 +02007446 is not found, zero is returned. See also sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007447
7448src_http_req_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007449src_http_req_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007450 Returns the cumulated number of HTTP requests from the current connection's
7451 source IPv4 address in the current proxy's stick-table or in the designated
7452 stick-table. This includes every started request, valid or not. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02007453 address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007454
7455src_http_req_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007456src_http_req_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007457 Returns the average rate of HTTP requests from the current connection's
7458 source IPv4 address in the current proxy's stick-table or in the designated
7459 stick-table, measured in amount of requests over the period configured in the
7460 table. This includes every started request, valid or not. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007461 not found, zero is returned. See also sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007462
7463src_inc_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007464src_inc_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007465 Increments the first General Purpose Counter associated to the connection's
7466 source IPv4 address in the current proxy's stick-table or in the designated
7467 stick-table, and returns its value. If the address is not found, an entry is
7468 created and 1 is returned. The test can also be used alone and always returns
7469 true. This is typically used as a second ACL in an expression in order to
7470 mark a connection when a first ACL was verified :
7471
7472 acl abuse src_http_req_rate gt 10
7473 acl kill src_inc_gpc0
Willy Tarreaue9656522010-08-17 15:40:09 +02007474 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02007475
7476src_kbytes_in <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007477src_kbytes_in(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007478 Returns the amount of data received from the connection's source IPv4 address
7479 in the current proxy's stick-table or in the designated stick-table, measured
7480 in kilobytes over the period configured in the table. If the address is not
7481 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02007482 which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007483
7484src_kbytes_out <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007485src_kbytes_out(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007486 Returns the amount of data sent to the connection's source IPv4 address in
7487 the current proxy's stick-table or in the designated stick-table, measured
7488 in kilobytes over the period configured in the table. If the address is not
7489 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02007490 which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007491
Willy Tarreaud63335a2010-02-26 12:56:52 +01007492src_port <integer>
7493 Applies to the client's TCP source port. This has a very limited usage.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007494
Willy Tarreauc9705a12010-07-27 20:05:50 +02007495src_sess_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007496src_sess_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007497 Returns the cumulated number of connections initiated from the current
7498 connection's source IPv4 address in the current proxy's stick-table or in the
7499 designated stick-table, that were transformed into sessions, which means that
7500 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreaue9656522010-08-17 15:40:09 +02007501 is returned. See also sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007502
7503src_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007504src_sess_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02007505 Returns the average session rate from the connection's source IPv4 address in
7506 the current proxy's stick-table or in the designated stick-table, measured in
7507 amount of sessions over the period configured in the table. A session is a
7508 connection that got past the early "tcp-request" rules. If the address is not
Willy Tarreaue9656522010-08-17 15:40:09 +02007509 found, zero is returned. See also sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007510
7511src_updt_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007512src_updt_conn_cnt(<table>) <integer>
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007513 Creates or updates the entry associated to the source IPv4 address in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02007514 current proxy's stick-table or in the designated stick-table. This table
7515 must be configured to store the "conn_cnt" data type, otherwise the match
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007516 will be ignored. The current count is incremented by one, and the expiration
7517 timer refreshed. The updated count is returned, so this match can't return
7518 zero. This is used to reject service abusers based on their source address.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007519 Note: it is recommended to use the more complete "track-counters" instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007520
7521 Example :
7522 # This frontend limits incoming SSH connections to 3 per 10 second for
7523 # each source address, and rejects excess connections until a 10 second
7524 # silence is observed. At most 20 addresses are tracked.
7525 listen ssh
7526 bind :22
7527 mode tcp
7528 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02007529 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007530 tcp-request content reject if { src_update_count gt 3 }
7531 server local 127.0.0.1:22
7532
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007533srv_conn(<backend>/<server>) <integer>
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +02007534 Applies to the number of currently established connections on the server,
7535 possibly including the connection being evaluated.
7536 It can be used to use a specific farm when one server is full.
7537 See also the "fe_conn", "be_conn" and "queue" criteria.
7538
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007539srv_id <integer>
7540 Applies to the server's id. Can be used in frontends or backends.
7541
Willy Tarreau0b1cd942010-05-16 22:18:27 +02007542srv_is_up(<server>)
7543srv_is_up(<backend>/<server>)
7544 Returns true when the designated server is UP, and false when it is either
7545 DOWN or in maintenance mode. If <backend> is omitted, then the server is
7546 looked up in the current backend. The function takes no arguments since it
7547 is used as a boolean. It is mainly used to take action based on an external
7548 status reported via a health check (eg: a geographical site's availability).
7549 Another possible use which is more of a hack consists in using dummy servers
7550 as boolean variables that can be enabled or disabled from the CLI, so that
7551 rules depending on those ACLs can be tweaked in realtime.
7552
Willy Tarreauc735a072011-03-29 00:57:02 +02007553table_avl <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007554table_avl(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02007555 Returns the total number of available entries in the current proxy's
7556 stick-table or in the designated stick-table. See also table_cnt.
7557
7558table_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007559table_cnt(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02007560 Returns the total number of entries currently in use in the current proxy's
7561 stick-table or in the designated stick-table. See also src_conn_cnt and
7562 table_avl for other entry counting methods.
7563
Willy Tarreau0ba27502007-12-24 16:55:16 +01007564
Willy Tarreaue9656522010-08-17 15:40:09 +020075657.5.2. Matching contents at Layer 4 (also called Layer 6)
7566---------------------------------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02007567
7568A second set of criteria depends on data found in buffers, but which can change
7569during analysis. This requires that some data has been buffered, for instance
Willy Tarreaue9656522010-08-17 15:40:09 +02007570through TCP request content inspection. Please see the "tcp-request content"
7571keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +02007572
7573req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02007574 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02007575 specified range. It is important to understand that this test does not
7576 return false as long as the buffer is changing. This means that a check with
7577 equality to zero will almost always immediately match at the beginning of the
7578 session, while a test for more data will wait for that data to come in and
7579 return false only when haproxy is certain that no more data will come in.
7580 This test was designed to be used with TCP request content inspection.
7581
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007582req_proto_http
7583 Returns true when data in the request buffer look like HTTP and correctly
7584 parses as such. It is the same parser as the common HTTP request parser which
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007585 is used so there should be no surprises. This test can be used for instance
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007586 to direct HTTP traffic to a given port and HTTPS traffic to another one
7587 using TCP request content inspection rules.
7588
Emeric Brunbede3d02009-06-30 17:54:00 +02007589req_rdp_cookie <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007590req_rdp_cookie(<name>) <string>
Emeric Brunbede3d02009-06-30 17:54:00 +02007591 Returns true when data in the request buffer look like the RDP protocol, and
7592 a cookie is present and equal to <string>. By default, any cookie name is
7593 checked, but a specific cookie name can be specified in parenthesis. The
7594 parser only checks for the first cookie, as illustrated in the RDP protocol
7595 specification. The cookie name is case insensitive. This ACL can be useful
7596 with the "MSTS" cookie, as it can contain the user name of the client
7597 connecting to the server if properly configured on the client. This can be
7598 used to restrict access to certain servers to certain users.
7599
7600req_rdp_cookie_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007601req_rdp_cookie_cnt(<name>) <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02007602 Returns true when the data in the request buffer look like the RDP protocol
7603 and the number of RDP cookies matches the specified range (typically zero or
7604 one). Optionally a specific cookie name can be checked. This is a simple way
7605 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
7606 cookies.
7607
Willy Tarreau62644772008-07-16 18:36:06 +02007608req_ssl_ver <decimal>
7609 Returns true when data in the request buffer look like SSL, with a protocol
7610 version matching the specified range. Both SSLv2 hello messages and SSLv3
7611 messages are supported. The test tries to be strict enough to avoid being
7612 easily fooled. In particular, it waits for as many bytes as announced in the
7613 message header if this header looks valid (bound to the buffer size). Note
7614 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
7615 with TCP request content inspection.
7616
Emeric Brun392d1d82010-09-24 15:45:16 +02007617req_ssl_hello_type <integer>
7618 Returns true when data in the request buffer looks like a complete SSL (v3
7619 or superior) hello message and handshake type is equal to <integer>.
7620 This test was designed to be used with TCP request content inspection: an
7621 SSL session ID may be fetched.
7622
7623rep_ssl_hello_type <integer>
7624 Returns true when data in the response buffer looks like a complete SSL (v3
7625 or superior) hello message and handshake type is equal to <integer>.
7626 This test was designed to be used with TCP response content inspection: a
7627 SSL session ID may be fetched.
7628
Willy Tarreaub6fb4202008-07-20 11:18:28 +02007629wait_end
7630 Waits for the end of the analysis period to return true. This may be used in
7631 conjunction with content analysis to avoid returning a wrong verdict early.
7632 It may also be used to delay some actions, such as a delayed reject for some
7633 special addresses. Since it either stops the rules evaluation or immediately
7634 returns true, it is recommended to use this acl as the last one in a rule.
7635 Please note that the default ACL "WAIT_END" is always usable without prior
7636 declaration. This test was designed to be used with TCP request content
7637 inspection.
7638
7639 Examples :
7640 # delay every incoming request by 2 seconds
7641 tcp-request inspect-delay 2s
7642 tcp-request content accept if WAIT_END
7643
7644 # don't immediately tell bad guys they are rejected
7645 tcp-request inspect-delay 10s
7646 acl goodguys src 10.0.0.0/24
7647 acl badguys src 10.0.1.0/24
7648 tcp-request content accept if goodguys
7649 tcp-request content reject if badguys WAIT_END
7650 tcp-request content reject
7651
Willy Tarreau62644772008-07-16 18:36:06 +02007652
Willy Tarreauc57f0e22009-05-10 13:12:33 +020076537.5.3. Matching at Layer 7
7654--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007655
Willy Tarreau62644772008-07-16 18:36:06 +02007656A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01007657application layer (layer 7). Those require that a full HTTP request has been
7658read, and are only evaluated then. They may require slightly more CPU resources
7659than the layer 4 ones, but not much since the request and response are indexed.
7660
Willy Tarreaud63335a2010-02-26 12:56:52 +01007661hdr <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007662hdr(<header>) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007663 Note: all the "hdr*" matching criteria either apply to all headers, or to a
7664 particular header whose name is passed between parenthesis and without any
7665 space. The header name is not case-sensitive. The header matching complies
7666 with RFC2616, and treats as separate headers all values delimited by commas.
7667 Use the shdr() variant for response headers sent by the server.
7668
7669 The "hdr" criteria returns true if any of the headers matching the criteria
7670 match any of the strings. This can be used to check exact for values. For
7671 instance, checking that "connection: close" is set :
7672
7673 hdr(Connection) -i close
7674
7675hdr_beg <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007676hdr_beg(<header>) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007677 Returns true when one of the headers begins with one of the strings. See
7678 "hdr" for more information on header matching. Use the shdr_beg() variant for
7679 response headers sent by the server.
7680
7681hdr_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007682hdr_cnt(<header>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007683 Returns true when the number of occurrence of the specified header matches
7684 the values or ranges specified. It is important to remember that one header
7685 line may count as several headers if it has several values. This is used to
7686 detect presence, absence or abuse of a specific header, as well as to block
7687 request smuggling attacks by rejecting requests which contain more than one
7688 of certain headers. See "hdr" for more information on header matching. Use
7689 the shdr_cnt() variant for response headers sent by the server.
7690
7691hdr_dir <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007692hdr_dir(<header>) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007693 Returns true when one of the headers contains one of the strings either
7694 isolated or delimited by slashes. This is used to perform filename or
7695 directory name matching, and may be used with Referer. See "hdr" for more
7696 information on header matching. Use the shdr_dir() variant for response
7697 headers sent by the server.
7698
7699hdr_dom <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007700hdr_dom(<header>) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007701 Returns true when one of the headers contains one of the strings either
7702 isolated or delimited by dots. This is used to perform domain name matching,
7703 and may be used with the Host header. See "hdr" for more information on
7704 header matching. Use the shdr_dom() variant for response headers sent by the
7705 server.
7706
7707hdr_end <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007708hdr_end(<header>) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007709 Returns true when one of the headers ends with one of the strings. See "hdr"
7710 for more information on header matching. Use the shdr_end() variant for
7711 response headers sent by the server.
7712
7713hdr_ip <ip_address>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007714hdr_ip(<header>) <ip_address>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007715 Returns true when one of the headers' values contains an IP address matching
7716 <ip_address>. This is mainly used with headers such as X-Forwarded-For or
7717 X-Client-IP. See "hdr" for more information on header matching. Use the
7718 shdr_ip() variant for response headers sent by the server.
7719
7720hdr_reg <regex>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007721hdr_reg(<header>) <regex>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007722 Returns true when one of the headers matches of the regular expressions. It
7723 can be used at any time, but it is important to remember that regex matching
7724 is slower than other methods. See also other "hdr_" criteria, as well as
7725 "hdr" for more information on header matching. Use the shdr_reg() variant for
7726 response headers sent by the server.
7727
7728hdr_sub <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007729hdr_sub(<header>) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007730 Returns true when one of the headers contains one of the strings. See "hdr"
7731 for more information on header matching. Use the shdr_sub() variant for
7732 response headers sent by the server.
7733
7734hdr_val <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007735hdr_val(<header>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007736 Returns true when one of the headers starts with a number which matches the
7737 values or ranges specified. This may be used to limit content-length to
7738 acceptable values for example. See "hdr" for more information on header
7739 matching. Use the shdr_val() variant for response headers sent by the server.
7740
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007741http_auth(<userlist>)
7742http_auth_group(<userlist>) <group> [<group>]*
Willy Tarreaud63335a2010-02-26 12:56:52 +01007743 Returns true when authentication data received from the client matches
7744 username & password stored on the userlist. It is also possible to
7745 use http_auth_group to check if the user is assigned to at least one
7746 of specified groups.
7747
7748 Currently only http basic auth is supported.
7749
Willy Tarreau7f18e522010-10-22 20:04:13 +02007750http_req_first
7751 Returns true when the request being processed is the first one of the
7752 connection. This can be used to add or remove headers that may be missing
7753 from some requests when a request is not the first one, or even to perform
7754 some specific ACL checks only on the first request.
7755
Willy Tarreau6a06a402007-07-15 20:15:28 +02007756method <string>
7757 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
7758 already check for most common methods.
7759
Willy Tarreau6a06a402007-07-15 20:15:28 +02007760path <string>
7761 Returns true when the path part of the request, which starts at the first
7762 slash and ends before the question mark, equals one of the strings. It may be
7763 used to match known files, such as /favicon.ico.
7764
7765path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007766 Returns true when the path begins with one of the strings. This can be used
7767 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007768
Willy Tarreau6a06a402007-07-15 20:15:28 +02007769path_dir <string>
7770 Returns true when one of the strings is found isolated or delimited with
7771 slashes in the path. This is used to perform filename or directory name
7772 matching without the risk of wrong match due to colliding prefixes. See also
7773 "url_dir" and "path_sub".
7774
7775path_dom <string>
7776 Returns true when one of the strings is found isolated or delimited with dots
7777 in the path. This may be used to perform domain name matching in proxy
7778 requests. See also "path_sub" and "url_dom".
7779
Willy Tarreaud63335a2010-02-26 12:56:52 +01007780path_end <string>
7781 Returns true when the path ends with one of the strings. This may be used to
7782 control file name extension.
7783
Willy Tarreau6a06a402007-07-15 20:15:28 +02007784path_reg <regex>
7785 Returns true when the path matches one of the regular expressions. It can be
7786 used any time, but it is important to remember that regex matching is slower
7787 than other methods. See also "url_reg" and all "path_" criteria.
7788
Willy Tarreaud63335a2010-02-26 12:56:52 +01007789path_sub <string>
7790 Returns true when the path contains one of the strings. It can be used to
7791 detect particular patterns in paths, such as "../" for example. See also
7792 "path_dir".
7793
7794req_ver <string>
7795 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
7796 ACL already check for versions 1.0 and 1.1.
7797
7798status <integer>
7799 Applies to the HTTP status code in the HTTP response, eg: "302". It can be
7800 used to act on responses depending on status ranges, for instance, remove
7801 any Location header if the response is not a 3xx.
7802
Willy Tarreau6a06a402007-07-15 20:15:28 +02007803url <string>
7804 Applies to the whole URL passed in the request. The only real use is to match
7805 "*", for which there already is a predefined ACL.
7806
7807url_beg <string>
7808 Returns true when the URL begins with one of the strings. This can be used to
7809 check whether a URL begins with a slash or with a protocol scheme.
7810
Willy Tarreau6a06a402007-07-15 20:15:28 +02007811url_dir <string>
7812 Returns true when one of the strings is found isolated or delimited with
7813 slashes in the URL. This is used to perform filename or directory name
7814 matching without the risk of wrong match due to colliding prefixes. See also
7815 "path_dir" and "url_sub".
7816
7817url_dom <string>
7818 Returns true when one of the strings is found isolated or delimited with dots
7819 in the URL. This is used to perform domain name matching without the risk of
7820 wrong match due to colliding prefixes. See also "url_sub".
7821
Willy Tarreaud63335a2010-02-26 12:56:52 +01007822url_end <string>
7823 Returns true when the URL ends with one of the strings. It has very limited
7824 use. "path_end" should be used instead for filename matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007825
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007826url_ip <ip_address>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007827 Applies to the IP address specified in the absolute URI in an HTTP request.
7828 It can be used to prevent access to certain resources such as local network.
Willy Tarreau198a7442008-01-17 12:05:32 +01007829 It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007830
7831url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007832 Applies to the port specified in the absolute URI in an HTTP request. It can
7833 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01007834 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01007835 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007836
Willy Tarreaud63335a2010-02-26 12:56:52 +01007837url_reg <regex>
7838 Returns true when the URL matches one of the regular expressions. It can be
7839 used any time, but it is important to remember that regex matching is slower
7840 than other methods. See also "path_reg" and all "url_" criteria.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007841
Willy Tarreaud63335a2010-02-26 12:56:52 +01007842url_sub <string>
7843 Returns true when the URL contains one of the strings. It can be used to
7844 detect particular patterns in query strings for example. See also "path_sub".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007845
Willy Tarreau198a7442008-01-17 12:05:32 +01007846
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078477.6. Pre-defined ACLs
7848---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007849
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007850Some predefined ACLs are hard-coded so that they do not have to be declared in
7851every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +02007852order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +01007853
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007854ACL name Equivalent to Usage
7855---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007856FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007857HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007858HTTP_1.0 req_ver 1.0 match HTTP version 1.0
7859HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +01007860HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
7861HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
7862HTTP_URL_SLASH url_beg / match URL beginning with "/"
7863HTTP_URL_STAR url * match URL equal to "*"
7864LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007865METH_CONNECT method CONNECT match HTTP CONNECT method
7866METH_GET method GET HEAD match HTTP GET or HEAD method
7867METH_HEAD method HEAD match HTTP HEAD method
7868METH_OPTIONS method OPTIONS match HTTP OPTIONS method
7869METH_POST method POST match HTTP POST method
7870METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +02007871RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007872REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +01007873TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007874WAIT_END wait_end wait for end of content analysis
7875---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007876
Willy Tarreauced27012008-01-17 20:35:34 +01007877
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078787.7. Using ACLs to form conditions
7879----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007880
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007881Some actions are only performed upon a valid condition. A condition is a
7882combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01007883
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007884 - AND (implicit)
7885 - OR (explicit with the "or" keyword or the "||" operator)
7886 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01007887
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007888A condition is formed as a disjunctive form:
Willy Tarreauced27012008-01-17 20:35:34 +01007889
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007890 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01007891
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007892Such conditions are generally used after an "if" or "unless" statement,
7893indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01007894
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007895For instance, to block HTTP requests to the "*" URL with methods other than
7896"OPTIONS", as well as POST requests without content-length, and GET or HEAD
7897requests with a content-length greater than 0, and finally every request which
7898is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01007899
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007900 acl missing_cl hdr_cnt(Content-length) eq 0
7901 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
7902 block if METH_GET HTTP_CONTENT
7903 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01007904
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007905To select a different backend for requests to static contents on the "www" site
7906and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01007907
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007908 acl url_static path_beg /static /images /img /css
7909 acl url_static path_end .gif .png .jpg .css .js
7910 acl host_www hdr_beg(host) -i www
7911 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01007912
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007913 # now use backend "static" for all static-only hosts, and for static urls
7914 # of host "www". Use backend "www" for the rest.
7915 use_backend static if host_static or host_www url_static
7916 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01007917
Willy Tarreau95fa4692010-02-01 13:05:50 +01007918It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
7919expressions that are built on the fly without needing to be declared. They must
7920be enclosed between braces, with a space before and after each brace (because
7921the braces must be seen as independant words). Example :
7922
7923 The following rule :
7924
7925 acl missing_cl hdr_cnt(Content-length) eq 0
7926 block if METH_POST missing_cl
7927
7928 Can also be written that way :
7929
7930 block if METH_POST { hdr_cnt(Content-length) eq 0 }
7931
7932It is generally not recommended to use this construct because it's a lot easier
7933to leave errors in the configuration when written that way. However, for very
7934simple rules matching only one source IP address for instance, it can make more
7935sense to use them than to declare ACLs with random names. Another example of
7936good use is the following :
7937
7938 With named ACLs :
7939
7940 acl site_dead nbsrv(dynamic) lt 2
7941 acl site_dead nbsrv(static) lt 2
7942 monitor fail if site_dead
7943
7944 With anonymous ACLs :
7945
7946 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
7947
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007948See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01007949
Willy Tarreau5764b382007-11-30 17:46:49 +01007950
Willy Tarreaub937b7e2010-01-12 15:27:54 +010079517.8. Pattern extraction
7952-----------------------
7953
7954The stickiness features relies on pattern extraction in the request and
7955response. Sometimes the data needs to be converted first before being stored,
7956for instance converted from ASCII to IP or upper case to lower case.
7957
7958All these operations of data extraction and conversion are defined as
7959"pattern extraction rules". A pattern rule always has the same format. It
7960begins with a single pattern fetch word, potentially followed by a list of
7961arguments within parenthesis then an optional list of transformations. As
7962much as possible, the pattern fetch functions use the same name as their
7963equivalent used in ACLs.
7964
7965The list of currently supported pattern fetch functions is the following :
7966
7967 src This is the source IPv4 address of the client of the session.
David du Colombier9a6d3c92011-03-17 10:40:24 +01007968 It is of type IPv4 and works on both IPv4 and IPv6 tables.
7969 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
7970 according to RFC 4291.
7971
7972 src6 This is the source IPv6 address of the client of the session.
7973 It is of type IPv6 and only works with such tables.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007974
7975 dst This is the destination IPv4 address of the session on the
7976 client side, which is the address the client connected to.
7977 It can be useful when running in transparent mode. It is of
David du Colombier9a6d3c92011-03-17 10:40:24 +01007978 type IPv4 and works on both IPv4 and IPv6 tables.
7979 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
7980 according to RFC 4291.
7981
7982 dst6 This is the destination IPv6 address of the session on the
7983 client side, which is the address the client connected to.
7984 It can be useful when running in transparent mode. It is of
Simon Hormandf791f52011-05-29 15:01:10 +09007985 type IPv6 and only works with such tables.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007986
7987 dst_port This is the destination TCP port of the session on the client
7988 side, which is the port the client connected to. This might be
7989 used when running in transparent mode or when assigning dynamic
7990 ports to some clients for a whole application session. It is of
7991 type integer and only works with such tables.
7992
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007993 hdr(<name>) This extracts the last occurrence of header <name> in an HTTP
Willy Tarreau4a568972010-05-12 08:08:50 +02007994 request and converts it to an IP address. This IP address is
7995 then used to match the table. A typical use is with the
7996 x-forwarded-for header.
7997
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007998 payload(<offset>,<length>)
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007999 This extracts a binary block of <length> bytes, and starting
8000 at bytes <offset> in the buffer of request or response (request
8001 on "stick on" or "stick match" or response in on "stick store
8002 response").
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008003
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008004 payload_lv(<offset1>,<length>[,<offset2>])
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008005 This extracts a binary block. In a first step the size of the
8006 block is read from response or request buffer at <offset>
8007 bytes and considered coded on <length> bytes. In a second step
8008 data of the block are read from buffer at <offset2> bytes
8009 (by default <lengthoffset> + <lengthsize>).
8010 If <offset2> is prefixed by '+' or '-', it is relative to
8011 <lengthoffset> + <lengthsize> else it is absolute.
8012 Ex: see SSL session id example in "stick table" chapter.
8013
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008014 url_param(<name>)
David Cournapeau16023ee2010-12-23 20:55:41 +09008015 This extracts the first occurrence of the parameter <name> in
Simon Hormandf791f52011-05-29 15:01:10 +09008016 the query string of the request and uses the corresponding value
David Cournapeau16023ee2010-12-23 20:55:41 +09008017 to match. A typical use is to get sticky session through url (e.g.
8018 http://example.com/foo?JESSIONID=some_id with
8019 url_param(JSESSIONID)), for cases where cookies cannot be used.
8020
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008021 rdp_cookie(<name>)
Simon Hormanab814e02011-06-24 14:50:20 +09008022 This extracts the value of the rdp cookie <name> as a string
8023 and uses this value to match. This enables implementation of
8024 persistence based on the mstshash cookie. This is typically
8025 done if there is no msts cookie present.
8026
8027 This differs from "balance rdp-cookie" in that any balancing
8028 algorithm may be used and thus the distribution of clients
8029 to backend servers is not linked to a hash of the RDP
8030 cookie. It is envisaged that using a balancing algorithm
8031 such as "balance roundrobin" or "balance leastconnect" will
8032 lead to a more even distribution of clients to backend
8033 servers than the hash used by "balance rdp-cookie".
8034
8035 Example :
8036 listen tse-farm
8037 bind 0.0.0.0:3389
8038 # wait up to 5s for an RDP cookie in the request
8039 tcp-request inspect-delay 5s
8040 tcp-request content accept if RDP_COOKIE
8041 # apply RDP cookie persistence
8042 persist rdp-cookie
8043 # Persist based on the mstshash cookie
8044 # This is only useful makes sense if
8045 # balance rdp-cookie is not used
8046 stick-table type string size 204800
8047 stick on rdp_cookie(mstshash)
8048 server srv1 1.1.1.1:3389
8049 server srv1 1.1.1.2:3389
8050
8051 See also : "balance rdp-cookie", "persist rdp-cookie",
8052 "tcp-request" and the "req_rdp_cookie" ACL.
8053
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008054 cookie(<name>)
Willy Tarreaub3eb2212011-07-01 16:16:17 +02008055 This extracts the last occurrence of the cookie name <name> on a
8056 "Cookie" header line from the request and uses the corresponding
8057 value to match. A typical use is to get multiple clients sharing
8058 a same profile use the same server. This can be similar to what
8059 "appsession" does with the "request-learn" statement, but with
8060 support for multi-peer synchronization and state keeping across
8061 restarts.
8062
8063 See also : "appsession"
8064
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008065 set-cookie(<name>)
Willy Tarreaub3eb2212011-07-01 16:16:17 +02008066 This extracts the last occurrence of the cookie name <name> on a
8067 "Set-Cookie" header line from the response and uses the
8068 corresponding value to match. This can be comparable to what
8069 "appsession" does with default options, but with support for
8070 multi-peer synchronization and state keeping across restarts.
8071
8072 See also : "appsession"
8073
Simon Hormanab814e02011-06-24 14:50:20 +09008074
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008075The currently available list of transformations include :
8076
8077 lower Convert a string pattern to lower case. This can only be placed
8078 after a string pattern fetch function or after a conversion
8079 function returning a string type. The result is of type string.
8080
8081 upper Convert a string pattern to upper case. This can only be placed
8082 after a string pattern fetch function or after a conversion
8083 function returning a string type. The result is of type string.
8084
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008085 ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for lookups
Willy Tarreaud31d6eb2010-01-26 18:01:41 +01008086 and storage. This can be used to make all hosts within a
8087 certain mask to share the same table entries and as such use
8088 the same server. The mask can be passed in dotted form (eg:
8089 255.255.255.0) or in CIDR form (eg: 24).
8090
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008091
Willy Tarreauc57f0e22009-05-10 13:12:33 +020080928. Logging
8093----------
Willy Tarreau844e3c52008-01-11 16:28:18 +01008094
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008095One of HAProxy's strong points certainly lies is its precise logs. It probably
8096provides the finest level of information available for such a product, which is
8097very important for troubleshooting complex environments. Standard information
8098provided in logs include client ports, TCP/HTTP state timers, precise session
8099state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008100to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008101headers.
8102
8103In order to improve administrators reactivity, it offers a great transparency
8104about encountered problems, both internal and external, and it is possible to
8105send logs to different sources at the same time with different level filters :
8106
8107 - global process-level logs (system errors, start/stop, etc..)
8108 - per-instance system and internal errors (lack of resource, bugs, ...)
8109 - per-instance external troubles (servers up/down, max connections)
8110 - per-instance activity (client connections), either at the establishment or
8111 at the termination.
8112
8113The ability to distribute different levels of logs to different log servers
8114allow several production teams to interact and to fix their problems as soon
8115as possible. For example, the system team might monitor system-wide errors,
8116while the application team might be monitoring the up/down for their servers in
8117real time, and the security team might analyze the activity logs with one hour
8118delay.
8119
8120
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081218.1. Log levels
8122---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008123
Simon Hormandf791f52011-05-29 15:01:10 +09008124TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008125source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +09008126HTTP request, HTTP return code, number of bytes transmitted, conditions
8127in which the session ended, and even exchanged cookies values. For example
8128track a particular user's problems. All messages may be sent to up to two
8129syslog servers. Check the "log" keyword in section 4.2 for more information
8130about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008131
8132
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081338.2. Log formats
8134----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008135
Emeric Brun3a058f32009-06-30 18:26:00 +02008136HAProxy supports 4 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +09008137and will be detailed in the following sections. A few of them may vary
8138slightly with the configuration, due to indicators specific to certain
8139options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008140
8141 - the default format, which is very basic and very rarely used. It only
8142 provides very basic information about the incoming connection at the moment
8143 it is accepted : source IP:port, destination IP:port, and frontend-name.
8144 This mode will eventually disappear so it will not be described to great
8145 extents.
8146
8147 - the TCP format, which is more advanced. This format is enabled when "option
8148 tcplog" is set on the frontend. HAProxy will then usually wait for the
8149 connection to terminate before logging. This format provides much richer
8150 information, such as timers, connection counts, queue size, etc... This
8151 format is recommended for pure TCP proxies.
8152
8153 - the HTTP format, which is the most advanced for HTTP proxying. This format
8154 is enabled when "option httplog" is set on the frontend. It provides the
8155 same information as the TCP format with some HTTP-specific fields such as
8156 the request, the status code, and captures of headers and cookies. This
8157 format is recommended for HTTP proxies.
8158
Emeric Brun3a058f32009-06-30 18:26:00 +02008159 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
8160 fields arranged in the same order as the CLF format. In this mode, all
8161 timers, captures, flags, etc... appear one per field after the end of the
8162 common fields, in the same order they appear in the standard HTTP format.
8163
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008164Next sections will go deeper into details for each of these formats. Format
8165specification will be performed on a "field" basis. Unless stated otherwise, a
8166field is a portion of text delimited by any number of spaces. Since syslog
8167servers are susceptible of inserting fields at the beginning of a line, it is
8168always assumed that the first field is the one containing the process name and
8169identifier.
8170
8171Note : Since log lines may be quite long, the log examples in sections below
8172 might be broken into multiple lines. The example log lines will be
8173 prefixed with 3 closing angle brackets ('>>>') and each time a log is
8174 broken into multiple lines, each non-final line will end with a
8175 backslash ('\') and the next line will start indented by two characters.
8176
8177
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081788.2.1. Default log format
8179-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008180
8181This format is used when no specific option is set. The log is emitted as soon
8182as the connection is accepted. One should note that this currently is the only
8183format which logs the request's destination IP and ports.
8184
8185 Example :
8186 listen www
8187 mode http
8188 log global
8189 server srv1 127.0.0.1:8000
8190
8191 >>> Feb 6 12:12:09 localhost \
8192 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
8193 (www/HTTP)
8194
8195 Field Format Extract from the example above
8196 1 process_name '[' pid ']:' haproxy[14385]:
8197 2 'Connect from' Connect from
8198 3 source_ip ':' source_port 10.0.1.2:33312
8199 4 'to' to
8200 5 destination_ip ':' destination_port 10.0.3.31:8012
8201 6 '(' frontend_name '/' mode ')' (www/HTTP)
8202
8203Detailed fields description :
8204 - "source_ip" is the IP address of the client which initiated the connection.
8205 - "source_port" is the TCP port of the client which initiated the connection.
8206 - "destination_ip" is the IP address the client connected to.
8207 - "destination_port" is the TCP port the client connected to.
8208 - "frontend_name" is the name of the frontend (or listener) which received
8209 and processed the connection.
8210 - "mode is the mode the frontend is operating (TCP or HTTP).
8211
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008212In case of a UNIX socket, the source and destination addresses are marked as
8213"unix:" and the ports reflect the internal ID of the socket which accepted the
8214connection (the same ID as reported in the stats).
8215
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008216It is advised not to use this deprecated format for newer installations as it
8217will eventually disappear.
8218
8219
Willy Tarreauc57f0e22009-05-10 13:12:33 +020082208.2.2. TCP log format
8221---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008222
8223The TCP format is used when "option tcplog" is specified in the frontend, and
8224is the recommended format for pure TCP proxies. It provides a lot of precious
8225information for troubleshooting. Since this format includes timers and byte
8226counts, the log is normally emitted at the end of the session. It can be
8227emitted earlier if "option logasap" is specified, which makes sense in most
8228environments with long sessions such as remote terminals. Sessions which match
8229the "monitor" rules are never logged. It is also possible not to emit logs for
8230sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008231specifying "option dontlognull" in the frontend. Successful connections will
8232not be logged if "option dontlog-normal" is specified in the frontend. A few
8233fields may slightly vary depending on some configuration options, those are
8234marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008235
8236 Example :
8237 frontend fnt
8238 mode tcp
8239 option tcplog
8240 log global
8241 default_backend bck
8242
8243 backend bck
8244 server srv1 127.0.0.1:8000
8245
8246 >>> Feb 6 12:12:56 localhost \
8247 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
8248 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
8249
8250 Field Format Extract from the example above
8251 1 process_name '[' pid ']:' haproxy[14387]:
8252 2 client_ip ':' client_port 10.0.1.2:33313
8253 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
8254 4 frontend_name fnt
8255 5 backend_name '/' server_name bck/srv1
8256 6 Tw '/' Tc '/' Tt* 0/0/5007
8257 7 bytes_read* 212
8258 8 termination_state --
8259 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
8260 10 srv_queue '/' backend_queue 0/0
8261
8262Detailed fields description :
8263 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008264 connection to haproxy. If the connection was accepted on a UNIX socket
8265 instead, the IP address would be replaced with the word "unix". Note that
8266 when the connection is accepted on a socket configured with "accept-proxy"
8267 and the PROXY protocol is correctly used, then the logs will reflect the
8268 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008269
8270 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008271 If the connection was accepted on a UNIX socket instead, the port would be
8272 replaced with the ID of the accepting socket, which is also reported in the
8273 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008274
8275 - "accept_date" is the exact date when the connection was received by haproxy
8276 (which might be very slightly different from the date observed on the
8277 network if there was some queuing in the system's backlog). This is usually
8278 the same date which may appear in any upstream firewall's log.
8279
8280 - "frontend_name" is the name of the frontend (or listener) which received
8281 and processed the connection.
8282
8283 - "backend_name" is the name of the backend (or listener) which was selected
8284 to manage the connection to the server. This will be the same as the
8285 frontend if no switching rule has been applied, which is common for TCP
8286 applications.
8287
8288 - "server_name" is the name of the last server to which the connection was
8289 sent, which might differ from the first one if there were connection errors
8290 and a redispatch occurred. Note that this server belongs to the backend
8291 which processed the request. If the connection was aborted before reaching
8292 a server, "<NOSRV>" is indicated instead of a server name.
8293
8294 - "Tw" is the total time in milliseconds spent waiting in the various queues.
8295 It can be "-1" if the connection was aborted before reaching the queue.
8296 See "Timers" below for more details.
8297
8298 - "Tc" is the total time in milliseconds spent waiting for the connection to
8299 establish to the final server, including retries. It can be "-1" if the
8300 connection was aborted before a connection could be established. See
8301 "Timers" below for more details.
8302
8303 - "Tt" is the total time in milliseconds elapsed between the accept and the
8304 last close. It covers all possible processings. There is one exception, if
8305 "option logasap" was specified, then the time counting stops at the moment
8306 the log is emitted. In this case, a '+' sign is prepended before the value,
8307 indicating that the final one will be larger. See "Timers" below for more
8308 details.
8309
8310 - "bytes_read" is the total number of bytes transmitted from the server to
8311 the client when the log is emitted. If "option logasap" is specified, the
8312 this value will be prefixed with a '+' sign indicating that the final one
8313 may be larger. Please note that this value is a 64-bit counter, so log
8314 analysis tools must be able to handle it without overflowing.
8315
8316 - "termination_state" is the condition the session was in when the session
8317 ended. This indicates the session state, which side caused the end of
8318 session to happen, and for what reason (timeout, error, ...). The normal
8319 flags should be "--", indicating the session was closed by either end with
8320 no data remaining in buffers. See below "Session state at disconnection"
8321 for more details.
8322
8323 - "actconn" is the total number of concurrent connections on the process when
8324 the session was logged. It it useful to detect when some per-process system
8325 limits have been reached. For instance, if actconn is close to 512 when
8326 multiple connection errors occur, chances are high that the system limits
8327 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008328 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008329
8330 - "feconn" is the total number of concurrent connections on the frontend when
8331 the session was logged. It is useful to estimate the amount of resource
8332 required to sustain high loads, and to detect when the frontend's "maxconn"
8333 has been reached. Most often when this value increases by huge jumps, it is
8334 because there is congestion on the backend servers, but sometimes it can be
8335 caused by a denial of service attack.
8336
8337 - "beconn" is the total number of concurrent connections handled by the
8338 backend when the session was logged. It includes the total number of
8339 concurrent connections active on servers as well as the number of
8340 connections pending in queues. It is useful to estimate the amount of
8341 additional servers needed to support high loads for a given application.
8342 Most often when this value increases by huge jumps, it is because there is
8343 congestion on the backend servers, but sometimes it can be caused by a
8344 denial of service attack.
8345
8346 - "srv_conn" is the total number of concurrent connections still active on
8347 the server when the session was logged. It can never exceed the server's
8348 configured "maxconn" parameter. If this value is very often close or equal
8349 to the server's "maxconn", it means that traffic regulation is involved a
8350 lot, meaning that either the server's maxconn value is too low, or that
8351 there aren't enough servers to process the load with an optimal response
8352 time. When only one of the server's "srv_conn" is high, it usually means
8353 that this server has some trouble causing the connections to take longer to
8354 be processed than on other servers.
8355
8356 - "retries" is the number of connection retries experienced by this session
8357 when trying to connect to the server. It must normally be zero, unless a
8358 server is being stopped at the same moment the connection was attempted.
8359 Frequent retries generally indicate either a network problem between
8360 haproxy and the server, or a misconfigured system backlog on the server
8361 preventing new connections from being queued. This field may optionally be
8362 prefixed with a '+' sign, indicating that the session has experienced a
8363 redispatch after the maximal retry count has been reached on the initial
8364 server. In this case, the server name appearing in the log is the one the
8365 connection was redispatched to, and not the first one, though both may
8366 sometimes be the same in case of hashing for instance. So as a general rule
8367 of thumb, when a '+' is present in front of the retry count, this count
8368 should not be attributed to the logged server.
8369
8370 - "srv_queue" is the total number of requests which were processed before
8371 this one in the server queue. It is zero when the request has not gone
8372 through the server queue. It makes it possible to estimate the approximate
8373 server's response time by dividing the time spent in queue by the number of
8374 requests in the queue. It is worth noting that if a session experiences a
8375 redispatch and passes through two server queues, their positions will be
8376 cumulated. A request should not pass through both the server queue and the
8377 backend queue unless a redispatch occurs.
8378
8379 - "backend_queue" is the total number of requests which were processed before
8380 this one in the backend's global queue. It is zero when the request has not
8381 gone through the global queue. It makes it possible to estimate the average
8382 queue length, which easily translates into a number of missing servers when
8383 divided by a server's "maxconn" parameter. It is worth noting that if a
8384 session experiences a redispatch, it may pass twice in the backend's queue,
8385 and then both positions will be cumulated. A request should not pass
8386 through both the server queue and the backend queue unless a redispatch
8387 occurs.
8388
8389
Willy Tarreauc57f0e22009-05-10 13:12:33 +020083908.2.3. HTTP log format
8391----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008392
8393The HTTP format is the most complete and the best suited for HTTP proxies. It
8394is enabled by when "option httplog" is specified in the frontend. It provides
8395the same level of information as the TCP format with additional features which
8396are specific to the HTTP protocol. Just like the TCP format, the log is usually
8397emitted at the end of the session, unless "option logasap" is specified, which
8398generally only makes sense for download sites. A session which matches the
8399"monitor" rules will never logged. It is also possible not to log sessions for
8400which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008401frontend. Successful connections will not be logged if "option dontlog-normal"
8402is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008403
8404Most fields are shared with the TCP log, some being different. A few fields may
8405slightly vary depending on some configuration options. Those ones are marked
8406with a star ('*') after the field name below.
8407
8408 Example :
8409 frontend http-in
8410 mode http
8411 option httplog
8412 log global
8413 default_backend bck
8414
8415 backend static
8416 server srv1 127.0.0.1:8000
8417
8418 >>> Feb 6 12:14:14 localhost \
8419 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
8420 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 +01008421 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008422
8423 Field Format Extract from the example above
8424 1 process_name '[' pid ']:' haproxy[14389]:
8425 2 client_ip ':' client_port 10.0.1.2:33317
8426 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
8427 4 frontend_name http-in
8428 5 backend_name '/' server_name static/srv1
8429 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
8430 7 status_code 200
8431 8 bytes_read* 2750
8432 9 captured_request_cookie -
8433 10 captured_response_cookie -
8434 11 termination_state ----
8435 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
8436 13 srv_queue '/' backend_queue 0/0
8437 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
8438 15 '{' captured_response_headers* '}' {}
8439 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +01008440
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008441
8442Detailed fields description :
8443 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008444 connection to haproxy. If the connection was accepted on a UNIX socket
8445 instead, the IP address would be replaced with the word "unix". Note that
8446 when the connection is accepted on a socket configured with "accept-proxy"
8447 and the PROXY protocol is correctly used, then the logs will reflect the
8448 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008449
8450 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008451 If the connection was accepted on a UNIX socket instead, the port would be
8452 replaced with the ID of the accepting socket, which is also reported in the
8453 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008454
8455 - "accept_date" is the exact date when the TCP connection was received by
8456 haproxy (which might be very slightly different from the date observed on
8457 the network if there was some queuing in the system's backlog). This is
8458 usually the same date which may appear in any upstream firewall's log. This
8459 does not depend on the fact that the client has sent the request or not.
8460
8461 - "frontend_name" is the name of the frontend (or listener) which received
8462 and processed the connection.
8463
8464 - "backend_name" is the name of the backend (or listener) which was selected
8465 to manage the connection to the server. This will be the same as the
8466 frontend if no switching rule has been applied.
8467
8468 - "server_name" is the name of the last server to which the connection was
8469 sent, which might differ from the first one if there were connection errors
8470 and a redispatch occurred. Note that this server belongs to the backend
8471 which processed the request. If the request was aborted before reaching a
8472 server, "<NOSRV>" is indicated instead of a server name. If the request was
8473 intercepted by the stats subsystem, "<STATS>" is indicated instead.
8474
8475 - "Tq" is the total time in milliseconds spent waiting for the client to send
8476 a full HTTP request, not counting data. It can be "-1" if the connection
8477 was aborted before a complete request could be received. It should always
8478 be very small because a request generally fits in one single packet. Large
8479 times here generally indicate network trouble between the client and
8480 haproxy. See "Timers" below for more details.
8481
8482 - "Tw" is the total time in milliseconds spent waiting in the various queues.
8483 It can be "-1" if the connection was aborted before reaching the queue.
8484 See "Timers" below for more details.
8485
8486 - "Tc" is the total time in milliseconds spent waiting for the connection to
8487 establish to the final server, including retries. It can be "-1" if the
8488 request was aborted before a connection could be established. See "Timers"
8489 below for more details.
8490
8491 - "Tr" is the total time in milliseconds spent waiting for the server to send
8492 a full HTTP response, not counting data. It can be "-1" if the request was
8493 aborted before a complete response could be received. It generally matches
8494 the server's processing time for the request, though it may be altered by
8495 the amount of data sent by the client to the server. Large times here on
8496 "GET" requests generally indicate an overloaded server. See "Timers" below
8497 for more details.
8498
8499 - "Tt" is the total time in milliseconds elapsed between the accept and the
8500 last close. It covers all possible processings. There is one exception, if
8501 "option logasap" was specified, then the time counting stops at the moment
8502 the log is emitted. In this case, a '+' sign is prepended before the value,
8503 indicating that the final one will be larger. See "Timers" below for more
8504 details.
8505
8506 - "status_code" is the HTTP status code returned to the client. This status
8507 is generally set by the server, but it might also be set by haproxy when
8508 the server cannot be reached or when its response is blocked by haproxy.
8509
8510 - "bytes_read" is the total number of bytes transmitted to the client when
8511 the log is emitted. This does include HTTP headers. If "option logasap" is
8512 specified, the this value will be prefixed with a '+' sign indicating that
8513 the final one may be larger. Please note that this value is a 64-bit
8514 counter, so log analysis tools must be able to handle it without
8515 overflowing.
8516
8517 - "captured_request_cookie" is an optional "name=value" entry indicating that
8518 the client had this cookie in the request. The cookie name and its maximum
8519 length are defined by the "capture cookie" statement in the frontend
8520 configuration. The field is a single dash ('-') when the option is not
8521 set. Only one cookie may be captured, it is generally used to track session
8522 ID exchanges between a client and a server to detect session crossing
8523 between clients due to application bugs. For more details, please consult
8524 the section "Capturing HTTP headers and cookies" below.
8525
8526 - "captured_response_cookie" is an optional "name=value" entry indicating
8527 that the server has returned a cookie with its response. The cookie name
8528 and its maximum length are defined by the "capture cookie" statement in the
8529 frontend configuration. The field is a single dash ('-') when the option is
8530 not set. Only one cookie may be captured, it is generally used to track
8531 session ID exchanges between a client and a server to detect session
8532 crossing between clients due to application bugs. For more details, please
8533 consult the section "Capturing HTTP headers and cookies" below.
8534
8535 - "termination_state" is the condition the session was in when the session
8536 ended. This indicates the session state, which side caused the end of
8537 session to happen, for what reason (timeout, error, ...), just like in TCP
8538 logs, and information about persistence operations on cookies in the last
8539 two characters. The normal flags should begin with "--", indicating the
8540 session was closed by either end with no data remaining in buffers. See
8541 below "Session state at disconnection" for more details.
8542
8543 - "actconn" is the total number of concurrent connections on the process when
8544 the session was logged. It it useful to detect when some per-process system
8545 limits have been reached. For instance, if actconn is close to 512 or 1024
8546 when multiple connection errors occur, chances are high that the system
8547 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008548 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008549 system.
8550
8551 - "feconn" is the total number of concurrent connections on the frontend when
8552 the session was logged. It is useful to estimate the amount of resource
8553 required to sustain high loads, and to detect when the frontend's "maxconn"
8554 has been reached. Most often when this value increases by huge jumps, it is
8555 because there is congestion on the backend servers, but sometimes it can be
8556 caused by a denial of service attack.
8557
8558 - "beconn" is the total number of concurrent connections handled by the
8559 backend when the session was logged. It includes the total number of
8560 concurrent connections active on servers as well as the number of
8561 connections pending in queues. It is useful to estimate the amount of
8562 additional servers needed to support high loads for a given application.
8563 Most often when this value increases by huge jumps, it is because there is
8564 congestion on the backend servers, but sometimes it can be caused by a
8565 denial of service attack.
8566
8567 - "srv_conn" is the total number of concurrent connections still active on
8568 the server when the session was logged. It can never exceed the server's
8569 configured "maxconn" parameter. If this value is very often close or equal
8570 to the server's "maxconn", it means that traffic regulation is involved a
8571 lot, meaning that either the server's maxconn value is too low, or that
8572 there aren't enough servers to process the load with an optimal response
8573 time. When only one of the server's "srv_conn" is high, it usually means
8574 that this server has some trouble causing the requests to take longer to be
8575 processed than on other servers.
8576
8577 - "retries" is the number of connection retries experienced by this session
8578 when trying to connect to the server. It must normally be zero, unless a
8579 server is being stopped at the same moment the connection was attempted.
8580 Frequent retries generally indicate either a network problem between
8581 haproxy and the server, or a misconfigured system backlog on the server
8582 preventing new connections from being queued. This field may optionally be
8583 prefixed with a '+' sign, indicating that the session has experienced a
8584 redispatch after the maximal retry count has been reached on the initial
8585 server. In this case, the server name appearing in the log is the one the
8586 connection was redispatched to, and not the first one, though both may
8587 sometimes be the same in case of hashing for instance. So as a general rule
8588 of thumb, when a '+' is present in front of the retry count, this count
8589 should not be attributed to the logged server.
8590
8591 - "srv_queue" is the total number of requests which were processed before
8592 this one in the server queue. It is zero when the request has not gone
8593 through the server queue. It makes it possible to estimate the approximate
8594 server's response time by dividing the time spent in queue by the number of
8595 requests in the queue. It is worth noting that if a session experiences a
8596 redispatch and passes through two server queues, their positions will be
8597 cumulated. A request should not pass through both the server queue and the
8598 backend queue unless a redispatch occurs.
8599
8600 - "backend_queue" is the total number of requests which were processed before
8601 this one in the backend's global queue. It is zero when the request has not
8602 gone through the global queue. It makes it possible to estimate the average
8603 queue length, which easily translates into a number of missing servers when
8604 divided by a server's "maxconn" parameter. It is worth noting that if a
8605 session experiences a redispatch, it may pass twice in the backend's queue,
8606 and then both positions will be cumulated. A request should not pass
8607 through both the server queue and the backend queue unless a redispatch
8608 occurs.
8609
8610 - "captured_request_headers" is a list of headers captured in the request due
8611 to the presence of the "capture request header" statement in the frontend.
8612 Multiple headers can be captured, they will be delimited by a vertical bar
8613 ('|'). When no capture is enabled, the braces do not appear, causing a
8614 shift of remaining fields. It is important to note that this field may
8615 contain spaces, and that using it requires a smarter log parser than when
8616 it's not used. Please consult the section "Capturing HTTP headers and
8617 cookies" below for more details.
8618
8619 - "captured_response_headers" is a list of headers captured in the response
8620 due to the presence of the "capture response header" statement in the
8621 frontend. Multiple headers can be captured, they will be delimited by a
8622 vertical bar ('|'). When no capture is enabled, the braces do not appear,
8623 causing a shift of remaining fields. It is important to note that this
8624 field may contain spaces, and that using it requires a smarter log parser
8625 than when it's not used. Please consult the section "Capturing HTTP headers
8626 and cookies" below for more details.
8627
8628 - "http_request" is the complete HTTP request line, including the method,
8629 request and HTTP version string. Non-printable characters are encoded (see
8630 below the section "Non-printable characters"). This is always the last
8631 field, and it is always delimited by quotes and is the only one which can
8632 contain quotes. If new fields are added to the log format, they will be
8633 added before this field. This field might be truncated if the request is
8634 huge and does not fit in the standard syslog buffer (1024 characters). This
8635 is the reason why this field must always remain the last one.
8636
8637
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086388.3. Advanced logging options
8639-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008640
8641Some advanced logging options are often looked for but are not easy to find out
8642just by looking at the various options. Here is an entry point for the few
8643options which can enable better logging. Please refer to the keywords reference
8644for more information about their usage.
8645
8646
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086478.3.1. Disabling logging of external tests
8648------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008649
8650It is quite common to have some monitoring tools perform health checks on
8651haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
8652commercial load-balancer, and sometimes it will simply be a more complete
8653monitoring system such as Nagios. When the tests are very frequent, users often
8654ask how to disable logging for those checks. There are three possibilities :
8655
8656 - if connections come from everywhere and are just TCP probes, it is often
8657 desired to simply disable logging of connections without data exchange, by
8658 setting "option dontlognull" in the frontend. It also disables logging of
8659 port scans, which may or may not be desired.
8660
8661 - if the connection come from a known source network, use "monitor-net" to
8662 declare this network as monitoring only. Any host in this network will then
8663 only be able to perform health checks, and their requests will not be
8664 logged. This is generally appropriate to designate a list of equipments
8665 such as other load-balancers.
8666
8667 - if the tests are performed on a known URI, use "monitor-uri" to declare
8668 this URI as dedicated to monitoring. Any host sending this request will
8669 only get the result of a health-check, and the request will not be logged.
8670
8671
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086728.3.2. Logging before waiting for the session to terminate
8673----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008674
8675The problem with logging at end of connection is that you have no clue about
8676what is happening during very long sessions, such as remote terminal sessions
8677or large file downloads. This problem can be worked around by specifying
8678"option logasap" in the frontend. Haproxy will then log as soon as possible,
8679just before data transfer begins. This means that in case of TCP, it will still
8680log the connection status to the server, and in case of HTTP, it will log just
8681after processing the server headers. In this case, the number of bytes reported
8682is the number of header bytes sent to the client. In order to avoid confusion
8683with normal logs, the total time field and the number of bytes are prefixed
8684with a '+' sign which means that real numbers are certainly larger.
8685
8686
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086878.3.3. Raising log level upon errors
8688------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008689
8690Sometimes it is more convenient to separate normal traffic from errors logs,
8691for instance in order to ease error monitoring from log files. When the option
8692"log-separate-errors" is used, connections which experience errors, timeouts,
8693retries, redispatches or HTTP status codes 5xx will see their syslog level
8694raised from "info" to "err". This will help a syslog daemon store the log in
8695a separate file. It is very important to keep the errors in the normal traffic
8696file too, so that log ordering is not altered. You should also be careful if
8697you already have configured your syslog daemon to store all logs higher than
8698"notice" in an "admin" file, because the "err" level is higher than "notice".
8699
8700
Willy Tarreauc57f0e22009-05-10 13:12:33 +020087018.3.4. Disabling logging of successful connections
8702--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008703
8704Although this may sound strange at first, some large sites have to deal with
8705multiple thousands of logs per second and are experiencing difficulties keeping
8706them intact for a long time or detecting errors within them. If the option
8707"dontlog-normal" is set on the frontend, all normal connections will not be
8708logged. In this regard, a normal connection is defined as one without any
8709error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
8710and a response with a status 5xx is not considered normal and will be logged
8711too. Of course, doing is is really discouraged as it will remove most of the
8712useful information from the logs. Do this only if you have no other
8713alternative.
8714
8715
Willy Tarreauc57f0e22009-05-10 13:12:33 +020087168.4. Timing events
8717------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008718
8719Timers provide a great help in troubleshooting network problems. All values are
8720reported in milliseconds (ms). These timers should be used in conjunction with
8721the session termination flags. In TCP mode with "option tcplog" set on the
8722frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
8723mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
8724
8725 - Tq: total time to get the client request (HTTP mode only). It's the time
8726 elapsed between the moment the client connection was accepted and the
8727 moment the proxy received the last HTTP header. The value "-1" indicates
8728 that the end of headers (empty line) has never been seen. This happens when
8729 the client closes prematurely or times out.
8730
8731 - Tw: total time spent in the queues waiting for a connection slot. It
8732 accounts for backend queue as well as the server queues, and depends on the
8733 queue size, and the time needed for the server to complete previous
8734 requests. The value "-1" means that the request was killed before reaching
8735 the queue, which is generally what happens with invalid or denied requests.
8736
8737 - Tc: total time to establish the TCP connection to the server. It's the time
8738 elapsed between the moment the proxy sent the connection request, and the
8739 moment it was acknowledged by the server, or between the TCP SYN packet and
8740 the matching SYN/ACK packet in return. The value "-1" means that the
8741 connection never established.
8742
8743 - Tr: server response time (HTTP mode only). It's the time elapsed between
8744 the moment the TCP connection was established to the server and the moment
8745 the server sent its complete response headers. It purely shows its request
8746 processing time, without the network overhead due to the data transmission.
8747 It is worth noting that when the client has data to send to the server, for
8748 instance during a POST request, the time already runs, and this can distort
8749 apparent response time. For this reason, it's generally wise not to trust
8750 too much this field for POST requests initiated from clients behind an
8751 untrusted network. A value of "-1" here means that the last the response
8752 header (empty line) was never seen, most likely because the server timeout
8753 stroke before the server managed to process the request.
8754
8755 - Tt: total session duration time, between the moment the proxy accepted it
8756 and the moment both ends were closed. The exception is when the "logasap"
8757 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
8758 prefixed with a '+' sign. From this field, we can deduce "Td", the data
8759 transmission time, by substracting other timers when valid :
8760
8761 Td = Tt - (Tq + Tw + Tc + Tr)
8762
8763 Timers with "-1" values have to be excluded from this equation. In TCP
8764 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
8765 negative.
8766
8767These timers provide precious indications on trouble causes. Since the TCP
8768protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
8769that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008770due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008771close to a timeout value specified in the configuration, it often means that a
8772session has been aborted on timeout.
8773
8774Most common cases :
8775
8776 - If "Tq" is close to 3000, a packet has probably been lost between the
8777 client and the proxy. This is very rare on local networks but might happen
8778 when clients are on far remote networks and send large requests. It may
8779 happen that values larger than usual appear here without any network cause.
8780 Sometimes, during an attack or just after a resource starvation has ended,
8781 haproxy may accept thousands of connections in a few milliseconds. The time
8782 spent accepting these connections will inevitably slightly delay processing
8783 of other connections, and it can happen that request times in the order of
8784 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +02008785 connections have been accepted at once. Setting "option http-server-close"
8786 may display larger request times since "Tq" also measures the time spent
8787 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008788
8789 - If "Tc" is close to 3000, a packet has probably been lost between the
8790 server and the proxy during the server connection phase. This value should
8791 always be very low, such as 1 ms on local networks and less than a few tens
8792 of ms on remote networks.
8793
Willy Tarreau55165fe2009-05-10 12:02:55 +02008794 - If "Tr" is nearly always lower than 3000 except some rare values which seem
8795 to be the average majored by 3000, there are probably some packets lost
8796 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008797
8798 - If "Tt" is large even for small byte counts, it generally is because
8799 neither the client nor the server decides to close the connection, for
8800 instance because both have agreed on a keep-alive connection mode. In order
8801 to solve this issue, it will be needed to specify "option httpclose" on
8802 either the frontend or the backend. If the problem persists, it means that
8803 the server ignores the "close" connection mode and expects the client to
8804 close. Then it will be required to use "option forceclose". Having the
8805 smallest possible 'Tt' is important when connection regulation is used with
8806 the "maxconn" option on the servers, since no new connection will be sent
8807 to the server until another one is released.
8808
8809Other noticeable HTTP log cases ('xx' means any value to be ignored) :
8810
8811 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
8812 was emitted before the data phase. All the timers are valid
8813 except "Tt" which is shorter than reality.
8814
8815 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
8816 or it aborted too early. Check the session termination flags
8817 then "timeout http-request" and "timeout client" settings.
8818
8819 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
8820 servers were out of order, because the request was invalid
8821 or forbidden by ACL rules. Check the session termination
8822 flags.
8823
8824 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
8825 actively refused it or it timed out after Tt-(Tq+Tw) ms.
8826 Check the session termination flags, then check the
8827 "timeout connect" setting. Note that the tarpit action might
8828 return similar-looking patterns, with "Tw" equal to the time
8829 the client connection was maintained open.
8830
8831 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
8832 a complete response in time, or it closed its connexion
8833 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
8834 termination flags, then check the "timeout server" setting.
8835
8836
Willy Tarreauc57f0e22009-05-10 13:12:33 +020088378.5. Session state at disconnection
8838-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008839
8840TCP and HTTP logs provide a session termination indicator in the
8841"termination_state" field, just before the number of active connections. It is
88422-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
8843each of which has a special meaning :
8844
8845 - On the first character, a code reporting the first event which caused the
8846 session to terminate :
8847
8848 C : the TCP session was unexpectedly aborted by the client.
8849
8850 S : the TCP session was unexpectedly aborted by the server, or the
8851 server explicitly refused it.
8852
8853 P : the session was prematurely aborted by the proxy, because of a
8854 connection limit enforcement, because a DENY filter was matched,
8855 because of a security check which detected and blocked a dangerous
8856 error in server response which might have caused information leak
8857 (eg: cacheable cookie), or because the response was processed by
8858 the proxy (redirect, stats, etc...).
8859
8860 R : a resource on the proxy has been exhausted (memory, sockets, source
8861 ports, ...). Usually, this appears during the connection phase, and
8862 system logs should contain a copy of the precise error. If this
8863 happens, it must be considered as a very serious anomaly which
8864 should be fixed as soon as possible by any means.
8865
8866 I : an internal error was identified by the proxy during a self-check.
8867 This should NEVER happen, and you are encouraged to report any log
8868 containing this, because this would almost certainly be a bug. It
8869 would be wise to preventively restart the process after such an
8870 event too, in case it would be caused by memory corruption.
8871
Simon Horman752dc4a2011-06-21 14:34:59 +09008872 D : the session was killed by haproxy because the server was detected
8873 as down and was configured to kill all connections when going down.
8874
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008875 c : the client-side timeout expired while waiting for the client to
8876 send or receive data.
8877
8878 s : the server-side timeout expired while waiting for the server to
8879 send or receive data.
8880
8881 - : normal session completion, both the client and the server closed
8882 with nothing left in the buffers.
8883
8884 - on the second character, the TCP or HTTP session state when it was closed :
8885
Willy Tarreauf7b30a92010-12-06 22:59:17 +01008886 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008887 (HTTP mode only). Nothing was sent to any server.
8888
8889 Q : the proxy was waiting in the QUEUE for a connection slot. This can
8890 only happen when servers have a 'maxconn' parameter set. It can
8891 also happen in the global queue after a redispatch consecutive to
8892 a failed attempt to connect to a dying server. If no redispatch is
8893 reported, then no connection attempt was made to any server.
8894
8895 C : the proxy was waiting for the CONNECTION to establish on the
8896 server. The server might at most have noticed a connection attempt.
8897
8898 H : the proxy was waiting for complete, valid response HEADERS from the
8899 server (HTTP only).
8900
8901 D : the session was in the DATA phase.
8902
8903 L : the proxy was still transmitting LAST data to the client while the
8904 server had already finished. This one is very rare as it can only
8905 happen when the client dies while receiving the last packets.
8906
8907 T : the request was tarpitted. It has been held open with the client
8908 during the whole "timeout tarpit" duration or until the client
8909 closed, both of which will be reported in the "Tw" timer.
8910
8911 - : normal session completion after end of data transfer.
8912
8913 - the third character tells whether the persistence cookie was provided by
8914 the client (only in HTTP mode) :
8915
8916 N : the client provided NO cookie. This is usually the case for new
8917 visitors, so counting the number of occurrences of this flag in the
8918 logs generally indicate a valid trend for the site frequentation.
8919
8920 I : the client provided an INVALID cookie matching no known server.
8921 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02008922 cookies between HTTP/HTTPS sites, persistence conditionally
8923 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008924
8925 D : the client provided a cookie designating a server which was DOWN,
8926 so either "option persist" was used and the client was sent to
8927 this server, or it was not set and the client was redispatched to
8928 another server.
8929
Willy Tarreau996a92c2010-10-13 19:30:47 +02008930 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008931 server.
8932
Willy Tarreau996a92c2010-10-13 19:30:47 +02008933 E : the client provided a valid cookie, but with a last date which was
8934 older than what is allowed by the "maxidle" cookie parameter, so
8935 the cookie is consider EXPIRED and is ignored. The request will be
8936 redispatched just as if there was no cookie.
8937
8938 O : the client provided a valid cookie, but with a first date which was
8939 older than what is allowed by the "maxlife" cookie parameter, so
8940 the cookie is consider too OLD and is ignored. The request will be
8941 redispatched just as if there was no cookie.
8942
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008943 - : does not apply (no cookie set in configuration).
8944
8945 - the last character reports what operations were performed on the persistence
8946 cookie returned by the server (only in HTTP mode) :
8947
8948 N : NO cookie was provided by the server, and none was inserted either.
8949
8950 I : no cookie was provided by the server, and the proxy INSERTED one.
8951 Note that in "cookie insert" mode, if the server provides a cookie,
8952 it will still be overwritten and reported as "I" here.
8953
Willy Tarreau996a92c2010-10-13 19:30:47 +02008954 U : the proxy UPDATED the last date in the cookie that was presented by
8955 the client. This can only happen in insert mode with "maxidle". It
8956 happens everytime there is activity at a different date than the
8957 date indicated in the cookie. If any other change happens, such as
8958 a redispatch, then the cookie will be marked as inserted instead.
8959
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008960 P : a cookie was PROVIDED by the server and transmitted as-is.
8961
8962 R : the cookie provided by the server was REWRITTEN by the proxy, which
8963 happens in "cookie rewrite" or "cookie prefix" modes.
8964
8965 D : the cookie provided by the server was DELETED by the proxy.
8966
8967 - : does not apply (no cookie set in configuration).
8968
Willy Tarreau996a92c2010-10-13 19:30:47 +02008969The combination of the two first flags gives a lot of information about what
8970was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008971helpful to detect server saturation, network troubles, local system resource
8972starvation, attacks, etc...
8973
8974The most common termination flags combinations are indicated below. They are
8975alphabetically sorted, with the lowercase set just after the upper case for
8976easier finding and understanding.
8977
8978 Flags Reason
8979
8980 -- Normal termination.
8981
8982 CC The client aborted before the connection could be established to the
8983 server. This can happen when haproxy tries to connect to a recently
8984 dead (or unchecked) server, and the client aborts while haproxy is
8985 waiting for the server to respond or for "timeout connect" to expire.
8986
8987 CD The client unexpectedly aborted during data transfer. This can be
8988 caused by a browser crash, by an intermediate equipment between the
8989 client and haproxy which decided to actively break the connection,
8990 by network routing issues between the client and haproxy, or by a
8991 keep-alive session between the server and the client terminated first
8992 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +01008993
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008994 cD The client did not send nor acknowledge any data for as long as the
8995 "timeout client" delay. This is often caused by network failures on
8996 the client side, or the client simply leaving the net uncleanly.
8997
8998 CH The client aborted while waiting for the server to start responding.
8999 It might be the server taking too long to respond or the client
9000 clicking the 'Stop' button too fast.
9001
9002 cH The "timeout client" stroke while waiting for client data during a
9003 POST request. This is sometimes caused by too large TCP MSS values
9004 for PPPoE networks which cannot transport full-sized packets. It can
9005 also happen when client timeout is smaller than server timeout and
9006 the server takes too long to respond.
9007
9008 CQ The client aborted while its session was queued, waiting for a server
9009 with enough empty slots to accept it. It might be that either all the
9010 servers were saturated or that the assigned server was taking too
9011 long a time to respond.
9012
9013 CR The client aborted before sending a full HTTP request. Most likely
9014 the request was typed by hand using a telnet client, and aborted
9015 too early. The HTTP status code is likely a 400 here. Sometimes this
9016 might also be caused by an IDS killing the connection between haproxy
9017 and the client.
9018
9019 cR The "timeout http-request" stroke before the client sent a full HTTP
9020 request. This is sometimes caused by too large TCP MSS values on the
9021 client side for PPPoE networks which cannot transport full-sized
9022 packets, or by clients sending requests by hand and not typing fast
9023 enough, or forgetting to enter the empty line at the end of the
9024 request. The HTTP status code is likely a 408 here.
9025
9026 CT The client aborted while its session was tarpitted. It is important to
9027 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +02009028 wrong tarpit rules have been written. If a lot of them happen, it
9029 might make sense to lower the "timeout tarpit" value to something
9030 closer to the average reported "Tw" timer, in order not to consume
9031 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009032
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009033 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009034 the TCP connection (the proxy received a TCP RST or an ICMP message
9035 in return). Under some circumstances, it can also be the network
9036 stack telling the proxy that the server is unreachable (eg: no route,
9037 or no ARP response on local network). When this happens in HTTP mode,
9038 the status code is likely a 502 or 503 here.
9039
9040 sC The "timeout connect" stroke before a connection to the server could
9041 complete. When this happens in HTTP mode, the status code is likely a
9042 503 or 504 here.
9043
9044 SD The connection to the server died with an error during the data
9045 transfer. This usually means that haproxy has received an RST from
9046 the server or an ICMP message from an intermediate equipment while
9047 exchanging data with the server. This can be caused by a server crash
9048 or by a network issue on an intermediate equipment.
9049
9050 sD The server did not send nor acknowledge any data for as long as the
9051 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009052 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009053 load-balancers, ...), as well as keep-alive sessions maintained
9054 between the client and the server expiring first on haproxy.
9055
9056 SH The server aborted before sending its full HTTP response headers, or
9057 it crashed while processing the request. Since a server aborting at
9058 this moment is very rare, it would be wise to inspect its logs to
9059 control whether it crashed and why. The logged request may indicate a
9060 small set of faulty requests, demonstrating bugs in the application.
9061 Sometimes this might also be caused by an IDS killing the connection
9062 between haproxy and the server.
9063
9064 sH The "timeout server" stroke before the server could return its
9065 response headers. This is the most common anomaly, indicating too
9066 long transactions, probably caused by server or database saturation.
9067 The immediate workaround consists in increasing the "timeout server"
9068 setting, but it is important to keep in mind that the user experience
9069 will suffer from these long response times. The only long term
9070 solution is to fix the application.
9071
9072 sQ The session spent too much time in queue and has been expired. See
9073 the "timeout queue" and "timeout connect" settings to find out how to
9074 fix this if it happens too often. If it often happens massively in
9075 short periods, it may indicate general problems on the affected
9076 servers due to I/O or database congestion, or saturation caused by
9077 external attacks.
9078
9079 PC The proxy refused to establish a connection to the server because the
9080 process' socket limit has been reached while attempting to connect.
9081 The global "maxconn" parameter may be increased in the configuration
9082 so that it does not happen anymore. This status is very rare and
9083 might happen when the global "ulimit-n" parameter is forced by hand.
9084
Willy Tarreaued2fd2d2010-12-29 11:23:27 +01009085 PD The proxy blocked an incorrectly formatted chunked encoded message in
9086 a request or a response, after the server has emitted its headers. In
9087 most cases, this will indicate an invalid message from the server to
9088 the client.
9089
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009090 PH The proxy blocked the server's response, because it was invalid,
9091 incomplete, dangerous (cache control), or matched a security filter.
9092 In any case, an HTTP 502 error is sent to the client. One possible
9093 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +01009094 containing unauthorized characters. It is also possible but quite
9095 rare, that the proxy blocked a chunked-encoding request from the
9096 client due to an invalid syntax, before the server responded. In this
9097 case, an HTTP 400 error is sent to the client and reported in the
9098 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009099
9100 PR The proxy blocked the client's HTTP request, either because of an
9101 invalid HTTP syntax, in which case it returned an HTTP 400 error to
9102 the client, or because a deny filter matched, in which case it
9103 returned an HTTP 403 error.
9104
9105 PT The proxy blocked the client's request and has tarpitted its
9106 connection before returning it a 500 server error. Nothing was sent
9107 to the server. The connection was maintained open for as long as
9108 reported by the "Tw" timer field.
9109
9110 RC A local resource has been exhausted (memory, sockets, source ports)
9111 preventing the connection to the server from establishing. The error
9112 logs will tell precisely what was missing. This is very rare and can
9113 only be solved by proper system tuning.
9114
Willy Tarreau996a92c2010-10-13 19:30:47 +02009115The combination of the two last flags gives a lot of information about how
9116persistence was handled by the client, the server and by haproxy. This is very
9117important to troubleshoot disconnections, when users complain they have to
9118re-authenticate. The commonly encountered flags are :
9119
9120 -- Persistence cookie is not enabled.
9121
9122 NN No cookie was provided by the client, none was inserted in the
9123 response. For instance, this can be in insert mode with "postonly"
9124 set on a GET request.
9125
9126 II A cookie designating an invalid server was provided by the client,
9127 a valid one was inserted in the response. This typically happens when
9128 a "server" entry is removed from the configuraton, since its cookie
9129 value can be presented by a client when no other server knows it.
9130
9131 NI No cookie was provided by the client, one was inserted in the
9132 response. This typically happens for first requests from every user
9133 in "insert" mode, which makes it an easy way to count real users.
9134
9135 VN A cookie was provided by the client, none was inserted in the
9136 response. This happens for most responses for which the client has
9137 already got a cookie.
9138
9139 VU A cookie was provided by the client, with a last visit date which is
9140 not completely up-to-date, so an updated cookie was provided in
9141 response. This can also happen if there was no date at all, or if
9142 there was a date but the "maxidle" parameter was not set, so that the
9143 cookie can be switched to unlimited time.
9144
9145 EI A cookie was provided by the client, with a last visit date which is
9146 too old for the "maxidle" parameter, so the cookie was ignored and a
9147 new cookie was inserted in the response.
9148
9149 OI A cookie was provided by the client, with a first visit date which is
9150 too old for the "maxlife" parameter, so the cookie was ignored and a
9151 new cookie was inserted in the response.
9152
9153 DI The server designated by the cookie was down, a new server was
9154 selected and a new cookie was emitted in the response.
9155
9156 VI The server designated by the cookie was not marked dead but could not
9157 be reached. A redispatch happened and selected another one, which was
9158 then advertised in the response.
9159
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009160
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091618.6. Non-printable characters
9162-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009163
9164In order not to cause trouble to log analysis tools or terminals during log
9165consulting, non-printable characters are not sent as-is into log files, but are
9166converted to the two-digits hexadecimal representation of their ASCII code,
9167prefixed by the character '#'. The only characters that can be logged without
9168being escaped are comprised between 32 and 126 (inclusive). Obviously, the
9169escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
9170is the same for the character '"' which becomes "#22", as well as '{', '|' and
9171'}' when logging headers.
9172
9173Note that the space character (' ') is not encoded in headers, which can cause
9174issues for tools relying on space count to locate fields. A typical header
9175containing spaces is "User-Agent".
9176
9177Last, it has been observed that some syslog daemons such as syslog-ng escape
9178the quote ('"') with a backslash ('\'). The reverse operation can safely be
9179performed since no quote may appear anywhere else in the logs.
9180
9181
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091828.7. Capturing HTTP cookies
9183---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009184
9185Cookie capture simplifies the tracking a complete user session. This can be
9186achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009187section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009188cookie will simultaneously be checked in the request ("Cookie:" header) and in
9189the response ("Set-Cookie:" header). The respective values will be reported in
9190the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009191locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009192not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
9193user switches to a new session for example, because the server will reassign it
9194a new cookie. It is also possible to detect if a server unexpectedly sets a
9195wrong cookie to a client, leading to session crossing.
9196
9197 Examples :
9198 # capture the first cookie whose name starts with "ASPSESSION"
9199 capture cookie ASPSESSION len 32
9200
9201 # capture the first cookie whose name is exactly "vgnvisitor"
9202 capture cookie vgnvisitor= len 32
9203
9204
Willy Tarreauc57f0e22009-05-10 13:12:33 +020092058.8. Capturing HTTP headers
9206---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009207
9208Header captures are useful to track unique request identifiers set by an upper
9209proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
9210the response, one can search for information about the response length, how the
9211server asked the cache to behave, or an object location during a redirection.
9212
9213Header captures are performed using the "capture request header" and "capture
9214response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009215section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009216
9217It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009218time. Non-existent headers are logged as empty strings, and if one header
9219appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009220are grouped within braces '{' and '}' in the same order as they were declared,
9221and delimited with a vertical bar '|' without any space. Response headers
9222follow the same representation, but are displayed after a space following the
9223request headers block. These blocks are displayed just before the HTTP request
9224in the logs.
9225
9226 Example :
9227 # This instance chains to the outgoing proxy
9228 listen proxy-out
9229 mode http
9230 option httplog
9231 option logasap
9232 log global
9233 server cache1 192.168.1.1:3128
9234
9235 # log the name of the virtual server
9236 capture request header Host len 20
9237
9238 # log the amount of data uploaded during a POST
9239 capture request header Content-Length len 10
9240
9241 # log the beginning of the referrer
9242 capture request header Referer len 20
9243
9244 # server name (useful for outgoing proxies only)
9245 capture response header Server len 20
9246
9247 # logging the content-length is useful with "option logasap"
9248 capture response header Content-Length len 10
9249
9250 # log the expected cache behaviour on the response
9251 capture response header Cache-Control len 8
9252
9253 # the Via header will report the next proxy's name
9254 capture response header Via len 20
9255
9256 # log the URL location during a redirection
9257 capture response header Location len 20
9258
9259 >>> Aug 9 20:26:09 localhost \
9260 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
9261 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
9262 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
9263 "GET http://fr.adserver.yahoo.com/"
9264
9265 >>> Aug 9 20:30:46 localhost \
9266 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
9267 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
9268 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009269 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009270
9271 >>> Aug 9 20:30:46 localhost \
9272 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
9273 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
9274 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
9275 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009276 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009277
9278
Willy Tarreauc57f0e22009-05-10 13:12:33 +020092798.9. Examples of logs
9280---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009281
9282These are real-world examples of logs accompanied with an explanation. Some of
9283them have been made up by hand. The syslog part has been removed for better
9284reading. Their sole purpose is to explain how to decipher them.
9285
9286 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
9287 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
9288 "HEAD / HTTP/1.0"
9289
9290 => long request (6.5s) entered by hand through 'telnet'. The server replied
9291 in 147 ms, and the session ended normally ('----')
9292
9293 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
9294 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
9295 0/9 "HEAD / HTTP/1.0"
9296
9297 => Idem, but the request was queued in the global queue behind 9 other
9298 requests, and waited there for 1230 ms.
9299
9300 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
9301 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
9302 "GET /image.iso HTTP/1.0"
9303
9304 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009305 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009306 14 ms, 243 bytes of headers were sent to the client, and total time from
9307 accept to first data byte is 30 ms.
9308
9309 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
9310 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
9311 "GET /cgi-bin/bug.cgi? HTTP/1.0"
9312
9313 => the proxy blocked a server response either because of an "rspdeny" or
9314 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02009315 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009316 risked being cached. In this case, the response is replaced with a "502
9317 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
9318 to return the 502 and not the server.
9319
9320 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009321 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 +01009322
9323 => the client never completed its request and aborted itself ("C---") after
9324 8.5s, while the proxy was waiting for the request headers ("-R--").
9325 Nothing was sent to any server.
9326
9327 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
9328 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
9329
9330 => The client never completed its request, which was aborted by the
9331 time-out ("c---") after 50s, while the proxy was waiting for the request
9332 headers ("-R--"). Nothing was sent to any server, but the proxy could
9333 send a 408 return code to the client.
9334
9335 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
9336 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
9337
9338 => This log was produced with "option tcplog". The client timed out after
9339 5 seconds ("c----").
9340
9341 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
9342 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009343 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009344
9345 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009346 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009347 (config says 'retries 3'), and no redispatch (otherwise we would have
9348 seen "/+3"). Status code 503 was returned to the client. There were 115
9349 connections on this server, 202 connections on this proxy, and 205 on
9350 the global process. It is possible that the server refused the
9351 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009352
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009353
Willy Tarreauc57f0e22009-05-10 13:12:33 +020093549. Statistics and monitoring
9355----------------------------
9356
9357It is possible to query HAProxy about its status. The most commonly used
9358mechanism is the HTTP statistics page. This page also exposes an alternative
9359CSV output format for monitoring tools. The same format is provided on the
9360Unix socket.
9361
9362
93639.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009364---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009365
Willy Tarreau7f062c42009-03-05 18:43:00 +01009366The statistics may be consulted either from the unix socket or from the HTTP
9367page. Both means provide a CSV format whose fields follow.
9368
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009369 0. pxname: proxy name
9370 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
9371 for server)
9372 2. qcur: current queued requests
9373 3. qmax: max queued requests
9374 4. scur: current sessions
9375 5. smax: max sessions
9376 6. slim: sessions limit
9377 7. stot: total sessions
9378 8. bin: bytes in
9379 9. bout: bytes out
9380 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009381 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009382 12. ereq: request errors
9383 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +01009384 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009385 15. wretr: retries (warning)
9386 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +01009387 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009388 18. weight: server weight (server), total weight (backend)
9389 19. act: server is active (server), number of active servers (backend)
9390 20. bck: server is backup (server), number of backup servers (backend)
9391 21. chkfail: number of failed checks
9392 22. chkdown: number of UP->DOWN transitions
9393 23. lastchg: last status change (in seconds)
9394 24. downtime: total downtime (in seconds)
9395 25. qlimit: queue limit
9396 26. pid: process id (0 for first instance, 1 for second, ...)
9397 27. iid: unique proxy id
9398 28. sid: service id (unique inside a proxy)
9399 29. throttle: warm up status
9400 30. lbtot: total number of times a server was selected
9401 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02009402 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +02009403 33. rate: number of sessions per second over last elapsed second
9404 34. rate_lim: limit on new sessions per second
9405 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02009406 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +01009407 UNK -> unknown
9408 INI -> initializing
9409 SOCKERR -> socket error
9410 L4OK -> check passed on layer 4, no upper layers testing enabled
9411 L4TMOUT -> layer 1-4 timeout
9412 L4CON -> layer 1-4 connection problem, for example
9413 "Connection refused" (tcp rst) or "No route to host" (icmp)
9414 L6OK -> check passed on layer 6
9415 L6TOUT -> layer 6 (SSL) timeout
9416 L6RSP -> layer 6 invalid response - protocol error
9417 L7OK -> check passed on layer 7
9418 L7OKC -> check conditionally passed on layer 7, for example 404 with
9419 disable-on-404
9420 L7TOUT -> layer 7 (HTTP/SMTP) timeout
9421 L7RSP -> layer 7 invalid response - protocol error
9422 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02009423 37. check_code: layer5-7 code, if available
9424 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009425 39. hrsp_1xx: http responses with 1xx code
9426 40. hrsp_2xx: http responses with 2xx code
9427 41. hrsp_3xx: http responses with 3xx code
9428 42. hrsp_4xx: http responses with 4xx code
9429 43. hrsp_5xx: http responses with 5xx code
9430 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +01009431 45. hanafail: failed health checks details
9432 46. req_rate: HTTP requests per second over last elapsed second
9433 47. req_rate_max: max number of HTTP requests per second observed
9434 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +01009435 49. cli_abrt: number of data transfers aborted by the client
9436 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau844e3c52008-01-11 16:28:18 +01009437
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009438
Willy Tarreauc57f0e22009-05-10 13:12:33 +020094399.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009440-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009441
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009442The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009443must be terminated by a line feed. The socket supports pipelining, so that it
9444is possible to chain multiple commands at once provided they are delimited by
9445a semi-colon or a line feed, although the former is more reliable as it has no
9446risk of being truncated over the network. The responses themselves will each be
9447followed by an empty line, so it will be easy for an external script to match a
9448given response with a given request. By default one command line is processed
9449then the connection closes, but there is an interactive allowing multiple lines
9450to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009451
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009452It is important to understand that when multiple haproxy processes are started
9453on the same sockets, any process may pick up the request and will output its
9454own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009455
Willy Tarreaud63335a2010-02-26 12:56:52 +01009456clear counters
9457 Clear the max values of the statistics counters in each proxy (frontend &
9458 backend) and in each server. The cumulated counters are not affected. This
9459 can be used to get clean counters after an incident, without having to
9460 restart nor to clear traffic counters. This command is restricted and can
9461 only be issued on sockets configured for levels "operator" or "admin".
9462
9463clear counters all
9464 Clear all statistics counters in each proxy (frontend & backend) and in each
9465 server. This has the same effect as restarting. This command is restricted
9466 and can only be issued on sockets configured for level "admin".
9467
Simon Hormanc88b8872011-06-15 15:18:49 +09009468clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
9469 Remove entries from the stick-table <table>.
9470
9471 This is typically used to unblock some users complaining they have been
9472 abusively denied access to a service, but this can also be used to clear some
9473 stickiness entries matching a server that is going to be replaced (see "show
9474 table" below for details). Note that sometimes, removal of an entry will be
9475 refused because it is currently tracked by a session. Retrying a few seconds
9476 later after the session ends is usual enough.
9477
9478 In the case where no options arguments are given all entries will be removed.
9479
9480 When the "data." form is used entries matching a filter applied using the
9481 stored data (see "stick-table" in section 4.2) are removed. A stored data
9482 type must be specified in <type>, and this data type must be stored in the
9483 table otherwise an error is reported. The data is compared according to
9484 <operator> with the 64-bit integer <value>. Operators are the same as with
9485 the ACLs :
9486
9487 - eq : match entries whose data is equal to this value
9488 - ne : match entries whose data is not equal to this value
9489 - le : match entries whose data is less than or equal to this value
9490 - ge : match entries whose data is greater than or equal to this value
9491 - lt : match entries whose data is less than this value
9492 - gt : match entries whose data is greater than this value
9493
9494 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +09009495 same type as the table, which currently is limited to IPv4, IPv6, integer and
9496 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009497
9498 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009499 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009500 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +02009501 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
9502 bytes_out_rate(60000)=187
9503 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9504 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009505
9506 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
9507
9508 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009509 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +02009510 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9511 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +09009512 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
9513 $ echo "show table http_proxy" | socat stdio /tmp/sock1
9514 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009515
Willy Tarreaud63335a2010-02-26 12:56:52 +01009516disable server <backend>/<server>
9517 Mark the server DOWN for maintenance. In this mode, no more checks will be
9518 performed on the server until it leaves maintenance.
9519 If the server is tracked by other servers, those servers will be set to DOWN
9520 during the maintenance.
9521
9522 In the statistics page, a server DOWN for maintenance will appear with a
9523 "MAINT" status, its tracking servers with the "MAINT(via)" one.
9524
9525 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +02009526 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +01009527
9528 This command is restricted and can only be issued on sockets configured for
9529 level "admin".
9530
9531enable server <backend>/<server>
9532 If the server was previously marked as DOWN for maintenance, this marks the
9533 server UP and checks are re-enabled.
9534
9535 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +02009536 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +01009537
9538 This command is restricted and can only be issued on sockets configured for
9539 level "admin".
9540
9541get weight <backend>/<server>
9542 Report the current weight and the initial weight of server <server> in
9543 backend <backend> or an error if either doesn't exist. The initial weight is
9544 the one that appears in the configuration file. Both are normally equal
9545 unless the current weight has been changed. Both the backend and the server
9546 may be specified either by their name or by their numeric ID, prefixed with a
Willy Tarreauf5f31922011-08-02 11:32:07 +02009547 sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +01009548
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009549help
9550 Print the list of known keywords and their basic usage. The same help screen
9551 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009552
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009553prompt
9554 Toggle the prompt at the beginning of the line and enter or leave interactive
9555 mode. In interactive mode, the connection is not closed after a command
9556 completes. Instead, the prompt will appear again, indicating the user that
9557 the interpreter is waiting for a new command. The prompt consists in a right
9558 angle bracket followed by a space "> ". This mode is particularly convenient
9559 when one wants to periodically check information such as stats or errors.
9560 It is also a good idea to enter interactive mode before issuing a "help"
9561 command.
9562
9563quit
9564 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009565
Willy Tarreau2a0f4d22011-08-02 11:49:05 +02009566set maxconn frontend <frontend> <value>
9567 Dynamically change the specified frontend's maxconn setting. Any non-null
9568 positive value is allowed, but setting values larger than the global maxconn
9569 does not make much sense. If the limit is increased and connections were
9570 pending, they will immediately be accepted. If it is lowered to a value below
9571 the current number of connections, new connections acceptation will be
9572 delayed until the threshold is reached. The frontend might be specified by
9573 either its name or its numeric ID prefixed with a sharp ('#').
9574
Willy Tarreau91886b62011-09-07 14:38:31 +02009575set maxconn global <maxconn>
9576 Dynamically change the global maxconn setting within the range defined by the
9577 initial global maxconn setting. If it is increased and connections were
9578 pending, they will immediately be accepted. If it is lowered to a value below
9579 the current number of connections, new connections acceptation will be
9580 delayed until the threshold is reached. A value of zero restores the initial
9581 setting.
9582
Willy Tarreauf5b22872011-09-07 16:13:44 +02009583set rate-limit connections global <value>
9584 Change the process-wide connection rate limit, which is set by the global
9585 'maxconnrate' setting. A value of zero disables the limitation. This limit
9586 applies to all frontends and the change has an immediate effect. The value
9587 is passed in number of connections per second.
9588
Willy Tarreaud63335a2010-02-26 12:56:52 +01009589set timeout cli <delay>
9590 Change the CLI interface timeout for current connection. This can be useful
9591 during long debugging sessions where the user needs to constantly inspect
9592 some indicators without being disconnected. The delay is passed in seconds.
9593
9594set weight <backend>/<server> <weight>[%]
9595 Change a server's weight to the value passed in argument. If the value ends
9596 with the '%' sign, then the new weight will be relative to the initially
9597 configured weight. Relative weights are only permitted between 0 and 100%,
9598 and absolute weights are permitted between 0 and 256. Servers which are part
9599 of a farm running a static load-balancing algorithm have stricter limitations
9600 because the weight cannot change once set. Thus for these servers, the only
9601 accepted values are 0 and 100% (or 0 and the initial weight). Changes take
9602 effect immediately, though certain LB algorithms require a certain amount of
9603 requests to consider changes. A typical usage of this command is to disable
9604 a server during an update by setting its weight to zero, then to enable it
9605 again after the update by setting it back to 100%. This command is restricted
9606 and can only be issued on sockets configured for level "admin". Both the
9607 backend and the server may be specified either by their name or by their
Willy Tarreauf5f31922011-08-02 11:32:07 +02009608 numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +01009609
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009610show errors [<iid>]
9611 Dump last known request and response errors collected by frontends and
9612 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +02009613 either frontend or backend whose ID is <iid>. This command is restricted
9614 and can only be issued on sockets configured for levels "operator" or
9615 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009616
9617 The errors which may be collected are the last request and response errors
9618 caused by protocol violations, often due to invalid characters in header
9619 names. The report precisely indicates what exact character violated the
9620 protocol. Other important information such as the exact date the error was
9621 detected, frontend and backend names, the server name (when known), the
9622 internal session ID and the source address which has initiated the session
9623 are reported too.
9624
9625 All characters are returned, and non-printable characters are encoded. The
9626 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
9627 letter following a backslash. The backslash itself is encoded as '\\' to
9628 avoid confusion. Other non-printable characters are encoded '\xNN' where
9629 NN is the two-digits hexadecimal representation of the character's ASCII
9630 code.
9631
9632 Lines are prefixed with the position of their first character, starting at 0
9633 for the beginning of the buffer. At most one input line is printed per line,
9634 and large lines will be broken into multiple consecutive output lines so that
9635 the output never goes beyond 79 characters wide. It is easy to detect if a
9636 line was broken, because it will not end with '\n' and the next line's offset
9637 will be followed by a '+' sign, indicating it is a continuation of previous
9638 line.
9639
9640 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009641 $ echo "show errors" | socat stdio /tmp/sock1
9642 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009643 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
9644 response length 213 bytes, error at position 23:
9645
9646 00000 HTTP/1.0 200 OK\r\n
9647 00017 header/bizarre:blah\r\n
9648 00038 Location: blah\r\n
9649 00054 Long-line: this is a very long line which should b
9650 00104+ e broken into multiple lines on the output buffer,
9651 00154+ otherwise it would be too large to print in a ter
9652 00204+ minal\r\n
9653 00211 \r\n
9654
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009655 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009656 ID 2 has blocked an invalid response from its server s2 which has internal
9657 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
9658 received by frontend fe-eth0 whose ID is 1. The total response length was
9659 213 bytes when the error was detected, and the error was at byte 23. This
9660 is the slash ('/') in header name "header/bizarre", which is not a valid
9661 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009662
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009663show info
9664 Dump info about haproxy status on current process.
9665
9666show sess
9667 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +02009668 be huge. This command is restricted and can only be issued on sockets
9669 configured for levels "operator" or "admin".
9670
Willy Tarreau66dc20a2010-03-05 17:53:32 +01009671show sess <id>
9672 Display a lot of internal information about the specified session identifier.
9673 This identifier is the first field at the beginning of the lines in the dumps
9674 of "show sess" (it corresponds to the session pointer). Those information are
9675 useless to most users but may be used by haproxy developers to troubleshoot a
9676 complex bug. The output format is intentionally not documented so that it can
9677 freely evolve depending on demands.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009678
9679show stat [<iid> <type> <sid>]
9680 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
9681 possible to dump only selected items :
9682 - <iid> is a proxy ID, -1 to dump everything
9683 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
9684 backends, 4 for servers, -1 for everything. These values can be ORed,
9685 for example:
9686 1 + 2 = 3 -> frontend + backend.
9687 1 + 2 + 4 = 7 -> frontend + backend + server.
9688 - <sid> is a server ID, -1 to dump everything from the selected proxy.
9689
9690 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009691 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
9692 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009693 Version: 1.4-dev2-49
9694 Release_date: 2009/09/23
9695 Nbproc: 1
9696 Process_num: 1
9697 (...)
9698
9699 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
9700 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
9701 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
9702 (...)
9703 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
9704
9705 $
9706
9707 Here, two commands have been issued at once. That way it's easy to find
9708 which process the stats apply to in multi-process mode. Notice the empty
9709 line after the information output which marks the end of the first block.
9710 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009711 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009712
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009713show table
9714 Dump general information on all known stick-tables. Their name is returned
9715 (the name of the proxy which holds them), their type (currently zero, always
9716 IP), their size in maximum possible number of entries, and the number of
9717 entries currently in use.
9718
9719 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009720 $ echo "show table" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +09009721 >>> # table: front_pub, type: ip, size:204800, used:171454
9722 >>> # table: back_rdp, type: ip, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009723
Simon Horman17bce342011-06-15 15:18:47 +09009724show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009725 Dump contents of stick-table <name>. In this mode, a first line of generic
9726 information about the table is reported as with "show table", then all
9727 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +09009728 a filter in order to specify what entries to display.
9729
9730 When the "data." form is used the filter applies to the stored data (see
9731 "stick-table" in section 4.2). A stored data type must be specified
9732 in <type>, and this data type must be stored in the table otherwise an
9733 error is reported. The data is compared according to <operator> with the
9734 64-bit integer <value>. Operators are the same as with the ACLs :
9735
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009736 - eq : match entries whose data is equal to this value
9737 - ne : match entries whose data is not equal to this value
9738 - le : match entries whose data is less than or equal to this value
9739 - ge : match entries whose data is greater than or equal to this value
9740 - lt : match entries whose data is less than this value
9741 - gt : match entries whose data is greater than this value
9742
Simon Hormanc88b8872011-06-15 15:18:49 +09009743
9744 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +09009745 same type as the table, which currently is limited to IPv4, IPv6, integer,
9746 and string.
Simon Horman17bce342011-06-15 15:18:47 +09009747
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009748 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009749 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +09009750 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +02009751 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
9752 bytes_out_rate(60000)=187
9753 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9754 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009755
Willy Tarreau62a36c42010-08-17 15:53:10 +02009756 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +09009757 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +02009758 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9759 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009760
Willy Tarreau62a36c42010-08-17 15:53:10 +02009761 $ echo "show table http_proxy data.conn_rate gt 5" | \
9762 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +09009763 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +02009764 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9765 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009766
Simon Horman17bce342011-06-15 15:18:47 +09009767 $ echo "show table http_proxy key 127.0.0.2" | \
9768 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +09009769 >>> # table: http_proxy, type: ip, size:204800, used:2
Simon Horman17bce342011-06-15 15:18:47 +09009770 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9771 bytes_out_rate(60000)=191
9772
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009773 When the data criterion applies to a dynamic value dependent on time such as
9774 a bytes rate, the value is dynamically computed during the evaluation of the
9775 entry in order to decide whether it has to be dumped or not. This means that
9776 such a filter could match for some time then not match anymore because as
9777 time goes, the average event rate drops.
9778
9779 It is possible to use this to extract lists of IP addresses abusing the
9780 service, in order to monitor them or even blacklist them in a firewall.
9781 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009782 $ echo "show table http_proxy data.gpc0 gt 0" \
9783 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009784 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
9785 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +02009786
Willy Tarreau0ba27502007-12-24 16:55:16 +01009787/*
9788 * Local variables:
9789 * fill-column: 79
9790 * End:
9791 */