blob: 4811043b8ed3b61a641b23f7b6e31d039baacd8d [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 Tarreauff4f82d2009-02-06 11:28:13 +0100451 - maxpipes
Willy Tarreau6a06a402007-07-15 20:15:28 +0200452 - noepoll
453 - nokqueue
454 - nopoll
455 - nosepoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100456 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200457 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200458 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200459 - tune.chksize
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100460 - tune.maxaccept
461 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200462 - tune.maxrewrite
Willy Tarreaue803de22010-01-21 17:43:04 +0100463 - tune.rcvbuf.client
464 - tune.rcvbuf.server
465 - tune.sndbuf.client
466 - tune.sndbuf.server
Willy Tarreaud72758d2010-01-12 10:42:19 +0100467
Willy Tarreau6a06a402007-07-15 20:15:28 +0200468 * Debugging
469 - debug
470 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200471
472
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004733.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200474------------------------------------
475
476chroot <jail dir>
477 Changes current directory to <jail dir> and performs a chroot() there before
478 dropping privileges. This increases the security level in case an unknown
479 vulnerability would be exploited, since it would make it very hard for the
480 attacker to exploit the system. This only works when the process is started
481 with superuser privileges. It is important to ensure that <jail_dir> is both
482 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100483
Willy Tarreau6a06a402007-07-15 20:15:28 +0200484daemon
485 Makes the process fork into background. This is the recommended mode of
486 operation. It is equivalent to the command line "-D" argument. It can be
487 disabled by the command line "-db" argument.
488
489gid <number>
490 Changes the process' group ID to <number>. It is recommended that the group
491 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
492 be started with a user belonging to this group, or with superuser privileges.
493 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100494
Willy Tarreau6a06a402007-07-15 20:15:28 +0200495group <group name>
496 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
497 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100498
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200499log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200500 Adds a global syslog server. Up to two global servers can be defined. They
501 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100502 configured with "log global".
503
504 <address> can be one of:
505
Willy Tarreau2769aa02007-12-27 18:26:09 +0100506 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100507 no port is specified, 514 is used by default (the standard syslog
508 port).
509
David du Colombier24bb5f52011-03-17 10:40:23 +0100510 - An IPv6 address followed by a colon and optionally a UDP port. If
511 no port is specified, 514 is used by default (the standard syslog
512 port).
513
Robert Tsai81ae1952007-12-05 10:47:29 +0100514 - A filesystem path to a UNIX domain socket, keeping in mind
515 considerations for chroot (be sure the path is accessible inside
516 the chroot) and uid/gid (be sure the path is appropriately
517 writeable).
518
519 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200520
521 kern user mail daemon auth syslog lpr news
522 uucp cron auth2 ftp ntp audit alert cron2
523 local0 local1 local2 local3 local4 local5 local6 local7
524
525 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200526 all messages are sent. If a maximum level is specified, only messages with a
527 severity at least as important as this level will be sent. An optional minimum
528 level can be specified. If it is set, logs emitted with a more severe level
529 than this one will be capped to this level. This is used to avoid sending
530 "emerg" messages on all terminals on some default syslog configurations.
531 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200532
533 emerg alert crit err warning notice info debug
534
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100535log-send-hostname [<string>]
536 Sets the hostname field in the syslog header. If optional "string" parameter
537 is set the header is set to the string contents, otherwise uses the hostname
538 of the system. Generally used if one is not relaying logs through an
539 intermediate syslog server or for simply customizing the hostname printed in
540 the logs.
541
Kevinm48936af2010-12-22 16:08:21 +0000542log-tag <string>
543 Sets the tag field in the syslog header to this string. It defaults to the
544 program name as launched from the command line, which usually is "haproxy".
545 Sometimes it can be useful to differentiate between multiple processes
546 running on the same host.
547
Willy Tarreau6a06a402007-07-15 20:15:28 +0200548nbproc <number>
549 Creates <number> processes when going daemon. This requires the "daemon"
550 mode. By default, only one process is created, which is the recommended mode
551 of operation. For systems limited to small sets of file descriptors per
552 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
553 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
554
555pidfile <pidfile>
556 Writes pids of all daemons into file <pidfile>. This option is equivalent to
557 the "-p" command line argument. The file must be accessible to the user
558 starting the process. See also "daemon".
559
Willy Tarreaufbee7132007-10-18 13:53:22 +0200560stats socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>]
Willy Tarreau6162db22009-10-10 17:13:00 +0200561 [level <level>]
562
Willy Tarreaufbee7132007-10-18 13:53:22 +0200563 Creates a UNIX socket in stream mode at location <path>. Any previously
564 existing socket will be backed up then replaced. Connections to this socket
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100565 will return various statistics outputs and even allow some commands to be
Willy Tarreau6162db22009-10-10 17:13:00 +0200566 issued. Please consult section 9.2 "Unix Socket commands" for more details.
567
568 An optional "level" parameter can be specified to restrict the nature of
569 the commands that can be issued on the socket :
570 - "user" is the least privileged level ; only non-sensitive stats can be
571 read, and no change is allowed. It would make sense on systems where it
572 is not easy to restrict access to the socket.
573
574 - "operator" is the default level and fits most common uses. All data can
575 be read, and only non-sensible changes are permitted (eg: clear max
576 counters).
577
578 - "admin" should be used with care, as everything is permitted (eg: clear
579 all counters).
Willy Tarreaua8efd362008-01-03 10:19:15 +0100580
581 On platforms which support it, it is possible to restrict access to this
582 socket by specifying numerical IDs after "uid" and "gid", or valid user and
583 group names after the "user" and "group" keywords. It is also possible to
584 restrict permissions on the socket by passing an octal value after the "mode"
585 keyword (same syntax as chmod). Depending on the platform, the permissions on
586 the socket will be inherited from the directory which hosts it, or from the
587 user the process is started with.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200588
589stats timeout <timeout, in milliseconds>
590 The default timeout on the stats socket is set to 10 seconds. It is possible
591 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100592 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200593
594stats maxconn <connections>
595 By default, the stats socket is limited to 10 concurrent connections. It is
596 possible to change this value with "stats maxconn".
597
Willy Tarreau6a06a402007-07-15 20:15:28 +0200598uid <number>
599 Changes the process' user ID to <number>. It is recommended that the user ID
600 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
601 be started with superuser privileges in order to be able to switch to another
602 one. See also "gid" and "user".
603
604ulimit-n <number>
605 Sets the maximum number of per-process file-descriptors to <number>. By
606 default, it is automatically computed, so it is recommended not to use this
607 option.
608
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100609unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
610 [ group <group> ] [ gid <gid> ]
611
612 Fixes common settings to UNIX listening sockets declared in "bind" statements.
613 This is mainly used to simplify declaration of those UNIX sockets and reduce
614 the risk of errors, since those settings are most commonly required but are
615 also process-specific. The <prefix> setting can be used to force all socket
616 path to be relative to that directory. This might be needed to access another
617 component's chroot. Note that those paths are resolved before haproxy chroots
618 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
619 all have the same meaning as their homonyms used by the "bind" statement. If
620 both are specified, the "bind" statement has priority, meaning that the
621 "unix-bind" settings may be seen as process-wide default settings.
622
Willy Tarreau6a06a402007-07-15 20:15:28 +0200623user <user name>
624 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
625 See also "uid" and "group".
626
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200627node <name>
628 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
629
630 This statement is useful in HA configurations where two or more processes or
631 servers share the same IP address. By setting a different node-name on all
632 nodes, it becomes easy to immediately spot what server is handling the
633 traffic.
634
635description <text>
636 Add a text that describes the instance.
637
638 Please note that it is required to escape certain characters (# for example)
639 and this text is inserted into a html page so you should avoid using
640 "<" and ">" characters.
641
Willy Tarreau6a06a402007-07-15 20:15:28 +0200642
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006433.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200644-----------------------
645
646maxconn <number>
647 Sets the maximum per-process number of concurrent connections to <number>. It
648 is equivalent to the command-line argument "-n". Proxies will stop accepting
649 connections when this limit is reached. The "ulimit-n" parameter is
650 automatically adjusted according to this value. See also "ulimit-n".
651
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100652maxpipes <number>
653 Sets the maximum per-process number of pipes to <number>. Currently, pipes
654 are only used by kernel-based tcp splicing. Since a pipe contains two file
655 descriptors, the "ulimit-n" value will be increased accordingly. The default
656 value is maxconn/4, which seems to be more than enough for most heavy usages.
657 The splice code dynamically allocates and releases pipes, and can fall back
658 to standard copy, so setting this value too low may only impact performance.
659
Willy Tarreau6a06a402007-07-15 20:15:28 +0200660noepoll
661 Disables the use of the "epoll" event polling system on Linux. It is
662 equivalent to the command-line argument "-de". The next polling system
663 used will generally be "poll". See also "nosepoll", and "nopoll".
664
665nokqueue
666 Disables the use of the "kqueue" event polling system on BSD. It is
667 equivalent to the command-line argument "-dk". The next polling system
668 used will generally be "poll". See also "nopoll".
669
670nopoll
671 Disables the use of the "poll" event polling system. It is equivalent to the
672 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100673 It should never be needed to disable "poll" since it's available on all
Willy Tarreau6a06a402007-07-15 20:15:28 +0200674 platforms supported by HAProxy. See also "nosepoll", and "nopoll" and
675 "nokqueue".
676
677nosepoll
678 Disables the use of the "speculative epoll" event polling system on Linux. It
679 is equivalent to the command-line argument "-ds". The next polling system
680 used will generally be "epoll". See also "nosepoll", and "nopoll".
681
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100682nosplice
683 Disables the use of kernel tcp splicing between sockets on Linux. It is
684 equivalent to the command line argument "-dS". Data will then be copied
685 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100686 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100687 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
688 be used. This option makes it easier to globally disable kernel splicing in
689 case of doubt. See also "option splice-auto", "option splice-request" and
690 "option splice-response".
691
Willy Tarreaufe255b72007-10-14 23:09:26 +0200692spread-checks <0..50, in percent>
693 Sometimes it is desirable to avoid sending health checks to servers at exact
694 intervals, for instance when many logical servers are located on the same
695 physical server. With the help of this parameter, it becomes possible to add
696 some randomness in the check interval between 0 and +/- 50%. A value between
697 2 and 5 seems to show good results. The default value remains at 0.
698
Willy Tarreau27a674e2009-08-17 07:23:33 +0200699tune.bufsize <number>
700 Sets the buffer size to this size (in bytes). Lower values allow more
701 sessions to coexist in the same amount of RAM, and higher values allow some
702 applications with very large cookies to work. The default value is 16384 and
703 can be changed at build time. It is strongly recommended not to change this
704 from the default value, as very low values will break some services such as
705 statistics, and values larger than default size will increase memory usage,
706 possibly causing the system to run out of memory. At least the global maxconn
707 parameter should be decreased by the same factor as this one is increased.
708
Willy Tarreau43961d52010-10-04 20:39:20 +0200709tune.chksize <number>
710 Sets the check buffer size to this size (in bytes). Higher values may help
711 find string or regex patterns in very large pages, though doing so may imply
712 more memory and CPU usage. The default value is 16384 and can be changed at
713 build time. It is not recommended to change this value, but to use better
714 checks whenever possible.
715
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100716tune.maxaccept <number>
717 Sets the maximum number of consecutive accepts that a process may perform on
718 a single wake up. High values give higher priority to high connection rates,
719 while lower values give higher priority to already established connections.
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100720 This value is limited to 100 by default in single process mode. However, in
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100721 multi-process mode (nbproc > 1), it defaults to 8 so that when one process
722 wakes up, it does not take all incoming connections for itself and leaves a
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100723 part of them to other processes. Setting this value to -1 completely disables
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100724 the limitation. It should normally not be needed to tweak this value.
725
726tune.maxpollevents <number>
727 Sets the maximum amount of events that can be processed at once in a call to
728 the polling system. The default value is adapted to the operating system. It
729 has been noticed that reducing it below 200 tends to slightly decrease
730 latency at the expense of network bandwidth, and increasing it above 200
731 tends to trade latency for slightly increased bandwidth.
732
Willy Tarreau27a674e2009-08-17 07:23:33 +0200733tune.maxrewrite <number>
734 Sets the reserved buffer space to this size in bytes. The reserved space is
735 used for header rewriting or appending. The first reads on sockets will never
736 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
737 bufsize, though that does not make much sense since there are rarely large
738 numbers of headers to add. Setting it too high prevents processing of large
739 requests or responses. Setting it too low prevents addition of new headers
740 to already large requests or to POST requests. It is generally wise to set it
741 to about 1024. It is automatically readjusted to half of bufsize if it is
742 larger than that. This means you don't have to worry about it when changing
743 bufsize.
744
Willy Tarreaue803de22010-01-21 17:43:04 +0100745tune.rcvbuf.client <number>
746tune.rcvbuf.server <number>
747 Forces the kernel socket receive buffer size on the client or the server side
748 to the specified value in bytes. This value applies to all TCP/HTTP frontends
749 and backends. It should normally never be set, and the default size (0) lets
750 the kernel autotune this value depending on the amount of available memory.
751 However it can sometimes help to set it to very low values (eg: 4096) in
752 order to save kernel memory by preventing it from buffering too large amounts
753 of received data. Lower values will significantly increase CPU usage though.
754
755tune.sndbuf.client <number>
756tune.sndbuf.server <number>
757 Forces the kernel socket send buffer size on the client or the server side to
758 the specified value in bytes. This value applies to all TCP/HTTP frontends
759 and backends. It should normally never be set, and the default size (0) lets
760 the kernel autotune this value depending on the amount of available memory.
761 However it can sometimes help to set it to very low values (eg: 4096) in
762 order to save kernel memory by preventing it from buffering too large amounts
763 of received data. Lower values will significantly increase CPU usage though.
764 Another use case is to prevent write timeouts with extremely slow clients due
765 to the kernel waiting for a large part of the buffer to be read before
766 notifying haproxy again.
767
Willy Tarreau6a06a402007-07-15 20:15:28 +0200768
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007693.3. Debugging
770--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200771
772debug
773 Enables debug mode which dumps to stdout all exchanges, and disables forking
774 into background. It is the equivalent of the command-line argument "-d". It
775 should never be used in a production configuration since it may prevent full
776 system startup.
777
778quiet
779 Do not display any message during startup. It is equivalent to the command-
780 line argument "-q".
781
Emeric Brunf099e792010-09-27 12:05:28 +0200782
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007833.4. Userlists
784--------------
785It is possible to control access to frontend/backend/listen sections or to
786http stats by allowing only authenticated and authorized users. To do this,
787it is required to create at least one userlist and to define users.
788
789userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100790 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100791 used to store authentication & authorization data for independent customers.
792
793group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +0100794 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100795 attach users to this group by using a comma separated list of names
796 proceeded by "users" keyword.
797
Cyril Bontéf0c60612010-02-06 14:44:47 +0100798user <username> [password|insecure-password <password>]
799 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100800 Adds user <username> to the current userlist. Both secure (encrypted) and
801 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +0100802 evaluated using the crypt(3) function so depending of the system's
803 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100804 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
805 DES-based method of crypting passwords.
806
807
808 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +0100809 userlist L1
810 group G1 users tiger,scott
811 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100812
Cyril Bontéf0c60612010-02-06 14:44:47 +0100813 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
814 user scott insecure-password elgato
815 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100816
Cyril Bontéf0c60612010-02-06 14:44:47 +0100817 userlist L2
818 group G1
819 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100820
Cyril Bontéf0c60612010-02-06 14:44:47 +0100821 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
822 user scott insecure-password elgato groups G1,G2
823 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100824
825 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200826
Emeric Brunf099e792010-09-27 12:05:28 +0200827
8283.5. Peers
829--------------
830It is possible to synchronize server entries in stick tables between several
831haproxy instances over TCP connections in a multi-master fashion. Each instance
832pushes its local updates and insertions to remote peers. Server IDs are used to
833identify servers remotely, so it is important that configurations look similar
834or at least that the same IDs are forced on each server on all participants.
835Interrupted exchanges are automatically detected and recovered from the last
836known point. In addition, during a soft restart, the old process connects to
837the new one using such a TCP connection to push all its entries before the new
838process tries to connect to other peers. That ensures very fast replication
839during a reload, it typically takes a fraction of a second even for large
840tables.
841
842peers <peersect>
843 Creates a new peer list with name <peersect>. It is an independant section,
844 which is referenced by one or more stick-tables.
845
846peer <peername> <ip>:<port>
847 Defines a peer inside a peers section.
848 If <peername> is set to the local peer name (by default hostname, or forced
849 using "-L" command line option), haproxy will listen for incoming remote peer
850 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
851 to join the remote peer, and <peername> is used at the protocol level to
852 identify and validate the remote peer on the server side.
853
854 During a soft restart, local peer <ip>:<port> is used by the old instance to
855 connect the new one and initiate a complete replication (teaching process).
856
857 It is strongly recommended to have the exact same peers declaration on all
858 peers and to only rely on the "-L" command line argument to change the local
859 peer name. This makes it easier to maintain coherent configuration files
860 across all peers.
861
862Example:
863 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100864 peer haproxy1 192.168.0.1:1024
865 peer haproxy2 192.168.0.2:1024
866 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +0200867
868 backend mybackend
869 mode tcp
870 balance roundrobin
871 stick-table type ip size 20k peers mypeers
872 stick on src
873
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100874 server srv1 192.168.0.30:80
875 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +0200876
877
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008784. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +0200879----------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100880
Willy Tarreau6a06a402007-07-15 20:15:28 +0200881Proxy configuration can be located in a set of sections :
882 - defaults <name>
883 - frontend <name>
884 - backend <name>
885 - listen <name>
886
887A "defaults" section sets default parameters for all other sections following
888its declaration. Those default parameters are reset by the next "defaults"
889section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +0100890section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200891
892A "frontend" section describes a set of listening sockets accepting client
893connections.
894
895A "backend" section describes a set of servers to which the proxy will connect
896to forward incoming connections.
897
898A "listen" section defines a complete proxy with its frontend and backend
899parts combined in one section. It is generally useful for TCP-only traffic.
900
Willy Tarreau0ba27502007-12-24 16:55:16 +0100901All proxy names must be formed from upper and lower case letters, digits,
902'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
903case-sensitive, which means that "www" and "WWW" are two different proxies.
904
905Historically, all proxy names could overlap, it just caused troubles in the
906logs. Since the introduction of content switching, it is mandatory that two
907proxies with overlapping capabilities (frontend/backend) have different names.
908However, it is still permitted that a frontend and a backend share the same
909name, as this configuration seems to be commonly encountered.
910
911Right now, two major proxy modes are supported : "tcp", also known as layer 4,
912and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100913bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +0100914protocol, and can interact with it by allowing, blocking, switching, adding,
915modifying, or removing arbitrary contents in requests or responses, based on
916arbitrary criteria.
917
Willy Tarreau0ba27502007-12-24 16:55:16 +0100918
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009194.1. Proxy keywords matrix
920--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100921
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200922The following list of keywords is supported. Most of them may only be used in a
923limited set of section types. Some of them are marked as "deprecated" because
924they are inherited from an old syntax which may be confusing or functionally
925limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100926marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200927option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +0200928and must be disabled for a specific instance. Such options may also be prefixed
929with "default" in order to restore default settings regardless of what has been
930specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100931
Willy Tarreau6a06a402007-07-15 20:15:28 +0200932
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100933 keyword defaults frontend listen backend
934------------------------------------+----------+----------+---------+---------
935acl - X X X
936appsession - - X X
937backlog X X X -
938balance X - X X
939bind - X X -
940bind-process X X X X
941block - X X X
942capture cookie - X X -
943capture request header - X X -
944capture response header - X X -
945clitimeout (deprecated) X X X -
946contimeout (deprecated) X - X X
947cookie X - X X
948default-server X - X X
949default_backend X X X -
950description - X X X
951disabled X X X X
952dispatch - - X X
953enabled X X X X
954errorfile X X X X
955errorloc X X X X
956errorloc302 X X X X
957-- keyword -------------------------- defaults - frontend - listen -- backend -
958errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +0200959force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100960fullconn X - X X
961grace X X X X
962hash-type X - X X
963http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +0100964http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +0200965http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100966http-request - X X X
967id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +0200968ignore-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100969log X X X X
970maxconn X X X -
971mode X X X X
972monitor fail - X X -
973monitor-net X X X -
974monitor-uri X X X -
975option abortonclose (*) X - X X
976option accept-invalid-http-request (*) X X X -
977option accept-invalid-http-response (*) X - X X
978option allbackups (*) X - X X
979option checkcache (*) X - X X
980option clitcpka (*) X X X -
981option contstats (*) X X X -
982option dontlog-normal (*) X X X -
983option dontlognull (*) X X X -
984option forceclose (*) X X X X
985-- keyword -------------------------- defaults - frontend - listen -- backend -
986option forwardfor X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +0200987option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +0200988option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100989option http-server-close (*) X X X X
990option http-use-proxy-header (*) X X X -
991option httpchk X - X X
992option httpclose (*) X X X X
993option httplog X X X X
994option http_proxy (*) X X X X
995option independant-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +0200996option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100997option log-health-checks (*) X - X X
998option log-separate-errors (*) X X X -
999option logasap (*) X X X -
1000option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001001option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001002option nolinger (*) X X X X
1003option originalto X X X X
1004option persist (*) X - X X
1005option redispatch (*) X - X X
1006option smtpchk X - X X
1007option socket-stats (*) X X X -
1008option splice-auto (*) X X X X
1009option splice-request (*) X X X X
1010option splice-response (*) X X X X
1011option srvtcpka (*) X - X X
1012option ssl-hello-chk X - X X
1013-- keyword -------------------------- defaults - frontend - listen -- backend -
1014option tcp-smart-accept (*) X X X -
1015option tcp-smart-connect (*) X - X X
1016option tcpka X X X X
1017option tcplog X X X X
1018option transparent (*) X - X X
1019persist rdp-cookie X - X X
1020rate-limit sessions X X X -
1021redirect - X X X
1022redisp (deprecated) X - X X
1023redispatch (deprecated) X - X X
1024reqadd - X X X
1025reqallow - X X X
1026reqdel - X X X
1027reqdeny - X X X
1028reqiallow - X X X
1029reqidel - X X X
1030reqideny - X X X
1031reqipass - X X X
1032reqirep - X X X
1033reqisetbe - X X X
1034reqitarpit - X X X
1035reqpass - X X X
1036reqrep - X X X
1037-- keyword -------------------------- defaults - frontend - listen -- backend -
1038reqsetbe - X X X
1039reqtarpit - X X X
1040retries X - X X
1041rspadd - X X X
1042rspdel - X X X
1043rspdeny - X X X
1044rspidel - X X X
1045rspideny - X X X
1046rspirep - X X X
1047rsprep - X X X
1048server - - X X
1049source X - X X
1050srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001051stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001052stats auth X - X X
1053stats enable X - X X
1054stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001055stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001056stats realm X - X X
1057stats refresh X - X X
1058stats scope X - X X
1059stats show-desc X - X X
1060stats show-legends X - X X
1061stats show-node X - X X
1062stats uri X - X X
1063-- keyword -------------------------- defaults - frontend - listen -- backend -
1064stick match - - X X
1065stick on - - X X
1066stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001067stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001068stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001069tcp-request connection - X X -
1070tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001071tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001072tcp-response content - - X X
1073tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001074timeout check X - X X
1075timeout client X X X -
1076timeout clitimeout (deprecated) X X X -
1077timeout connect X - X X
1078timeout contimeout (deprecated) X - X X
1079timeout http-keep-alive X X X X
1080timeout http-request X X X X
1081timeout queue X - X X
1082timeout server X - X X
1083timeout srvtimeout (deprecated) X - X X
1084timeout tarpit X X X X
1085transparent (deprecated) X - X X
1086use_backend - X X -
1087------------------------------------+----------+----------+---------+---------
1088 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001089
Willy Tarreau0ba27502007-12-24 16:55:16 +01001090
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010914.2. Alphabetically sorted keywords reference
1092---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001093
1094This section provides a description of each keyword and its usage.
1095
1096
1097acl <aclname> <criterion> [flags] [operator] <value> ...
1098 Declare or complete an access list.
1099 May be used in sections : defaults | frontend | listen | backend
1100 no | yes | yes | yes
1101 Example:
1102 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1103 acl invalid_src src_port 0:1023
1104 acl local_dst hdr(host) -i localhost
1105
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001106 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001107
1108
Cyril Bontéb21570a2009-11-29 20:04:48 +01001109appsession <cookie> len <length> timeout <holdtime>
1110 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001111 Define session stickiness on an existing application cookie.
1112 May be used in sections : defaults | frontend | listen | backend
1113 no | no | yes | yes
1114 Arguments :
1115 <cookie> this is the name of the cookie used by the application and which
1116 HAProxy will have to learn for each new session.
1117
Cyril Bontéb21570a2009-11-29 20:04:48 +01001118 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001119 checked in each cookie value.
1120
1121 <holdtime> this is the time after which the cookie will be removed from
1122 memory if unused. If no unit is specified, this time is in
1123 milliseconds.
1124
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001125 request-learn
1126 If this option is specified, then haproxy will be able to learn
1127 the cookie found in the request in case the server does not
1128 specify any in response. This is typically what happens with
1129 PHPSESSID cookies, or when haproxy's session expires before
1130 the application's session and the correct server is selected.
1131 It is recommended to specify this option to improve reliability.
1132
Cyril Bontéb21570a2009-11-29 20:04:48 +01001133 prefix When this option is specified, haproxy will match on the cookie
1134 prefix (or URL parameter prefix). The appsession value is the
1135 data following this prefix.
1136
1137 Example :
1138 appsession ASPSESSIONID len 64 timeout 3h prefix
1139
1140 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1141 the appsession value will be XXXX=XXXXX.
1142
1143 mode This option allows to change the URL parser mode.
1144 2 modes are currently supported :
1145 - path-parameters :
1146 The parser looks for the appsession in the path parameters
1147 part (each parameter is separated by a semi-colon), which is
1148 convenient for JSESSIONID for example.
1149 This is the default mode if the option is not set.
1150 - query-string :
1151 In this mode, the parser will look for the appsession in the
1152 query string.
1153
Willy Tarreau0ba27502007-12-24 16:55:16 +01001154 When an application cookie is defined in a backend, HAProxy will check when
1155 the server sets such a cookie, and will store its value in a table, and
1156 associate it with the server's identifier. Up to <length> characters from
1157 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001158 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1159 the mode used). If a known value is found, the client will be directed to the
1160 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001161 applied. Cookies are automatically removed from memory when they have been
1162 unused for a duration longer than <holdtime>.
1163
1164 The definition of an application cookie is limited to one per backend.
1165
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001166 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1167 unless you know what you do : memory is not shared between the
1168 processes, which can result in random behaviours.
1169
Willy Tarreau0ba27502007-12-24 16:55:16 +01001170 Example :
1171 appsession JSESSIONID len 52 timeout 3h
1172
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001173 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1174 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001175
1176
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001177backlog <conns>
1178 Give hints to the system about the approximate listen backlog desired size
1179 May be used in sections : defaults | frontend | listen | backend
1180 yes | yes | yes | no
1181 Arguments :
1182 <conns> is the number of pending connections. Depending on the operating
1183 system, it may represent the number of already acknowledged
1184 connections, of non-acknowledged ones, or both.
1185
1186 In order to protect against SYN flood attacks, one solution is to increase
1187 the system's SYN backlog size. Depending on the system, sometimes it is just
1188 tunable via a system parameter, sometimes it is not adjustable at all, and
1189 sometimes the system relies on hints given by the application at the time of
1190 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1191 to the listen() syscall. On systems which can make use of this value, it can
1192 sometimes be useful to be able to specify a different value, hence this
1193 backlog parameter.
1194
1195 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1196 used as a hint and the system accepts up to the smallest greater power of
1197 two, and never more than some limits (usually 32768).
1198
1199 See also : "maxconn" and the target operating system's tuning guide.
1200
1201
Willy Tarreau0ba27502007-12-24 16:55:16 +01001202balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001203balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001204 Define the load balancing algorithm to be used in a backend.
1205 May be used in sections : defaults | frontend | listen | backend
1206 yes | no | yes | yes
1207 Arguments :
1208 <algorithm> is the algorithm used to select a server when doing load
1209 balancing. This only applies when no persistence information
1210 is available, or when a connection is redispatched to another
1211 server. <algorithm> may be one of the following :
1212
1213 roundrobin Each server is used in turns, according to their weights.
1214 This is the smoothest and fairest algorithm when the server's
1215 processing time remains equally distributed. This algorithm
1216 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001217 on the fly for slow starts for instance. It is limited by
1218 design to 4128 active servers per backend. Note that in some
1219 large farms, when a server becomes up after having been down
1220 for a very short time, it may sometimes take a few hundreds
1221 requests for it to be re-integrated into the farm and start
1222 receiving traffic. This is normal, though very rare. It is
1223 indicated here in case you would have the chance to observe
1224 it, so that you don't worry.
1225
1226 static-rr Each server is used in turns, according to their weights.
1227 This algorithm is as similar to roundrobin except that it is
1228 static, which means that changing a server's weight on the
1229 fly will have no effect. On the other hand, it has no design
1230 limitation on the number of servers, and when a server goes
1231 up, it is always immediately reintroduced into the farm, once
1232 the full map is recomputed. It also uses slightly less CPU to
1233 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001234
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001235 leastconn The server with the lowest number of connections receives the
1236 connection. Round-robin is performed within groups of servers
1237 of the same load to ensure that all servers will be used. Use
1238 of this algorithm is recommended where very long sessions are
1239 expected, such as LDAP, SQL, TSE, etc... but is not very well
1240 suited for protocols using short sessions such as HTTP. This
1241 algorithm is dynamic, which means that server weights may be
1242 adjusted on the fly for slow starts for instance.
1243
Willy Tarreau0ba27502007-12-24 16:55:16 +01001244 source The source IP address is hashed and divided by the total
1245 weight of the running servers to designate which server will
1246 receive the request. This ensures that the same client IP
1247 address will always reach the same server as long as no
1248 server goes down or up. If the hash result changes due to the
1249 number of running servers changing, many clients will be
1250 directed to a different server. This algorithm is generally
1251 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001252 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001253 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001254 static by default, which means that changing a server's
1255 weight on the fly will have no effect, but this can be
1256 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001257
1258 uri The left part of the URI (before the question mark) is hashed
1259 and divided by the total weight of the running servers. The
1260 result designates which server will receive the request. This
1261 ensures that a same URI will always be directed to the same
1262 server as long as no server goes up or down. This is used
1263 with proxy caches and anti-virus proxies in order to maximize
1264 the cache hit rate. Note that this algorithm may only be used
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001265 in an HTTP backend. This algorithm is static by default,
1266 which means that changing a server's weight on the fly will
1267 have no effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001268
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001269 This algorithm support two optional parameters "len" and
1270 "depth", both followed by a positive integer number. These
1271 options may be helpful when it is needed to balance servers
1272 based on the beginning of the URI only. The "len" parameter
1273 indicates that the algorithm should only consider that many
1274 characters at the beginning of the URI to compute the hash.
1275 Note that having "len" set to 1 rarely makes sense since most
1276 URIs start with a leading "/".
1277
1278 The "depth" parameter indicates the maximum directory depth
1279 to be used to compute the hash. One level is counted for each
1280 slash in the request. If both parameters are specified, the
1281 evaluation stops when either is reached.
1282
Willy Tarreau0ba27502007-12-24 16:55:16 +01001283 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001284 the query string of each HTTP GET request.
1285
1286 If the modifier "check_post" is used, then an HTTP POST
1287 request entity will be searched for the parameter argument,
Willy Tarreau61a21a32011-03-01 20:35:49 +01001288 when it is not found in a query string after a question mark
1289 ('?') in the URL. Optionally, specify a number of octets to
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001290 wait for before attempting to search the message body. If the
1291 entity can not be searched, then round robin is used for each
1292 request. For instance, if your clients always send the LB
1293 parameter in the first 128 bytes, then specify that. The
1294 default is 48. The entity data will not be scanned until the
1295 required number of octets have arrived at the gateway, this
1296 is the minimum of: (default/max_wait, Content-Length or first
1297 chunk length). If Content-Length is missing or zero, it does
1298 not need to wait for more data than the client promised to
1299 send. When Content-Length is present and larger than
1300 <max_wait>, then waiting is limited to <max_wait> and it is
1301 assumed that this will be enough data to search for the
1302 presence of the parameter. In the unlikely event that
1303 Transfer-Encoding: chunked is used, only the first chunk is
1304 scanned. Parameter values separated by a chunk boundary, may
1305 be randomly balanced if at all.
1306
1307 If the parameter is found followed by an equal sign ('=') and
1308 a value, then the value is hashed and divided by the total
1309 weight of the running servers. The result designates which
1310 server will receive the request.
1311
1312 This is used to track user identifiers in requests and ensure
1313 that a same user ID will always be sent to the same server as
1314 long as no server goes up or down. If no value is found or if
1315 the parameter is not found, then a round robin algorithm is
1316 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001317 backend. This algorithm is static by default, which means
1318 that changing a server's weight on the fly will have no
1319 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001320
Benoitaffb4812009-03-25 13:02:10 +01001321 hdr(name) The HTTP header <name> will be looked up in each HTTP request.
1322 Just as with the equivalent ACL 'hdr()' function, the header
1323 name in parenthesis is not case sensitive. If the header is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001324 absent or if it does not contain any value, the roundrobin
Benoitaffb4812009-03-25 13:02:10 +01001325 algorithm is applied instead.
1326
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001327 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001328 reducing the hash algorithm to the main domain part with some
1329 specific headers such as 'Host'. For instance, in the Host
1330 value "haproxy.1wt.eu", only "1wt" will be considered.
1331
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001332 This algorithm is static by default, which means that
1333 changing a server's weight on the fly will have no effect,
1334 but this can be changed using "hash-type".
1335
Emeric Brun736aa232009-06-30 17:56:00 +02001336 rdp-cookie
1337 rdp-cookie(name)
1338 The RDP cookie <name> (or "mstshash" if omitted) will be
1339 looked up and hashed for each incoming TCP request. Just as
1340 with the equivalent ACL 'req_rdp_cookie()' function, the name
1341 is not case-sensitive. This mechanism is useful as a degraded
1342 persistence mode, as it makes it possible to always send the
1343 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001344 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001345 used instead.
1346
1347 Note that for this to work, the frontend must ensure that an
1348 RDP cookie is already present in the request buffer. For this
1349 you must use 'tcp-request content accept' rule combined with
1350 a 'req_rdp_cookie_cnt' ACL.
1351
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001352 This algorithm is static by default, which means that
1353 changing a server's weight on the fly will have no effect,
1354 but this can be changed using "hash-type".
1355
Simon Hormanab814e02011-06-24 14:50:20 +09001356 See also the rdp_cookie pattern fetch function.
1357
Willy Tarreau0ba27502007-12-24 16:55:16 +01001358 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001359 algorithms. Right now, only "url_param" and "uri" support an
1360 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001361
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001362 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001363 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001364
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001365 The load balancing algorithm of a backend is set to roundrobin when no other
1366 algorithm, mode nor option have been set. The algorithm may only be set once
1367 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001368
1369 Examples :
1370 balance roundrobin
1371 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001372 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001373 balance hdr(User-Agent)
1374 balance hdr(host)
1375 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001376
1377 Note: the following caveats and limitations on using the "check_post"
1378 extension with "url_param" must be considered :
1379
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001380 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001381 to determine if the parameters will be found in the body or entity which
1382 may contain binary data. Therefore another method may be required to
1383 restrict consideration of POST requests that have no URL parameters in
1384 the body. (see acl reqideny http_end)
1385
1386 - using a <max_wait> value larger than the request buffer size does not
1387 make sense and is useless. The buffer size is set at build time, and
1388 defaults to 16 kB.
1389
1390 - Content-Encoding is not supported, the parameter search will probably
1391 fail; and load balancing will fall back to Round Robin.
1392
1393 - Expect: 100-continue is not supported, load balancing will fall back to
1394 Round Robin.
1395
1396 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1397 If the entire parameter value is not present in the first chunk, the
1398 selection of server is undefined (actually, defined by how little
1399 actually appeared in the first chunk).
1400
1401 - This feature does not support generation of a 100, 411 or 501 response.
1402
1403 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001404 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001405 white space or control characters are found, indicating the end of what
1406 might be a URL parameter list. This is probably not a concern with SGML
1407 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001408
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001409 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1410 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001411
1412
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001413bind [<address>]:<port_range> [, ...]
1414bind [<address>]:<port_range> [, ...] interface <interface>
1415bind [<address>]:<port_range> [, ...] mss <maxseg>
1416bind [<address>]:<port_range> [, ...] transparent
1417bind [<address>]:<port_range> [, ...] id <id>
1418bind [<address>]:<port_range> [, ...] name <name>
1419bind [<address>]:<port_range> [, ...] defer-accept
Willy Tarreau71c814e2010-10-29 21:56:16 +02001420bind [<address>]:<port_range> [, ...] accept-proxy
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001421bind /<path> [, ...]
1422bind /<path> [, ...] mode <mode>
1423bind /<path> [, ...] [ user <user> | uid <uid> ]
1424bind /<path> [, ...] [ group <user> | gid <gid> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001425 Define one or several listening addresses and/or ports in a frontend.
1426 May be used in sections : defaults | frontend | listen | backend
1427 no | yes | yes | no
1428 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001429 <address> is optional and can be a host name, an IPv4 address, an IPv6
1430 address, or '*'. It designates the address the frontend will
1431 listen on. If unset, all IPv4 addresses of the system will be
1432 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001433 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001434
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001435 <port_range> is either a unique TCP port, or a port range for which the
1436 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001437 above. The port is mandatory for TCP listeners. Note that in
1438 the case of an IPv6 address, the port is always the number
1439 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001440 - a numerical port (ex: '80')
1441 - a dash-delimited ports range explicitly stating the lower
1442 and upper bounds (ex: '2000-2100') which are included in
1443 the range.
1444
1445 Particular care must be taken against port ranges, because
1446 every <address:port> couple consumes one socket (= a file
1447 descriptor), so it's easy to consume lots of descriptors
1448 with a simple range, and to run out of sockets. Also, each
1449 <address:port> couple must be used only once among all
1450 instances running on a same system. Please note that binding
1451 to ports lower than 1024 generally require particular
1452 privileges to start the program, which are independant of
1453 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001454
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001455 <path> is a UNIX socket path beginning with a slash ('/'). This is
1456 alternative to the TCP listening port. Haproxy will then
1457 receive UNIX connections on the socket located at this place.
1458 The path must begin with a slash and by default is absolute.
1459 It can be relative to the prefix defined by "unix-bind" in
1460 the global section. Note that the total length of the prefix
1461 followed by the socket path cannot exceed some system limits
1462 for UNIX sockets, which commonly are set to 107 characters.
1463
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001464 <interface> is an optional physical interface name. This is currently
1465 only supported on Linux. The interface must be a physical
1466 interface, not an aliased interface. When specified, all
1467 addresses on the same line will only be accepted if the
1468 incoming packet physically come through the designated
1469 interface. It is also possible to bind multiple frontends to
1470 the same address if they are bound to different interfaces.
1471 Note that binding to a physical interface requires root
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001472 privileges. This parameter is only compatible with TCP
1473 sockets.
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001474
Willy Tarreaube1b9182009-06-14 18:48:19 +02001475 <maxseg> is an optional TCP Maximum Segment Size (MSS) value to be
1476 advertised on incoming connections. This can be used to force
1477 a lower MSS for certain specific ports, for instance for
1478 connections passing through a VPN. Note that this relies on a
1479 kernel feature which is theorically supported under Linux but
1480 was buggy in all versions prior to 2.6.28. It may or may not
Willy Tarreau48a7e722010-12-24 15:26:39 +01001481 work on other operating systems. It may also not change the
1482 advertised value but change the effective size of outgoing
1483 segments. The commonly advertised value on Ethernet networks
1484 is 1460 = 1500(MTU) - 40(IP+TCP). If this value is positive,
1485 it will be used as the advertised MSS. If it is negative, it
1486 will indicate by how much to reduce the incoming connection's
1487 advertised MSS for outgoing segments. This parameter is only
1488 compatible with TCP sockets.
Willy Tarreaube1b9182009-06-14 18:48:19 +02001489
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02001490 <id> is a persistent value for socket ID. Must be positive and
1491 unique in the proxy. An unused value will automatically be
1492 assigned if unset. Can only be used when defining only a
1493 single socket.
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02001494
1495 <name> is an optional name provided for stats
1496
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001497 <mode> is the octal mode used to define access permissions on the
1498 UNIX socket. It can also be set by default in the global
1499 section's "unix-bind" statement. Note that some platforms
1500 simply ignore this.
1501
1502 <user> is the name of user that will be marked owner of the UNIX
1503 socket. It can also be set by default in the global
1504 section's "unix-bind" statement. Note that some platforms
1505 simply ignore this.
1506
1507 <group> is the name of a group that will be used to create the UNIX
1508 socket. It can also be set by default in the global section's
1509 "unix-bind" statement. Note that some platforms simply ignore
1510 this.
1511
1512 <uid> is the uid of user that will be marked owner of the UNIX
1513 socket. It can also be set by default in the global section's
1514 "unix-bind" statement. Note that some platforms simply ignore
1515 this.
1516
1517 <gid> is the gid of a group that will be used to create the UNIX
1518 socket. It can also be set by default in the global section's
1519 "unix-bind" statement. Note that some platforms simply ignore
1520 this.
1521
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001522 transparent is an optional keyword which is supported only on certain
1523 Linux kernels. It indicates that the addresses will be bound
1524 even if they do not belong to the local machine. Any packet
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001525 targeting any of these addresses will be caught just as if
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001526 the address was locally configured. This normally requires
1527 that IP forwarding is enabled. Caution! do not use this with
1528 the default address '*', as it would redirect any traffic for
1529 the specified port. This keyword is available only when
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001530 HAProxy is built with USE_LINUX_TPROXY=1. This parameter is
1531 only compatible with TCP sockets.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001532
Willy Tarreau59f89202010-10-02 11:54:00 +02001533 defer-accept is an optional keyword which is supported only on certain
Willy Tarreaucb6cd432009-10-13 07:34:14 +02001534 Linux kernels. It states that a connection will only be
1535 accepted once some data arrive on it, or at worst after the
1536 first retransmit. This should be used only on protocols for
1537 which the client talks first (eg: HTTP). It can slightly
1538 improve performance by ensuring that most of the request is
1539 already available when the connection is accepted. On the
1540 other hand, it will not be able to detect connections which
1541 don't talk. It is important to note that this option is
1542 broken in all kernels up to 2.6.31, as the connection is
1543 never accepted until the client talks. This can cause issues
1544 with front firewalls which would see an established
1545 connection while the proxy will only see it in SYN_RECV.
1546
Willy Tarreau71c814e2010-10-29 21:56:16 +02001547 accept-proxy is an optional keyword which enforces use of the PROXY
1548 protocol over any connection accepted by this listener. The
1549 PROXY protocol dictates the layer 3/4 addresses of the
1550 incoming connection to be used everywhere an address is used,
1551 with the only exception of "tcp-request connection" rules
1552 which will only see the real connection address. Logs will
1553 reflect the addresses indicated in the protocol, unless it is
1554 violated, in which case the real address will still be used.
1555 This keyword combined with support from external components
1556 can be used as an efficient and reliable alternative to the
1557 X-Forwarded-For mechanism which is not always reliable and
1558 not even always usable.
1559
Willy Tarreau0ba27502007-12-24 16:55:16 +01001560 It is possible to specify a list of address:port combinations delimited by
1561 commas. The frontend will then listen on all of these addresses. There is no
1562 fixed limit to the number of addresses and ports which can be listened on in
1563 a frontend, as well as there is no limit to the number of "bind" statements
1564 in a frontend.
1565
1566 Example :
1567 listen http_proxy
1568 bind :80,:443
1569 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001570 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001571
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001572 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreau71c814e2010-10-29 21:56:16 +02001573 documentation.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001574
1575
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001576bind-process [ all | odd | even | <number 1-32> ] ...
1577 Limit visibility of an instance to a certain set of processes numbers.
1578 May be used in sections : defaults | frontend | listen | backend
1579 yes | yes | yes | yes
1580 Arguments :
1581 all All process will see this instance. This is the default. It
1582 may be used to override a default value.
1583
1584 odd This instance will be enabled on processes 1,3,5,...31. This
1585 option may be combined with other numbers.
1586
1587 even This instance will be enabled on processes 2,4,6,...32. This
1588 option may be combined with other numbers. Do not use it
1589 with less than 2 processes otherwise some instances might be
1590 missing from all processes.
1591
1592 number The instance will be enabled on this process number, between
1593 1 and 32. You must be careful not to reference a process
1594 number greater than the configured global.nbproc, otherwise
1595 some instances might be missing from all processes.
1596
1597 This keyword limits binding of certain instances to certain processes. This
1598 is useful in order not to have too many processes listening to the same
1599 ports. For instance, on a dual-core machine, it might make sense to set
1600 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1601 and 'even' instances.
1602
1603 At the moment, it is not possible to reference more than 32 processes using
1604 this keyword, but this should be more than enough for most setups. Please
1605 note that 'all' really means all processes and is not limited to the first
1606 32.
1607
1608 If some backends are referenced by frontends bound to other processes, the
1609 backend automatically inherits the frontend's processes.
1610
1611 Example :
1612 listen app_ip1
1613 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001614 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001615
1616 listen app_ip2
1617 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001618 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001619
1620 listen management
1621 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001622 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001623
1624 See also : "nbproc" in global section.
1625
1626
Willy Tarreau0ba27502007-12-24 16:55:16 +01001627block { if | unless } <condition>
1628 Block a layer 7 request if/unless a condition is matched
1629 May be used in sections : defaults | frontend | listen | backend
1630 no | yes | yes | yes
1631
1632 The HTTP request will be blocked very early in the layer 7 processing
1633 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001634 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001635 typically used to deny access to certain sensible resources if some
1636 conditions are met or not met. There is no fixed limit to the number of
1637 "block" statements per instance.
1638
1639 Example:
1640 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1641 acl invalid_src src_port 0:1023
1642 acl local_dst hdr(host) -i localhost
1643 block if invalid_src || local_dst
1644
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001645 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001646
1647
1648capture cookie <name> len <length>
1649 Capture and log a cookie in the request and in the response.
1650 May be used in sections : defaults | frontend | listen | backend
1651 no | yes | yes | no
1652 Arguments :
1653 <name> is the beginning of the name of the cookie to capture. In order
1654 to match the exact name, simply suffix the name with an equal
1655 sign ('='). The full name will appear in the logs, which is
1656 useful with application servers which adjust both the cookie name
1657 and value (eg: ASPSESSIONXXXXX).
1658
1659 <length> is the maximum number of characters to report in the logs, which
1660 include the cookie name, the equal sign and the value, all in the
1661 standard "name=value" form. The string will be truncated on the
1662 right if it exceeds <length>.
1663
1664 Only the first cookie is captured. Both the "cookie" request headers and the
1665 "set-cookie" response headers are monitored. This is particularly useful to
1666 check for application bugs causing session crossing or stealing between
1667 users, because generally the user's cookies can only change on a login page.
1668
1669 When the cookie was not presented by the client, the associated log column
1670 will report "-". When a request does not cause a cookie to be assigned by the
1671 server, a "-" is reported in the response column.
1672
1673 The capture is performed in the frontend only because it is necessary that
1674 the log format does not change for a given frontend depending on the
1675 backends. This may change in the future. Note that there can be only one
1676 "capture cookie" statement in a frontend. The maximum capture length is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001677 configured in the sources by default to 64 characters. It is not possible to
Willy Tarreau0ba27502007-12-24 16:55:16 +01001678 specify a capture in a "defaults" section.
1679
1680 Example:
1681 capture cookie ASPSESSION len 32
1682
1683 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001684 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001685
1686
1687capture request header <name> len <length>
1688 Capture and log the first occurrence of the specified request header.
1689 May be used in sections : defaults | frontend | listen | backend
1690 no | yes | yes | no
1691 Arguments :
1692 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001693 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001694 appear in the requests, with the first letter of each word in
1695 upper case. The header name will not appear in the logs, only the
1696 value is reported, but the position in the logs is respected.
1697
1698 <length> is the maximum number of characters to extract from the value and
1699 report in the logs. The string will be truncated on the right if
1700 it exceeds <length>.
1701
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001702 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001703 value will be added to the logs between braces ('{}'). If multiple headers
1704 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001705 in the same order they were declared in the configuration. Non-existent
1706 headers will be logged just as an empty string. Common uses for request
1707 header captures include the "Host" field in virtual hosting environments, the
1708 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001709 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001710 environments to find where the request came from.
1711
1712 Note that when capturing headers such as "User-agent", some spaces may be
1713 logged, making the log analysis more difficult. Thus be careful about what
1714 you log if you know your log parser is not smart enough to rely on the
1715 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001716
1717 There is no limit to the number of captured request headers, but each capture
1718 is limited to 64 characters. In order to keep log format consistent for a
1719 same frontend, header captures can only be declared in a frontend. It is not
1720 possible to specify a capture in a "defaults" section.
1721
1722 Example:
1723 capture request header Host len 15
1724 capture request header X-Forwarded-For len 15
1725 capture request header Referrer len 15
1726
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001727 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001728 about logging.
1729
1730
1731capture response header <name> len <length>
1732 Capture and log the first occurrence of the specified response header.
1733 May be used in sections : defaults | frontend | listen | backend
1734 no | yes | yes | no
1735 Arguments :
1736 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001737 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001738 appear in the response, with the first letter of each word in
1739 upper case. The header name will not appear in the logs, only the
1740 value is reported, but the position in the logs is respected.
1741
1742 <length> is the maximum number of characters to extract from the value and
1743 report in the logs. The string will be truncated on the right if
1744 it exceeds <length>.
1745
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001746 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001747 result will be added to the logs between braces ('{}') after the captured
1748 request headers. If multiple headers are captured, they will be delimited by
1749 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001750 the configuration. Non-existent headers will be logged just as an empty
1751 string. Common uses for response header captures include the "Content-length"
1752 header which indicates how many bytes are expected to be returned, the
1753 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001754
1755 There is no limit to the number of captured response headers, but each
1756 capture is limited to 64 characters. In order to keep log format consistent
1757 for a same frontend, header captures can only be declared in a frontend. It
1758 is not possible to specify a capture in a "defaults" section.
1759
1760 Example:
1761 capture response header Content-length len 9
1762 capture response header Location len 15
1763
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001764 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001765 about logging.
1766
1767
Cyril Bontéf0c60612010-02-06 14:44:47 +01001768clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001769 Set the maximum inactivity time on the client side.
1770 May be used in sections : defaults | frontend | listen | backend
1771 yes | yes | yes | no
1772 Arguments :
1773 <timeout> is the timeout value is specified in milliseconds by default, but
1774 can be in any other unit if the number is suffixed by the unit,
1775 as explained at the top of this document.
1776
1777 The inactivity timeout applies when the client is expected to acknowledge or
1778 send data. In HTTP mode, this timeout is particularly important to consider
1779 during the first phase, when the client sends the request, and during the
1780 response while it is reading data sent by the server. The value is specified
1781 in milliseconds by default, but can be in any other unit if the number is
1782 suffixed by the unit, as specified at the top of this document. In TCP mode
1783 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1784 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001785 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001786 losses by specifying timeouts that are slightly above multiples of 3 seconds
1787 (eg: 4 or 5 seconds).
1788
1789 This parameter is specific to frontends, but can be specified once for all in
1790 "defaults" sections. This is in fact one of the easiest solutions not to
1791 forget about it. An unspecified timeout results in an infinite timeout, which
1792 is not recommended. Such a usage is accepted and works but reports a warning
1793 during startup because it may results in accumulation of expired sessions in
1794 the system if the system's timeouts are not configured either.
1795
1796 This parameter is provided for compatibility but is currently deprecated.
1797 Please use "timeout client" instead.
1798
Willy Tarreau036fae02008-01-06 13:24:40 +01001799 See also : "timeout client", "timeout http-request", "timeout server", and
1800 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001801
1802
Cyril Bontéf0c60612010-02-06 14:44:47 +01001803contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001804 Set the maximum time to wait for a connection attempt to a server to succeed.
1805 May be used in sections : defaults | frontend | listen | backend
1806 yes | no | yes | yes
1807 Arguments :
1808 <timeout> is the timeout value is specified in milliseconds by default, but
1809 can be in any other unit if the number is suffixed by the unit,
1810 as explained at the top of this document.
1811
1812 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001813 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01001814 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01001815 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
1816 connect timeout also presets the queue timeout to the same value if this one
1817 has not been specified. Historically, the contimeout was also used to set the
1818 tarpit timeout in a listen section, which is not possible in a pure frontend.
1819
1820 This parameter is specific to backends, but can be specified once for all in
1821 "defaults" sections. This is in fact one of the easiest solutions not to
1822 forget about it. An unspecified timeout results in an infinite timeout, which
1823 is not recommended. Such a usage is accepted and works but reports a warning
1824 during startup because it may results in accumulation of failed sessions in
1825 the system if the system's timeouts are not configured either.
1826
1827 This parameter is provided for backwards compatibility but is currently
1828 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
1829 instead.
1830
1831 See also : "timeout connect", "timeout queue", "timeout tarpit",
1832 "timeout server", "contimeout".
1833
1834
Willy Tarreau55165fe2009-05-10 12:02:55 +02001835cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001836 [ postonly ] [ preserve ] [ domain <domain> ]*
Willy Tarreau996a92c2010-10-13 19:30:47 +02001837 [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001838 Enable cookie-based persistence in a backend.
1839 May be used in sections : defaults | frontend | listen | backend
1840 yes | no | yes | yes
1841 Arguments :
1842 <name> is the name of the cookie which will be monitored, modified or
1843 inserted in order to bring persistence. This cookie is sent to
1844 the client via a "Set-Cookie" header in the response, and is
1845 brought back by the client in a "Cookie" header in all requests.
1846 Special care should be taken to choose a name which does not
1847 conflict with any likely application cookie. Also, if the same
1848 backends are subject to be used by the same clients (eg:
1849 HTTP/HTTPS), care should be taken to use different cookie names
1850 between all backends if persistence between them is not desired.
1851
1852 rewrite This keyword indicates that the cookie will be provided by the
1853 server and that haproxy will have to modify its value to set the
1854 server's identifier in it. This mode is handy when the management
1855 of complex combinations of "Set-cookie" and "Cache-control"
1856 headers is left to the application. The application can then
1857 decide whether or not it is appropriate to emit a persistence
1858 cookie. Since all responses should be monitored, this mode only
1859 works in HTTP close mode. Unless the application behaviour is
1860 very complex and/or broken, it is advised not to start with this
1861 mode for new deployments. This keyword is incompatible with
1862 "insert" and "prefix".
1863
1864 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02001865 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001866
Willy Tarreaua79094d2010-08-31 22:54:15 +02001867 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001868 server. When used without the "preserve" option, if the server
1869 emits a cookie with the same name, it will be remove before
1870 processing. For this reason, this mode can be used to upgrade
1871 existing configurations running in the "rewrite" mode. The cookie
1872 will only be a session cookie and will not be stored on the
1873 client's disk. By default, unless the "indirect" option is added,
1874 the server will see the cookies emitted by the client. Due to
1875 caching effects, it is generally wise to add the "nocache" or
1876 "postonly" keywords (see below). The "insert" keyword is not
1877 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001878
1879 prefix This keyword indicates that instead of relying on a dedicated
1880 cookie for the persistence, an existing one will be completed.
1881 This may be needed in some specific environments where the client
1882 does not support more than one single cookie and the application
1883 already needs it. In this case, whenever the server sets a cookie
1884 named <name>, it will be prefixed with the server's identifier
1885 and a delimiter. The prefix will be removed from all client
1886 requests so that the server still finds the cookie it emitted.
1887 Since all requests and responses are subject to being modified,
1888 this mode requires the HTTP close mode. The "prefix" keyword is
1889 not compatible with "rewrite" and "insert".
1890
Willy Tarreaua79094d2010-08-31 22:54:15 +02001891 indirect When this option is specified, no cookie will be emitted to a
1892 client which already has a valid one for the server which has
1893 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001894 it will be removed, unless the "preserve" option is also set. In
1895 "insert" mode, this will additionally remove cookies from the
1896 requests transmitted to the server, making the persistence
1897 mechanism totally transparent from an application point of view.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001898
1899 nocache This option is recommended in conjunction with the insert mode
1900 when there is a cache between the client and HAProxy, as it
1901 ensures that a cacheable response will be tagged non-cacheable if
1902 a cookie needs to be inserted. This is important because if all
1903 persistence cookies are added on a cacheable home page for
1904 instance, then all customers will then fetch the page from an
1905 outer cache and will all share the same persistence cookie,
1906 leading to one server receiving much more traffic than others.
1907 See also the "insert" and "postonly" options.
1908
1909 postonly This option ensures that cookie insertion will only be performed
1910 on responses to POST requests. It is an alternative to the
1911 "nocache" option, because POST responses are not cacheable, so
1912 this ensures that the persistence cookie will never get cached.
1913 Since most sites do not need any sort of persistence before the
1914 first POST which generally is a login request, this is a very
1915 efficient method to optimize caching without risking to find a
1916 persistence cookie in the cache.
1917 See also the "insert" and "nocache" options.
1918
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001919 preserve This option may only be used with "insert" and/or "indirect". It
1920 allows the server to emit the persistence cookie itself. In this
1921 case, if a cookie is found in the response, haproxy will leave it
1922 untouched. This is useful in order to end persistence after a
1923 logout request for instance. For this, the server just has to
1924 emit a cookie with an invalid value (eg: empty) or with a date in
1925 the past. By combining this mechanism with the "disable-on-404"
1926 check option, it is possible to perform a completely graceful
1927 shutdown because users will definitely leave the server after
1928 they logout.
1929
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001930 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001931 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01001932 name. If the domain begins with a dot, the browser is allowed to
1933 use it for any host ending with that name. It is also possible to
1934 specify several domain names by invoking this option multiple
1935 times. Some browsers might have small limits on the number of
1936 domains, so be careful when doing that. For the record, sending
1937 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001938
Willy Tarreau996a92c2010-10-13 19:30:47 +02001939 maxidle This option allows inserted cookies to be ignored after some idle
1940 time. It only works with insert-mode cookies. When a cookie is
1941 sent to the client, the date this cookie was emitted is sent too.
1942 Upon further presentations of this cookie, if the date is older
1943 than the delay indicated by the parameter (in seconds), it will
1944 be ignored. Otherwise, it will be refreshed if needed when the
1945 response is sent to the client. This is particularly useful to
1946 prevent users who never close their browsers from remaining for
1947 too long on the same server (eg: after a farm size change). When
1948 this option is set and a cookie has no date, it is always
1949 accepted, but gets refreshed in the response. This maintains the
1950 ability for admins to access their sites. Cookies that have a
1951 date in the future further than 24 hours are ignored. Doing so
1952 lets admins fix timezone issues without risking kicking users off
1953 the site.
1954
1955 maxlife This option allows inserted cookies to be ignored after some life
1956 time, whether they're in use or not. It only works with insert
1957 mode cookies. When a cookie is first sent to the client, the date
1958 this cookie was emitted is sent too. Upon further presentations
1959 of this cookie, if the date is older than the delay indicated by
1960 the parameter (in seconds), it will be ignored. If the cookie in
1961 the request has no date, it is accepted and a date will be set.
1962 Cookies that have a date in the future further than 24 hours are
1963 ignored. Doing so lets admins fix timezone issues without risking
1964 kicking users off the site. Contrary to maxidle, this value is
1965 not refreshed, only the first visit date counts. Both maxidle and
1966 maxlife may be used at the time. This is particularly useful to
1967 prevent users who never close their browsers from remaining for
1968 too long on the same server (eg: after a farm size change). This
1969 is stronger than the maxidle method in that it forces a
1970 redispatch after some absolute delay.
1971
Willy Tarreau0ba27502007-12-24 16:55:16 +01001972 There can be only one persistence cookie per HTTP backend, and it can be
1973 declared in a defaults section. The value of the cookie will be the value
1974 indicated after the "cookie" keyword in a "server" statement. If no cookie
1975 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001976
Willy Tarreau0ba27502007-12-24 16:55:16 +01001977 Examples :
1978 cookie JSESSIONID prefix
1979 cookie SRV insert indirect nocache
1980 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02001981 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01001982
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02001983 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001984 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001985
Willy Tarreau983e01e2010-01-11 18:42:06 +01001986
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001987default-server [param*]
1988 Change default options for a server in a backend
1989 May be used in sections : defaults | frontend | listen | backend
1990 yes | no | yes | yes
1991 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01001992 <param*> is a list of parameters for this server. The "default-server"
1993 keyword accepts an important number of options and has a complete
1994 section dedicated to it. Please refer to section 5 for more
1995 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001996
Willy Tarreau983e01e2010-01-11 18:42:06 +01001997 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001998 default-server inter 1000 weight 13
1999
2000 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002001
Willy Tarreau983e01e2010-01-11 18:42:06 +01002002
Willy Tarreau0ba27502007-12-24 16:55:16 +01002003default_backend <backend>
2004 Specify the backend to use when no "use_backend" rule has been matched.
2005 May be used in sections : defaults | frontend | listen | backend
2006 yes | yes | yes | no
2007 Arguments :
2008 <backend> is the name of the backend to use.
2009
2010 When doing content-switching between frontend and backends using the
2011 "use_backend" keyword, it is often useful to indicate which backend will be
2012 used when no rule has matched. It generally is the dynamic backend which
2013 will catch all undetermined requests.
2014
Willy Tarreau0ba27502007-12-24 16:55:16 +01002015 Example :
2016
2017 use_backend dynamic if url_dyn
2018 use_backend static if url_css url_img extension_img
2019 default_backend dynamic
2020
Willy Tarreau2769aa02007-12-27 18:26:09 +01002021 See also : "use_backend", "reqsetbe", "reqisetbe"
2022
Willy Tarreau0ba27502007-12-24 16:55:16 +01002023
2024disabled
2025 Disable a proxy, frontend or backend.
2026 May be used in sections : defaults | frontend | listen | backend
2027 yes | yes | yes | yes
2028 Arguments : none
2029
2030 The "disabled" keyword is used to disable an instance, mainly in order to
2031 liberate a listening port or to temporarily disable a service. The instance
2032 will still be created and its configuration will be checked, but it will be
2033 created in the "stopped" state and will appear as such in the statistics. It
2034 will not receive any traffic nor will it send any health-checks or logs. It
2035 is possible to disable many instances at once by adding the "disabled"
2036 keyword in a "defaults" section.
2037
2038 See also : "enabled"
2039
2040
Willy Tarreau5ce94572010-06-07 14:35:41 +02002041dispatch <address>:<port>
2042 Set a default server address
2043 May be used in sections : defaults | frontend | listen | backend
2044 no | no | yes | yes
2045 Arguments : none
2046
2047 <address> is the IPv4 address of the default server. Alternatively, a
2048 resolvable hostname is supported, but this name will be resolved
2049 during start-up.
2050
2051 <ports> is a mandatory port specification. All connections will be sent
2052 to this port, and it is not permitted to use port offsets as is
2053 possible with normal servers.
2054
Willy Tarreau787aed52011-04-15 06:45:37 +02002055 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002056 server can take the connection. In the past it was used to forward non
2057 persistent connections to an auxiliary load balancer. Due to its simple
2058 syntax, it has also been used for simple TCP relays. It is recommended not to
2059 use it for more clarity, and to use the "server" directive instead.
2060
2061 See also : "server"
2062
2063
Willy Tarreau0ba27502007-12-24 16:55:16 +01002064enabled
2065 Enable a proxy, frontend or backend.
2066 May be used in sections : defaults | frontend | listen | backend
2067 yes | yes | yes | yes
2068 Arguments : none
2069
2070 The "enabled" keyword is used to explicitly enable an instance, when the
2071 defaults has been set to "disabled". This is very rarely used.
2072
2073 See also : "disabled"
2074
2075
2076errorfile <code> <file>
2077 Return a file contents instead of errors generated by HAProxy
2078 May be used in sections : defaults | frontend | listen | backend
2079 yes | yes | yes | yes
2080 Arguments :
2081 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002082 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002083
2084 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002085 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002086 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002087 error pages, and to use absolute paths, since files are read
2088 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002089
2090 It is important to understand that this keyword is not meant to rewrite
2091 errors returned by the server, but errors detected and returned by HAProxy.
2092 This is why the list of supported errors is limited to a small set.
2093
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002094 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2095
Willy Tarreau0ba27502007-12-24 16:55:16 +01002096 The files are returned verbatim on the TCP socket. This allows any trick such
2097 as redirections to another URL or site, as well as tricks to clean cookies,
2098 force enable or disable caching, etc... The package provides default error
2099 files returning the same contents as default errors.
2100
Willy Tarreau59140a22009-02-22 12:02:30 +01002101 The files should not exceed the configured buffer size (BUFSIZE), which
2102 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2103 not to put any reference to local contents (eg: images) in order to avoid
2104 loops between the client and HAProxy when all servers are down, causing an
2105 error to be returned instead of an image. For better HTTP compliance, it is
2106 recommended that all header lines end with CR-LF and not LF alone.
2107
Willy Tarreau0ba27502007-12-24 16:55:16 +01002108 The files are read at the same time as the configuration and kept in memory.
2109 For this reason, the errors continue to be returned even when the process is
2110 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002111 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002112 403 status code and interrogating a blocked URL.
2113
2114 See also : "errorloc", "errorloc302", "errorloc303"
2115
Willy Tarreau59140a22009-02-22 12:02:30 +01002116 Example :
2117 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2118 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2119 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2120
Willy Tarreau2769aa02007-12-27 18:26:09 +01002121
2122errorloc <code> <url>
2123errorloc302 <code> <url>
2124 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2125 May be used in sections : defaults | frontend | listen | backend
2126 yes | yes | yes | yes
2127 Arguments :
2128 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002129 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002130
2131 <url> it is the exact contents of the "Location" header. It may contain
2132 either a relative URI to an error page hosted on the same site,
2133 or an absolute URI designating an error page on another site.
2134 Special care should be given to relative URIs to avoid redirect
2135 loops if the URI itself may generate the same error (eg: 500).
2136
2137 It is important to understand that this keyword is not meant to rewrite
2138 errors returned by the server, but errors detected and returned by HAProxy.
2139 This is why the list of supported errors is limited to a small set.
2140
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002141 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2142
Willy Tarreau2769aa02007-12-27 18:26:09 +01002143 Note that both keyword return the HTTP 302 status code, which tells the
2144 client to fetch the designated URL using the same HTTP method. This can be
2145 quite problematic in case of non-GET methods such as POST, because the URL
2146 sent to the client might not be allowed for something other than GET. To
2147 workaround this problem, please use "errorloc303" which send the HTTP 303
2148 status code, indicating to the client that the URL must be fetched with a GET
2149 request.
2150
2151 See also : "errorfile", "errorloc303"
2152
2153
2154errorloc303 <code> <url>
2155 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2156 May be used in sections : defaults | frontend | listen | backend
2157 yes | yes | yes | yes
2158 Arguments :
2159 <code> is the HTTP status code. Currently, HAProxy is capable of
2160 generating codes 400, 403, 408, 500, 502, 503, and 504.
2161
2162 <url> it is the exact contents of the "Location" header. It may contain
2163 either a relative URI to an error page hosted on the same site,
2164 or an absolute URI designating an error page on another site.
2165 Special care should be given to relative URIs to avoid redirect
2166 loops if the URI itself may generate the same error (eg: 500).
2167
2168 It is important to understand that this keyword is not meant to rewrite
2169 errors returned by the server, but errors detected and returned by HAProxy.
2170 This is why the list of supported errors is limited to a small set.
2171
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002172 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2173
Willy Tarreau2769aa02007-12-27 18:26:09 +01002174 Note that both keyword return the HTTP 303 status code, which tells the
2175 client to fetch the designated URL using the same HTTP GET method. This
2176 solves the usual problems associated with "errorloc" and the 302 code. It is
2177 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002178 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002179
2180 See also : "errorfile", "errorloc", "errorloc302"
2181
2182
Willy Tarreau4de91492010-01-22 19:10:05 +01002183force-persist { if | unless } <condition>
2184 Declare a condition to force persistence on down servers
2185 May be used in sections: defaults | frontend | listen | backend
2186 no | yes | yes | yes
2187
2188 By default, requests are not dispatched to down servers. It is possible to
2189 force this using "option persist", but it is unconditional and redispatches
2190 to a valid server if "option redispatch" is set. That leaves with very little
2191 possibilities to force some requests to reach a server which is artificially
2192 marked down for maintenance operations.
2193
2194 The "force-persist" statement allows one to declare various ACL-based
2195 conditions which, when met, will cause a request to ignore the down status of
2196 a server and still try to connect to it. That makes it possible to start a
2197 server, still replying an error to the health checks, and run a specially
2198 configured browser to test the service. Among the handy methods, one could
2199 use a specific source IP address, or a specific cookie. The cookie also has
2200 the advantage that it can easily be added/removed on the browser from a test
2201 page. Once the service is validated, it is then possible to open the service
2202 to the world by returning a valid response to health checks.
2203
2204 The forced persistence is enabled when an "if" condition is met, or unless an
2205 "unless" condition is met. The final redispatch is always disabled when this
2206 is used.
2207
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002208 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002209 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002210
2211
Willy Tarreau2769aa02007-12-27 18:26:09 +01002212fullconn <conns>
2213 Specify at what backend load the servers will reach their maxconn
2214 May be used in sections : defaults | frontend | listen | backend
2215 yes | no | yes | yes
2216 Arguments :
2217 <conns> is the number of connections on the backend which will make the
2218 servers use the maximal number of connections.
2219
Willy Tarreau198a7442008-01-17 12:05:32 +01002220 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002221 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002222 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002223 load. The server will then always accept at least <minconn> connections,
2224 never more than <maxconn>, and the limit will be on the ramp between both
2225 values when the backend has less than <conns> concurrent connections. This
2226 makes it possible to limit the load on the servers during normal loads, but
2227 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002228 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002229
Willy Tarreaufbb78422011-06-05 15:38:35 +02002230 Since it's hard to get this value right, haproxy automatically sets it to
2231 10% of the sum of the maxconns of all frontends that may branch to this
2232 backend. That way it's safe to leave it unset.
2233
Willy Tarreau2769aa02007-12-27 18:26:09 +01002234 Example :
2235 # The servers will accept between 100 and 1000 concurrent connections each
2236 # and the maximum of 1000 will be reached when the backend reaches 10000
2237 # connections.
2238 backend dynamic
2239 fullconn 10000
2240 server srv1 dyn1:80 minconn 100 maxconn 1000
2241 server srv2 dyn2:80 minconn 100 maxconn 1000
2242
2243 See also : "maxconn", "server"
2244
2245
2246grace <time>
2247 Maintain a proxy operational for some time after a soft stop
2248 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002249 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002250 Arguments :
2251 <time> is the time (by default in milliseconds) for which the instance
2252 will remain operational with the frontend sockets still listening
2253 when a soft-stop is received via the SIGUSR1 signal.
2254
2255 This may be used to ensure that the services disappear in a certain order.
2256 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002257 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002258 needed by the equipment to detect the failure.
2259
2260 Note that currently, there is very little benefit in using this parameter,
2261 and it may in fact complicate the soft-reconfiguration process more than
2262 simplify it.
2263
Willy Tarreau0ba27502007-12-24 16:55:16 +01002264
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002265hash-type <method>
2266 Specify a method to use for mapping hashes to servers
2267 May be used in sections : defaults | frontend | listen | backend
2268 yes | no | yes | yes
2269 Arguments :
2270 map-based the hash table is a static array containing all alive servers.
2271 The hashes will be very smooth, will consider weights, but will
2272 be static in that weight changes while a server is up will be
2273 ignored. This means that there will be no slow start. Also,
2274 since a server is selected by its position in the array, most
2275 mappings are changed when the server count changes. This means
2276 that when a server goes up or down, or when a server is added
2277 to a farm, most connections will be redistributed to different
2278 servers. This can be inconvenient with caches for instance.
2279
Willy Tarreau798a39c2010-11-24 15:04:29 +01002280 avalanche this mechanism uses the default map-based hashing described
2281 above but applies a full avalanche hash before performing the
2282 mapping. The result is a slightly less smooth hash for most
2283 situations, but the hash becomes better than pure map-based
2284 hashes when the number of servers is a multiple of the size of
2285 the input set. When using URI hash with a number of servers
2286 multiple of 64, it's desirable to change the hash type to
2287 this value.
2288
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002289 consistent the hash table is a tree filled with many occurrences of each
2290 server. The hash key is looked up in the tree and the closest
2291 server is chosen. This hash is dynamic, it supports changing
2292 weights while the servers are up, so it is compatible with the
2293 slow start feature. It has the advantage that when a server
2294 goes up or down, only its associations are moved. When a server
2295 is added to the farm, only a few part of the mappings are
2296 redistributed, making it an ideal algorithm for caches.
2297 However, due to its principle, the algorithm will never be very
2298 smooth and it may sometimes be necessary to adjust a server's
2299 weight or its ID to get a more balanced distribution. In order
2300 to get the same distribution on multiple load balancers, it is
2301 important that all servers have the same IDs.
2302
2303 The default hash type is "map-based" and is recommended for most usages.
2304
2305 See also : "balance", "server"
2306
2307
Willy Tarreau0ba27502007-12-24 16:55:16 +01002308http-check disable-on-404
2309 Enable a maintenance mode upon HTTP/404 response to health-checks
2310 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002311 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002312 Arguments : none
2313
2314 When this option is set, a server which returns an HTTP code 404 will be
2315 excluded from further load-balancing, but will still receive persistent
2316 connections. This provides a very convenient method for Web administrators
2317 to perform a graceful shutdown of their servers. It is also important to note
2318 that a server which is detected as failed while it was in this mode will not
2319 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2320 will immediately be reinserted into the farm. The status on the stats page
2321 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002322 option only works in conjunction with the "httpchk" option. If this option
2323 is used with "http-check expect", then it has precedence over it so that 404
2324 responses will still be considered as soft-stop.
2325
2326 See also : "option httpchk", "http-check expect"
2327
2328
2329http-check expect [!] <match> <pattern>
2330 Make HTTP health checks consider reponse contents or specific status codes
2331 May be used in sections : defaults | frontend | listen | backend
2332 no | no | yes | yes
2333 Arguments :
2334 <match> is a keyword indicating how to look for a specific pattern in the
2335 response. The keyword may be one of "status", "rstatus",
2336 "string", or "rstring". The keyword may be preceeded by an
2337 exclamation mark ("!") to negate the match. Spaces are allowed
2338 between the exclamation mark and the keyword. See below for more
2339 details on the supported keywords.
2340
2341 <pattern> is the pattern to look for. It may be a string or a regular
2342 expression. If the pattern contains spaces, they must be escaped
2343 with the usual backslash ('\').
2344
2345 By default, "option httpchk" considers that response statuses 2xx and 3xx
2346 are valid, and that others are invalid. When "http-check expect" is used,
2347 it defines what is considered valid or invalid. Only one "http-check"
2348 statement is supported in a backend. If a server fails to respond or times
2349 out, the check obviously fails. The available matches are :
2350
2351 status <string> : test the exact string match for the HTTP status code.
2352 A health check respose will be considered valid if the
2353 response's status code is exactly this string. If the
2354 "status" keyword is prefixed with "!", then the response
2355 will be considered invalid if the status code matches.
2356
2357 rstatus <regex> : test a regular expression for the HTTP status code.
2358 A health check respose will be considered valid if the
2359 response's status code matches the expression. If the
2360 "rstatus" keyword is prefixed with "!", then the response
2361 will be considered invalid if the status code matches.
2362 This is mostly used to check for multiple codes.
2363
2364 string <string> : test the exact string match in the HTTP response body.
2365 A health check respose will be considered valid if the
2366 response's body contains this exact string. If the
2367 "string" keyword is prefixed with "!", then the response
2368 will be considered invalid if the body contains this
2369 string. This can be used to look for a mandatory word at
2370 the end of a dynamic page, or to detect a failure when a
2371 specific error appears on the check page (eg: a stack
2372 trace).
2373
2374 rstring <regex> : test a regular expression on the HTTP response body.
2375 A health check respose will be considered valid if the
2376 response's body matches this expression. If the "rstring"
2377 keyword is prefixed with "!", then the response will be
2378 considered invalid if the body matches the expression.
2379 This can be used to look for a mandatory word at the end
2380 of a dynamic page, or to detect a failure when a specific
2381 error appears on the check page (eg: a stack trace).
2382
2383 It is important to note that the responses will be limited to a certain size
2384 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2385 Thus, too large responses may not contain the mandatory pattern when using
2386 "string" or "rstring". If a large response is absolutely required, it is
2387 possible to change the default max size by setting the global variable.
2388 However, it is worth keeping in mind that parsing very large responses can
2389 waste some CPU cycles, especially when regular expressions are used, and that
2390 it is always better to focus the checks on smaller resources.
2391
2392 Last, if "http-check expect" is combined with "http-check disable-on-404",
2393 then this last one has precedence when the server responds with 404.
2394
2395 Examples :
2396 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002397 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002398
2399 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002400 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002401
2402 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002403 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002404
2405 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002406 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002407
Willy Tarreaubd741542010-03-16 18:46:54 +01002408 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002409
2410
Willy Tarreauef781042010-01-27 11:53:01 +01002411http-check send-state
2412 Enable emission of a state header with HTTP health checks
2413 May be used in sections : defaults | frontend | listen | backend
2414 yes | no | yes | yes
2415 Arguments : none
2416
2417 When this option is set, haproxy will systematically send a special header
2418 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2419 how they are seen by haproxy. This can be used for instance when a server is
2420 manipulated without access to haproxy and the operator needs to know whether
2421 haproxy still sees it up or not, or if the server is the last one in a farm.
2422
2423 The header is composed of fields delimited by semi-colons, the first of which
2424 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2425 checks on the total number before transition, just as appears in the stats
2426 interface. Next headers are in the form "<variable>=<value>", indicating in
2427 no specific order some values available in the stats interface :
2428 - a variable "name", containing the name of the backend followed by a slash
2429 ("/") then the name of the server. This can be used when a server is
2430 checked in multiple backends.
2431
2432 - a variable "node" containing the name of the haproxy node, as set in the
2433 global "node" variable, otherwise the system's hostname if unspecified.
2434
2435 - a variable "weight" indicating the weight of the server, a slash ("/")
2436 and the total weight of the farm (just counting usable servers). This
2437 helps to know if other servers are available to handle the load when this
2438 one fails.
2439
2440 - a variable "scur" indicating the current number of concurrent connections
2441 on the server, followed by a slash ("/") then the total number of
2442 connections on all servers of the same backend.
2443
2444 - a variable "qcur" indicating the current number of requests in the
2445 server's queue.
2446
2447 Example of a header received by the application server :
2448 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2449 scur=13/22; qcur=0
2450
2451 See also : "option httpchk", "http-check disable-on-404"
2452
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002453http-request { allow | deny | auth [realm <realm>] }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002454 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002455 Access control for Layer 7 requests
2456
2457 May be used in sections: defaults | frontend | listen | backend
2458 no | yes | yes | yes
2459
2460 These set of options allow to fine control access to a
2461 frontend/listen/backend. Each option may be followed by if/unless and acl.
2462 First option with matched condition (or option without condition) is final.
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002463 For "deny" a 403 error will be returned, for "allow" normal processing is
2464 performed, for "auth" a 401/407 error code is returned so the client
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002465 should be asked to enter a username and password.
2466
2467 There is no fixed limit to the number of http-request statements per
2468 instance.
2469
2470 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002471 acl nagios src 192.168.129.3
2472 acl local_net src 192.168.0.0/16
2473 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002474
Cyril Bonté78caf842010-03-10 22:41:43 +01002475 http-request allow if nagios
2476 http-request allow if local_net auth_ok
2477 http-request auth realm Gimme if local_net auth_ok
2478 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002479
Cyril Bonté78caf842010-03-10 22:41:43 +01002480 Example:
2481 acl auth_ok http_auth_group(L1) G1
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002482
Cyril Bonté78caf842010-03-10 22:41:43 +01002483 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002484
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002485 See also : "stats http-request", section 3.4 about userlists and section 7
2486 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002487
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002488id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02002489 Set a persistent ID to a proxy.
2490 May be used in sections : defaults | frontend | listen | backend
2491 no | yes | yes | yes
2492 Arguments : none
2493
2494 Set a persistent ID for the proxy. This ID must be unique and positive.
2495 An unused ID will automatically be assigned if unset. The first assigned
2496 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002497
2498
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002499ignore-persist { if | unless } <condition>
2500 Declare a condition to ignore persistence
2501 May be used in sections: defaults | frontend | listen | backend
2502 no | yes | yes | yes
2503
2504 By default, when cookie persistence is enabled, every requests containing
2505 the cookie are unconditionally persistent (assuming the target server is up
2506 and running).
2507
2508 The "ignore-persist" statement allows one to declare various ACL-based
2509 conditions which, when met, will cause a request to ignore persistence.
2510 This is sometimes useful to load balance requests for static files, which
2511 oftenly don't require persistence. This can also be used to fully disable
2512 persistence for a specific User-Agent (for example, some web crawler bots).
2513
2514 Combined with "appsession", it can also help reduce HAProxy memory usage, as
2515 the appsession table won't grow if persistence is ignored.
2516
2517 The persistence is ignored when an "if" condition is met, or unless an
2518 "unless" condition is met.
2519
2520 See also : "force-persist", "cookie", and section 7 about ACL usage.
2521
2522
Willy Tarreau2769aa02007-12-27 18:26:09 +01002523log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002524log <address> <facility> [<level> [<minlevel>]]
Willy Tarreau2769aa02007-12-27 18:26:09 +01002525 Enable per-instance logging of events and traffic.
2526 May be used in sections : defaults | frontend | listen | backend
2527 yes | yes | yes | yes
2528 Arguments :
2529 global should be used when the instance's logging parameters are the
2530 same as the global ones. This is the most common usage. "global"
2531 replaces <address>, <facility> and <level> with those of the log
2532 entries found in the "global" section. Only one "log global"
2533 statement may be used per instance, and this form takes no other
2534 parameter.
2535
2536 <address> indicates where to send the logs. It takes the same format as
2537 for the "global" section's logs, and can be one of :
2538
2539 - An IPv4 address optionally followed by a colon (':') and a UDP
2540 port. If no port is specified, 514 is used by default (the
2541 standard syslog port).
2542
David du Colombier24bb5f52011-03-17 10:40:23 +01002543 - An IPv6 address followed by a colon (':') and optionally a UDP
2544 port. If no port is specified, 514 is used by default (the
2545 standard syslog port).
2546
Willy Tarreau2769aa02007-12-27 18:26:09 +01002547 - A filesystem path to a UNIX domain socket, keeping in mind
2548 considerations for chroot (be sure the path is accessible
2549 inside the chroot) and uid/gid (be sure the path is
2550 appropriately writeable).
2551
2552 <facility> must be one of the 24 standard syslog facilities :
2553
2554 kern user mail daemon auth syslog lpr news
2555 uucp cron auth2 ftp ntp audit alert cron2
2556 local0 local1 local2 local3 local4 local5 local6 local7
2557
2558 <level> is optional and can be specified to filter outgoing messages. By
2559 default, all messages are sent. If a level is specified, only
2560 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002561 will be sent. An optional minimum level can be specified. If it
2562 is set, logs emitted with a more severe level than this one will
2563 be capped to this level. This is used to avoid sending "emerg"
2564 messages on all terminals on some default syslog configurations.
2565 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002566
2567 emerg alert crit err warning notice info debug
2568
2569 Note that up to two "log" entries may be specified per instance. However, if
2570 "log global" is used and if the "global" section already contains 2 log
2571 entries, then additional log entries will be ignored.
2572
2573 Also, it is important to keep in mind that it is the frontend which decides
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002574 what to log from a connection, and that in case of content switching, the log
2575 entries from the backend will be ignored. Connections are logged at level
2576 "info".
2577
2578 However, backend log declaration define how and where servers status changes
2579 will be logged. Level "notice" will be used to indicate a server going up,
2580 "warning" will be used for termination signals and definitive service
2581 termination, and "alert" will be used for when a server goes down.
2582
2583 Note : According to RFC3164, messages are truncated to 1024 bytes before
2584 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002585
2586 Example :
2587 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002588 log 127.0.0.1:514 local0 notice # only send important events
2589 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreau2769aa02007-12-27 18:26:09 +01002590
2591
2592maxconn <conns>
2593 Fix the maximum number of concurrent connections on a frontend
2594 May be used in sections : defaults | frontend | listen | backend
2595 yes | yes | yes | no
2596 Arguments :
2597 <conns> is the maximum number of concurrent connections the frontend will
2598 accept to serve. Excess connections will be queued by the system
2599 in the socket's listen queue and will be served once a connection
2600 closes.
2601
2602 If the system supports it, it can be useful on big sites to raise this limit
2603 very high so that haproxy manages connection queues, instead of leaving the
2604 clients with unanswered connection attempts. This value should not exceed the
2605 global maxconn. Also, keep in mind that a connection contains two buffers
2606 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
2607 consumed per established connection. That means that a medium system equipped
2608 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
2609 properly tuned.
2610
2611 Also, when <conns> is set to large values, it is possible that the servers
2612 are not sized to accept such loads, and for this reason it is generally wise
2613 to assign them some reasonable connection limits.
2614
2615 See also : "server", global section's "maxconn", "fullconn"
2616
2617
2618mode { tcp|http|health }
2619 Set the running mode or protocol of the instance
2620 May be used in sections : defaults | frontend | listen | backend
2621 yes | yes | yes | yes
2622 Arguments :
2623 tcp The instance will work in pure TCP mode. A full-duplex connection
2624 will be established between clients and servers, and no layer 7
2625 examination will be performed. This is the default mode. It
2626 should be used for SSL, SSH, SMTP, ...
2627
2628 http The instance will work in HTTP mode. The client request will be
2629 analyzed in depth before connecting to any server. Any request
2630 which is not RFC-compliant will be rejected. Layer 7 filtering,
2631 processing and switching will be possible. This is the mode which
2632 brings HAProxy most of its value.
2633
2634 health The instance will work in "health" mode. It will just reply "OK"
2635 to incoming connections and close the connection. Nothing will be
2636 logged. This mode is used to reply to external components health
2637 checks. This mode is deprecated and should not be used anymore as
2638 it is possible to do the same and even better by combining TCP or
2639 HTTP modes with the "monitor" keyword.
2640
2641 When doing content switching, it is mandatory that the frontend and the
2642 backend are in the same mode (generally HTTP), otherwise the configuration
2643 will be refused.
2644
2645 Example :
2646 defaults http_instances
2647 mode http
2648
2649 See also : "monitor", "monitor-net"
2650
Willy Tarreau0ba27502007-12-24 16:55:16 +01002651
Cyril Bontéf0c60612010-02-06 14:44:47 +01002652monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01002653 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002654 May be used in sections : defaults | frontend | listen | backend
2655 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01002656 Arguments :
2657 if <cond> the monitor request will fail if the condition is satisfied,
2658 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002659 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01002660 are met, for instance a low number of servers both in a
2661 backend and its backup.
2662
2663 unless <cond> the monitor request will succeed only if the condition is
2664 satisfied, and will fail otherwise. Such a condition may be
2665 based on a test on the presence of a minimum number of active
2666 servers in a list of backends.
2667
2668 This statement adds a condition which can force the response to a monitor
2669 request to report a failure. By default, when an external component queries
2670 the URI dedicated to monitoring, a 200 response is returned. When one of the
2671 conditions above is met, haproxy will return 503 instead of 200. This is
2672 very useful to report a site failure to an external component which may base
2673 routing advertisements between multiple sites on the availability reported by
2674 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002675 criterion. Note that "monitor fail" only works in HTTP mode. Both status
2676 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002677
2678 Example:
2679 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01002680 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01002681 acl site_dead nbsrv(dynamic) lt 2
2682 acl site_dead nbsrv(static) lt 2
2683 monitor-uri /site_alive
2684 monitor fail if site_dead
2685
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002686 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002687
2688
2689monitor-net <source>
2690 Declare a source network which is limited to monitor requests
2691 May be used in sections : defaults | frontend | listen | backend
2692 yes | yes | yes | no
2693 Arguments :
2694 <source> is the source IPv4 address or network which will only be able to
2695 get monitor responses to any request. It can be either an IPv4
2696 address, a host name, or an address followed by a slash ('/')
2697 followed by a mask.
2698
2699 In TCP mode, any connection coming from a source matching <source> will cause
2700 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002701 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01002702 forwarding the connection to a remote server.
2703
2704 In HTTP mode, a connection coming from a source matching <source> will be
2705 accepted, the following response will be sent without waiting for a request,
2706 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
2707 enough for any front-end HTTP probe to detect that the service is UP and
2708 running without forwarding the request to a backend server.
2709
2710 Monitor requests are processed very early. It is not possible to block nor
2711 divert them using ACLs. They cannot be logged either, and it is the intended
2712 purpose. They are only used to report HAProxy's health to an upper component,
2713 nothing more. Right now, it is not possible to set failure conditions on
2714 requests caught by "monitor-net".
2715
Willy Tarreau95cd2832010-03-04 23:36:33 +01002716 Last, please note that only one "monitor-net" statement can be specified in
2717 a frontend. If more than one is found, only the last one will be considered.
2718
Willy Tarreau2769aa02007-12-27 18:26:09 +01002719 Example :
2720 # addresses .252 and .253 are just probing us.
2721 frontend www
2722 monitor-net 192.168.0.252/31
2723
2724 See also : "monitor fail", "monitor-uri"
2725
2726
2727monitor-uri <uri>
2728 Intercept a URI used by external components' monitor requests
2729 May be used in sections : defaults | frontend | listen | backend
2730 yes | yes | yes | no
2731 Arguments :
2732 <uri> is the exact URI which we want to intercept to return HAProxy's
2733 health status instead of forwarding the request.
2734
2735 When an HTTP request referencing <uri> will be received on a frontend,
2736 HAProxy will not forward it nor log it, but instead will return either
2737 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
2738 conditions defined with "monitor fail". This is normally enough for any
2739 front-end HTTP probe to detect that the service is UP and running without
2740 forwarding the request to a backend server. Note that the HTTP method, the
2741 version and all headers are ignored, but the request must at least be valid
2742 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
2743
2744 Monitor requests are processed very early. It is not possible to block nor
2745 divert them using ACLs. They cannot be logged either, and it is the intended
2746 purpose. They are only used to report HAProxy's health to an upper component,
2747 nothing more. However, it is possible to add any number of conditions using
2748 "monitor fail" and ACLs so that the result can be adjusted to whatever check
2749 can be imagined (most often the number of available servers in a backend).
2750
2751 Example :
2752 # Use /haproxy_test to report haproxy's status
2753 frontend www
2754 mode http
2755 monitor-uri /haproxy_test
2756
2757 See also : "monitor fail", "monitor-net"
2758
Willy Tarreau0ba27502007-12-24 16:55:16 +01002759
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002760option abortonclose
2761no option abortonclose
2762 Enable or disable early dropping of aborted requests pending in queues.
2763 May be used in sections : defaults | frontend | listen | backend
2764 yes | no | yes | yes
2765 Arguments : none
2766
2767 In presence of very high loads, the servers will take some time to respond.
2768 The per-instance connection queue will inflate, and the response time will
2769 increase respective to the size of the queue times the average per-session
2770 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01002771 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002772 the queue, and slowing down other users, and the servers as well, because the
2773 request will eventually be served, then aborted at the first error
2774 encountered while delivering the response.
2775
2776 As there is no way to distinguish between a full STOP and a simple output
2777 close on the client side, HTTP agents should be conservative and consider
2778 that the client might only have closed its output channel while waiting for
2779 the response. However, this introduces risks of congestion when lots of users
2780 do the same, and is completely useless nowadays because probably no client at
2781 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01002782 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002783 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01002784 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002785 of being the single component to break rare but valid traffic is extremely
2786 low, which adds to the temptation to be able to abort a session early while
2787 still not served and not pollute the servers.
2788
2789 In HAProxy, the user can choose the desired behaviour using the option
2790 "abortonclose". By default (without the option) the behaviour is HTTP
2791 compliant and aborted requests will be served. But when the option is
2792 specified, a session with an incoming channel closed will be aborted while
2793 it is still possible, either pending in the queue for a connection slot, or
2794 during the connection establishment if the server has not yet acknowledged
2795 the connection request. This considerably reduces the queue size and the load
2796 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01002797 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002798
2799 If this option has been enabled in a "defaults" section, it can be disabled
2800 in a specific instance by prepending the "no" keyword before it.
2801
2802 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
2803
2804
Willy Tarreau4076a152009-04-02 15:18:36 +02002805option accept-invalid-http-request
2806no option accept-invalid-http-request
2807 Enable or disable relaxing of HTTP request parsing
2808 May be used in sections : defaults | frontend | listen | backend
2809 yes | yes | yes | no
2810 Arguments : none
2811
2812 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2813 means that invalid characters in header names are not permitted and cause an
2814 error to be returned to the client. This is the desired behaviour as such
2815 forbidden characters are essentially used to build attacks exploiting server
2816 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2817 server will emit invalid header names for whatever reason (configuration,
2818 implementation) and the issue will not be immediately fixed. In such a case,
2819 it is possible to relax HAProxy's header name parser to accept any character
2820 even if that does not make sense, by specifying this option.
2821
2822 This option should never be enabled by default as it hides application bugs
2823 and open security breaches. It should only be deployed after a problem has
2824 been confirmed.
2825
2826 When this option is enabled, erroneous header names will still be accepted in
2827 requests, but the complete request will be captured in order to permit later
2828 analysis using the "show errors" request on the UNIX stats socket. Doing this
2829 also helps confirming that the issue has been solved.
2830
2831 If this option has been enabled in a "defaults" section, it can be disabled
2832 in a specific instance by prepending the "no" keyword before it.
2833
2834 See also : "option accept-invalid-http-response" and "show errors" on the
2835 stats socket.
2836
2837
2838option accept-invalid-http-response
2839no option accept-invalid-http-response
2840 Enable or disable relaxing of HTTP response parsing
2841 May be used in sections : defaults | frontend | listen | backend
2842 yes | no | yes | yes
2843 Arguments : none
2844
2845 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2846 means that invalid characters in header names are not permitted and cause an
2847 error to be returned to the client. This is the desired behaviour as such
2848 forbidden characters are essentially used to build attacks exploiting server
2849 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2850 server will emit invalid header names for whatever reason (configuration,
2851 implementation) and the issue will not be immediately fixed. In such a case,
2852 it is possible to relax HAProxy's header name parser to accept any character
2853 even if that does not make sense, by specifying this option.
2854
2855 This option should never be enabled by default as it hides application bugs
2856 and open security breaches. It should only be deployed after a problem has
2857 been confirmed.
2858
2859 When this option is enabled, erroneous header names will still be accepted in
2860 responses, but the complete response will be captured in order to permit
2861 later analysis using the "show errors" request on the UNIX stats socket.
2862 Doing this also helps confirming that the issue has been solved.
2863
2864 If this option has been enabled in a "defaults" section, it can be disabled
2865 in a specific instance by prepending the "no" keyword before it.
2866
2867 See also : "option accept-invalid-http-request" and "show errors" on the
2868 stats socket.
2869
2870
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002871option allbackups
2872no option allbackups
2873 Use either all backup servers at a time or only the first one
2874 May be used in sections : defaults | frontend | listen | backend
2875 yes | no | yes | yes
2876 Arguments : none
2877
2878 By default, the first operational backup server gets all traffic when normal
2879 servers are all down. Sometimes, it may be preferred to use multiple backups
2880 at once, because one will not be enough. When "option allbackups" is enabled,
2881 the load balancing will be performed among all backup servers when all normal
2882 ones are unavailable. The same load balancing algorithm will be used and the
2883 servers' weights will be respected. Thus, there will not be any priority
2884 order between the backup servers anymore.
2885
2886 This option is mostly used with static server farms dedicated to return a
2887 "sorry" page when an application is completely offline.
2888
2889 If this option has been enabled in a "defaults" section, it can be disabled
2890 in a specific instance by prepending the "no" keyword before it.
2891
2892
2893option checkcache
2894no option checkcache
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002895 Analyze all server responses and block requests with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002896 May be used in sections : defaults | frontend | listen | backend
2897 yes | no | yes | yes
2898 Arguments : none
2899
2900 Some high-level frameworks set application cookies everywhere and do not
2901 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002902 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002903 high risk of session crossing or stealing between users traversing the same
2904 caches. In some situations, it is better to block the response than to let
2905 some sensible session information go in the wild.
2906
2907 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002908 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01002909 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002910 response to check if there's a risk of caching a cookie on a client-side
2911 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01002912 to the client are :
2913 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002914 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01002915 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002916 - all those that come from a POST request, provided that the server has not
2917 set a 'Cache-Control: public' header ;
2918 - those with a 'Pragma: no-cache' header
2919 - those with a 'Cache-control: private' header
2920 - those with a 'Cache-control: no-store' header
2921 - those with a 'Cache-control: max-age=0' header
2922 - those with a 'Cache-control: s-maxage=0' header
2923 - those with a 'Cache-control: no-cache' header
2924 - those with a 'Cache-control: no-cache="set-cookie"' header
2925 - those with a 'Cache-control: no-cache="set-cookie,' header
2926 (allowing other fields after set-cookie)
2927
2928 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01002929 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002930 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002931 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002932 that admins are informed that there's something to be fixed.
2933
2934 Due to the high impact on the application, the application should be tested
2935 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002936 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002937 production, as it will report potentially dangerous application behaviours.
2938
2939 If this option has been enabled in a "defaults" section, it can be disabled
2940 in a specific instance by prepending the "no" keyword before it.
2941
2942
2943option clitcpka
2944no option clitcpka
2945 Enable or disable the sending of TCP keepalive packets on the client side
2946 May be used in sections : defaults | frontend | listen | backend
2947 yes | yes | yes | no
2948 Arguments : none
2949
2950 When there is a firewall or any session-aware component between a client and
2951 a server, and when the protocol involves very long sessions with long idle
2952 periods (eg: remote desktops), there is a risk that one of the intermediate
2953 components decides to expire a session which has remained idle for too long.
2954
2955 Enabling socket-level TCP keep-alives makes the system regularly send packets
2956 to the other end of the connection, leaving it active. The delay between
2957 keep-alive probes is controlled by the system only and depends both on the
2958 operating system and its tuning parameters.
2959
2960 It is important to understand that keep-alive packets are neither emitted nor
2961 received at the application level. It is only the network stacks which sees
2962 them. For this reason, even if one side of the proxy already uses keep-alives
2963 to maintain its connection alive, those keep-alive packets will not be
2964 forwarded to the other side of the proxy.
2965
2966 Please note that this has nothing to do with HTTP keep-alive.
2967
2968 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
2969 client side of a connection, which should help when session expirations are
2970 noticed between HAProxy and a client.
2971
2972 If this option has been enabled in a "defaults" section, it can be disabled
2973 in a specific instance by prepending the "no" keyword before it.
2974
2975 See also : "option srvtcpka", "option tcpka"
2976
2977
Willy Tarreau0ba27502007-12-24 16:55:16 +01002978option contstats
2979 Enable continuous traffic statistics updates
2980 May be used in sections : defaults | frontend | listen | backend
2981 yes | yes | yes | no
2982 Arguments : none
2983
2984 By default, counters used for statistics calculation are incremented
2985 only when a session finishes. It works quite well when serving small
2986 objects, but with big ones (for example large images or archives) or
2987 with A/V streaming, a graph generated from haproxy counters looks like
2988 a hedgehog. With this option enabled counters get incremented continuously,
2989 during a whole session. Recounting touches a hotpath directly so
2990 it is not enabled by default, as it has small performance impact (~0.5%).
2991
2992
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002993option dontlog-normal
2994no option dontlog-normal
2995 Enable or disable logging of normal, successful connections
2996 May be used in sections : defaults | frontend | listen | backend
2997 yes | yes | yes | no
2998 Arguments : none
2999
3000 There are large sites dealing with several thousand connections per second
3001 and for which logging is a major pain. Some of them are even forced to turn
3002 logs off and cannot debug production issues. Setting this option ensures that
3003 normal connections, those which experience no error, no timeout, no retry nor
3004 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
3005 mode, the response status code is checked and return codes 5xx will still be
3006 logged.
3007
3008 It is strongly discouraged to use this option as most of the time, the key to
3009 complex issues is in the normal logs which will not be logged here. If you
3010 need to separate logs, see the "log-separate-errors" option instead.
3011
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003012 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003013 logging.
3014
3015
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003016option dontlognull
3017no option dontlognull
3018 Enable or disable logging of null connections
3019 May be used in sections : defaults | frontend | listen | backend
3020 yes | yes | yes | no
3021 Arguments : none
3022
3023 In certain environments, there are components which will regularly connect to
3024 various systems to ensure that they are still alive. It can be the case from
3025 another load balancer as well as from monitoring systems. By default, even a
3026 simple port probe or scan will produce a log. If those connections pollute
3027 the logs too much, it is possible to enable option "dontlognull" to indicate
3028 that a connection on which no data has been transferred will not be logged,
3029 which typically corresponds to those probes.
3030
3031 It is generally recommended not to use this option in uncontrolled
3032 environments (eg: internet), otherwise scans and other malicious activities
3033 would not be logged.
3034
3035 If this option has been enabled in a "defaults" section, it can be disabled
3036 in a specific instance by prepending the "no" keyword before it.
3037
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003038 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003039
3040
3041option forceclose
3042no option forceclose
3043 Enable or disable active connection closing after response is transferred.
3044 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003045 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003046 Arguments : none
3047
3048 Some HTTP servers do not necessarily close the connections when they receive
3049 the "Connection: close" set by "option httpclose", and if the client does not
3050 close either, then the connection remains open till the timeout expires. This
3051 causes high number of simultaneous connections on the servers and shows high
3052 global session times in the logs.
3053
3054 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003055 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003056 to respond. This option implicitly enables the "httpclose" option. Note that
3057 this option also enables the parsing of the full request and response, which
3058 means we can close the connection to the server very quickly, releasing some
3059 resources earlier than with httpclose.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003060
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003061 This option may also be combined with "option http-pretend-keepalive", which
3062 will disable sending of the "Connection: close" header, but will still cause
3063 the connection to be closed once the whole response is received.
3064
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003065 If this option has been enabled in a "defaults" section, it can be disabled
3066 in a specific instance by prepending the "no" keyword before it.
3067
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003068 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003069
3070
Ross Westaf72a1d2008-08-03 10:51:45 +02003071option forwardfor [ except <network> ] [ header <name> ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003072 Enable insertion of the X-Forwarded-For header to requests sent to servers
3073 May be used in sections : defaults | frontend | listen | backend
3074 yes | yes | yes | yes
3075 Arguments :
3076 <network> is an optional argument used to disable this option for sources
3077 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003078 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003079 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003080
3081 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3082 their client address. This is sometimes annoying when the client's IP address
3083 is expected in server logs. To solve this problem, the well-known HTTP header
3084 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3085 This header contains a value representing the client's IP address. Since this
3086 header is always appended at the end of the existing header list, the server
3087 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003088 the server's manual to find how to enable use of this standard header. Note
3089 that only the last occurrence of the header must be used, since it is really
3090 possible that the client has already brought one.
3091
Willy Tarreaud72758d2010-01-12 10:42:19 +01003092 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003093 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003094 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3095 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003096 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3097 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003098
3099 Sometimes, a same HAProxy instance may be shared between a direct client
3100 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3101 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3102 header for a known source address or network by adding the "except" keyword
3103 followed by the network address. In this case, any source IP matching the
3104 network will not cause an addition of this header. Most common uses are with
3105 private networks or 127.0.0.1.
3106
3107 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003108 least one of them uses it, the header will be added. Note that the backend's
3109 setting of the header subargument takes precedence over the frontend's if
3110 both are defined.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003111
3112 It is important to note that as long as HAProxy does not support keep-alive
3113 connections, only the first request of a connection will receive the header.
3114 For this reason, it is important to ensure that "option httpclose" is set
3115 when using this option.
3116
Ross Westaf72a1d2008-08-03 10:51:45 +02003117 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003118 # Public HTTP address also used by stunnel on the same machine
3119 frontend www
3120 mode http
3121 option forwardfor except 127.0.0.1 # stunnel already adds the header
3122
Ross Westaf72a1d2008-08-03 10:51:45 +02003123 # Those servers want the IP Address in X-Client
3124 backend www
3125 mode http
3126 option forwardfor header X-Client
3127
Willy Tarreauc27debf2008-01-06 08:57:02 +01003128 See also : "option httpclose"
3129
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003130
Willy Tarreau96e31212011-05-30 18:10:30 +02003131option http-no-delay
3132no option http-no-delay
3133 Instruct the system to favor low interactive delays over performance in HTTP
3134 May be used in sections : defaults | frontend | listen | backend
3135 yes | yes | yes | yes
3136 Arguments : none
3137
3138 In HTTP, each payload is unidirectional and has no notion of interactivity.
3139 Any agent is expected to queue data somewhat for a reasonably low delay.
3140 There are some very rare server-to-server applications that abuse the HTTP
3141 protocol and expect the payload phase to be highly interactive, with many
3142 interleaved data chunks in both directions within a single request. This is
3143 absolutely not supported by the HTTP specification and will not work across
3144 most proxies or servers. When such applications attempt to do this through
3145 haproxy, it works but they will experience high delays due to the network
3146 optimizations which favor performance by instructing the system to wait for
3147 enough data to be available in order to only send full packets. Typical
3148 delays are around 200 ms per round trip. Note that this only happens with
3149 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
3150 affected.
3151
3152 When "option http-no-delay" is present in either the frontend or the backend
3153 used by a connection, all such optimizations will be disabled in order to
3154 make the exchanges as fast as possible. Of course this offers no guarantee on
3155 the functionality, as it may break at any other place. But if it works via
3156 HAProxy, it will work as fast as possible. This option should never be used
3157 by default, and should never be used at all unless such a buggy application
3158 is discovered. The impact of using this option is an increase of bandwidth
3159 usage and CPU usage, which may significantly lower performance in high
3160 latency environments.
3161
3162
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003163option http-pretend-keepalive
3164no option http-pretend-keepalive
3165 Define whether haproxy will announce keepalive to the server or not
3166 May be used in sections : defaults | frontend | listen | backend
3167 yes | yes | yes | yes
3168 Arguments : none
3169
3170 When running with "option http-server-close" or "option forceclose", haproxy
3171 adds a "Connection: close" header to the request forwarded to the server.
3172 Unfortunately, when some servers see this header, they automatically refrain
3173 from using the chunked encoding for responses of unknown length, while this
3174 is totally unrelated. The immediate effect is that this prevents haproxy from
3175 maintaining the client connection alive. A second effect is that a client or
3176 a cache could receive an incomplete response without being aware of it, and
3177 consider the response complete.
3178
3179 By setting "option http-pretend-keepalive", haproxy will make the server
3180 believe it will keep the connection alive. The server will then not fall back
3181 to the abnormal undesired above. When haproxy gets the whole response, it
3182 will close the connection with the server just as it would do with the
3183 "forceclose" option. That way the client gets a normal response and the
3184 connection is correctly closed on the server side.
3185
3186 It is recommended not to enable this option by default, because most servers
3187 will more efficiently close the connection themselves after the last packet,
3188 and release its buffers slightly earlier. Also, the added packet on the
3189 network could slightly reduce the overall peak performance. However it is
3190 worth noting that when this option is enabled, haproxy will have slightly
3191 less work to do. So if haproxy is the bottleneck on the whole architecture,
3192 enabling this option might save a few CPU cycles.
3193
3194 This option may be set both in a frontend and in a backend. It is enabled if
3195 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau22a95342010-09-29 14:31:41 +02003196 This option may be compbined with "option httpclose", which will cause
3197 keepalive to be announced to the server and close to be announced to the
3198 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003199
3200 If this option has been enabled in a "defaults" section, it can be disabled
3201 in a specific instance by prepending the "no" keyword before it.
3202
3203 See also : "option forceclose" and "option http-server-close"
3204
Willy Tarreauc27debf2008-01-06 08:57:02 +01003205
Willy Tarreaub608feb2010-01-02 22:47:18 +01003206option http-server-close
3207no option http-server-close
3208 Enable or disable HTTP connection closing on the server side
3209 May be used in sections : defaults | frontend | listen | backend
3210 yes | yes | yes | yes
3211 Arguments : none
3212
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003213 By default, when a client communicates with a server, HAProxy will only
3214 analyze, log, and process the first request of each connection. Setting
3215 "option http-server-close" enables HTTP connection-close mode on the server
3216 side while keeping the ability to support HTTP keep-alive and pipelining on
3217 the client side. This provides the lowest latency on the client side (slow
3218 network) and the fastest session reuse on the server side to save server
3219 resources, similarly to "option forceclose". It also permits non-keepalive
3220 capable servers to be served in keep-alive mode to the clients if they
3221 conform to the requirements of RFC2616. Please note that some servers do not
3222 always conform to those requirements when they see "Connection: close" in the
3223 request. The effect will be that keep-alive will never be used. A workaround
3224 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003225
3226 At the moment, logs will not indicate whether requests came from the same
3227 session or not. The accept date reported in the logs corresponds to the end
3228 of the previous request, and the request time corresponds to the time spent
3229 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01003230 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3231 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01003232
3233 This option may be set both in a frontend and in a backend. It is enabled if
3234 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003235 It is worth noting that "option forceclose" has precedence over "option
3236 http-server-close" and that combining "http-server-close" with "httpclose"
3237 basically achieve the same result as "forceclose".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003238
3239 If this option has been enabled in a "defaults" section, it can be disabled
3240 in a specific instance by prepending the "no" keyword before it.
3241
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003242 See also : "option forceclose", "option http-pretend-keepalive",
3243 "option httpclose" and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003244
3245
Willy Tarreau88d349d2010-01-25 12:15:43 +01003246option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01003247no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01003248 Make use of non-standard Proxy-Connection header instead of Connection
3249 May be used in sections : defaults | frontend | listen | backend
3250 yes | yes | yes | no
3251 Arguments : none
3252
3253 While RFC2616 explicitly states that HTTP/1.1 agents must use the
3254 Connection header to indicate their wish of persistent or non-persistent
3255 connections, both browsers and proxies ignore this header for proxied
3256 connections and make use of the undocumented, non-standard Proxy-Connection
3257 header instead. The issue begins when trying to put a load balancer between
3258 browsers and such proxies, because there will be a difference between what
3259 haproxy understands and what the client and the proxy agree on.
3260
3261 By setting this option in a frontend, haproxy can automatically switch to use
3262 that non-standard header if it sees proxied requests. A proxied request is
3263 defined here as one where the URI begins with neither a '/' nor a '*'. The
3264 choice of header only affects requests passing through proxies making use of
3265 one of the "httpclose", "forceclose" and "http-server-close" options. Note
3266 that this option can only be specified in a frontend and will affect the
3267 request along its whole life.
3268
Willy Tarreau844a7e72010-01-31 21:46:18 +01003269 Also, when this option is set, a request which requires authentication will
3270 automatically switch to use proxy authentication headers if it is itself a
3271 proxied request. That makes it possible to check or enforce authentication in
3272 front of an existing proxy.
3273
Willy Tarreau88d349d2010-01-25 12:15:43 +01003274 This option should normally never be used, except in front of a proxy.
3275
3276 See also : "option httpclose", "option forceclose" and "option
3277 http-server-close".
3278
3279
Willy Tarreaud63335a2010-02-26 12:56:52 +01003280option httpchk
3281option httpchk <uri>
3282option httpchk <method> <uri>
3283option httpchk <method> <uri> <version>
3284 Enable HTTP protocol to check on the servers health
3285 May be used in sections : defaults | frontend | listen | backend
3286 yes | no | yes | yes
3287 Arguments :
3288 <method> is the optional HTTP method used with the requests. When not set,
3289 the "OPTIONS" method is used, as it generally requires low server
3290 processing and is easy to filter out from the logs. Any method
3291 may be used, though it is not recommended to invent non-standard
3292 ones.
3293
3294 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
3295 which is accessible by default on almost any server, but may be
3296 changed to any other URI. Query strings are permitted.
3297
3298 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
3299 but some servers might behave incorrectly in HTTP 1.0, so turning
3300 it to HTTP/1.1 may sometimes help. Note that the Host field is
3301 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
3302 after "\r\n" following the version string.
3303
3304 By default, server health checks only consist in trying to establish a TCP
3305 connection. When "option httpchk" is specified, a complete HTTP request is
3306 sent once the TCP connection is established, and responses 2xx and 3xx are
3307 considered valid, while all other ones indicate a server failure, including
3308 the lack of any response.
3309
3310 The port and interval are specified in the server configuration.
3311
3312 This option does not necessarily require an HTTP backend, it also works with
3313 plain TCP backends. This is particularly useful to check simple scripts bound
3314 to some dedicated ports using the inetd daemon.
3315
3316 Examples :
3317 # Relay HTTPS traffic to Apache instance and check service availability
3318 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
3319 backend https_relay
3320 mode tcp
3321 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
3322 server apache1 192.168.1.1:443 check port 80
3323
3324 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003325 "option pgsql-check", "http-check" and the "check", "port" and
3326 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01003327
3328
Willy Tarreauc27debf2008-01-06 08:57:02 +01003329option httpclose
3330no option httpclose
3331 Enable or disable passive HTTP connection closing
3332 May be used in sections : defaults | frontend | listen | backend
3333 yes | yes | yes | yes
3334 Arguments : none
3335
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003336 By default, when a client communicates with a server, HAProxy will only
3337 analyze, log, and process the first request of each connection. If "option
3338 httpclose" is set, it will check if a "Connection: close" header is already
3339 set in each direction, and will add one if missing. Each end should react to
3340 this by actively closing the TCP connection after each transfer, thus
3341 resulting in a switch to the HTTP close mode. Any "Connection" header
3342 different from "close" will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003343
3344 It seldom happens that some servers incorrectly ignore this header and do not
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003345 close the connection eventhough they reply "Connection: close". For this
3346 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
3347 it is possible to use the "option forceclose" which actively closes the
3348 request connection once the server responds. Option "forceclose" also
3349 releases the server connection earlier because it does not have to wait for
3350 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003351
3352 This option may be set both in a frontend and in a backend. It is enabled if
3353 at least one of the frontend or backend holding a connection has it enabled.
3354 If "option forceclose" is specified too, it has precedence over "httpclose".
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003355 If "option http-server-close" is enabled at the same time as "httpclose", it
3356 basically achieves the same result as "option forceclose".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003357
3358 If this option has been enabled in a "defaults" section, it can be disabled
3359 in a specific instance by prepending the "no" keyword before it.
3360
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003361 See also : "option forceclose", "option http-server-close" and
3362 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003363
3364
Emeric Brun3a058f32009-06-30 18:26:00 +02003365option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003366 Enable logging of HTTP request, session state and timers
3367 May be used in sections : defaults | frontend | listen | backend
3368 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02003369 Arguments :
3370 clf if the "clf" argument is added, then the output format will be
3371 the CLF format instead of HAProxy's default HTTP format. You can
3372 use this when you need to feed HAProxy's logs through a specific
3373 log analyser which only support the CLF format and which is not
3374 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003375
3376 By default, the log output format is very poor, as it only contains the
3377 source and destination addresses, and the instance name. By specifying
3378 "option httplog", each log line turns into a much richer format including,
3379 but not limited to, the HTTP request, the connection timers, the session
3380 status, the connections numbers, the captured headers and cookies, the
3381 frontend, backend and server name, and of course the source address and
3382 ports.
3383
3384 This option may be set either in the frontend or the backend.
3385
Emeric Brun3a058f32009-06-30 18:26:00 +02003386 If this option has been enabled in a "defaults" section, it can be disabled
3387 in a specific instance by prepending the "no" keyword before it. Specifying
3388 only "option httplog" will automatically clear the 'clf' mode if it was set
3389 by default.
3390
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003391 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003392
Willy Tarreau55165fe2009-05-10 12:02:55 +02003393
3394option http_proxy
3395no option http_proxy
3396 Enable or disable plain HTTP proxy mode
3397 May be used in sections : defaults | frontend | listen | backend
3398 yes | yes | yes | yes
3399 Arguments : none
3400
3401 It sometimes happens that people need a pure HTTP proxy which understands
3402 basic proxy requests without caching nor any fancy feature. In this case,
3403 it may be worth setting up an HAProxy instance with the "option http_proxy"
3404 set. In this mode, no server is declared, and the connection is forwarded to
3405 the IP address and port found in the URL after the "http://" scheme.
3406
3407 No host address resolution is performed, so this only works when pure IP
3408 addresses are passed. Since this option's usage perimeter is rather limited,
3409 it will probably be used only by experts who know they need exactly it. Last,
3410 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01003411 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02003412 be analyzed.
3413
3414 If this option has been enabled in a "defaults" section, it can be disabled
3415 in a specific instance by prepending the "no" keyword before it.
3416
3417 Example :
3418 # this backend understands HTTP proxy requests and forwards them directly.
3419 backend direct_forward
3420 option httpclose
3421 option http_proxy
3422
3423 See also : "option httpclose"
3424
Willy Tarreau211ad242009-10-03 21:45:07 +02003425
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003426option independant-streams
3427no option independant-streams
3428 Enable or disable independant timeout processing for both directions
3429 May be used in sections : defaults | frontend | listen | backend
3430 yes | yes | yes | yes
3431 Arguments : none
3432
3433 By default, when data is sent over a socket, both the write timeout and the
3434 read timeout for that socket are refreshed, because we consider that there is
3435 activity on that socket, and we have no other means of guessing if we should
3436 receive data or not.
3437
3438 While this default behaviour is desirable for almost all applications, there
3439 exists a situation where it is desirable to disable it, and only refresh the
3440 read timeout if there are incoming data. This happens on sessions with large
3441 timeouts and low amounts of exchanged data such as telnet session. If the
3442 server suddenly disappears, the output data accumulates in the system's
3443 socket buffers, both timeouts are correctly refreshed, and there is no way
3444 to know the server does not receive them, so we don't timeout. However, when
3445 the underlying protocol always echoes sent data, it would be enough by itself
3446 to detect the issue using the read timeout. Note that this problem does not
3447 happen with more verbose protocols because data won't accumulate long in the
3448 socket buffers.
3449
3450 When this option is set on the frontend, it will disable read timeout updates
3451 on data sent to the client. There probably is little use of this case. When
3452 the option is set on the backend, it will disable read timeout updates on
3453 data sent to the server. Doing so will typically break large HTTP posts from
3454 slow lines, so use it with caution.
3455
3456 See also : "timeout client" and "timeout server"
3457
3458
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003459option ldap-check
3460 Use LDAPv3 health checks for server testing
3461 May be used in sections : defaults | frontend | listen | backend
3462 yes | no | yes | yes
3463 Arguments : none
3464
3465 It is possible to test that the server correctly talks LDAPv3 instead of just
3466 testing that it accepts the TCP connection. When this option is set, an
3467 LDAPv3 anonymous simple bind message is sent to the server, and the response
3468 is analyzed to find an LDAPv3 bind response message.
3469
3470 The server is considered valid only when the LDAP response contains success
3471 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
3472
3473 Logging of bind requests is server dependent see your documentation how to
3474 configure it.
3475
3476 Example :
3477 option ldap-check
3478
3479 See also : "option httpchk"
3480
3481
Willy Tarreau211ad242009-10-03 21:45:07 +02003482option log-health-checks
3483no option log-health-checks
3484 Enable or disable logging of health checks
3485 May be used in sections : defaults | frontend | listen | backend
3486 yes | no | yes | yes
3487 Arguments : none
3488
3489 Enable health checks logging so it possible to check for example what
3490 was happening before a server crash. Failed health check are logged if
3491 server is UP and succeeded health checks if server is DOWN, so the amount
3492 of additional information is limited.
3493
3494 If health check logging is enabled no health check status is printed
3495 when servers is set up UP/DOWN/ENABLED/DISABLED.
3496
3497 See also: "log" and section 8 about logging.
3498
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003499
3500option log-separate-errors
3501no option log-separate-errors
3502 Change log level for non-completely successful connections
3503 May be used in sections : defaults | frontend | listen | backend
3504 yes | yes | yes | no
3505 Arguments : none
3506
3507 Sometimes looking for errors in logs is not easy. This option makes haproxy
3508 raise the level of logs containing potentially interesting information such
3509 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
3510 level changes from "info" to "err". This makes it possible to log them
3511 separately to a different file with most syslog daemons. Be careful not to
3512 remove them from the original file, otherwise you would lose ordering which
3513 provides very important information.
3514
3515 Using this option, large sites dealing with several thousand connections per
3516 second may log normal traffic to a rotating buffer and only archive smaller
3517 error logs.
3518
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003519 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003520 logging.
3521
Willy Tarreauc27debf2008-01-06 08:57:02 +01003522
3523option logasap
3524no option logasap
3525 Enable or disable early logging of HTTP requests
3526 May be used in sections : defaults | frontend | listen | backend
3527 yes | yes | yes | no
3528 Arguments : none
3529
3530 By default, HTTP requests are logged upon termination so that the total
3531 transfer time and the number of bytes appear in the logs. When large objects
3532 are being transferred, it may take a while before the request appears in the
3533 logs. Using "option logasap", the request gets logged as soon as the server
3534 sends the complete headers. The only missing information in the logs will be
3535 the total number of bytes which will indicate everything except the amount
3536 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003537 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01003538 "Content-Length" response header so that the logs at least indicate how many
3539 bytes are expected to be transferred.
3540
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003541 Examples :
3542 listen http_proxy 0.0.0.0:80
3543 mode http
3544 option httplog
3545 option logasap
3546 log 192.168.2.200 local3
3547
3548 >>> Feb 6 12:14:14 localhost \
3549 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
3550 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
3551 "GET /image.iso HTTP/1.0"
3552
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003553 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01003554 logging.
3555
3556
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003557option mysql-check [ user <username> ]
3558 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003559 May be used in sections : defaults | frontend | listen | backend
3560 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003561 Arguments :
3562 user <username> This is the username which will be used when connecting
3563 to MySQL server.
3564
3565 If you specify a username, the check consists of sending two MySQL packet,
3566 one Client Authentication packet, and one QUIT packet, to correctly close
3567 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
3568 Error packet. It is a basic but useful test which does not produce error nor
3569 aborted connect on the server. However, it requires adding an authorization
3570 in the MySQL table, like this :
3571
3572 USE mysql;
3573 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
3574 FLUSH PRIVILEGES;
3575
3576 If you don't specify a username (it is deprecated and not recommended), the
3577 check only consists in parsing the Mysql Handshake Initialisation packet or
3578 Error packet, we don't send anything in this mode. It was reported that it
3579 can generate lockout if check is too frequent and/or if there is not enough
3580 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
3581 value as if a connection is established successfully within fewer than MySQL
3582 "max_connect_errors" attempts after a previous connection was interrupted,
3583 the error count for the host is cleared to zero. If HAProxy's server get
3584 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
3585
3586 Remember that this does not check database presence nor database consistency.
3587 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003588
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02003589 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003590
3591 Most often, an incoming MySQL server needs to see the client's IP address for
3592 various purposes, including IP privilege matching and connection logging.
3593 When possible, it is often wise to masquerade the client's IP address when
3594 connecting to the server using the "usesrc" argument of the "source" keyword,
3595 which requires the cttproxy feature to be compiled in, and the MySQL server
3596 to route the client via the machine hosting haproxy.
3597
3598 See also: "option httpchk"
3599
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003600option pgsql-check [ user <username> ]
3601 Use PostgreSQL health checks for server testing
3602 May be used in sections : defaults | frontend | listen | backend
3603 yes | no | yes | yes
3604 Arguments :
3605 user <username> This is the username which will be used when connecting
3606 to PostgreSQL server.
3607
3608 The check sends a PostgreSQL StartupMessage and waits for either
3609 Authentication request or ErrorResponse message. It is a basic but useful
3610 test which does not produce error nor aborted connect on the server.
3611 This check is identical with the "mysql-check".
3612
3613 See also: "option httpchk"
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003614
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003615option nolinger
3616no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003617 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003618 May be used in sections: defaults | frontend | listen | backend
3619 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003620 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003621
3622 When clients or servers abort connections in a dirty way (eg: they are
3623 physically disconnected), the session timeouts triggers and the session is
3624 closed. But it will remain in FIN_WAIT1 state for some time in the system,
3625 using some resources and possibly limiting the ability to establish newer
3626 connections.
3627
3628 When this happens, it is possible to activate "option nolinger" which forces
3629 the system to immediately remove any socket's pending data on close. Thus,
3630 the session is instantly purged from the system's tables. This usually has
3631 side effects such as increased number of TCP resets due to old retransmits
3632 getting immediately rejected. Some firewalls may sometimes complain about
3633 this too.
3634
3635 For this reason, it is not recommended to use this option when not absolutely
3636 needed. You know that you need it when you have thousands of FIN_WAIT1
3637 sessions on your system (TIME_WAIT ones do not count).
3638
3639 This option may be used both on frontends and backends, depending on the side
3640 where it is required. Use it on the frontend for clients, and on the backend
3641 for servers.
3642
3643 If this option has been enabled in a "defaults" section, it can be disabled
3644 in a specific instance by prepending the "no" keyword before it.
3645
3646
Willy Tarreau55165fe2009-05-10 12:02:55 +02003647option originalto [ except <network> ] [ header <name> ]
3648 Enable insertion of the X-Original-To header to requests sent to servers
3649 May be used in sections : defaults | frontend | listen | backend
3650 yes | yes | yes | yes
3651 Arguments :
3652 <network> is an optional argument used to disable this option for sources
3653 matching <network>
3654 <name> an optional argument to specify a different "X-Original-To"
3655 header name.
3656
3657 Since HAProxy can work in transparent mode, every request from a client can
3658 be redirected to the proxy and HAProxy itself can proxy every request to a
3659 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
3660 be lost. This is annoying when you want access rules based on destination ip
3661 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
3662 added by HAProxy to all requests sent to the server. This header contains a
3663 value representing the original destination IP address. Since this must be
3664 configured to always use the last occurrence of this header only. Note that
3665 only the last occurrence of the header must be used, since it is really
3666 possible that the client has already brought one.
3667
3668 The keyword "header" may be used to supply a different header name to replace
3669 the default "X-Original-To". This can be useful where you might already
3670 have a "X-Original-To" header from a different application, and you need
3671 preserve it. Also if your backend server doesn't use the "X-Original-To"
3672 header and requires different one.
3673
3674 Sometimes, a same HAProxy instance may be shared between a direct client
3675 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3676 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3677 header for a known source address or network by adding the "except" keyword
3678 followed by the network address. In this case, any source IP matching the
3679 network will not cause an addition of this header. Most common uses are with
3680 private networks or 127.0.0.1.
3681
3682 This option may be specified either in the frontend or in the backend. If at
3683 least one of them uses it, the header will be added. Note that the backend's
3684 setting of the header subargument takes precedence over the frontend's if
3685 both are defined.
3686
3687 It is important to note that as long as HAProxy does not support keep-alive
3688 connections, only the first request of a connection will receive the header.
3689 For this reason, it is important to ensure that "option httpclose" is set
3690 when using this option.
3691
3692 Examples :
3693 # Original Destination address
3694 frontend www
3695 mode http
3696 option originalto except 127.0.0.1
3697
3698 # Those servers want the IP Address in X-Client-Dst
3699 backend www
3700 mode http
3701 option originalto header X-Client-Dst
3702
3703 See also : "option httpclose"
3704
3705
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003706option persist
3707no option persist
3708 Enable or disable forced persistence on down servers
3709 May be used in sections: defaults | frontend | listen | backend
3710 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003711 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003712
3713 When an HTTP request reaches a backend with a cookie which references a dead
3714 server, by default it is redispatched to another server. It is possible to
3715 force the request to be sent to the dead server first using "option persist"
3716 if absolutely needed. A common use case is when servers are under extreme
3717 load and spend their time flapping. In this case, the users would still be
3718 directed to the server they opened the session on, in the hope they would be
3719 correctly served. It is recommended to use "option redispatch" in conjunction
3720 with this option so that in the event it would not be possible to connect to
3721 the server at all (server definitely dead), the client would finally be
3722 redirected to another valid server.
3723
3724 If this option has been enabled in a "defaults" section, it can be disabled
3725 in a specific instance by prepending the "no" keyword before it.
3726
Willy Tarreau4de91492010-01-22 19:10:05 +01003727 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003728
3729
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003730option redispatch
3731no option redispatch
3732 Enable or disable session redistribution in case of connection failure
3733 May be used in sections: defaults | frontend | listen | backend
3734 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003735 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003736
3737 In HTTP mode, if a server designated by a cookie is down, clients may
3738 definitely stick to it because they cannot flush the cookie, so they will not
3739 be able to access the service anymore.
3740
3741 Specifying "option redispatch" will allow the proxy to break their
3742 persistence and redistribute them to a working server.
3743
3744 It also allows to retry last connection to another server in case of multiple
3745 connection failures. Of course, it requires having "retries" set to a nonzero
3746 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01003747
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003748 This form is the preferred form, which replaces both the "redispatch" and
3749 "redisp" keywords.
3750
3751 If this option has been enabled in a "defaults" section, it can be disabled
3752 in a specific instance by prepending the "no" keyword before it.
3753
Willy Tarreau4de91492010-01-22 19:10:05 +01003754 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003755
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003756
3757option smtpchk
3758option smtpchk <hello> <domain>
3759 Use SMTP health checks for server testing
3760 May be used in sections : defaults | frontend | listen | backend
3761 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01003762 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003763 <hello> is an optional argument. It is the "hello" command to use. It can
3764 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
3765 values will be turned into the default command ("HELO").
3766
3767 <domain> is the domain name to present to the server. It may only be
3768 specified (and is mandatory) if the hello command has been
3769 specified. By default, "localhost" is used.
3770
3771 When "option smtpchk" is set, the health checks will consist in TCP
3772 connections followed by an SMTP command. By default, this command is
3773 "HELO localhost". The server's return code is analyzed and only return codes
3774 starting with a "2" will be considered as valid. All other responses,
3775 including a lack of response will constitute an error and will indicate a
3776 dead server.
3777
3778 This test is meant to be used with SMTP servers or relays. Depending on the
3779 request, it is possible that some servers do not log each connection attempt,
3780 so you may want to experiment to improve the behaviour. Using telnet on port
3781 25 is often easier than adjusting the configuration.
3782
3783 Most often, an incoming SMTP server needs to see the client's IP address for
3784 various purposes, including spam filtering, anti-spoofing and logging. When
3785 possible, it is often wise to masquerade the client's IP address when
3786 connecting to the server using the "usesrc" argument of the "source" keyword,
3787 which requires the cttproxy feature to be compiled in.
3788
3789 Example :
3790 option smtpchk HELO mydomain.org
3791
3792 See also : "option httpchk", "source"
3793
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003794
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02003795option socket-stats
3796no option socket-stats
3797
3798 Enable or disable collecting & providing separate statistics for each socket.
3799 May be used in sections : defaults | frontend | listen | backend
3800 yes | yes | yes | no
3801
3802 Arguments : none
3803
3804
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003805option splice-auto
3806no option splice-auto
3807 Enable or disable automatic kernel acceleration on sockets in both directions
3808 May be used in sections : defaults | frontend | listen | backend
3809 yes | yes | yes | yes
3810 Arguments : none
3811
3812 When this option is enabled either on a frontend or on a backend, haproxy
3813 will automatically evaluate the opportunity to use kernel tcp splicing to
3814 forward data between the client and the server, in either direction. Haproxy
3815 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003816 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003817 are not much aggressive in order to limit excessive use of splicing. This
3818 option requires splicing to be enabled at compile time, and may be globally
3819 disabled with the global option "nosplice". Since splice uses pipes, using it
3820 requires that there are enough spare pipes.
3821
3822 Important note: kernel-based TCP splicing is a Linux-specific feature which
3823 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
3824 transfer data between sockets without copying these data to user-space, thus
3825 providing noticeable performance gains and CPU cycles savings. Since many
3826 early implementations are buggy, corrupt data and/or are inefficient, this
3827 feature is not enabled by default, and it should be used with extreme care.
3828 While it is not possible to detect the correctness of an implementation,
3829 2.6.29 is the first version offering a properly working implementation. In
3830 case of doubt, splicing may be globally disabled using the global "nosplice"
3831 keyword.
3832
3833 Example :
3834 option splice-auto
3835
3836 If this option has been enabled in a "defaults" section, it can be disabled
3837 in a specific instance by prepending the "no" keyword before it.
3838
3839 See also : "option splice-request", "option splice-response", and global
3840 options "nosplice" and "maxpipes"
3841
3842
3843option splice-request
3844no option splice-request
3845 Enable or disable automatic kernel acceleration on sockets for requests
3846 May be used in sections : defaults | frontend | listen | backend
3847 yes | yes | yes | yes
3848 Arguments : none
3849
3850 When this option is enabled either on a frontend or on a backend, haproxy
3851 will user kernel tcp splicing whenever possible to forward data going from
3852 the client to the server. It might still use the recv/send scheme if there
3853 are no spare pipes left. This option requires splicing to be enabled at
3854 compile time, and may be globally disabled with the global option "nosplice".
3855 Since splice uses pipes, using it requires that there are enough spare pipes.
3856
3857 Important note: see "option splice-auto" for usage limitations.
3858
3859 Example :
3860 option splice-request
3861
3862 If this option has been enabled in a "defaults" section, it can be disabled
3863 in a specific instance by prepending the "no" keyword before it.
3864
3865 See also : "option splice-auto", "option splice-response", and global options
3866 "nosplice" and "maxpipes"
3867
3868
3869option splice-response
3870no option splice-response
3871 Enable or disable automatic kernel acceleration on sockets for responses
3872 May be used in sections : defaults | frontend | listen | backend
3873 yes | yes | yes | yes
3874 Arguments : none
3875
3876 When this option is enabled either on a frontend or on a backend, haproxy
3877 will user kernel tcp splicing whenever possible to forward data going from
3878 the server to the client. It might still use the recv/send scheme if there
3879 are no spare pipes left. This option requires splicing to be enabled at
3880 compile time, and may be globally disabled with the global option "nosplice".
3881 Since splice uses pipes, using it requires that there are enough spare pipes.
3882
3883 Important note: see "option splice-auto" for usage limitations.
3884
3885 Example :
3886 option splice-response
3887
3888 If this option has been enabled in a "defaults" section, it can be disabled
3889 in a specific instance by prepending the "no" keyword before it.
3890
3891 See also : "option splice-auto", "option splice-request", and global options
3892 "nosplice" and "maxpipes"
3893
3894
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003895option srvtcpka
3896no option srvtcpka
3897 Enable or disable the sending of TCP keepalive packets on the server side
3898 May be used in sections : defaults | frontend | listen | backend
3899 yes | no | yes | yes
3900 Arguments : none
3901
3902 When there is a firewall or any session-aware component between a client and
3903 a server, and when the protocol involves very long sessions with long idle
3904 periods (eg: remote desktops), there is a risk that one of the intermediate
3905 components decides to expire a session which has remained idle for too long.
3906
3907 Enabling socket-level TCP keep-alives makes the system regularly send packets
3908 to the other end of the connection, leaving it active. The delay between
3909 keep-alive probes is controlled by the system only and depends both on the
3910 operating system and its tuning parameters.
3911
3912 It is important to understand that keep-alive packets are neither emitted nor
3913 received at the application level. It is only the network stacks which sees
3914 them. For this reason, even if one side of the proxy already uses keep-alives
3915 to maintain its connection alive, those keep-alive packets will not be
3916 forwarded to the other side of the proxy.
3917
3918 Please note that this has nothing to do with HTTP keep-alive.
3919
3920 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
3921 server side of a connection, which should help when session expirations are
3922 noticed between HAProxy and a server.
3923
3924 If this option has been enabled in a "defaults" section, it can be disabled
3925 in a specific instance by prepending the "no" keyword before it.
3926
3927 See also : "option clitcpka", "option tcpka"
3928
3929
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003930option ssl-hello-chk
3931 Use SSLv3 client hello health checks for server testing
3932 May be used in sections : defaults | frontend | listen | backend
3933 yes | no | yes | yes
3934 Arguments : none
3935
3936 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
3937 possible to test that the server correctly talks SSL instead of just testing
3938 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
3939 SSLv3 client hello messages are sent once the connection is established to
3940 the server, and the response is analyzed to find an SSL server hello message.
3941 The server is considered valid only when the response contains this server
3942 hello message.
3943
3944 All servers tested till there correctly reply to SSLv3 client hello messages,
3945 and most servers tested do not even log the requests containing only hello
3946 messages, which is appreciable.
3947
3948 See also: "option httpchk"
3949
3950
Willy Tarreau9ea05a72009-06-14 12:07:01 +02003951option tcp-smart-accept
3952no option tcp-smart-accept
3953 Enable or disable the saving of one ACK packet during the accept sequence
3954 May be used in sections : defaults | frontend | listen | backend
3955 yes | yes | yes | no
3956 Arguments : none
3957
3958 When an HTTP connection request comes in, the system acknowledges it on
3959 behalf of HAProxy, then the client immediately sends its request, and the
3960 system acknowledges it too while it is notifying HAProxy about the new
3961 connection. HAProxy then reads the request and responds. This means that we
3962 have one TCP ACK sent by the system for nothing, because the request could
3963 very well be acknowledged by HAProxy when it sends its response.
3964
3965 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
3966 sending this useless ACK on platforms which support it (currently at least
3967 Linux). It must not cause any problem, because the system will send it anyway
3968 after 40 ms if the response takes more time than expected to come.
3969
3970 During complex network debugging sessions, it may be desirable to disable
3971 this optimization because delayed ACKs can make troubleshooting more complex
3972 when trying to identify where packets are delayed. It is then possible to
3973 fall back to normal behaviour by specifying "no option tcp-smart-accept".
3974
3975 It is also possible to force it for non-HTTP proxies by simply specifying
3976 "option tcp-smart-accept". For instance, it can make sense with some services
3977 such as SMTP where the server speaks first.
3978
3979 It is recommended to avoid forcing this option in a defaults section. In case
3980 of doubt, consider setting it back to automatic values by prepending the
3981 "default" keyword before it, or disabling it using the "no" keyword.
3982
Willy Tarreaud88edf22009-06-14 15:48:17 +02003983 See also : "option tcp-smart-connect"
3984
3985
3986option tcp-smart-connect
3987no option tcp-smart-connect
3988 Enable or disable the saving of one ACK packet during the connect sequence
3989 May be used in sections : defaults | frontend | listen | backend
3990 yes | no | yes | yes
3991 Arguments : none
3992
3993 On certain systems (at least Linux), HAProxy can ask the kernel not to
3994 immediately send an empty ACK upon a connection request, but to directly
3995 send the buffer request instead. This saves one packet on the network and
3996 thus boosts performance. It can also be useful for some servers, because they
3997 immediately get the request along with the incoming connection.
3998
3999 This feature is enabled when "option tcp-smart-connect" is set in a backend.
4000 It is not enabled by default because it makes network troubleshooting more
4001 complex.
4002
4003 It only makes sense to enable it with protocols where the client speaks first
4004 such as HTTP. In other situations, if there is no data to send in place of
4005 the ACK, a normal ACK is sent.
4006
4007 If this option has been enabled in a "defaults" section, it can be disabled
4008 in a specific instance by prepending the "no" keyword before it.
4009
4010 See also : "option tcp-smart-accept"
4011
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004012
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004013option tcpka
4014 Enable or disable the sending of TCP keepalive packets on both sides
4015 May be used in sections : defaults | frontend | listen | backend
4016 yes | yes | yes | yes
4017 Arguments : none
4018
4019 When there is a firewall or any session-aware component between a client and
4020 a server, and when the protocol involves very long sessions with long idle
4021 periods (eg: remote desktops), there is a risk that one of the intermediate
4022 components decides to expire a session which has remained idle for too long.
4023
4024 Enabling socket-level TCP keep-alives makes the system regularly send packets
4025 to the other end of the connection, leaving it active. The delay between
4026 keep-alive probes is controlled by the system only and depends both on the
4027 operating system and its tuning parameters.
4028
4029 It is important to understand that keep-alive packets are neither emitted nor
4030 received at the application level. It is only the network stacks which sees
4031 them. For this reason, even if one side of the proxy already uses keep-alives
4032 to maintain its connection alive, those keep-alive packets will not be
4033 forwarded to the other side of the proxy.
4034
4035 Please note that this has nothing to do with HTTP keep-alive.
4036
4037 Using option "tcpka" enables the emission of TCP keep-alive probes on both
4038 the client and server sides of a connection. Note that this is meaningful
4039 only in "defaults" or "listen" sections. If this option is used in a
4040 frontend, only the client side will get keep-alives, and if this option is
4041 used in a backend, only the server side will get keep-alives. For this
4042 reason, it is strongly recommended to explicitly use "option clitcpka" and
4043 "option srvtcpka" when the configuration is split between frontends and
4044 backends.
4045
4046 See also : "option clitcpka", "option srvtcpka"
4047
Willy Tarreau844e3c52008-01-11 16:28:18 +01004048
4049option tcplog
4050 Enable advanced logging of TCP connections with session state and timers
4051 May be used in sections : defaults | frontend | listen | backend
4052 yes | yes | yes | yes
4053 Arguments : none
4054
4055 By default, the log output format is very poor, as it only contains the
4056 source and destination addresses, and the instance name. By specifying
4057 "option tcplog", each log line turns into a much richer format including, but
4058 not limited to, the connection timers, the session status, the connections
4059 numbers, the frontend, backend and server name, and of course the source
4060 address and ports. This option is useful for pure TCP proxies in order to
4061 find which of the client or server disconnects or times out. For normal HTTP
4062 proxies, it's better to use "option httplog" which is even more complete.
4063
4064 This option may be set either in the frontend or the backend.
4065
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004066 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004067
4068
Willy Tarreau844e3c52008-01-11 16:28:18 +01004069option transparent
4070no option transparent
4071 Enable client-side transparent proxying
4072 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004073 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004074 Arguments : none
4075
4076 This option was introduced in order to provide layer 7 persistence to layer 3
4077 load balancers. The idea is to use the OS's ability to redirect an incoming
4078 connection for a remote address to a local process (here HAProxy), and let
4079 this process know what address was initially requested. When this option is
4080 used, sessions without cookies will be forwarded to the original destination
4081 IP address of the incoming request (which should match that of another
4082 equipment), while requests with cookies will still be forwarded to the
4083 appropriate server.
4084
4085 Note that contrary to a common belief, this option does NOT make HAProxy
4086 present the client's IP to the server when establishing the connection.
4087
Willy Tarreaua1146052011-03-01 09:51:54 +01004088 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004089 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004090
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004091
Emeric Brun647caf12009-06-30 17:57:00 +02004092persist rdp-cookie
4093persist rdp-cookie(name)
4094 Enable RDP cookie-based persistence
4095 May be used in sections : defaults | frontend | listen | backend
4096 yes | no | yes | yes
4097 Arguments :
4098 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02004099 default cookie name "msts" will be used. There currently is no
4100 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02004101
4102 This statement enables persistence based on an RDP cookie. The RDP cookie
4103 contains all information required to find the server in the list of known
4104 servers. So when this option is set in the backend, the request is analysed
4105 and if an RDP cookie is found, it is decoded. If it matches a known server
4106 which is still UP (or if "option persist" is set), then the connection is
4107 forwarded to this server.
4108
4109 Note that this only makes sense in a TCP backend, but for this to work, the
4110 frontend must have waited long enough to ensure that an RDP cookie is present
4111 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004112 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02004113 a single "listen" section.
4114
Willy Tarreau61e28f22010-05-16 22:31:05 +02004115 Also, it is important to understand that the terminal server will emit this
4116 RDP cookie only if it is configured for "token redirection mode", which means
4117 that the "IP address redirection" option is disabled.
4118
Emeric Brun647caf12009-06-30 17:57:00 +02004119 Example :
4120 listen tse-farm
4121 bind :3389
4122 # wait up to 5s for an RDP cookie in the request
4123 tcp-request inspect-delay 5s
4124 tcp-request content accept if RDP_COOKIE
4125 # apply RDP cookie persistence
4126 persist rdp-cookie
4127 # if server is unknown, let's balance on the same cookie.
4128 # alternatively, "balance leastconn" may be useful too.
4129 balance rdp-cookie
4130 server srv1 1.1.1.1:3389
4131 server srv2 1.1.1.2:3389
4132
Simon Hormanab814e02011-06-24 14:50:20 +09004133 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
4134 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02004135
4136
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004137rate-limit sessions <rate>
4138 Set a limit on the number of new sessions accepted per second on a frontend
4139 May be used in sections : defaults | frontend | listen | backend
4140 yes | yes | yes | no
4141 Arguments :
4142 <rate> The <rate> parameter is an integer designating the maximum number
4143 of new sessions per second to accept on the frontend.
4144
4145 When the frontend reaches the specified number of new sessions per second, it
4146 stops accepting new connections until the rate drops below the limit again.
4147 During this time, the pending sessions will be kept in the socket's backlog
4148 (in system buffers) and haproxy will not even be aware that sessions are
4149 pending. When applying very low limit on a highly loaded service, it may make
4150 sense to increase the socket's backlog using the "backlog" keyword.
4151
4152 This feature is particularly efficient at blocking connection-based attacks
4153 or service abuse on fragile servers. Since the session rate is measured every
4154 millisecond, it is extremely accurate. Also, the limit applies immediately,
4155 no delay is needed at all to detect the threshold.
4156
4157 Example : limit the connection rate on SMTP to 10 per second max
4158 listen smtp
4159 mode tcp
4160 bind :25
4161 rate-limit sessions 10
4162 server 127.0.0.1:1025
4163
4164 Note : when the maximum rate is reached, the frontend's status appears as
4165 "FULL" in the statistics, exactly as when it is saturated.
4166
4167 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
4168
4169
Willy Tarreauf285f542010-01-03 20:03:03 +01004170redirect location <to> [code <code>] <option> [{if | unless} <condition>]
4171redirect prefix <to> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004172 Return an HTTP redirection if/unless a condition is matched
4173 May be used in sections : defaults | frontend | listen | backend
4174 no | yes | yes | yes
4175
4176 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01004177 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004178
Willy Tarreau0140f252008-11-19 21:07:09 +01004179 Arguments :
4180 <to> With "redirect location", the exact value in <to> is placed into
4181 the HTTP "Location" header. In case of "redirect prefix", the
4182 "Location" header is built from the concatenation of <to> and the
4183 complete URI, including the query string, unless the "drop-query"
Willy Tarreaufe651a52008-11-19 21:15:17 +01004184 option is specified (see below). As a special case, if <to>
4185 equals exactly "/" in prefix mode, then nothing is inserted
4186 before the original URI. It allows one to redirect to the same
4187 URL.
Willy Tarreau0140f252008-11-19 21:07:09 +01004188
4189 <code> The code is optional. It indicates which type of HTTP redirection
4190 is desired. Only codes 301, 302 and 303 are supported, and 302 is
4191 used if no code is specified. 301 means "Moved permanently", and
4192 a browser may cache the Location. 302 means "Moved permanently"
4193 and means that the browser should not cache the redirection. 303
4194 is equivalent to 302 except that the browser will fetch the
4195 location with a GET method.
4196
4197 <option> There are several options which can be specified to adjust the
4198 expected behaviour of a redirection :
4199
4200 - "drop-query"
4201 When this keyword is used in a prefix-based redirection, then the
4202 location will be set without any possible query-string, which is useful
4203 for directing users to a non-secure page for instance. It has no effect
4204 with a location-type redirect.
4205
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004206 - "append-slash"
4207 This keyword may be used in conjunction with "drop-query" to redirect
4208 users who use a URL not ending with a '/' to the same one with the '/'.
4209 It can be useful to ensure that search engines will only see one URL.
4210 For this, a return code 301 is preferred.
4211
Willy Tarreau0140f252008-11-19 21:07:09 +01004212 - "set-cookie NAME[=value]"
4213 A "Set-Cookie" header will be added with NAME (and optionally "=value")
4214 to the response. This is sometimes used to indicate that a user has
4215 been seen, for instance to protect against some types of DoS. No other
4216 cookie option is added, so the cookie will be a session cookie. Note
4217 that for a browser, a sole cookie name without an equal sign is
4218 different from a cookie with an equal sign.
4219
4220 - "clear-cookie NAME[=]"
4221 A "Set-Cookie" header will be added with NAME (and optionally "="), but
4222 with the "Max-Age" attribute set to zero. This will tell the browser to
4223 delete this cookie. It is useful for instance on logout pages. It is
4224 important to note that clearing the cookie "NAME" will not remove a
4225 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
4226 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004227
4228 Example: move the login URL only to HTTPS.
4229 acl clear dst_port 80
4230 acl secure dst_port 8080
4231 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01004232 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01004233 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01004234 acl cookie_set hdr_sub(cookie) SEEN=1
4235
4236 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01004237 redirect prefix https://mysite.com if login_page !secure
4238 redirect prefix http://mysite.com drop-query if login_page !uid_given
4239 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01004240 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004241
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004242 Example: send redirects for request for articles without a '/'.
4243 acl missing_slash path_reg ^/article/[^/]*$
4244 redirect code 301 prefix / drop-query append-slash if missing_slash
4245
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004246 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004247
4248
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004249redisp (deprecated)
4250redispatch (deprecated)
4251 Enable or disable session redistribution in case of connection failure
4252 May be used in sections: defaults | frontend | listen | backend
4253 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004254 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004255
4256 In HTTP mode, if a server designated by a cookie is down, clients may
4257 definitely stick to it because they cannot flush the cookie, so they will not
4258 be able to access the service anymore.
4259
4260 Specifying "redispatch" will allow the proxy to break their persistence and
4261 redistribute them to a working server.
4262
4263 It also allows to retry last connection to another server in case of multiple
4264 connection failures. Of course, it requires having "retries" set to a nonzero
4265 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004266
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004267 This form is deprecated, do not use it in any new configuration, use the new
4268 "option redispatch" instead.
4269
4270 See also : "option redispatch"
4271
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004272
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004273reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004274 Add a header at the end of the HTTP request
4275 May be used in sections : defaults | frontend | listen | backend
4276 no | yes | yes | yes
4277 Arguments :
4278 <string> is the complete line to be added. Any space or known delimiter
4279 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004280 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004281
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004282 <cond> is an optional matching condition built from ACLs. It makes it
4283 possible to ignore this rule when other conditions are not met.
4284
Willy Tarreau303c0352008-01-17 19:01:39 +01004285 A new line consisting in <string> followed by a line feed will be added after
4286 the last header of an HTTP request.
4287
4288 Header transformations only apply to traffic which passes through HAProxy,
4289 and not to traffic generated by HAProxy, such as health-checks or error
4290 responses.
4291
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004292 Example : add "X-Proto: SSL" to requests coming via port 81
4293 acl is-ssl dst_port 81
4294 reqadd X-Proto:\ SSL if is-ssl
4295
4296 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
4297 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004298
4299
Willy Tarreau5321c422010-01-28 20:35:13 +01004300reqallow <search> [{if | unless} <cond>]
4301reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004302 Definitely allow an HTTP request if a line matches a regular expression
4303 May be used in sections : defaults | frontend | listen | backend
4304 no | yes | yes | yes
4305 Arguments :
4306 <search> is the regular expression applied to HTTP headers and to the
4307 request line. This is an extended regular expression. Parenthesis
4308 grouping is supported and no preliminary backslash is required.
4309 Any space or known delimiter must be escaped using a backslash
4310 ('\'). The pattern applies to a full line at a time. The
4311 "reqallow" keyword strictly matches case while "reqiallow"
4312 ignores case.
4313
Willy Tarreau5321c422010-01-28 20:35:13 +01004314 <cond> is an optional matching condition built from ACLs. It makes it
4315 possible to ignore this rule when other conditions are not met.
4316
Willy Tarreau303c0352008-01-17 19:01:39 +01004317 A request containing any line which matches extended regular expression
4318 <search> will mark the request as allowed, even if any later test would
4319 result in a deny. The test applies both to the request line and to request
4320 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004321 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004322
4323 It is easier, faster and more powerful to use ACLs to write access policies.
4324 Reqdeny, reqallow and reqpass should be avoided in new designs.
4325
4326 Example :
4327 # allow www.* but refuse *.local
4328 reqiallow ^Host:\ www\.
4329 reqideny ^Host:\ .*\.local
4330
Willy Tarreau5321c422010-01-28 20:35:13 +01004331 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
4332 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004333
4334
Willy Tarreau5321c422010-01-28 20:35:13 +01004335reqdel <search> [{if | unless} <cond>]
4336reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004337 Delete all headers matching a regular expression in an HTTP request
4338 May be used in sections : defaults | frontend | listen | backend
4339 no | yes | yes | yes
4340 Arguments :
4341 <search> is the regular expression applied to HTTP headers and to the
4342 request line. This is an extended regular expression. Parenthesis
4343 grouping is supported and no preliminary backslash is required.
4344 Any space or known delimiter must be escaped using a backslash
4345 ('\'). The pattern applies to a full line at a time. The "reqdel"
4346 keyword strictly matches case while "reqidel" ignores case.
4347
Willy Tarreau5321c422010-01-28 20:35:13 +01004348 <cond> is an optional matching condition built from ACLs. It makes it
4349 possible to ignore this rule when other conditions are not met.
4350
Willy Tarreau303c0352008-01-17 19:01:39 +01004351 Any header line matching extended regular expression <search> in the request
4352 will be completely deleted. Most common use of this is to remove unwanted
4353 and/or dangerous headers or cookies from a request before passing it to the
4354 next servers.
4355
4356 Header transformations only apply to traffic which passes through HAProxy,
4357 and not to traffic generated by HAProxy, such as health-checks or error
4358 responses. Keep in mind that header names are not case-sensitive.
4359
4360 Example :
4361 # remove X-Forwarded-For header and SERVER cookie
4362 reqidel ^X-Forwarded-For:.*
4363 reqidel ^Cookie:.*SERVER=
4364
Willy Tarreau5321c422010-01-28 20:35:13 +01004365 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
4366 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004367
4368
Willy Tarreau5321c422010-01-28 20:35:13 +01004369reqdeny <search> [{if | unless} <cond>]
4370reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004371 Deny an HTTP request if a line matches a regular expression
4372 May be used in sections : defaults | frontend | listen | backend
4373 no | yes | yes | yes
4374 Arguments :
4375 <search> is the regular expression applied to HTTP headers and to the
4376 request line. This is an extended regular expression. Parenthesis
4377 grouping is supported and no preliminary backslash is required.
4378 Any space or known delimiter must be escaped using a backslash
4379 ('\'). The pattern applies to a full line at a time. The
4380 "reqdeny" keyword strictly matches case while "reqideny" ignores
4381 case.
4382
Willy Tarreau5321c422010-01-28 20:35:13 +01004383 <cond> is an optional matching condition built from ACLs. It makes it
4384 possible to ignore this rule when other conditions are not met.
4385
Willy Tarreau303c0352008-01-17 19:01:39 +01004386 A request containing any line which matches extended regular expression
4387 <search> will mark the request as denied, even if any later test would
4388 result in an allow. The test applies both to the request line and to request
4389 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004390 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004391
Willy Tarreauced27012008-01-17 20:35:34 +01004392 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004393 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01004394 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01004395
Willy Tarreau303c0352008-01-17 19:01:39 +01004396 It is easier, faster and more powerful to use ACLs to write access policies.
4397 Reqdeny, reqallow and reqpass should be avoided in new designs.
4398
4399 Example :
4400 # refuse *.local, then allow www.*
4401 reqideny ^Host:\ .*\.local
4402 reqiallow ^Host:\ www\.
4403
Willy Tarreau5321c422010-01-28 20:35:13 +01004404 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
4405 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004406
4407
Willy Tarreau5321c422010-01-28 20:35:13 +01004408reqpass <search> [{if | unless} <cond>]
4409reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004410 Ignore any HTTP request line matching a regular expression in next rules
4411 May be used in sections : defaults | frontend | listen | backend
4412 no | yes | yes | yes
4413 Arguments :
4414 <search> is the regular expression applied to HTTP headers and to the
4415 request line. This is an extended regular expression. Parenthesis
4416 grouping is supported and no preliminary backslash is required.
4417 Any space or known delimiter must be escaped using a backslash
4418 ('\'). The pattern applies to a full line at a time. The
4419 "reqpass" keyword strictly matches case while "reqipass" ignores
4420 case.
4421
Willy Tarreau5321c422010-01-28 20:35:13 +01004422 <cond> is an optional matching condition built from ACLs. It makes it
4423 possible to ignore this rule when other conditions are not met.
4424
Willy Tarreau303c0352008-01-17 19:01:39 +01004425 A request containing any line which matches extended regular expression
4426 <search> will skip next rules, without assigning any deny or allow verdict.
4427 The test applies both to the request line and to request headers. Keep in
4428 mind that URLs in request line are case-sensitive while header names are not.
4429
4430 It is easier, faster and more powerful to use ACLs to write access policies.
4431 Reqdeny, reqallow and reqpass should be avoided in new designs.
4432
4433 Example :
4434 # refuse *.local, then allow www.*, but ignore "www.private.local"
4435 reqipass ^Host:\ www.private\.local
4436 reqideny ^Host:\ .*\.local
4437 reqiallow ^Host:\ www\.
4438
Willy Tarreau5321c422010-01-28 20:35:13 +01004439 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
4440 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004441
4442
Willy Tarreau5321c422010-01-28 20:35:13 +01004443reqrep <search> <string> [{if | unless} <cond>]
4444reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004445 Replace a regular expression with a string in an HTTP request line
4446 May be used in sections : defaults | frontend | listen | backend
4447 no | yes | yes | yes
4448 Arguments :
4449 <search> is the regular expression applied to HTTP headers and to the
4450 request line. This is an extended regular expression. Parenthesis
4451 grouping is supported and no preliminary backslash is required.
4452 Any space or known delimiter must be escaped using a backslash
4453 ('\'). The pattern applies to a full line at a time. The "reqrep"
4454 keyword strictly matches case while "reqirep" ignores case.
4455
4456 <string> is the complete line to be added. Any space or known delimiter
4457 must be escaped using a backslash ('\'). References to matched
4458 pattern groups are possible using the common \N form, with N
4459 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004460 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004461
Willy Tarreau5321c422010-01-28 20:35:13 +01004462 <cond> is an optional matching condition built from ACLs. It makes it
4463 possible to ignore this rule when other conditions are not met.
4464
Willy Tarreau303c0352008-01-17 19:01:39 +01004465 Any line matching extended regular expression <search> in the request (both
4466 the request line and header lines) will be completely replaced with <string>.
4467 Most common use of this is to rewrite URLs or domain names in "Host" headers.
4468
4469 Header transformations only apply to traffic which passes through HAProxy,
4470 and not to traffic generated by HAProxy, such as health-checks or error
4471 responses. Note that for increased readability, it is suggested to add enough
4472 spaces between the request and the response. Keep in mind that URLs in
4473 request line are case-sensitive while header names are not.
4474
4475 Example :
4476 # replace "/static/" with "/" at the beginning of any request path.
4477 reqrep ^([^\ ]*)\ /static/(.*) \1\ /\2
4478 # replace "www.mydomain.com" with "www" in the host name.
4479 reqirep ^Host:\ www.mydomain.com Host:\ www
4480
Willy Tarreau5321c422010-01-28 20:35:13 +01004481 See also: "reqadd", "reqdel", "rsprep", section 6 about HTTP header
4482 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004483
4484
Willy Tarreau5321c422010-01-28 20:35:13 +01004485reqtarpit <search> [{if | unless} <cond>]
4486reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004487 Tarpit an HTTP request containing a line matching a regular expression
4488 May be used in sections : defaults | frontend | listen | backend
4489 no | yes | yes | yes
4490 Arguments :
4491 <search> is the regular expression applied to HTTP headers and to the
4492 request line. This is an extended regular expression. Parenthesis
4493 grouping is supported and no preliminary backslash is required.
4494 Any space or known delimiter must be escaped using a backslash
4495 ('\'). The pattern applies to a full line at a time. The
4496 "reqtarpit" keyword strictly matches case while "reqitarpit"
4497 ignores case.
4498
Willy Tarreau5321c422010-01-28 20:35:13 +01004499 <cond> is an optional matching condition built from ACLs. It makes it
4500 possible to ignore this rule when other conditions are not met.
4501
Willy Tarreau303c0352008-01-17 19:01:39 +01004502 A request containing any line which matches extended regular expression
4503 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01004504 be kept open for a pre-defined time, then will return an HTTP error 500 so
4505 that the attacker does not suspect it has been tarpitted. The status 500 will
4506 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01004507 delay is defined by "timeout tarpit", or "timeout connect" if the former is
4508 not set.
4509
4510 The goal of the tarpit is to slow down robots attacking servers with
4511 identifiable requests. Many robots limit their outgoing number of connections
4512 and stay connected waiting for a reply which can take several minutes to
4513 come. Depending on the environment and attack, it may be particularly
4514 efficient at reducing the load on the network and firewalls.
4515
Willy Tarreau5321c422010-01-28 20:35:13 +01004516 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01004517 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
4518 # block all others.
4519 reqipass ^User-Agent:\.*(Mozilla|MSIE)
4520 reqitarpit ^User-Agent:
4521
Willy Tarreau5321c422010-01-28 20:35:13 +01004522 # block bad guys
4523 acl badguys src 10.1.0.3 172.16.13.20/28
4524 reqitarpit . if badguys
4525
4526 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
4527 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004528
4529
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02004530retries <value>
4531 Set the number of retries to perform on a server after a connection failure
4532 May be used in sections: defaults | frontend | listen | backend
4533 yes | no | yes | yes
4534 Arguments :
4535 <value> is the number of times a connection attempt should be retried on
4536 a server when a connection either is refused or times out. The
4537 default value is 3.
4538
4539 It is important to understand that this value applies to the number of
4540 connection attempts, not full requests. When a connection has effectively
4541 been established to a server, there will be no more retry.
4542
4543 In order to avoid immediate reconnections to a server which is restarting,
4544 a turn-around timer of 1 second is applied before a retry occurs.
4545
4546 When "option redispatch" is set, the last retry may be performed on another
4547 server even if a cookie references a different server.
4548
4549 See also : "option redispatch"
4550
4551
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004552rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004553 Add a header at the end of the HTTP response
4554 May be used in sections : defaults | frontend | listen | backend
4555 no | yes | yes | yes
4556 Arguments :
4557 <string> is the complete line to be added. Any space or known delimiter
4558 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004559 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004560
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004561 <cond> is an optional matching condition built from ACLs. It makes it
4562 possible to ignore this rule when other conditions are not met.
4563
Willy Tarreau303c0352008-01-17 19:01:39 +01004564 A new line consisting in <string> followed by a line feed will be added after
4565 the last header of an HTTP response.
4566
4567 Header transformations only apply to traffic which passes through HAProxy,
4568 and not to traffic generated by HAProxy, such as health-checks or error
4569 responses.
4570
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004571 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
4572 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004573
4574
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004575rspdel <search> [{if | unless} <cond>]
4576rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004577 Delete all headers matching a regular expression in an HTTP response
4578 May be used in sections : defaults | frontend | listen | backend
4579 no | yes | yes | yes
4580 Arguments :
4581 <search> is the regular expression applied to HTTP headers and to the
4582 response line. This is an extended regular expression, so
4583 parenthesis grouping is supported and no preliminary backslash
4584 is required. Any space or known delimiter must be escaped using
4585 a backslash ('\'). The pattern applies to a full line at a time.
4586 The "rspdel" keyword strictly matches case while "rspidel"
4587 ignores case.
4588
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004589 <cond> is an optional matching condition built from ACLs. It makes it
4590 possible to ignore this rule when other conditions are not met.
4591
Willy Tarreau303c0352008-01-17 19:01:39 +01004592 Any header line matching extended regular expression <search> in the response
4593 will be completely deleted. Most common use of this is to remove unwanted
4594 and/or sensible headers or cookies from a response before passing it to the
4595 client.
4596
4597 Header transformations only apply to traffic which passes through HAProxy,
4598 and not to traffic generated by HAProxy, such as health-checks or error
4599 responses. Keep in mind that header names are not case-sensitive.
4600
4601 Example :
4602 # remove the Server header from responses
4603 reqidel ^Server:.*
4604
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004605 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
4606 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004607
4608
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004609rspdeny <search> [{if | unless} <cond>]
4610rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004611 Block an HTTP response if a line matches a regular expression
4612 May be used in sections : defaults | frontend | listen | backend
4613 no | yes | yes | yes
4614 Arguments :
4615 <search> is the regular expression applied to HTTP headers and to the
4616 response line. This is an extended regular expression, so
4617 parenthesis grouping is supported and no preliminary backslash
4618 is required. Any space or known delimiter must be escaped using
4619 a backslash ('\'). The pattern applies to a full line at a time.
4620 The "rspdeny" keyword strictly matches case while "rspideny"
4621 ignores case.
4622
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004623 <cond> is an optional matching condition built from ACLs. It makes it
4624 possible to ignore this rule when other conditions are not met.
4625
Willy Tarreau303c0352008-01-17 19:01:39 +01004626 A response containing any line which matches extended regular expression
4627 <search> will mark the request as denied. The test applies both to the
4628 response line and to response headers. Keep in mind that header names are not
4629 case-sensitive.
4630
4631 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01004632 block the response before it reaches the client. If a response is denied, it
4633 will be replaced with an HTTP 502 error so that the client never retrieves
4634 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01004635
4636 It is easier, faster and more powerful to use ACLs to write access policies.
4637 Rspdeny should be avoided in new designs.
4638
4639 Example :
4640 # Ensure that no content type matching ms-word will leak
4641 rspideny ^Content-type:\.*/ms-word
4642
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004643 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
4644 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004645
4646
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004647rsprep <search> <string> [{if | unless} <cond>]
4648rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004649 Replace a regular expression with a string in an HTTP response line
4650 May be used in sections : defaults | frontend | listen | backend
4651 no | yes | yes | yes
4652 Arguments :
4653 <search> is the regular expression applied to HTTP headers and to the
4654 response line. This is an extended regular expression, so
4655 parenthesis grouping is supported and no preliminary backslash
4656 is required. Any space or known delimiter must be escaped using
4657 a backslash ('\'). The pattern applies to a full line at a time.
4658 The "rsprep" keyword strictly matches case while "rspirep"
4659 ignores case.
4660
4661 <string> is the complete line to be added. Any space or known delimiter
4662 must be escaped using a backslash ('\'). References to matched
4663 pattern groups are possible using the common \N form, with N
4664 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004665 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004666
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004667 <cond> is an optional matching condition built from ACLs. It makes it
4668 possible to ignore this rule when other conditions are not met.
4669
Willy Tarreau303c0352008-01-17 19:01:39 +01004670 Any line matching extended regular expression <search> in the response (both
4671 the response line and header lines) will be completely replaced with
4672 <string>. Most common use of this is to rewrite Location headers.
4673
4674 Header transformations only apply to traffic which passes through HAProxy,
4675 and not to traffic generated by HAProxy, such as health-checks or error
4676 responses. Note that for increased readability, it is suggested to add enough
4677 spaces between the request and the response. Keep in mind that header names
4678 are not case-sensitive.
4679
4680 Example :
4681 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
4682 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
4683
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004684 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
4685 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004686
4687
David du Colombier486df472011-03-17 10:40:26 +01004688server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004689 Declare a server in a backend
4690 May be used in sections : defaults | frontend | listen | backend
4691 no | no | yes | yes
4692 Arguments :
4693 <name> is the internal name assigned to this server. This name will
4694 appear in logs and alerts.
4695
David du Colombier486df472011-03-17 10:40:26 +01004696 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
4697 resolvable hostname is supported, but this name will be resolved
4698 during start-up. Address "0.0.0.0" or "*" has a special meaning.
4699 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02004700 address as the one from the client connection. This is useful in
4701 transparent proxy architectures where the client's connection is
4702 intercepted and haproxy must forward to the original destination
4703 address. This is more or less what the "transparent" keyword does
4704 except that with a server it's possible to limit concurrency and
4705 to report statistics.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004706
4707 <ports> is an optional port specification. If set, all connections will
4708 be sent to this port. If unset, the same port the client
4709 connected to will be used. The port may also be prefixed by a "+"
4710 or a "-". In this case, the server's port will be determined by
4711 adding this value to the client's port.
4712
4713 <param*> is a list of parameters for this server. The "server" keywords
4714 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004715 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004716
4717 Examples :
4718 server first 10.1.1.1:1080 cookie first check inter 1000
4719 server second 10.1.1.2:1080 cookie second check inter 1000
4720
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004721 See also: "default-server" and section 5 about server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004722
4723
4724source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02004725source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004726source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004727 Set the source address for outgoing connections
4728 May be used in sections : defaults | frontend | listen | backend
4729 yes | no | yes | yes
4730 Arguments :
4731 <addr> is the IPv4 address HAProxy will bind to before connecting to a
4732 server. This address is also used as a source for health checks.
4733 The default value of 0.0.0.0 means that the system will select
4734 the most appropriate address to reach its destination.
4735
4736 <port> is an optional port. It is normally not needed but may be useful
4737 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004738 the system will select a free port. Note that port ranges are not
4739 supported in the backend. If you want to force port ranges, you
4740 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004741
4742 <addr2> is the IP address to present to the server when connections are
4743 forwarded in full transparent proxy mode. This is currently only
4744 supported on some patched Linux kernels. When this address is
4745 specified, clients connecting to the server will be presented
4746 with this address, while health checks will still use the address
4747 <addr>.
4748
4749 <port2> is the optional port to present to the server when connections
4750 are forwarded in full transparent proxy mode (see <addr2> above).
4751 The default value of zero means the system will select a free
4752 port.
4753
Willy Tarreaubce70882009-09-07 11:51:47 +02004754 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
4755 This is the name of a comma-separated header list which can
4756 contain multiple IP addresses. By default, the last occurrence is
4757 used. This is designed to work with the X-Forwarded-For header
4758 and to automatically bind to the the client's IP address as seen
4759 by previous proxy, typically Stunnel. In order to use another
4760 occurrence from the last one, please see the <occ> parameter
4761 below. When the header (or occurrence) is not found, no binding
4762 is performed so that the proxy's default IP address is used. Also
4763 keep in mind that the header name is case insensitive, as for any
4764 HTTP header.
4765
4766 <occ> is the occurrence number of a value to be used in a multi-value
4767 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
4768 in order to specificy which occurrence to use for the source IP
4769 address. Positive values indicate a position from the first
4770 occurrence, 1 being the first one. Negative values indicate
4771 positions relative to the last one, -1 being the last one. This
4772 is helpful for situations where an X-Forwarded-For header is set
4773 at the entry point of an infrastructure and must be used several
4774 proxy layers away. When this value is not specified, -1 is
4775 assumed. Passing a zero here disables the feature.
4776
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004777 <name> is an optional interface name to which to bind to for outgoing
4778 traffic. On systems supporting this features (currently, only
4779 Linux), this allows one to bind all traffic to the server to
4780 this interface even if it is not the one the system would select
4781 based on routing tables. This should be used with extreme care.
4782 Note that using this option requires root privileges.
4783
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004784 The "source" keyword is useful in complex environments where a specific
4785 address only is allowed to connect to the servers. It may be needed when a
4786 private address must be used through a public gateway for instance, and it is
4787 known that the system cannot determine the adequate source address by itself.
4788
4789 An extension which is available on certain patched Linux kernels may be used
4790 through the "usesrc" optional keyword. It makes it possible to connect to the
4791 servers with an IP address which does not belong to the system itself. This
4792 is called "full transparent proxy mode". For this to work, the destination
4793 servers have to route their traffic back to this address through the machine
4794 running HAProxy, and IP forwarding must generally be enabled on this machine.
4795
4796 In this "full transparent proxy" mode, it is possible to force a specific IP
4797 address to be presented to the servers. This is not much used in fact. A more
4798 common use is to tell HAProxy to present the client's IP address. For this,
4799 there are two methods :
4800
4801 - present the client's IP and port addresses. This is the most transparent
4802 mode, but it can cause problems when IP connection tracking is enabled on
4803 the machine, because a same connection may be seen twice with different
4804 states. However, this solution presents the huge advantage of not
4805 limiting the system to the 64k outgoing address+port couples, because all
4806 of the client ranges may be used.
4807
4808 - present only the client's IP address and select a spare port. This
4809 solution is still quite elegant but slightly less transparent (downstream
4810 firewalls logs will not match upstream's). It also presents the downside
4811 of limiting the number of concurrent connections to the usual 64k ports.
4812 However, since the upstream and downstream ports are different, local IP
4813 connection tracking on the machine will not be upset by the reuse of the
4814 same session.
4815
4816 Note that depending on the transparent proxy technology used, it may be
4817 required to force the source address. In fact, cttproxy version 2 requires an
4818 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
4819 IP address because it creates NAT entries which much match the exact outgoing
4820 address. Tproxy version 4 and some other kernel patches which work in pure
4821 forwarding mode generally will not have this limitation.
4822
4823 This option sets the default source for all servers in the backend. It may
4824 also be specified in a "defaults" section. Finer source address specification
4825 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004826 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004827
4828 Examples :
4829 backend private
4830 # Connect to the servers using our 192.168.1.200 source address
4831 source 192.168.1.200
4832
4833 backend transparent_ssl1
4834 # Connect to the SSL farm from the client's source address
4835 source 192.168.1.200 usesrc clientip
4836
4837 backend transparent_ssl2
4838 # Connect to the SSL farm from the client's source address and port
4839 # not recommended if IP conntrack is present on the local machine.
4840 source 192.168.1.200 usesrc client
4841
4842 backend transparent_ssl3
4843 # Connect to the SSL farm from the client's source address. It
4844 # is more conntrack-friendly.
4845 source 192.168.1.200 usesrc clientip
4846
4847 backend transparent_smtp
4848 # Connect to the SMTP farm from the client's source address/port
4849 # with Tproxy version 4.
4850 source 0.0.0.0 usesrc clientip
4851
Willy Tarreaubce70882009-09-07 11:51:47 +02004852 backend transparent_http
4853 # Connect to the servers using the client's IP as seen by previous
4854 # proxy.
4855 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
4856
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004857 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004858 the Linux kernel on www.balabit.com, the "bind" keyword.
4859
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004860
Willy Tarreau844e3c52008-01-11 16:28:18 +01004861srvtimeout <timeout> (deprecated)
4862 Set the maximum inactivity time on the server side.
4863 May be used in sections : defaults | frontend | listen | backend
4864 yes | no | yes | yes
4865 Arguments :
4866 <timeout> is the timeout value specified in milliseconds by default, but
4867 can be in any other unit if the number is suffixed by the unit,
4868 as explained at the top of this document.
4869
4870 The inactivity timeout applies when the server is expected to acknowledge or
4871 send data. In HTTP mode, this timeout is particularly important to consider
4872 during the first phase of the server's response, when it has to send the
4873 headers, as it directly represents the server's processing time for the
4874 request. To find out what value to put there, it's often good to start with
4875 what would be considered as unacceptable response times, then check the logs
4876 to observe the response time distribution, and adjust the value accordingly.
4877
4878 The value is specified in milliseconds by default, but can be in any other
4879 unit if the number is suffixed by the unit, as specified at the top of this
4880 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
4881 recommended that the client timeout remains equal to the server timeout in
4882 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004883 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01004884 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01004885 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01004886
4887 This parameter is specific to backends, but can be specified once for all in
4888 "defaults" sections. This is in fact one of the easiest solutions not to
4889 forget about it. An unspecified timeout results in an infinite timeout, which
4890 is not recommended. Such a usage is accepted and works but reports a warning
4891 during startup because it may results in accumulation of expired sessions in
4892 the system if the system's timeouts are not configured either.
4893
4894 This parameter is provided for compatibility but is currently deprecated.
4895 Please use "timeout server" instead.
4896
4897 See also : "timeout server", "timeout client" and "clitimeout".
4898
4899
Cyril Bonté66c327d2010-10-12 00:14:37 +02004900stats admin { if | unless } <cond>
4901 Enable statistics admin level if/unless a condition is matched
4902 May be used in sections : defaults | frontend | listen | backend
4903 no | no | yes | yes
4904
4905 This statement enables the statistics admin level if/unless a condition is
4906 matched.
4907
4908 The admin level allows to enable/disable servers from the web interface. By
4909 default, statistics page is read-only for security reasons.
4910
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01004911 Note : Consider not using this feature in multi-process mode (nbproc > 1)
4912 unless you know what you do : memory is not shared between the
4913 processes, which can result in random behaviours.
4914
Cyril Bonté23b39d92011-02-10 22:54:44 +01004915 Currently, the POST request is limited to the buffer size minus the reserved
4916 buffer space, which means that if the list of servers is too long, the
4917 request won't be processed. It is recommended to alter few servers at a
4918 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02004919
4920 Example :
4921 # statistics admin level only for localhost
4922 backend stats_localhost
4923 stats enable
4924 stats admin if LOCALHOST
4925
4926 Example :
4927 # statistics admin level always enabled because of the authentication
4928 backend stats_auth
4929 stats enable
4930 stats auth admin:AdMiN123
4931 stats admin if TRUE
4932
4933 Example :
4934 # statistics admin level depends on the authenticated user
4935 userlist stats-auth
4936 group admin users admin
4937 user admin insecure-password AdMiN123
4938 group readonly users haproxy
4939 user haproxy insecure-password haproxy
4940
4941 backend stats_auth
4942 stats enable
4943 acl AUTH http_auth(stats-auth)
4944 acl AUTH_ADMIN http_auth_group(stats-auth) admin
4945 stats http-request auth unless AUTH
4946 stats admin if AUTH_ADMIN
4947
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01004948 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
4949 "bind-process", section 3.4 about userlists and section 7 about
4950 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02004951
4952
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004953stats auth <user>:<passwd>
4954 Enable statistics with authentication and grant access to an account
4955 May be used in sections : defaults | frontend | listen | backend
4956 yes | no | yes | yes
4957 Arguments :
4958 <user> is a user name to grant access to
4959
4960 <passwd> is the cleartext password associated to this user
4961
4962 This statement enables statistics with default settings, and restricts access
4963 to declared users only. It may be repeated as many times as necessary to
4964 allow as many users as desired. When a user tries to access the statistics
4965 without a valid account, a "401 Forbidden" response will be returned so that
4966 the browser asks the user to provide a valid user and password. The real
4967 which will be returned to the browser is configurable using "stats realm".
4968
4969 Since the authentication method is HTTP Basic Authentication, the passwords
4970 circulate in cleartext on the network. Thus, it was decided that the
4971 configuration file would also use cleartext passwords to remind the users
4972 that those ones should not be sensible and not shared with any other account.
4973
4974 It is also possible to reduce the scope of the proxies which appear in the
4975 report using "stats scope".
4976
4977 Though this statement alone is enough to enable statistics reporting, it is
4978 recommended to set all other settings in order to avoid relying on default
4979 unobvious parameters.
4980
4981 Example :
4982 # public access (limited to this backend only)
4983 backend public_www
4984 server srv1 192.168.0.1:80
4985 stats enable
4986 stats hide-version
4987 stats scope .
4988 stats uri /admin?stats
4989 stats realm Haproxy\ Statistics
4990 stats auth admin1:AdMiN123
4991 stats auth admin2:AdMiN321
4992
4993 # internal monitoring access (unlimited)
4994 backend private_monitoring
4995 stats enable
4996 stats uri /admin?stats
4997 stats refresh 5s
4998
4999 See also : "stats enable", "stats realm", "stats scope", "stats uri"
5000
5001
5002stats enable
5003 Enable statistics reporting with default settings
5004 May be used in sections : defaults | frontend | listen | backend
5005 yes | no | yes | yes
5006 Arguments : none
5007
5008 This statement enables statistics reporting with default settings defined
5009 at build time. Unless stated otherwise, these settings are used :
5010 - stats uri : /haproxy?stats
5011 - stats realm : "HAProxy Statistics"
5012 - stats auth : no authentication
5013 - stats scope : no restriction
5014
5015 Though this statement alone is enough to enable statistics reporting, it is
5016 recommended to set all other settings in order to avoid relying on default
5017 unobvious parameters.
5018
5019 Example :
5020 # public access (limited to this backend only)
5021 backend public_www
5022 server srv1 192.168.0.1:80
5023 stats enable
5024 stats hide-version
5025 stats scope .
5026 stats uri /admin?stats
5027 stats realm Haproxy\ Statistics
5028 stats auth admin1:AdMiN123
5029 stats auth admin2:AdMiN321
5030
5031 # internal monitoring access (unlimited)
5032 backend private_monitoring
5033 stats enable
5034 stats uri /admin?stats
5035 stats refresh 5s
5036
5037 See also : "stats auth", "stats realm", "stats uri"
5038
5039
Willy Tarreaud63335a2010-02-26 12:56:52 +01005040stats hide-version
5041 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005042 May be used in sections : defaults | frontend | listen | backend
5043 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01005044 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005045
Willy Tarreaud63335a2010-02-26 12:56:52 +01005046 By default, the stats page reports some useful status information along with
5047 the statistics. Among them is HAProxy's version. However, it is generally
5048 considered dangerous to report precise version to anyone, as it can help them
5049 target known weaknesses with specific attacks. The "stats hide-version"
5050 statement removes the version from the statistics report. This is recommended
5051 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005052
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005053 Though this statement alone is enough to enable statistics reporting, it is
5054 recommended to set all other settings in order to avoid relying on default
5055 unobvious parameters.
5056
Willy Tarreaud63335a2010-02-26 12:56:52 +01005057 Example :
5058 # public access (limited to this backend only)
5059 backend public_www
5060 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005061 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005062 stats hide-version
5063 stats scope .
5064 stats uri /admin?stats
5065 stats realm Haproxy\ Statistics
5066 stats auth admin1:AdMiN123
5067 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005068
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005069 # internal monitoring access (unlimited)
5070 backend private_monitoring
5071 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005072 stats uri /admin?stats
5073 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01005074
Willy Tarreaud63335a2010-02-26 12:56:52 +01005075 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005076
Willy Tarreau983e01e2010-01-11 18:42:06 +01005077
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02005078stats http-request { allow | deny | auth [realm <realm>] }
5079 [ { if | unless } <condition> ]
5080 Access control for statistics
5081
5082 May be used in sections: defaults | frontend | listen | backend
5083 no | no | yes | yes
5084
5085 As "http-request", these set of options allow to fine control access to
5086 statistics. Each option may be followed by if/unless and acl.
5087 First option with matched condition (or option without condition) is final.
5088 For "deny" a 403 error will be returned, for "allow" normal processing is
5089 performed, for "auth" a 401/407 error code is returned so the client
5090 should be asked to enter a username and password.
5091
5092 There is no fixed limit to the number of http-request statements per
5093 instance.
5094
5095 See also : "http-request", section 3.4 about userlists and section 7
5096 about ACL usage.
5097
5098
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005099stats realm <realm>
5100 Enable statistics and set authentication realm
5101 May be used in sections : defaults | frontend | listen | backend
5102 yes | no | yes | yes
5103 Arguments :
5104 <realm> is the name of the HTTP Basic Authentication realm reported to
5105 the browser. The browser uses it to display it in the pop-up
5106 inviting the user to enter a valid username and password.
5107
5108 The realm is read as a single word, so any spaces in it should be escaped
5109 using a backslash ('\').
5110
5111 This statement is useful only in conjunction with "stats auth" since it is
5112 only related to authentication.
5113
5114 Though this statement alone is enough to enable statistics reporting, it is
5115 recommended to set all other settings in order to avoid relying on default
5116 unobvious parameters.
5117
5118 Example :
5119 # public access (limited to this backend only)
5120 backend public_www
5121 server srv1 192.168.0.1:80
5122 stats enable
5123 stats hide-version
5124 stats scope .
5125 stats uri /admin?stats
5126 stats realm Haproxy\ Statistics
5127 stats auth admin1:AdMiN123
5128 stats auth admin2:AdMiN321
5129
5130 # internal monitoring access (unlimited)
5131 backend private_monitoring
5132 stats enable
5133 stats uri /admin?stats
5134 stats refresh 5s
5135
5136 See also : "stats auth", "stats enable", "stats uri"
5137
5138
5139stats refresh <delay>
5140 Enable statistics with automatic refresh
5141 May be used in sections : defaults | frontend | listen | backend
5142 yes | no | yes | yes
5143 Arguments :
5144 <delay> is the suggested refresh delay, specified in seconds, which will
5145 be returned to the browser consulting the report page. While the
5146 browser is free to apply any delay, it will generally respect it
5147 and refresh the page this every seconds. The refresh interval may
5148 be specified in any other non-default time unit, by suffixing the
5149 unit after the value, as explained at the top of this document.
5150
5151 This statement is useful on monitoring displays with a permanent page
5152 reporting the load balancer's activity. When set, the HTML report page will
5153 include a link "refresh"/"stop refresh" so that the user can select whether
5154 he wants automatic refresh of the page or not.
5155
5156 Though this statement alone is enough to enable statistics reporting, it is
5157 recommended to set all other settings in order to avoid relying on default
5158 unobvious parameters.
5159
5160 Example :
5161 # public access (limited to this backend only)
5162 backend public_www
5163 server srv1 192.168.0.1:80
5164 stats enable
5165 stats hide-version
5166 stats scope .
5167 stats uri /admin?stats
5168 stats realm Haproxy\ Statistics
5169 stats auth admin1:AdMiN123
5170 stats auth admin2:AdMiN321
5171
5172 # internal monitoring access (unlimited)
5173 backend private_monitoring
5174 stats enable
5175 stats uri /admin?stats
5176 stats refresh 5s
5177
5178 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5179
5180
5181stats scope { <name> | "." }
5182 Enable statistics and limit access scope
5183 May be used in sections : defaults | frontend | listen | backend
5184 yes | no | yes | yes
5185 Arguments :
5186 <name> is the name of a listen, frontend or backend section to be
5187 reported. The special name "." (a single dot) designates the
5188 section in which the statement appears.
5189
5190 When this statement is specified, only the sections enumerated with this
5191 statement will appear in the report. All other ones will be hidden. This
5192 statement may appear as many times as needed if multiple sections need to be
5193 reported. Please note that the name checking is performed as simple string
5194 comparisons, and that it is never checked that a give section name really
5195 exists.
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
Willy Tarreaud63335a2010-02-26 12:56:52 +01005221
Willy Tarreauc9705a12010-07-27 20:05:50 +02005222stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01005223 Enable reporting of a description on the statistics page.
5224 May be used in sections : defaults | frontend | listen | backend
5225 yes | no | yes | yes
5226
Willy Tarreauc9705a12010-07-27 20:05:50 +02005227 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01005228 description from global section is automatically used instead.
5229
5230 This statement is useful for users that offer shared services to their
5231 customers, where node or description should be different for each customer.
5232
5233 Though this statement alone is enough to enable statistics reporting, it is
5234 recommended to set all other settings in order to avoid relying on default
5235 unobvious parameters.
5236
5237 Example :
5238 # internal monitoring access (unlimited)
5239 backend private_monitoring
5240 stats enable
5241 stats show-desc Master node for Europe, Asia, Africa
5242 stats uri /admin?stats
5243 stats refresh 5s
5244
5245 See also: "show-node", "stats enable", "stats uri" and "description" in
5246 global section.
5247
5248
5249stats show-legends
5250 Enable reporting additional informations on the statistics page :
5251 - cap: capabilities (proxy)
5252 - mode: one of tcp, http or health (proxy)
5253 - id: SNMP ID (proxy, socket, server)
5254 - IP (socket, server)
5255 - cookie (backend, server)
5256
5257 Though this statement alone is enough to enable statistics reporting, it is
5258 recommended to set all other settings in order to avoid relying on default
5259 unobvious parameters.
5260
5261 See also: "stats enable", "stats uri".
5262
5263
5264stats show-node [ <name> ]
5265 Enable reporting of a host name on the statistics page.
5266 May be used in sections : defaults | frontend | listen | backend
5267 yes | no | yes | yes
5268 Arguments:
5269 <name> is an optional name to be reported. If unspecified, the
5270 node name from global section is automatically used instead.
5271
5272 This statement is useful for users that offer shared services to their
5273 customers, where node or description might be different on a stats page
5274 provided for each customer.
5275
5276 Though this statement alone is enough to enable statistics reporting, it is
5277 recommended to set all other settings in order to avoid relying on default
5278 unobvious parameters.
5279
5280 Example:
5281 # internal monitoring access (unlimited)
5282 backend private_monitoring
5283 stats enable
5284 stats show-node Europe-1
5285 stats uri /admin?stats
5286 stats refresh 5s
5287
5288 See also: "show-desc", "stats enable", "stats uri", and "node" in global
5289 section.
5290
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005291
5292stats uri <prefix>
5293 Enable statistics and define the URI prefix to access them
5294 May be used in sections : defaults | frontend | listen | backend
5295 yes | no | yes | yes
5296 Arguments :
5297 <prefix> is the prefix of any URI which will be redirected to stats. This
5298 prefix may contain a question mark ('?') to indicate part of a
5299 query string.
5300
5301 The statistics URI is intercepted on the relayed traffic, so it appears as a
5302 page within the normal application. It is strongly advised to ensure that the
5303 selected URI will never appear in the application, otherwise it will never be
5304 possible to reach it in the application.
5305
5306 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005307 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005308 It is generally a good idea to include a question mark in the URI so that
5309 intermediate proxies refrain from caching the results. Also, since any string
5310 beginning with the prefix will be accepted as a stats request, the question
5311 mark helps ensuring that no valid URI will begin with the same words.
5312
5313 It is sometimes very convenient to use "/" as the URI prefix, and put that
5314 statement in a "listen" instance of its own. That makes it easy to dedicate
5315 an address or a port to statistics only.
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 # public access (limited to this backend only)
5323 backend public_www
5324 server srv1 192.168.0.1:80
5325 stats enable
5326 stats hide-version
5327 stats scope .
5328 stats uri /admin?stats
5329 stats realm Haproxy\ Statistics
5330 stats auth admin1:AdMiN123
5331 stats auth admin2:AdMiN321
5332
5333 # internal monitoring access (unlimited)
5334 backend private_monitoring
5335 stats enable
5336 stats uri /admin?stats
5337 stats refresh 5s
5338
5339 See also : "stats auth", "stats enable", "stats realm"
5340
5341
Willy Tarreaud63335a2010-02-26 12:56:52 +01005342stick match <pattern> [table <table>] [{if | unless} <cond>]
5343 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005344 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01005345 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005346
5347 Arguments :
5348 <pattern> is a pattern extraction rule as described in section 7.8. It
5349 describes what elements of the incoming request or connection
5350 will be analysed in the hope to find a matching entry in a
5351 stickiness table. This rule is mandatory.
5352
5353 <table> is an optional stickiness table name. If unspecified, the same
5354 backend's table is used. A stickiness table is declared using
5355 the "stick-table" statement.
5356
5357 <cond> is an optional matching condition. It makes it possible to match
5358 on a certain criterion only when other conditions are met (or
5359 not met). For instance, it could be used to match on a source IP
5360 address except when a request passes through a known proxy, in
5361 which case we'd match on a header containing that IP address.
5362
5363 Some protocols or applications require complex stickiness rules and cannot
5364 always simply rely on cookies nor hashing. The "stick match" statement
5365 describes a rule to extract the stickiness criterion from an incoming request
5366 or connection. See section 7 for a complete list of possible patterns and
5367 transformation rules.
5368
5369 The table has to be declared using the "stick-table" statement. It must be of
5370 a type compatible with the pattern. By default it is the one which is present
5371 in the same backend. It is possible to share a table with other backends by
5372 referencing it using the "table" keyword. If another table is referenced,
5373 the server's ID inside the backends are used. By default, all server IDs
5374 start at 1 in each backend, so the server ordering is enough. But in case of
5375 doubt, it is highly recommended to force server IDs using their "id" setting.
5376
5377 It is possible to restrict the conditions where a "stick match" statement
5378 will apply, using "if" or "unless" followed by a condition. See section 7 for
5379 ACL based conditions.
5380
5381 There is no limit on the number of "stick match" statements. The first that
5382 applies and matches will cause the request to be directed to the same server
5383 as was used for the request which created the entry. That way, multiple
5384 matches can be used as fallbacks.
5385
5386 The stick rules are checked after the persistence cookies, so they will not
5387 affect stickiness if a cookie has already been used to select a server. That
5388 way, it becomes very easy to insert cookies and match on IP addresses in
5389 order to maintain stickiness between HTTP and HTTPS.
5390
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005391 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5392 unless you know what you do : memory is not shared between the
5393 processes, which can result in random behaviours.
5394
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005395 Example :
5396 # forward SMTP users to the same server they just used for POP in the
5397 # last 30 minutes
5398 backend pop
5399 mode tcp
5400 balance roundrobin
5401 stick store-request src
5402 stick-table type ip size 200k expire 30m
5403 server s1 192.168.1.1:110
5404 server s2 192.168.1.1:110
5405
5406 backend smtp
5407 mode tcp
5408 balance roundrobin
5409 stick match src table pop
5410 server s1 192.168.1.1:25
5411 server s2 192.168.1.1:25
5412
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005413 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5414 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005415
5416
5417stick on <pattern> [table <table>] [{if | unless} <condition>]
5418 Define a request pattern to associate a user to a server
5419 May be used in sections : defaults | frontend | listen | backend
5420 no | no | yes | yes
5421
5422 Note : This form is exactly equivalent to "stick match" followed by
5423 "stick store-request", all with the same arguments. Please refer
5424 to both keywords for details. It is only provided as a convenience
5425 for writing more maintainable configurations.
5426
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005427 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5428 unless you know what you do : memory is not shared between the
5429 processes, which can result in random behaviours.
5430
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005431 Examples :
5432 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01005433 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005434
5435 # ...is strictly equivalent to this one :
5436 stick match src table pop if !localhost
5437 stick store-request src table pop if !localhost
5438
5439
5440 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
5441 # well as HTTP without cookie. Share the same table between both accesses.
5442 backend http
5443 mode http
5444 balance roundrobin
5445 stick on src table https
5446 cookie SRV insert indirect nocache
5447 server s1 192.168.1.1:80 cookie s1
5448 server s2 192.168.1.1:80 cookie s2
5449
5450 backend https
5451 mode tcp
5452 balance roundrobin
5453 stick-table type ip size 200k expire 30m
5454 stick on src
5455 server s1 192.168.1.1:443
5456 server s2 192.168.1.1:443
5457
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005458 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005459
5460
5461stick store-request <pattern> [table <table>] [{if | unless} <condition>]
5462 Define a request pattern used to create an entry in a stickiness table
5463 May be used in sections : defaults | frontend | listen | backend
5464 no | no | yes | yes
5465
5466 Arguments :
5467 <pattern> is a pattern extraction rule as described in section 7.8. It
5468 describes what elements of the incoming request or connection
5469 will be analysed, extracted and stored in the table once a
5470 server is selected.
5471
5472 <table> is an optional stickiness table name. If unspecified, the same
5473 backend's table is used. A stickiness table is declared using
5474 the "stick-table" statement.
5475
5476 <cond> is an optional storage condition. It makes it possible to store
5477 certain criteria only when some conditions are met (or not met).
5478 For instance, it could be used to store the source IP address
5479 except when the request passes through a known proxy, in which
5480 case we'd store a converted form of a header containing that IP
5481 address.
5482
5483 Some protocols or applications require complex stickiness rules and cannot
5484 always simply rely on cookies nor hashing. The "stick store-request" statement
5485 describes a rule to decide what to extract from the request and when to do
5486 it, in order to store it into a stickiness table for further requests to
5487 match it using the "stick match" statement. Obviously the extracted part must
5488 make sense and have a chance to be matched in a further request. Storing a
5489 client's IP address for instance often makes sense. Storing an ID found in a
5490 URL parameter also makes sense. Storing a source port will almost never make
5491 any sense because it will be randomly matched. See section 7 for a complete
5492 list of possible patterns and transformation rules.
5493
5494 The table has to be declared using the "stick-table" statement. It must be of
5495 a type compatible with the pattern. By default it is the one which is present
5496 in the same backend. It is possible to share a table with other backends by
5497 referencing it using the "table" keyword. If another table is referenced,
5498 the server's ID inside the backends are used. By default, all server IDs
5499 start at 1 in each backend, so the server ordering is enough. But in case of
5500 doubt, it is highly recommended to force server IDs using their "id" setting.
5501
5502 It is possible to restrict the conditions where a "stick store-request"
5503 statement will apply, using "if" or "unless" followed by a condition. This
5504 condition will be evaluated while parsing the request, so any criteria can be
5505 used. See section 7 for ACL based conditions.
5506
5507 There is no limit on the number of "stick store-request" statements, but
5508 there is a limit of 8 simultaneous stores per request or response. This
5509 makes it possible to store up to 8 criteria, all extracted from either the
5510 request or the response, regardless of the number of rules. Only the 8 first
5511 ones which match will be kept. Using this, it is possible to feed multiple
5512 tables at once in the hope to increase the chance to recognize a user on
5513 another protocol or access method.
5514
5515 The "store-request" rules are evaluated once the server connection has been
5516 established, so that the table will contain the real server that processed
5517 the request.
5518
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005519 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5520 unless you know what you do : memory is not shared between the
5521 processes, which can result in random behaviours.
5522
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005523 Example :
5524 # forward SMTP users to the same server they just used for POP in the
5525 # last 30 minutes
5526 backend pop
5527 mode tcp
5528 balance roundrobin
5529 stick store-request src
5530 stick-table type ip size 200k expire 30m
5531 server s1 192.168.1.1:110
5532 server s2 192.168.1.1:110
5533
5534 backend smtp
5535 mode tcp
5536 balance roundrobin
5537 stick match src table pop
5538 server s1 192.168.1.1:25
5539 server s2 192.168.1.1:25
5540
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005541 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5542 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005543
5544
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005545stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02005546 size <size> [expire <expire>] [nopurge] [peers <peersect>]
5547 [store <data_type>]*
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005548 Configure the stickiness table for the current backend
5549 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005550 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005551
5552 Arguments :
5553 ip a table declared with "type ip" will only store IPv4 addresses.
5554 This form is very compact (about 50 bytes per entry) and allows
5555 very fast entry lookup and stores with almost no overhead. This
5556 is mainly used to store client source IP addresses.
5557
David du Colombier9a6d3c92011-03-17 10:40:24 +01005558 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
5559 This form is very compact (about 60 bytes per entry) and allows
5560 very fast entry lookup and stores with almost no overhead. This
5561 is mainly used to store client source IP addresses.
5562
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005563 integer a table declared with "type integer" will store 32bit integers
5564 which can represent a client identifier found in a request for
5565 instance.
5566
5567 string a table declared with "type string" will store substrings of up
5568 to <len> characters. If the string provided by the pattern
5569 extractor is larger than <len>, it will be truncated before
5570 being stored. During matching, at most <len> characters will be
5571 compared between the string in the table and the extracted
5572 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005573 to 32 characters.
5574
5575 binary a table declared with "type binary" will store binary blocks
5576 of <len> bytes. If the block provided by the pattern
5577 extractor is larger than <len>, it will be truncated before
5578 being stored. If the block provided by the pattern extractor
5579 is shorter than <len>, it will be padded by 0. When not
5580 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005581
5582 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005583 "string" type table (See type "string" above). Or the number
5584 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005585 changing this parameter as memory usage will proportionally
5586 increase.
5587
5588 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01005589 value directly impacts memory usage. Count approximately
5590 50 bytes per entry, plus the size of a string if any. The size
5591 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005592
5593 [nopurge] indicates that we refuse to purge older entries when the table
5594 is full. When not specified and the table is full when haproxy
5595 wants to store an entry in it, it will flush a few of the oldest
5596 entries in order to release some space for the new ones. This is
5597 most often the desired behaviour. In some specific cases, it
5598 be desirable to refuse new entries instead of purging the older
5599 ones. That may be the case when the amount of data to store is
5600 far above the hardware limits and we prefer not to offer access
5601 to new clients than to reject the ones already connected. When
5602 using this parameter, be sure to properly set the "expire"
5603 parameter (see below).
5604
Emeric Brunf099e792010-09-27 12:05:28 +02005605 <peersect> is the name of the peers section to use for replication. Entries
5606 which associate keys to server IDs are kept synchronized with
5607 the remote peers declared in this section. All entries are also
5608 automatically learned from the local peer (old process) during a
5609 soft restart.
5610
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005611 NOTE : peers can't be used in multi-process mode.
5612
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005613 <expire> defines the maximum duration of an entry in the table since it
5614 was last created, refreshed or matched. The expiration delay is
5615 defined using the standard time format, similarly as the various
5616 timeouts. The maximum duration is slightly above 24 days. See
5617 section 2.2 for more information. If this delay is not specified,
5618 the session won't automatically expire, but older entries will
5619 be removed once full. Be sure not to use the "nopurge" parameter
5620 if not expiration delay is specified.
5621
Willy Tarreau08d5f982010-06-06 13:34:54 +02005622 <data_type> is used to store additional information in the stick-table. This
5623 may be used by ACLs in order to control various criteria related
5624 to the activity of the client matching the stick-table. For each
5625 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02005626 that the additional data can fit. Several data types may be
5627 stored with an entry. Multiple data types may be specified after
5628 the "store" keyword, as a comma-separated list. Alternatively,
5629 it is possible to repeat the "store" keyword followed by one or
5630 several data types. Except for the "server_id" type which is
5631 automatically detected and enabled, all data types must be
5632 explicitly declared to be stored. If an ACL references a data
5633 type which is not stored, the ACL will simply not match. Some
5634 data types require an argument which must be passed just after
5635 the type between parenthesis. See below for the supported data
5636 types and their arguments.
5637
5638 The data types that can be stored with an entry are the following :
5639 - server_id : this is an integer which holds the numeric ID of the server a
5640 request was assigned to. It is used by the "stick match", "stick store",
5641 and "stick on" rules. It is automatically enabled when referenced.
5642
5643 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
5644 integer which may be used for anything. Most of the time it will be used
5645 to put a special tag on some entries, for instance to note that a
5646 specific behaviour was detected and must be known for future matches.
5647
5648 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
5649 the absolute number of connections received from clients which matched
5650 this entry. It does not mean the connections were accepted, just that
5651 they were received.
5652
5653 - conn_cur : Current Connections. It is a positive 32-bit integer which
5654 stores the concurrent connection counts for the entry. It is incremented
5655 once an incoming connection matches the entry, and decremented once the
5656 connection leaves. That way it is possible to know at any time the exact
5657 number of concurrent connections for an entry.
5658
5659 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5660 integer parameter <period> which indicates in milliseconds the length
5661 of the period over which the average is measured. It reports the average
5662 incoming connection rate over that period, in connections per period. The
5663 result is an integer which can be matched using ACLs.
5664
5665 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
5666 the absolute number of sessions received from clients which matched this
5667 entry. A session is a connection that was accepted by the layer 4 rules.
5668
5669 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5670 integer parameter <period> which indicates in milliseconds the length
5671 of the period over which the average is measured. It reports the average
5672 incoming session rate over that period, in sessions per period. The
5673 result is an integer which can be matched using ACLs.
5674
5675 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
5676 counts the absolute number of HTTP requests received from clients which
5677 matched this entry. It does not matter whether they are valid requests or
5678 not. Note that this is different from sessions when keep-alive is used on
5679 the client side.
5680
5681 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5682 integer parameter <period> which indicates in milliseconds the length
5683 of the period over which the average is measured. It reports the average
5684 HTTP request rate over that period, in requests per period. The result is
5685 an integer which can be matched using ACLs. It does not matter whether
5686 they are valid requests or not. Note that this is different from sessions
5687 when keep-alive is used on the client side.
5688
5689 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
5690 counts the absolute number of HTTP requests errors induced by clients
5691 which matched this entry. Errors are counted on invalid and truncated
5692 requests, as well as on denied or tarpitted requests, and on failed
5693 authentications. If the server responds with 4xx, then the request is
5694 also counted as an error since it's an error triggered by the client
5695 (eg: vulnerability scan).
5696
5697 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5698 integer parameter <period> which indicates in milliseconds the length
5699 of the period over which the average is measured. It reports the average
5700 HTTP request error rate over that period, in requests per period (see
5701 http_err_cnt above for what is accounted as an error). The result is an
5702 integer which can be matched using ACLs.
5703
5704 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
5705 integer which counts the cumulated amount of bytes received from clients
5706 which matched this entry. Headers are included in the count. This may be
5707 used to limit abuse of upload features on photo or video servers.
5708
5709 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5710 integer parameter <period> which indicates in milliseconds the length
5711 of the period over which the average is measured. It reports the average
5712 incoming bytes rate over that period, in bytes per period. It may be used
5713 to detect users which upload too much and too fast. Warning: with large
5714 uploads, it is possible that the amount of uploaded data will be counted
5715 once upon termination, thus causing spikes in the average transfer speed
5716 instead of having a smooth one. This may partially be smoothed with
5717 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
5718 recommended for better fairness.
5719
5720 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
5721 integer which counts the cumulated amount of bytes sent to clients which
5722 matched this entry. Headers are included in the count. This may be used
5723 to limit abuse of bots sucking the whole site.
5724
5725 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
5726 an integer parameter <period> which indicates in milliseconds the length
5727 of the period over which the average is measured. It reports the average
5728 outgoing bytes rate over that period, in bytes per period. It may be used
5729 to detect users which download too much and too fast. Warning: with large
5730 transfers, it is possible that the amount of transferred data will be
5731 counted once upon termination, thus causing spikes in the average
5732 transfer speed instead of having a smooth one. This may partially be
5733 smoothed with "option contstats" though this is not perfect yet. Use of
5734 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02005735
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005736 There is only one stick-table per proxy. At the moment of writing this doc,
5737 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005738 to be required, simply create a dummy backend with a stick-table in it and
5739 reference it.
5740
5741 It is important to understand that stickiness based on learning information
5742 has some limitations, including the fact that all learned associations are
5743 lost upon restart. In general it can be good as a complement but not always
5744 as an exclusive stickiness.
5745
Willy Tarreauc9705a12010-07-27 20:05:50 +02005746 Last, memory requirements may be important when storing many data types.
5747 Indeed, storing all indicators above at once in each entry requires 116 bytes
5748 per entry, or 116 MB for a 1-million entries table. This is definitely not
5749 something that can be ignored.
5750
5751 Example:
5752 # Keep track of counters of up to 1 million IP addresses over 5 minutes
5753 # and store a general purpose counter and the average connection rate
5754 # computed over a sliding window of 30 seconds.
5755 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
5756
5757 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01005758 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005759
5760
Emeric Brun6a1cefa2010-09-24 18:15:17 +02005761stick store-response <pattern> [table <table>] [{if | unless} <condition>]
5762 Define a request pattern used to create an entry in a stickiness table
5763 May be used in sections : defaults | frontend | listen | backend
5764 no | no | yes | yes
5765
5766 Arguments :
5767 <pattern> is a pattern extraction rule as described in section 7.8. It
5768 describes what elements of the response or connection will
5769 be analysed, extracted and stored in the table once a
5770 server is selected.
5771
5772 <table> is an optional stickiness table name. If unspecified, the same
5773 backend's table is used. A stickiness table is declared using
5774 the "stick-table" statement.
5775
5776 <cond> is an optional storage condition. It makes it possible to store
5777 certain criteria only when some conditions are met (or not met).
5778 For instance, it could be used to store the SSL session ID only
5779 when the response is a SSL server hello.
5780
5781 Some protocols or applications require complex stickiness rules and cannot
5782 always simply rely on cookies nor hashing. The "stick store-response"
5783 statement describes a rule to decide what to extract from the response and
5784 when to do it, in order to store it into a stickiness table for further
5785 requests to match it using the "stick match" statement. Obviously the
5786 extracted part must make sense and have a chance to be matched in a further
5787 request. Storing an ID found in a header of a response makes sense.
5788 See section 7 for a complete list of possible patterns and transformation
5789 rules.
5790
5791 The table has to be declared using the "stick-table" statement. It must be of
5792 a type compatible with the pattern. By default it is the one which is present
5793 in the same backend. It is possible to share a table with other backends by
5794 referencing it using the "table" keyword. If another table is referenced,
5795 the server's ID inside the backends are used. By default, all server IDs
5796 start at 1 in each backend, so the server ordering is enough. But in case of
5797 doubt, it is highly recommended to force server IDs using their "id" setting.
5798
5799 It is possible to restrict the conditions where a "stick store-response"
5800 statement will apply, using "if" or "unless" followed by a condition. This
5801 condition will be evaluated while parsing the response, so any criteria can
5802 be used. See section 7 for ACL based conditions.
5803
5804 There is no limit on the number of "stick store-response" statements, but
5805 there is a limit of 8 simultaneous stores per request or response. This
5806 makes it possible to store up to 8 criteria, all extracted from either the
5807 request or the response, regardless of the number of rules. Only the 8 first
5808 ones which match will be kept. Using this, it is possible to feed multiple
5809 tables at once in the hope to increase the chance to recognize a user on
5810 another protocol or access method.
5811
5812 The table will contain the real server that processed the request.
5813
5814 Example :
5815 # Learn SSL session ID from both request and response and create affinity.
5816 backend https
5817 mode tcp
5818 balance roundrobin
5819 # maximum SSL session ID length is 32 bytes.
5820 stick-table type binary len 32 size 30k expire 30m
5821
5822 acl clienthello req_ssl_hello_type 1
5823 acl serverhello rep_ssl_hello_type 2
5824
5825 # use tcp content accepts to detects ssl client and server hello.
5826 tcp-request inspect-delay 5s
5827 tcp-request content accept if clienthello
5828
5829 # no timeout on response inspect delay by default.
5830 tcp-response content accept if serverhello
5831
5832 # SSL session ID (SSLID) may be present on a client or server hello.
5833 # Its length is coded on 1 byte at offset 43 and its value starts
5834 # at offset 44.
5835
5836 # Match and learn on request if client hello.
5837 stick on payload_lv(43,1) if clienthello
5838
5839 # Learn on response if server hello.
5840 stick store-response payload_lv(43,1) if serverhello
5841
5842 server s1 192.168.1.1:443
5843 server s2 192.168.1.1:443
5844
5845 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
5846 extraction.
5847
5848
Willy Tarreaue9656522010-08-17 15:40:09 +02005849tcp-request connection <action> [{if | unless} <condition>]
5850 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02005851 May be used in sections : defaults | frontend | listen | backend
5852 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02005853 Arguments :
5854 <action> defines the action to perform if the condition applies. Valid
5855 actions include : "accept", "reject", "track-sc1", "track-sc2".
5856 See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02005857
Willy Tarreaue9656522010-08-17 15:40:09 +02005858 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005859
5860 Immediately after acceptance of a new incoming connection, it is possible to
5861 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02005862 or dropped or have its counters tracked. Those conditions cannot make use of
5863 any data contents because the connection has not been read from yet, and the
5864 buffers are not yet allocated. This is used to selectively and very quickly
5865 accept or drop connections from various sources with a very low overhead. If
5866 some contents need to be inspected in order to take the decision, the
5867 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005868
Willy Tarreaue9656522010-08-17 15:40:09 +02005869 The "tcp-request connection" rules are evaluated in their exact declaration
5870 order. If no rule matches or if there is no rule, the default action is to
5871 accept the incoming connection. There is no specific limit to the number of
5872 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005873
Willy Tarreaue9656522010-08-17 15:40:09 +02005874 Three types of actions are supported :
5875 - accept :
5876 accepts the connection if the condition is true (when used with "if")
5877 or false (when used with "unless"). The first such rule executed ends
5878 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005879
Willy Tarreaue9656522010-08-17 15:40:09 +02005880 - reject :
5881 rejects the connection if the condition is true (when used with "if")
5882 or false (when used with "unless"). The first such rule executed ends
5883 the rules evaluation. Rejected connections do not even become a
5884 session, which is why they are accounted separately for in the stats,
5885 as "denied connections". They are not considered for the session
5886 rate-limit and are not logged either. The reason is that these rules
5887 should only be used to filter extremely high connection rates such as
5888 the ones encountered during a massive DDoS attack. Under these extreme
5889 conditions, the simple action of logging each event would make the
5890 system collapse and would considerably lower the filtering capacity. If
5891 logging is absolutely desired, then "tcp-request content" rules should
5892 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005893
Willy Tarreaue9656522010-08-17 15:40:09 +02005894 - { track-sc1 | track-sc2 } <key> [table <table>] :
5895 enables tracking of sticky counters from current connection. These
5896 rules do not stop evaluation and do not change default action. Two sets
5897 of counters may be simultaneously tracked by the same connection. The
5898 first "track-sc1" rule executed enables tracking of the counters of the
5899 specified table as the first set. The first "track-sc2" rule executed
5900 enables tracking of the counters of the specified table as the second
5901 set. It is a recommended practice to use the first set of counters for
5902 the per-frontend counters and the second set for the per-backend ones.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005903
Willy Tarreaue9656522010-08-17 15:40:09 +02005904 These actions take one or two arguments :
5905 <key> is mandatory, and defines the criterion the tracking key will
5906 be derived from. At the moment, only "src" is supported. With
5907 it, the key will be the connection's source IPv4 address.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005908
Willy Tarreaue9656522010-08-17 15:40:09 +02005909 <table> is an optional table to be used instead of the default one,
5910 which is the stick-table declared in the current proxy. All
5911 the counters for the matches and updates for the key will
5912 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005913
Willy Tarreaue9656522010-08-17 15:40:09 +02005914 Once a "track-sc*" rule is executed, the key is looked up in the table
5915 and if it is not found, an entry is allocated for it. Then a pointer to
5916 that entry is kept during all the session's life, and this entry's
5917 counters are updated as often as possible, every time the session's
5918 counters are updated, and also systematically when the session ends.
5919 If the entry tracks concurrent connection counters, one connection is
5920 counted for as long as the entry is tracked, and the entry will not
5921 expire during that time. Tracking counters also provides a performance
5922 advantage over just checking the keys, because only one table lookup is
5923 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005924
Willy Tarreaue9656522010-08-17 15:40:09 +02005925 Note that the "if/unless" condition is optional. If no condition is set on
5926 the action, it is simply performed unconditionally. That can be useful for
5927 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005928
Willy Tarreaue9656522010-08-17 15:40:09 +02005929 Example: accept all connections from white-listed hosts, reject too fast
5930 connection without counting them, and track accepted connections.
5931 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005932
Willy Tarreaue9656522010-08-17 15:40:09 +02005933 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005934 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaue9656522010-08-17 15:40:09 +02005935 tcp-request connection track-sc1 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005936
Willy Tarreaue9656522010-08-17 15:40:09 +02005937 Example: accept all connections from white-listed hosts, count all other
5938 connections and reject too fast ones. This results in abusive ones
5939 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005940
Willy Tarreaue9656522010-08-17 15:40:09 +02005941 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
5942 tcp-request connection track-sc1 src
5943 tcp-request connection reject if { sc1_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005944
5945 See section 7 about ACL usage.
5946
Willy Tarreaue9656522010-08-17 15:40:09 +02005947 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005948
5949
Willy Tarreaue9656522010-08-17 15:40:09 +02005950tcp-request content <action> [{if | unless} <condition>]
5951 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02005952 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02005953 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02005954 Arguments :
5955 <action> defines the action to perform if the condition applies. Valid
5956 actions include : "accept", "reject", "track-sc1", "track-sc2".
5957 See "tcp-request connection" above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02005958
Willy Tarreaue9656522010-08-17 15:40:09 +02005959 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02005960
Willy Tarreaue9656522010-08-17 15:40:09 +02005961 A request's contents can be analysed at an early stage of request processing
5962 called "TCP content inspection". During this stage, ACL-based rules are
5963 evaluated every time the request contents are updated, until either an
5964 "accept" or a "reject" rule matches, or the TCP request inspection delay
5965 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02005966
Willy Tarreaue9656522010-08-17 15:40:09 +02005967 The first difference between these rules and "tcp-request connection" rules
5968 is that "tcp-request content" rules can make use of contents to take a
5969 decision. Most often, these decisions will consider a protocol recognition or
5970 validity. The second difference is that content-based rules can be used in
5971 both frontends and backends. In frontends, they will be evaluated upon new
5972 connections. In backends, they will be evaluated once a session is assigned
5973 a backend. This means that a single frontend connection may be evaluated
5974 several times by one or multiple backends when a session gets reassigned
5975 (for instance after a client-side HTTP keep-alive request).
Willy Tarreau62644772008-07-16 18:36:06 +02005976
Willy Tarreaue9656522010-08-17 15:40:09 +02005977 Content-based rules are evaluated in their exact declaration order. If no
5978 rule matches or if there is no rule, the default action is to accept the
5979 contents. There is no specific limit to the number of rules which may be
5980 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02005981
Willy Tarreaue9656522010-08-17 15:40:09 +02005982 Three types of actions are supported :
5983 - accept :
5984 - reject :
5985 - { track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02005986
Willy Tarreaue9656522010-08-17 15:40:09 +02005987 They have the same meaning as their counter-parts in "tcp-request connection"
5988 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02005989
Willy Tarreaue9656522010-08-17 15:40:09 +02005990 Also, it is worth noting that if sticky counters are tracked from a rule
5991 defined in a backend, this tracking will automatically end when the session
5992 releases the backend. That allows per-backend counter tracking even in case
5993 of HTTP keep-alive requests when the backend changes. While there is nothing
5994 mandatory about it, it is recommended to use the track-sc1 pointer to track
5995 per-frontend counters and track-sc2 to track per-backend counters.
Willy Tarreau62644772008-07-16 18:36:06 +02005996
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005997 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02005998 the action, it is simply performed unconditionally. That can be useful for
5999 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02006000
Willy Tarreaue9656522010-08-17 15:40:09 +02006001 It is perfectly possible to match layer 7 contents with "tcp-request content"
6002 rules, but then it is important to ensure that a full request has been
6003 buffered, otherwise no contents will match. In order to achieve this, the
6004 best solution involves detecting the HTTP protocol during the inspection
6005 period.
Willy Tarreau62644772008-07-16 18:36:06 +02006006
6007 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02006008 # Accept HTTP requests containing a Host header saying "example.com"
6009 # and reject everything else.
6010 acl is_host_com hdr(Host) -i example.com
6011 tcp-request inspect-delay 30s
6012 tcp-request content accept if HTTP is_host_com
6013 tcp-request content reject
6014
6015 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02006016 # reject SMTP connection if client speaks first
6017 tcp-request inspect-delay 30s
6018 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006019 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02006020
6021 # Forward HTTPS connection only if client speaks
6022 tcp-request inspect-delay 30s
6023 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006024 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02006025 tcp-request content reject
6026
6027 Example: track per-frontend and per-backend counters, block abusers at the
6028 frontend when the backend detects abuse.
6029
6030 frontend http
6031 # Use General Purpose Couter 0 in SC1 as a global abuse counter
6032 # protecting all our sites
6033 stick-table type ip size 1m expire 5m store gpc0
6034 tcp-request connection track-sc1 src
6035 tcp-request connection reject if { sc1_get_gpc0 gt 0 }
6036 ...
6037 use_backend http_dynamic if { path_end .php }
6038
6039 backend http_dynamic
6040 # if a source makes too fast requests to this dynamic site (tracked
6041 # by SC2), block it globally in the frontend.
6042 stick-table type ip size 1m expire 5m store http_req_rate(10s)
6043 acl click_too_fast sc2_http_req_rate gt 10
6044 acl mark_as_abuser sc1_inc_gpc0
6045 tcp-request content track-sc2 src
6046 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02006047
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006048 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02006049
Willy Tarreaue9656522010-08-17 15:40:09 +02006050 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02006051
6052
6053tcp-request inspect-delay <timeout>
6054 Set the maximum allowed time to wait for data during content inspection
6055 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006056 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02006057 Arguments :
6058 <timeout> is the timeout value specified in milliseconds by default, but
6059 can be in any other unit if the number is suffixed by the unit,
6060 as explained at the top of this document.
6061
6062 People using haproxy primarily as a TCP relay are often worried about the
6063 risk of passing any type of protocol to a server without any analysis. In
6064 order to be able to analyze the request contents, we must first withhold
6065 the data then analyze them. This statement simply enables withholding of
6066 data for at most the specified amount of time.
6067
Willy Tarreaufb356202010-08-03 14:02:05 +02006068 TCP content inspection applies very early when a connection reaches a
6069 frontend, then very early when the connection is forwarded to a backend. This
6070 means that a connection may experience a first delay in the frontend and a
6071 second delay in the backend if both have tcp-request rules.
6072
Willy Tarreau62644772008-07-16 18:36:06 +02006073 Note that when performing content inspection, haproxy will evaluate the whole
6074 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006075 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02006076 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01006077 contents are definitive. If no delay is set, haproxy will not wait at all
6078 and will immediately apply a verdict based on the available information.
6079 Obviously this is unlikely to be very useful and might even be racy, so such
6080 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02006081
6082 As soon as a rule matches, the request is released and continues as usual. If
6083 the timeout is reached and no rule matches, the default policy will be to let
6084 it pass through unaffected.
6085
6086 For most protocols, it is enough to set it to a few seconds, as most clients
6087 send the full request immediately upon connection. Add 3 or more seconds to
6088 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01006089 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02006090 before the server (eg: SMTP), or to wait for a client to talk before passing
6091 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02006092 least the inspection delay, otherwise it will expire first. If the client
6093 closes the connection or if the buffer is full, the delay immediately expires
6094 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02006095
Willy Tarreau55165fe2009-05-10 12:02:55 +02006096 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02006097 "timeout client".
6098
6099
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006100tcp-response content <action> [{if | unless} <condition>]
6101 Perform an action on a session response depending on a layer 4-7 condition
6102 May be used in sections : defaults | frontend | listen | backend
6103 no | no | yes | yes
6104 Arguments :
6105 <action> defines the action to perform if the condition applies. Valid
6106 actions include : "accept", "reject".
6107 See "tcp-request connection" above for their signification.
6108
6109 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
6110
6111 Response contents can be analysed at an early stage of response processing
6112 called "TCP content inspection". During this stage, ACL-based rules are
6113 evaluated every time the response contents are updated, until either an
6114 "accept" or a "reject" rule matches, or a TCP response inspection delay is
6115 set and expires with no matching rule.
6116
6117 Most often, these decisions will consider a protocol recognition or validity.
6118
6119 Content-based rules are evaluated in their exact declaration order. If no
6120 rule matches or if there is no rule, the default action is to accept the
6121 contents. There is no specific limit to the number of rules which may be
6122 inserted.
6123
6124 Two types of actions are supported :
6125 - accept :
6126 accepts the response if the condition is true (when used with "if")
6127 or false (when used with "unless"). The first such rule executed ends
6128 the rules evaluation.
6129
6130 - reject :
6131 rejects the response if the condition is true (when used with "if")
6132 or false (when used with "unless"). The first such rule executed ends
6133 the rules evaluation. Rejected session are immediatly closed.
6134
6135 Note that the "if/unless" condition is optional. If no condition is set on
6136 the action, it is simply performed unconditionally. That can be useful for
6137 for changing the default action to a reject.
6138
6139 It is perfectly possible to match layer 7 contents with "tcp-reponse content"
6140 rules, but then it is important to ensure that a full response has been
6141 buffered, otherwise no contents will match. In order to achieve this, the
6142 best solution involves detecting the HTTP protocol during the inspection
6143 period.
6144
6145 See section 7 about ACL usage.
6146
6147 See also : "tcp-request content", "tcp-response inspect-delay"
6148
6149
6150tcp-response inspect-delay <timeout>
6151 Set the maximum allowed time to wait for a response during content inspection
6152 May be used in sections : defaults | frontend | listen | backend
6153 no | no | yes | yes
6154 Arguments :
6155 <timeout> is the timeout value specified in milliseconds by default, but
6156 can be in any other unit if the number is suffixed by the unit,
6157 as explained at the top of this document.
6158
6159 See also : "tcp-response content", "tcp-request inspect-delay".
6160
6161
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006162timeout check <timeout>
6163 Set additional check timeout, but only after a connection has been already
6164 established.
6165
6166 May be used in sections: defaults | frontend | listen | backend
6167 yes | no | yes | yes
6168 Arguments:
6169 <timeout> is the timeout value specified in milliseconds by default, but
6170 can be in any other unit if the number is suffixed by the unit,
6171 as explained at the top of this document.
6172
6173 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
6174 for check and "timeout check" as an additional read timeout. The "min" is
6175 used so that people running with *very* long "timeout connect" (eg. those
6176 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01006177 (Please also note that there is no valid reason to have such long connect
6178 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
6179 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006180
6181 If "timeout check" is not set haproxy uses "inter" for complete check
6182 timeout (connect + read) exactly like all <1.3.15 version.
6183
6184 In most cases check request is much simpler and faster to handle than normal
6185 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01006186 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006187
6188 This parameter is specific to backends, but can be specified once for all in
6189 "defaults" sections. This is in fact one of the easiest solutions not to
6190 forget about it.
6191
Willy Tarreau41a340d2008-01-22 12:25:31 +01006192 See also: "timeout connect", "timeout queue", "timeout server",
6193 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006194
6195
Willy Tarreau0ba27502007-12-24 16:55:16 +01006196timeout client <timeout>
6197timeout clitimeout <timeout> (deprecated)
6198 Set the maximum inactivity time on the client side.
6199 May be used in sections : defaults | frontend | listen | backend
6200 yes | yes | yes | no
6201 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006202 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006203 can be in any other unit if the number is suffixed by the unit,
6204 as explained at the top of this document.
6205
6206 The inactivity timeout applies when the client is expected to acknowledge or
6207 send data. In HTTP mode, this timeout is particularly important to consider
6208 during the first phase, when the client sends the request, and during the
6209 response while it is reading data sent by the server. The value is specified
6210 in milliseconds by default, but can be in any other unit if the number is
6211 suffixed by the unit, as specified at the top of this document. In TCP mode
6212 (and to a lesser extent, in HTTP mode), it is highly recommended that the
6213 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006214 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01006215 losses by specifying timeouts that are slightly above multiples of 3 seconds
6216 (eg: 4 or 5 seconds).
6217
6218 This parameter is specific to frontends, but can be specified once for all in
6219 "defaults" sections. This is in fact one of the easiest solutions not to
6220 forget about it. An unspecified timeout results in an infinite timeout, which
6221 is not recommended. Such a usage is accepted and works but reports a warning
6222 during startup because it may results in accumulation of expired sessions in
6223 the system if the system's timeouts are not configured either.
6224
6225 This parameter replaces the old, deprecated "clitimeout". It is recommended
6226 to use it to write new configurations. The form "timeout clitimeout" is
6227 provided only by backwards compatibility but its use is strongly discouraged.
6228
6229 See also : "clitimeout", "timeout server".
6230
6231
6232timeout connect <timeout>
6233timeout contimeout <timeout> (deprecated)
6234 Set the maximum time to wait for a connection attempt to a server to succeed.
6235 May be used in sections : defaults | frontend | listen | backend
6236 yes | no | yes | yes
6237 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006238 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006239 can be in any other unit if the number is suffixed by the unit,
6240 as explained at the top of this document.
6241
6242 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006243 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01006244 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01006245 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006246 connect timeout also presets both queue and tarpit timeouts to the same value
6247 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006248
6249 This parameter is specific to backends, but can be specified once for all in
6250 "defaults" sections. This is in fact one of the easiest solutions not to
6251 forget about it. An unspecified timeout results in an infinite timeout, which
6252 is not recommended. Such a usage is accepted and works but reports a warning
6253 during startup because it may results in accumulation of failed sessions in
6254 the system if the system's timeouts are not configured either.
6255
6256 This parameter replaces the old, deprecated "contimeout". It is recommended
6257 to use it to write new configurations. The form "timeout contimeout" is
6258 provided only by backwards compatibility but its use is strongly discouraged.
6259
Willy Tarreau41a340d2008-01-22 12:25:31 +01006260 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
6261 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006262
6263
Willy Tarreaub16a5742010-01-10 14:46:16 +01006264timeout http-keep-alive <timeout>
6265 Set the maximum allowed time to wait for a new HTTP request to appear
6266 May be used in sections : defaults | frontend | listen | backend
6267 yes | yes | yes | yes
6268 Arguments :
6269 <timeout> is the timeout value specified in milliseconds by default, but
6270 can be in any other unit if the number is suffixed by the unit,
6271 as explained at the top of this document.
6272
6273 By default, the time to wait for a new request in case of keep-alive is set
6274 by "timeout http-request". However this is not always convenient because some
6275 people want very short keep-alive timeouts in order to release connections
6276 faster, and others prefer to have larger ones but still have short timeouts
6277 once the request has started to present itself.
6278
6279 The "http-keep-alive" timeout covers these needs. It will define how long to
6280 wait for a new HTTP request to start coming after a response was sent. Once
6281 the first byte of request has been seen, the "http-request" timeout is used
6282 to wait for the complete request to come. Note that empty lines prior to a
6283 new request do not refresh the timeout and are not counted as a new request.
6284
6285 There is also another difference between the two timeouts : when a connection
6286 expires during timeout http-keep-alive, no error is returned, the connection
6287 just closes. If the connection expires in "http-request" while waiting for a
6288 connection to complete, a HTTP 408 error is returned.
6289
6290 In general it is optimal to set this value to a few tens to hundreds of
6291 milliseconds, to allow users to fetch all objects of a page at once but
6292 without waiting for further clicks. Also, if set to a very small value (eg:
6293 1 millisecond) it will probably only accept pipelined requests but not the
6294 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02006295 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01006296
6297 If this parameter is not set, the "http-request" timeout applies, and if both
6298 are not set, "timeout client" still applies at the lower level. It should be
6299 set in the frontend to take effect, unless the frontend is in TCP mode, in
6300 which case the HTTP backend's timeout will be used.
6301
6302 See also : "timeout http-request", "timeout client".
6303
6304
Willy Tarreau036fae02008-01-06 13:24:40 +01006305timeout http-request <timeout>
6306 Set the maximum allowed time to wait for a complete HTTP request
6307 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006308 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01006309 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006310 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01006311 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 In order to offer DoS protection, it may be required to lower the maximum
6315 accepted time to receive a complete HTTP request without affecting the client
6316 timeout. This helps protecting against established connections on which
6317 nothing is sent. The client timeout cannot offer a good protection against
6318 this abuse because it is an inactivity timeout, which means that if the
6319 attacker sends one character every now and then, the timeout will not
6320 trigger. With the HTTP request timeout, no matter what speed the client
6321 types, the request will be aborted if it does not complete in time.
6322
6323 Note that this timeout only applies to the header part of the request, and
6324 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01006325 used anymore. It is used again on keep-alive connections to wait for a second
6326 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01006327
6328 Generally it is enough to set it to a few seconds, as most clients send the
6329 full request immediately upon connection. Add 3 or more seconds to cover TCP
6330 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
6331 generally work on local networks as long as there are no packet losses. This
6332 will prevent people from sending bare HTTP requests using telnet.
6333
6334 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006335 chunk of the incoming request. It should be set in the frontend to take
6336 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
6337 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01006338
Willy Tarreaub16a5742010-01-10 14:46:16 +01006339 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01006340
Willy Tarreau844e3c52008-01-11 16:28:18 +01006341
6342timeout queue <timeout>
6343 Set the maximum time to wait in the queue for a connection slot to be free
6344 May be used in sections : defaults | frontend | listen | backend
6345 yes | no | yes | yes
6346 Arguments :
6347 <timeout> is the timeout value specified in milliseconds by default, but
6348 can be in any other unit if the number is suffixed by the unit,
6349 as explained at the top of this document.
6350
6351 When a server's maxconn is reached, connections are left pending in a queue
6352 which may be server-specific or global to the backend. In order not to wait
6353 indefinitely, a timeout is applied to requests pending in the queue. If the
6354 timeout is reached, it is considered that the request will almost never be
6355 served, so it is dropped and a 503 error is returned to the client.
6356
6357 The "timeout queue" statement allows to fix the maximum time for a request to
6358 be left pending in a queue. If unspecified, the same value as the backend's
6359 connection timeout ("timeout connect") is used, for backwards compatibility
6360 with older versions with no "timeout queue" parameter.
6361
6362 See also : "timeout connect", "contimeout".
6363
6364
6365timeout server <timeout>
6366timeout srvtimeout <timeout> (deprecated)
6367 Set the maximum inactivity time on the server side.
6368 May be used in sections : defaults | frontend | listen | backend
6369 yes | no | yes | yes
6370 Arguments :
6371 <timeout> is the timeout value specified in milliseconds by default, but
6372 can be in any other unit if the number is suffixed by the unit,
6373 as explained at the top of this document.
6374
6375 The inactivity timeout applies when the server is expected to acknowledge or
6376 send data. In HTTP mode, this timeout is particularly important to consider
6377 during the first phase of the server's response, when it has to send the
6378 headers, as it directly represents the server's processing time for the
6379 request. To find out what value to put there, it's often good to start with
6380 what would be considered as unacceptable response times, then check the logs
6381 to observe the response time distribution, and adjust the value accordingly.
6382
6383 The value is specified in milliseconds by default, but can be in any other
6384 unit if the number is suffixed by the unit, as specified at the top of this
6385 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
6386 recommended that the client timeout remains equal to the server timeout in
6387 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006388 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01006389 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01006390 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01006391
6392 This parameter is specific to backends, but can be specified once for all in
6393 "defaults" sections. This is in fact one of the easiest solutions not to
6394 forget about it. An unspecified timeout results in an infinite timeout, which
6395 is not recommended. Such a usage is accepted and works but reports a warning
6396 during startup because it may results in accumulation of expired sessions in
6397 the system if the system's timeouts are not configured either.
6398
6399 This parameter replaces the old, deprecated "srvtimeout". It is recommended
6400 to use it to write new configurations. The form "timeout srvtimeout" is
6401 provided only by backwards compatibility but its use is strongly discouraged.
6402
6403 See also : "srvtimeout", "timeout client".
6404
6405
6406timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01006407 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01006408 May be used in sections : defaults | frontend | listen | backend
6409 yes | yes | yes | yes
6410 Arguments :
6411 <timeout> is the tarpit duration specified in milliseconds by default, but
6412 can be in any other unit if the number is suffixed by the unit,
6413 as explained at the top of this document.
6414
6415 When a connection is tarpitted using "reqtarpit", it is maintained open with
6416 no activity for a certain amount of time, then closed. "timeout tarpit"
6417 defines how long it will be maintained open.
6418
6419 The value is specified in milliseconds by default, but can be in any other
6420 unit if the number is suffixed by the unit, as specified at the top of this
6421 document. If unspecified, the same value as the backend's connection timeout
6422 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01006423 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006424
6425 See also : "timeout connect", "contimeout".
6426
6427
6428transparent (deprecated)
6429 Enable client-side transparent proxying
6430 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006431 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006432 Arguments : none
6433
6434 This keyword was introduced in order to provide layer 7 persistence to layer
6435 3 load balancers. The idea is to use the OS's ability to redirect an incoming
6436 connection for a remote address to a local process (here HAProxy), and let
6437 this process know what address was initially requested. When this option is
6438 used, sessions without cookies will be forwarded to the original destination
6439 IP address of the incoming request (which should match that of another
6440 equipment), while requests with cookies will still be forwarded to the
6441 appropriate server.
6442
6443 The "transparent" keyword is deprecated, use "option transparent" instead.
6444
6445 Note that contrary to a common belief, this option does NOT make HAProxy
6446 present the client's IP to the server when establishing the connection.
6447
Willy Tarreau844e3c52008-01-11 16:28:18 +01006448 See also: "option transparent"
6449
6450
6451use_backend <backend> if <condition>
6452use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006453 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006454 May be used in sections : defaults | frontend | listen | backend
6455 no | yes | yes | no
6456 Arguments :
6457 <backend> is the name of a valid backend or "listen" section.
6458
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006459 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006460
6461 When doing content-switching, connections arrive on a frontend and are then
6462 dispatched to various backends depending on a number of conditions. The
6463 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006464 "use_backend" keyword. While it is normally used with HTTP processing, it can
6465 also be used in pure TCP, either without content using stateless ACLs (eg:
6466 source address validation) or combined with a "tcp-request" rule to wait for
6467 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006468
6469 There may be as many "use_backend" rules as desired. All of these rules are
6470 evaluated in their declaration order, and the first one which matches will
6471 assign the backend.
6472
6473 In the first form, the backend will be used if the condition is met. In the
6474 second form, the backend will be used if the condition is not met. If no
6475 condition is valid, the backend defined with "default_backend" will be used.
6476 If no default backend is defined, either the servers in the same section are
6477 used (in case of a "listen" section) or, in case of a frontend, no server is
6478 used and a 503 service unavailable response is returned.
6479
Willy Tarreau51aecc72009-07-12 09:47:04 +02006480 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006481 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02006482 and backend processing will immediately follow, or the backend will wait for
6483 a complete HTTP request to get in. This feature is useful when a frontend
6484 must decode several protocols on a unique port, one of them being HTTP.
6485
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006486 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006487
Willy Tarreau036fae02008-01-06 13:24:40 +01006488
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010064895. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01006490------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006491
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01006492The "server" and "default-server" keywords support a certain number of settings
6493which are all passed as arguments on the server line. The order in which those
6494arguments appear does not count, and they are all optional. Some of those
6495settings are single words (booleans) while others expect one or several values
6496after them. In this case, the values must immediately follow the setting name.
6497Except default-server, all those settings must be specified after the server's
6498address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02006499
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006500 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01006501 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02006502
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006503The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006504
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006505addr <ipv4>
6506 Using the "addr" parameter, it becomes possible to use a different IP address
6507 to send health-checks. On some servers, it may be desirable to dedicate an IP
6508 address to specific component able to perform complex tests which are more
6509 suitable to health-checks than the application. This parameter is ignored if
6510 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006511
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006512 Supported in default-server: No
6513
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006514backup
6515 When "backup" is present on a server line, the server is only used in load
6516 balancing when all other non-backup servers are unavailable. Requests coming
6517 with a persistence cookie referencing the server will always be served
6518 though. By default, only the first operational backup server is used, unless
6519 the "allbackups" option is set in the backend. See also the "allbackups"
6520 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006521
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006522 Supported in default-server: No
6523
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006524check
6525 This option enables health checks on the server. By default, a server is
6526 always considered available. If "check" is set, the server will receive
6527 periodic health checks to ensure that it is really able to serve requests.
6528 The default address and port to send the tests to are those of the server,
6529 and the default source is the same as the one defined in the backend. It is
6530 possible to change the address using the "addr" parameter, the port using the
6531 "port" parameter, the source address using the "source" address, and the
6532 interval and timers using the "inter", "rise" and "fall" parameters. The
6533 request method is define in the backend using the "httpchk", "smtpchk",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01006534 "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please refer to
6535 those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006536
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006537 Supported in default-server: No
6538
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006539cookie <value>
6540 The "cookie" parameter sets the cookie value assigned to the server to
6541 <value>. This value will be checked in incoming requests, and the first
6542 operational server possessing the same value will be selected. In return, in
6543 cookie insertion or rewrite modes, this value will be assigned to the cookie
6544 sent to the client. There is nothing wrong in having several servers sharing
6545 the same cookie value, and it is in fact somewhat common between normal and
6546 backup servers. See also the "cookie" keyword in backend section.
6547
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006548 Supported in default-server: No
6549
Willy Tarreau96839092010-03-29 10:02:24 +02006550disabled
6551 The "disabled" keyword starts the server in the "disabled" state. That means
6552 that it is marked down in maintenance mode, and no connection other than the
6553 ones allowed by persist mode will reach it. It is very well suited to setup
6554 new servers, because normal traffic will never reach them, while it is still
6555 possible to test the service by making use of the force-persist mechanism.
6556
6557 Supported in default-server: No
6558
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006559error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01006560 If health observing is enabled, the "error-limit" parameter specifies the
6561 number of consecutive errors that triggers event selected by the "on-error"
6562 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006563
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006564 Supported in default-server: Yes
6565
6566 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006567
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006568fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006569 The "fall" parameter states that a server will be considered as dead after
6570 <count> consecutive unsuccessful health checks. This value defaults to 3 if
6571 unspecified. See also the "check", "inter" and "rise" parameters.
6572
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006573 Supported in default-server: Yes
6574
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006575id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02006576 Set a persistent ID for the server. This ID must be positive and unique for
6577 the proxy. An unused ID will automatically be assigned if unset. The first
6578 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006579
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006580 Supported in default-server: No
6581
6582inter <delay>
6583fastinter <delay>
6584downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006585 The "inter" parameter sets the interval between two consecutive health checks
6586 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
6587 It is also possible to use "fastinter" and "downinter" to optimize delays
6588 between checks depending on the server state :
6589
6590 Server state | Interval used
6591 ---------------------------------+-----------------------------------------
6592 UP 100% (non-transitional) | "inter"
6593 ---------------------------------+-----------------------------------------
6594 Transitionally UP (going down), |
6595 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
6596 or yet unchecked. |
6597 ---------------------------------+-----------------------------------------
6598 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
6599 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01006600
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006601 Just as with every other time-based parameter, they can be entered in any
6602 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
6603 serves as a timeout for health checks sent to servers if "timeout check" is
6604 not set. In order to reduce "resonance" effects when multiple servers are
6605 hosted on the same hardware, the health-checks of all servers are started
6606 with a small time offset between them. It is also possible to add some random
6607 noise in the health checks interval using the global "spread-checks"
6608 keyword. This makes sense for instance when a lot of backends use the same
6609 servers.
6610
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006611 Supported in default-server: Yes
6612
6613maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006614 The "maxconn" parameter specifies the maximal number of concurrent
6615 connections that will be sent to this server. If the number of incoming
6616 concurrent requests goes higher than this value, they will be queued, waiting
6617 for a connection to be released. This parameter is very important as it can
6618 save fragile servers from going down under extreme loads. If a "minconn"
6619 parameter is specified, the limit becomes dynamic. The default value is "0"
6620 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
6621 the backend's "fullconn" keyword.
6622
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006623 Supported in default-server: Yes
6624
6625maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006626 The "maxqueue" parameter specifies the maximal number of connections which
6627 will wait in the queue for this server. If this limit is reached, next
6628 requests will be redispatched to other servers instead of indefinitely
6629 waiting to be served. This will break persistence but may allow people to
6630 quickly re-log in when the server they try to connect to is dying. The
6631 default value is "0" which means the queue is unlimited. See also the
6632 "maxconn" and "minconn" parameters.
6633
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006634 Supported in default-server: Yes
6635
6636minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006637 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
6638 limit following the backend's load. The server will always accept at least
6639 <minconn> connections, never more than <maxconn>, and the limit will be on
6640 the ramp between both values when the backend has less than <fullconn>
6641 concurrent connections. This makes it possible to limit the load on the
6642 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006643 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006644 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006645
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006646 Supported in default-server: Yes
6647
Simon Hormanfa461682011-06-25 09:39:49 +09006648non-stick
6649 Never add connections allocated to this sever to a stick-table.
6650 This may be used in conjunction with backup to ensure that
6651 stick-table persistence is disabled for backup servers.
6652
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006653observe <mode>
6654 This option enables health adjusting based on observing communication with
6655 the server. By default this functionality is disabled and enabling it also
6656 requires to enable health checks. There are two supported modes: "layer4" and
6657 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
6658 significant. In layer7, which is only allowed for http proxies, responses
6659 received from server are verified, like valid/wrong http code, unparsable
6660 headers, a timeout, etc.
6661
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006662 Supported in default-server: No
6663
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006664 See also the "check", "on-error" and "error-limit".
6665
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006666on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006667 Select what should happen when enough consecutive errors are detected.
6668 Currently, four modes are available:
6669 - fastinter: force fastinter
6670 - fail-check: simulate a failed check, also forces fastinter (default)
6671 - sudden-death: simulate a pre-fatal failed health check, one more failed
6672 check will mark a server down, forces fastinter
6673 - mark-down: mark the server immediately down and force fastinter
6674
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006675 Supported in default-server: Yes
6676
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006677 See also the "check", "observe" and "error-limit".
6678
Simon Hormane0d1bfb2011-06-21 14:34:58 +09006679on-marked-down <action>
6680 Modify what occurs when a server is marked down.
6681 Currently one action is available:
6682 - shutdown-sessions: Shutdown peer sessions
6683
6684 Actions are disabled by default
6685
6686 Supported in default-server: Yes
6687
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006688port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006689 Using the "port" parameter, it becomes possible to use a different port to
6690 send health-checks. On some servers, it may be desirable to dedicate a port
6691 to a specific component able to perform complex tests which are more suitable
6692 to health-checks than the application. It is common to run a simple script in
6693 inetd for instance. This parameter is ignored if the "check" parameter is not
6694 set. See also the "addr" parameter.
6695
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006696 Supported in default-server: Yes
6697
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006698redir <prefix>
6699 The "redir" parameter enables the redirection mode for all GET and HEAD
6700 requests addressing this server. This means that instead of having HAProxy
6701 forward the request to the server, it will send an "HTTP 302" response with
6702 the "Location" header composed of this prefix immediately followed by the
6703 requested URI beginning at the leading '/' of the path component. That means
6704 that no trailing slash should be used after <prefix>. All invalid requests
6705 will be rejected, and all non-GET or HEAD requests will be normally served by
6706 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006707 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006708 requests are still analysed, making this solution completely usable to direct
6709 users to a remote location in case of local disaster. Main use consists in
6710 increasing bandwidth for static servers by having the clients directly
6711 connect to them. Note: never use a relative location here, it would cause a
6712 loop between the client and HAProxy!
6713
6714 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
6715
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006716 Supported in default-server: No
6717
6718rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006719 The "rise" parameter states that a server will be considered as operational
6720 after <count> consecutive successful health checks. This value defaults to 2
6721 if unspecified. See also the "check", "inter" and "fall" parameters.
6722
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006723 Supported in default-server: Yes
6724
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01006725send-proxy
6726 The "send-proxy" parameter enforces use of the PROXY protocol over any
6727 connection established to this server. The PROXY protocol informs the other
6728 end about the layer 3/4 addresses of the incoming connection, so that it can
6729 know the client's address or the public address it accessed to, whatever the
6730 upper layer protocol. For connections accepted by an "accept-proxy" listener,
6731 the advertised address will be used. Only TCPv4 and TCPv6 address families
6732 are supported. Other families such as Unix sockets, will report an UNKNOWN
6733 family. Servers using this option can fully be chained to another instance of
6734 haproxy listening with an "accept-proxy" setting. This setting must not be
6735 used if the server isn't aware of the protocol. See also the "accept-proxy"
6736 option of the "bind" keyword.
6737
6738 Supported in default-server: No
6739
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006740slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006741 The "slowstart" parameter for a server accepts a value in milliseconds which
6742 indicates after how long a server which has just come back up will run at
6743 full speed. Just as with every other time-based parameter, it can be entered
6744 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
6745 linearly from 0 to 100% during this time. The limitation applies to two
6746 parameters :
6747
6748 - maxconn: the number of connections accepted by the server will grow from 1
6749 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
6750
6751 - weight: when the backend uses a dynamic weighted algorithm, the weight
6752 grows linearly from 1 to 100%. In this case, the weight is updated at every
6753 health-check. For this reason, it is important that the "inter" parameter
6754 is smaller than the "slowstart", in order to maximize the number of steps.
6755
6756 The slowstart never applies when haproxy starts, otherwise it would cause
6757 trouble to running servers. It only applies when a server has been previously
6758 seen as failed.
6759
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006760 Supported in default-server: Yes
6761
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006762source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02006763source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006764source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006765 The "source" parameter sets the source address which will be used when
6766 connecting to the server. It follows the exact same parameters and principle
6767 as the backend "source" keyword, except that it only applies to the server
6768 referencing it. Please consult the "source" keyword for details.
6769
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006770 Additionally, the "source" statement on a server line allows one to specify a
6771 source port range by indicating the lower and higher bounds delimited by a
6772 dash ('-'). Some operating systems might require a valid IP address when a
6773 source port range is specified. It is permitted to have the same IP/range for
6774 several servers. Doing so makes it possible to bypass the maximum of 64k
6775 total concurrent connections. The limit will then reach 64k connections per
6776 server.
6777
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006778 Supported in default-server: No
6779
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006780track [<proxy>/]<server>
6781 This option enables ability to set the current state of the server by
6782 tracking another one. Only a server with checks enabled can be tracked
6783 so it is not possible for example to track a server that tracks another
6784 one. If <proxy> is omitted the current one is used. If disable-on-404 is
6785 used, it has to be enabled on both proxies.
6786
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006787 Supported in default-server: No
6788
6789weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006790 The "weight" parameter is used to adjust the server's weight relative to
6791 other servers. All servers will receive a load proportional to their weight
6792 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02006793 load. The default weight is 1, and the maximal value is 256. A value of 0
6794 means the server will not participate in load-balancing but will still accept
6795 persistent connections. If this parameter is used to distribute the load
6796 according to server's capacity, it is recommended to start with values which
6797 can both grow and shrink, for instance between 10 and 100 to leave enough
6798 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006799
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006800 Supported in default-server: Yes
6801
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006802
68036. HTTP header manipulation
6804---------------------------
6805
6806In HTTP mode, it is possible to rewrite, add or delete some of the request and
6807response headers based on regular expressions. It is also possible to block a
6808request or a response if a particular header matches a regular expression,
6809which is enough to stop most elementary protocol attacks, and to protect
6810against information leak from the internal network. But there is a limitation
6811to this : since HAProxy's HTTP engine does not support keep-alive, only headers
6812passed during the first request of a TCP session will be seen. All subsequent
6813headers will be considered data only and not analyzed. Furthermore, HAProxy
6814never touches data contents, it stops analysis at the end of headers.
6815
Willy Tarreau816b9792009-09-15 21:25:21 +02006816There is an exception though. If HAProxy encounters an "Informational Response"
6817(status code 1xx), it is able to process all rsp* rules which can allow, deny,
6818rewrite or delete a header, but it will refuse to add a header to any such
6819messages as this is not HTTP-compliant. The reason for still processing headers
6820in such responses is to stop and/or fix any possible information leak which may
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006821happen, for instance because another downstream equipment would unconditionally
Willy Tarreau816b9792009-09-15 21:25:21 +02006822add a header, or if a server name appears there. When such messages are seen,
6823normal processing still occurs on the next non-informational messages.
6824
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006825This section covers common usage of the following keywords, described in detail
6826in section 4.2 :
6827
6828 - reqadd <string>
6829 - reqallow <search>
6830 - reqiallow <search>
6831 - reqdel <search>
6832 - reqidel <search>
6833 - reqdeny <search>
6834 - reqideny <search>
6835 - reqpass <search>
6836 - reqipass <search>
6837 - reqrep <search> <replace>
6838 - reqirep <search> <replace>
6839 - reqtarpit <search>
6840 - reqitarpit <search>
6841 - rspadd <string>
6842 - rspdel <search>
6843 - rspidel <search>
6844 - rspdeny <search>
6845 - rspideny <search>
6846 - rsprep <search> <replace>
6847 - rspirep <search> <replace>
6848
6849With all these keywords, the same conventions are used. The <search> parameter
6850is a POSIX extended regular expression (regex) which supports grouping through
6851parenthesis (without the backslash). Spaces and other delimiters must be
6852prefixed with a backslash ('\') to avoid confusion with a field delimiter.
6853Other characters may be prefixed with a backslash to change their meaning :
6854
6855 \t for a tab
6856 \r for a carriage return (CR)
6857 \n for a new line (LF)
6858 \ to mark a space and differentiate it from a delimiter
6859 \# to mark a sharp and differentiate it from a comment
6860 \\ to use a backslash in a regex
6861 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
6862 \xXX to write the ASCII hex code XX as in the C language
6863
6864The <replace> parameter contains the string to be used to replace the largest
6865portion of text matching the regex. It can make use of the special characters
6866above, and can reference a substring which is delimited by parenthesis in the
6867regex, by writing a backslash ('\') immediately followed by one digit from 0 to
68689 indicating the group position (0 designating the entire line). This practice
6869is very common to users of the "sed" program.
6870
6871The <string> parameter represents the string which will systematically be added
6872after the last header line. It can also use special character sequences above.
6873
6874Notes related to these keywords :
6875---------------------------------
6876 - these keywords are not always convenient to allow/deny based on header
6877 contents. It is strongly recommended to use ACLs with the "block" keyword
6878 instead, resulting in far more flexible and manageable rules.
6879
6880 - lines are always considered as a whole. It is not possible to reference
6881 a header name only or a value only. This is important because of the way
6882 headers are written (notably the number of spaces after the colon).
6883
6884 - the first line is always considered as a header, which makes it possible to
6885 rewrite or filter HTTP requests URIs or response codes, but in turn makes
6886 it harder to distinguish between headers and request line. The regex prefix
6887 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
6888 ^[^ \t:]*: matches any header name followed by a colon.
6889
6890 - for performances reasons, the number of characters added to a request or to
6891 a response is limited at build time to values between 1 and 4 kB. This
6892 should normally be far more than enough for most usages. If it is too short
6893 on occasional usages, it is possible to gain some space by removing some
6894 useless headers before adding new ones.
6895
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006896 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006897 without the 'i' letter except that they ignore case when matching patterns.
6898
6899 - when a request passes through a frontend then a backend, all req* rules
6900 from the frontend will be evaluated, then all req* rules from the backend
6901 will be evaluated. The reverse path is applied to responses.
6902
6903 - req* statements are applied after "block" statements, so that "block" is
6904 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01006905 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006906
6907
Willy Tarreaub937b7e2010-01-12 15:27:54 +010069087. Using ACLs and pattern extraction
6909------------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006910
6911The use of Access Control Lists (ACL) provides a flexible solution to perform
6912content switching and generally to take decisions based on content extracted
6913from the request, the response or any environmental status. The principle is
6914simple :
6915
6916 - define test criteria with sets of values
6917 - perform actions only if a set of tests is valid
6918
6919The actions generally consist in blocking the request, or selecting a backend.
6920
6921In order to define a test, the "acl" keyword is used. The syntax is :
6922
6923 acl <aclname> <criterion> [flags] [operator] <value> ...
6924
6925This creates a new ACL <aclname> or completes an existing one with new tests.
6926Those tests apply to the portion of request/response specified in <criterion>
6927and may be adjusted with optional flags [flags]. Some criteria also support
6928an operator which may be specified before the set of values. The values are
6929of the type supported by the criterion, and are separated by spaces.
6930
6931ACL names must be formed from upper and lower case letters, digits, '-' (dash),
6932'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
6933which means that "my_acl" and "My_Acl" are two different ACLs.
6934
6935There is no enforced limit to the number of ACLs. The unused ones do not affect
6936performance, they just consume a small amount of memory.
6937
6938The following ACL flags are currently supported :
6939
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006940 -i : ignore case during matching of all subsequent patterns.
6941 -f : load patterns from a file.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006942 -- : force end of flags. Useful when a string looks like one of the flags.
6943
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006944The "-f" flag is special as it loads all of the lines it finds in the file
6945specified in argument and loads all of them before continuing. It is even
6946possible to pass multiple "-f" arguments if the patterns are to be loaded from
Willy Tarreau58215a02010-05-13 22:07:43 +02006947multiple files. Empty lines as well as lines beginning with a sharp ('#') will
6948be ignored. All leading spaces and tabs will be stripped. If it is absolutely
6949needed to insert a valid pattern beginning with a sharp, just prefix it with a
6950space so that it is not taken for a comment. Depending on the data type and
6951match method, haproxy may load the lines into a binary tree, allowing very fast
6952lookups. This is true for IPv4 and exact string matching. In this case,
6953duplicates will automatically be removed. Also, note that the "-i" flag applies
6954to subsequent entries and not to entries loaded from files preceeding it. For
6955instance :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006956
6957 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
6958
6959In this example, each line of "exact-ua.lst" will be exactly matched against
6960the "user-agent" header of the request. Then each line of "generic-ua" will be
6961case-insensitively matched. Then the word "test" will be insensitively matched
6962too.
6963
6964Note that right now it is difficult for the ACL parsers to report errors, so if
6965a file is unreadable or unparsable, the most you'll get is a parse error in the
6966ACL. Thus, file-based ACLs should only be produced by reliable processes.
6967
Willy Tarreau6a06a402007-07-15 20:15:28 +02006968Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01006969
Willy Tarreau6a06a402007-07-15 20:15:28 +02006970 - integers or integer ranges
6971 - strings
6972 - regular expressions
6973 - IP addresses and networks
6974
6975
Willy Tarreauc57f0e22009-05-10 13:12:33 +020069767.1. Matching integers
6977----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006978
6979Matching integers is special in that ranges and operators are permitted. Note
6980that integer matching only applies to positive values. A range is a value
6981expressed with a lower and an upper bound separated with a colon, both of which
6982may be omitted.
6983
6984For instance, "1024:65535" is a valid range to represent a range of
6985unprivileged ports, and "1024:" would also work. "0:1023" is a valid
6986representation of privileged ports, and ":1023" would also work.
6987
Willy Tarreau62644772008-07-16 18:36:06 +02006988As a special case, some ACL functions support decimal numbers which are in fact
6989two integers separated by a dot. This is used with some version checks for
6990instance. All integer properties apply to those decimal numbers, including
6991ranges and operators.
6992
Willy Tarreau6a06a402007-07-15 20:15:28 +02006993For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01006994operators with ranges does not make much sense and is strongly discouraged.
6995Similarly, it does not make much sense to perform order comparisons with a set
6996of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006997
Willy Tarreau0ba27502007-12-24 16:55:16 +01006998Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02006999
7000 eq : true if the tested value equals at least one value
7001 ge : true if the tested value is greater than or equal to at least one value
7002 gt : true if the tested value is greater than at least one value
7003 le : true if the tested value is less than or equal to at least one value
7004 lt : true if the tested value is less than at least one value
7005
Willy Tarreau0ba27502007-12-24 16:55:16 +01007006For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007007
7008 acl negative-length hdr_val(content-length) lt 0
7009
Willy Tarreau62644772008-07-16 18:36:06 +02007010This one matches SSL versions between 3.0 and 3.1 (inclusive) :
7011
7012 acl sslv3 req_ssl_ver 3:3.1
7013
Willy Tarreau6a06a402007-07-15 20:15:28 +02007014
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070157.2. Matching strings
7016---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007017
7018String matching applies to verbatim strings as they are passed, with the
7019exception of the backslash ("\") which makes it possible to escape some
7020characters such as the space. If the "-i" flag is passed before the first
7021string, then the matching will be performed ignoring the case. In order
7022to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01007023before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007024
7025
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070267.3. Matching regular expressions (regexes)
7027-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007028
7029Just like with string matching, regex matching applies to verbatim strings as
7030they are passed, with the exception of the backslash ("\") which makes it
7031possible to escape some characters such as the space. If the "-i" flag is
7032passed before the first regex, then the matching will be performed ignoring
7033the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01007034the "--" flag before the first string. Same principle applies of course to
7035match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007036
7037
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070387.4. Matching IPv4 addresses
7039----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007040
7041IPv4 addresses values can be specified either as plain addresses or with a
7042netmask appended, in which case the IPv4 address matches whenever it is
7043within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007044host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01007045difficult to read and debug configurations. If hostnames are used, you should
7046at least ensure that they are present in /etc/hosts so that the configuration
7047does not depend on any random DNS match at the moment the configuration is
7048parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007049
7050
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070517.5. Available matching criteria
7052--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007053
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070547.5.1. Matching at Layer 4 and below
7055------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007056
7057A first set of criteria applies to information which does not require any
7058analysis of the request or response contents. Those generally include TCP/IP
7059addresses and ports, as well as internal values independant on the stream.
7060
Willy Tarreau6a06a402007-07-15 20:15:28 +02007061always_false
7062 This one never matches. All values and flags are ignored. It may be used as
7063 a temporary replacement for another one when adjusting configurations.
7064
7065always_true
7066 This one always matches. All values and flags are ignored. It may be used as
7067 a temporary replacement for another one when adjusting configurations.
7068
Willy Tarreaud63335a2010-02-26 12:56:52 +01007069avg_queue <integer>
Willy Tarreau6cbd6472010-09-08 19:06:18 +02007070avg_queue(backend) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007071 Returns the total number of queued connections of the designated backend
7072 divided by the number of active servers. This is very similar to "queue"
7073 except that the size of the farm is considered, in order to give a more
7074 accurate measurement of the time it may take for a new connection to be
7075 processed. The main usage is to return a sorry page to new users when it
7076 becomes certain they will get a degraded service. Note that in the event
7077 there would not be any active server anymore, we would consider twice the
7078 number of queued connections as the measured value. This is a fair estimate,
7079 as we expect one server to get back soon anyway, but we still prefer to send
7080 new traffic to another backend if in better shape. See also the "queue",
7081 "be_conn", and "be_sess_rate" criteria.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01007082
Willy Tarreaua36af912009-10-10 12:02:45 +02007083be_conn <integer>
Willy Tarreau6cbd6472010-09-08 19:06:18 +02007084be_conn(backend) <integer>
Willy Tarreaua36af912009-10-10 12:02:45 +02007085 Applies to the number of currently established connections on the backend,
7086 possibly including the connection being evaluated. If no backend name is
7087 specified, the current one is used. But it is also possible to check another
7088 backend. It can be used to use a specific farm when the nominal one is full.
7089 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007090
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007091be_id <integer>
7092 Applies to the backend's id. Can be used in frontends to check from which
7093 backend it was called.
7094
Willy Tarreaud63335a2010-02-26 12:56:52 +01007095be_sess_rate <integer>
7096be_sess_rate(backend) <integer>
7097 Returns true when the sessions creation rate on the backend matches the
7098 specified values or ranges, in number of new sessions per second. This is
7099 used to switch to an alternate backend when an expensive or fragile one
7100 reaches too high a session rate, or to limit abuse of service (eg. prevent
7101 sucking of an online dictionary).
7102
7103 Example :
7104 # Redirect to an error page if the dictionary is requested too often
7105 backend dynamic
7106 mode http
7107 acl being_scanned be_sess_rate gt 100
7108 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01007109
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007110connslots <integer>
7111connslots(backend) <integer>
7112 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02007113 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007114 usage; see "use_backend" keyword) can be redirected to a different backend.
7115
Willy Tarreau55165fe2009-05-10 12:02:55 +02007116 'connslots' = number of available server connection slots, + number of
7117 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007118
Willy Tarreaua36af912009-10-10 12:02:45 +02007119 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02007120 useful when you have a case of traffic going to one single ip, splitting into
7121 multiple backends (perhaps using acls to do name-based load balancing) and
7122 you want to be able to differentiate between different backends, and their
7123 available "connslots". Also, whereas "nbsrv" only measures servers that are
7124 actually *down*, this acl is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02007125 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007126
Willy Tarreau55165fe2009-05-10 12:02:55 +02007127 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
7128 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
7129 then this acl clearly does not make sense, in which case the value returned
7130 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007131
Willy Tarreaud63335a2010-02-26 12:56:52 +01007132dst <ip_address>
7133 Applies to the local IPv4 address the client connected to. It can be used to
7134 switch to a different backend for some alternative addresses.
Willy Tarreaua36af912009-10-10 12:02:45 +02007135
Willy Tarreaud63335a2010-02-26 12:56:52 +01007136dst_conn <integer>
7137 Applies to the number of currently established connections on the same socket
7138 including the one being evaluated. It can be used to either return a sorry
7139 page before hard-blocking, or to use a specific backend to drain new requests
7140 when the socket is considered saturated. This offers the ability to assign
7141 different limits to different listening ports or addresses. See also the
7142 "fe_conn" and "be_conn" criteria.
7143
7144dst_port <integer>
7145 Applies to the local port the client connected to. It can be used to switch
7146 to a different backend for some alternative ports.
7147
7148fe_conn <integer>
7149fe_conn(frontend) <integer>
7150 Applies to the number of currently established connections on the frontend,
7151 possibly including the connection being evaluated. If no frontend name is
7152 specified, the current one is used. But it is also possible to check another
7153 frontend. It can be used to either return a sorry page before hard-blocking,
7154 or to use a specific backend to drain new requests when the farm is
7155 considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
7156 criteria.
7157
7158fe_id <integer>
Cyril Bonté78caf842010-03-10 22:41:43 +01007159 Applies to the frontend's id. Can be used in backends to check from which
Willy Tarreaud63335a2010-02-26 12:56:52 +01007160 frontend it was called.
Willy Tarreaua36af912009-10-10 12:02:45 +02007161
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007162fe_sess_rate <integer>
7163fe_sess_rate(frontend) <integer>
7164 Returns true when the session creation rate on the current or the named
7165 frontend matches the specified values or ranges, expressed in new sessions
7166 per second. This is used to limit the connection rate to acceptable ranges in
7167 order to prevent abuse of service at the earliest moment. This can be
7168 combined with layer 4 ACLs in order to force the clients to wait a bit for
7169 the rate to go down below the limit.
7170
7171 Example :
7172 # This frontend limits incoming mails to 10/s with a max of 100
7173 # concurrent connections. We accept any connection below 10/s, and
7174 # force excess clients to wait for 100 ms. Since clients are limited to
7175 # 100 max, there cannot be more than 10 incoming mails per second.
7176 frontend mail
7177 bind :25
7178 mode tcp
7179 maxconn 100
7180 acl too_fast fe_sess_rate ge 10
7181 tcp-request inspect-delay 100ms
7182 tcp-request content accept if ! too_fast
7183 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01007184
Willy Tarreaud63335a2010-02-26 12:56:52 +01007185nbsrv <integer>
7186nbsrv(backend) <integer>
7187 Returns true when the number of usable servers of either the current backend
7188 or the named backend matches the values or ranges specified. This is used to
7189 switch to an alternate backend when the number of servers is too low to
7190 to handle some load. It is useful to report a failure when combined with
7191 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007192
Willy Tarreaud63335a2010-02-26 12:56:52 +01007193queue <integer>
Willy Tarreauf5a526f2010-09-01 08:06:18 +02007194queue(backend) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007195 Returns the total number of queued connections of the designated backend,
7196 including all the connections in server queues. If no backend name is
7197 specified, the current one is used, but it is also possible to check another
7198 one. This can be used to take actions when queuing goes above a known level,
7199 generally indicating a surge of traffic or a massive slowdown on the servers.
7200 One possible action could be to reject new users but still accept old ones.
7201 See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
7202
Willy Tarreaue9656522010-08-17 15:40:09 +02007203sc1_bytes_in_rate
7204sc2_bytes_in_rate
7205 Returns the average client-to-server bytes rate from the currently tracked
7206 counters, measured in amount of bytes over the period configured in the
7207 table. See also src_bytes_in_rate.
7208
7209sc1_bytes_out_rate
7210sc2_bytes_out_rate
7211 Returns the average server-to-client bytes rate from the currently tracked
7212 counters, measured in amount of bytes over the period configured in the
7213 table. See also src_bytes_out_rate.
7214
7215sc1_conn_cnt
7216sc2_conn_cnt
7217 Returns the cumulated number of incoming connections from currently tracked
7218 counters. See also src_conn_cnt.
7219
7220sc1_conn_cur
7221sc2_conn_cur
7222 Returns the current amount of concurrent connections tracking the same
7223 tracked counters. This number is automatically incremented when tracking
7224 begins and decremented when tracking stops. See also src_conn_cur.
7225
7226sc1_conn_rate
7227sc2_conn_rate
7228 Returns the average connection rate from the currently tracked counters,
7229 measured in amount of connections over the period configured in the table.
7230 See also src_conn_rate.
7231
7232sc1_get_gpc0
7233sc2_get_gpc0
7234 Returns the value of the first General Purpose Counter associated to the
7235 currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0.
7236
7237sc1_http_err_cnt
7238sc2_http_err_cnt
7239 Returns the cumulated number of HTTP errors from the currently tracked
7240 counters. This includes the both request errors and 4xx error responses.
7241 See also src_http_err_cnt.
7242
7243sc1_http_err_rate
7244sc2_http_err_rate
7245 Returns the average rate of HTTP errors from the currently tracked counters,
7246 measured in amount of errors over the period configured in the table. This
7247 includes the both request errors and 4xx error responses. See also
7248 src_http_err_rate.
7249
7250sc1_http_req_cnt
7251sc2_http_req_cnt
7252 Returns the cumulated number of HTTP requests from the currently tracked
7253 counters. This includes every started request, valid or not. See also
7254 src_http_req_cnt.
7255
7256sc1_http_req_rate
7257sc2_http_req_rate
7258 Returns the average rate of HTTP requests from the currently tracked
7259 counters, measured in amount of requests over the period configured in
7260 the table. This includes every started request, valid or not. See also
7261 src_http_req_rate.
7262
7263sc1_inc_gpc0
7264sc2_inc_gpc0
7265 Increments the first General Purpose Counter associated to the currently
7266 tracked counters, and returns its value. Before the first invocation, the
7267 stored value is zero, so first invocation will increase it to 1 and will
7268 return 1. The test can also be used alone and always returns true. This is
7269 typically used as a second ACL in an expression in order to mark a connection
7270 when a first ACL was verified :
7271
7272 acl abuse sc1_http_req_rate gt 10
7273 acl kill sc1_inc_gpc0
7274 tcp-request connection reject if abuse kill
7275
7276sc1_kbytes_in
7277sc2_kbytes_in
7278 Returns the amount of client-to-server data from the currently tracked
7279 counters, measured in kilobytes over the period configured in the table. The
7280 test is currently performed on 32-bit integers, which limits values to 4
7281 terabytes. See also src_kbytes_in.
7282
7283sc1_kbytes_out
7284sc2_kbytes_out
7285 Returns the amount of server-to-client data from the currently tracked
7286 counters, measured in kilobytes over the period configured in the table. The
7287 test is currently performed on 32-bit integers, which limits values to 4
7288 terabytes. See also src_kbytes_out.
7289
7290sc1_sess_cnt
7291sc2_sess_cnt
7292 Returns the cumulated number of incoming connections that were transformed
7293 into sessions, which means that they were accepted by a "tcp-request
7294 connection" rule, from the currently tracked counters. A backend may count
7295 more sessions than connections because each connection could result in many
7296 backend sessions if some HTTP keep-alive is performend over the connection
7297 with the client. See also src_sess_cnt.
7298
7299sc1_sess_rate
7300sc2_sess_rate
7301 Returns the average session rate from the currently tracked counters,
7302 measured in amount of sessions over the period configured in the table. A
7303 session is a connection that got past the early "tcp-request connection"
7304 rules. A backend may count more sessions than connections because each
7305 connection could result in many backend sessions if some HTTP keep-alive is
7306 performend over the connection with the client. See also src_sess_rate.
7307
Willy Tarreaud63335a2010-02-26 12:56:52 +01007308so_id <integer>
7309 Applies to the socket's id. Useful in frontends with many bind keywords.
7310
7311src <ip_address>
7312 Applies to the client's IPv4 address. It is usually used to limit access to
7313 certain resources such as statistics. Note that it is the TCP-level source
7314 address which is used, and not the address of a client behind a proxy.
7315
Willy Tarreauc9705a12010-07-27 20:05:50 +02007316src_bytes_in_rate <integer>
7317src_bytes_in_rate(table) <integer>
7318 Returns the average bytes rate from the connection's source IPv4 address in
7319 the current proxy's stick-table or in the designated stick-table, measured in
7320 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007321 not found, zero is returned. See also sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007322
7323src_bytes_out_rate <integer>
7324src_bytes_out_rate(table) <integer>
7325 Returns the average bytes rate to the connection's source IPv4 address in the
7326 current proxy's stick-table or in the designated stick-table, measured in
7327 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007328 not found, zero is returned. See also sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007329
7330src_conn_cnt <integer>
7331src_conn_cnt(table) <integer>
7332 Returns the cumulated number of connections initiated from the current
7333 connection's source IPv4 address in the current proxy's stick-table or in
7334 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02007335 See also sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007336
7337src_conn_cur <integer>
7338src_conn_cur(table) <integer>
7339 Returns the current amount of concurrent connections initiated from the
7340 current connection's source IPv4 address in the current proxy's stick-table
7341 or in the designated stick-table. If the address is not found, zero is
Willy Tarreaue9656522010-08-17 15:40:09 +02007342 returned. See also sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007343
7344src_conn_rate <integer>
7345src_conn_rate(table) <integer>
7346 Returns the average connection rate from the connection's source IPv4 address
7347 in the current proxy's stick-table or in the designated stick-table, measured
7348 in amount of connections over the period configured in the table. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02007349 address is not found, zero is returned. See also sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007350
7351src_get_gpc0 <integer>
7352src_get_gpc0(table) <integer>
7353 Returns the value of the first General Purpose Counter associated to the
7354 connection's source IPv4 address in the current proxy's stick-table or in
7355 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02007356 See also sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007357
7358src_http_err_cnt <integer>
7359src_http_err_cnt(table) <integer>
7360 Returns the cumulated number of HTTP errors from the current connection's
7361 source IPv4 address in the current proxy's stick-table or in the designated
7362 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreaue9656522010-08-17 15:40:09 +02007363 If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007364
7365src_http_err_rate <integer>
7366src_http_err_rate(table) <integer>
7367 Returns the average rate of HTTP errors from the current connection's source
7368 IPv4 address in the current proxy's stick-table or in the designated stick-
7369 table, measured in amount of errors over the period configured in the table.
7370 This includes the both request errors and 4xx error responses. If the address
Willy Tarreaue9656522010-08-17 15:40:09 +02007371 is not found, zero is returned. See also sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007372
7373src_http_req_cnt <integer>
7374src_http_req_cnt(table) <integer>
7375 Returns the cumulated number of HTTP requests from the current connection's
7376 source IPv4 address in the current proxy's stick-table or in the designated
7377 stick-table. This includes every started request, valid or not. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02007378 address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007379
7380src_http_req_rate <integer>
7381src_http_req_rate(table) <integer>
7382 Returns the average rate of HTTP requests from the current connection's
7383 source IPv4 address in the current proxy's stick-table or in the designated
7384 stick-table, measured in amount of requests over the period configured in the
7385 table. This includes every started request, valid or not. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007386 not found, zero is returned. See also sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007387
7388src_inc_gpc0 <integer>
7389src_inc_gpc0(table) <integer>
7390 Increments 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 value. If the address is not found, an entry is
7393 created and 1 is returned. The test can also be used alone and always returns
7394 true. This is typically used as a second ACL in an expression in order to
7395 mark a connection when a first ACL was verified :
7396
7397 acl abuse src_http_req_rate gt 10
7398 acl kill src_inc_gpc0
Willy Tarreaue9656522010-08-17 15:40:09 +02007399 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02007400
7401src_kbytes_in <integer>
7402src_kbytes_in(table) <integer>
7403 Returns the amount of data received from the connection's source IPv4 address
7404 in the current proxy's stick-table or in the designated stick-table, measured
7405 in kilobytes over the period configured in the table. If the address is not
7406 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02007407 which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007408
7409src_kbytes_out <integer>
7410src_kbytes_out(table) <integer>
7411 Returns the amount of data sent to the connection's source IPv4 address in
7412 the current proxy's stick-table or in the designated stick-table, measured
7413 in kilobytes over the period configured in the table. If the address is not
7414 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02007415 which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007416
Willy Tarreaud63335a2010-02-26 12:56:52 +01007417src_port <integer>
7418 Applies to the client's TCP source port. This has a very limited usage.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007419
Willy Tarreauc9705a12010-07-27 20:05:50 +02007420src_sess_cnt <integer>
7421src_sess_cnt(table) <integer>
7422 Returns the cumulated number of connections initiated from the current
7423 connection's source IPv4 address in the current proxy's stick-table or in the
7424 designated stick-table, that were transformed into sessions, which means that
7425 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreaue9656522010-08-17 15:40:09 +02007426 is returned. See also sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007427
7428src_sess_rate <integer>
7429src_sess_rate(table) <integer>
7430 Returns the average session rate from the connection's source IPv4 address in
7431 the current proxy's stick-table or in the designated stick-table, measured in
7432 amount of sessions over the period configured in the table. A session is a
7433 connection that got past the early "tcp-request" rules. If the address is not
Willy Tarreaue9656522010-08-17 15:40:09 +02007434 found, zero is returned. See also sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007435
7436src_updt_conn_cnt <integer>
7437src_updt_conn_cnt(table) <integer>
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007438 Creates or updates the entry associated to the source IPv4 address in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02007439 current proxy's stick-table or in the designated stick-table. This table
7440 must be configured to store the "conn_cnt" data type, otherwise the match
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007441 will be ignored. The current count is incremented by one, and the expiration
7442 timer refreshed. The updated count is returned, so this match can't return
7443 zero. This is used to reject service abusers based on their source address.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007444 Note: it is recommended to use the more complete "track-counters" instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007445
7446 Example :
7447 # This frontend limits incoming SSH connections to 3 per 10 second for
7448 # each source address, and rejects excess connections until a 10 second
7449 # silence is observed. At most 20 addresses are tracked.
7450 listen ssh
7451 bind :22
7452 mode tcp
7453 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02007454 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007455 tcp-request content reject if { src_update_count gt 3 }
7456 server local 127.0.0.1:22
7457
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007458srv_id <integer>
7459 Applies to the server's id. Can be used in frontends or backends.
7460
Willy Tarreau0b1cd942010-05-16 22:18:27 +02007461srv_is_up(<server>)
7462srv_is_up(<backend>/<server>)
7463 Returns true when the designated server is UP, and false when it is either
7464 DOWN or in maintenance mode. If <backend> is omitted, then the server is
7465 looked up in the current backend. The function takes no arguments since it
7466 is used as a boolean. It is mainly used to take action based on an external
7467 status reported via a health check (eg: a geographical site's availability).
7468 Another possible use which is more of a hack consists in using dummy servers
7469 as boolean variables that can be enabled or disabled from the CLI, so that
7470 rules depending on those ACLs can be tweaked in realtime.
7471
Willy Tarreauc735a072011-03-29 00:57:02 +02007472table_avl <integer>
7473table_avl(table) <integer>
7474 Returns the total number of available entries in the current proxy's
7475 stick-table or in the designated stick-table. See also table_cnt.
7476
7477table_cnt <integer>
7478table_cnt(table) <integer>
7479 Returns the total number of entries currently in use in the current proxy's
7480 stick-table or in the designated stick-table. See also src_conn_cnt and
7481 table_avl for other entry counting methods.
7482
Willy Tarreau0ba27502007-12-24 16:55:16 +01007483
Willy Tarreaue9656522010-08-17 15:40:09 +020074847.5.2. Matching contents at Layer 4 (also called Layer 6)
7485---------------------------------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02007486
7487A second set of criteria depends on data found in buffers, but which can change
7488during analysis. This requires that some data has been buffered, for instance
Willy Tarreaue9656522010-08-17 15:40:09 +02007489through TCP request content inspection. Please see the "tcp-request content"
7490keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +02007491
7492req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02007493 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02007494 specified range. It is important to understand that this test does not
7495 return false as long as the buffer is changing. This means that a check with
7496 equality to zero will almost always immediately match at the beginning of the
7497 session, while a test for more data will wait for that data to come in and
7498 return false only when haproxy is certain that no more data will come in.
7499 This test was designed to be used with TCP request content inspection.
7500
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007501req_proto_http
7502 Returns true when data in the request buffer look like HTTP and correctly
7503 parses as such. It is the same parser as the common HTTP request parser which
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007504 is used so there should be no surprises. This test can be used for instance
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007505 to direct HTTP traffic to a given port and HTTPS traffic to another one
7506 using TCP request content inspection rules.
7507
Emeric Brunbede3d02009-06-30 17:54:00 +02007508req_rdp_cookie <string>
7509req_rdp_cookie(name) <string>
7510 Returns true when data in the request buffer look like the RDP protocol, and
7511 a cookie is present and equal to <string>. By default, any cookie name is
7512 checked, but a specific cookie name can be specified in parenthesis. The
7513 parser only checks for the first cookie, as illustrated in the RDP protocol
7514 specification. The cookie name is case insensitive. This ACL can be useful
7515 with the "MSTS" cookie, as it can contain the user name of the client
7516 connecting to the server if properly configured on the client. This can be
7517 used to restrict access to certain servers to certain users.
7518
7519req_rdp_cookie_cnt <integer>
7520req_rdp_cookie_cnt(name) <integer>
7521 Returns true when the data in the request buffer look like the RDP protocol
7522 and the number of RDP cookies matches the specified range (typically zero or
7523 one). Optionally a specific cookie name can be checked. This is a simple way
7524 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
7525 cookies.
7526
Willy Tarreau62644772008-07-16 18:36:06 +02007527req_ssl_ver <decimal>
7528 Returns true when data in the request buffer look like SSL, with a protocol
7529 version matching the specified range. Both SSLv2 hello messages and SSLv3
7530 messages are supported. The test tries to be strict enough to avoid being
7531 easily fooled. In particular, it waits for as many bytes as announced in the
7532 message header if this header looks valid (bound to the buffer size). Note
7533 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
7534 with TCP request content inspection.
7535
Emeric Brun392d1d82010-09-24 15:45:16 +02007536req_ssl_hello_type <integer>
7537 Returns true when data in the request buffer looks like a complete SSL (v3
7538 or superior) hello message and handshake type is equal to <integer>.
7539 This test was designed to be used with TCP request content inspection: an
7540 SSL session ID may be fetched.
7541
7542rep_ssl_hello_type <integer>
7543 Returns true when data in the response buffer looks like a complete SSL (v3
7544 or superior) hello message and handshake type is equal to <integer>.
7545 This test was designed to be used with TCP response content inspection: a
7546 SSL session ID may be fetched.
7547
Willy Tarreaub6fb4202008-07-20 11:18:28 +02007548wait_end
7549 Waits for the end of the analysis period to return true. This may be used in
7550 conjunction with content analysis to avoid returning a wrong verdict early.
7551 It may also be used to delay some actions, such as a delayed reject for some
7552 special addresses. Since it either stops the rules evaluation or immediately
7553 returns true, it is recommended to use this acl as the last one in a rule.
7554 Please note that the default ACL "WAIT_END" is always usable without prior
7555 declaration. This test was designed to be used with TCP request content
7556 inspection.
7557
7558 Examples :
7559 # delay every incoming request by 2 seconds
7560 tcp-request inspect-delay 2s
7561 tcp-request content accept if WAIT_END
7562
7563 # don't immediately tell bad guys they are rejected
7564 tcp-request inspect-delay 10s
7565 acl goodguys src 10.0.0.0/24
7566 acl badguys src 10.0.1.0/24
7567 tcp-request content accept if goodguys
7568 tcp-request content reject if badguys WAIT_END
7569 tcp-request content reject
7570
Willy Tarreau62644772008-07-16 18:36:06 +02007571
Willy Tarreauc57f0e22009-05-10 13:12:33 +020075727.5.3. Matching at Layer 7
7573--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007574
Willy Tarreau62644772008-07-16 18:36:06 +02007575A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01007576application layer (layer 7). Those require that a full HTTP request has been
7577read, and are only evaluated then. They may require slightly more CPU resources
7578than the layer 4 ones, but not much since the request and response are indexed.
7579
Willy Tarreaud63335a2010-02-26 12:56:52 +01007580hdr <string>
7581hdr(header) <string>
7582 Note: all the "hdr*" matching criteria either apply to all headers, or to a
7583 particular header whose name is passed between parenthesis and without any
7584 space. The header name is not case-sensitive. The header matching complies
7585 with RFC2616, and treats as separate headers all values delimited by commas.
7586 Use the shdr() variant for response headers sent by the server.
7587
7588 The "hdr" criteria returns true if any of the headers matching the criteria
7589 match any of the strings. This can be used to check exact for values. For
7590 instance, checking that "connection: close" is set :
7591
7592 hdr(Connection) -i close
7593
7594hdr_beg <string>
7595hdr_beg(header) <string>
7596 Returns true when one of the headers begins with one of the strings. See
7597 "hdr" for more information on header matching. Use the shdr_beg() variant for
7598 response headers sent by the server.
7599
7600hdr_cnt <integer>
7601hdr_cnt(header) <integer>
7602 Returns true when the number of occurrence of the specified header matches
7603 the values or ranges specified. It is important to remember that one header
7604 line may count as several headers if it has several values. This is used to
7605 detect presence, absence or abuse of a specific header, as well as to block
7606 request smuggling attacks by rejecting requests which contain more than one
7607 of certain headers. See "hdr" for more information on header matching. Use
7608 the shdr_cnt() variant for response headers sent by the server.
7609
7610hdr_dir <string>
7611hdr_dir(header) <string>
7612 Returns true when one of the headers contains one of the strings either
7613 isolated or delimited by slashes. This is used to perform filename or
7614 directory name matching, and may be used with Referer. See "hdr" for more
7615 information on header matching. Use the shdr_dir() variant for response
7616 headers sent by the server.
7617
7618hdr_dom <string>
7619hdr_dom(header) <string>
7620 Returns true when one of the headers contains one of the strings either
7621 isolated or delimited by dots. This is used to perform domain name matching,
7622 and may be used with the Host header. See "hdr" for more information on
7623 header matching. Use the shdr_dom() variant for response headers sent by the
7624 server.
7625
7626hdr_end <string>
7627hdr_end(header) <string>
7628 Returns true when one of the headers ends with one of the strings. See "hdr"
7629 for more information on header matching. Use the shdr_end() variant for
7630 response headers sent by the server.
7631
7632hdr_ip <ip_address>
7633hdr_ip(header) <ip_address>
7634 Returns true when one of the headers' values contains an IP address matching
7635 <ip_address>. This is mainly used with headers such as X-Forwarded-For or
7636 X-Client-IP. See "hdr" for more information on header matching. Use the
7637 shdr_ip() variant for response headers sent by the server.
7638
7639hdr_reg <regex>
7640hdr_reg(header) <regex>
7641 Returns true when one of the headers matches of the regular expressions. It
7642 can be used at any time, but it is important to remember that regex matching
7643 is slower than other methods. See also other "hdr_" criteria, as well as
7644 "hdr" for more information on header matching. Use the shdr_reg() variant for
7645 response headers sent by the server.
7646
7647hdr_sub <string>
7648hdr_sub(header) <string>
7649 Returns true when one of the headers contains one of the strings. See "hdr"
7650 for more information on header matching. Use the shdr_sub() variant for
7651 response headers sent by the server.
7652
7653hdr_val <integer>
7654hdr_val(header) <integer>
7655 Returns true when one of the headers starts with a number which matches the
7656 values or ranges specified. This may be used to limit content-length to
7657 acceptable values for example. See "hdr" for more information on header
7658 matching. Use the shdr_val() variant for response headers sent by the server.
7659
7660http_auth(userlist)
7661http_auth_group(userlist) <group> [<group>]*
7662 Returns true when authentication data received from the client matches
7663 username & password stored on the userlist. It is also possible to
7664 use http_auth_group to check if the user is assigned to at least one
7665 of specified groups.
7666
7667 Currently only http basic auth is supported.
7668
Willy Tarreau7f18e522010-10-22 20:04:13 +02007669http_req_first
7670 Returns true when the request being processed is the first one of the
7671 connection. This can be used to add or remove headers that may be missing
7672 from some requests when a request is not the first one, or even to perform
7673 some specific ACL checks only on the first request.
7674
Willy Tarreau6a06a402007-07-15 20:15:28 +02007675method <string>
7676 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
7677 already check for most common methods.
7678
Willy Tarreau6a06a402007-07-15 20:15:28 +02007679path <string>
7680 Returns true when the path part of the request, which starts at the first
7681 slash and ends before the question mark, equals one of the strings. It may be
7682 used to match known files, such as /favicon.ico.
7683
7684path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007685 Returns true when the path begins with one of the strings. This can be used
7686 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007687
Willy Tarreau6a06a402007-07-15 20:15:28 +02007688path_dir <string>
7689 Returns true when one of the strings is found isolated or delimited with
7690 slashes in the path. This is used to perform filename or directory name
7691 matching without the risk of wrong match due to colliding prefixes. See also
7692 "url_dir" and "path_sub".
7693
7694path_dom <string>
7695 Returns true when one of the strings is found isolated or delimited with dots
7696 in the path. This may be used to perform domain name matching in proxy
7697 requests. See also "path_sub" and "url_dom".
7698
Willy Tarreaud63335a2010-02-26 12:56:52 +01007699path_end <string>
7700 Returns true when the path ends with one of the strings. This may be used to
7701 control file name extension.
7702
Willy Tarreau6a06a402007-07-15 20:15:28 +02007703path_reg <regex>
7704 Returns true when the path matches one of the regular expressions. It can be
7705 used any time, but it is important to remember that regex matching is slower
7706 than other methods. See also "url_reg" and all "path_" criteria.
7707
Willy Tarreaud63335a2010-02-26 12:56:52 +01007708path_sub <string>
7709 Returns true when the path contains one of the strings. It can be used to
7710 detect particular patterns in paths, such as "../" for example. See also
7711 "path_dir".
7712
7713req_ver <string>
7714 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
7715 ACL already check for versions 1.0 and 1.1.
7716
7717status <integer>
7718 Applies to the HTTP status code in the HTTP response, eg: "302". It can be
7719 used to act on responses depending on status ranges, for instance, remove
7720 any Location header if the response is not a 3xx.
7721
Willy Tarreau6a06a402007-07-15 20:15:28 +02007722url <string>
7723 Applies to the whole URL passed in the request. The only real use is to match
7724 "*", for which there already is a predefined ACL.
7725
7726url_beg <string>
7727 Returns true when the URL begins with one of the strings. This can be used to
7728 check whether a URL begins with a slash or with a protocol scheme.
7729
Willy Tarreau6a06a402007-07-15 20:15:28 +02007730url_dir <string>
7731 Returns true when one of the strings is found isolated or delimited with
7732 slashes in the URL. This is used to perform filename or directory name
7733 matching without the risk of wrong match due to colliding prefixes. See also
7734 "path_dir" and "url_sub".
7735
7736url_dom <string>
7737 Returns true when one of the strings is found isolated or delimited with dots
7738 in the URL. This is used to perform domain name matching without the risk of
7739 wrong match due to colliding prefixes. See also "url_sub".
7740
Willy Tarreaud63335a2010-02-26 12:56:52 +01007741url_end <string>
7742 Returns true when the URL ends with one of the strings. It has very limited
7743 use. "path_end" should be used instead for filename matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007744
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007745url_ip <ip_address>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007746 Applies to the IP address specified in the absolute URI in an HTTP request.
7747 It can be used to prevent access to certain resources such as local network.
Willy Tarreau198a7442008-01-17 12:05:32 +01007748 It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007749
7750url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007751 Applies to the port specified in the absolute URI in an HTTP request. It can
7752 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01007753 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01007754 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007755
Willy Tarreaud63335a2010-02-26 12:56:52 +01007756url_reg <regex>
7757 Returns true when the URL matches one of the regular expressions. It can be
7758 used any time, but it is important to remember that regex matching is slower
7759 than other methods. See also "path_reg" and all "url_" criteria.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007760
Willy Tarreaud63335a2010-02-26 12:56:52 +01007761url_sub <string>
7762 Returns true when the URL contains one of the strings. It can be used to
7763 detect particular patterns in query strings for example. See also "path_sub".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007764
Willy Tarreau198a7442008-01-17 12:05:32 +01007765
Willy Tarreauc57f0e22009-05-10 13:12:33 +020077667.6. Pre-defined ACLs
7767---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007768
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007769Some predefined ACLs are hard-coded so that they do not have to be declared in
7770every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +02007771order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +01007772
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007773ACL name Equivalent to Usage
7774---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007775FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007776HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007777HTTP_1.0 req_ver 1.0 match HTTP version 1.0
7778HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +01007779HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
7780HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
7781HTTP_URL_SLASH url_beg / match URL beginning with "/"
7782HTTP_URL_STAR url * match URL equal to "*"
7783LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007784METH_CONNECT method CONNECT match HTTP CONNECT method
7785METH_GET method GET HEAD match HTTP GET or HEAD method
7786METH_HEAD method HEAD match HTTP HEAD method
7787METH_OPTIONS method OPTIONS match HTTP OPTIONS method
7788METH_POST method POST match HTTP POST method
7789METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +02007790RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007791REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +01007792TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007793WAIT_END wait_end wait for end of content analysis
7794---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007795
Willy Tarreauced27012008-01-17 20:35:34 +01007796
Willy Tarreauc57f0e22009-05-10 13:12:33 +020077977.7. Using ACLs to form conditions
7798----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007799
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007800Some actions are only performed upon a valid condition. A condition is a
7801combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01007802
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007803 - AND (implicit)
7804 - OR (explicit with the "or" keyword or the "||" operator)
7805 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01007806
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007807A condition is formed as a disjunctive form:
Willy Tarreauced27012008-01-17 20:35:34 +01007808
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007809 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01007810
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007811Such conditions are generally used after an "if" or "unless" statement,
7812indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01007813
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007814For instance, to block HTTP requests to the "*" URL with methods other than
7815"OPTIONS", as well as POST requests without content-length, and GET or HEAD
7816requests with a content-length greater than 0, and finally every request which
7817is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01007818
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007819 acl missing_cl hdr_cnt(Content-length) eq 0
7820 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
7821 block if METH_GET HTTP_CONTENT
7822 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01007823
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007824To select a different backend for requests to static contents on the "www" site
7825and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01007826
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007827 acl url_static path_beg /static /images /img /css
7828 acl url_static path_end .gif .png .jpg .css .js
7829 acl host_www hdr_beg(host) -i www
7830 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01007831
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007832 # now use backend "static" for all static-only hosts, and for static urls
7833 # of host "www". Use backend "www" for the rest.
7834 use_backend static if host_static or host_www url_static
7835 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01007836
Willy Tarreau95fa4692010-02-01 13:05:50 +01007837It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
7838expressions that are built on the fly without needing to be declared. They must
7839be enclosed between braces, with a space before and after each brace (because
7840the braces must be seen as independant words). Example :
7841
7842 The following rule :
7843
7844 acl missing_cl hdr_cnt(Content-length) eq 0
7845 block if METH_POST missing_cl
7846
7847 Can also be written that way :
7848
7849 block if METH_POST { hdr_cnt(Content-length) eq 0 }
7850
7851It is generally not recommended to use this construct because it's a lot easier
7852to leave errors in the configuration when written that way. However, for very
7853simple rules matching only one source IP address for instance, it can make more
7854sense to use them than to declare ACLs with random names. Another example of
7855good use is the following :
7856
7857 With named ACLs :
7858
7859 acl site_dead nbsrv(dynamic) lt 2
7860 acl site_dead nbsrv(static) lt 2
7861 monitor fail if site_dead
7862
7863 With anonymous ACLs :
7864
7865 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
7866
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007867See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01007868
Willy Tarreau5764b382007-11-30 17:46:49 +01007869
Willy Tarreaub937b7e2010-01-12 15:27:54 +010078707.8. Pattern extraction
7871-----------------------
7872
7873The stickiness features relies on pattern extraction in the request and
7874response. Sometimes the data needs to be converted first before being stored,
7875for instance converted from ASCII to IP or upper case to lower case.
7876
7877All these operations of data extraction and conversion are defined as
7878"pattern extraction rules". A pattern rule always has the same format. It
7879begins with a single pattern fetch word, potentially followed by a list of
7880arguments within parenthesis then an optional list of transformations. As
7881much as possible, the pattern fetch functions use the same name as their
7882equivalent used in ACLs.
7883
7884The list of currently supported pattern fetch functions is the following :
7885
7886 src This is the source IPv4 address of the client of the session.
David du Colombier9a6d3c92011-03-17 10:40:24 +01007887 It is of type IPv4 and works on both IPv4 and IPv6 tables.
7888 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
7889 according to RFC 4291.
7890
7891 src6 This is the source IPv6 address of the client of the session.
7892 It is of type IPv6 and only works with such tables.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007893
7894 dst This is the destination IPv4 address of the session on the
7895 client side, which is the address the client connected to.
7896 It can be useful when running in transparent mode. It is of
David du Colombier9a6d3c92011-03-17 10:40:24 +01007897 type IPv4 and works on both IPv4 and IPv6 tables.
7898 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
7899 according to RFC 4291.
7900
7901 dst6 This is the destination IPv6 address of the session on the
7902 client side, which is the address the client connected to.
7903 It can be useful when running in transparent mode. It is of
Simon Hormandf791f52011-05-29 15:01:10 +09007904 type IPv6 and only works with such tables.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007905
7906 dst_port This is the destination TCP port of the session on the client
7907 side, which is the port the client connected to. This might be
7908 used when running in transparent mode or when assigning dynamic
7909 ports to some clients for a whole application session. It is of
7910 type integer and only works with such tables.
7911
Willy Tarreau4a568972010-05-12 08:08:50 +02007912 hdr(name) This extracts the last occurrence of header <name> in an HTTP
7913 request and converts it to an IP address. This IP address is
7914 then used to match the table. A typical use is with the
7915 x-forwarded-for header.
7916
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007917 payload(offset,length)
7918 This extracts a binary block of <length> bytes, and starting
7919 at bytes <offset> in the buffer of request or response (request
7920 on "stick on" or "stick match" or response in on "stick store
7921 response").
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007922
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007923 payload_lv(offset1,length[,offset2])
7924 This extracts a binary block. In a first step the size of the
7925 block is read from response or request buffer at <offset>
7926 bytes and considered coded on <length> bytes. In a second step
7927 data of the block are read from buffer at <offset2> bytes
7928 (by default <lengthoffset> + <lengthsize>).
7929 If <offset2> is prefixed by '+' or '-', it is relative to
7930 <lengthoffset> + <lengthsize> else it is absolute.
7931 Ex: see SSL session id example in "stick table" chapter.
7932
David Cournapeau16023ee2010-12-23 20:55:41 +09007933 url_param(name)
7934 This extracts the first occurrence of the parameter <name> in
Simon Hormandf791f52011-05-29 15:01:10 +09007935 the query string of the request and uses the corresponding value
David Cournapeau16023ee2010-12-23 20:55:41 +09007936 to match. A typical use is to get sticky session through url (e.g.
7937 http://example.com/foo?JESSIONID=some_id with
7938 url_param(JSESSIONID)), for cases where cookies cannot be used.
7939
Simon Hormanab814e02011-06-24 14:50:20 +09007940 rdp_cookie(name)
7941 This extracts the value of the rdp cookie <name> as a string
7942 and uses this value to match. This enables implementation of
7943 persistence based on the mstshash cookie. This is typically
7944 done if there is no msts cookie present.
7945
7946 This differs from "balance rdp-cookie" in that any balancing
7947 algorithm may be used and thus the distribution of clients
7948 to backend servers is not linked to a hash of the RDP
7949 cookie. It is envisaged that using a balancing algorithm
7950 such as "balance roundrobin" or "balance leastconnect" will
7951 lead to a more even distribution of clients to backend
7952 servers than the hash used by "balance rdp-cookie".
7953
7954 Example :
7955 listen tse-farm
7956 bind 0.0.0.0:3389
7957 # wait up to 5s for an RDP cookie in the request
7958 tcp-request inspect-delay 5s
7959 tcp-request content accept if RDP_COOKIE
7960 # apply RDP cookie persistence
7961 persist rdp-cookie
7962 # Persist based on the mstshash cookie
7963 # This is only useful makes sense if
7964 # balance rdp-cookie is not used
7965 stick-table type string size 204800
7966 stick on rdp_cookie(mstshash)
7967 server srv1 1.1.1.1:3389
7968 server srv1 1.1.1.2:3389
7969
7970 See also : "balance rdp-cookie", "persist rdp-cookie",
7971 "tcp-request" and the "req_rdp_cookie" ACL.
7972
Willy Tarreaub3eb2212011-07-01 16:16:17 +02007973 cookie(name)
7974 This extracts the last occurrence of the cookie name <name> on a
7975 "Cookie" header line from the request and uses the corresponding
7976 value to match. A typical use is to get multiple clients sharing
7977 a same profile use the same server. This can be similar to what
7978 "appsession" does with the "request-learn" statement, but with
7979 support for multi-peer synchronization and state keeping across
7980 restarts.
7981
7982 See also : "appsession"
7983
7984 set-cookie(name)
7985 This extracts the last occurrence of the cookie name <name> on a
7986 "Set-Cookie" header line from the response and uses the
7987 corresponding value to match. This can be comparable to what
7988 "appsession" does with default options, but with support for
7989 multi-peer synchronization and state keeping across restarts.
7990
7991 See also : "appsession"
7992
Simon Hormanab814e02011-06-24 14:50:20 +09007993
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007994The currently available list of transformations include :
7995
7996 lower Convert a string pattern to lower case. This can only be placed
7997 after a string pattern fetch function or after a conversion
7998 function returning a string type. The result is of type string.
7999
8000 upper Convert a string pattern to upper case. This can only be placed
8001 after a string pattern fetch function or after a conversion
8002 function returning a string type. The result is of type string.
8003
Willy Tarreaud31d6eb2010-01-26 18:01:41 +01008004 ipmask(mask) Apply a mask to an IPv4 address, and use the result for lookups
8005 and storage. This can be used to make all hosts within a
8006 certain mask to share the same table entries and as such use
8007 the same server. The mask can be passed in dotted form (eg:
8008 255.255.255.0) or in CIDR form (eg: 24).
8009
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008010
Willy Tarreauc57f0e22009-05-10 13:12:33 +020080118. Logging
8012----------
Willy Tarreau844e3c52008-01-11 16:28:18 +01008013
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008014One of HAProxy's strong points certainly lies is its precise logs. It probably
8015provides the finest level of information available for such a product, which is
8016very important for troubleshooting complex environments. Standard information
8017provided in logs include client ports, TCP/HTTP state timers, precise session
8018state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008019to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008020headers.
8021
8022In order to improve administrators reactivity, it offers a great transparency
8023about encountered problems, both internal and external, and it is possible to
8024send logs to different sources at the same time with different level filters :
8025
8026 - global process-level logs (system errors, start/stop, etc..)
8027 - per-instance system and internal errors (lack of resource, bugs, ...)
8028 - per-instance external troubles (servers up/down, max connections)
8029 - per-instance activity (client connections), either at the establishment or
8030 at the termination.
8031
8032The ability to distribute different levels of logs to different log servers
8033allow several production teams to interact and to fix their problems as soon
8034as possible. For example, the system team might monitor system-wide errors,
8035while the application team might be monitoring the up/down for their servers in
8036real time, and the security team might analyze the activity logs with one hour
8037delay.
8038
8039
Willy Tarreauc57f0e22009-05-10 13:12:33 +020080408.1. Log levels
8041---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008042
Simon Hormandf791f52011-05-29 15:01:10 +09008043TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008044source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +09008045HTTP request, HTTP return code, number of bytes transmitted, conditions
8046in which the session ended, and even exchanged cookies values. For example
8047track a particular user's problems. All messages may be sent to up to two
8048syslog servers. Check the "log" keyword in section 4.2 for more information
8049about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008050
8051
Willy Tarreauc57f0e22009-05-10 13:12:33 +020080528.2. Log formats
8053----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008054
Emeric Brun3a058f32009-06-30 18:26:00 +02008055HAProxy supports 4 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +09008056and will be detailed in the following sections. A few of them may vary
8057slightly with the configuration, due to indicators specific to certain
8058options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008059
8060 - the default format, which is very basic and very rarely used. It only
8061 provides very basic information about the incoming connection at the moment
8062 it is accepted : source IP:port, destination IP:port, and frontend-name.
8063 This mode will eventually disappear so it will not be described to great
8064 extents.
8065
8066 - the TCP format, which is more advanced. This format is enabled when "option
8067 tcplog" is set on the frontend. HAProxy will then usually wait for the
8068 connection to terminate before logging. This format provides much richer
8069 information, such as timers, connection counts, queue size, etc... This
8070 format is recommended for pure TCP proxies.
8071
8072 - the HTTP format, which is the most advanced for HTTP proxying. This format
8073 is enabled when "option httplog" is set on the frontend. It provides the
8074 same information as the TCP format with some HTTP-specific fields such as
8075 the request, the status code, and captures of headers and cookies. This
8076 format is recommended for HTTP proxies.
8077
Emeric Brun3a058f32009-06-30 18:26:00 +02008078 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
8079 fields arranged in the same order as the CLF format. In this mode, all
8080 timers, captures, flags, etc... appear one per field after the end of the
8081 common fields, in the same order they appear in the standard HTTP format.
8082
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008083Next sections will go deeper into details for each of these formats. Format
8084specification will be performed on a "field" basis. Unless stated otherwise, a
8085field is a portion of text delimited by any number of spaces. Since syslog
8086servers are susceptible of inserting fields at the beginning of a line, it is
8087always assumed that the first field is the one containing the process name and
8088identifier.
8089
8090Note : Since log lines may be quite long, the log examples in sections below
8091 might be broken into multiple lines. The example log lines will be
8092 prefixed with 3 closing angle brackets ('>>>') and each time a log is
8093 broken into multiple lines, each non-final line will end with a
8094 backslash ('\') and the next line will start indented by two characters.
8095
8096
Willy Tarreauc57f0e22009-05-10 13:12:33 +020080978.2.1. Default log format
8098-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008099
8100This format is used when no specific option is set. The log is emitted as soon
8101as the connection is accepted. One should note that this currently is the only
8102format which logs the request's destination IP and ports.
8103
8104 Example :
8105 listen www
8106 mode http
8107 log global
8108 server srv1 127.0.0.1:8000
8109
8110 >>> Feb 6 12:12:09 localhost \
8111 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
8112 (www/HTTP)
8113
8114 Field Format Extract from the example above
8115 1 process_name '[' pid ']:' haproxy[14385]:
8116 2 'Connect from' Connect from
8117 3 source_ip ':' source_port 10.0.1.2:33312
8118 4 'to' to
8119 5 destination_ip ':' destination_port 10.0.3.31:8012
8120 6 '(' frontend_name '/' mode ')' (www/HTTP)
8121
8122Detailed fields description :
8123 - "source_ip" is the IP address of the client which initiated the connection.
8124 - "source_port" is the TCP port of the client which initiated the connection.
8125 - "destination_ip" is the IP address the client connected to.
8126 - "destination_port" is the TCP port the client connected to.
8127 - "frontend_name" is the name of the frontend (or listener) which received
8128 and processed the connection.
8129 - "mode is the mode the frontend is operating (TCP or HTTP).
8130
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008131In case of a UNIX socket, the source and destination addresses are marked as
8132"unix:" and the ports reflect the internal ID of the socket which accepted the
8133connection (the same ID as reported in the stats).
8134
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008135It is advised not to use this deprecated format for newer installations as it
8136will eventually disappear.
8137
8138
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081398.2.2. TCP log format
8140---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008141
8142The TCP format is used when "option tcplog" is specified in the frontend, and
8143is the recommended format for pure TCP proxies. It provides a lot of precious
8144information for troubleshooting. Since this format includes timers and byte
8145counts, the log is normally emitted at the end of the session. It can be
8146emitted earlier if "option logasap" is specified, which makes sense in most
8147environments with long sessions such as remote terminals. Sessions which match
8148the "monitor" rules are never logged. It is also possible not to emit logs for
8149sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008150specifying "option dontlognull" in the frontend. Successful connections will
8151not be logged if "option dontlog-normal" is specified in the frontend. A few
8152fields may slightly vary depending on some configuration options, those are
8153marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008154
8155 Example :
8156 frontend fnt
8157 mode tcp
8158 option tcplog
8159 log global
8160 default_backend bck
8161
8162 backend bck
8163 server srv1 127.0.0.1:8000
8164
8165 >>> Feb 6 12:12:56 localhost \
8166 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
8167 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
8168
8169 Field Format Extract from the example above
8170 1 process_name '[' pid ']:' haproxy[14387]:
8171 2 client_ip ':' client_port 10.0.1.2:33313
8172 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
8173 4 frontend_name fnt
8174 5 backend_name '/' server_name bck/srv1
8175 6 Tw '/' Tc '/' Tt* 0/0/5007
8176 7 bytes_read* 212
8177 8 termination_state --
8178 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
8179 10 srv_queue '/' backend_queue 0/0
8180
8181Detailed fields description :
8182 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008183 connection to haproxy. If the connection was accepted on a UNIX socket
8184 instead, the IP address would be replaced with the word "unix". Note that
8185 when the connection is accepted on a socket configured with "accept-proxy"
8186 and the PROXY protocol is correctly used, then the logs will reflect the
8187 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008188
8189 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008190 If the connection was accepted on a UNIX socket instead, the port would be
8191 replaced with the ID of the accepting socket, which is also reported in the
8192 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008193
8194 - "accept_date" is the exact date when the connection was received by haproxy
8195 (which might be very slightly different from the date observed on the
8196 network if there was some queuing in the system's backlog). This is usually
8197 the same date which may appear in any upstream firewall's log.
8198
8199 - "frontend_name" is the name of the frontend (or listener) which received
8200 and processed the connection.
8201
8202 - "backend_name" is the name of the backend (or listener) which was selected
8203 to manage the connection to the server. This will be the same as the
8204 frontend if no switching rule has been applied, which is common for TCP
8205 applications.
8206
8207 - "server_name" is the name of the last server to which the connection was
8208 sent, which might differ from the first one if there were connection errors
8209 and a redispatch occurred. Note that this server belongs to the backend
8210 which processed the request. If the connection was aborted before reaching
8211 a server, "<NOSRV>" is indicated instead of a server name.
8212
8213 - "Tw" is the total time in milliseconds spent waiting in the various queues.
8214 It can be "-1" if the connection was aborted before reaching the queue.
8215 See "Timers" below for more details.
8216
8217 - "Tc" is the total time in milliseconds spent waiting for the connection to
8218 establish to the final server, including retries. It can be "-1" if the
8219 connection was aborted before a connection could be established. See
8220 "Timers" below for more details.
8221
8222 - "Tt" is the total time in milliseconds elapsed between the accept and the
8223 last close. It covers all possible processings. There is one exception, if
8224 "option logasap" was specified, then the time counting stops at the moment
8225 the log is emitted. In this case, a '+' sign is prepended before the value,
8226 indicating that the final one will be larger. See "Timers" below for more
8227 details.
8228
8229 - "bytes_read" is the total number of bytes transmitted from the server to
8230 the client when the log is emitted. If "option logasap" is specified, the
8231 this value will be prefixed with a '+' sign indicating that the final one
8232 may be larger. Please note that this value is a 64-bit counter, so log
8233 analysis tools must be able to handle it without overflowing.
8234
8235 - "termination_state" is the condition the session was in when the session
8236 ended. This indicates the session state, which side caused the end of
8237 session to happen, and for what reason (timeout, error, ...). The normal
8238 flags should be "--", indicating the session was closed by either end with
8239 no data remaining in buffers. See below "Session state at disconnection"
8240 for more details.
8241
8242 - "actconn" is the total number of concurrent connections on the process when
8243 the session was logged. It it useful to detect when some per-process system
8244 limits have been reached. For instance, if actconn is close to 512 when
8245 multiple connection errors occur, chances are high that the system limits
8246 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008247 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008248
8249 - "feconn" is the total number of concurrent connections on the frontend when
8250 the session was logged. It is useful to estimate the amount of resource
8251 required to sustain high loads, and to detect when the frontend's "maxconn"
8252 has been reached. Most often when this value increases by huge jumps, it is
8253 because there is congestion on the backend servers, but sometimes it can be
8254 caused by a denial of service attack.
8255
8256 - "beconn" is the total number of concurrent connections handled by the
8257 backend when the session was logged. It includes the total number of
8258 concurrent connections active on servers as well as the number of
8259 connections pending in queues. It is useful to estimate the amount of
8260 additional servers needed to support high loads for a given application.
8261 Most often when this value increases by huge jumps, it is because there is
8262 congestion on the backend servers, but sometimes it can be caused by a
8263 denial of service attack.
8264
8265 - "srv_conn" is the total number of concurrent connections still active on
8266 the server when the session was logged. It can never exceed the server's
8267 configured "maxconn" parameter. If this value is very often close or equal
8268 to the server's "maxconn", it means that traffic regulation is involved a
8269 lot, meaning that either the server's maxconn value is too low, or that
8270 there aren't enough servers to process the load with an optimal response
8271 time. When only one of the server's "srv_conn" is high, it usually means
8272 that this server has some trouble causing the connections to take longer to
8273 be processed than on other servers.
8274
8275 - "retries" is the number of connection retries experienced by this session
8276 when trying to connect to the server. It must normally be zero, unless a
8277 server is being stopped at the same moment the connection was attempted.
8278 Frequent retries generally indicate either a network problem between
8279 haproxy and the server, or a misconfigured system backlog on the server
8280 preventing new connections from being queued. This field may optionally be
8281 prefixed with a '+' sign, indicating that the session has experienced a
8282 redispatch after the maximal retry count has been reached on the initial
8283 server. In this case, the server name appearing in the log is the one the
8284 connection was redispatched to, and not the first one, though both may
8285 sometimes be the same in case of hashing for instance. So as a general rule
8286 of thumb, when a '+' is present in front of the retry count, this count
8287 should not be attributed to the logged server.
8288
8289 - "srv_queue" is the total number of requests which were processed before
8290 this one in the server queue. It is zero when the request has not gone
8291 through the server queue. It makes it possible to estimate the approximate
8292 server's response time by dividing the time spent in queue by the number of
8293 requests in the queue. It is worth noting that if a session experiences a
8294 redispatch and passes through two server queues, their positions will be
8295 cumulated. A request should not pass through both the server queue and the
8296 backend queue unless a redispatch occurs.
8297
8298 - "backend_queue" is the total number of requests which were processed before
8299 this one in the backend's global queue. It is zero when the request has not
8300 gone through the global queue. It makes it possible to estimate the average
8301 queue length, which easily translates into a number of missing servers when
8302 divided by a server's "maxconn" parameter. It is worth noting that if a
8303 session experiences a redispatch, it may pass twice in the backend's queue,
8304 and then both positions will be cumulated. A request should not pass
8305 through both the server queue and the backend queue unless a redispatch
8306 occurs.
8307
8308
Willy Tarreauc57f0e22009-05-10 13:12:33 +020083098.2.3. HTTP log format
8310----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008311
8312The HTTP format is the most complete and the best suited for HTTP proxies. It
8313is enabled by when "option httplog" is specified in the frontend. It provides
8314the same level of information as the TCP format with additional features which
8315are specific to the HTTP protocol. Just like the TCP format, the log is usually
8316emitted at the end of the session, unless "option logasap" is specified, which
8317generally only makes sense for download sites. A session which matches the
8318"monitor" rules will never logged. It is also possible not to log sessions for
8319which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008320frontend. Successful connections will not be logged if "option dontlog-normal"
8321is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008322
8323Most fields are shared with the TCP log, some being different. A few fields may
8324slightly vary depending on some configuration options. Those ones are marked
8325with a star ('*') after the field name below.
8326
8327 Example :
8328 frontend http-in
8329 mode http
8330 option httplog
8331 log global
8332 default_backend bck
8333
8334 backend static
8335 server srv1 127.0.0.1:8000
8336
8337 >>> Feb 6 12:14:14 localhost \
8338 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
8339 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 +01008340 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008341
8342 Field Format Extract from the example above
8343 1 process_name '[' pid ']:' haproxy[14389]:
8344 2 client_ip ':' client_port 10.0.1.2:33317
8345 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
8346 4 frontend_name http-in
8347 5 backend_name '/' server_name static/srv1
8348 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
8349 7 status_code 200
8350 8 bytes_read* 2750
8351 9 captured_request_cookie -
8352 10 captured_response_cookie -
8353 11 termination_state ----
8354 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
8355 13 srv_queue '/' backend_queue 0/0
8356 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
8357 15 '{' captured_response_headers* '}' {}
8358 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +01008359
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008360
8361Detailed fields description :
8362 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008363 connection to haproxy. If the connection was accepted on a UNIX socket
8364 instead, the IP address would be replaced with the word "unix". Note that
8365 when the connection is accepted on a socket configured with "accept-proxy"
8366 and the PROXY protocol is correctly used, then the logs will reflect the
8367 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008368
8369 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008370 If the connection was accepted on a UNIX socket instead, the port would be
8371 replaced with the ID of the accepting socket, which is also reported in the
8372 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008373
8374 - "accept_date" is the exact date when the TCP connection was received by
8375 haproxy (which might be very slightly different from the date observed on
8376 the network if there was some queuing in the system's backlog). This is
8377 usually the same date which may appear in any upstream firewall's log. This
8378 does not depend on the fact that the client has sent the request or not.
8379
8380 - "frontend_name" is the name of the frontend (or listener) which received
8381 and processed the connection.
8382
8383 - "backend_name" is the name of the backend (or listener) which was selected
8384 to manage the connection to the server. This will be the same as the
8385 frontend if no switching rule has been applied.
8386
8387 - "server_name" is the name of the last server to which the connection was
8388 sent, which might differ from the first one if there were connection errors
8389 and a redispatch occurred. Note that this server belongs to the backend
8390 which processed the request. If the request was aborted before reaching a
8391 server, "<NOSRV>" is indicated instead of a server name. If the request was
8392 intercepted by the stats subsystem, "<STATS>" is indicated instead.
8393
8394 - "Tq" is the total time in milliseconds spent waiting for the client to send
8395 a full HTTP request, not counting data. It can be "-1" if the connection
8396 was aborted before a complete request could be received. It should always
8397 be very small because a request generally fits in one single packet. Large
8398 times here generally indicate network trouble between the client and
8399 haproxy. See "Timers" below for more details.
8400
8401 - "Tw" is the total time in milliseconds spent waiting in the various queues.
8402 It can be "-1" if the connection was aborted before reaching the queue.
8403 See "Timers" below for more details.
8404
8405 - "Tc" is the total time in milliseconds spent waiting for the connection to
8406 establish to the final server, including retries. It can be "-1" if the
8407 request was aborted before a connection could be established. See "Timers"
8408 below for more details.
8409
8410 - "Tr" is the total time in milliseconds spent waiting for the server to send
8411 a full HTTP response, not counting data. It can be "-1" if the request was
8412 aborted before a complete response could be received. It generally matches
8413 the server's processing time for the request, though it may be altered by
8414 the amount of data sent by the client to the server. Large times here on
8415 "GET" requests generally indicate an overloaded server. See "Timers" below
8416 for more details.
8417
8418 - "Tt" is the total time in milliseconds elapsed between the accept and the
8419 last close. It covers all possible processings. There is one exception, if
8420 "option logasap" was specified, then the time counting stops at the moment
8421 the log is emitted. In this case, a '+' sign is prepended before the value,
8422 indicating that the final one will be larger. See "Timers" below for more
8423 details.
8424
8425 - "status_code" is the HTTP status code returned to the client. This status
8426 is generally set by the server, but it might also be set by haproxy when
8427 the server cannot be reached or when its response is blocked by haproxy.
8428
8429 - "bytes_read" is the total number of bytes transmitted to the client when
8430 the log is emitted. This does include HTTP headers. If "option logasap" is
8431 specified, the this value will be prefixed with a '+' sign indicating that
8432 the final one may be larger. Please note that this value is a 64-bit
8433 counter, so log analysis tools must be able to handle it without
8434 overflowing.
8435
8436 - "captured_request_cookie" is an optional "name=value" entry indicating that
8437 the client had this cookie in the request. The cookie name and its maximum
8438 length are defined by the "capture cookie" statement in the frontend
8439 configuration. The field is a single dash ('-') when the option is not
8440 set. Only one cookie may be captured, it is generally used to track session
8441 ID exchanges between a client and a server to detect session crossing
8442 between clients due to application bugs. For more details, please consult
8443 the section "Capturing HTTP headers and cookies" below.
8444
8445 - "captured_response_cookie" is an optional "name=value" entry indicating
8446 that the server has returned a cookie with its response. The cookie name
8447 and its maximum length are defined by the "capture cookie" statement in the
8448 frontend configuration. The field is a single dash ('-') when the option is
8449 not set. Only one cookie may be captured, it is generally used to track
8450 session ID exchanges between a client and a server to detect session
8451 crossing between clients due to application bugs. For more details, please
8452 consult the section "Capturing HTTP headers and cookies" below.
8453
8454 - "termination_state" is the condition the session was in when the session
8455 ended. This indicates the session state, which side caused the end of
8456 session to happen, for what reason (timeout, error, ...), just like in TCP
8457 logs, and information about persistence operations on cookies in the last
8458 two characters. The normal flags should begin with "--", indicating the
8459 session was closed by either end with no data remaining in buffers. See
8460 below "Session state at disconnection" for more details.
8461
8462 - "actconn" is the total number of concurrent connections on the process when
8463 the session was logged. It it useful to detect when some per-process system
8464 limits have been reached. For instance, if actconn is close to 512 or 1024
8465 when multiple connection errors occur, chances are high that the system
8466 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008467 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008468 system.
8469
8470 - "feconn" is the total number of concurrent connections on the frontend when
8471 the session was logged. It is useful to estimate the amount of resource
8472 required to sustain high loads, and to detect when the frontend's "maxconn"
8473 has been reached. Most often when this value increases by huge jumps, it is
8474 because there is congestion on the backend servers, but sometimes it can be
8475 caused by a denial of service attack.
8476
8477 - "beconn" is the total number of concurrent connections handled by the
8478 backend when the session was logged. It includes the total number of
8479 concurrent connections active on servers as well as the number of
8480 connections pending in queues. It is useful to estimate the amount of
8481 additional servers needed to support high loads for a given application.
8482 Most often when this value increases by huge jumps, it is because there is
8483 congestion on the backend servers, but sometimes it can be caused by a
8484 denial of service attack.
8485
8486 - "srv_conn" is the total number of concurrent connections still active on
8487 the server when the session was logged. It can never exceed the server's
8488 configured "maxconn" parameter. If this value is very often close or equal
8489 to the server's "maxconn", it means that traffic regulation is involved a
8490 lot, meaning that either the server's maxconn value is too low, or that
8491 there aren't enough servers to process the load with an optimal response
8492 time. When only one of the server's "srv_conn" is high, it usually means
8493 that this server has some trouble causing the requests to take longer to be
8494 processed than on other servers.
8495
8496 - "retries" is the number of connection retries experienced by this session
8497 when trying to connect to the server. It must normally be zero, unless a
8498 server is being stopped at the same moment the connection was attempted.
8499 Frequent retries generally indicate either a network problem between
8500 haproxy and the server, or a misconfigured system backlog on the server
8501 preventing new connections from being queued. This field may optionally be
8502 prefixed with a '+' sign, indicating that the session has experienced a
8503 redispatch after the maximal retry count has been reached on the initial
8504 server. In this case, the server name appearing in the log is the one the
8505 connection was redispatched to, and not the first one, though both may
8506 sometimes be the same in case of hashing for instance. So as a general rule
8507 of thumb, when a '+' is present in front of the retry count, this count
8508 should not be attributed to the logged server.
8509
8510 - "srv_queue" is the total number of requests which were processed before
8511 this one in the server queue. It is zero when the request has not gone
8512 through the server queue. It makes it possible to estimate the approximate
8513 server's response time by dividing the time spent in queue by the number of
8514 requests in the queue. It is worth noting that if a session experiences a
8515 redispatch and passes through two server queues, their positions will be
8516 cumulated. A request should not pass through both the server queue and the
8517 backend queue unless a redispatch occurs.
8518
8519 - "backend_queue" is the total number of requests which were processed before
8520 this one in the backend's global queue. It is zero when the request has not
8521 gone through the global queue. It makes it possible to estimate the average
8522 queue length, which easily translates into a number of missing servers when
8523 divided by a server's "maxconn" parameter. It is worth noting that if a
8524 session experiences a redispatch, it may pass twice in the backend's queue,
8525 and then both positions will be cumulated. A request should not pass
8526 through both the server queue and the backend queue unless a redispatch
8527 occurs.
8528
8529 - "captured_request_headers" is a list of headers captured in the request due
8530 to the presence of the "capture request header" statement in the frontend.
8531 Multiple headers can be captured, they will be delimited by a vertical bar
8532 ('|'). When no capture is enabled, the braces do not appear, causing a
8533 shift of remaining fields. It is important to note that this field may
8534 contain spaces, and that using it requires a smarter log parser than when
8535 it's not used. Please consult the section "Capturing HTTP headers and
8536 cookies" below for more details.
8537
8538 - "captured_response_headers" is a list of headers captured in the response
8539 due to the presence of the "capture response header" statement in the
8540 frontend. Multiple headers can be captured, they will be delimited by a
8541 vertical bar ('|'). When no capture is enabled, the braces do not appear,
8542 causing a shift of remaining fields. It is important to note that this
8543 field may contain spaces, and that using it requires a smarter log parser
8544 than when it's not used. Please consult the section "Capturing HTTP headers
8545 and cookies" below for more details.
8546
8547 - "http_request" is the complete HTTP request line, including the method,
8548 request and HTTP version string. Non-printable characters are encoded (see
8549 below the section "Non-printable characters"). This is always the last
8550 field, and it is always delimited by quotes and is the only one which can
8551 contain quotes. If new fields are added to the log format, they will be
8552 added before this field. This field might be truncated if the request is
8553 huge and does not fit in the standard syslog buffer (1024 characters). This
8554 is the reason why this field must always remain the last one.
8555
8556
Willy Tarreauc57f0e22009-05-10 13:12:33 +020085578.3. Advanced logging options
8558-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008559
8560Some advanced logging options are often looked for but are not easy to find out
8561just by looking at the various options. Here is an entry point for the few
8562options which can enable better logging. Please refer to the keywords reference
8563for more information about their usage.
8564
8565
Willy Tarreauc57f0e22009-05-10 13:12:33 +020085668.3.1. Disabling logging of external tests
8567------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008568
8569It is quite common to have some monitoring tools perform health checks on
8570haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
8571commercial load-balancer, and sometimes it will simply be a more complete
8572monitoring system such as Nagios. When the tests are very frequent, users often
8573ask how to disable logging for those checks. There are three possibilities :
8574
8575 - if connections come from everywhere and are just TCP probes, it is often
8576 desired to simply disable logging of connections without data exchange, by
8577 setting "option dontlognull" in the frontend. It also disables logging of
8578 port scans, which may or may not be desired.
8579
8580 - if the connection come from a known source network, use "monitor-net" to
8581 declare this network as monitoring only. Any host in this network will then
8582 only be able to perform health checks, and their requests will not be
8583 logged. This is generally appropriate to designate a list of equipments
8584 such as other load-balancers.
8585
8586 - if the tests are performed on a known URI, use "monitor-uri" to declare
8587 this URI as dedicated to monitoring. Any host sending this request will
8588 only get the result of a health-check, and the request will not be logged.
8589
8590
Willy Tarreauc57f0e22009-05-10 13:12:33 +020085918.3.2. Logging before waiting for the session to terminate
8592----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008593
8594The problem with logging at end of connection is that you have no clue about
8595what is happening during very long sessions, such as remote terminal sessions
8596or large file downloads. This problem can be worked around by specifying
8597"option logasap" in the frontend. Haproxy will then log as soon as possible,
8598just before data transfer begins. This means that in case of TCP, it will still
8599log the connection status to the server, and in case of HTTP, it will log just
8600after processing the server headers. In this case, the number of bytes reported
8601is the number of header bytes sent to the client. In order to avoid confusion
8602with normal logs, the total time field and the number of bytes are prefixed
8603with a '+' sign which means that real numbers are certainly larger.
8604
8605
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086068.3.3. Raising log level upon errors
8607------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008608
8609Sometimes it is more convenient to separate normal traffic from errors logs,
8610for instance in order to ease error monitoring from log files. When the option
8611"log-separate-errors" is used, connections which experience errors, timeouts,
8612retries, redispatches or HTTP status codes 5xx will see their syslog level
8613raised from "info" to "err". This will help a syslog daemon store the log in
8614a separate file. It is very important to keep the errors in the normal traffic
8615file too, so that log ordering is not altered. You should also be careful if
8616you already have configured your syslog daemon to store all logs higher than
8617"notice" in an "admin" file, because the "err" level is higher than "notice".
8618
8619
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086208.3.4. Disabling logging of successful connections
8621--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008622
8623Although this may sound strange at first, some large sites have to deal with
8624multiple thousands of logs per second and are experiencing difficulties keeping
8625them intact for a long time or detecting errors within them. If the option
8626"dontlog-normal" is set on the frontend, all normal connections will not be
8627logged. In this regard, a normal connection is defined as one without any
8628error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
8629and a response with a status 5xx is not considered normal and will be logged
8630too. Of course, doing is is really discouraged as it will remove most of the
8631useful information from the logs. Do this only if you have no other
8632alternative.
8633
8634
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086358.4. Timing events
8636------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008637
8638Timers provide a great help in troubleshooting network problems. All values are
8639reported in milliseconds (ms). These timers should be used in conjunction with
8640the session termination flags. In TCP mode with "option tcplog" set on the
8641frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
8642mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
8643
8644 - Tq: total time to get the client request (HTTP mode only). It's the time
8645 elapsed between the moment the client connection was accepted and the
8646 moment the proxy received the last HTTP header. The value "-1" indicates
8647 that the end of headers (empty line) has never been seen. This happens when
8648 the client closes prematurely or times out.
8649
8650 - Tw: total time spent in the queues waiting for a connection slot. It
8651 accounts for backend queue as well as the server queues, and depends on the
8652 queue size, and the time needed for the server to complete previous
8653 requests. The value "-1" means that the request was killed before reaching
8654 the queue, which is generally what happens with invalid or denied requests.
8655
8656 - Tc: total time to establish the TCP connection to the server. It's the time
8657 elapsed between the moment the proxy sent the connection request, and the
8658 moment it was acknowledged by the server, or between the TCP SYN packet and
8659 the matching SYN/ACK packet in return. The value "-1" means that the
8660 connection never established.
8661
8662 - Tr: server response time (HTTP mode only). It's the time elapsed between
8663 the moment the TCP connection was established to the server and the moment
8664 the server sent its complete response headers. It purely shows its request
8665 processing time, without the network overhead due to the data transmission.
8666 It is worth noting that when the client has data to send to the server, for
8667 instance during a POST request, the time already runs, and this can distort
8668 apparent response time. For this reason, it's generally wise not to trust
8669 too much this field for POST requests initiated from clients behind an
8670 untrusted network. A value of "-1" here means that the last the response
8671 header (empty line) was never seen, most likely because the server timeout
8672 stroke before the server managed to process the request.
8673
8674 - Tt: total session duration time, between the moment the proxy accepted it
8675 and the moment both ends were closed. The exception is when the "logasap"
8676 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
8677 prefixed with a '+' sign. From this field, we can deduce "Td", the data
8678 transmission time, by substracting other timers when valid :
8679
8680 Td = Tt - (Tq + Tw + Tc + Tr)
8681
8682 Timers with "-1" values have to be excluded from this equation. In TCP
8683 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
8684 negative.
8685
8686These timers provide precious indications on trouble causes. Since the TCP
8687protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
8688that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008689due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008690close to a timeout value specified in the configuration, it often means that a
8691session has been aborted on timeout.
8692
8693Most common cases :
8694
8695 - If "Tq" is close to 3000, a packet has probably been lost between the
8696 client and the proxy. This is very rare on local networks but might happen
8697 when clients are on far remote networks and send large requests. It may
8698 happen that values larger than usual appear here without any network cause.
8699 Sometimes, during an attack or just after a resource starvation has ended,
8700 haproxy may accept thousands of connections in a few milliseconds. The time
8701 spent accepting these connections will inevitably slightly delay processing
8702 of other connections, and it can happen that request times in the order of
8703 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +02008704 connections have been accepted at once. Setting "option http-server-close"
8705 may display larger request times since "Tq" also measures the time spent
8706 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008707
8708 - If "Tc" is close to 3000, a packet has probably been lost between the
8709 server and the proxy during the server connection phase. This value should
8710 always be very low, such as 1 ms on local networks and less than a few tens
8711 of ms on remote networks.
8712
Willy Tarreau55165fe2009-05-10 12:02:55 +02008713 - If "Tr" is nearly always lower than 3000 except some rare values which seem
8714 to be the average majored by 3000, there are probably some packets lost
8715 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008716
8717 - If "Tt" is large even for small byte counts, it generally is because
8718 neither the client nor the server decides to close the connection, for
8719 instance because both have agreed on a keep-alive connection mode. In order
8720 to solve this issue, it will be needed to specify "option httpclose" on
8721 either the frontend or the backend. If the problem persists, it means that
8722 the server ignores the "close" connection mode and expects the client to
8723 close. Then it will be required to use "option forceclose". Having the
8724 smallest possible 'Tt' is important when connection regulation is used with
8725 the "maxconn" option on the servers, since no new connection will be sent
8726 to the server until another one is released.
8727
8728Other noticeable HTTP log cases ('xx' means any value to be ignored) :
8729
8730 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
8731 was emitted before the data phase. All the timers are valid
8732 except "Tt" which is shorter than reality.
8733
8734 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
8735 or it aborted too early. Check the session termination flags
8736 then "timeout http-request" and "timeout client" settings.
8737
8738 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
8739 servers were out of order, because the request was invalid
8740 or forbidden by ACL rules. Check the session termination
8741 flags.
8742
8743 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
8744 actively refused it or it timed out after Tt-(Tq+Tw) ms.
8745 Check the session termination flags, then check the
8746 "timeout connect" setting. Note that the tarpit action might
8747 return similar-looking patterns, with "Tw" equal to the time
8748 the client connection was maintained open.
8749
8750 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
8751 a complete response in time, or it closed its connexion
8752 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
8753 termination flags, then check the "timeout server" setting.
8754
8755
Willy Tarreauc57f0e22009-05-10 13:12:33 +020087568.5. Session state at disconnection
8757-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008758
8759TCP and HTTP logs provide a session termination indicator in the
8760"termination_state" field, just before the number of active connections. It is
87612-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
8762each of which has a special meaning :
8763
8764 - On the first character, a code reporting the first event which caused the
8765 session to terminate :
8766
8767 C : the TCP session was unexpectedly aborted by the client.
8768
8769 S : the TCP session was unexpectedly aborted by the server, or the
8770 server explicitly refused it.
8771
8772 P : the session was prematurely aborted by the proxy, because of a
8773 connection limit enforcement, because a DENY filter was matched,
8774 because of a security check which detected and blocked a dangerous
8775 error in server response which might have caused information leak
8776 (eg: cacheable cookie), or because the response was processed by
8777 the proxy (redirect, stats, etc...).
8778
8779 R : a resource on the proxy has been exhausted (memory, sockets, source
8780 ports, ...). Usually, this appears during the connection phase, and
8781 system logs should contain a copy of the precise error. If this
8782 happens, it must be considered as a very serious anomaly which
8783 should be fixed as soon as possible by any means.
8784
8785 I : an internal error was identified by the proxy during a self-check.
8786 This should NEVER happen, and you are encouraged to report any log
8787 containing this, because this would almost certainly be a bug. It
8788 would be wise to preventively restart the process after such an
8789 event too, in case it would be caused by memory corruption.
8790
Simon Horman752dc4a2011-06-21 14:34:59 +09008791 D : the session was killed by haproxy because the server was detected
8792 as down and was configured to kill all connections when going down.
8793
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008794 c : the client-side timeout expired while waiting for the client to
8795 send or receive data.
8796
8797 s : the server-side timeout expired while waiting for the server to
8798 send or receive data.
8799
8800 - : normal session completion, both the client and the server closed
8801 with nothing left in the buffers.
8802
8803 - on the second character, the TCP or HTTP session state when it was closed :
8804
Willy Tarreauf7b30a92010-12-06 22:59:17 +01008805 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008806 (HTTP mode only). Nothing was sent to any server.
8807
8808 Q : the proxy was waiting in the QUEUE for a connection slot. This can
8809 only happen when servers have a 'maxconn' parameter set. It can
8810 also happen in the global queue after a redispatch consecutive to
8811 a failed attempt to connect to a dying server. If no redispatch is
8812 reported, then no connection attempt was made to any server.
8813
8814 C : the proxy was waiting for the CONNECTION to establish on the
8815 server. The server might at most have noticed a connection attempt.
8816
8817 H : the proxy was waiting for complete, valid response HEADERS from the
8818 server (HTTP only).
8819
8820 D : the session was in the DATA phase.
8821
8822 L : the proxy was still transmitting LAST data to the client while the
8823 server had already finished. This one is very rare as it can only
8824 happen when the client dies while receiving the last packets.
8825
8826 T : the request was tarpitted. It has been held open with the client
8827 during the whole "timeout tarpit" duration or until the client
8828 closed, both of which will be reported in the "Tw" timer.
8829
8830 - : normal session completion after end of data transfer.
8831
8832 - the third character tells whether the persistence cookie was provided by
8833 the client (only in HTTP mode) :
8834
8835 N : the client provided NO cookie. This is usually the case for new
8836 visitors, so counting the number of occurrences of this flag in the
8837 logs generally indicate a valid trend for the site frequentation.
8838
8839 I : the client provided an INVALID cookie matching no known server.
8840 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02008841 cookies between HTTP/HTTPS sites, persistence conditionally
8842 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008843
8844 D : the client provided a cookie designating a server which was DOWN,
8845 so either "option persist" was used and the client was sent to
8846 this server, or it was not set and the client was redispatched to
8847 another server.
8848
Willy Tarreau996a92c2010-10-13 19:30:47 +02008849 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008850 server.
8851
Willy Tarreau996a92c2010-10-13 19:30:47 +02008852 E : the client provided a valid cookie, but with a last date which was
8853 older than what is allowed by the "maxidle" cookie parameter, so
8854 the cookie is consider EXPIRED and is ignored. The request will be
8855 redispatched just as if there was no cookie.
8856
8857 O : the client provided a valid cookie, but with a first date which was
8858 older than what is allowed by the "maxlife" cookie parameter, so
8859 the cookie is consider too OLD and is ignored. The request will be
8860 redispatched just as if there was no cookie.
8861
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008862 - : does not apply (no cookie set in configuration).
8863
8864 - the last character reports what operations were performed on the persistence
8865 cookie returned by the server (only in HTTP mode) :
8866
8867 N : NO cookie was provided by the server, and none was inserted either.
8868
8869 I : no cookie was provided by the server, and the proxy INSERTED one.
8870 Note that in "cookie insert" mode, if the server provides a cookie,
8871 it will still be overwritten and reported as "I" here.
8872
Willy Tarreau996a92c2010-10-13 19:30:47 +02008873 U : the proxy UPDATED the last date in the cookie that was presented by
8874 the client. This can only happen in insert mode with "maxidle". It
8875 happens everytime there is activity at a different date than the
8876 date indicated in the cookie. If any other change happens, such as
8877 a redispatch, then the cookie will be marked as inserted instead.
8878
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008879 P : a cookie was PROVIDED by the server and transmitted as-is.
8880
8881 R : the cookie provided by the server was REWRITTEN by the proxy, which
8882 happens in "cookie rewrite" or "cookie prefix" modes.
8883
8884 D : the cookie provided by the server was DELETED by the proxy.
8885
8886 - : does not apply (no cookie set in configuration).
8887
Willy Tarreau996a92c2010-10-13 19:30:47 +02008888The combination of the two first flags gives a lot of information about what
8889was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008890helpful to detect server saturation, network troubles, local system resource
8891starvation, attacks, etc...
8892
8893The most common termination flags combinations are indicated below. They are
8894alphabetically sorted, with the lowercase set just after the upper case for
8895easier finding and understanding.
8896
8897 Flags Reason
8898
8899 -- Normal termination.
8900
8901 CC The client aborted before the connection could be established to the
8902 server. This can happen when haproxy tries to connect to a recently
8903 dead (or unchecked) server, and the client aborts while haproxy is
8904 waiting for the server to respond or for "timeout connect" to expire.
8905
8906 CD The client unexpectedly aborted during data transfer. This can be
8907 caused by a browser crash, by an intermediate equipment between the
8908 client and haproxy which decided to actively break the connection,
8909 by network routing issues between the client and haproxy, or by a
8910 keep-alive session between the server and the client terminated first
8911 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +01008912
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008913 cD The client did not send nor acknowledge any data for as long as the
8914 "timeout client" delay. This is often caused by network failures on
8915 the client side, or the client simply leaving the net uncleanly.
8916
8917 CH The client aborted while waiting for the server to start responding.
8918 It might be the server taking too long to respond or the client
8919 clicking the 'Stop' button too fast.
8920
8921 cH The "timeout client" stroke while waiting for client data during a
8922 POST request. This is sometimes caused by too large TCP MSS values
8923 for PPPoE networks which cannot transport full-sized packets. It can
8924 also happen when client timeout is smaller than server timeout and
8925 the server takes too long to respond.
8926
8927 CQ The client aborted while its session was queued, waiting for a server
8928 with enough empty slots to accept it. It might be that either all the
8929 servers were saturated or that the assigned server was taking too
8930 long a time to respond.
8931
8932 CR The client aborted before sending a full HTTP request. Most likely
8933 the request was typed by hand using a telnet client, and aborted
8934 too early. The HTTP status code is likely a 400 here. Sometimes this
8935 might also be caused by an IDS killing the connection between haproxy
8936 and the client.
8937
8938 cR The "timeout http-request" stroke before the client sent a full HTTP
8939 request. This is sometimes caused by too large TCP MSS values on the
8940 client side for PPPoE networks which cannot transport full-sized
8941 packets, or by clients sending requests by hand and not typing fast
8942 enough, or forgetting to enter the empty line at the end of the
8943 request. The HTTP status code is likely a 408 here.
8944
8945 CT The client aborted while its session was tarpitted. It is important to
8946 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +02008947 wrong tarpit rules have been written. If a lot of them happen, it
8948 might make sense to lower the "timeout tarpit" value to something
8949 closer to the average reported "Tw" timer, in order not to consume
8950 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008951
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008952 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008953 the TCP connection (the proxy received a TCP RST or an ICMP message
8954 in return). Under some circumstances, it can also be the network
8955 stack telling the proxy that the server is unreachable (eg: no route,
8956 or no ARP response on local network). When this happens in HTTP mode,
8957 the status code is likely a 502 or 503 here.
8958
8959 sC The "timeout connect" stroke before a connection to the server could
8960 complete. When this happens in HTTP mode, the status code is likely a
8961 503 or 504 here.
8962
8963 SD The connection to the server died with an error during the data
8964 transfer. This usually means that haproxy has received an RST from
8965 the server or an ICMP message from an intermediate equipment while
8966 exchanging data with the server. This can be caused by a server crash
8967 or by a network issue on an intermediate equipment.
8968
8969 sD The server did not send nor acknowledge any data for as long as the
8970 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008971 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008972 load-balancers, ...), as well as keep-alive sessions maintained
8973 between the client and the server expiring first on haproxy.
8974
8975 SH The server aborted before sending its full HTTP response headers, or
8976 it crashed while processing the request. Since a server aborting at
8977 this moment is very rare, it would be wise to inspect its logs to
8978 control whether it crashed and why. The logged request may indicate a
8979 small set of faulty requests, demonstrating bugs in the application.
8980 Sometimes this might also be caused by an IDS killing the connection
8981 between haproxy and the server.
8982
8983 sH The "timeout server" stroke before the server could return its
8984 response headers. This is the most common anomaly, indicating too
8985 long transactions, probably caused by server or database saturation.
8986 The immediate workaround consists in increasing the "timeout server"
8987 setting, but it is important to keep in mind that the user experience
8988 will suffer from these long response times. The only long term
8989 solution is to fix the application.
8990
8991 sQ The session spent too much time in queue and has been expired. See
8992 the "timeout queue" and "timeout connect" settings to find out how to
8993 fix this if it happens too often. If it often happens massively in
8994 short periods, it may indicate general problems on the affected
8995 servers due to I/O or database congestion, or saturation caused by
8996 external attacks.
8997
8998 PC The proxy refused to establish a connection to the server because the
8999 process' socket limit has been reached while attempting to connect.
9000 The global "maxconn" parameter may be increased in the configuration
9001 so that it does not happen anymore. This status is very rare and
9002 might happen when the global "ulimit-n" parameter is forced by hand.
9003
Willy Tarreaued2fd2d2010-12-29 11:23:27 +01009004 PD The proxy blocked an incorrectly formatted chunked encoded message in
9005 a request or a response, after the server has emitted its headers. In
9006 most cases, this will indicate an invalid message from the server to
9007 the client.
9008
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009009 PH The proxy blocked the server's response, because it was invalid,
9010 incomplete, dangerous (cache control), or matched a security filter.
9011 In any case, an HTTP 502 error is sent to the client. One possible
9012 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +01009013 containing unauthorized characters. It is also possible but quite
9014 rare, that the proxy blocked a chunked-encoding request from the
9015 client due to an invalid syntax, before the server responded. In this
9016 case, an HTTP 400 error is sent to the client and reported in the
9017 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009018
9019 PR The proxy blocked the client's HTTP request, either because of an
9020 invalid HTTP syntax, in which case it returned an HTTP 400 error to
9021 the client, or because a deny filter matched, in which case it
9022 returned an HTTP 403 error.
9023
9024 PT The proxy blocked the client's request and has tarpitted its
9025 connection before returning it a 500 server error. Nothing was sent
9026 to the server. The connection was maintained open for as long as
9027 reported by the "Tw" timer field.
9028
9029 RC A local resource has been exhausted (memory, sockets, source ports)
9030 preventing the connection to the server from establishing. The error
9031 logs will tell precisely what was missing. This is very rare and can
9032 only be solved by proper system tuning.
9033
Willy Tarreau996a92c2010-10-13 19:30:47 +02009034The combination of the two last flags gives a lot of information about how
9035persistence was handled by the client, the server and by haproxy. This is very
9036important to troubleshoot disconnections, when users complain they have to
9037re-authenticate. The commonly encountered flags are :
9038
9039 -- Persistence cookie is not enabled.
9040
9041 NN No cookie was provided by the client, none was inserted in the
9042 response. For instance, this can be in insert mode with "postonly"
9043 set on a GET request.
9044
9045 II A cookie designating an invalid server was provided by the client,
9046 a valid one was inserted in the response. This typically happens when
9047 a "server" entry is removed from the configuraton, since its cookie
9048 value can be presented by a client when no other server knows it.
9049
9050 NI No cookie was provided by the client, one was inserted in the
9051 response. This typically happens for first requests from every user
9052 in "insert" mode, which makes it an easy way to count real users.
9053
9054 VN A cookie was provided by the client, none was inserted in the
9055 response. This happens for most responses for which the client has
9056 already got a cookie.
9057
9058 VU A cookie was provided by the client, with a last visit date which is
9059 not completely up-to-date, so an updated cookie was provided in
9060 response. This can also happen if there was no date at all, or if
9061 there was a date but the "maxidle" parameter was not set, so that the
9062 cookie can be switched to unlimited time.
9063
9064 EI A cookie was provided by the client, with a last visit date which is
9065 too old for the "maxidle" parameter, so the cookie was ignored and a
9066 new cookie was inserted in the response.
9067
9068 OI A cookie was provided by the client, with a first visit date which is
9069 too old for the "maxlife" parameter, so the cookie was ignored and a
9070 new cookie was inserted in the response.
9071
9072 DI The server designated by the cookie was down, a new server was
9073 selected and a new cookie was emitted in the response.
9074
9075 VI The server designated by the cookie was not marked dead but could not
9076 be reached. A redispatch happened and selected another one, which was
9077 then advertised in the response.
9078
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009079
Willy Tarreauc57f0e22009-05-10 13:12:33 +020090808.6. Non-printable characters
9081-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009082
9083In order not to cause trouble to log analysis tools or terminals during log
9084consulting, non-printable characters are not sent as-is into log files, but are
9085converted to the two-digits hexadecimal representation of their ASCII code,
9086prefixed by the character '#'. The only characters that can be logged without
9087being escaped are comprised between 32 and 126 (inclusive). Obviously, the
9088escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
9089is the same for the character '"' which becomes "#22", as well as '{', '|' and
9090'}' when logging headers.
9091
9092Note that the space character (' ') is not encoded in headers, which can cause
9093issues for tools relying on space count to locate fields. A typical header
9094containing spaces is "User-Agent".
9095
9096Last, it has been observed that some syslog daemons such as syslog-ng escape
9097the quote ('"') with a backslash ('\'). The reverse operation can safely be
9098performed since no quote may appear anywhere else in the logs.
9099
9100
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091018.7. Capturing HTTP cookies
9102---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009103
9104Cookie capture simplifies the tracking a complete user session. This can be
9105achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009106section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009107cookie will simultaneously be checked in the request ("Cookie:" header) and in
9108the response ("Set-Cookie:" header). The respective values will be reported in
9109the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009110locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009111not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
9112user switches to a new session for example, because the server will reassign it
9113a new cookie. It is also possible to detect if a server unexpectedly sets a
9114wrong cookie to a client, leading to session crossing.
9115
9116 Examples :
9117 # capture the first cookie whose name starts with "ASPSESSION"
9118 capture cookie ASPSESSION len 32
9119
9120 # capture the first cookie whose name is exactly "vgnvisitor"
9121 capture cookie vgnvisitor= len 32
9122
9123
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091248.8. Capturing HTTP headers
9125---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009126
9127Header captures are useful to track unique request identifiers set by an upper
9128proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
9129the response, one can search for information about the response length, how the
9130server asked the cache to behave, or an object location during a redirection.
9131
9132Header captures are performed using the "capture request header" and "capture
9133response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009134section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009135
9136It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009137time. Non-existent headers are logged as empty strings, and if one header
9138appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009139are grouped within braces '{' and '}' in the same order as they were declared,
9140and delimited with a vertical bar '|' without any space. Response headers
9141follow the same representation, but are displayed after a space following the
9142request headers block. These blocks are displayed just before the HTTP request
9143in the logs.
9144
9145 Example :
9146 # This instance chains to the outgoing proxy
9147 listen proxy-out
9148 mode http
9149 option httplog
9150 option logasap
9151 log global
9152 server cache1 192.168.1.1:3128
9153
9154 # log the name of the virtual server
9155 capture request header Host len 20
9156
9157 # log the amount of data uploaded during a POST
9158 capture request header Content-Length len 10
9159
9160 # log the beginning of the referrer
9161 capture request header Referer len 20
9162
9163 # server name (useful for outgoing proxies only)
9164 capture response header Server len 20
9165
9166 # logging the content-length is useful with "option logasap"
9167 capture response header Content-Length len 10
9168
9169 # log the expected cache behaviour on the response
9170 capture response header Cache-Control len 8
9171
9172 # the Via header will report the next proxy's name
9173 capture response header Via len 20
9174
9175 # log the URL location during a redirection
9176 capture response header Location len 20
9177
9178 >>> Aug 9 20:26:09 localhost \
9179 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
9180 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
9181 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
9182 "GET http://fr.adserver.yahoo.com/"
9183
9184 >>> Aug 9 20:30:46 localhost \
9185 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
9186 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
9187 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009188 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009189
9190 >>> Aug 9 20:30:46 localhost \
9191 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
9192 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
9193 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
9194 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009195 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009196
9197
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091988.9. Examples of logs
9199---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009200
9201These are real-world examples of logs accompanied with an explanation. Some of
9202them have been made up by hand. The syslog part has been removed for better
9203reading. Their sole purpose is to explain how to decipher them.
9204
9205 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
9206 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
9207 "HEAD / HTTP/1.0"
9208
9209 => long request (6.5s) entered by hand through 'telnet'. The server replied
9210 in 147 ms, and the session ended normally ('----')
9211
9212 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
9213 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
9214 0/9 "HEAD / HTTP/1.0"
9215
9216 => Idem, but the request was queued in the global queue behind 9 other
9217 requests, and waited there for 1230 ms.
9218
9219 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
9220 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
9221 "GET /image.iso HTTP/1.0"
9222
9223 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009224 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009225 14 ms, 243 bytes of headers were sent to the client, and total time from
9226 accept to first data byte is 30 ms.
9227
9228 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
9229 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
9230 "GET /cgi-bin/bug.cgi? HTTP/1.0"
9231
9232 => the proxy blocked a server response either because of an "rspdeny" or
9233 "rspideny" filter, or because the response was improperly formatted and
9234 not HTTP-compliant, or because it blocked sensible information which
9235 risked being cached. In this case, the response is replaced with a "502
9236 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
9237 to return the 502 and not the server.
9238
9239 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009240 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 +01009241
9242 => the client never completed its request and aborted itself ("C---") after
9243 8.5s, while the proxy was waiting for the request headers ("-R--").
9244 Nothing was sent to any server.
9245
9246 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
9247 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
9248
9249 => The client never completed its request, which was aborted by the
9250 time-out ("c---") after 50s, while the proxy was waiting for the request
9251 headers ("-R--"). Nothing was sent to any server, but the proxy could
9252 send a 408 return code to the client.
9253
9254 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
9255 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
9256
9257 => This log was produced with "option tcplog". The client timed out after
9258 5 seconds ("c----").
9259
9260 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
9261 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009262 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009263
9264 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009265 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009266 (config says 'retries 3'), and no redispatch (otherwise we would have
9267 seen "/+3"). Status code 503 was returned to the client. There were 115
9268 connections on this server, 202 connections on this proxy, and 205 on
9269 the global process. It is possible that the server refused the
9270 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009271
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009272
Willy Tarreauc57f0e22009-05-10 13:12:33 +020092739. Statistics and monitoring
9274----------------------------
9275
9276It is possible to query HAProxy about its status. The most commonly used
9277mechanism is the HTTP statistics page. This page also exposes an alternative
9278CSV output format for monitoring tools. The same format is provided on the
9279Unix socket.
9280
9281
92829.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009283---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009284
Willy Tarreau7f062c42009-03-05 18:43:00 +01009285The statistics may be consulted either from the unix socket or from the HTTP
9286page. Both means provide a CSV format whose fields follow.
9287
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009288 0. pxname: proxy name
9289 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
9290 for server)
9291 2. qcur: current queued requests
9292 3. qmax: max queued requests
9293 4. scur: current sessions
9294 5. smax: max sessions
9295 6. slim: sessions limit
9296 7. stot: total sessions
9297 8. bin: bytes in
9298 9. bout: bytes out
9299 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009300 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009301 12. ereq: request errors
9302 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +01009303 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009304 15. wretr: retries (warning)
9305 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +01009306 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009307 18. weight: server weight (server), total weight (backend)
9308 19. act: server is active (server), number of active servers (backend)
9309 20. bck: server is backup (server), number of backup servers (backend)
9310 21. chkfail: number of failed checks
9311 22. chkdown: number of UP->DOWN transitions
9312 23. lastchg: last status change (in seconds)
9313 24. downtime: total downtime (in seconds)
9314 25. qlimit: queue limit
9315 26. pid: process id (0 for first instance, 1 for second, ...)
9316 27. iid: unique proxy id
9317 28. sid: service id (unique inside a proxy)
9318 29. throttle: warm up status
9319 30. lbtot: total number of times a server was selected
9320 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02009321 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +02009322 33. rate: number of sessions per second over last elapsed second
9323 34. rate_lim: limit on new sessions per second
9324 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02009325 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +01009326 UNK -> unknown
9327 INI -> initializing
9328 SOCKERR -> socket error
9329 L4OK -> check passed on layer 4, no upper layers testing enabled
9330 L4TMOUT -> layer 1-4 timeout
9331 L4CON -> layer 1-4 connection problem, for example
9332 "Connection refused" (tcp rst) or "No route to host" (icmp)
9333 L6OK -> check passed on layer 6
9334 L6TOUT -> layer 6 (SSL) timeout
9335 L6RSP -> layer 6 invalid response - protocol error
9336 L7OK -> check passed on layer 7
9337 L7OKC -> check conditionally passed on layer 7, for example 404 with
9338 disable-on-404
9339 L7TOUT -> layer 7 (HTTP/SMTP) timeout
9340 L7RSP -> layer 7 invalid response - protocol error
9341 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02009342 37. check_code: layer5-7 code, if available
9343 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009344 39. hrsp_1xx: http responses with 1xx code
9345 40. hrsp_2xx: http responses with 2xx code
9346 41. hrsp_3xx: http responses with 3xx code
9347 42. hrsp_4xx: http responses with 4xx code
9348 43. hrsp_5xx: http responses with 5xx code
9349 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +01009350 45. hanafail: failed health checks details
9351 46. req_rate: HTTP requests per second over last elapsed second
9352 47. req_rate_max: max number of HTTP requests per second observed
9353 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +01009354 49. cli_abrt: number of data transfers aborted by the client
9355 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau844e3c52008-01-11 16:28:18 +01009356
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009357
Willy Tarreauc57f0e22009-05-10 13:12:33 +020093589.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009359-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009360
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009361The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009362must be terminated by a line feed. The socket supports pipelining, so that it
9363is possible to chain multiple commands at once provided they are delimited by
9364a semi-colon or a line feed, although the former is more reliable as it has no
9365risk of being truncated over the network. The responses themselves will each be
9366followed by an empty line, so it will be easy for an external script to match a
9367given response with a given request. By default one command line is processed
9368then the connection closes, but there is an interactive allowing multiple lines
9369to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009370
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009371It is important to understand that when multiple haproxy processes are started
9372on the same sockets, any process may pick up the request and will output its
9373own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009374
Willy Tarreaud63335a2010-02-26 12:56:52 +01009375clear counters
9376 Clear the max values of the statistics counters in each proxy (frontend &
9377 backend) and in each server. The cumulated counters are not affected. This
9378 can be used to get clean counters after an incident, without having to
9379 restart nor to clear traffic counters. This command is restricted and can
9380 only be issued on sockets configured for levels "operator" or "admin".
9381
9382clear counters all
9383 Clear all statistics counters in each proxy (frontend & backend) and in each
9384 server. This has the same effect as restarting. This command is restricted
9385 and can only be issued on sockets configured for level "admin".
9386
Simon Hormanc88b8872011-06-15 15:18:49 +09009387clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
9388 Remove entries from the stick-table <table>.
9389
9390 This is typically used to unblock some users complaining they have been
9391 abusively denied access to a service, but this can also be used to clear some
9392 stickiness entries matching a server that is going to be replaced (see "show
9393 table" below for details). Note that sometimes, removal of an entry will be
9394 refused because it is currently tracked by a session. Retrying a few seconds
9395 later after the session ends is usual enough.
9396
9397 In the case where no options arguments are given all entries will be removed.
9398
9399 When the "data." form is used entries matching a filter applied using the
9400 stored data (see "stick-table" in section 4.2) are removed. A stored data
9401 type must be specified in <type>, and this data type must be stored in the
9402 table otherwise an error is reported. The data is compared according to
9403 <operator> with the 64-bit integer <value>. Operators are the same as with
9404 the ACLs :
9405
9406 - eq : match entries whose data is equal to this value
9407 - ne : match entries whose data is not equal to this value
9408 - le : match entries whose data is less than or equal to this value
9409 - ge : match entries whose data is greater than or equal to this value
9410 - lt : match entries whose data is less than this value
9411 - gt : match entries whose data is greater than this value
9412
9413 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +09009414 same type as the table, which currently is limited to IPv4, IPv6, integer and
9415 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009416
9417 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009418 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009419 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +02009420 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
9421 bytes_out_rate(60000)=187
9422 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9423 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009424
9425 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
9426
9427 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009428 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +02009429 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9430 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +09009431 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
9432 $ echo "show table http_proxy" | socat stdio /tmp/sock1
9433 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009434
Willy Tarreaud63335a2010-02-26 12:56:52 +01009435disable server <backend>/<server>
9436 Mark the server DOWN for maintenance. In this mode, no more checks will be
9437 performed on the server until it leaves maintenance.
9438 If the server is tracked by other servers, those servers will be set to DOWN
9439 during the maintenance.
9440
9441 In the statistics page, a server DOWN for maintenance will appear with a
9442 "MAINT" status, its tracking servers with the "MAINT(via)" one.
9443
9444 Both the backend and the server may be specified either by their name or by
9445 their numeric ID, prefixed with a dash ('#').
9446
9447 This command is restricted and can only be issued on sockets configured for
9448 level "admin".
9449
9450enable server <backend>/<server>
9451 If the server was previously marked as DOWN for maintenance, this marks the
9452 server UP and checks are re-enabled.
9453
9454 Both the backend and the server may be specified either by their name or by
9455 their numeric ID, prefixed with a dash ('#').
9456
9457 This command is restricted and can only be issued on sockets configured for
9458 level "admin".
9459
9460get weight <backend>/<server>
9461 Report the current weight and the initial weight of server <server> in
9462 backend <backend> or an error if either doesn't exist. The initial weight is
9463 the one that appears in the configuration file. Both are normally equal
9464 unless the current weight has been changed. Both the backend and the server
9465 may be specified either by their name or by their numeric ID, prefixed with a
9466 dash ('#').
9467
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009468help
9469 Print the list of known keywords and their basic usage. The same help screen
9470 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009471
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009472prompt
9473 Toggle the prompt at the beginning of the line and enter or leave interactive
9474 mode. In interactive mode, the connection is not closed after a command
9475 completes. Instead, the prompt will appear again, indicating the user that
9476 the interpreter is waiting for a new command. The prompt consists in a right
9477 angle bracket followed by a space "> ". This mode is particularly convenient
9478 when one wants to periodically check information such as stats or errors.
9479 It is also a good idea to enter interactive mode before issuing a "help"
9480 command.
9481
9482quit
9483 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009484
Willy Tarreaud63335a2010-02-26 12:56:52 +01009485set timeout cli <delay>
9486 Change the CLI interface timeout for current connection. This can be useful
9487 during long debugging sessions where the user needs to constantly inspect
9488 some indicators without being disconnected. The delay is passed in seconds.
9489
9490set weight <backend>/<server> <weight>[%]
9491 Change a server's weight to the value passed in argument. If the value ends
9492 with the '%' sign, then the new weight will be relative to the initially
9493 configured weight. Relative weights are only permitted between 0 and 100%,
9494 and absolute weights are permitted between 0 and 256. Servers which are part
9495 of a farm running a static load-balancing algorithm have stricter limitations
9496 because the weight cannot change once set. Thus for these servers, the only
9497 accepted values are 0 and 100% (or 0 and the initial weight). Changes take
9498 effect immediately, though certain LB algorithms require a certain amount of
9499 requests to consider changes. A typical usage of this command is to disable
9500 a server during an update by setting its weight to zero, then to enable it
9501 again after the update by setting it back to 100%. This command is restricted
9502 and can only be issued on sockets configured for level "admin". Both the
9503 backend and the server may be specified either by their name or by their
9504 numeric ID, prefixed with a dash ('#').
9505
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009506show errors [<iid>]
9507 Dump last known request and response errors collected by frontends and
9508 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +02009509 either frontend or backend whose ID is <iid>. This command is restricted
9510 and can only be issued on sockets configured for levels "operator" or
9511 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009512
9513 The errors which may be collected are the last request and response errors
9514 caused by protocol violations, often due to invalid characters in header
9515 names. The report precisely indicates what exact character violated the
9516 protocol. Other important information such as the exact date the error was
9517 detected, frontend and backend names, the server name (when known), the
9518 internal session ID and the source address which has initiated the session
9519 are reported too.
9520
9521 All characters are returned, and non-printable characters are encoded. The
9522 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
9523 letter following a backslash. The backslash itself is encoded as '\\' to
9524 avoid confusion. Other non-printable characters are encoded '\xNN' where
9525 NN is the two-digits hexadecimal representation of the character's ASCII
9526 code.
9527
9528 Lines are prefixed with the position of their first character, starting at 0
9529 for the beginning of the buffer. At most one input line is printed per line,
9530 and large lines will be broken into multiple consecutive output lines so that
9531 the output never goes beyond 79 characters wide. It is easy to detect if a
9532 line was broken, because it will not end with '\n' and the next line's offset
9533 will be followed by a '+' sign, indicating it is a continuation of previous
9534 line.
9535
9536 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009537 $ echo "show errors" | socat stdio /tmp/sock1
9538 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009539 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
9540 response length 213 bytes, error at position 23:
9541
9542 00000 HTTP/1.0 200 OK\r\n
9543 00017 header/bizarre:blah\r\n
9544 00038 Location: blah\r\n
9545 00054 Long-line: this is a very long line which should b
9546 00104+ e broken into multiple lines on the output buffer,
9547 00154+ otherwise it would be too large to print in a ter
9548 00204+ minal\r\n
9549 00211 \r\n
9550
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009551 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009552 ID 2 has blocked an invalid response from its server s2 which has internal
9553 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
9554 received by frontend fe-eth0 whose ID is 1. The total response length was
9555 213 bytes when the error was detected, and the error was at byte 23. This
9556 is the slash ('/') in header name "header/bizarre", which is not a valid
9557 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009558
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009559show info
9560 Dump info about haproxy status on current process.
9561
9562show sess
9563 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +02009564 be huge. This command is restricted and can only be issued on sockets
9565 configured for levels "operator" or "admin".
9566
Willy Tarreau66dc20a2010-03-05 17:53:32 +01009567show sess <id>
9568 Display a lot of internal information about the specified session identifier.
9569 This identifier is the first field at the beginning of the lines in the dumps
9570 of "show sess" (it corresponds to the session pointer). Those information are
9571 useless to most users but may be used by haproxy developers to troubleshoot a
9572 complex bug. The output format is intentionally not documented so that it can
9573 freely evolve depending on demands.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009574
9575show stat [<iid> <type> <sid>]
9576 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
9577 possible to dump only selected items :
9578 - <iid> is a proxy ID, -1 to dump everything
9579 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
9580 backends, 4 for servers, -1 for everything. These values can be ORed,
9581 for example:
9582 1 + 2 = 3 -> frontend + backend.
9583 1 + 2 + 4 = 7 -> frontend + backend + server.
9584 - <sid> is a server ID, -1 to dump everything from the selected proxy.
9585
9586 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009587 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
9588 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009589 Version: 1.4-dev2-49
9590 Release_date: 2009/09/23
9591 Nbproc: 1
9592 Process_num: 1
9593 (...)
9594
9595 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
9596 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
9597 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
9598 (...)
9599 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
9600
9601 $
9602
9603 Here, two commands have been issued at once. That way it's easy to find
9604 which process the stats apply to in multi-process mode. Notice the empty
9605 line after the information output which marks the end of the first block.
9606 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009607 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009608
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009609show table
9610 Dump general information on all known stick-tables. Their name is returned
9611 (the name of the proxy which holds them), their type (currently zero, always
9612 IP), their size in maximum possible number of entries, and the number of
9613 entries currently in use.
9614
9615 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009616 $ echo "show table" | socat stdio /tmp/sock1
9617 >>> # table: front_pub, type: 0, size:204800, used:171454
9618 >>> # table: back_rdp, type: 0, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009619
Simon Horman17bce342011-06-15 15:18:47 +09009620show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009621 Dump contents of stick-table <name>. In this mode, a first line of generic
9622 information about the table is reported as with "show table", then all
9623 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +09009624 a filter in order to specify what entries to display.
9625
9626 When the "data." form is used the filter applies to the stored data (see
9627 "stick-table" in section 4.2). A stored data type must be specified
9628 in <type>, and this data type must be stored in the table otherwise an
9629 error is reported. The data is compared according to <operator> with the
9630 64-bit integer <value>. Operators are the same as with the ACLs :
9631
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009632 - eq : match entries whose data is equal to this value
9633 - ne : match entries whose data is not equal to this value
9634 - le : match entries whose data is less than or equal to this value
9635 - ge : match entries whose data is greater than or equal to this value
9636 - lt : match entries whose data is less than this value
9637 - gt : match entries whose data is greater than this value
9638
Simon Hormanc88b8872011-06-15 15:18:49 +09009639
9640 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +09009641 same type as the table, which currently is limited to IPv4, IPv6, integer,
9642 and string.
Simon Horman17bce342011-06-15 15:18:47 +09009643
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009644 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009645 $ echo "show table http_proxy" | socat stdio /tmp/sock1
9646 >>> # table: http_proxy, type: 0, size:204800, used:2
9647 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
9648 bytes_out_rate(60000)=187
9649 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9650 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009651
Willy Tarreau62a36c42010-08-17 15:53:10 +02009652 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
9653 >>> # table: http_proxy, type: 0, size:204800, used:2
9654 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9655 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009656
Willy Tarreau62a36c42010-08-17 15:53:10 +02009657 $ echo "show table http_proxy data.conn_rate gt 5" | \
9658 socat stdio /tmp/sock1
9659 >>> # table: http_proxy, type: 0, size:204800, used:2
9660 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9661 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009662
Simon Horman17bce342011-06-15 15:18:47 +09009663 $ echo "show table http_proxy key 127.0.0.2" | \
9664 socat stdio /tmp/sock1
9665 >>> # table: http_proxy, type: 0, size:204800, used:2
9666 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9667 bytes_out_rate(60000)=191
9668
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009669 When the data criterion applies to a dynamic value dependent on time such as
9670 a bytes rate, the value is dynamically computed during the evaluation of the
9671 entry in order to decide whether it has to be dumped or not. This means that
9672 such a filter could match for some time then not match anymore because as
9673 time goes, the average event rate drops.
9674
9675 It is possible to use this to extract lists of IP addresses abusing the
9676 service, in order to monitor them or even blacklist them in a firewall.
9677 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009678 $ echo "show table http_proxy data.gpc0 gt 0" \
9679 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009680 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
9681 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +02009682
Willy Tarreau0ba27502007-12-24 16:55:16 +01009683/*
9684 * Local variables:
9685 * fill-column: 79
9686 * End:
9687 */