blob: 7a5ace2860e58ceb0d6b9d15ff436afbd42b5928 [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 Tarreau442e8342010-11-11 23:29:35 +01007 2010/11/11
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
510 - A filesystem path to a UNIX domain socket, keeping in mind
511 considerations for chroot (be sure the path is accessible inside
512 the chroot) and uid/gid (be sure the path is appropriately
513 writeable).
514
515 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200516
517 kern user mail daemon auth syslog lpr news
518 uucp cron auth2 ftp ntp audit alert cron2
519 local0 local1 local2 local3 local4 local5 local6 local7
520
521 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200522 all messages are sent. If a maximum level is specified, only messages with a
523 severity at least as important as this level will be sent. An optional minimum
524 level can be specified. If it is set, logs emitted with a more severe level
525 than this one will be capped to this level. This is used to avoid sending
526 "emerg" messages on all terminals on some default syslog configurations.
527 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200528
529 emerg alert crit err warning notice info debug
530
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100531log-send-hostname [<string>]
532 Sets the hostname field in the syslog header. If optional "string" parameter
533 is set the header is set to the string contents, otherwise uses the hostname
534 of the system. Generally used if one is not relaying logs through an
535 intermediate syslog server or for simply customizing the hostname printed in
536 the logs.
537
Kevinm48936af2010-12-22 16:08:21 +0000538log-tag <string>
539 Sets the tag field in the syslog header to this string. It defaults to the
540 program name as launched from the command line, which usually is "haproxy".
541 Sometimes it can be useful to differentiate between multiple processes
542 running on the same host.
543
Willy Tarreau6a06a402007-07-15 20:15:28 +0200544nbproc <number>
545 Creates <number> processes when going daemon. This requires the "daemon"
546 mode. By default, only one process is created, which is the recommended mode
547 of operation. For systems limited to small sets of file descriptors per
548 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
549 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
550
551pidfile <pidfile>
552 Writes pids of all daemons into file <pidfile>. This option is equivalent to
553 the "-p" command line argument. The file must be accessible to the user
554 starting the process. See also "daemon".
555
Willy Tarreaufbee7132007-10-18 13:53:22 +0200556stats socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>]
Willy Tarreau6162db22009-10-10 17:13:00 +0200557 [level <level>]
558
Willy Tarreaufbee7132007-10-18 13:53:22 +0200559 Creates a UNIX socket in stream mode at location <path>. Any previously
560 existing socket will be backed up then replaced. Connections to this socket
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100561 will return various statistics outputs and even allow some commands to be
Willy Tarreau6162db22009-10-10 17:13:00 +0200562 issued. Please consult section 9.2 "Unix Socket commands" for more details.
563
564 An optional "level" parameter can be specified to restrict the nature of
565 the commands that can be issued on the socket :
566 - "user" is the least privileged level ; only non-sensitive stats can be
567 read, and no change is allowed. It would make sense on systems where it
568 is not easy to restrict access to the socket.
569
570 - "operator" is the default level and fits most common uses. All data can
571 be read, and only non-sensible changes are permitted (eg: clear max
572 counters).
573
574 - "admin" should be used with care, as everything is permitted (eg: clear
575 all counters).
Willy Tarreaua8efd362008-01-03 10:19:15 +0100576
577 On platforms which support it, it is possible to restrict access to this
578 socket by specifying numerical IDs after "uid" and "gid", or valid user and
579 group names after the "user" and "group" keywords. It is also possible to
580 restrict permissions on the socket by passing an octal value after the "mode"
581 keyword (same syntax as chmod). Depending on the platform, the permissions on
582 the socket will be inherited from the directory which hosts it, or from the
583 user the process is started with.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200584
585stats timeout <timeout, in milliseconds>
586 The default timeout on the stats socket is set to 10 seconds. It is possible
587 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100588 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200589
590stats maxconn <connections>
591 By default, the stats socket is limited to 10 concurrent connections. It is
592 possible to change this value with "stats maxconn".
593
Willy Tarreau6a06a402007-07-15 20:15:28 +0200594uid <number>
595 Changes the process' user ID to <number>. It is recommended that the user ID
596 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
597 be started with superuser privileges in order to be able to switch to another
598 one. See also "gid" and "user".
599
600ulimit-n <number>
601 Sets the maximum number of per-process file-descriptors to <number>. By
602 default, it is automatically computed, so it is recommended not to use this
603 option.
604
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100605unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
606 [ group <group> ] [ gid <gid> ]
607
608 Fixes common settings to UNIX listening sockets declared in "bind" statements.
609 This is mainly used to simplify declaration of those UNIX sockets and reduce
610 the risk of errors, since those settings are most commonly required but are
611 also process-specific. The <prefix> setting can be used to force all socket
612 path to be relative to that directory. This might be needed to access another
613 component's chroot. Note that those paths are resolved before haproxy chroots
614 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
615 all have the same meaning as their homonyms used by the "bind" statement. If
616 both are specified, the "bind" statement has priority, meaning that the
617 "unix-bind" settings may be seen as process-wide default settings.
618
Willy Tarreau6a06a402007-07-15 20:15:28 +0200619user <user name>
620 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
621 See also "uid" and "group".
622
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200623node <name>
624 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
625
626 This statement is useful in HA configurations where two or more processes or
627 servers share the same IP address. By setting a different node-name on all
628 nodes, it becomes easy to immediately spot what server is handling the
629 traffic.
630
631description <text>
632 Add a text that describes the instance.
633
634 Please note that it is required to escape certain characters (# for example)
635 and this text is inserted into a html page so you should avoid using
636 "<" and ">" characters.
637
Willy Tarreau6a06a402007-07-15 20:15:28 +0200638
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006393.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200640-----------------------
641
642maxconn <number>
643 Sets the maximum per-process number of concurrent connections to <number>. It
644 is equivalent to the command-line argument "-n". Proxies will stop accepting
645 connections when this limit is reached. The "ulimit-n" parameter is
646 automatically adjusted according to this value. See also "ulimit-n".
647
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100648maxpipes <number>
649 Sets the maximum per-process number of pipes to <number>. Currently, pipes
650 are only used by kernel-based tcp splicing. Since a pipe contains two file
651 descriptors, the "ulimit-n" value will be increased accordingly. The default
652 value is maxconn/4, which seems to be more than enough for most heavy usages.
653 The splice code dynamically allocates and releases pipes, and can fall back
654 to standard copy, so setting this value too low may only impact performance.
655
Willy Tarreau6a06a402007-07-15 20:15:28 +0200656noepoll
657 Disables the use of the "epoll" event polling system on Linux. It is
658 equivalent to the command-line argument "-de". The next polling system
659 used will generally be "poll". See also "nosepoll", and "nopoll".
660
661nokqueue
662 Disables the use of the "kqueue" event polling system on BSD. It is
663 equivalent to the command-line argument "-dk". The next polling system
664 used will generally be "poll". See also "nopoll".
665
666nopoll
667 Disables the use of the "poll" event polling system. It is equivalent to the
668 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100669 It should never be needed to disable "poll" since it's available on all
Willy Tarreau6a06a402007-07-15 20:15:28 +0200670 platforms supported by HAProxy. See also "nosepoll", and "nopoll" and
671 "nokqueue".
672
673nosepoll
674 Disables the use of the "speculative epoll" event polling system on Linux. It
675 is equivalent to the command-line argument "-ds". The next polling system
676 used will generally be "epoll". See also "nosepoll", and "nopoll".
677
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100678nosplice
679 Disables the use of kernel tcp splicing between sockets on Linux. It is
680 equivalent to the command line argument "-dS". Data will then be copied
681 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100682 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100683 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
684 be used. This option makes it easier to globally disable kernel splicing in
685 case of doubt. See also "option splice-auto", "option splice-request" and
686 "option splice-response".
687
Willy Tarreaufe255b72007-10-14 23:09:26 +0200688spread-checks <0..50, in percent>
689 Sometimes it is desirable to avoid sending health checks to servers at exact
690 intervals, for instance when many logical servers are located on the same
691 physical server. With the help of this parameter, it becomes possible to add
692 some randomness in the check interval between 0 and +/- 50%. A value between
693 2 and 5 seems to show good results. The default value remains at 0.
694
Willy Tarreau27a674e2009-08-17 07:23:33 +0200695tune.bufsize <number>
696 Sets the buffer size to this size (in bytes). Lower values allow more
697 sessions to coexist in the same amount of RAM, and higher values allow some
698 applications with very large cookies to work. The default value is 16384 and
699 can be changed at build time. It is strongly recommended not to change this
700 from the default value, as very low values will break some services such as
701 statistics, and values larger than default size will increase memory usage,
702 possibly causing the system to run out of memory. At least the global maxconn
703 parameter should be decreased by the same factor as this one is increased.
704
Willy Tarreau43961d52010-10-04 20:39:20 +0200705tune.chksize <number>
706 Sets the check buffer size to this size (in bytes). Higher values may help
707 find string or regex patterns in very large pages, though doing so may imply
708 more memory and CPU usage. The default value is 16384 and can be changed at
709 build time. It is not recommended to change this value, but to use better
710 checks whenever possible.
711
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100712tune.maxaccept <number>
713 Sets the maximum number of consecutive accepts that a process may perform on
714 a single wake up. High values give higher priority to high connection rates,
715 while lower values give higher priority to already established connections.
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100716 This value is limited to 100 by default in single process mode. However, in
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100717 multi-process mode (nbproc > 1), it defaults to 8 so that when one process
718 wakes up, it does not take all incoming connections for itself and leaves a
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100719 part of them to other processes. Setting this value to -1 completely disables
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100720 the limitation. It should normally not be needed to tweak this value.
721
722tune.maxpollevents <number>
723 Sets the maximum amount of events that can be processed at once in a call to
724 the polling system. The default value is adapted to the operating system. It
725 has been noticed that reducing it below 200 tends to slightly decrease
726 latency at the expense of network bandwidth, and increasing it above 200
727 tends to trade latency for slightly increased bandwidth.
728
Willy Tarreau27a674e2009-08-17 07:23:33 +0200729tune.maxrewrite <number>
730 Sets the reserved buffer space to this size in bytes. The reserved space is
731 used for header rewriting or appending. The first reads on sockets will never
732 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
733 bufsize, though that does not make much sense since there are rarely large
734 numbers of headers to add. Setting it too high prevents processing of large
735 requests or responses. Setting it too low prevents addition of new headers
736 to already large requests or to POST requests. It is generally wise to set it
737 to about 1024. It is automatically readjusted to half of bufsize if it is
738 larger than that. This means you don't have to worry about it when changing
739 bufsize.
740
Willy Tarreaue803de22010-01-21 17:43:04 +0100741tune.rcvbuf.client <number>
742tune.rcvbuf.server <number>
743 Forces the kernel socket receive buffer size on the client or the server side
744 to the specified value in bytes. This value applies to all TCP/HTTP frontends
745 and backends. It should normally never be set, and the default size (0) lets
746 the kernel autotune this value depending on the amount of available memory.
747 However it can sometimes help to set it to very low values (eg: 4096) in
748 order to save kernel memory by preventing it from buffering too large amounts
749 of received data. Lower values will significantly increase CPU usage though.
750
751tune.sndbuf.client <number>
752tune.sndbuf.server <number>
753 Forces the kernel socket send buffer size on the client or the server side to
754 the specified value in bytes. This value applies to all TCP/HTTP frontends
755 and backends. It should normally never be set, and the default size (0) lets
756 the kernel autotune this value depending on the amount of available memory.
757 However it can sometimes help to set it to very low values (eg: 4096) in
758 order to save kernel memory by preventing it from buffering too large amounts
759 of received data. Lower values will significantly increase CPU usage though.
760 Another use case is to prevent write timeouts with extremely slow clients due
761 to the kernel waiting for a large part of the buffer to be read before
762 notifying haproxy again.
763
Willy Tarreau6a06a402007-07-15 20:15:28 +0200764
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007653.3. Debugging
766--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200767
768debug
769 Enables debug mode which dumps to stdout all exchanges, and disables forking
770 into background. It is the equivalent of the command-line argument "-d". It
771 should never be used in a production configuration since it may prevent full
772 system startup.
773
774quiet
775 Do not display any message during startup. It is equivalent to the command-
776 line argument "-q".
777
Emeric Brunf099e792010-09-27 12:05:28 +0200778
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007793.4. Userlists
780--------------
781It is possible to control access to frontend/backend/listen sections or to
782http stats by allowing only authenticated and authorized users. To do this,
783it is required to create at least one userlist and to define users.
784
785userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100786 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100787 used to store authentication & authorization data for independent customers.
788
789group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +0100790 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100791 attach users to this group by using a comma separated list of names
792 proceeded by "users" keyword.
793
Cyril Bontéf0c60612010-02-06 14:44:47 +0100794user <username> [password|insecure-password <password>]
795 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100796 Adds user <username> to the current userlist. Both secure (encrypted) and
797 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +0100798 evaluated using the crypt(3) function so depending of the system's
799 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100800 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
801 DES-based method of crypting passwords.
802
803
804 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +0100805 userlist L1
806 group G1 users tiger,scott
807 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100808
Cyril Bontéf0c60612010-02-06 14:44:47 +0100809 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
810 user scott insecure-password elgato
811 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100812
Cyril Bontéf0c60612010-02-06 14:44:47 +0100813 userlist L2
814 group G1
815 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100816
Cyril Bontéf0c60612010-02-06 14:44:47 +0100817 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
818 user scott insecure-password elgato groups G1,G2
819 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100820
821 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200822
Emeric Brunf099e792010-09-27 12:05:28 +0200823
8243.5. Peers
825--------------
826It is possible to synchronize server entries in stick tables between several
827haproxy instances over TCP connections in a multi-master fashion. Each instance
828pushes its local updates and insertions to remote peers. Server IDs are used to
829identify servers remotely, so it is important that configurations look similar
830or at least that the same IDs are forced on each server on all participants.
831Interrupted exchanges are automatically detected and recovered from the last
832known point. In addition, during a soft restart, the old process connects to
833the new one using such a TCP connection to push all its entries before the new
834process tries to connect to other peers. That ensures very fast replication
835during a reload, it typically takes a fraction of a second even for large
836tables.
837
838peers <peersect>
839 Creates a new peer list with name <peersect>. It is an independant section,
840 which is referenced by one or more stick-tables.
841
842peer <peername> <ip>:<port>
843 Defines a peer inside a peers section.
844 If <peername> is set to the local peer name (by default hostname, or forced
845 using "-L" command line option), haproxy will listen for incoming remote peer
846 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
847 to join the remote peer, and <peername> is used at the protocol level to
848 identify and validate the remote peer on the server side.
849
850 During a soft restart, local peer <ip>:<port> is used by the old instance to
851 connect the new one and initiate a complete replication (teaching process).
852
853 It is strongly recommended to have the exact same peers declaration on all
854 peers and to only rely on the "-L" command line argument to change the local
855 peer name. This makes it easier to maintain coherent configuration files
856 across all peers.
857
858Example:
859 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100860 peer haproxy1 192.168.0.1:1024
861 peer haproxy2 192.168.0.2:1024
862 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +0200863
864 backend mybackend
865 mode tcp
866 balance roundrobin
867 stick-table type ip size 20k peers mypeers
868 stick on src
869
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100870 server srv1 192.168.0.30:80
871 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +0200872
873
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008744. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +0200875----------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100876
Willy Tarreau6a06a402007-07-15 20:15:28 +0200877Proxy configuration can be located in a set of sections :
878 - defaults <name>
879 - frontend <name>
880 - backend <name>
881 - listen <name>
882
883A "defaults" section sets default parameters for all other sections following
884its declaration. Those default parameters are reset by the next "defaults"
885section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +0100886section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200887
888A "frontend" section describes a set of listening sockets accepting client
889connections.
890
891A "backend" section describes a set of servers to which the proxy will connect
892to forward incoming connections.
893
894A "listen" section defines a complete proxy with its frontend and backend
895parts combined in one section. It is generally useful for TCP-only traffic.
896
Willy Tarreau0ba27502007-12-24 16:55:16 +0100897All proxy names must be formed from upper and lower case letters, digits,
898'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
899case-sensitive, which means that "www" and "WWW" are two different proxies.
900
901Historically, all proxy names could overlap, it just caused troubles in the
902logs. Since the introduction of content switching, it is mandatory that two
903proxies with overlapping capabilities (frontend/backend) have different names.
904However, it is still permitted that a frontend and a backend share the same
905name, as this configuration seems to be commonly encountered.
906
907Right now, two major proxy modes are supported : "tcp", also known as layer 4,
908and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100909bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +0100910protocol, and can interact with it by allowing, blocking, switching, adding,
911modifying, or removing arbitrary contents in requests or responses, based on
912arbitrary criteria.
913
Willy Tarreau0ba27502007-12-24 16:55:16 +0100914
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009154.1. Proxy keywords matrix
916--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100917
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200918The following list of keywords is supported. Most of them may only be used in a
919limited set of section types. Some of them are marked as "deprecated" because
920they are inherited from an old syntax which may be confusing or functionally
921limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100922marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200923option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +0200924and must be disabled for a specific instance. Such options may also be prefixed
925with "default" in order to restore default settings regardless of what has been
926specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100927
Willy Tarreau6a06a402007-07-15 20:15:28 +0200928
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100929 keyword defaults frontend listen backend
930------------------------------------+----------+----------+---------+---------
931acl - X X X
932appsession - - X X
933backlog X X X -
934balance X - X X
935bind - X X -
936bind-process X X X X
937block - X X X
938capture cookie - X X -
939capture request header - X X -
940capture response header - X X -
941clitimeout (deprecated) X X X -
942contimeout (deprecated) X - X X
943cookie X - X X
944default-server X - X X
945default_backend X X X -
946description - X X X
947disabled X X X X
948dispatch - - X X
949enabled X X X X
950errorfile X X X X
951errorloc X X X X
952errorloc302 X X X X
953-- keyword -------------------------- defaults - frontend - listen -- backend -
954errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +0200955force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100956fullconn X - X X
957grace X X X X
958hash-type X - X X
959http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +0100960http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +0200961http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100962http-request - X X X
963id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +0200964ignore-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100965log X X X X
966maxconn X X X -
967mode X X X X
968monitor fail - X X -
969monitor-net X X X -
970monitor-uri X X X -
971option abortonclose (*) X - X X
972option accept-invalid-http-request (*) X X X -
973option accept-invalid-http-response (*) X - X X
974option allbackups (*) X - X X
975option checkcache (*) X - X X
976option clitcpka (*) X X X -
977option contstats (*) X X X -
978option dontlog-normal (*) X X X -
979option dontlognull (*) X X X -
980option forceclose (*) X X X X
981-- keyword -------------------------- defaults - frontend - listen -- backend -
982option forwardfor X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +0200983option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100984option http-server-close (*) X X X X
985option http-use-proxy-header (*) X X X -
986option httpchk X - X X
987option httpclose (*) X X X X
988option httplog X X X X
989option http_proxy (*) X X X X
990option independant-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +0200991option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100992option log-health-checks (*) X - X X
993option log-separate-errors (*) X X X -
994option logasap (*) X X X -
995option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +0100996option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +0100997option nolinger (*) X X X X
998option originalto X X X X
999option persist (*) X - X X
1000option redispatch (*) X - X X
1001option smtpchk X - X X
1002option socket-stats (*) X X X -
1003option splice-auto (*) X X X X
1004option splice-request (*) X X X X
1005option splice-response (*) X X X X
1006option srvtcpka (*) X - X X
1007option ssl-hello-chk X - X X
1008-- keyword -------------------------- defaults - frontend - listen -- backend -
1009option tcp-smart-accept (*) X X X -
1010option tcp-smart-connect (*) X - X X
1011option tcpka X X X X
1012option tcplog X X X X
1013option transparent (*) X - X X
1014persist rdp-cookie X - X X
1015rate-limit sessions X X X -
1016redirect - X X X
1017redisp (deprecated) X - X X
1018redispatch (deprecated) X - X X
1019reqadd - X X X
1020reqallow - X X X
1021reqdel - X X X
1022reqdeny - X X X
1023reqiallow - X X X
1024reqidel - X X X
1025reqideny - X X X
1026reqipass - X X X
1027reqirep - X X X
1028reqisetbe - X X X
1029reqitarpit - X X X
1030reqpass - X X X
1031reqrep - X X X
1032-- keyword -------------------------- defaults - frontend - listen -- backend -
1033reqsetbe - X X X
1034reqtarpit - X X X
1035retries X - X X
1036rspadd - X X X
1037rspdel - X X X
1038rspdeny - X X X
1039rspidel - X X X
1040rspideny - X X X
1041rspirep - X X X
1042rsprep - X X X
1043server - - X X
1044source X - X X
1045srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001046stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001047stats auth X - X X
1048stats enable X - X X
1049stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001050stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001051stats realm X - X X
1052stats refresh X - X X
1053stats scope X - X X
1054stats show-desc X - X X
1055stats show-legends X - X X
1056stats show-node X - X X
1057stats uri X - X X
1058-- keyword -------------------------- defaults - frontend - listen -- backend -
1059stick match - - X X
1060stick on - - X X
1061stick store-request - - X X
1062stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001063tcp-request connection - X X -
1064tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001065tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001066tcp-response content - - X X
1067tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001068timeout check X - X X
1069timeout client X X X -
1070timeout clitimeout (deprecated) X X X -
1071timeout connect X - X X
1072timeout contimeout (deprecated) X - X X
1073timeout http-keep-alive X X X X
1074timeout http-request X X X X
1075timeout queue X - X X
1076timeout server X - X X
1077timeout srvtimeout (deprecated) X - X X
1078timeout tarpit X X X X
1079transparent (deprecated) X - X X
1080use_backend - X X -
1081------------------------------------+----------+----------+---------+---------
1082 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001083
Willy Tarreau0ba27502007-12-24 16:55:16 +01001084
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010854.2. Alphabetically sorted keywords reference
1086---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001087
1088This section provides a description of each keyword and its usage.
1089
1090
1091acl <aclname> <criterion> [flags] [operator] <value> ...
1092 Declare or complete an access list.
1093 May be used in sections : defaults | frontend | listen | backend
1094 no | yes | yes | yes
1095 Example:
1096 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1097 acl invalid_src src_port 0:1023
1098 acl local_dst hdr(host) -i localhost
1099
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001100 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001101
1102
Cyril Bontéb21570a2009-11-29 20:04:48 +01001103appsession <cookie> len <length> timeout <holdtime>
1104 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001105 Define session stickiness on an existing application cookie.
1106 May be used in sections : defaults | frontend | listen | backend
1107 no | no | yes | yes
1108 Arguments :
1109 <cookie> this is the name of the cookie used by the application and which
1110 HAProxy will have to learn for each new session.
1111
Cyril Bontéb21570a2009-11-29 20:04:48 +01001112 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001113 checked in each cookie value.
1114
1115 <holdtime> this is the time after which the cookie will be removed from
1116 memory if unused. If no unit is specified, this time is in
1117 milliseconds.
1118
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001119 request-learn
1120 If this option is specified, then haproxy will be able to learn
1121 the cookie found in the request in case the server does not
1122 specify any in response. This is typically what happens with
1123 PHPSESSID cookies, or when haproxy's session expires before
1124 the application's session and the correct server is selected.
1125 It is recommended to specify this option to improve reliability.
1126
Cyril Bontéb21570a2009-11-29 20:04:48 +01001127 prefix When this option is specified, haproxy will match on the cookie
1128 prefix (or URL parameter prefix). The appsession value is the
1129 data following this prefix.
1130
1131 Example :
1132 appsession ASPSESSIONID len 64 timeout 3h prefix
1133
1134 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1135 the appsession value will be XXXX=XXXXX.
1136
1137 mode This option allows to change the URL parser mode.
1138 2 modes are currently supported :
1139 - path-parameters :
1140 The parser looks for the appsession in the path parameters
1141 part (each parameter is separated by a semi-colon), which is
1142 convenient for JSESSIONID for example.
1143 This is the default mode if the option is not set.
1144 - query-string :
1145 In this mode, the parser will look for the appsession in the
1146 query string.
1147
Willy Tarreau0ba27502007-12-24 16:55:16 +01001148 When an application cookie is defined in a backend, HAProxy will check when
1149 the server sets such a cookie, and will store its value in a table, and
1150 associate it with the server's identifier. Up to <length> characters from
1151 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001152 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1153 the mode used). If a known value is found, the client will be directed to the
1154 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001155 applied. Cookies are automatically removed from memory when they have been
1156 unused for a duration longer than <holdtime>.
1157
1158 The definition of an application cookie is limited to one per backend.
1159
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001160 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1161 unless you know what you do : memory is not shared between the
1162 processes, which can result in random behaviours.
1163
Willy Tarreau0ba27502007-12-24 16:55:16 +01001164 Example :
1165 appsession JSESSIONID len 52 timeout 3h
1166
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001167 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1168 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001169
1170
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001171backlog <conns>
1172 Give hints to the system about the approximate listen backlog desired size
1173 May be used in sections : defaults | frontend | listen | backend
1174 yes | yes | yes | no
1175 Arguments :
1176 <conns> is the number of pending connections. Depending on the operating
1177 system, it may represent the number of already acknowledged
1178 connections, of non-acknowledged ones, or both.
1179
1180 In order to protect against SYN flood attacks, one solution is to increase
1181 the system's SYN backlog size. Depending on the system, sometimes it is just
1182 tunable via a system parameter, sometimes it is not adjustable at all, and
1183 sometimes the system relies on hints given by the application at the time of
1184 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1185 to the listen() syscall. On systems which can make use of this value, it can
1186 sometimes be useful to be able to specify a different value, hence this
1187 backlog parameter.
1188
1189 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1190 used as a hint and the system accepts up to the smallest greater power of
1191 two, and never more than some limits (usually 32768).
1192
1193 See also : "maxconn" and the target operating system's tuning guide.
1194
1195
Willy Tarreau0ba27502007-12-24 16:55:16 +01001196balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001197balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001198 Define the load balancing algorithm to be used in a backend.
1199 May be used in sections : defaults | frontend | listen | backend
1200 yes | no | yes | yes
1201 Arguments :
1202 <algorithm> is the algorithm used to select a server when doing load
1203 balancing. This only applies when no persistence information
1204 is available, or when a connection is redispatched to another
1205 server. <algorithm> may be one of the following :
1206
1207 roundrobin Each server is used in turns, according to their weights.
1208 This is the smoothest and fairest algorithm when the server's
1209 processing time remains equally distributed. This algorithm
1210 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001211 on the fly for slow starts for instance. It is limited by
1212 design to 4128 active servers per backend. Note that in some
1213 large farms, when a server becomes up after having been down
1214 for a very short time, it may sometimes take a few hundreds
1215 requests for it to be re-integrated into the farm and start
1216 receiving traffic. This is normal, though very rare. It is
1217 indicated here in case you would have the chance to observe
1218 it, so that you don't worry.
1219
1220 static-rr Each server is used in turns, according to their weights.
1221 This algorithm is as similar to roundrobin except that it is
1222 static, which means that changing a server's weight on the
1223 fly will have no effect. On the other hand, it has no design
1224 limitation on the number of servers, and when a server goes
1225 up, it is always immediately reintroduced into the farm, once
1226 the full map is recomputed. It also uses slightly less CPU to
1227 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001228
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001229 leastconn The server with the lowest number of connections receives the
1230 connection. Round-robin is performed within groups of servers
1231 of the same load to ensure that all servers will be used. Use
1232 of this algorithm is recommended where very long sessions are
1233 expected, such as LDAP, SQL, TSE, etc... but is not very well
1234 suited for protocols using short sessions such as HTTP. This
1235 algorithm is dynamic, which means that server weights may be
1236 adjusted on the fly for slow starts for instance.
1237
Willy Tarreau0ba27502007-12-24 16:55:16 +01001238 source The source IP address is hashed and divided by the total
1239 weight of the running servers to designate which server will
1240 receive the request. This ensures that the same client IP
1241 address will always reach the same server as long as no
1242 server goes down or up. If the hash result changes due to the
1243 number of running servers changing, many clients will be
1244 directed to a different server. This algorithm is generally
1245 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001246 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001247 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001248 static by default, which means that changing a server's
1249 weight on the fly will have no effect, but this can be
1250 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001251
1252 uri The left part of the URI (before the question mark) is hashed
1253 and divided by the total weight of the running servers. The
1254 result designates which server will receive the request. This
1255 ensures that a same URI will always be directed to the same
1256 server as long as no server goes up or down. This is used
1257 with proxy caches and anti-virus proxies in order to maximize
1258 the cache hit rate. Note that this algorithm may only be used
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001259 in an HTTP backend. This algorithm is static by default,
1260 which means that changing a server's weight on the fly will
1261 have no effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001262
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001263 This algorithm support two optional parameters "len" and
1264 "depth", both followed by a positive integer number. These
1265 options may be helpful when it is needed to balance servers
1266 based on the beginning of the URI only. The "len" parameter
1267 indicates that the algorithm should only consider that many
1268 characters at the beginning of the URI to compute the hash.
1269 Note that having "len" set to 1 rarely makes sense since most
1270 URIs start with a leading "/".
1271
1272 The "depth" parameter indicates the maximum directory depth
1273 to be used to compute the hash. One level is counted for each
1274 slash in the request. If both parameters are specified, the
1275 evaluation stops when either is reached.
1276
Willy Tarreau0ba27502007-12-24 16:55:16 +01001277 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001278 the query string of each HTTP GET request.
1279
1280 If the modifier "check_post" is used, then an HTTP POST
1281 request entity will be searched for the parameter argument,
Willy Tarreau61a21a32011-03-01 20:35:49 +01001282 when it is not found in a query string after a question mark
1283 ('?') in the URL. Optionally, specify a number of octets to
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001284 wait for before attempting to search the message body. If the
1285 entity can not be searched, then round robin is used for each
1286 request. For instance, if your clients always send the LB
1287 parameter in the first 128 bytes, then specify that. The
1288 default is 48. The entity data will not be scanned until the
1289 required number of octets have arrived at the gateway, this
1290 is the minimum of: (default/max_wait, Content-Length or first
1291 chunk length). If Content-Length is missing or zero, it does
1292 not need to wait for more data than the client promised to
1293 send. When Content-Length is present and larger than
1294 <max_wait>, then waiting is limited to <max_wait> and it is
1295 assumed that this will be enough data to search for the
1296 presence of the parameter. In the unlikely event that
1297 Transfer-Encoding: chunked is used, only the first chunk is
1298 scanned. Parameter values separated by a chunk boundary, may
1299 be randomly balanced if at all.
1300
1301 If the parameter is found followed by an equal sign ('=') and
1302 a value, then the value is hashed and divided by the total
1303 weight of the running servers. The result designates which
1304 server will receive the request.
1305
1306 This is used to track user identifiers in requests and ensure
1307 that a same user ID will always be sent to the same server as
1308 long as no server goes up or down. If no value is found or if
1309 the parameter is not found, then a round robin algorithm is
1310 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001311 backend. This algorithm is static by default, which means
1312 that changing a server's weight on the fly will have no
1313 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001314
Benoitaffb4812009-03-25 13:02:10 +01001315 hdr(name) The HTTP header <name> will be looked up in each HTTP request.
1316 Just as with the equivalent ACL 'hdr()' function, the header
1317 name in parenthesis is not case sensitive. If the header is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001318 absent or if it does not contain any value, the roundrobin
Benoitaffb4812009-03-25 13:02:10 +01001319 algorithm is applied instead.
1320
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001321 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001322 reducing the hash algorithm to the main domain part with some
1323 specific headers such as 'Host'. For instance, in the Host
1324 value "haproxy.1wt.eu", only "1wt" will be considered.
1325
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001326 This algorithm is static by default, which means that
1327 changing a server's weight on the fly will have no effect,
1328 but this can be changed using "hash-type".
1329
Emeric Brun736aa232009-06-30 17:56:00 +02001330 rdp-cookie
1331 rdp-cookie(name)
1332 The RDP cookie <name> (or "mstshash" if omitted) will be
1333 looked up and hashed for each incoming TCP request. Just as
1334 with the equivalent ACL 'req_rdp_cookie()' function, the name
1335 is not case-sensitive. This mechanism is useful as a degraded
1336 persistence mode, as it makes it possible to always send the
1337 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001338 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001339 used instead.
1340
1341 Note that for this to work, the frontend must ensure that an
1342 RDP cookie is already present in the request buffer. For this
1343 you must use 'tcp-request content accept' rule combined with
1344 a 'req_rdp_cookie_cnt' ACL.
1345
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001346 This algorithm is static by default, which means that
1347 changing a server's weight on the fly will have no effect,
1348 but this can be changed using "hash-type".
1349
Willy Tarreau0ba27502007-12-24 16:55:16 +01001350 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001351 algorithms. Right now, only "url_param" and "uri" support an
1352 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001353
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001354 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001355 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001356
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001357 The load balancing algorithm of a backend is set to roundrobin when no other
1358 algorithm, mode nor option have been set. The algorithm may only be set once
1359 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001360
1361 Examples :
1362 balance roundrobin
1363 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001364 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001365 balance hdr(User-Agent)
1366 balance hdr(host)
1367 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001368
1369 Note: the following caveats and limitations on using the "check_post"
1370 extension with "url_param" must be considered :
1371
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001372 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001373 to determine if the parameters will be found in the body or entity which
1374 may contain binary data. Therefore another method may be required to
1375 restrict consideration of POST requests that have no URL parameters in
1376 the body. (see acl reqideny http_end)
1377
1378 - using a <max_wait> value larger than the request buffer size does not
1379 make sense and is useless. The buffer size is set at build time, and
1380 defaults to 16 kB.
1381
1382 - Content-Encoding is not supported, the parameter search will probably
1383 fail; and load balancing will fall back to Round Robin.
1384
1385 - Expect: 100-continue is not supported, load balancing will fall back to
1386 Round Robin.
1387
1388 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1389 If the entire parameter value is not present in the first chunk, the
1390 selection of server is undefined (actually, defined by how little
1391 actually appeared in the first chunk).
1392
1393 - This feature does not support generation of a 100, 411 or 501 response.
1394
1395 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001396 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001397 white space or control characters are found, indicating the end of what
1398 might be a URL parameter list. This is probably not a concern with SGML
1399 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001400
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001401 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1402 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001403
1404
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001405bind [<address>]:<port_range> [, ...]
1406bind [<address>]:<port_range> [, ...] interface <interface>
1407bind [<address>]:<port_range> [, ...] mss <maxseg>
1408bind [<address>]:<port_range> [, ...] transparent
1409bind [<address>]:<port_range> [, ...] id <id>
1410bind [<address>]:<port_range> [, ...] name <name>
1411bind [<address>]:<port_range> [, ...] defer-accept
Willy Tarreau71c814e2010-10-29 21:56:16 +02001412bind [<address>]:<port_range> [, ...] accept-proxy
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001413bind /<path> [, ...]
1414bind /<path> [, ...] mode <mode>
1415bind /<path> [, ...] [ user <user> | uid <uid> ]
1416bind /<path> [, ...] [ group <user> | gid <gid> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001417 Define one or several listening addresses and/or ports in a frontend.
1418 May be used in sections : defaults | frontend | listen | backend
1419 no | yes | yes | no
1420 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001421 <address> is optional and can be a host name, an IPv4 address, an IPv6
1422 address, or '*'. It designates the address the frontend will
1423 listen on. If unset, all IPv4 addresses of the system will be
1424 listened on. The same will apply for '*' or the system's
1425 special address "0.0.0.0".
1426
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001427 <port_range> is either a unique TCP port, or a port range for which the
1428 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001429 above. The port is mandatory for TCP listeners. Note that in
1430 the case of an IPv6 address, the port is always the number
1431 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001432 - a numerical port (ex: '80')
1433 - a dash-delimited ports range explicitly stating the lower
1434 and upper bounds (ex: '2000-2100') which are included in
1435 the range.
1436
1437 Particular care must be taken against port ranges, because
1438 every <address:port> couple consumes one socket (= a file
1439 descriptor), so it's easy to consume lots of descriptors
1440 with a simple range, and to run out of sockets. Also, each
1441 <address:port> couple must be used only once among all
1442 instances running on a same system. Please note that binding
1443 to ports lower than 1024 generally require particular
1444 privileges to start the program, which are independant of
1445 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001446
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001447 <path> is a UNIX socket path beginning with a slash ('/'). This is
1448 alternative to the TCP listening port. Haproxy will then
1449 receive UNIX connections on the socket located at this place.
1450 The path must begin with a slash and by default is absolute.
1451 It can be relative to the prefix defined by "unix-bind" in
1452 the global section. Note that the total length of the prefix
1453 followed by the socket path cannot exceed some system limits
1454 for UNIX sockets, which commonly are set to 107 characters.
1455
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001456 <interface> is an optional physical interface name. This is currently
1457 only supported on Linux. The interface must be a physical
1458 interface, not an aliased interface. When specified, all
1459 addresses on the same line will only be accepted if the
1460 incoming packet physically come through the designated
1461 interface. It is also possible to bind multiple frontends to
1462 the same address if they are bound to different interfaces.
1463 Note that binding to a physical interface requires root
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001464 privileges. This parameter is only compatible with TCP
1465 sockets.
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001466
Willy Tarreaube1b9182009-06-14 18:48:19 +02001467 <maxseg> is an optional TCP Maximum Segment Size (MSS) value to be
1468 advertised on incoming connections. This can be used to force
1469 a lower MSS for certain specific ports, for instance for
1470 connections passing through a VPN. Note that this relies on a
1471 kernel feature which is theorically supported under Linux but
1472 was buggy in all versions prior to 2.6.28. It may or may not
Willy Tarreau48a7e722010-12-24 15:26:39 +01001473 work on other operating systems. It may also not change the
1474 advertised value but change the effective size of outgoing
1475 segments. The commonly advertised value on Ethernet networks
1476 is 1460 = 1500(MTU) - 40(IP+TCP). If this value is positive,
1477 it will be used as the advertised MSS. If it is negative, it
1478 will indicate by how much to reduce the incoming connection's
1479 advertised MSS for outgoing segments. This parameter is only
1480 compatible with TCP sockets.
Willy Tarreaube1b9182009-06-14 18:48:19 +02001481
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02001482 <id> is a persistent value for socket ID. Must be positive and
1483 unique in the proxy. An unused value will automatically be
1484 assigned if unset. Can only be used when defining only a
1485 single socket.
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02001486
1487 <name> is an optional name provided for stats
1488
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001489 <mode> is the octal mode used to define access permissions on the
1490 UNIX socket. It can also be set by default in the global
1491 section's "unix-bind" statement. Note that some platforms
1492 simply ignore this.
1493
1494 <user> is the name of user that will be marked owner of the UNIX
1495 socket. It can also be set by default in the global
1496 section's "unix-bind" statement. Note that some platforms
1497 simply ignore this.
1498
1499 <group> is the name of a group that will be used to create the UNIX
1500 socket. It can also be set by default in the global section's
1501 "unix-bind" statement. Note that some platforms simply ignore
1502 this.
1503
1504 <uid> is the uid of user that will be marked owner of the UNIX
1505 socket. It can also be set by default in the global section's
1506 "unix-bind" statement. Note that some platforms simply ignore
1507 this.
1508
1509 <gid> is the gid of a group that will be used to create the UNIX
1510 socket. It can also be set by default in the global section's
1511 "unix-bind" statement. Note that some platforms simply ignore
1512 this.
1513
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001514 transparent is an optional keyword which is supported only on certain
1515 Linux kernels. It indicates that the addresses will be bound
1516 even if they do not belong to the local machine. Any packet
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001517 targeting any of these addresses will be caught just as if
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001518 the address was locally configured. This normally requires
1519 that IP forwarding is enabled. Caution! do not use this with
1520 the default address '*', as it would redirect any traffic for
1521 the specified port. This keyword is available only when
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001522 HAProxy is built with USE_LINUX_TPROXY=1. This parameter is
1523 only compatible with TCP sockets.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001524
Willy Tarreau59f89202010-10-02 11:54:00 +02001525 defer-accept is an optional keyword which is supported only on certain
Willy Tarreaucb6cd432009-10-13 07:34:14 +02001526 Linux kernels. It states that a connection will only be
1527 accepted once some data arrive on it, or at worst after the
1528 first retransmit. This should be used only on protocols for
1529 which the client talks first (eg: HTTP). It can slightly
1530 improve performance by ensuring that most of the request is
1531 already available when the connection is accepted. On the
1532 other hand, it will not be able to detect connections which
1533 don't talk. It is important to note that this option is
1534 broken in all kernels up to 2.6.31, as the connection is
1535 never accepted until the client talks. This can cause issues
1536 with front firewalls which would see an established
1537 connection while the proxy will only see it in SYN_RECV.
1538
Willy Tarreau71c814e2010-10-29 21:56:16 +02001539 accept-proxy is an optional keyword which enforces use of the PROXY
1540 protocol over any connection accepted by this listener. The
1541 PROXY protocol dictates the layer 3/4 addresses of the
1542 incoming connection to be used everywhere an address is used,
1543 with the only exception of "tcp-request connection" rules
1544 which will only see the real connection address. Logs will
1545 reflect the addresses indicated in the protocol, unless it is
1546 violated, in which case the real address will still be used.
1547 This keyword combined with support from external components
1548 can be used as an efficient and reliable alternative to the
1549 X-Forwarded-For mechanism which is not always reliable and
1550 not even always usable.
1551
Willy Tarreau0ba27502007-12-24 16:55:16 +01001552 It is possible to specify a list of address:port combinations delimited by
1553 commas. The frontend will then listen on all of these addresses. There is no
1554 fixed limit to the number of addresses and ports which can be listened on in
1555 a frontend, as well as there is no limit to the number of "bind" statements
1556 in a frontend.
1557
1558 Example :
1559 listen http_proxy
1560 bind :80,:443
1561 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001562 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001563
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001564 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreau71c814e2010-10-29 21:56:16 +02001565 documentation.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001566
1567
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001568bind-process [ all | odd | even | <number 1-32> ] ...
1569 Limit visibility of an instance to a certain set of processes numbers.
1570 May be used in sections : defaults | frontend | listen | backend
1571 yes | yes | yes | yes
1572 Arguments :
1573 all All process will see this instance. This is the default. It
1574 may be used to override a default value.
1575
1576 odd This instance will be enabled on processes 1,3,5,...31. This
1577 option may be combined with other numbers.
1578
1579 even This instance will be enabled on processes 2,4,6,...32. This
1580 option may be combined with other numbers. Do not use it
1581 with less than 2 processes otherwise some instances might be
1582 missing from all processes.
1583
1584 number The instance will be enabled on this process number, between
1585 1 and 32. You must be careful not to reference a process
1586 number greater than the configured global.nbproc, otherwise
1587 some instances might be missing from all processes.
1588
1589 This keyword limits binding of certain instances to certain processes. This
1590 is useful in order not to have too many processes listening to the same
1591 ports. For instance, on a dual-core machine, it might make sense to set
1592 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1593 and 'even' instances.
1594
1595 At the moment, it is not possible to reference more than 32 processes using
1596 this keyword, but this should be more than enough for most setups. Please
1597 note that 'all' really means all processes and is not limited to the first
1598 32.
1599
1600 If some backends are referenced by frontends bound to other processes, the
1601 backend automatically inherits the frontend's processes.
1602
1603 Example :
1604 listen app_ip1
1605 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001606 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001607
1608 listen app_ip2
1609 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001610 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001611
1612 listen management
1613 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001614 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001615
1616 See also : "nbproc" in global section.
1617
1618
Willy Tarreau0ba27502007-12-24 16:55:16 +01001619block { if | unless } <condition>
1620 Block a layer 7 request if/unless a condition is matched
1621 May be used in sections : defaults | frontend | listen | backend
1622 no | yes | yes | yes
1623
1624 The HTTP request will be blocked very early in the layer 7 processing
1625 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001626 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001627 typically used to deny access to certain sensible resources if some
1628 conditions are met or not met. There is no fixed limit to the number of
1629 "block" statements per instance.
1630
1631 Example:
1632 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1633 acl invalid_src src_port 0:1023
1634 acl local_dst hdr(host) -i localhost
1635 block if invalid_src || local_dst
1636
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001637 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001638
1639
1640capture cookie <name> len <length>
1641 Capture and log a cookie in the request and in the response.
1642 May be used in sections : defaults | frontend | listen | backend
1643 no | yes | yes | no
1644 Arguments :
1645 <name> is the beginning of the name of the cookie to capture. In order
1646 to match the exact name, simply suffix the name with an equal
1647 sign ('='). The full name will appear in the logs, which is
1648 useful with application servers which adjust both the cookie name
1649 and value (eg: ASPSESSIONXXXXX).
1650
1651 <length> is the maximum number of characters to report in the logs, which
1652 include the cookie name, the equal sign and the value, all in the
1653 standard "name=value" form. The string will be truncated on the
1654 right if it exceeds <length>.
1655
1656 Only the first cookie is captured. Both the "cookie" request headers and the
1657 "set-cookie" response headers are monitored. This is particularly useful to
1658 check for application bugs causing session crossing or stealing between
1659 users, because generally the user's cookies can only change on a login page.
1660
1661 When the cookie was not presented by the client, the associated log column
1662 will report "-". When a request does not cause a cookie to be assigned by the
1663 server, a "-" is reported in the response column.
1664
1665 The capture is performed in the frontend only because it is necessary that
1666 the log format does not change for a given frontend depending on the
1667 backends. This may change in the future. Note that there can be only one
1668 "capture cookie" statement in a frontend. The maximum capture length is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001669 configured in the sources by default to 64 characters. It is not possible to
Willy Tarreau0ba27502007-12-24 16:55:16 +01001670 specify a capture in a "defaults" section.
1671
1672 Example:
1673 capture cookie ASPSESSION len 32
1674
1675 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001676 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001677
1678
1679capture request header <name> len <length>
1680 Capture and log the first occurrence of the specified request header.
1681 May be used in sections : defaults | frontend | listen | backend
1682 no | yes | yes | no
1683 Arguments :
1684 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001685 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001686 appear in the requests, with the first letter of each word in
1687 upper case. The header name will not appear in the logs, only the
1688 value is reported, but the position in the logs is respected.
1689
1690 <length> is the maximum number of characters to extract from the value and
1691 report in the logs. The string will be truncated on the right if
1692 it exceeds <length>.
1693
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001694 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001695 value will be added to the logs between braces ('{}'). If multiple headers
1696 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001697 in the same order they were declared in the configuration. Non-existent
1698 headers will be logged just as an empty string. Common uses for request
1699 header captures include the "Host" field in virtual hosting environments, the
1700 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001701 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001702 environments to find where the request came from.
1703
1704 Note that when capturing headers such as "User-agent", some spaces may be
1705 logged, making the log analysis more difficult. Thus be careful about what
1706 you log if you know your log parser is not smart enough to rely on the
1707 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001708
1709 There is no limit to the number of captured request headers, but each capture
1710 is limited to 64 characters. In order to keep log format consistent for a
1711 same frontend, header captures can only be declared in a frontend. It is not
1712 possible to specify a capture in a "defaults" section.
1713
1714 Example:
1715 capture request header Host len 15
1716 capture request header X-Forwarded-For len 15
1717 capture request header Referrer len 15
1718
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001719 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001720 about logging.
1721
1722
1723capture response header <name> len <length>
1724 Capture and log the first occurrence of the specified response header.
1725 May be used in sections : defaults | frontend | listen | backend
1726 no | yes | yes | no
1727 Arguments :
1728 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001729 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001730 appear in the response, with the first letter of each word in
1731 upper case. The header name will not appear in the logs, only the
1732 value is reported, but the position in the logs is respected.
1733
1734 <length> is the maximum number of characters to extract from the value and
1735 report in the logs. The string will be truncated on the right if
1736 it exceeds <length>.
1737
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001738 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001739 result will be added to the logs between braces ('{}') after the captured
1740 request headers. If multiple headers are captured, they will be delimited by
1741 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001742 the configuration. Non-existent headers will be logged just as an empty
1743 string. Common uses for response header captures include the "Content-length"
1744 header which indicates how many bytes are expected to be returned, the
1745 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001746
1747 There is no limit to the number of captured response headers, but each
1748 capture is limited to 64 characters. In order to keep log format consistent
1749 for a same frontend, header captures can only be declared in a frontend. It
1750 is not possible to specify a capture in a "defaults" section.
1751
1752 Example:
1753 capture response header Content-length len 9
1754 capture response header Location len 15
1755
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001756 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001757 about logging.
1758
1759
Cyril Bontéf0c60612010-02-06 14:44:47 +01001760clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001761 Set the maximum inactivity time on the client side.
1762 May be used in sections : defaults | frontend | listen | backend
1763 yes | yes | yes | no
1764 Arguments :
1765 <timeout> is the timeout value is specified in milliseconds by default, but
1766 can be in any other unit if the number is suffixed by the unit,
1767 as explained at the top of this document.
1768
1769 The inactivity timeout applies when the client is expected to acknowledge or
1770 send data. In HTTP mode, this timeout is particularly important to consider
1771 during the first phase, when the client sends the request, and during the
1772 response while it is reading data sent by the server. The value is specified
1773 in milliseconds by default, but can be in any other unit if the number is
1774 suffixed by the unit, as specified at the top of this document. In TCP mode
1775 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1776 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001777 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001778 losses by specifying timeouts that are slightly above multiples of 3 seconds
1779 (eg: 4 or 5 seconds).
1780
1781 This parameter is specific to frontends, but can be specified once for all in
1782 "defaults" sections. This is in fact one of the easiest solutions not to
1783 forget about it. An unspecified timeout results in an infinite timeout, which
1784 is not recommended. Such a usage is accepted and works but reports a warning
1785 during startup because it may results in accumulation of expired sessions in
1786 the system if the system's timeouts are not configured either.
1787
1788 This parameter is provided for compatibility but is currently deprecated.
1789 Please use "timeout client" instead.
1790
Willy Tarreau036fae02008-01-06 13:24:40 +01001791 See also : "timeout client", "timeout http-request", "timeout server", and
1792 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001793
1794
Cyril Bontéf0c60612010-02-06 14:44:47 +01001795contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001796 Set the maximum time to wait for a connection attempt to a server to succeed.
1797 May be used in sections : defaults | frontend | listen | backend
1798 yes | no | yes | yes
1799 Arguments :
1800 <timeout> is the timeout value is specified in milliseconds by default, but
1801 can be in any other unit if the number is suffixed by the unit,
1802 as explained at the top of this document.
1803
1804 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001805 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01001806 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01001807 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
1808 connect timeout also presets the queue timeout to the same value if this one
1809 has not been specified. Historically, the contimeout was also used to set the
1810 tarpit timeout in a listen section, which is not possible in a pure frontend.
1811
1812 This parameter is specific to backends, but can be specified once for all in
1813 "defaults" sections. This is in fact one of the easiest solutions not to
1814 forget about it. An unspecified timeout results in an infinite timeout, which
1815 is not recommended. Such a usage is accepted and works but reports a warning
1816 during startup because it may results in accumulation of failed sessions in
1817 the system if the system's timeouts are not configured either.
1818
1819 This parameter is provided for backwards compatibility but is currently
1820 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
1821 instead.
1822
1823 See also : "timeout connect", "timeout queue", "timeout tarpit",
1824 "timeout server", "contimeout".
1825
1826
Willy Tarreau55165fe2009-05-10 12:02:55 +02001827cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001828 [ postonly ] [ preserve ] [ domain <domain> ]*
Willy Tarreau996a92c2010-10-13 19:30:47 +02001829 [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001830 Enable cookie-based persistence in a backend.
1831 May be used in sections : defaults | frontend | listen | backend
1832 yes | no | yes | yes
1833 Arguments :
1834 <name> is the name of the cookie which will be monitored, modified or
1835 inserted in order to bring persistence. This cookie is sent to
1836 the client via a "Set-Cookie" header in the response, and is
1837 brought back by the client in a "Cookie" header in all requests.
1838 Special care should be taken to choose a name which does not
1839 conflict with any likely application cookie. Also, if the same
1840 backends are subject to be used by the same clients (eg:
1841 HTTP/HTTPS), care should be taken to use different cookie names
1842 between all backends if persistence between them is not desired.
1843
1844 rewrite This keyword indicates that the cookie will be provided by the
1845 server and that haproxy will have to modify its value to set the
1846 server's identifier in it. This mode is handy when the management
1847 of complex combinations of "Set-cookie" and "Cache-control"
1848 headers is left to the application. The application can then
1849 decide whether or not it is appropriate to emit a persistence
1850 cookie. Since all responses should be monitored, this mode only
1851 works in HTTP close mode. Unless the application behaviour is
1852 very complex and/or broken, it is advised not to start with this
1853 mode for new deployments. This keyword is incompatible with
1854 "insert" and "prefix".
1855
1856 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02001857 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001858
Willy Tarreaua79094d2010-08-31 22:54:15 +02001859 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001860 server. When used without the "preserve" option, if the server
1861 emits a cookie with the same name, it will be remove before
1862 processing. For this reason, this mode can be used to upgrade
1863 existing configurations running in the "rewrite" mode. The cookie
1864 will only be a session cookie and will not be stored on the
1865 client's disk. By default, unless the "indirect" option is added,
1866 the server will see the cookies emitted by the client. Due to
1867 caching effects, it is generally wise to add the "nocache" or
1868 "postonly" keywords (see below). The "insert" keyword is not
1869 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001870
1871 prefix This keyword indicates that instead of relying on a dedicated
1872 cookie for the persistence, an existing one will be completed.
1873 This may be needed in some specific environments where the client
1874 does not support more than one single cookie and the application
1875 already needs it. In this case, whenever the server sets a cookie
1876 named <name>, it will be prefixed with the server's identifier
1877 and a delimiter. The prefix will be removed from all client
1878 requests so that the server still finds the cookie it emitted.
1879 Since all requests and responses are subject to being modified,
1880 this mode requires the HTTP close mode. The "prefix" keyword is
1881 not compatible with "rewrite" and "insert".
1882
Willy Tarreaua79094d2010-08-31 22:54:15 +02001883 indirect When this option is specified, no cookie will be emitted to a
1884 client which already has a valid one for the server which has
1885 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001886 it will be removed, unless the "preserve" option is also set. In
1887 "insert" mode, this will additionally remove cookies from the
1888 requests transmitted to the server, making the persistence
1889 mechanism totally transparent from an application point of view.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001890
1891 nocache This option is recommended in conjunction with the insert mode
1892 when there is a cache between the client and HAProxy, as it
1893 ensures that a cacheable response will be tagged non-cacheable if
1894 a cookie needs to be inserted. This is important because if all
1895 persistence cookies are added on a cacheable home page for
1896 instance, then all customers will then fetch the page from an
1897 outer cache and will all share the same persistence cookie,
1898 leading to one server receiving much more traffic than others.
1899 See also the "insert" and "postonly" options.
1900
1901 postonly This option ensures that cookie insertion will only be performed
1902 on responses to POST requests. It is an alternative to the
1903 "nocache" option, because POST responses are not cacheable, so
1904 this ensures that the persistence cookie will never get cached.
1905 Since most sites do not need any sort of persistence before the
1906 first POST which generally is a login request, this is a very
1907 efficient method to optimize caching without risking to find a
1908 persistence cookie in the cache.
1909 See also the "insert" and "nocache" options.
1910
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001911 preserve This option may only be used with "insert" and/or "indirect". It
1912 allows the server to emit the persistence cookie itself. In this
1913 case, if a cookie is found in the response, haproxy will leave it
1914 untouched. This is useful in order to end persistence after a
1915 logout request for instance. For this, the server just has to
1916 emit a cookie with an invalid value (eg: empty) or with a date in
1917 the past. By combining this mechanism with the "disable-on-404"
1918 check option, it is possible to perform a completely graceful
1919 shutdown because users will definitely leave the server after
1920 they logout.
1921
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001922 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001923 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01001924 name. If the domain begins with a dot, the browser is allowed to
1925 use it for any host ending with that name. It is also possible to
1926 specify several domain names by invoking this option multiple
1927 times. Some browsers might have small limits on the number of
1928 domains, so be careful when doing that. For the record, sending
1929 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001930
Willy Tarreau996a92c2010-10-13 19:30:47 +02001931 maxidle This option allows inserted cookies to be ignored after some idle
1932 time. It only works with insert-mode cookies. When a cookie is
1933 sent to the client, the date this cookie was emitted is sent too.
1934 Upon further presentations of this cookie, if the date is older
1935 than the delay indicated by the parameter (in seconds), it will
1936 be ignored. Otherwise, it will be refreshed if needed when the
1937 response is sent to the client. This is particularly useful to
1938 prevent users who never close their browsers from remaining for
1939 too long on the same server (eg: after a farm size change). When
1940 this option is set and a cookie has no date, it is always
1941 accepted, but gets refreshed in the response. This maintains the
1942 ability for admins to access their sites. Cookies that have a
1943 date in the future further than 24 hours are ignored. Doing so
1944 lets admins fix timezone issues without risking kicking users off
1945 the site.
1946
1947 maxlife This option allows inserted cookies to be ignored after some life
1948 time, whether they're in use or not. It only works with insert
1949 mode cookies. When a cookie is first sent to the client, the date
1950 this cookie was emitted is sent too. Upon further presentations
1951 of this cookie, if the date is older than the delay indicated by
1952 the parameter (in seconds), it will be ignored. If the cookie in
1953 the request has no date, it is accepted and a date will be set.
1954 Cookies that have a date in the future further than 24 hours are
1955 ignored. Doing so lets admins fix timezone issues without risking
1956 kicking users off the site. Contrary to maxidle, this value is
1957 not refreshed, only the first visit date counts. Both maxidle and
1958 maxlife may be used at the time. This is particularly useful to
1959 prevent users who never close their browsers from remaining for
1960 too long on the same server (eg: after a farm size change). This
1961 is stronger than the maxidle method in that it forces a
1962 redispatch after some absolute delay.
1963
Willy Tarreau0ba27502007-12-24 16:55:16 +01001964 There can be only one persistence cookie per HTTP backend, and it can be
1965 declared in a defaults section. The value of the cookie will be the value
1966 indicated after the "cookie" keyword in a "server" statement. If no cookie
1967 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001968
Willy Tarreau0ba27502007-12-24 16:55:16 +01001969 Examples :
1970 cookie JSESSIONID prefix
1971 cookie SRV insert indirect nocache
1972 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02001973 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01001974
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02001975 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001976 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001977
Willy Tarreau983e01e2010-01-11 18:42:06 +01001978
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001979default-server [param*]
1980 Change default options for a server in a backend
1981 May be used in sections : defaults | frontend | listen | backend
1982 yes | no | yes | yes
1983 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01001984 <param*> is a list of parameters for this server. The "default-server"
1985 keyword accepts an important number of options and has a complete
1986 section dedicated to it. Please refer to section 5 for more
1987 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001988
Willy Tarreau983e01e2010-01-11 18:42:06 +01001989 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01001990 default-server inter 1000 weight 13
1991
1992 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01001993
Willy Tarreau983e01e2010-01-11 18:42:06 +01001994
Willy Tarreau0ba27502007-12-24 16:55:16 +01001995default_backend <backend>
1996 Specify the backend to use when no "use_backend" rule has been matched.
1997 May be used in sections : defaults | frontend | listen | backend
1998 yes | yes | yes | no
1999 Arguments :
2000 <backend> is the name of the backend to use.
2001
2002 When doing content-switching between frontend and backends using the
2003 "use_backend" keyword, it is often useful to indicate which backend will be
2004 used when no rule has matched. It generally is the dynamic backend which
2005 will catch all undetermined requests.
2006
Willy Tarreau0ba27502007-12-24 16:55:16 +01002007 Example :
2008
2009 use_backend dynamic if url_dyn
2010 use_backend static if url_css url_img extension_img
2011 default_backend dynamic
2012
Willy Tarreau2769aa02007-12-27 18:26:09 +01002013 See also : "use_backend", "reqsetbe", "reqisetbe"
2014
Willy Tarreau0ba27502007-12-24 16:55:16 +01002015
2016disabled
2017 Disable a proxy, frontend or backend.
2018 May be used in sections : defaults | frontend | listen | backend
2019 yes | yes | yes | yes
2020 Arguments : none
2021
2022 The "disabled" keyword is used to disable an instance, mainly in order to
2023 liberate a listening port or to temporarily disable a service. The instance
2024 will still be created and its configuration will be checked, but it will be
2025 created in the "stopped" state and will appear as such in the statistics. It
2026 will not receive any traffic nor will it send any health-checks or logs. It
2027 is possible to disable many instances at once by adding the "disabled"
2028 keyword in a "defaults" section.
2029
2030 See also : "enabled"
2031
2032
Willy Tarreau5ce94572010-06-07 14:35:41 +02002033dispatch <address>:<port>
2034 Set a default server address
2035 May be used in sections : defaults | frontend | listen | backend
2036 no | no | yes | yes
2037 Arguments : none
2038
2039 <address> is the IPv4 address of the default server. Alternatively, a
2040 resolvable hostname is supported, but this name will be resolved
2041 during start-up.
2042
2043 <ports> is a mandatory port specification. All connections will be sent
2044 to this port, and it is not permitted to use port offsets as is
2045 possible with normal servers.
2046
2047 The "disabled" keyword designates a default server for use when no other
2048 server can take the connection. In the past it was used to forward non
2049 persistent connections to an auxiliary load balancer. Due to its simple
2050 syntax, it has also been used for simple TCP relays. It is recommended not to
2051 use it for more clarity, and to use the "server" directive instead.
2052
2053 See also : "server"
2054
2055
Willy Tarreau0ba27502007-12-24 16:55:16 +01002056enabled
2057 Enable a proxy, frontend or backend.
2058 May be used in sections : defaults | frontend | listen | backend
2059 yes | yes | yes | yes
2060 Arguments : none
2061
2062 The "enabled" keyword is used to explicitly enable an instance, when the
2063 defaults has been set to "disabled". This is very rarely used.
2064
2065 See also : "disabled"
2066
2067
2068errorfile <code> <file>
2069 Return a file contents instead of errors generated by HAProxy
2070 May be used in sections : defaults | frontend | listen | backend
2071 yes | yes | yes | yes
2072 Arguments :
2073 <code> is the HTTP status code. Currently, HAProxy is capable of
2074 generating codes 400, 403, 408, 500, 502, 503, and 504.
2075
2076 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002077 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002078 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002079 error pages, and to use absolute paths, since files are read
2080 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002081
2082 It is important to understand that this keyword is not meant to rewrite
2083 errors returned by the server, but errors detected and returned by HAProxy.
2084 This is why the list of supported errors is limited to a small set.
2085
2086 The files are returned verbatim on the TCP socket. This allows any trick such
2087 as redirections to another URL or site, as well as tricks to clean cookies,
2088 force enable or disable caching, etc... The package provides default error
2089 files returning the same contents as default errors.
2090
Willy Tarreau59140a22009-02-22 12:02:30 +01002091 The files should not exceed the configured buffer size (BUFSIZE), which
2092 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2093 not to put any reference to local contents (eg: images) in order to avoid
2094 loops between the client and HAProxy when all servers are down, causing an
2095 error to be returned instead of an image. For better HTTP compliance, it is
2096 recommended that all header lines end with CR-LF and not LF alone.
2097
Willy Tarreau0ba27502007-12-24 16:55:16 +01002098 The files are read at the same time as the configuration and kept in memory.
2099 For this reason, the errors continue to be returned even when the process is
2100 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002101 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002102 403 status code and interrogating a blocked URL.
2103
2104 See also : "errorloc", "errorloc302", "errorloc303"
2105
Willy Tarreau59140a22009-02-22 12:02:30 +01002106 Example :
2107 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2108 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2109 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2110
Willy Tarreau2769aa02007-12-27 18:26:09 +01002111
2112errorloc <code> <url>
2113errorloc302 <code> <url>
2114 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2115 May be used in sections : defaults | frontend | listen | backend
2116 yes | yes | yes | yes
2117 Arguments :
2118 <code> is the HTTP status code. Currently, HAProxy is capable of
2119 generating codes 400, 403, 408, 500, 502, 503, and 504.
2120
2121 <url> it is the exact contents of the "Location" header. It may contain
2122 either a relative URI to an error page hosted on the same site,
2123 or an absolute URI designating an error page on another site.
2124 Special care should be given to relative URIs to avoid redirect
2125 loops if the URI itself may generate the same error (eg: 500).
2126
2127 It is important to understand that this keyword is not meant to rewrite
2128 errors returned by the server, but errors detected and returned by HAProxy.
2129 This is why the list of supported errors is limited to a small set.
2130
2131 Note that both keyword return the HTTP 302 status code, which tells the
2132 client to fetch the designated URL using the same HTTP method. This can be
2133 quite problematic in case of non-GET methods such as POST, because the URL
2134 sent to the client might not be allowed for something other than GET. To
2135 workaround this problem, please use "errorloc303" which send the HTTP 303
2136 status code, indicating to the client that the URL must be fetched with a GET
2137 request.
2138
2139 See also : "errorfile", "errorloc303"
2140
2141
2142errorloc303 <code> <url>
2143 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2144 May be used in sections : defaults | frontend | listen | backend
2145 yes | yes | yes | yes
2146 Arguments :
2147 <code> is the HTTP status code. Currently, HAProxy is capable of
2148 generating codes 400, 403, 408, 500, 502, 503, and 504.
2149
2150 <url> it is the exact contents of the "Location" header. It may contain
2151 either a relative URI to an error page hosted on the same site,
2152 or an absolute URI designating an error page on another site.
2153 Special care should be given to relative URIs to avoid redirect
2154 loops if the URI itself may generate the same error (eg: 500).
2155
2156 It is important to understand that this keyword is not meant to rewrite
2157 errors returned by the server, but errors detected and returned by HAProxy.
2158 This is why the list of supported errors is limited to a small set.
2159
2160 Note that both keyword return the HTTP 303 status code, which tells the
2161 client to fetch the designated URL using the same HTTP GET method. This
2162 solves the usual problems associated with "errorloc" and the 302 code. It is
2163 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002164 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002165
2166 See also : "errorfile", "errorloc", "errorloc302"
2167
2168
Willy Tarreau4de91492010-01-22 19:10:05 +01002169force-persist { if | unless } <condition>
2170 Declare a condition to force persistence on down servers
2171 May be used in sections: defaults | frontend | listen | backend
2172 no | yes | yes | yes
2173
2174 By default, requests are not dispatched to down servers. It is possible to
2175 force this using "option persist", but it is unconditional and redispatches
2176 to a valid server if "option redispatch" is set. That leaves with very little
2177 possibilities to force some requests to reach a server which is artificially
2178 marked down for maintenance operations.
2179
2180 The "force-persist" statement allows one to declare various ACL-based
2181 conditions which, when met, will cause a request to ignore the down status of
2182 a server and still try to connect to it. That makes it possible to start a
2183 server, still replying an error to the health checks, and run a specially
2184 configured browser to test the service. Among the handy methods, one could
2185 use a specific source IP address, or a specific cookie. The cookie also has
2186 the advantage that it can easily be added/removed on the browser from a test
2187 page. Once the service is validated, it is then possible to open the service
2188 to the world by returning a valid response to health checks.
2189
2190 The forced persistence is enabled when an "if" condition is met, or unless an
2191 "unless" condition is met. The final redispatch is always disabled when this
2192 is used.
2193
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002194 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002195 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002196
2197
Willy Tarreau2769aa02007-12-27 18:26:09 +01002198fullconn <conns>
2199 Specify at what backend load the servers will reach their maxconn
2200 May be used in sections : defaults | frontend | listen | backend
2201 yes | no | yes | yes
2202 Arguments :
2203 <conns> is the number of connections on the backend which will make the
2204 servers use the maximal number of connections.
2205
Willy Tarreau198a7442008-01-17 12:05:32 +01002206 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002207 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002208 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002209 load. The server will then always accept at least <minconn> connections,
2210 never more than <maxconn>, and the limit will be on the ramp between both
2211 values when the backend has less than <conns> concurrent connections. This
2212 makes it possible to limit the load on the servers during normal loads, but
2213 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002214 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002215
2216 Example :
2217 # The servers will accept between 100 and 1000 concurrent connections each
2218 # and the maximum of 1000 will be reached when the backend reaches 10000
2219 # connections.
2220 backend dynamic
2221 fullconn 10000
2222 server srv1 dyn1:80 minconn 100 maxconn 1000
2223 server srv2 dyn2:80 minconn 100 maxconn 1000
2224
2225 See also : "maxconn", "server"
2226
2227
2228grace <time>
2229 Maintain a proxy operational for some time after a soft stop
2230 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002231 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002232 Arguments :
2233 <time> is the time (by default in milliseconds) for which the instance
2234 will remain operational with the frontend sockets still listening
2235 when a soft-stop is received via the SIGUSR1 signal.
2236
2237 This may be used to ensure that the services disappear in a certain order.
2238 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002239 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002240 needed by the equipment to detect the failure.
2241
2242 Note that currently, there is very little benefit in using this parameter,
2243 and it may in fact complicate the soft-reconfiguration process more than
2244 simplify it.
2245
Willy Tarreau0ba27502007-12-24 16:55:16 +01002246
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002247hash-type <method>
2248 Specify a method to use for mapping hashes to servers
2249 May be used in sections : defaults | frontend | listen | backend
2250 yes | no | yes | yes
2251 Arguments :
2252 map-based the hash table is a static array containing all alive servers.
2253 The hashes will be very smooth, will consider weights, but will
2254 be static in that weight changes while a server is up will be
2255 ignored. This means that there will be no slow start. Also,
2256 since a server is selected by its position in the array, most
2257 mappings are changed when the server count changes. This means
2258 that when a server goes up or down, or when a server is added
2259 to a farm, most connections will be redistributed to different
2260 servers. This can be inconvenient with caches for instance.
2261
Willy Tarreau798a39c2010-11-24 15:04:29 +01002262 avalanche this mechanism uses the default map-based hashing described
2263 above but applies a full avalanche hash before performing the
2264 mapping. The result is a slightly less smooth hash for most
2265 situations, but the hash becomes better than pure map-based
2266 hashes when the number of servers is a multiple of the size of
2267 the input set. When using URI hash with a number of servers
2268 multiple of 64, it's desirable to change the hash type to
2269 this value.
2270
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002271 consistent the hash table is a tree filled with many occurrences of each
2272 server. The hash key is looked up in the tree and the closest
2273 server is chosen. This hash is dynamic, it supports changing
2274 weights while the servers are up, so it is compatible with the
2275 slow start feature. It has the advantage that when a server
2276 goes up or down, only its associations are moved. When a server
2277 is added to the farm, only a few part of the mappings are
2278 redistributed, making it an ideal algorithm for caches.
2279 However, due to its principle, the algorithm will never be very
2280 smooth and it may sometimes be necessary to adjust a server's
2281 weight or its ID to get a more balanced distribution. In order
2282 to get the same distribution on multiple load balancers, it is
2283 important that all servers have the same IDs.
2284
2285 The default hash type is "map-based" and is recommended for most usages.
2286
2287 See also : "balance", "server"
2288
2289
Willy Tarreau0ba27502007-12-24 16:55:16 +01002290http-check disable-on-404
2291 Enable a maintenance mode upon HTTP/404 response to health-checks
2292 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002293 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002294 Arguments : none
2295
2296 When this option is set, a server which returns an HTTP code 404 will be
2297 excluded from further load-balancing, but will still receive persistent
2298 connections. This provides a very convenient method for Web administrators
2299 to perform a graceful shutdown of their servers. It is also important to note
2300 that a server which is detected as failed while it was in this mode will not
2301 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2302 will immediately be reinserted into the farm. The status on the stats page
2303 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002304 option only works in conjunction with the "httpchk" option. If this option
2305 is used with "http-check expect", then it has precedence over it so that 404
2306 responses will still be considered as soft-stop.
2307
2308 See also : "option httpchk", "http-check expect"
2309
2310
2311http-check expect [!] <match> <pattern>
2312 Make HTTP health checks consider reponse contents or specific status codes
2313 May be used in sections : defaults | frontend | listen | backend
2314 no | no | yes | yes
2315 Arguments :
2316 <match> is a keyword indicating how to look for a specific pattern in the
2317 response. The keyword may be one of "status", "rstatus",
2318 "string", or "rstring". The keyword may be preceeded by an
2319 exclamation mark ("!") to negate the match. Spaces are allowed
2320 between the exclamation mark and the keyword. See below for more
2321 details on the supported keywords.
2322
2323 <pattern> is the pattern to look for. It may be a string or a regular
2324 expression. If the pattern contains spaces, they must be escaped
2325 with the usual backslash ('\').
2326
2327 By default, "option httpchk" considers that response statuses 2xx and 3xx
2328 are valid, and that others are invalid. When "http-check expect" is used,
2329 it defines what is considered valid or invalid. Only one "http-check"
2330 statement is supported in a backend. If a server fails to respond or times
2331 out, the check obviously fails. The available matches are :
2332
2333 status <string> : test the exact string match for the HTTP status code.
2334 A health check respose will be considered valid if the
2335 response's status code is exactly this string. If the
2336 "status" keyword is prefixed with "!", then the response
2337 will be considered invalid if the status code matches.
2338
2339 rstatus <regex> : test a regular expression for the HTTP status code.
2340 A health check respose will be considered valid if the
2341 response's status code matches the expression. If the
2342 "rstatus" keyword is prefixed with "!", then the response
2343 will be considered invalid if the status code matches.
2344 This is mostly used to check for multiple codes.
2345
2346 string <string> : test the exact string match in the HTTP response body.
2347 A health check respose will be considered valid if the
2348 response's body contains this exact string. If the
2349 "string" keyword is prefixed with "!", then the response
2350 will be considered invalid if the body contains this
2351 string. This can be used to look for a mandatory word at
2352 the end of a dynamic page, or to detect a failure when a
2353 specific error appears on the check page (eg: a stack
2354 trace).
2355
2356 rstring <regex> : test a regular expression on the HTTP response body.
2357 A health check respose will be considered valid if the
2358 response's body matches this expression. If the "rstring"
2359 keyword is prefixed with "!", then the response will be
2360 considered invalid if the body matches the expression.
2361 This can be used to look for a mandatory word at the end
2362 of a dynamic page, or to detect a failure when a specific
2363 error appears on the check page (eg: a stack trace).
2364
2365 It is important to note that the responses will be limited to a certain size
2366 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2367 Thus, too large responses may not contain the mandatory pattern when using
2368 "string" or "rstring". If a large response is absolutely required, it is
2369 possible to change the default max size by setting the global variable.
2370 However, it is worth keeping in mind that parsing very large responses can
2371 waste some CPU cycles, especially when regular expressions are used, and that
2372 it is always better to focus the checks on smaller resources.
2373
2374 Last, if "http-check expect" is combined with "http-check disable-on-404",
2375 then this last one has precedence when the server responds with 404.
2376
2377 Examples :
2378 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002379 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002380
2381 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002382 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002383
2384 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002385 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002386
2387 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002388 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002389
Willy Tarreaubd741542010-03-16 18:46:54 +01002390 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002391
2392
Willy Tarreauef781042010-01-27 11:53:01 +01002393http-check send-state
2394 Enable emission of a state header with HTTP health checks
2395 May be used in sections : defaults | frontend | listen | backend
2396 yes | no | yes | yes
2397 Arguments : none
2398
2399 When this option is set, haproxy will systematically send a special header
2400 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2401 how they are seen by haproxy. This can be used for instance when a server is
2402 manipulated without access to haproxy and the operator needs to know whether
2403 haproxy still sees it up or not, or if the server is the last one in a farm.
2404
2405 The header is composed of fields delimited by semi-colons, the first of which
2406 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2407 checks on the total number before transition, just as appears in the stats
2408 interface. Next headers are in the form "<variable>=<value>", indicating in
2409 no specific order some values available in the stats interface :
2410 - a variable "name", containing the name of the backend followed by a slash
2411 ("/") then the name of the server. This can be used when a server is
2412 checked in multiple backends.
2413
2414 - a variable "node" containing the name of the haproxy node, as set in the
2415 global "node" variable, otherwise the system's hostname if unspecified.
2416
2417 - a variable "weight" indicating the weight of the server, a slash ("/")
2418 and the total weight of the farm (just counting usable servers). This
2419 helps to know if other servers are available to handle the load when this
2420 one fails.
2421
2422 - a variable "scur" indicating the current number of concurrent connections
2423 on the server, followed by a slash ("/") then the total number of
2424 connections on all servers of the same backend.
2425
2426 - a variable "qcur" indicating the current number of requests in the
2427 server's queue.
2428
2429 Example of a header received by the application server :
2430 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2431 scur=13/22; qcur=0
2432
2433 See also : "option httpchk", "http-check disable-on-404"
2434
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002435http-request { allow | deny | auth [realm <realm>] }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002436 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002437 Access control for Layer 7 requests
2438
2439 May be used in sections: defaults | frontend | listen | backend
2440 no | yes | yes | yes
2441
2442 These set of options allow to fine control access to a
2443 frontend/listen/backend. Each option may be followed by if/unless and acl.
2444 First option with matched condition (or option without condition) is final.
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002445 For "deny" a 403 error will be returned, for "allow" normal processing is
2446 performed, for "auth" a 401/407 error code is returned so the client
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002447 should be asked to enter a username and password.
2448
2449 There is no fixed limit to the number of http-request statements per
2450 instance.
2451
2452 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002453 acl nagios src 192.168.129.3
2454 acl local_net src 192.168.0.0/16
2455 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002456
Cyril Bonté78caf842010-03-10 22:41:43 +01002457 http-request allow if nagios
2458 http-request allow if local_net auth_ok
2459 http-request auth realm Gimme if local_net auth_ok
2460 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002461
Cyril Bonté78caf842010-03-10 22:41:43 +01002462 Example:
2463 acl auth_ok http_auth_group(L1) G1
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002464
Cyril Bonté78caf842010-03-10 22:41:43 +01002465 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002466
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002467 See also : "stats http-request", section 3.4 about userlists and section 7
2468 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002469
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002470id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02002471 Set a persistent ID to a proxy.
2472 May be used in sections : defaults | frontend | listen | backend
2473 no | yes | yes | yes
2474 Arguments : none
2475
2476 Set a persistent ID for the proxy. This ID must be unique and positive.
2477 An unused ID will automatically be assigned if unset. The first assigned
2478 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002479
2480
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002481ignore-persist { if | unless } <condition>
2482 Declare a condition to ignore persistence
2483 May be used in sections: defaults | frontend | listen | backend
2484 no | yes | yes | yes
2485
2486 By default, when cookie persistence is enabled, every requests containing
2487 the cookie are unconditionally persistent (assuming the target server is up
2488 and running).
2489
2490 The "ignore-persist" statement allows one to declare various ACL-based
2491 conditions which, when met, will cause a request to ignore persistence.
2492 This is sometimes useful to load balance requests for static files, which
2493 oftenly don't require persistence. This can also be used to fully disable
2494 persistence for a specific User-Agent (for example, some web crawler bots).
2495
2496 Combined with "appsession", it can also help reduce HAProxy memory usage, as
2497 the appsession table won't grow if persistence is ignored.
2498
2499 The persistence is ignored when an "if" condition is met, or unless an
2500 "unless" condition is met.
2501
2502 See also : "force-persist", "cookie", and section 7 about ACL usage.
2503
2504
Willy Tarreau2769aa02007-12-27 18:26:09 +01002505log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002506log <address> <facility> [<level> [<minlevel>]]
Willy Tarreau2769aa02007-12-27 18:26:09 +01002507 Enable per-instance logging of events and traffic.
2508 May be used in sections : defaults | frontend | listen | backend
2509 yes | yes | yes | yes
2510 Arguments :
2511 global should be used when the instance's logging parameters are the
2512 same as the global ones. This is the most common usage. "global"
2513 replaces <address>, <facility> and <level> with those of the log
2514 entries found in the "global" section. Only one "log global"
2515 statement may be used per instance, and this form takes no other
2516 parameter.
2517
2518 <address> indicates where to send the logs. It takes the same format as
2519 for the "global" section's logs, and can be one of :
2520
2521 - An IPv4 address optionally followed by a colon (':') and a UDP
2522 port. If no port is specified, 514 is used by default (the
2523 standard syslog port).
2524
2525 - A filesystem path to a UNIX domain socket, keeping in mind
2526 considerations for chroot (be sure the path is accessible
2527 inside the chroot) and uid/gid (be sure the path is
2528 appropriately writeable).
2529
2530 <facility> must be one of the 24 standard syslog facilities :
2531
2532 kern user mail daemon auth syslog lpr news
2533 uucp cron auth2 ftp ntp audit alert cron2
2534 local0 local1 local2 local3 local4 local5 local6 local7
2535
2536 <level> is optional and can be specified to filter outgoing messages. By
2537 default, all messages are sent. If a level is specified, only
2538 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002539 will be sent. An optional minimum level can be specified. If it
2540 is set, logs emitted with a more severe level than this one will
2541 be capped to this level. This is used to avoid sending "emerg"
2542 messages on all terminals on some default syslog configurations.
2543 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002544
2545 emerg alert crit err warning notice info debug
2546
2547 Note that up to two "log" entries may be specified per instance. However, if
2548 "log global" is used and if the "global" section already contains 2 log
2549 entries, then additional log entries will be ignored.
2550
2551 Also, it is important to keep in mind that it is the frontend which decides
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002552 what to log from a connection, and that in case of content switching, the log
2553 entries from the backend will be ignored. Connections are logged at level
2554 "info".
2555
2556 However, backend log declaration define how and where servers status changes
2557 will be logged. Level "notice" will be used to indicate a server going up,
2558 "warning" will be used for termination signals and definitive service
2559 termination, and "alert" will be used for when a server goes down.
2560
2561 Note : According to RFC3164, messages are truncated to 1024 bytes before
2562 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002563
2564 Example :
2565 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002566 log 127.0.0.1:514 local0 notice # only send important events
2567 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreau2769aa02007-12-27 18:26:09 +01002568
2569
2570maxconn <conns>
2571 Fix the maximum number of concurrent connections on a frontend
2572 May be used in sections : defaults | frontend | listen | backend
2573 yes | yes | yes | no
2574 Arguments :
2575 <conns> is the maximum number of concurrent connections the frontend will
2576 accept to serve. Excess connections will be queued by the system
2577 in the socket's listen queue and will be served once a connection
2578 closes.
2579
2580 If the system supports it, it can be useful on big sites to raise this limit
2581 very high so that haproxy manages connection queues, instead of leaving the
2582 clients with unanswered connection attempts. This value should not exceed the
2583 global maxconn. Also, keep in mind that a connection contains two buffers
2584 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
2585 consumed per established connection. That means that a medium system equipped
2586 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
2587 properly tuned.
2588
2589 Also, when <conns> is set to large values, it is possible that the servers
2590 are not sized to accept such loads, and for this reason it is generally wise
2591 to assign them some reasonable connection limits.
2592
2593 See also : "server", global section's "maxconn", "fullconn"
2594
2595
2596mode { tcp|http|health }
2597 Set the running mode or protocol of the instance
2598 May be used in sections : defaults | frontend | listen | backend
2599 yes | yes | yes | yes
2600 Arguments :
2601 tcp The instance will work in pure TCP mode. A full-duplex connection
2602 will be established between clients and servers, and no layer 7
2603 examination will be performed. This is the default mode. It
2604 should be used for SSL, SSH, SMTP, ...
2605
2606 http The instance will work in HTTP mode. The client request will be
2607 analyzed in depth before connecting to any server. Any request
2608 which is not RFC-compliant will be rejected. Layer 7 filtering,
2609 processing and switching will be possible. This is the mode which
2610 brings HAProxy most of its value.
2611
2612 health The instance will work in "health" mode. It will just reply "OK"
2613 to incoming connections and close the connection. Nothing will be
2614 logged. This mode is used to reply to external components health
2615 checks. This mode is deprecated and should not be used anymore as
2616 it is possible to do the same and even better by combining TCP or
2617 HTTP modes with the "monitor" keyword.
2618
2619 When doing content switching, it is mandatory that the frontend and the
2620 backend are in the same mode (generally HTTP), otherwise the configuration
2621 will be refused.
2622
2623 Example :
2624 defaults http_instances
2625 mode http
2626
2627 See also : "monitor", "monitor-net"
2628
Willy Tarreau0ba27502007-12-24 16:55:16 +01002629
Cyril Bontéf0c60612010-02-06 14:44:47 +01002630monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01002631 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002632 May be used in sections : defaults | frontend | listen | backend
2633 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01002634 Arguments :
2635 if <cond> the monitor request will fail if the condition is satisfied,
2636 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002637 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01002638 are met, for instance a low number of servers both in a
2639 backend and its backup.
2640
2641 unless <cond> the monitor request will succeed only if the condition is
2642 satisfied, and will fail otherwise. Such a condition may be
2643 based on a test on the presence of a minimum number of active
2644 servers in a list of backends.
2645
2646 This statement adds a condition which can force the response to a monitor
2647 request to report a failure. By default, when an external component queries
2648 the URI dedicated to monitoring, a 200 response is returned. When one of the
2649 conditions above is met, haproxy will return 503 instead of 200. This is
2650 very useful to report a site failure to an external component which may base
2651 routing advertisements between multiple sites on the availability reported by
2652 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002653 criterion. Note that "monitor fail" only works in HTTP mode.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002654
2655 Example:
2656 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01002657 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01002658 acl site_dead nbsrv(dynamic) lt 2
2659 acl site_dead nbsrv(static) lt 2
2660 monitor-uri /site_alive
2661 monitor fail if site_dead
2662
Willy Tarreau2769aa02007-12-27 18:26:09 +01002663 See also : "monitor-net", "monitor-uri"
2664
2665
2666monitor-net <source>
2667 Declare a source network which is limited to monitor requests
2668 May be used in sections : defaults | frontend | listen | backend
2669 yes | yes | yes | no
2670 Arguments :
2671 <source> is the source IPv4 address or network which will only be able to
2672 get monitor responses to any request. It can be either an IPv4
2673 address, a host name, or an address followed by a slash ('/')
2674 followed by a mask.
2675
2676 In TCP mode, any connection coming from a source matching <source> will cause
2677 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002678 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01002679 forwarding the connection to a remote server.
2680
2681 In HTTP mode, a connection coming from a source matching <source> will be
2682 accepted, the following response will be sent without waiting for a request,
2683 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
2684 enough for any front-end HTTP probe to detect that the service is UP and
2685 running without forwarding the request to a backend server.
2686
2687 Monitor requests are processed very early. It is not possible to block nor
2688 divert them using ACLs. They cannot be logged either, and it is the intended
2689 purpose. They are only used to report HAProxy's health to an upper component,
2690 nothing more. Right now, it is not possible to set failure conditions on
2691 requests caught by "monitor-net".
2692
Willy Tarreau95cd2832010-03-04 23:36:33 +01002693 Last, please note that only one "monitor-net" statement can be specified in
2694 a frontend. If more than one is found, only the last one will be considered.
2695
Willy Tarreau2769aa02007-12-27 18:26:09 +01002696 Example :
2697 # addresses .252 and .253 are just probing us.
2698 frontend www
2699 monitor-net 192.168.0.252/31
2700
2701 See also : "monitor fail", "monitor-uri"
2702
2703
2704monitor-uri <uri>
2705 Intercept a URI used by external components' monitor requests
2706 May be used in sections : defaults | frontend | listen | backend
2707 yes | yes | yes | no
2708 Arguments :
2709 <uri> is the exact URI which we want to intercept to return HAProxy's
2710 health status instead of forwarding the request.
2711
2712 When an HTTP request referencing <uri> will be received on a frontend,
2713 HAProxy will not forward it nor log it, but instead will return either
2714 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
2715 conditions defined with "monitor fail". This is normally enough for any
2716 front-end HTTP probe to detect that the service is UP and running without
2717 forwarding the request to a backend server. Note that the HTTP method, the
2718 version and all headers are ignored, but the request must at least be valid
2719 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
2720
2721 Monitor requests are processed very early. It is not possible to block nor
2722 divert them using ACLs. They cannot be logged either, and it is the intended
2723 purpose. They are only used to report HAProxy's health to an upper component,
2724 nothing more. However, it is possible to add any number of conditions using
2725 "monitor fail" and ACLs so that the result can be adjusted to whatever check
2726 can be imagined (most often the number of available servers in a backend).
2727
2728 Example :
2729 # Use /haproxy_test to report haproxy's status
2730 frontend www
2731 mode http
2732 monitor-uri /haproxy_test
2733
2734 See also : "monitor fail", "monitor-net"
2735
Willy Tarreau0ba27502007-12-24 16:55:16 +01002736
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002737option abortonclose
2738no option abortonclose
2739 Enable or disable early dropping of aborted requests pending in queues.
2740 May be used in sections : defaults | frontend | listen | backend
2741 yes | no | yes | yes
2742 Arguments : none
2743
2744 In presence of very high loads, the servers will take some time to respond.
2745 The per-instance connection queue will inflate, and the response time will
2746 increase respective to the size of the queue times the average per-session
2747 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01002748 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002749 the queue, and slowing down other users, and the servers as well, because the
2750 request will eventually be served, then aborted at the first error
2751 encountered while delivering the response.
2752
2753 As there is no way to distinguish between a full STOP and a simple output
2754 close on the client side, HTTP agents should be conservative and consider
2755 that the client might only have closed its output channel while waiting for
2756 the response. However, this introduces risks of congestion when lots of users
2757 do the same, and is completely useless nowadays because probably no client at
2758 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01002759 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002760 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01002761 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002762 of being the single component to break rare but valid traffic is extremely
2763 low, which adds to the temptation to be able to abort a session early while
2764 still not served and not pollute the servers.
2765
2766 In HAProxy, the user can choose the desired behaviour using the option
2767 "abortonclose". By default (without the option) the behaviour is HTTP
2768 compliant and aborted requests will be served. But when the option is
2769 specified, a session with an incoming channel closed will be aborted while
2770 it is still possible, either pending in the queue for a connection slot, or
2771 during the connection establishment if the server has not yet acknowledged
2772 the connection request. This considerably reduces the queue size and the load
2773 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01002774 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002775
2776 If this option has been enabled in a "defaults" section, it can be disabled
2777 in a specific instance by prepending the "no" keyword before it.
2778
2779 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
2780
2781
Willy Tarreau4076a152009-04-02 15:18:36 +02002782option accept-invalid-http-request
2783no option accept-invalid-http-request
2784 Enable or disable relaxing of HTTP request parsing
2785 May be used in sections : defaults | frontend | listen | backend
2786 yes | yes | yes | no
2787 Arguments : none
2788
2789 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2790 means that invalid characters in header names are not permitted and cause an
2791 error to be returned to the client. This is the desired behaviour as such
2792 forbidden characters are essentially used to build attacks exploiting server
2793 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2794 server will emit invalid header names for whatever reason (configuration,
2795 implementation) and the issue will not be immediately fixed. In such a case,
2796 it is possible to relax HAProxy's header name parser to accept any character
2797 even if that does not make sense, by specifying this option.
2798
2799 This option should never be enabled by default as it hides application bugs
2800 and open security breaches. It should only be deployed after a problem has
2801 been confirmed.
2802
2803 When this option is enabled, erroneous header names will still be accepted in
2804 requests, but the complete request will be captured in order to permit later
2805 analysis using the "show errors" request on the UNIX stats socket. Doing this
2806 also helps confirming that the issue has been solved.
2807
2808 If this option has been enabled in a "defaults" section, it can be disabled
2809 in a specific instance by prepending the "no" keyword before it.
2810
2811 See also : "option accept-invalid-http-response" and "show errors" on the
2812 stats socket.
2813
2814
2815option accept-invalid-http-response
2816no option accept-invalid-http-response
2817 Enable or disable relaxing of HTTP response parsing
2818 May be used in sections : defaults | frontend | listen | backend
2819 yes | no | yes | yes
2820 Arguments : none
2821
2822 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2823 means that invalid characters in header names are not permitted and cause an
2824 error to be returned to the client. This is the desired behaviour as such
2825 forbidden characters are essentially used to build attacks exploiting server
2826 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2827 server will emit invalid header names for whatever reason (configuration,
2828 implementation) and the issue will not be immediately fixed. In such a case,
2829 it is possible to relax HAProxy's header name parser to accept any character
2830 even if that does not make sense, by specifying this option.
2831
2832 This option should never be enabled by default as it hides application bugs
2833 and open security breaches. It should only be deployed after a problem has
2834 been confirmed.
2835
2836 When this option is enabled, erroneous header names will still be accepted in
2837 responses, but the complete response will be captured in order to permit
2838 later analysis using the "show errors" request on the UNIX stats socket.
2839 Doing this also helps confirming that the issue has been solved.
2840
2841 If this option has been enabled in a "defaults" section, it can be disabled
2842 in a specific instance by prepending the "no" keyword before it.
2843
2844 See also : "option accept-invalid-http-request" and "show errors" on the
2845 stats socket.
2846
2847
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002848option allbackups
2849no option allbackups
2850 Use either all backup servers at a time or only the first one
2851 May be used in sections : defaults | frontend | listen | backend
2852 yes | no | yes | yes
2853 Arguments : none
2854
2855 By default, the first operational backup server gets all traffic when normal
2856 servers are all down. Sometimes, it may be preferred to use multiple backups
2857 at once, because one will not be enough. When "option allbackups" is enabled,
2858 the load balancing will be performed among all backup servers when all normal
2859 ones are unavailable. The same load balancing algorithm will be used and the
2860 servers' weights will be respected. Thus, there will not be any priority
2861 order between the backup servers anymore.
2862
2863 This option is mostly used with static server farms dedicated to return a
2864 "sorry" page when an application is completely offline.
2865
2866 If this option has been enabled in a "defaults" section, it can be disabled
2867 in a specific instance by prepending the "no" keyword before it.
2868
2869
2870option checkcache
2871no option checkcache
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002872 Analyze all server responses and block requests with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002873 May be used in sections : defaults | frontend | listen | backend
2874 yes | no | yes | yes
2875 Arguments : none
2876
2877 Some high-level frameworks set application cookies everywhere and do not
2878 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002879 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002880 high risk of session crossing or stealing between users traversing the same
2881 caches. In some situations, it is better to block the response than to let
2882 some sensible session information go in the wild.
2883
2884 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002885 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01002886 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002887 response to check if there's a risk of caching a cookie on a client-side
2888 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01002889 to the client are :
2890 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002891 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01002892 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002893 - all those that come from a POST request, provided that the server has not
2894 set a 'Cache-Control: public' header ;
2895 - those with a 'Pragma: no-cache' header
2896 - those with a 'Cache-control: private' header
2897 - those with a 'Cache-control: no-store' header
2898 - those with a 'Cache-control: max-age=0' header
2899 - those with a 'Cache-control: s-maxage=0' header
2900 - those with a 'Cache-control: no-cache' header
2901 - those with a 'Cache-control: no-cache="set-cookie"' header
2902 - those with a 'Cache-control: no-cache="set-cookie,' header
2903 (allowing other fields after set-cookie)
2904
2905 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01002906 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002907 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002908 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002909 that admins are informed that there's something to be fixed.
2910
2911 Due to the high impact on the application, the application should be tested
2912 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002913 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002914 production, as it will report potentially dangerous application behaviours.
2915
2916 If this option has been enabled in a "defaults" section, it can be disabled
2917 in a specific instance by prepending the "no" keyword before it.
2918
2919
2920option clitcpka
2921no option clitcpka
2922 Enable or disable the sending of TCP keepalive packets on the client side
2923 May be used in sections : defaults | frontend | listen | backend
2924 yes | yes | yes | no
2925 Arguments : none
2926
2927 When there is a firewall or any session-aware component between a client and
2928 a server, and when the protocol involves very long sessions with long idle
2929 periods (eg: remote desktops), there is a risk that one of the intermediate
2930 components decides to expire a session which has remained idle for too long.
2931
2932 Enabling socket-level TCP keep-alives makes the system regularly send packets
2933 to the other end of the connection, leaving it active. The delay between
2934 keep-alive probes is controlled by the system only and depends both on the
2935 operating system and its tuning parameters.
2936
2937 It is important to understand that keep-alive packets are neither emitted nor
2938 received at the application level. It is only the network stacks which sees
2939 them. For this reason, even if one side of the proxy already uses keep-alives
2940 to maintain its connection alive, those keep-alive packets will not be
2941 forwarded to the other side of the proxy.
2942
2943 Please note that this has nothing to do with HTTP keep-alive.
2944
2945 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
2946 client side of a connection, which should help when session expirations are
2947 noticed between HAProxy and a client.
2948
2949 If this option has been enabled in a "defaults" section, it can be disabled
2950 in a specific instance by prepending the "no" keyword before it.
2951
2952 See also : "option srvtcpka", "option tcpka"
2953
2954
Willy Tarreau0ba27502007-12-24 16:55:16 +01002955option contstats
2956 Enable continuous traffic statistics updates
2957 May be used in sections : defaults | frontend | listen | backend
2958 yes | yes | yes | no
2959 Arguments : none
2960
2961 By default, counters used for statistics calculation are incremented
2962 only when a session finishes. It works quite well when serving small
2963 objects, but with big ones (for example large images or archives) or
2964 with A/V streaming, a graph generated from haproxy counters looks like
2965 a hedgehog. With this option enabled counters get incremented continuously,
2966 during a whole session. Recounting touches a hotpath directly so
2967 it is not enabled by default, as it has small performance impact (~0.5%).
2968
2969
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002970option dontlog-normal
2971no option dontlog-normal
2972 Enable or disable logging of normal, successful connections
2973 May be used in sections : defaults | frontend | listen | backend
2974 yes | yes | yes | no
2975 Arguments : none
2976
2977 There are large sites dealing with several thousand connections per second
2978 and for which logging is a major pain. Some of them are even forced to turn
2979 logs off and cannot debug production issues. Setting this option ensures that
2980 normal connections, those which experience no error, no timeout, no retry nor
2981 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
2982 mode, the response status code is checked and return codes 5xx will still be
2983 logged.
2984
2985 It is strongly discouraged to use this option as most of the time, the key to
2986 complex issues is in the normal logs which will not be logged here. If you
2987 need to separate logs, see the "log-separate-errors" option instead.
2988
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002989 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002990 logging.
2991
2992
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002993option dontlognull
2994no option dontlognull
2995 Enable or disable logging of null connections
2996 May be used in sections : defaults | frontend | listen | backend
2997 yes | yes | yes | no
2998 Arguments : none
2999
3000 In certain environments, there are components which will regularly connect to
3001 various systems to ensure that they are still alive. It can be the case from
3002 another load balancer as well as from monitoring systems. By default, even a
3003 simple port probe or scan will produce a log. If those connections pollute
3004 the logs too much, it is possible to enable option "dontlognull" to indicate
3005 that a connection on which no data has been transferred will not be logged,
3006 which typically corresponds to those probes.
3007
3008 It is generally recommended not to use this option in uncontrolled
3009 environments (eg: internet), otherwise scans and other malicious activities
3010 would not be logged.
3011
3012 If this option has been enabled in a "defaults" section, it can be disabled
3013 in a specific instance by prepending the "no" keyword before it.
3014
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003015 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003016
3017
3018option forceclose
3019no option forceclose
3020 Enable or disable active connection closing after response is transferred.
3021 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003022 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003023 Arguments : none
3024
3025 Some HTTP servers do not necessarily close the connections when they receive
3026 the "Connection: close" set by "option httpclose", and if the client does not
3027 close either, then the connection remains open till the timeout expires. This
3028 causes high number of simultaneous connections on the servers and shows high
3029 global session times in the logs.
3030
3031 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003032 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003033 to respond. This option implicitly enables the "httpclose" option. Note that
3034 this option also enables the parsing of the full request and response, which
3035 means we can close the connection to the server very quickly, releasing some
3036 resources earlier than with httpclose.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003037
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003038 This option may also be combined with "option http-pretend-keepalive", which
3039 will disable sending of the "Connection: close" header, but will still cause
3040 the connection to be closed once the whole response is received.
3041
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003042 If this option has been enabled in a "defaults" section, it can be disabled
3043 in a specific instance by prepending the "no" keyword before it.
3044
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003045 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003046
3047
Ross Westaf72a1d2008-08-03 10:51:45 +02003048option forwardfor [ except <network> ] [ header <name> ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003049 Enable insertion of the X-Forwarded-For header to requests sent to servers
3050 May be used in sections : defaults | frontend | listen | backend
3051 yes | yes | yes | yes
3052 Arguments :
3053 <network> is an optional argument used to disable this option for sources
3054 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003055 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003056 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003057
3058 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3059 their client address. This is sometimes annoying when the client's IP address
3060 is expected in server logs. To solve this problem, the well-known HTTP header
3061 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3062 This header contains a value representing the client's IP address. Since this
3063 header is always appended at the end of the existing header list, the server
3064 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003065 the server's manual to find how to enable use of this standard header. Note
3066 that only the last occurrence of the header must be used, since it is really
3067 possible that the client has already brought one.
3068
Willy Tarreaud72758d2010-01-12 10:42:19 +01003069 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003070 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003071 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3072 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003073 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3074 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003075
3076 Sometimes, a same HAProxy instance may be shared between a direct client
3077 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3078 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3079 header for a known source address or network by adding the "except" keyword
3080 followed by the network address. In this case, any source IP matching the
3081 network will not cause an addition of this header. Most common uses are with
3082 private networks or 127.0.0.1.
3083
3084 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003085 least one of them uses it, the header will be added. Note that the backend's
3086 setting of the header subargument takes precedence over the frontend's if
3087 both are defined.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003088
3089 It is important to note that as long as HAProxy does not support keep-alive
3090 connections, only the first request of a connection will receive the header.
3091 For this reason, it is important to ensure that "option httpclose" is set
3092 when using this option.
3093
Ross Westaf72a1d2008-08-03 10:51:45 +02003094 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003095 # Public HTTP address also used by stunnel on the same machine
3096 frontend www
3097 mode http
3098 option forwardfor except 127.0.0.1 # stunnel already adds the header
3099
Ross Westaf72a1d2008-08-03 10:51:45 +02003100 # Those servers want the IP Address in X-Client
3101 backend www
3102 mode http
3103 option forwardfor header X-Client
3104
Willy Tarreauc27debf2008-01-06 08:57:02 +01003105 See also : "option httpclose"
3106
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003107
3108option http-pretend-keepalive
3109no option http-pretend-keepalive
3110 Define whether haproxy will announce keepalive to the server or not
3111 May be used in sections : defaults | frontend | listen | backend
3112 yes | yes | yes | yes
3113 Arguments : none
3114
3115 When running with "option http-server-close" or "option forceclose", haproxy
3116 adds a "Connection: close" header to the request forwarded to the server.
3117 Unfortunately, when some servers see this header, they automatically refrain
3118 from using the chunked encoding for responses of unknown length, while this
3119 is totally unrelated. The immediate effect is that this prevents haproxy from
3120 maintaining the client connection alive. A second effect is that a client or
3121 a cache could receive an incomplete response without being aware of it, and
3122 consider the response complete.
3123
3124 By setting "option http-pretend-keepalive", haproxy will make the server
3125 believe it will keep the connection alive. The server will then not fall back
3126 to the abnormal undesired above. When haproxy gets the whole response, it
3127 will close the connection with the server just as it would do with the
3128 "forceclose" option. That way the client gets a normal response and the
3129 connection is correctly closed on the server side.
3130
3131 It is recommended not to enable this option by default, because most servers
3132 will more efficiently close the connection themselves after the last packet,
3133 and release its buffers slightly earlier. Also, the added packet on the
3134 network could slightly reduce the overall peak performance. However it is
3135 worth noting that when this option is enabled, haproxy will have slightly
3136 less work to do. So if haproxy is the bottleneck on the whole architecture,
3137 enabling this option might save a few CPU cycles.
3138
3139 This option may be set both in a frontend and in a backend. It is enabled if
3140 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau22a95342010-09-29 14:31:41 +02003141 This option may be compbined with "option httpclose", which will cause
3142 keepalive to be announced to the server and close to be announced to the
3143 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003144
3145 If this option has been enabled in a "defaults" section, it can be disabled
3146 in a specific instance by prepending the "no" keyword before it.
3147
3148 See also : "option forceclose" and "option http-server-close"
3149
Willy Tarreauc27debf2008-01-06 08:57:02 +01003150
Willy Tarreaub608feb2010-01-02 22:47:18 +01003151option http-server-close
3152no option http-server-close
3153 Enable or disable HTTP connection closing on the server side
3154 May be used in sections : defaults | frontend | listen | backend
3155 yes | yes | yes | yes
3156 Arguments : none
3157
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003158 By default, when a client communicates with a server, HAProxy will only
3159 analyze, log, and process the first request of each connection. Setting
3160 "option http-server-close" enables HTTP connection-close mode on the server
3161 side while keeping the ability to support HTTP keep-alive and pipelining on
3162 the client side. This provides the lowest latency on the client side (slow
3163 network) and the fastest session reuse on the server side to save server
3164 resources, similarly to "option forceclose". It also permits non-keepalive
3165 capable servers to be served in keep-alive mode to the clients if they
3166 conform to the requirements of RFC2616. Please note that some servers do not
3167 always conform to those requirements when they see "Connection: close" in the
3168 request. The effect will be that keep-alive will never be used. A workaround
3169 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003170
3171 At the moment, logs will not indicate whether requests came from the same
3172 session or not. The accept date reported in the logs corresponds to the end
3173 of the previous request, and the request time corresponds to the time spent
3174 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01003175 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3176 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01003177
3178 This option may be set both in a frontend and in a backend. It is enabled if
3179 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003180 It is worth noting that "option forceclose" has precedence over "option
3181 http-server-close" and that combining "http-server-close" with "httpclose"
3182 basically achieve the same result as "forceclose".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003183
3184 If this option has been enabled in a "defaults" section, it can be disabled
3185 in a specific instance by prepending the "no" keyword before it.
3186
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003187 See also : "option forceclose", "option http-pretend-keepalive",
3188 "option httpclose" and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003189
3190
Willy Tarreau88d349d2010-01-25 12:15:43 +01003191option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01003192no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01003193 Make use of non-standard Proxy-Connection header instead of Connection
3194 May be used in sections : defaults | frontend | listen | backend
3195 yes | yes | yes | no
3196 Arguments : none
3197
3198 While RFC2616 explicitly states that HTTP/1.1 agents must use the
3199 Connection header to indicate their wish of persistent or non-persistent
3200 connections, both browsers and proxies ignore this header for proxied
3201 connections and make use of the undocumented, non-standard Proxy-Connection
3202 header instead. The issue begins when trying to put a load balancer between
3203 browsers and such proxies, because there will be a difference between what
3204 haproxy understands and what the client and the proxy agree on.
3205
3206 By setting this option in a frontend, haproxy can automatically switch to use
3207 that non-standard header if it sees proxied requests. A proxied request is
3208 defined here as one where the URI begins with neither a '/' nor a '*'. The
3209 choice of header only affects requests passing through proxies making use of
3210 one of the "httpclose", "forceclose" and "http-server-close" options. Note
3211 that this option can only be specified in a frontend and will affect the
3212 request along its whole life.
3213
Willy Tarreau844a7e72010-01-31 21:46:18 +01003214 Also, when this option is set, a request which requires authentication will
3215 automatically switch to use proxy authentication headers if it is itself a
3216 proxied request. That makes it possible to check or enforce authentication in
3217 front of an existing proxy.
3218
Willy Tarreau88d349d2010-01-25 12:15:43 +01003219 This option should normally never be used, except in front of a proxy.
3220
3221 See also : "option httpclose", "option forceclose" and "option
3222 http-server-close".
3223
3224
Willy Tarreaud63335a2010-02-26 12:56:52 +01003225option httpchk
3226option httpchk <uri>
3227option httpchk <method> <uri>
3228option httpchk <method> <uri> <version>
3229 Enable HTTP protocol to check on the servers health
3230 May be used in sections : defaults | frontend | listen | backend
3231 yes | no | yes | yes
3232 Arguments :
3233 <method> is the optional HTTP method used with the requests. When not set,
3234 the "OPTIONS" method is used, as it generally requires low server
3235 processing and is easy to filter out from the logs. Any method
3236 may be used, though it is not recommended to invent non-standard
3237 ones.
3238
3239 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
3240 which is accessible by default on almost any server, but may be
3241 changed to any other URI. Query strings are permitted.
3242
3243 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
3244 but some servers might behave incorrectly in HTTP 1.0, so turning
3245 it to HTTP/1.1 may sometimes help. Note that the Host field is
3246 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
3247 after "\r\n" following the version string.
3248
3249 By default, server health checks only consist in trying to establish a TCP
3250 connection. When "option httpchk" is specified, a complete HTTP request is
3251 sent once the TCP connection is established, and responses 2xx and 3xx are
3252 considered valid, while all other ones indicate a server failure, including
3253 the lack of any response.
3254
3255 The port and interval are specified in the server configuration.
3256
3257 This option does not necessarily require an HTTP backend, it also works with
3258 plain TCP backends. This is particularly useful to check simple scripts bound
3259 to some dedicated ports using the inetd daemon.
3260
3261 Examples :
3262 # Relay HTTPS traffic to Apache instance and check service availability
3263 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
3264 backend https_relay
3265 mode tcp
3266 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
3267 server apache1 192.168.1.1:443 check port 80
3268
3269 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003270 "option pgsql-check", "http-check" and the "check", "port" and
3271 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01003272
3273
Willy Tarreauc27debf2008-01-06 08:57:02 +01003274option httpclose
3275no option httpclose
3276 Enable or disable passive HTTP connection closing
3277 May be used in sections : defaults | frontend | listen | backend
3278 yes | yes | yes | yes
3279 Arguments : none
3280
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003281 By default, when a client communicates with a server, HAProxy will only
3282 analyze, log, and process the first request of each connection. If "option
3283 httpclose" is set, it will check if a "Connection: close" header is already
3284 set in each direction, and will add one if missing. Each end should react to
3285 this by actively closing the TCP connection after each transfer, thus
3286 resulting in a switch to the HTTP close mode. Any "Connection" header
3287 different from "close" will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003288
3289 It seldom happens that some servers incorrectly ignore this header and do not
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003290 close the connection eventhough they reply "Connection: close". For this
3291 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
3292 it is possible to use the "option forceclose" which actively closes the
3293 request connection once the server responds. Option "forceclose" also
3294 releases the server connection earlier because it does not have to wait for
3295 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003296
3297 This option may be set both in a frontend and in a backend. It is enabled if
3298 at least one of the frontend or backend holding a connection has it enabled.
3299 If "option forceclose" is specified too, it has precedence over "httpclose".
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003300 If "option http-server-close" is enabled at the same time as "httpclose", it
3301 basically achieves the same result as "option forceclose".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003302
3303 If this option has been enabled in a "defaults" section, it can be disabled
3304 in a specific instance by prepending the "no" keyword before it.
3305
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003306 See also : "option forceclose", "option http-server-close" and
3307 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003308
3309
Emeric Brun3a058f32009-06-30 18:26:00 +02003310option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003311 Enable logging of HTTP request, session state and timers
3312 May be used in sections : defaults | frontend | listen | backend
3313 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02003314 Arguments :
3315 clf if the "clf" argument is added, then the output format will be
3316 the CLF format instead of HAProxy's default HTTP format. You can
3317 use this when you need to feed HAProxy's logs through a specific
3318 log analyser which only support the CLF format and which is not
3319 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003320
3321 By default, the log output format is very poor, as it only contains the
3322 source and destination addresses, and the instance name. By specifying
3323 "option httplog", each log line turns into a much richer format including,
3324 but not limited to, the HTTP request, the connection timers, the session
3325 status, the connections numbers, the captured headers and cookies, the
3326 frontend, backend and server name, and of course the source address and
3327 ports.
3328
3329 This option may be set either in the frontend or the backend.
3330
Emeric Brun3a058f32009-06-30 18:26:00 +02003331 If this option has been enabled in a "defaults" section, it can be disabled
3332 in a specific instance by prepending the "no" keyword before it. Specifying
3333 only "option httplog" will automatically clear the 'clf' mode if it was set
3334 by default.
3335
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003336 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003337
Willy Tarreau55165fe2009-05-10 12:02:55 +02003338
3339option http_proxy
3340no option http_proxy
3341 Enable or disable plain HTTP proxy mode
3342 May be used in sections : defaults | frontend | listen | backend
3343 yes | yes | yes | yes
3344 Arguments : none
3345
3346 It sometimes happens that people need a pure HTTP proxy which understands
3347 basic proxy requests without caching nor any fancy feature. In this case,
3348 it may be worth setting up an HAProxy instance with the "option http_proxy"
3349 set. In this mode, no server is declared, and the connection is forwarded to
3350 the IP address and port found in the URL after the "http://" scheme.
3351
3352 No host address resolution is performed, so this only works when pure IP
3353 addresses are passed. Since this option's usage perimeter is rather limited,
3354 it will probably be used only by experts who know they need exactly it. Last,
3355 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01003356 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02003357 be analyzed.
3358
3359 If this option has been enabled in a "defaults" section, it can be disabled
3360 in a specific instance by prepending the "no" keyword before it.
3361
3362 Example :
3363 # this backend understands HTTP proxy requests and forwards them directly.
3364 backend direct_forward
3365 option httpclose
3366 option http_proxy
3367
3368 See also : "option httpclose"
3369
Willy Tarreau211ad242009-10-03 21:45:07 +02003370
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003371option independant-streams
3372no option independant-streams
3373 Enable or disable independant timeout processing for both directions
3374 May be used in sections : defaults | frontend | listen | backend
3375 yes | yes | yes | yes
3376 Arguments : none
3377
3378 By default, when data is sent over a socket, both the write timeout and the
3379 read timeout for that socket are refreshed, because we consider that there is
3380 activity on that socket, and we have no other means of guessing if we should
3381 receive data or not.
3382
3383 While this default behaviour is desirable for almost all applications, there
3384 exists a situation where it is desirable to disable it, and only refresh the
3385 read timeout if there are incoming data. This happens on sessions with large
3386 timeouts and low amounts of exchanged data such as telnet session. If the
3387 server suddenly disappears, the output data accumulates in the system's
3388 socket buffers, both timeouts are correctly refreshed, and there is no way
3389 to know the server does not receive them, so we don't timeout. However, when
3390 the underlying protocol always echoes sent data, it would be enough by itself
3391 to detect the issue using the read timeout. Note that this problem does not
3392 happen with more verbose protocols because data won't accumulate long in the
3393 socket buffers.
3394
3395 When this option is set on the frontend, it will disable read timeout updates
3396 on data sent to the client. There probably is little use of this case. When
3397 the option is set on the backend, it will disable read timeout updates on
3398 data sent to the server. Doing so will typically break large HTTP posts from
3399 slow lines, so use it with caution.
3400
3401 See also : "timeout client" and "timeout server"
3402
3403
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003404option ldap-check
3405 Use LDAPv3 health checks for server testing
3406 May be used in sections : defaults | frontend | listen | backend
3407 yes | no | yes | yes
3408 Arguments : none
3409
3410 It is possible to test that the server correctly talks LDAPv3 instead of just
3411 testing that it accepts the TCP connection. When this option is set, an
3412 LDAPv3 anonymous simple bind message is sent to the server, and the response
3413 is analyzed to find an LDAPv3 bind response message.
3414
3415 The server is considered valid only when the LDAP response contains success
3416 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
3417
3418 Logging of bind requests is server dependent see your documentation how to
3419 configure it.
3420
3421 Example :
3422 option ldap-check
3423
3424 See also : "option httpchk"
3425
3426
Willy Tarreau211ad242009-10-03 21:45:07 +02003427option log-health-checks
3428no option log-health-checks
3429 Enable or disable logging of health checks
3430 May be used in sections : defaults | frontend | listen | backend
3431 yes | no | yes | yes
3432 Arguments : none
3433
3434 Enable health checks logging so it possible to check for example what
3435 was happening before a server crash. Failed health check are logged if
3436 server is UP and succeeded health checks if server is DOWN, so the amount
3437 of additional information is limited.
3438
3439 If health check logging is enabled no health check status is printed
3440 when servers is set up UP/DOWN/ENABLED/DISABLED.
3441
3442 See also: "log" and section 8 about logging.
3443
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003444
3445option log-separate-errors
3446no option log-separate-errors
3447 Change log level for non-completely successful connections
3448 May be used in sections : defaults | frontend | listen | backend
3449 yes | yes | yes | no
3450 Arguments : none
3451
3452 Sometimes looking for errors in logs is not easy. This option makes haproxy
3453 raise the level of logs containing potentially interesting information such
3454 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
3455 level changes from "info" to "err". This makes it possible to log them
3456 separately to a different file with most syslog daemons. Be careful not to
3457 remove them from the original file, otherwise you would lose ordering which
3458 provides very important information.
3459
3460 Using this option, large sites dealing with several thousand connections per
3461 second may log normal traffic to a rotating buffer and only archive smaller
3462 error logs.
3463
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003464 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003465 logging.
3466
Willy Tarreauc27debf2008-01-06 08:57:02 +01003467
3468option logasap
3469no option logasap
3470 Enable or disable early logging of HTTP requests
3471 May be used in sections : defaults | frontend | listen | backend
3472 yes | yes | yes | no
3473 Arguments : none
3474
3475 By default, HTTP requests are logged upon termination so that the total
3476 transfer time and the number of bytes appear in the logs. When large objects
3477 are being transferred, it may take a while before the request appears in the
3478 logs. Using "option logasap", the request gets logged as soon as the server
3479 sends the complete headers. The only missing information in the logs will be
3480 the total number of bytes which will indicate everything except the amount
3481 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003482 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01003483 "Content-Length" response header so that the logs at least indicate how many
3484 bytes are expected to be transferred.
3485
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003486 Examples :
3487 listen http_proxy 0.0.0.0:80
3488 mode http
3489 option httplog
3490 option logasap
3491 log 192.168.2.200 local3
3492
3493 >>> Feb 6 12:14:14 localhost \
3494 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
3495 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
3496 "GET /image.iso HTTP/1.0"
3497
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003498 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01003499 logging.
3500
3501
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003502option mysql-check [ user <username> ]
3503 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003504 May be used in sections : defaults | frontend | listen | backend
3505 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003506 Arguments :
3507 user <username> This is the username which will be used when connecting
3508 to MySQL server.
3509
3510 If you specify a username, the check consists of sending two MySQL packet,
3511 one Client Authentication packet, and one QUIT packet, to correctly close
3512 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
3513 Error packet. It is a basic but useful test which does not produce error nor
3514 aborted connect on the server. However, it requires adding an authorization
3515 in the MySQL table, like this :
3516
3517 USE mysql;
3518 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
3519 FLUSH PRIVILEGES;
3520
3521 If you don't specify a username (it is deprecated and not recommended), the
3522 check only consists in parsing the Mysql Handshake Initialisation packet or
3523 Error packet, we don't send anything in this mode. It was reported that it
3524 can generate lockout if check is too frequent and/or if there is not enough
3525 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
3526 value as if a connection is established successfully within fewer than MySQL
3527 "max_connect_errors" attempts after a previous connection was interrupted,
3528 the error count for the host is cleared to zero. If HAProxy's server get
3529 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
3530
3531 Remember that this does not check database presence nor database consistency.
3532 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003533
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003534 The check requires MySQL >=4.0, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003535
3536 Most often, an incoming MySQL server needs to see the client's IP address for
3537 various purposes, including IP privilege matching and connection logging.
3538 When possible, it is often wise to masquerade the client's IP address when
3539 connecting to the server using the "usesrc" argument of the "source" keyword,
3540 which requires the cttproxy feature to be compiled in, and the MySQL server
3541 to route the client via the machine hosting haproxy.
3542
3543 See also: "option httpchk"
3544
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003545option pgsql-check [ user <username> ]
3546 Use PostgreSQL health checks for server testing
3547 May be used in sections : defaults | frontend | listen | backend
3548 yes | no | yes | yes
3549 Arguments :
3550 user <username> This is the username which will be used when connecting
3551 to PostgreSQL server.
3552
3553 The check sends a PostgreSQL StartupMessage and waits for either
3554 Authentication request or ErrorResponse message. It is a basic but useful
3555 test which does not produce error nor aborted connect on the server.
3556 This check is identical with the "mysql-check".
3557
3558 See also: "option httpchk"
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003559
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003560option nolinger
3561no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003562 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003563 May be used in sections: defaults | frontend | listen | backend
3564 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003565 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003566
3567 When clients or servers abort connections in a dirty way (eg: they are
3568 physically disconnected), the session timeouts triggers and the session is
3569 closed. But it will remain in FIN_WAIT1 state for some time in the system,
3570 using some resources and possibly limiting the ability to establish newer
3571 connections.
3572
3573 When this happens, it is possible to activate "option nolinger" which forces
3574 the system to immediately remove any socket's pending data on close. Thus,
3575 the session is instantly purged from the system's tables. This usually has
3576 side effects such as increased number of TCP resets due to old retransmits
3577 getting immediately rejected. Some firewalls may sometimes complain about
3578 this too.
3579
3580 For this reason, it is not recommended to use this option when not absolutely
3581 needed. You know that you need it when you have thousands of FIN_WAIT1
3582 sessions on your system (TIME_WAIT ones do not count).
3583
3584 This option may be used both on frontends and backends, depending on the side
3585 where it is required. Use it on the frontend for clients, and on the backend
3586 for servers.
3587
3588 If this option has been enabled in a "defaults" section, it can be disabled
3589 in a specific instance by prepending the "no" keyword before it.
3590
3591
Willy Tarreau55165fe2009-05-10 12:02:55 +02003592option originalto [ except <network> ] [ header <name> ]
3593 Enable insertion of the X-Original-To header to requests sent to servers
3594 May be used in sections : defaults | frontend | listen | backend
3595 yes | yes | yes | yes
3596 Arguments :
3597 <network> is an optional argument used to disable this option for sources
3598 matching <network>
3599 <name> an optional argument to specify a different "X-Original-To"
3600 header name.
3601
3602 Since HAProxy can work in transparent mode, every request from a client can
3603 be redirected to the proxy and HAProxy itself can proxy every request to a
3604 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
3605 be lost. This is annoying when you want access rules based on destination ip
3606 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
3607 added by HAProxy to all requests sent to the server. This header contains a
3608 value representing the original destination IP address. Since this must be
3609 configured to always use the last occurrence of this header only. Note that
3610 only the last occurrence of the header must be used, since it is really
3611 possible that the client has already brought one.
3612
3613 The keyword "header" may be used to supply a different header name to replace
3614 the default "X-Original-To". This can be useful where you might already
3615 have a "X-Original-To" header from a different application, and you need
3616 preserve it. Also if your backend server doesn't use the "X-Original-To"
3617 header and requires different one.
3618
3619 Sometimes, a same HAProxy instance may be shared between a direct client
3620 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3621 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3622 header for a known source address or network by adding the "except" keyword
3623 followed by the network address. In this case, any source IP matching the
3624 network will not cause an addition of this header. Most common uses are with
3625 private networks or 127.0.0.1.
3626
3627 This option may be specified either in the frontend or in the backend. If at
3628 least one of them uses it, the header will be added. Note that the backend's
3629 setting of the header subargument takes precedence over the frontend's if
3630 both are defined.
3631
3632 It is important to note that as long as HAProxy does not support keep-alive
3633 connections, only the first request of a connection will receive the header.
3634 For this reason, it is important to ensure that "option httpclose" is set
3635 when using this option.
3636
3637 Examples :
3638 # Original Destination address
3639 frontend www
3640 mode http
3641 option originalto except 127.0.0.1
3642
3643 # Those servers want the IP Address in X-Client-Dst
3644 backend www
3645 mode http
3646 option originalto header X-Client-Dst
3647
3648 See also : "option httpclose"
3649
3650
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003651option persist
3652no option persist
3653 Enable or disable forced persistence on down servers
3654 May be used in sections: defaults | frontend | listen | backend
3655 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003656 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003657
3658 When an HTTP request reaches a backend with a cookie which references a dead
3659 server, by default it is redispatched to another server. It is possible to
3660 force the request to be sent to the dead server first using "option persist"
3661 if absolutely needed. A common use case is when servers are under extreme
3662 load and spend their time flapping. In this case, the users would still be
3663 directed to the server they opened the session on, in the hope they would be
3664 correctly served. It is recommended to use "option redispatch" in conjunction
3665 with this option so that in the event it would not be possible to connect to
3666 the server at all (server definitely dead), the client would finally be
3667 redirected to another valid server.
3668
3669 If this option has been enabled in a "defaults" section, it can be disabled
3670 in a specific instance by prepending the "no" keyword before it.
3671
Willy Tarreau4de91492010-01-22 19:10:05 +01003672 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003673
3674
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003675option redispatch
3676no option redispatch
3677 Enable or disable session redistribution in case of connection failure
3678 May be used in sections: defaults | frontend | listen | backend
3679 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003680 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003681
3682 In HTTP mode, if a server designated by a cookie is down, clients may
3683 definitely stick to it because they cannot flush the cookie, so they will not
3684 be able to access the service anymore.
3685
3686 Specifying "option redispatch" will allow the proxy to break their
3687 persistence and redistribute them to a working server.
3688
3689 It also allows to retry last connection to another server in case of multiple
3690 connection failures. Of course, it requires having "retries" set to a nonzero
3691 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01003692
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003693 This form is the preferred form, which replaces both the "redispatch" and
3694 "redisp" keywords.
3695
3696 If this option has been enabled in a "defaults" section, it can be disabled
3697 in a specific instance by prepending the "no" keyword before it.
3698
Willy Tarreau4de91492010-01-22 19:10:05 +01003699 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003700
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003701
3702option smtpchk
3703option smtpchk <hello> <domain>
3704 Use SMTP health checks for server testing
3705 May be used in sections : defaults | frontend | listen | backend
3706 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01003707 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003708 <hello> is an optional argument. It is the "hello" command to use. It can
3709 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
3710 values will be turned into the default command ("HELO").
3711
3712 <domain> is the domain name to present to the server. It may only be
3713 specified (and is mandatory) if the hello command has been
3714 specified. By default, "localhost" is used.
3715
3716 When "option smtpchk" is set, the health checks will consist in TCP
3717 connections followed by an SMTP command. By default, this command is
3718 "HELO localhost". The server's return code is analyzed and only return codes
3719 starting with a "2" will be considered as valid. All other responses,
3720 including a lack of response will constitute an error and will indicate a
3721 dead server.
3722
3723 This test is meant to be used with SMTP servers or relays. Depending on the
3724 request, it is possible that some servers do not log each connection attempt,
3725 so you may want to experiment to improve the behaviour. Using telnet on port
3726 25 is often easier than adjusting the configuration.
3727
3728 Most often, an incoming SMTP server needs to see the client's IP address for
3729 various purposes, including spam filtering, anti-spoofing and logging. When
3730 possible, it is often wise to masquerade the client's IP address when
3731 connecting to the server using the "usesrc" argument of the "source" keyword,
3732 which requires the cttproxy feature to be compiled in.
3733
3734 Example :
3735 option smtpchk HELO mydomain.org
3736
3737 See also : "option httpchk", "source"
3738
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003739
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02003740option socket-stats
3741no option socket-stats
3742
3743 Enable or disable collecting & providing separate statistics for each socket.
3744 May be used in sections : defaults | frontend | listen | backend
3745 yes | yes | yes | no
3746
3747 Arguments : none
3748
3749
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003750option splice-auto
3751no option splice-auto
3752 Enable or disable automatic kernel acceleration on sockets in both directions
3753 May be used in sections : defaults | frontend | listen | backend
3754 yes | yes | yes | yes
3755 Arguments : none
3756
3757 When this option is enabled either on a frontend or on a backend, haproxy
3758 will automatically evaluate the opportunity to use kernel tcp splicing to
3759 forward data between the client and the server, in either direction. Haproxy
3760 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003761 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003762 are not much aggressive in order to limit excessive use of splicing. This
3763 option requires splicing to be enabled at compile time, and may be globally
3764 disabled with the global option "nosplice". Since splice uses pipes, using it
3765 requires that there are enough spare pipes.
3766
3767 Important note: kernel-based TCP splicing is a Linux-specific feature which
3768 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
3769 transfer data between sockets without copying these data to user-space, thus
3770 providing noticeable performance gains and CPU cycles savings. Since many
3771 early implementations are buggy, corrupt data and/or are inefficient, this
3772 feature is not enabled by default, and it should be used with extreme care.
3773 While it is not possible to detect the correctness of an implementation,
3774 2.6.29 is the first version offering a properly working implementation. In
3775 case of doubt, splicing may be globally disabled using the global "nosplice"
3776 keyword.
3777
3778 Example :
3779 option splice-auto
3780
3781 If this option has been enabled in a "defaults" section, it can be disabled
3782 in a specific instance by prepending the "no" keyword before it.
3783
3784 See also : "option splice-request", "option splice-response", and global
3785 options "nosplice" and "maxpipes"
3786
3787
3788option splice-request
3789no option splice-request
3790 Enable or disable automatic kernel acceleration on sockets for requests
3791 May be used in sections : defaults | frontend | listen | backend
3792 yes | yes | yes | yes
3793 Arguments : none
3794
3795 When this option is enabled either on a frontend or on a backend, haproxy
3796 will user kernel tcp splicing whenever possible to forward data going from
3797 the client to the server. It might still use the recv/send scheme if there
3798 are no spare pipes left. This option requires splicing to be enabled at
3799 compile time, and may be globally disabled with the global option "nosplice".
3800 Since splice uses pipes, using it requires that there are enough spare pipes.
3801
3802 Important note: see "option splice-auto" for usage limitations.
3803
3804 Example :
3805 option splice-request
3806
3807 If this option has been enabled in a "defaults" section, it can be disabled
3808 in a specific instance by prepending the "no" keyword before it.
3809
3810 See also : "option splice-auto", "option splice-response", and global options
3811 "nosplice" and "maxpipes"
3812
3813
3814option splice-response
3815no option splice-response
3816 Enable or disable automatic kernel acceleration on sockets for responses
3817 May be used in sections : defaults | frontend | listen | backend
3818 yes | yes | yes | yes
3819 Arguments : none
3820
3821 When this option is enabled either on a frontend or on a backend, haproxy
3822 will user kernel tcp splicing whenever possible to forward data going from
3823 the server to the client. It might still use the recv/send scheme if there
3824 are no spare pipes left. This option requires splicing to be enabled at
3825 compile time, and may be globally disabled with the global option "nosplice".
3826 Since splice uses pipes, using it requires that there are enough spare pipes.
3827
3828 Important note: see "option splice-auto" for usage limitations.
3829
3830 Example :
3831 option splice-response
3832
3833 If this option has been enabled in a "defaults" section, it can be disabled
3834 in a specific instance by prepending the "no" keyword before it.
3835
3836 See also : "option splice-auto", "option splice-request", and global options
3837 "nosplice" and "maxpipes"
3838
3839
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003840option srvtcpka
3841no option srvtcpka
3842 Enable or disable the sending of TCP keepalive packets on the server side
3843 May be used in sections : defaults | frontend | listen | backend
3844 yes | no | yes | yes
3845 Arguments : none
3846
3847 When there is a firewall or any session-aware component between a client and
3848 a server, and when the protocol involves very long sessions with long idle
3849 periods (eg: remote desktops), there is a risk that one of the intermediate
3850 components decides to expire a session which has remained idle for too long.
3851
3852 Enabling socket-level TCP keep-alives makes the system regularly send packets
3853 to the other end of the connection, leaving it active. The delay between
3854 keep-alive probes is controlled by the system only and depends both on the
3855 operating system and its tuning parameters.
3856
3857 It is important to understand that keep-alive packets are neither emitted nor
3858 received at the application level. It is only the network stacks which sees
3859 them. For this reason, even if one side of the proxy already uses keep-alives
3860 to maintain its connection alive, those keep-alive packets will not be
3861 forwarded to the other side of the proxy.
3862
3863 Please note that this has nothing to do with HTTP keep-alive.
3864
3865 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
3866 server side of a connection, which should help when session expirations are
3867 noticed between HAProxy and a server.
3868
3869 If this option has been enabled in a "defaults" section, it can be disabled
3870 in a specific instance by prepending the "no" keyword before it.
3871
3872 See also : "option clitcpka", "option tcpka"
3873
3874
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003875option ssl-hello-chk
3876 Use SSLv3 client hello health checks for server testing
3877 May be used in sections : defaults | frontend | listen | backend
3878 yes | no | yes | yes
3879 Arguments : none
3880
3881 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
3882 possible to test that the server correctly talks SSL instead of just testing
3883 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
3884 SSLv3 client hello messages are sent once the connection is established to
3885 the server, and the response is analyzed to find an SSL server hello message.
3886 The server is considered valid only when the response contains this server
3887 hello message.
3888
3889 All servers tested till there correctly reply to SSLv3 client hello messages,
3890 and most servers tested do not even log the requests containing only hello
3891 messages, which is appreciable.
3892
3893 See also: "option httpchk"
3894
3895
Willy Tarreau9ea05a72009-06-14 12:07:01 +02003896option tcp-smart-accept
3897no option tcp-smart-accept
3898 Enable or disable the saving of one ACK packet during the accept sequence
3899 May be used in sections : defaults | frontend | listen | backend
3900 yes | yes | yes | no
3901 Arguments : none
3902
3903 When an HTTP connection request comes in, the system acknowledges it on
3904 behalf of HAProxy, then the client immediately sends its request, and the
3905 system acknowledges it too while it is notifying HAProxy about the new
3906 connection. HAProxy then reads the request and responds. This means that we
3907 have one TCP ACK sent by the system for nothing, because the request could
3908 very well be acknowledged by HAProxy when it sends its response.
3909
3910 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
3911 sending this useless ACK on platforms which support it (currently at least
3912 Linux). It must not cause any problem, because the system will send it anyway
3913 after 40 ms if the response takes more time than expected to come.
3914
3915 During complex network debugging sessions, it may be desirable to disable
3916 this optimization because delayed ACKs can make troubleshooting more complex
3917 when trying to identify where packets are delayed. It is then possible to
3918 fall back to normal behaviour by specifying "no option tcp-smart-accept".
3919
3920 It is also possible to force it for non-HTTP proxies by simply specifying
3921 "option tcp-smart-accept". For instance, it can make sense with some services
3922 such as SMTP where the server speaks first.
3923
3924 It is recommended to avoid forcing this option in a defaults section. In case
3925 of doubt, consider setting it back to automatic values by prepending the
3926 "default" keyword before it, or disabling it using the "no" keyword.
3927
Willy Tarreaud88edf22009-06-14 15:48:17 +02003928 See also : "option tcp-smart-connect"
3929
3930
3931option tcp-smart-connect
3932no option tcp-smart-connect
3933 Enable or disable the saving of one ACK packet during the connect sequence
3934 May be used in sections : defaults | frontend | listen | backend
3935 yes | no | yes | yes
3936 Arguments : none
3937
3938 On certain systems (at least Linux), HAProxy can ask the kernel not to
3939 immediately send an empty ACK upon a connection request, but to directly
3940 send the buffer request instead. This saves one packet on the network and
3941 thus boosts performance. It can also be useful for some servers, because they
3942 immediately get the request along with the incoming connection.
3943
3944 This feature is enabled when "option tcp-smart-connect" is set in a backend.
3945 It is not enabled by default because it makes network troubleshooting more
3946 complex.
3947
3948 It only makes sense to enable it with protocols where the client speaks first
3949 such as HTTP. In other situations, if there is no data to send in place of
3950 the ACK, a normal ACK is sent.
3951
3952 If this option has been enabled in a "defaults" section, it can be disabled
3953 in a specific instance by prepending the "no" keyword before it.
3954
3955 See also : "option tcp-smart-accept"
3956
Willy Tarreau9ea05a72009-06-14 12:07:01 +02003957
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003958option tcpka
3959 Enable or disable the sending of TCP keepalive packets on both sides
3960 May be used in sections : defaults | frontend | listen | backend
3961 yes | yes | yes | yes
3962 Arguments : none
3963
3964 When there is a firewall or any session-aware component between a client and
3965 a server, and when the protocol involves very long sessions with long idle
3966 periods (eg: remote desktops), there is a risk that one of the intermediate
3967 components decides to expire a session which has remained idle for too long.
3968
3969 Enabling socket-level TCP keep-alives makes the system regularly send packets
3970 to the other end of the connection, leaving it active. The delay between
3971 keep-alive probes is controlled by the system only and depends both on the
3972 operating system and its tuning parameters.
3973
3974 It is important to understand that keep-alive packets are neither emitted nor
3975 received at the application level. It is only the network stacks which sees
3976 them. For this reason, even if one side of the proxy already uses keep-alives
3977 to maintain its connection alive, those keep-alive packets will not be
3978 forwarded to the other side of the proxy.
3979
3980 Please note that this has nothing to do with HTTP keep-alive.
3981
3982 Using option "tcpka" enables the emission of TCP keep-alive probes on both
3983 the client and server sides of a connection. Note that this is meaningful
3984 only in "defaults" or "listen" sections. If this option is used in a
3985 frontend, only the client side will get keep-alives, and if this option is
3986 used in a backend, only the server side will get keep-alives. For this
3987 reason, it is strongly recommended to explicitly use "option clitcpka" and
3988 "option srvtcpka" when the configuration is split between frontends and
3989 backends.
3990
3991 See also : "option clitcpka", "option srvtcpka"
3992
Willy Tarreau844e3c52008-01-11 16:28:18 +01003993
3994option tcplog
3995 Enable advanced logging of TCP connections with session state and timers
3996 May be used in sections : defaults | frontend | listen | backend
3997 yes | yes | yes | yes
3998 Arguments : none
3999
4000 By default, the log output format is very poor, as it only contains the
4001 source and destination addresses, and the instance name. By specifying
4002 "option tcplog", each log line turns into a much richer format including, but
4003 not limited to, the connection timers, the session status, the connections
4004 numbers, the frontend, backend and server name, and of course the source
4005 address and ports. This option is useful for pure TCP proxies in order to
4006 find which of the client or server disconnects or times out. For normal HTTP
4007 proxies, it's better to use "option httplog" which is even more complete.
4008
4009 This option may be set either in the frontend or the backend.
4010
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004011 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004012
4013
Willy Tarreau844e3c52008-01-11 16:28:18 +01004014option transparent
4015no option transparent
4016 Enable client-side transparent proxying
4017 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004018 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004019 Arguments : none
4020
4021 This option was introduced in order to provide layer 7 persistence to layer 3
4022 load balancers. The idea is to use the OS's ability to redirect an incoming
4023 connection for a remote address to a local process (here HAProxy), and let
4024 this process know what address was initially requested. When this option is
4025 used, sessions without cookies will be forwarded to the original destination
4026 IP address of the incoming request (which should match that of another
4027 equipment), while requests with cookies will still be forwarded to the
4028 appropriate server.
4029
4030 Note that contrary to a common belief, this option does NOT make HAProxy
4031 present the client's IP to the server when establishing the connection.
4032
Willy Tarreaua1146052011-03-01 09:51:54 +01004033 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004034 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004035
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004036
Emeric Brun647caf12009-06-30 17:57:00 +02004037persist rdp-cookie
4038persist rdp-cookie(name)
4039 Enable RDP cookie-based persistence
4040 May be used in sections : defaults | frontend | listen | backend
4041 yes | no | yes | yes
4042 Arguments :
4043 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02004044 default cookie name "msts" will be used. There currently is no
4045 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02004046
4047 This statement enables persistence based on an RDP cookie. The RDP cookie
4048 contains all information required to find the server in the list of known
4049 servers. So when this option is set in the backend, the request is analysed
4050 and if an RDP cookie is found, it is decoded. If it matches a known server
4051 which is still UP (or if "option persist" is set), then the connection is
4052 forwarded to this server.
4053
4054 Note that this only makes sense in a TCP backend, but for this to work, the
4055 frontend must have waited long enough to ensure that an RDP cookie is present
4056 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004057 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02004058 a single "listen" section.
4059
Willy Tarreau61e28f22010-05-16 22:31:05 +02004060 Also, it is important to understand that the terminal server will emit this
4061 RDP cookie only if it is configured for "token redirection mode", which means
4062 that the "IP address redirection" option is disabled.
4063
Emeric Brun647caf12009-06-30 17:57:00 +02004064 Example :
4065 listen tse-farm
4066 bind :3389
4067 # wait up to 5s for an RDP cookie in the request
4068 tcp-request inspect-delay 5s
4069 tcp-request content accept if RDP_COOKIE
4070 # apply RDP cookie persistence
4071 persist rdp-cookie
4072 # if server is unknown, let's balance on the same cookie.
4073 # alternatively, "balance leastconn" may be useful too.
4074 balance rdp-cookie
4075 server srv1 1.1.1.1:3389
4076 server srv2 1.1.1.2:3389
4077
4078 See also : "balance rdp-cookie", "tcp-request" and the "req_rdp_cookie" ACL.
4079
4080
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004081rate-limit sessions <rate>
4082 Set a limit on the number of new sessions accepted per second on a frontend
4083 May be used in sections : defaults | frontend | listen | backend
4084 yes | yes | yes | no
4085 Arguments :
4086 <rate> The <rate> parameter is an integer designating the maximum number
4087 of new sessions per second to accept on the frontend.
4088
4089 When the frontend reaches the specified number of new sessions per second, it
4090 stops accepting new connections until the rate drops below the limit again.
4091 During this time, the pending sessions will be kept in the socket's backlog
4092 (in system buffers) and haproxy will not even be aware that sessions are
4093 pending. When applying very low limit on a highly loaded service, it may make
4094 sense to increase the socket's backlog using the "backlog" keyword.
4095
4096 This feature is particularly efficient at blocking connection-based attacks
4097 or service abuse on fragile servers. Since the session rate is measured every
4098 millisecond, it is extremely accurate. Also, the limit applies immediately,
4099 no delay is needed at all to detect the threshold.
4100
4101 Example : limit the connection rate on SMTP to 10 per second max
4102 listen smtp
4103 mode tcp
4104 bind :25
4105 rate-limit sessions 10
4106 server 127.0.0.1:1025
4107
4108 Note : when the maximum rate is reached, the frontend's status appears as
4109 "FULL" in the statistics, exactly as when it is saturated.
4110
4111 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
4112
4113
Willy Tarreauf285f542010-01-03 20:03:03 +01004114redirect location <to> [code <code>] <option> [{if | unless} <condition>]
4115redirect prefix <to> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004116 Return an HTTP redirection if/unless a condition is matched
4117 May be used in sections : defaults | frontend | listen | backend
4118 no | yes | yes | yes
4119
4120 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01004121 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004122
Willy Tarreau0140f252008-11-19 21:07:09 +01004123 Arguments :
4124 <to> With "redirect location", the exact value in <to> is placed into
4125 the HTTP "Location" header. In case of "redirect prefix", the
4126 "Location" header is built from the concatenation of <to> and the
4127 complete URI, including the query string, unless the "drop-query"
Willy Tarreaufe651a52008-11-19 21:15:17 +01004128 option is specified (see below). As a special case, if <to>
4129 equals exactly "/" in prefix mode, then nothing is inserted
4130 before the original URI. It allows one to redirect to the same
4131 URL.
Willy Tarreau0140f252008-11-19 21:07:09 +01004132
4133 <code> The code is optional. It indicates which type of HTTP redirection
4134 is desired. Only codes 301, 302 and 303 are supported, and 302 is
4135 used if no code is specified. 301 means "Moved permanently", and
4136 a browser may cache the Location. 302 means "Moved permanently"
4137 and means that the browser should not cache the redirection. 303
4138 is equivalent to 302 except that the browser will fetch the
4139 location with a GET method.
4140
4141 <option> There are several options which can be specified to adjust the
4142 expected behaviour of a redirection :
4143
4144 - "drop-query"
4145 When this keyword is used in a prefix-based redirection, then the
4146 location will be set without any possible query-string, which is useful
4147 for directing users to a non-secure page for instance. It has no effect
4148 with a location-type redirect.
4149
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004150 - "append-slash"
4151 This keyword may be used in conjunction with "drop-query" to redirect
4152 users who use a URL not ending with a '/' to the same one with the '/'.
4153 It can be useful to ensure that search engines will only see one URL.
4154 For this, a return code 301 is preferred.
4155
Willy Tarreau0140f252008-11-19 21:07:09 +01004156 - "set-cookie NAME[=value]"
4157 A "Set-Cookie" header will be added with NAME (and optionally "=value")
4158 to the response. This is sometimes used to indicate that a user has
4159 been seen, for instance to protect against some types of DoS. No other
4160 cookie option is added, so the cookie will be a session cookie. Note
4161 that for a browser, a sole cookie name without an equal sign is
4162 different from a cookie with an equal sign.
4163
4164 - "clear-cookie NAME[=]"
4165 A "Set-Cookie" header will be added with NAME (and optionally "="), but
4166 with the "Max-Age" attribute set to zero. This will tell the browser to
4167 delete this cookie. It is useful for instance on logout pages. It is
4168 important to note that clearing the cookie "NAME" will not remove a
4169 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
4170 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004171
4172 Example: move the login URL only to HTTPS.
4173 acl clear dst_port 80
4174 acl secure dst_port 8080
4175 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01004176 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01004177 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01004178 acl cookie_set hdr_sub(cookie) SEEN=1
4179
4180 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01004181 redirect prefix https://mysite.com if login_page !secure
4182 redirect prefix http://mysite.com drop-query if login_page !uid_given
4183 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01004184 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004185
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004186 Example: send redirects for request for articles without a '/'.
4187 acl missing_slash path_reg ^/article/[^/]*$
4188 redirect code 301 prefix / drop-query append-slash if missing_slash
4189
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004190 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004191
4192
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004193redisp (deprecated)
4194redispatch (deprecated)
4195 Enable or disable session redistribution in case of connection failure
4196 May be used in sections: defaults | frontend | listen | backend
4197 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004198 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004199
4200 In HTTP mode, if a server designated by a cookie is down, clients may
4201 definitely stick to it because they cannot flush the cookie, so they will not
4202 be able to access the service anymore.
4203
4204 Specifying "redispatch" will allow the proxy to break their persistence and
4205 redistribute them to a working server.
4206
4207 It also allows to retry last connection to another server in case of multiple
4208 connection failures. Of course, it requires having "retries" set to a nonzero
4209 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004210
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004211 This form is deprecated, do not use it in any new configuration, use the new
4212 "option redispatch" instead.
4213
4214 See also : "option redispatch"
4215
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004216
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004217reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004218 Add a header at the end of the HTTP request
4219 May be used in sections : defaults | frontend | listen | backend
4220 no | yes | yes | yes
4221 Arguments :
4222 <string> is the complete line to be added. Any space or known delimiter
4223 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004224 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004225
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004226 <cond> is an optional matching condition built from ACLs. It makes it
4227 possible to ignore this rule when other conditions are not met.
4228
Willy Tarreau303c0352008-01-17 19:01:39 +01004229 A new line consisting in <string> followed by a line feed will be added after
4230 the last header of an HTTP request.
4231
4232 Header transformations only apply to traffic which passes through HAProxy,
4233 and not to traffic generated by HAProxy, such as health-checks or error
4234 responses.
4235
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004236 Example : add "X-Proto: SSL" to requests coming via port 81
4237 acl is-ssl dst_port 81
4238 reqadd X-Proto:\ SSL if is-ssl
4239
4240 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
4241 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004242
4243
Willy Tarreau5321c422010-01-28 20:35:13 +01004244reqallow <search> [{if | unless} <cond>]
4245reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004246 Definitely allow an HTTP request if a line matches a regular expression
4247 May be used in sections : defaults | frontend | listen | backend
4248 no | yes | yes | yes
4249 Arguments :
4250 <search> is the regular expression applied to HTTP headers and to the
4251 request line. This is an extended regular expression. Parenthesis
4252 grouping is supported and no preliminary backslash is required.
4253 Any space or known delimiter must be escaped using a backslash
4254 ('\'). The pattern applies to a full line at a time. The
4255 "reqallow" keyword strictly matches case while "reqiallow"
4256 ignores case.
4257
Willy Tarreau5321c422010-01-28 20:35:13 +01004258 <cond> is an optional matching condition built from ACLs. It makes it
4259 possible to ignore this rule when other conditions are not met.
4260
Willy Tarreau303c0352008-01-17 19:01:39 +01004261 A request containing any line which matches extended regular expression
4262 <search> will mark the request as allowed, even if any later test would
4263 result in a deny. The test applies both to the request line and to request
4264 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004265 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004266
4267 It is easier, faster and more powerful to use ACLs to write access policies.
4268 Reqdeny, reqallow and reqpass should be avoided in new designs.
4269
4270 Example :
4271 # allow www.* but refuse *.local
4272 reqiallow ^Host:\ www\.
4273 reqideny ^Host:\ .*\.local
4274
Willy Tarreau5321c422010-01-28 20:35:13 +01004275 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
4276 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004277
4278
Willy Tarreau5321c422010-01-28 20:35:13 +01004279reqdel <search> [{if | unless} <cond>]
4280reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004281 Delete all headers matching a regular expression in an HTTP request
4282 May be used in sections : defaults | frontend | listen | backend
4283 no | yes | yes | yes
4284 Arguments :
4285 <search> is the regular expression applied to HTTP headers and to the
4286 request line. This is an extended regular expression. Parenthesis
4287 grouping is supported and no preliminary backslash is required.
4288 Any space or known delimiter must be escaped using a backslash
4289 ('\'). The pattern applies to a full line at a time. The "reqdel"
4290 keyword strictly matches case while "reqidel" ignores case.
4291
Willy Tarreau5321c422010-01-28 20:35:13 +01004292 <cond> is an optional matching condition built from ACLs. It makes it
4293 possible to ignore this rule when other conditions are not met.
4294
Willy Tarreau303c0352008-01-17 19:01:39 +01004295 Any header line matching extended regular expression <search> in the request
4296 will be completely deleted. Most common use of this is to remove unwanted
4297 and/or dangerous headers or cookies from a request before passing it to the
4298 next servers.
4299
4300 Header transformations only apply to traffic which passes through HAProxy,
4301 and not to traffic generated by HAProxy, such as health-checks or error
4302 responses. Keep in mind that header names are not case-sensitive.
4303
4304 Example :
4305 # remove X-Forwarded-For header and SERVER cookie
4306 reqidel ^X-Forwarded-For:.*
4307 reqidel ^Cookie:.*SERVER=
4308
Willy Tarreau5321c422010-01-28 20:35:13 +01004309 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
4310 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004311
4312
Willy Tarreau5321c422010-01-28 20:35:13 +01004313reqdeny <search> [{if | unless} <cond>]
4314reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004315 Deny an HTTP request if a line matches a regular expression
4316 May be used in sections : defaults | frontend | listen | backend
4317 no | yes | yes | yes
4318 Arguments :
4319 <search> is the regular expression applied to HTTP headers and to the
4320 request line. This is an extended regular expression. Parenthesis
4321 grouping is supported and no preliminary backslash is required.
4322 Any space or known delimiter must be escaped using a backslash
4323 ('\'). The pattern applies to a full line at a time. The
4324 "reqdeny" keyword strictly matches case while "reqideny" ignores
4325 case.
4326
Willy Tarreau5321c422010-01-28 20:35:13 +01004327 <cond> is an optional matching condition built from ACLs. It makes it
4328 possible to ignore this rule when other conditions are not met.
4329
Willy Tarreau303c0352008-01-17 19:01:39 +01004330 A request containing any line which matches extended regular expression
4331 <search> will mark the request as denied, even if any later test would
4332 result in an allow. The test applies both to the request line and to request
4333 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004334 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004335
Willy Tarreauced27012008-01-17 20:35:34 +01004336 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004337 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01004338 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01004339
Willy Tarreau303c0352008-01-17 19:01:39 +01004340 It is easier, faster and more powerful to use ACLs to write access policies.
4341 Reqdeny, reqallow and reqpass should be avoided in new designs.
4342
4343 Example :
4344 # refuse *.local, then allow www.*
4345 reqideny ^Host:\ .*\.local
4346 reqiallow ^Host:\ www\.
4347
Willy Tarreau5321c422010-01-28 20:35:13 +01004348 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
4349 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004350
4351
Willy Tarreau5321c422010-01-28 20:35:13 +01004352reqpass <search> [{if | unless} <cond>]
4353reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004354 Ignore any HTTP request line matching a regular expression in next rules
4355 May be used in sections : defaults | frontend | listen | backend
4356 no | yes | yes | yes
4357 Arguments :
4358 <search> is the regular expression applied to HTTP headers and to the
4359 request line. This is an extended regular expression. Parenthesis
4360 grouping is supported and no preliminary backslash is required.
4361 Any space or known delimiter must be escaped using a backslash
4362 ('\'). The pattern applies to a full line at a time. The
4363 "reqpass" keyword strictly matches case while "reqipass" ignores
4364 case.
4365
Willy Tarreau5321c422010-01-28 20:35:13 +01004366 <cond> is an optional matching condition built from ACLs. It makes it
4367 possible to ignore this rule when other conditions are not met.
4368
Willy Tarreau303c0352008-01-17 19:01:39 +01004369 A request containing any line which matches extended regular expression
4370 <search> will skip next rules, without assigning any deny or allow verdict.
4371 The test applies both to the request line and to request headers. Keep in
4372 mind that URLs in request line are case-sensitive while header names are not.
4373
4374 It is easier, faster and more powerful to use ACLs to write access policies.
4375 Reqdeny, reqallow and reqpass should be avoided in new designs.
4376
4377 Example :
4378 # refuse *.local, then allow www.*, but ignore "www.private.local"
4379 reqipass ^Host:\ www.private\.local
4380 reqideny ^Host:\ .*\.local
4381 reqiallow ^Host:\ www\.
4382
Willy Tarreau5321c422010-01-28 20:35:13 +01004383 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
4384 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004385
4386
Willy Tarreau5321c422010-01-28 20:35:13 +01004387reqrep <search> <string> [{if | unless} <cond>]
4388reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004389 Replace a regular expression with a string in an HTTP request line
4390 May be used in sections : defaults | frontend | listen | backend
4391 no | yes | yes | yes
4392 Arguments :
4393 <search> is the regular expression applied to HTTP headers and to the
4394 request line. This is an extended regular expression. Parenthesis
4395 grouping is supported and no preliminary backslash is required.
4396 Any space or known delimiter must be escaped using a backslash
4397 ('\'). The pattern applies to a full line at a time. The "reqrep"
4398 keyword strictly matches case while "reqirep" ignores case.
4399
4400 <string> is the complete line to be added. Any space or known delimiter
4401 must be escaped using a backslash ('\'). References to matched
4402 pattern groups are possible using the common \N form, with N
4403 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004404 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004405
Willy Tarreau5321c422010-01-28 20:35:13 +01004406 <cond> is an optional matching condition built from ACLs. It makes it
4407 possible to ignore this rule when other conditions are not met.
4408
Willy Tarreau303c0352008-01-17 19:01:39 +01004409 Any line matching extended regular expression <search> in the request (both
4410 the request line and header lines) will be completely replaced with <string>.
4411 Most common use of this is to rewrite URLs or domain names in "Host" headers.
4412
4413 Header transformations only apply to traffic which passes through HAProxy,
4414 and not to traffic generated by HAProxy, such as health-checks or error
4415 responses. Note that for increased readability, it is suggested to add enough
4416 spaces between the request and the response. Keep in mind that URLs in
4417 request line are case-sensitive while header names are not.
4418
4419 Example :
4420 # replace "/static/" with "/" at the beginning of any request path.
4421 reqrep ^([^\ ]*)\ /static/(.*) \1\ /\2
4422 # replace "www.mydomain.com" with "www" in the host name.
4423 reqirep ^Host:\ www.mydomain.com Host:\ www
4424
Willy Tarreau5321c422010-01-28 20:35:13 +01004425 See also: "reqadd", "reqdel", "rsprep", section 6 about HTTP header
4426 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004427
4428
Willy Tarreau5321c422010-01-28 20:35:13 +01004429reqtarpit <search> [{if | unless} <cond>]
4430reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004431 Tarpit an HTTP request containing a line matching a regular expression
4432 May be used in sections : defaults | frontend | listen | backend
4433 no | yes | yes | yes
4434 Arguments :
4435 <search> is the regular expression applied to HTTP headers and to the
4436 request line. This is an extended regular expression. Parenthesis
4437 grouping is supported and no preliminary backslash is required.
4438 Any space or known delimiter must be escaped using a backslash
4439 ('\'). The pattern applies to a full line at a time. The
4440 "reqtarpit" keyword strictly matches case while "reqitarpit"
4441 ignores case.
4442
Willy Tarreau5321c422010-01-28 20:35:13 +01004443 <cond> is an optional matching condition built from ACLs. It makes it
4444 possible to ignore this rule when other conditions are not met.
4445
Willy Tarreau303c0352008-01-17 19:01:39 +01004446 A request containing any line which matches extended regular expression
4447 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01004448 be kept open for a pre-defined time, then will return an HTTP error 500 so
4449 that the attacker does not suspect it has been tarpitted. The status 500 will
4450 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01004451 delay is defined by "timeout tarpit", or "timeout connect" if the former is
4452 not set.
4453
4454 The goal of the tarpit is to slow down robots attacking servers with
4455 identifiable requests. Many robots limit their outgoing number of connections
4456 and stay connected waiting for a reply which can take several minutes to
4457 come. Depending on the environment and attack, it may be particularly
4458 efficient at reducing the load on the network and firewalls.
4459
Willy Tarreau5321c422010-01-28 20:35:13 +01004460 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01004461 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
4462 # block all others.
4463 reqipass ^User-Agent:\.*(Mozilla|MSIE)
4464 reqitarpit ^User-Agent:
4465
Willy Tarreau5321c422010-01-28 20:35:13 +01004466 # block bad guys
4467 acl badguys src 10.1.0.3 172.16.13.20/28
4468 reqitarpit . if badguys
4469
4470 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
4471 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004472
4473
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02004474retries <value>
4475 Set the number of retries to perform on a server after a connection failure
4476 May be used in sections: defaults | frontend | listen | backend
4477 yes | no | yes | yes
4478 Arguments :
4479 <value> is the number of times a connection attempt should be retried on
4480 a server when a connection either is refused or times out. The
4481 default value is 3.
4482
4483 It is important to understand that this value applies to the number of
4484 connection attempts, not full requests. When a connection has effectively
4485 been established to a server, there will be no more retry.
4486
4487 In order to avoid immediate reconnections to a server which is restarting,
4488 a turn-around timer of 1 second is applied before a retry occurs.
4489
4490 When "option redispatch" is set, the last retry may be performed on another
4491 server even if a cookie references a different server.
4492
4493 See also : "option redispatch"
4494
4495
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004496rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004497 Add a header at the end of the HTTP response
4498 May be used in sections : defaults | frontend | listen | backend
4499 no | yes | yes | yes
4500 Arguments :
4501 <string> is the complete line to be added. Any space or known delimiter
4502 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004503 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004504
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004505 <cond> is an optional matching condition built from ACLs. It makes it
4506 possible to ignore this rule when other conditions are not met.
4507
Willy Tarreau303c0352008-01-17 19:01:39 +01004508 A new line consisting in <string> followed by a line feed will be added after
4509 the last header of an HTTP response.
4510
4511 Header transformations only apply to traffic which passes through HAProxy,
4512 and not to traffic generated by HAProxy, such as health-checks or error
4513 responses.
4514
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004515 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
4516 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004517
4518
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004519rspdel <search> [{if | unless} <cond>]
4520rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004521 Delete all headers matching a regular expression in an HTTP response
4522 May be used in sections : defaults | frontend | listen | backend
4523 no | yes | yes | yes
4524 Arguments :
4525 <search> is the regular expression applied to HTTP headers and to the
4526 response line. This is an extended regular expression, so
4527 parenthesis grouping is supported and no preliminary backslash
4528 is required. Any space or known delimiter must be escaped using
4529 a backslash ('\'). The pattern applies to a full line at a time.
4530 The "rspdel" keyword strictly matches case while "rspidel"
4531 ignores case.
4532
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004533 <cond> is an optional matching condition built from ACLs. It makes it
4534 possible to ignore this rule when other conditions are not met.
4535
Willy Tarreau303c0352008-01-17 19:01:39 +01004536 Any header line matching extended regular expression <search> in the response
4537 will be completely deleted. Most common use of this is to remove unwanted
4538 and/or sensible headers or cookies from a response before passing it to the
4539 client.
4540
4541 Header transformations only apply to traffic which passes through HAProxy,
4542 and not to traffic generated by HAProxy, such as health-checks or error
4543 responses. Keep in mind that header names are not case-sensitive.
4544
4545 Example :
4546 # remove the Server header from responses
4547 reqidel ^Server:.*
4548
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004549 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
4550 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004551
4552
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004553rspdeny <search> [{if | unless} <cond>]
4554rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004555 Block an HTTP response if a line matches a regular expression
4556 May be used in sections : defaults | frontend | listen | backend
4557 no | yes | yes | yes
4558 Arguments :
4559 <search> is the regular expression applied to HTTP headers and to the
4560 response line. This is an extended regular expression, so
4561 parenthesis grouping is supported and no preliminary backslash
4562 is required. Any space or known delimiter must be escaped using
4563 a backslash ('\'). The pattern applies to a full line at a time.
4564 The "rspdeny" keyword strictly matches case while "rspideny"
4565 ignores case.
4566
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004567 <cond> is an optional matching condition built from ACLs. It makes it
4568 possible to ignore this rule when other conditions are not met.
4569
Willy Tarreau303c0352008-01-17 19:01:39 +01004570 A response containing any line which matches extended regular expression
4571 <search> will mark the request as denied. The test applies both to the
4572 response line and to response headers. Keep in mind that header names are not
4573 case-sensitive.
4574
4575 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01004576 block the response before it reaches the client. If a response is denied, it
4577 will be replaced with an HTTP 502 error so that the client never retrieves
4578 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01004579
4580 It is easier, faster and more powerful to use ACLs to write access policies.
4581 Rspdeny should be avoided in new designs.
4582
4583 Example :
4584 # Ensure that no content type matching ms-word will leak
4585 rspideny ^Content-type:\.*/ms-word
4586
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004587 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
4588 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004589
4590
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004591rsprep <search> <string> [{if | unless} <cond>]
4592rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004593 Replace a regular expression with a string in an HTTP response line
4594 May be used in sections : defaults | frontend | listen | backend
4595 no | yes | yes | yes
4596 Arguments :
4597 <search> is the regular expression applied to HTTP headers and to the
4598 response line. This is an extended regular expression, so
4599 parenthesis grouping is supported and no preliminary backslash
4600 is required. Any space or known delimiter must be escaped using
4601 a backslash ('\'). The pattern applies to a full line at a time.
4602 The "rsprep" keyword strictly matches case while "rspirep"
4603 ignores case.
4604
4605 <string> is the complete line to be added. Any space or known delimiter
4606 must be escaped using a backslash ('\'). References to matched
4607 pattern groups are possible using the common \N form, with N
4608 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004609 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004610
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004611 <cond> is an optional matching condition built from ACLs. It makes it
4612 possible to ignore this rule when other conditions are not met.
4613
Willy Tarreau303c0352008-01-17 19:01:39 +01004614 Any line matching extended regular expression <search> in the response (both
4615 the response line and header lines) will be completely replaced with
4616 <string>. Most common use of this is to rewrite Location headers.
4617
4618 Header transformations only apply to traffic which passes through HAProxy,
4619 and not to traffic generated by HAProxy, such as health-checks or error
4620 responses. Note that for increased readability, it is suggested to add enough
4621 spaces between the request and the response. Keep in mind that header names
4622 are not case-sensitive.
4623
4624 Example :
4625 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
4626 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
4627
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004628 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
4629 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004630
4631
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004632server <name> <address>[:port] [param*]
4633 Declare a server in a backend
4634 May be used in sections : defaults | frontend | listen | backend
4635 no | no | yes | yes
4636 Arguments :
4637 <name> is the internal name assigned to this server. This name will
4638 appear in logs and alerts.
4639
4640 <address> is the IPv4 address of the server. Alternatively, a resolvable
4641 hostname is supported, but this name will be resolved during
Willy Tarreaud669a4f2010-07-13 14:49:50 +02004642 start-up. Address "0.0.0.0" or "*" has a special meaning. It
4643 indicates that the connection will be forwarded to the same IP
4644 address as the one from the client connection. This is useful in
4645 transparent proxy architectures where the client's connection is
4646 intercepted and haproxy must forward to the original destination
4647 address. This is more or less what the "transparent" keyword does
4648 except that with a server it's possible to limit concurrency and
4649 to report statistics.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004650
4651 <ports> is an optional port specification. If set, all connections will
4652 be sent to this port. If unset, the same port the client
4653 connected to will be used. The port may also be prefixed by a "+"
4654 or a "-". In this case, the server's port will be determined by
4655 adding this value to the client's port.
4656
4657 <param*> is a list of parameters for this server. The "server" keywords
4658 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004659 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004660
4661 Examples :
4662 server first 10.1.1.1:1080 cookie first check inter 1000
4663 server second 10.1.1.2:1080 cookie second check inter 1000
4664
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004665 See also: "default-server" and section 5 about server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004666
4667
4668source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02004669source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004670source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004671 Set the source address for outgoing connections
4672 May be used in sections : defaults | frontend | listen | backend
4673 yes | no | yes | yes
4674 Arguments :
4675 <addr> is the IPv4 address HAProxy will bind to before connecting to a
4676 server. This address is also used as a source for health checks.
4677 The default value of 0.0.0.0 means that the system will select
4678 the most appropriate address to reach its destination.
4679
4680 <port> is an optional port. It is normally not needed but may be useful
4681 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004682 the system will select a free port. Note that port ranges are not
4683 supported in the backend. If you want to force port ranges, you
4684 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004685
4686 <addr2> is the IP address to present to the server when connections are
4687 forwarded in full transparent proxy mode. This is currently only
4688 supported on some patched Linux kernels. When this address is
4689 specified, clients connecting to the server will be presented
4690 with this address, while health checks will still use the address
4691 <addr>.
4692
4693 <port2> is the optional port to present to the server when connections
4694 are forwarded in full transparent proxy mode (see <addr2> above).
4695 The default value of zero means the system will select a free
4696 port.
4697
Willy Tarreaubce70882009-09-07 11:51:47 +02004698 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
4699 This is the name of a comma-separated header list which can
4700 contain multiple IP addresses. By default, the last occurrence is
4701 used. This is designed to work with the X-Forwarded-For header
4702 and to automatically bind to the the client's IP address as seen
4703 by previous proxy, typically Stunnel. In order to use another
4704 occurrence from the last one, please see the <occ> parameter
4705 below. When the header (or occurrence) is not found, no binding
4706 is performed so that the proxy's default IP address is used. Also
4707 keep in mind that the header name is case insensitive, as for any
4708 HTTP header.
4709
4710 <occ> is the occurrence number of a value to be used in a multi-value
4711 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
4712 in order to specificy which occurrence to use for the source IP
4713 address. Positive values indicate a position from the first
4714 occurrence, 1 being the first one. Negative values indicate
4715 positions relative to the last one, -1 being the last one. This
4716 is helpful for situations where an X-Forwarded-For header is set
4717 at the entry point of an infrastructure and must be used several
4718 proxy layers away. When this value is not specified, -1 is
4719 assumed. Passing a zero here disables the feature.
4720
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004721 <name> is an optional interface name to which to bind to for outgoing
4722 traffic. On systems supporting this features (currently, only
4723 Linux), this allows one to bind all traffic to the server to
4724 this interface even if it is not the one the system would select
4725 based on routing tables. This should be used with extreme care.
4726 Note that using this option requires root privileges.
4727
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004728 The "source" keyword is useful in complex environments where a specific
4729 address only is allowed to connect to the servers. It may be needed when a
4730 private address must be used through a public gateway for instance, and it is
4731 known that the system cannot determine the adequate source address by itself.
4732
4733 An extension which is available on certain patched Linux kernels may be used
4734 through the "usesrc" optional keyword. It makes it possible to connect to the
4735 servers with an IP address which does not belong to the system itself. This
4736 is called "full transparent proxy mode". For this to work, the destination
4737 servers have to route their traffic back to this address through the machine
4738 running HAProxy, and IP forwarding must generally be enabled on this machine.
4739
4740 In this "full transparent proxy" mode, it is possible to force a specific IP
4741 address to be presented to the servers. This is not much used in fact. A more
4742 common use is to tell HAProxy to present the client's IP address. For this,
4743 there are two methods :
4744
4745 - present the client's IP and port addresses. This is the most transparent
4746 mode, but it can cause problems when IP connection tracking is enabled on
4747 the machine, because a same connection may be seen twice with different
4748 states. However, this solution presents the huge advantage of not
4749 limiting the system to the 64k outgoing address+port couples, because all
4750 of the client ranges may be used.
4751
4752 - present only the client's IP address and select a spare port. This
4753 solution is still quite elegant but slightly less transparent (downstream
4754 firewalls logs will not match upstream's). It also presents the downside
4755 of limiting the number of concurrent connections to the usual 64k ports.
4756 However, since the upstream and downstream ports are different, local IP
4757 connection tracking on the machine will not be upset by the reuse of the
4758 same session.
4759
4760 Note that depending on the transparent proxy technology used, it may be
4761 required to force the source address. In fact, cttproxy version 2 requires an
4762 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
4763 IP address because it creates NAT entries which much match the exact outgoing
4764 address. Tproxy version 4 and some other kernel patches which work in pure
4765 forwarding mode generally will not have this limitation.
4766
4767 This option sets the default source for all servers in the backend. It may
4768 also be specified in a "defaults" section. Finer source address specification
4769 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004770 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004771
4772 Examples :
4773 backend private
4774 # Connect to the servers using our 192.168.1.200 source address
4775 source 192.168.1.200
4776
4777 backend transparent_ssl1
4778 # Connect to the SSL farm from the client's source address
4779 source 192.168.1.200 usesrc clientip
4780
4781 backend transparent_ssl2
4782 # Connect to the SSL farm from the client's source address and port
4783 # not recommended if IP conntrack is present on the local machine.
4784 source 192.168.1.200 usesrc client
4785
4786 backend transparent_ssl3
4787 # Connect to the SSL farm from the client's source address. It
4788 # is more conntrack-friendly.
4789 source 192.168.1.200 usesrc clientip
4790
4791 backend transparent_smtp
4792 # Connect to the SMTP farm from the client's source address/port
4793 # with Tproxy version 4.
4794 source 0.0.0.0 usesrc clientip
4795
Willy Tarreaubce70882009-09-07 11:51:47 +02004796 backend transparent_http
4797 # Connect to the servers using the client's IP as seen by previous
4798 # proxy.
4799 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
4800
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004801 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004802 the Linux kernel on www.balabit.com, the "bind" keyword.
4803
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004804
Willy Tarreau844e3c52008-01-11 16:28:18 +01004805srvtimeout <timeout> (deprecated)
4806 Set the maximum inactivity time on the server side.
4807 May be used in sections : defaults | frontend | listen | backend
4808 yes | no | yes | yes
4809 Arguments :
4810 <timeout> is the timeout value specified in milliseconds by default, but
4811 can be in any other unit if the number is suffixed by the unit,
4812 as explained at the top of this document.
4813
4814 The inactivity timeout applies when the server is expected to acknowledge or
4815 send data. In HTTP mode, this timeout is particularly important to consider
4816 during the first phase of the server's response, when it has to send the
4817 headers, as it directly represents the server's processing time for the
4818 request. To find out what value to put there, it's often good to start with
4819 what would be considered as unacceptable response times, then check the logs
4820 to observe the response time distribution, and adjust the value accordingly.
4821
4822 The value is specified in milliseconds by default, but can be in any other
4823 unit if the number is suffixed by the unit, as specified at the top of this
4824 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
4825 recommended that the client timeout remains equal to the server timeout in
4826 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004827 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01004828 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01004829 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01004830
4831 This parameter is specific to backends, but can be specified once for all in
4832 "defaults" sections. This is in fact one of the easiest solutions not to
4833 forget about it. An unspecified timeout results in an infinite timeout, which
4834 is not recommended. Such a usage is accepted and works but reports a warning
4835 during startup because it may results in accumulation of expired sessions in
4836 the system if the system's timeouts are not configured either.
4837
4838 This parameter is provided for compatibility but is currently deprecated.
4839 Please use "timeout server" instead.
4840
4841 See also : "timeout server", "timeout client" and "clitimeout".
4842
4843
Cyril Bonté66c327d2010-10-12 00:14:37 +02004844stats admin { if | unless } <cond>
4845 Enable statistics admin level if/unless a condition is matched
4846 May be used in sections : defaults | frontend | listen | backend
4847 no | no | yes | yes
4848
4849 This statement enables the statistics admin level if/unless a condition is
4850 matched.
4851
4852 The admin level allows to enable/disable servers from the web interface. By
4853 default, statistics page is read-only for security reasons.
4854
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01004855 Note : Consider not using this feature in multi-process mode (nbproc > 1)
4856 unless you know what you do : memory is not shared between the
4857 processes, which can result in random behaviours.
4858
Cyril Bonté23b39d92011-02-10 22:54:44 +01004859 Currently, the POST request is limited to the buffer size minus the reserved
4860 buffer space, which means that if the list of servers is too long, the
4861 request won't be processed. It is recommended to alter few servers at a
4862 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02004863
4864 Example :
4865 # statistics admin level only for localhost
4866 backend stats_localhost
4867 stats enable
4868 stats admin if LOCALHOST
4869
4870 Example :
4871 # statistics admin level always enabled because of the authentication
4872 backend stats_auth
4873 stats enable
4874 stats auth admin:AdMiN123
4875 stats admin if TRUE
4876
4877 Example :
4878 # statistics admin level depends on the authenticated user
4879 userlist stats-auth
4880 group admin users admin
4881 user admin insecure-password AdMiN123
4882 group readonly users haproxy
4883 user haproxy insecure-password haproxy
4884
4885 backend stats_auth
4886 stats enable
4887 acl AUTH http_auth(stats-auth)
4888 acl AUTH_ADMIN http_auth_group(stats-auth) admin
4889 stats http-request auth unless AUTH
4890 stats admin if AUTH_ADMIN
4891
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01004892 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
4893 "bind-process", section 3.4 about userlists and section 7 about
4894 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02004895
4896
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004897stats auth <user>:<passwd>
4898 Enable statistics with authentication and grant access to an account
4899 May be used in sections : defaults | frontend | listen | backend
4900 yes | no | yes | yes
4901 Arguments :
4902 <user> is a user name to grant access to
4903
4904 <passwd> is the cleartext password associated to this user
4905
4906 This statement enables statistics with default settings, and restricts access
4907 to declared users only. It may be repeated as many times as necessary to
4908 allow as many users as desired. When a user tries to access the statistics
4909 without a valid account, a "401 Forbidden" response will be returned so that
4910 the browser asks the user to provide a valid user and password. The real
4911 which will be returned to the browser is configurable using "stats realm".
4912
4913 Since the authentication method is HTTP Basic Authentication, the passwords
4914 circulate in cleartext on the network. Thus, it was decided that the
4915 configuration file would also use cleartext passwords to remind the users
4916 that those ones should not be sensible and not shared with any other account.
4917
4918 It is also possible to reduce the scope of the proxies which appear in the
4919 report using "stats scope".
4920
4921 Though this statement alone is enough to enable statistics reporting, it is
4922 recommended to set all other settings in order to avoid relying on default
4923 unobvious parameters.
4924
4925 Example :
4926 # public access (limited to this backend only)
4927 backend public_www
4928 server srv1 192.168.0.1:80
4929 stats enable
4930 stats hide-version
4931 stats scope .
4932 stats uri /admin?stats
4933 stats realm Haproxy\ Statistics
4934 stats auth admin1:AdMiN123
4935 stats auth admin2:AdMiN321
4936
4937 # internal monitoring access (unlimited)
4938 backend private_monitoring
4939 stats enable
4940 stats uri /admin?stats
4941 stats refresh 5s
4942
4943 See also : "stats enable", "stats realm", "stats scope", "stats uri"
4944
4945
4946stats enable
4947 Enable statistics reporting with default settings
4948 May be used in sections : defaults | frontend | listen | backend
4949 yes | no | yes | yes
4950 Arguments : none
4951
4952 This statement enables statistics reporting with default settings defined
4953 at build time. Unless stated otherwise, these settings are used :
4954 - stats uri : /haproxy?stats
4955 - stats realm : "HAProxy Statistics"
4956 - stats auth : no authentication
4957 - stats scope : no restriction
4958
4959 Though this statement alone is enough to enable statistics reporting, it is
4960 recommended to set all other settings in order to avoid relying on default
4961 unobvious parameters.
4962
4963 Example :
4964 # public access (limited to this backend only)
4965 backend public_www
4966 server srv1 192.168.0.1:80
4967 stats enable
4968 stats hide-version
4969 stats scope .
4970 stats uri /admin?stats
4971 stats realm Haproxy\ Statistics
4972 stats auth admin1:AdMiN123
4973 stats auth admin2:AdMiN321
4974
4975 # internal monitoring access (unlimited)
4976 backend private_monitoring
4977 stats enable
4978 stats uri /admin?stats
4979 stats refresh 5s
4980
4981 See also : "stats auth", "stats realm", "stats uri"
4982
4983
Willy Tarreaud63335a2010-02-26 12:56:52 +01004984stats hide-version
4985 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02004986 May be used in sections : defaults | frontend | listen | backend
4987 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01004988 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02004989
Willy Tarreaud63335a2010-02-26 12:56:52 +01004990 By default, the stats page reports some useful status information along with
4991 the statistics. Among them is HAProxy's version. However, it is generally
4992 considered dangerous to report precise version to anyone, as it can help them
4993 target known weaknesses with specific attacks. The "stats hide-version"
4994 statement removes the version from the statistics report. This is recommended
4995 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02004996
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02004997 Though this statement alone is enough to enable statistics reporting, it is
4998 recommended to set all other settings in order to avoid relying on default
4999 unobvious parameters.
5000
Willy Tarreaud63335a2010-02-26 12:56:52 +01005001 Example :
5002 # public access (limited to this backend only)
5003 backend public_www
5004 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005005 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005006 stats hide-version
5007 stats scope .
5008 stats uri /admin?stats
5009 stats realm Haproxy\ Statistics
5010 stats auth admin1:AdMiN123
5011 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005012
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005013 # internal monitoring access (unlimited)
5014 backend private_monitoring
5015 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005016 stats uri /admin?stats
5017 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01005018
Willy Tarreaud63335a2010-02-26 12:56:52 +01005019 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005020
Willy Tarreau983e01e2010-01-11 18:42:06 +01005021
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02005022stats http-request { allow | deny | auth [realm <realm>] }
5023 [ { if | unless } <condition> ]
5024 Access control for statistics
5025
5026 May be used in sections: defaults | frontend | listen | backend
5027 no | no | yes | yes
5028
5029 As "http-request", these set of options allow to fine control access to
5030 statistics. Each option may be followed by if/unless and acl.
5031 First option with matched condition (or option without condition) is final.
5032 For "deny" a 403 error will be returned, for "allow" normal processing is
5033 performed, for "auth" a 401/407 error code is returned so the client
5034 should be asked to enter a username and password.
5035
5036 There is no fixed limit to the number of http-request statements per
5037 instance.
5038
5039 See also : "http-request", section 3.4 about userlists and section 7
5040 about ACL usage.
5041
5042
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005043stats realm <realm>
5044 Enable statistics and set authentication realm
5045 May be used in sections : defaults | frontend | listen | backend
5046 yes | no | yes | yes
5047 Arguments :
5048 <realm> is the name of the HTTP Basic Authentication realm reported to
5049 the browser. The browser uses it to display it in the pop-up
5050 inviting the user to enter a valid username and password.
5051
5052 The realm is read as a single word, so any spaces in it should be escaped
5053 using a backslash ('\').
5054
5055 This statement is useful only in conjunction with "stats auth" since it is
5056 only related to authentication.
5057
5058 Though this statement alone is enough to enable statistics reporting, it is
5059 recommended to set all other settings in order to avoid relying on default
5060 unobvious parameters.
5061
5062 Example :
5063 # public access (limited to this backend only)
5064 backend public_www
5065 server srv1 192.168.0.1:80
5066 stats enable
5067 stats hide-version
5068 stats scope .
5069 stats uri /admin?stats
5070 stats realm Haproxy\ Statistics
5071 stats auth admin1:AdMiN123
5072 stats auth admin2:AdMiN321
5073
5074 # internal monitoring access (unlimited)
5075 backend private_monitoring
5076 stats enable
5077 stats uri /admin?stats
5078 stats refresh 5s
5079
5080 See also : "stats auth", "stats enable", "stats uri"
5081
5082
5083stats refresh <delay>
5084 Enable statistics with automatic refresh
5085 May be used in sections : defaults | frontend | listen | backend
5086 yes | no | yes | yes
5087 Arguments :
5088 <delay> is the suggested refresh delay, specified in seconds, which will
5089 be returned to the browser consulting the report page. While the
5090 browser is free to apply any delay, it will generally respect it
5091 and refresh the page this every seconds. The refresh interval may
5092 be specified in any other non-default time unit, by suffixing the
5093 unit after the value, as explained at the top of this document.
5094
5095 This statement is useful on monitoring displays with a permanent page
5096 reporting the load balancer's activity. When set, the HTML report page will
5097 include a link "refresh"/"stop refresh" so that the user can select whether
5098 he wants automatic refresh of the page or not.
5099
5100 Though this statement alone is enough to enable statistics reporting, it is
5101 recommended to set all other settings in order to avoid relying on default
5102 unobvious parameters.
5103
5104 Example :
5105 # public access (limited to this backend only)
5106 backend public_www
5107 server srv1 192.168.0.1:80
5108 stats enable
5109 stats hide-version
5110 stats scope .
5111 stats uri /admin?stats
5112 stats realm Haproxy\ Statistics
5113 stats auth admin1:AdMiN123
5114 stats auth admin2:AdMiN321
5115
5116 # internal monitoring access (unlimited)
5117 backend private_monitoring
5118 stats enable
5119 stats uri /admin?stats
5120 stats refresh 5s
5121
5122 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5123
5124
5125stats scope { <name> | "." }
5126 Enable statistics and limit access scope
5127 May be used in sections : defaults | frontend | listen | backend
5128 yes | no | yes | yes
5129 Arguments :
5130 <name> is the name of a listen, frontend or backend section to be
5131 reported. The special name "." (a single dot) designates the
5132 section in which the statement appears.
5133
5134 When this statement is specified, only the sections enumerated with this
5135 statement will appear in the report. All other ones will be hidden. This
5136 statement may appear as many times as needed if multiple sections need to be
5137 reported. Please note that the name checking is performed as simple string
5138 comparisons, and that it is never checked that a give section name really
5139 exists.
5140
5141 Though this statement alone is enough to enable statistics reporting, it is
5142 recommended to set all other settings in order to avoid relying on default
5143 unobvious parameters.
5144
5145 Example :
5146 # public access (limited to this backend only)
5147 backend public_www
5148 server srv1 192.168.0.1:80
5149 stats enable
5150 stats hide-version
5151 stats scope .
5152 stats uri /admin?stats
5153 stats realm Haproxy\ Statistics
5154 stats auth admin1:AdMiN123
5155 stats auth admin2:AdMiN321
5156
5157 # internal monitoring access (unlimited)
5158 backend private_monitoring
5159 stats enable
5160 stats uri /admin?stats
5161 stats refresh 5s
5162
5163 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5164
Willy Tarreaud63335a2010-02-26 12:56:52 +01005165
Willy Tarreauc9705a12010-07-27 20:05:50 +02005166stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01005167 Enable reporting of a description on the statistics page.
5168 May be used in sections : defaults | frontend | listen | backend
5169 yes | no | yes | yes
5170
Willy Tarreauc9705a12010-07-27 20:05:50 +02005171 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01005172 description from global section is automatically used instead.
5173
5174 This statement is useful for users that offer shared services to their
5175 customers, where node or description should be different for each customer.
5176
5177 Though this statement alone is enough to enable statistics reporting, it is
5178 recommended to set all other settings in order to avoid relying on default
5179 unobvious parameters.
5180
5181 Example :
5182 # internal monitoring access (unlimited)
5183 backend private_monitoring
5184 stats enable
5185 stats show-desc Master node for Europe, Asia, Africa
5186 stats uri /admin?stats
5187 stats refresh 5s
5188
5189 See also: "show-node", "stats enable", "stats uri" and "description" in
5190 global section.
5191
5192
5193stats show-legends
5194 Enable reporting additional informations on the statistics page :
5195 - cap: capabilities (proxy)
5196 - mode: one of tcp, http or health (proxy)
5197 - id: SNMP ID (proxy, socket, server)
5198 - IP (socket, server)
5199 - cookie (backend, server)
5200
5201 Though this statement alone is enough to enable statistics reporting, it is
5202 recommended to set all other settings in order to avoid relying on default
5203 unobvious parameters.
5204
5205 See also: "stats enable", "stats uri".
5206
5207
5208stats show-node [ <name> ]
5209 Enable reporting of a host name on the statistics page.
5210 May be used in sections : defaults | frontend | listen | backend
5211 yes | no | yes | yes
5212 Arguments:
5213 <name> is an optional name to be reported. If unspecified, the
5214 node name from global section is automatically used instead.
5215
5216 This statement is useful for users that offer shared services to their
5217 customers, where node or description might be different on a stats page
5218 provided for each customer.
5219
5220 Though this statement alone is enough to enable statistics reporting, it is
5221 recommended to set all other settings in order to avoid relying on default
5222 unobvious parameters.
5223
5224 Example:
5225 # internal monitoring access (unlimited)
5226 backend private_monitoring
5227 stats enable
5228 stats show-node Europe-1
5229 stats uri /admin?stats
5230 stats refresh 5s
5231
5232 See also: "show-desc", "stats enable", "stats uri", and "node" in global
5233 section.
5234
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005235
5236stats uri <prefix>
5237 Enable statistics and define the URI prefix to access them
5238 May be used in sections : defaults | frontend | listen | backend
5239 yes | no | yes | yes
5240 Arguments :
5241 <prefix> is the prefix of any URI which will be redirected to stats. This
5242 prefix may contain a question mark ('?') to indicate part of a
5243 query string.
5244
5245 The statistics URI is intercepted on the relayed traffic, so it appears as a
5246 page within the normal application. It is strongly advised to ensure that the
5247 selected URI will never appear in the application, otherwise it will never be
5248 possible to reach it in the application.
5249
5250 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005251 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005252 It is generally a good idea to include a question mark in the URI so that
5253 intermediate proxies refrain from caching the results. Also, since any string
5254 beginning with the prefix will be accepted as a stats request, the question
5255 mark helps ensuring that no valid URI will begin with the same words.
5256
5257 It is sometimes very convenient to use "/" as the URI prefix, and put that
5258 statement in a "listen" instance of its own. That makes it easy to dedicate
5259 an address or a port to statistics only.
5260
5261 Though this statement alone is enough to enable statistics reporting, it is
5262 recommended to set all other settings in order to avoid relying on default
5263 unobvious parameters.
5264
5265 Example :
5266 # public access (limited to this backend only)
5267 backend public_www
5268 server srv1 192.168.0.1:80
5269 stats enable
5270 stats hide-version
5271 stats scope .
5272 stats uri /admin?stats
5273 stats realm Haproxy\ Statistics
5274 stats auth admin1:AdMiN123
5275 stats auth admin2:AdMiN321
5276
5277 # internal monitoring access (unlimited)
5278 backend private_monitoring
5279 stats enable
5280 stats uri /admin?stats
5281 stats refresh 5s
5282
5283 See also : "stats auth", "stats enable", "stats realm"
5284
5285
Willy Tarreaud63335a2010-02-26 12:56:52 +01005286stick match <pattern> [table <table>] [{if | unless} <cond>]
5287 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005288 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01005289 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005290
5291 Arguments :
5292 <pattern> is a pattern extraction rule as described in section 7.8. It
5293 describes what elements of the incoming request or connection
5294 will be analysed in the hope to find a matching entry in a
5295 stickiness table. This rule is mandatory.
5296
5297 <table> is an optional stickiness table name. If unspecified, the same
5298 backend's table is used. A stickiness table is declared using
5299 the "stick-table" statement.
5300
5301 <cond> is an optional matching condition. It makes it possible to match
5302 on a certain criterion only when other conditions are met (or
5303 not met). For instance, it could be used to match on a source IP
5304 address except when a request passes through a known proxy, in
5305 which case we'd match on a header containing that IP address.
5306
5307 Some protocols or applications require complex stickiness rules and cannot
5308 always simply rely on cookies nor hashing. The "stick match" statement
5309 describes a rule to extract the stickiness criterion from an incoming request
5310 or connection. See section 7 for a complete list of possible patterns and
5311 transformation rules.
5312
5313 The table has to be declared using the "stick-table" statement. It must be of
5314 a type compatible with the pattern. By default it is the one which is present
5315 in the same backend. It is possible to share a table with other backends by
5316 referencing it using the "table" keyword. If another table is referenced,
5317 the server's ID inside the backends are used. By default, all server IDs
5318 start at 1 in each backend, so the server ordering is enough. But in case of
5319 doubt, it is highly recommended to force server IDs using their "id" setting.
5320
5321 It is possible to restrict the conditions where a "stick match" statement
5322 will apply, using "if" or "unless" followed by a condition. See section 7 for
5323 ACL based conditions.
5324
5325 There is no limit on the number of "stick match" statements. The first that
5326 applies and matches will cause the request to be directed to the same server
5327 as was used for the request which created the entry. That way, multiple
5328 matches can be used as fallbacks.
5329
5330 The stick rules are checked after the persistence cookies, so they will not
5331 affect stickiness if a cookie has already been used to select a server. That
5332 way, it becomes very easy to insert cookies and match on IP addresses in
5333 order to maintain stickiness between HTTP and HTTPS.
5334
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005335 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5336 unless you know what you do : memory is not shared between the
5337 processes, which can result in random behaviours.
5338
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005339 Example :
5340 # forward SMTP users to the same server they just used for POP in the
5341 # last 30 minutes
5342 backend pop
5343 mode tcp
5344 balance roundrobin
5345 stick store-request src
5346 stick-table type ip size 200k expire 30m
5347 server s1 192.168.1.1:110
5348 server s2 192.168.1.1:110
5349
5350 backend smtp
5351 mode tcp
5352 balance roundrobin
5353 stick match src table pop
5354 server s1 192.168.1.1:25
5355 server s2 192.168.1.1:25
5356
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005357 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5358 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005359
5360
5361stick on <pattern> [table <table>] [{if | unless} <condition>]
5362 Define a request pattern to associate a user to a server
5363 May be used in sections : defaults | frontend | listen | backend
5364 no | no | yes | yes
5365
5366 Note : This form is exactly equivalent to "stick match" followed by
5367 "stick store-request", all with the same arguments. Please refer
5368 to both keywords for details. It is only provided as a convenience
5369 for writing more maintainable configurations.
5370
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005371 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5372 unless you know what you do : memory is not shared between the
5373 processes, which can result in random behaviours.
5374
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005375 Examples :
5376 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01005377 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005378
5379 # ...is strictly equivalent to this one :
5380 stick match src table pop if !localhost
5381 stick store-request src table pop if !localhost
5382
5383
5384 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
5385 # well as HTTP without cookie. Share the same table between both accesses.
5386 backend http
5387 mode http
5388 balance roundrobin
5389 stick on src table https
5390 cookie SRV insert indirect nocache
5391 server s1 192.168.1.1:80 cookie s1
5392 server s2 192.168.1.1:80 cookie s2
5393
5394 backend https
5395 mode tcp
5396 balance roundrobin
5397 stick-table type ip size 200k expire 30m
5398 stick on src
5399 server s1 192.168.1.1:443
5400 server s2 192.168.1.1:443
5401
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005402 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005403
5404
5405stick store-request <pattern> [table <table>] [{if | unless} <condition>]
5406 Define a request pattern used to create an entry in a stickiness table
5407 May be used in sections : defaults | frontend | listen | backend
5408 no | no | yes | yes
5409
5410 Arguments :
5411 <pattern> is a pattern extraction rule as described in section 7.8. It
5412 describes what elements of the incoming request or connection
5413 will be analysed, extracted and stored in the table once a
5414 server is selected.
5415
5416 <table> is an optional stickiness table name. If unspecified, the same
5417 backend's table is used. A stickiness table is declared using
5418 the "stick-table" statement.
5419
5420 <cond> is an optional storage condition. It makes it possible to store
5421 certain criteria only when some conditions are met (or not met).
5422 For instance, it could be used to store the source IP address
5423 except when the request passes through a known proxy, in which
5424 case we'd store a converted form of a header containing that IP
5425 address.
5426
5427 Some protocols or applications require complex stickiness rules and cannot
5428 always simply rely on cookies nor hashing. The "stick store-request" statement
5429 describes a rule to decide what to extract from the request and when to do
5430 it, in order to store it into a stickiness table for further requests to
5431 match it using the "stick match" statement. Obviously the extracted part must
5432 make sense and have a chance to be matched in a further request. Storing a
5433 client's IP address for instance often makes sense. Storing an ID found in a
5434 URL parameter also makes sense. Storing a source port will almost never make
5435 any sense because it will be randomly matched. See section 7 for a complete
5436 list of possible patterns and transformation rules.
5437
5438 The table has to be declared using the "stick-table" statement. It must be of
5439 a type compatible with the pattern. By default it is the one which is present
5440 in the same backend. It is possible to share a table with other backends by
5441 referencing it using the "table" keyword. If another table is referenced,
5442 the server's ID inside the backends are used. By default, all server IDs
5443 start at 1 in each backend, so the server ordering is enough. But in case of
5444 doubt, it is highly recommended to force server IDs using their "id" setting.
5445
5446 It is possible to restrict the conditions where a "stick store-request"
5447 statement will apply, using "if" or "unless" followed by a condition. This
5448 condition will be evaluated while parsing the request, so any criteria can be
5449 used. See section 7 for ACL based conditions.
5450
5451 There is no limit on the number of "stick store-request" statements, but
5452 there is a limit of 8 simultaneous stores per request or response. This
5453 makes it possible to store up to 8 criteria, all extracted from either the
5454 request or the response, regardless of the number of rules. Only the 8 first
5455 ones which match will be kept. Using this, it is possible to feed multiple
5456 tables at once in the hope to increase the chance to recognize a user on
5457 another protocol or access method.
5458
5459 The "store-request" rules are evaluated once the server connection has been
5460 established, so that the table will contain the real server that processed
5461 the request.
5462
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005463 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5464 unless you know what you do : memory is not shared between the
5465 processes, which can result in random behaviours.
5466
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005467 Example :
5468 # forward SMTP users to the same server they just used for POP in the
5469 # last 30 minutes
5470 backend pop
5471 mode tcp
5472 balance roundrobin
5473 stick store-request src
5474 stick-table type ip size 200k expire 30m
5475 server s1 192.168.1.1:110
5476 server s2 192.168.1.1:110
5477
5478 backend smtp
5479 mode tcp
5480 balance roundrobin
5481 stick match src table pop
5482 server s1 192.168.1.1:25
5483 server s2 192.168.1.1:25
5484
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005485 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5486 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005487
5488
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005489stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02005490 size <size> [expire <expire>] [nopurge] [peers <peersect>]
5491 [store <data_type>]*
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005492 Configure the stickiness table for the current backend
5493 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005494 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005495
5496 Arguments :
5497 ip a table declared with "type ip" will only store IPv4 addresses.
5498 This form is very compact (about 50 bytes per entry) and allows
5499 very fast entry lookup and stores with almost no overhead. This
5500 is mainly used to store client source IP addresses.
5501
5502 integer a table declared with "type integer" will store 32bit integers
5503 which can represent a client identifier found in a request for
5504 instance.
5505
5506 string a table declared with "type string" will store substrings of up
5507 to <len> characters. If the string provided by the pattern
5508 extractor is larger than <len>, it will be truncated before
5509 being stored. During matching, at most <len> characters will be
5510 compared between the string in the table and the extracted
5511 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005512 to 32 characters.
5513
5514 binary a table declared with "type binary" will store binary blocks
5515 of <len> bytes. If the block provided by the pattern
5516 extractor is larger than <len>, it will be truncated before
5517 being stored. If the block provided by the pattern extractor
5518 is shorter than <len>, it will be padded by 0. When not
5519 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005520
5521 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005522 "string" type table (See type "string" above). Or the number
5523 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005524 changing this parameter as memory usage will proportionally
5525 increase.
5526
5527 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01005528 value directly impacts memory usage. Count approximately
5529 50 bytes per entry, plus the size of a string if any. The size
5530 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005531
5532 [nopurge] indicates that we refuse to purge older entries when the table
5533 is full. When not specified and the table is full when haproxy
5534 wants to store an entry in it, it will flush a few of the oldest
5535 entries in order to release some space for the new ones. This is
5536 most often the desired behaviour. In some specific cases, it
5537 be desirable to refuse new entries instead of purging the older
5538 ones. That may be the case when the amount of data to store is
5539 far above the hardware limits and we prefer not to offer access
5540 to new clients than to reject the ones already connected. When
5541 using this parameter, be sure to properly set the "expire"
5542 parameter (see below).
5543
Emeric Brunf099e792010-09-27 12:05:28 +02005544 <peersect> is the name of the peers section to use for replication. Entries
5545 which associate keys to server IDs are kept synchronized with
5546 the remote peers declared in this section. All entries are also
5547 automatically learned from the local peer (old process) during a
5548 soft restart.
5549
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005550 NOTE : peers can't be used in multi-process mode.
5551
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005552 <expire> defines the maximum duration of an entry in the table since it
5553 was last created, refreshed or matched. The expiration delay is
5554 defined using the standard time format, similarly as the various
5555 timeouts. The maximum duration is slightly above 24 days. See
5556 section 2.2 for more information. If this delay is not specified,
5557 the session won't automatically expire, but older entries will
5558 be removed once full. Be sure not to use the "nopurge" parameter
5559 if not expiration delay is specified.
5560
Willy Tarreau08d5f982010-06-06 13:34:54 +02005561 <data_type> is used to store additional information in the stick-table. This
5562 may be used by ACLs in order to control various criteria related
5563 to the activity of the client matching the stick-table. For each
5564 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02005565 that the additional data can fit. Several data types may be
5566 stored with an entry. Multiple data types may be specified after
5567 the "store" keyword, as a comma-separated list. Alternatively,
5568 it is possible to repeat the "store" keyword followed by one or
5569 several data types. Except for the "server_id" type which is
5570 automatically detected and enabled, all data types must be
5571 explicitly declared to be stored. If an ACL references a data
5572 type which is not stored, the ACL will simply not match. Some
5573 data types require an argument which must be passed just after
5574 the type between parenthesis. See below for the supported data
5575 types and their arguments.
5576
5577 The data types that can be stored with an entry are the following :
5578 - server_id : this is an integer which holds the numeric ID of the server a
5579 request was assigned to. It is used by the "stick match", "stick store",
5580 and "stick on" rules. It is automatically enabled when referenced.
5581
5582 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
5583 integer which may be used for anything. Most of the time it will be used
5584 to put a special tag on some entries, for instance to note that a
5585 specific behaviour was detected and must be known for future matches.
5586
5587 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
5588 the absolute number of connections received from clients which matched
5589 this entry. It does not mean the connections were accepted, just that
5590 they were received.
5591
5592 - conn_cur : Current Connections. It is a positive 32-bit integer which
5593 stores the concurrent connection counts for the entry. It is incremented
5594 once an incoming connection matches the entry, and decremented once the
5595 connection leaves. That way it is possible to know at any time the exact
5596 number of concurrent connections for an entry.
5597
5598 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5599 integer parameter <period> which indicates in milliseconds the length
5600 of the period over which the average is measured. It reports the average
5601 incoming connection rate over that period, in connections per period. The
5602 result is an integer which can be matched using ACLs.
5603
5604 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
5605 the absolute number of sessions received from clients which matched this
5606 entry. A session is a connection that was accepted by the layer 4 rules.
5607
5608 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5609 integer parameter <period> which indicates in milliseconds the length
5610 of the period over which the average is measured. It reports the average
5611 incoming session rate over that period, in sessions per period. The
5612 result is an integer which can be matched using ACLs.
5613
5614 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
5615 counts the absolute number of HTTP requests received from clients which
5616 matched this entry. It does not matter whether they are valid requests or
5617 not. Note that this is different from sessions when keep-alive is used on
5618 the client side.
5619
5620 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5621 integer parameter <period> which indicates in milliseconds the length
5622 of the period over which the average is measured. It reports the average
5623 HTTP request rate over that period, in requests per period. The result is
5624 an integer which can be matched using ACLs. It does not matter whether
5625 they are valid requests or not. Note that this is different from sessions
5626 when keep-alive is used on the client side.
5627
5628 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
5629 counts the absolute number of HTTP requests errors induced by clients
5630 which matched this entry. Errors are counted on invalid and truncated
5631 requests, as well as on denied or tarpitted requests, and on failed
5632 authentications. If the server responds with 4xx, then the request is
5633 also counted as an error since it's an error triggered by the client
5634 (eg: vulnerability scan).
5635
5636 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5637 integer parameter <period> which indicates in milliseconds the length
5638 of the period over which the average is measured. It reports the average
5639 HTTP request error rate over that period, in requests per period (see
5640 http_err_cnt above for what is accounted as an error). The result is an
5641 integer which can be matched using ACLs.
5642
5643 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
5644 integer which counts the cumulated amount of bytes received from clients
5645 which matched this entry. Headers are included in the count. This may be
5646 used to limit abuse of upload features on photo or video servers.
5647
5648 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5649 integer parameter <period> which indicates in milliseconds the length
5650 of the period over which the average is measured. It reports the average
5651 incoming bytes rate over that period, in bytes per period. It may be used
5652 to detect users which upload too much and too fast. Warning: with large
5653 uploads, it is possible that the amount of uploaded data will be counted
5654 once upon termination, thus causing spikes in the average transfer speed
5655 instead of having a smooth one. This may partially be smoothed with
5656 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
5657 recommended for better fairness.
5658
5659 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
5660 integer which counts the cumulated amount of bytes sent to clients which
5661 matched this entry. Headers are included in the count. This may be used
5662 to limit abuse of bots sucking the whole site.
5663
5664 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
5665 an integer parameter <period> which indicates in milliseconds the length
5666 of the period over which the average is measured. It reports the average
5667 outgoing bytes rate over that period, in bytes per period. It may be used
5668 to detect users which download too much and too fast. Warning: with large
5669 transfers, it is possible that the amount of transferred data will be
5670 counted once upon termination, thus causing spikes in the average
5671 transfer speed instead of having a smooth one. This may partially be
5672 smoothed with "option contstats" though this is not perfect yet. Use of
5673 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02005674
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005675 There is only one stick-table per proxy. At the moment of writing this doc,
5676 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005677 to be required, simply create a dummy backend with a stick-table in it and
5678 reference it.
5679
5680 It is important to understand that stickiness based on learning information
5681 has some limitations, including the fact that all learned associations are
5682 lost upon restart. In general it can be good as a complement but not always
5683 as an exclusive stickiness.
5684
Willy Tarreauc9705a12010-07-27 20:05:50 +02005685 Last, memory requirements may be important when storing many data types.
5686 Indeed, storing all indicators above at once in each entry requires 116 bytes
5687 per entry, or 116 MB for a 1-million entries table. This is definitely not
5688 something that can be ignored.
5689
5690 Example:
5691 # Keep track of counters of up to 1 million IP addresses over 5 minutes
5692 # and store a general purpose counter and the average connection rate
5693 # computed over a sliding window of 30 seconds.
5694 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
5695
5696 See also : "stick match", "stick on", "stick store-request", section 2.2
5697 about time format and section 7 avoud ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005698
5699
Emeric Brun6a1cefa2010-09-24 18:15:17 +02005700stick store-response <pattern> [table <table>] [{if | unless} <condition>]
5701 Define a request pattern used to create an entry in a stickiness table
5702 May be used in sections : defaults | frontend | listen | backend
5703 no | no | yes | yes
5704
5705 Arguments :
5706 <pattern> is a pattern extraction rule as described in section 7.8. It
5707 describes what elements of the response or connection will
5708 be analysed, extracted and stored in the table once a
5709 server is selected.
5710
5711 <table> is an optional stickiness table name. If unspecified, the same
5712 backend's table is used. A stickiness table is declared using
5713 the "stick-table" statement.
5714
5715 <cond> is an optional storage condition. It makes it possible to store
5716 certain criteria only when some conditions are met (or not met).
5717 For instance, it could be used to store the SSL session ID only
5718 when the response is a SSL server hello.
5719
5720 Some protocols or applications require complex stickiness rules and cannot
5721 always simply rely on cookies nor hashing. The "stick store-response"
5722 statement describes a rule to decide what to extract from the response and
5723 when to do it, in order to store it into a stickiness table for further
5724 requests to match it using the "stick match" statement. Obviously the
5725 extracted part must make sense and have a chance to be matched in a further
5726 request. Storing an ID found in a header of a response makes sense.
5727 See section 7 for a complete list of possible patterns and transformation
5728 rules.
5729
5730 The table has to be declared using the "stick-table" statement. It must be of
5731 a type compatible with the pattern. By default it is the one which is present
5732 in the same backend. It is possible to share a table with other backends by
5733 referencing it using the "table" keyword. If another table is referenced,
5734 the server's ID inside the backends are used. By default, all server IDs
5735 start at 1 in each backend, so the server ordering is enough. But in case of
5736 doubt, it is highly recommended to force server IDs using their "id" setting.
5737
5738 It is possible to restrict the conditions where a "stick store-response"
5739 statement will apply, using "if" or "unless" followed by a condition. This
5740 condition will be evaluated while parsing the response, so any criteria can
5741 be used. See section 7 for ACL based conditions.
5742
5743 There is no limit on the number of "stick store-response" statements, but
5744 there is a limit of 8 simultaneous stores per request or response. This
5745 makes it possible to store up to 8 criteria, all extracted from either the
5746 request or the response, regardless of the number of rules. Only the 8 first
5747 ones which match will be kept. Using this, it is possible to feed multiple
5748 tables at once in the hope to increase the chance to recognize a user on
5749 another protocol or access method.
5750
5751 The table will contain the real server that processed the request.
5752
5753 Example :
5754 # Learn SSL session ID from both request and response and create affinity.
5755 backend https
5756 mode tcp
5757 balance roundrobin
5758 # maximum SSL session ID length is 32 bytes.
5759 stick-table type binary len 32 size 30k expire 30m
5760
5761 acl clienthello req_ssl_hello_type 1
5762 acl serverhello rep_ssl_hello_type 2
5763
5764 # use tcp content accepts to detects ssl client and server hello.
5765 tcp-request inspect-delay 5s
5766 tcp-request content accept if clienthello
5767
5768 # no timeout on response inspect delay by default.
5769 tcp-response content accept if serverhello
5770
5771 # SSL session ID (SSLID) may be present on a client or server hello.
5772 # Its length is coded on 1 byte at offset 43 and its value starts
5773 # at offset 44.
5774
5775 # Match and learn on request if client hello.
5776 stick on payload_lv(43,1) if clienthello
5777
5778 # Learn on response if server hello.
5779 stick store-response payload_lv(43,1) if serverhello
5780
5781 server s1 192.168.1.1:443
5782 server s2 192.168.1.1:443
5783
5784 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
5785 extraction.
5786
5787
Willy Tarreaue9656522010-08-17 15:40:09 +02005788tcp-request connection <action> [{if | unless} <condition>]
5789 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02005790 May be used in sections : defaults | frontend | listen | backend
5791 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02005792 Arguments :
5793 <action> defines the action to perform if the condition applies. Valid
5794 actions include : "accept", "reject", "track-sc1", "track-sc2".
5795 See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02005796
Willy Tarreaue9656522010-08-17 15:40:09 +02005797 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005798
5799 Immediately after acceptance of a new incoming connection, it is possible to
5800 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02005801 or dropped or have its counters tracked. Those conditions cannot make use of
5802 any data contents because the connection has not been read from yet, and the
5803 buffers are not yet allocated. This is used to selectively and very quickly
5804 accept or drop connections from various sources with a very low overhead. If
5805 some contents need to be inspected in order to take the decision, the
5806 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005807
Willy Tarreaue9656522010-08-17 15:40:09 +02005808 The "tcp-request connection" rules are evaluated in their exact declaration
5809 order. If no rule matches or if there is no rule, the default action is to
5810 accept the incoming connection. There is no specific limit to the number of
5811 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005812
Willy Tarreaue9656522010-08-17 15:40:09 +02005813 Three types of actions are supported :
5814 - accept :
5815 accepts the connection if the condition is true (when used with "if")
5816 or false (when used with "unless"). The first such rule executed ends
5817 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005818
Willy Tarreaue9656522010-08-17 15:40:09 +02005819 - reject :
5820 rejects the connection if the condition is true (when used with "if")
5821 or false (when used with "unless"). The first such rule executed ends
5822 the rules evaluation. Rejected connections do not even become a
5823 session, which is why they are accounted separately for in the stats,
5824 as "denied connections". They are not considered for the session
5825 rate-limit and are not logged either. The reason is that these rules
5826 should only be used to filter extremely high connection rates such as
5827 the ones encountered during a massive DDoS attack. Under these extreme
5828 conditions, the simple action of logging each event would make the
5829 system collapse and would considerably lower the filtering capacity. If
5830 logging is absolutely desired, then "tcp-request content" rules should
5831 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005832
Willy Tarreaue9656522010-08-17 15:40:09 +02005833 - { track-sc1 | track-sc2 } <key> [table <table>] :
5834 enables tracking of sticky counters from current connection. These
5835 rules do not stop evaluation and do not change default action. Two sets
5836 of counters may be simultaneously tracked by the same connection. The
5837 first "track-sc1" rule executed enables tracking of the counters of the
5838 specified table as the first set. The first "track-sc2" rule executed
5839 enables tracking of the counters of the specified table as the second
5840 set. It is a recommended practice to use the first set of counters for
5841 the per-frontend counters and the second set for the per-backend ones.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005842
Willy Tarreaue9656522010-08-17 15:40:09 +02005843 These actions take one or two arguments :
5844 <key> is mandatory, and defines the criterion the tracking key will
5845 be derived from. At the moment, only "src" is supported. With
5846 it, the key will be the connection's source IPv4 address.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005847
Willy Tarreaue9656522010-08-17 15:40:09 +02005848 <table> is an optional table to be used instead of the default one,
5849 which is the stick-table declared in the current proxy. All
5850 the counters for the matches and updates for the key will
5851 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005852
Willy Tarreaue9656522010-08-17 15:40:09 +02005853 Once a "track-sc*" rule is executed, the key is looked up in the table
5854 and if it is not found, an entry is allocated for it. Then a pointer to
5855 that entry is kept during all the session's life, and this entry's
5856 counters are updated as often as possible, every time the session's
5857 counters are updated, and also systematically when the session ends.
5858 If the entry tracks concurrent connection counters, one connection is
5859 counted for as long as the entry is tracked, and the entry will not
5860 expire during that time. Tracking counters also provides a performance
5861 advantage over just checking the keys, because only one table lookup is
5862 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005863
Willy Tarreaue9656522010-08-17 15:40:09 +02005864 Note that the "if/unless" condition is optional. If no condition is set on
5865 the action, it is simply performed unconditionally. That can be useful for
5866 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005867
Willy Tarreaue9656522010-08-17 15:40:09 +02005868 Example: accept all connections from white-listed hosts, reject too fast
5869 connection without counting them, and track accepted connections.
5870 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005871
Willy Tarreaue9656522010-08-17 15:40:09 +02005872 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005873 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaue9656522010-08-17 15:40:09 +02005874 tcp-request connection track-sc1 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005875
Willy Tarreaue9656522010-08-17 15:40:09 +02005876 Example: accept all connections from white-listed hosts, count all other
5877 connections and reject too fast ones. This results in abusive ones
5878 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005879
Willy Tarreaue9656522010-08-17 15:40:09 +02005880 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
5881 tcp-request connection track-sc1 src
5882 tcp-request connection reject if { sc1_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005883
5884 See section 7 about ACL usage.
5885
Willy Tarreaue9656522010-08-17 15:40:09 +02005886 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005887
5888
Willy Tarreaue9656522010-08-17 15:40:09 +02005889tcp-request content <action> [{if | unless} <condition>]
5890 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02005891 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02005892 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02005893 Arguments :
5894 <action> defines the action to perform if the condition applies. Valid
5895 actions include : "accept", "reject", "track-sc1", "track-sc2".
5896 See "tcp-request connection" above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02005897
Willy Tarreaue9656522010-08-17 15:40:09 +02005898 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02005899
Willy Tarreaue9656522010-08-17 15:40:09 +02005900 A request's contents can be analysed at an early stage of request processing
5901 called "TCP content inspection". During this stage, ACL-based rules are
5902 evaluated every time the request contents are updated, until either an
5903 "accept" or a "reject" rule matches, or the TCP request inspection delay
5904 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02005905
Willy Tarreaue9656522010-08-17 15:40:09 +02005906 The first difference between these rules and "tcp-request connection" rules
5907 is that "tcp-request content" rules can make use of contents to take a
5908 decision. Most often, these decisions will consider a protocol recognition or
5909 validity. The second difference is that content-based rules can be used in
5910 both frontends and backends. In frontends, they will be evaluated upon new
5911 connections. In backends, they will be evaluated once a session is assigned
5912 a backend. This means that a single frontend connection may be evaluated
5913 several times by one or multiple backends when a session gets reassigned
5914 (for instance after a client-side HTTP keep-alive request).
Willy Tarreau62644772008-07-16 18:36:06 +02005915
Willy Tarreaue9656522010-08-17 15:40:09 +02005916 Content-based rules are evaluated in their exact declaration order. If no
5917 rule matches or if there is no rule, the default action is to accept the
5918 contents. There is no specific limit to the number of rules which may be
5919 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02005920
Willy Tarreaue9656522010-08-17 15:40:09 +02005921 Three types of actions are supported :
5922 - accept :
5923 - reject :
5924 - { track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02005925
Willy Tarreaue9656522010-08-17 15:40:09 +02005926 They have the same meaning as their counter-parts in "tcp-request connection"
5927 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02005928
Willy Tarreaue9656522010-08-17 15:40:09 +02005929 Also, it is worth noting that if sticky counters are tracked from a rule
5930 defined in a backend, this tracking will automatically end when the session
5931 releases the backend. That allows per-backend counter tracking even in case
5932 of HTTP keep-alive requests when the backend changes. While there is nothing
5933 mandatory about it, it is recommended to use the track-sc1 pointer to track
5934 per-frontend counters and track-sc2 to track per-backend counters.
Willy Tarreau62644772008-07-16 18:36:06 +02005935
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005936 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02005937 the action, it is simply performed unconditionally. That can be useful for
5938 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02005939
Willy Tarreaue9656522010-08-17 15:40:09 +02005940 It is perfectly possible to match layer 7 contents with "tcp-request content"
5941 rules, but then it is important to ensure that a full request has been
5942 buffered, otherwise no contents will match. In order to achieve this, the
5943 best solution involves detecting the HTTP protocol during the inspection
5944 period.
Willy Tarreau62644772008-07-16 18:36:06 +02005945
5946 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02005947 # Accept HTTP requests containing a Host header saying "example.com"
5948 # and reject everything else.
5949 acl is_host_com hdr(Host) -i example.com
5950 tcp-request inspect-delay 30s
5951 tcp-request content accept if HTTP is_host_com
5952 tcp-request content reject
5953
5954 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02005955 # reject SMTP connection if client speaks first
5956 tcp-request inspect-delay 30s
5957 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005958 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02005959
5960 # Forward HTTPS connection only if client speaks
5961 tcp-request inspect-delay 30s
5962 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02005963 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02005964 tcp-request content reject
5965
5966 Example: track per-frontend and per-backend counters, block abusers at the
5967 frontend when the backend detects abuse.
5968
5969 frontend http
5970 # Use General Purpose Couter 0 in SC1 as a global abuse counter
5971 # protecting all our sites
5972 stick-table type ip size 1m expire 5m store gpc0
5973 tcp-request connection track-sc1 src
5974 tcp-request connection reject if { sc1_get_gpc0 gt 0 }
5975 ...
5976 use_backend http_dynamic if { path_end .php }
5977
5978 backend http_dynamic
5979 # if a source makes too fast requests to this dynamic site (tracked
5980 # by SC2), block it globally in the frontend.
5981 stick-table type ip size 1m expire 5m store http_req_rate(10s)
5982 acl click_too_fast sc2_http_req_rate gt 10
5983 acl mark_as_abuser sc1_inc_gpc0
5984 tcp-request content track-sc2 src
5985 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02005986
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005987 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02005988
Willy Tarreaue9656522010-08-17 15:40:09 +02005989 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02005990
5991
5992tcp-request inspect-delay <timeout>
5993 Set the maximum allowed time to wait for data during content inspection
5994 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02005995 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02005996 Arguments :
5997 <timeout> is the timeout value specified in milliseconds by default, but
5998 can be in any other unit if the number is suffixed by the unit,
5999 as explained at the top of this document.
6000
6001 People using haproxy primarily as a TCP relay are often worried about the
6002 risk of passing any type of protocol to a server without any analysis. In
6003 order to be able to analyze the request contents, we must first withhold
6004 the data then analyze them. This statement simply enables withholding of
6005 data for at most the specified amount of time.
6006
Willy Tarreaufb356202010-08-03 14:02:05 +02006007 TCP content inspection applies very early when a connection reaches a
6008 frontend, then very early when the connection is forwarded to a backend. This
6009 means that a connection may experience a first delay in the frontend and a
6010 second delay in the backend if both have tcp-request rules.
6011
Willy Tarreau62644772008-07-16 18:36:06 +02006012 Note that when performing content inspection, haproxy will evaluate the whole
6013 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006014 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02006015 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01006016 contents are definitive. If no delay is set, haproxy will not wait at all
6017 and will immediately apply a verdict based on the available information.
6018 Obviously this is unlikely to be very useful and might even be racy, so such
6019 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02006020
6021 As soon as a rule matches, the request is released and continues as usual. If
6022 the timeout is reached and no rule matches, the default policy will be to let
6023 it pass through unaffected.
6024
6025 For most protocols, it is enough to set it to a few seconds, as most clients
6026 send the full request immediately upon connection. Add 3 or more seconds to
6027 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01006028 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02006029 before the server (eg: SMTP), or to wait for a client to talk before passing
6030 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02006031 least the inspection delay, otherwise it will expire first. If the client
6032 closes the connection or if the buffer is full, the delay immediately expires
6033 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02006034
Willy Tarreau55165fe2009-05-10 12:02:55 +02006035 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02006036 "timeout client".
6037
6038
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006039tcp-response content <action> [{if | unless} <condition>]
6040 Perform an action on a session response depending on a layer 4-7 condition
6041 May be used in sections : defaults | frontend | listen | backend
6042 no | no | yes | yes
6043 Arguments :
6044 <action> defines the action to perform if the condition applies. Valid
6045 actions include : "accept", "reject".
6046 See "tcp-request connection" above for their signification.
6047
6048 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
6049
6050 Response contents can be analysed at an early stage of response processing
6051 called "TCP content inspection". During this stage, ACL-based rules are
6052 evaluated every time the response contents are updated, until either an
6053 "accept" or a "reject" rule matches, or a TCP response inspection delay is
6054 set and expires with no matching rule.
6055
6056 Most often, these decisions will consider a protocol recognition or validity.
6057
6058 Content-based rules are evaluated in their exact declaration order. If no
6059 rule matches or if there is no rule, the default action is to accept the
6060 contents. There is no specific limit to the number of rules which may be
6061 inserted.
6062
6063 Two types of actions are supported :
6064 - accept :
6065 accepts the response if the condition is true (when used with "if")
6066 or false (when used with "unless"). The first such rule executed ends
6067 the rules evaluation.
6068
6069 - reject :
6070 rejects the response if the condition is true (when used with "if")
6071 or false (when used with "unless"). The first such rule executed ends
6072 the rules evaluation. Rejected session are immediatly closed.
6073
6074 Note that the "if/unless" condition is optional. If no condition is set on
6075 the action, it is simply performed unconditionally. That can be useful for
6076 for changing the default action to a reject.
6077
6078 It is perfectly possible to match layer 7 contents with "tcp-reponse content"
6079 rules, but then it is important to ensure that a full response has been
6080 buffered, otherwise no contents will match. In order to achieve this, the
6081 best solution involves detecting the HTTP protocol during the inspection
6082 period.
6083
6084 See section 7 about ACL usage.
6085
6086 See also : "tcp-request content", "tcp-response inspect-delay"
6087
6088
6089tcp-response inspect-delay <timeout>
6090 Set the maximum allowed time to wait for a response during content inspection
6091 May be used in sections : defaults | frontend | listen | backend
6092 no | no | yes | yes
6093 Arguments :
6094 <timeout> is the timeout value specified in milliseconds by default, but
6095 can be in any other unit if the number is suffixed by the unit,
6096 as explained at the top of this document.
6097
6098 See also : "tcp-response content", "tcp-request inspect-delay".
6099
6100
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006101timeout check <timeout>
6102 Set additional check timeout, but only after a connection has been already
6103 established.
6104
6105 May be used in sections: defaults | frontend | listen | backend
6106 yes | no | yes | yes
6107 Arguments:
6108 <timeout> is the timeout value specified in milliseconds by default, but
6109 can be in any other unit if the number is suffixed by the unit,
6110 as explained at the top of this document.
6111
6112 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
6113 for check and "timeout check" as an additional read timeout. The "min" is
6114 used so that people running with *very* long "timeout connect" (eg. those
6115 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01006116 (Please also note that there is no valid reason to have such long connect
6117 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
6118 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006119
6120 If "timeout check" is not set haproxy uses "inter" for complete check
6121 timeout (connect + read) exactly like all <1.3.15 version.
6122
6123 In most cases check request is much simpler and faster to handle than normal
6124 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01006125 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006126
6127 This parameter is specific to backends, but can be specified once for all in
6128 "defaults" sections. This is in fact one of the easiest solutions not to
6129 forget about it.
6130
Willy Tarreau41a340d2008-01-22 12:25:31 +01006131 See also: "timeout connect", "timeout queue", "timeout server",
6132 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006133
6134
Willy Tarreau0ba27502007-12-24 16:55:16 +01006135timeout client <timeout>
6136timeout clitimeout <timeout> (deprecated)
6137 Set the maximum inactivity time on the client side.
6138 May be used in sections : defaults | frontend | listen | backend
6139 yes | yes | yes | no
6140 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006141 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006142 can be in any other unit if the number is suffixed by the unit,
6143 as explained at the top of this document.
6144
6145 The inactivity timeout applies when the client is expected to acknowledge or
6146 send data. In HTTP mode, this timeout is particularly important to consider
6147 during the first phase, when the client sends the request, and during the
6148 response while it is reading data sent by the server. The value is specified
6149 in milliseconds by default, but can be in any other unit if the number is
6150 suffixed by the unit, as specified at the top of this document. In TCP mode
6151 (and to a lesser extent, in HTTP mode), it is highly recommended that the
6152 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006153 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01006154 losses by specifying timeouts that are slightly above multiples of 3 seconds
6155 (eg: 4 or 5 seconds).
6156
6157 This parameter is specific to frontends, but can be specified once for all in
6158 "defaults" sections. This is in fact one of the easiest solutions not to
6159 forget about it. An unspecified timeout results in an infinite timeout, which
6160 is not recommended. Such a usage is accepted and works but reports a warning
6161 during startup because it may results in accumulation of expired sessions in
6162 the system if the system's timeouts are not configured either.
6163
6164 This parameter replaces the old, deprecated "clitimeout". It is recommended
6165 to use it to write new configurations. The form "timeout clitimeout" is
6166 provided only by backwards compatibility but its use is strongly discouraged.
6167
6168 See also : "clitimeout", "timeout server".
6169
6170
6171timeout connect <timeout>
6172timeout contimeout <timeout> (deprecated)
6173 Set the maximum time to wait for a connection attempt to a server to succeed.
6174 May be used in sections : defaults | frontend | listen | backend
6175 yes | no | yes | yes
6176 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006177 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006178 can be in any other unit if the number is suffixed by the unit,
6179 as explained at the top of this document.
6180
6181 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006182 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01006183 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01006184 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006185 connect timeout also presets both queue and tarpit timeouts to the same value
6186 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +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. An unspecified timeout results in an infinite timeout, which
6191 is not recommended. Such a usage is accepted and works but reports a warning
6192 during startup because it may results in accumulation of failed sessions in
6193 the system if the system's timeouts are not configured either.
6194
6195 This parameter replaces the old, deprecated "contimeout". It is recommended
6196 to use it to write new configurations. The form "timeout contimeout" is
6197 provided only by backwards compatibility but its use is strongly discouraged.
6198
Willy Tarreau41a340d2008-01-22 12:25:31 +01006199 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
6200 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006201
6202
Willy Tarreaub16a5742010-01-10 14:46:16 +01006203timeout http-keep-alive <timeout>
6204 Set the maximum allowed time to wait for a new HTTP request to appear
6205 May be used in sections : defaults | frontend | listen | backend
6206 yes | yes | yes | yes
6207 Arguments :
6208 <timeout> is the timeout value specified in milliseconds by default, but
6209 can be in any other unit if the number is suffixed by the unit,
6210 as explained at the top of this document.
6211
6212 By default, the time to wait for a new request in case of keep-alive is set
6213 by "timeout http-request". However this is not always convenient because some
6214 people want very short keep-alive timeouts in order to release connections
6215 faster, and others prefer to have larger ones but still have short timeouts
6216 once the request has started to present itself.
6217
6218 The "http-keep-alive" timeout covers these needs. It will define how long to
6219 wait for a new HTTP request to start coming after a response was sent. Once
6220 the first byte of request has been seen, the "http-request" timeout is used
6221 to wait for the complete request to come. Note that empty lines prior to a
6222 new request do not refresh the timeout and are not counted as a new request.
6223
6224 There is also another difference between the two timeouts : when a connection
6225 expires during timeout http-keep-alive, no error is returned, the connection
6226 just closes. If the connection expires in "http-request" while waiting for a
6227 connection to complete, a HTTP 408 error is returned.
6228
6229 In general it is optimal to set this value to a few tens to hundreds of
6230 milliseconds, to allow users to fetch all objects of a page at once but
6231 without waiting for further clicks. Also, if set to a very small value (eg:
6232 1 millisecond) it will probably only accept pipelined requests but not the
6233 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02006234 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01006235
6236 If this parameter is not set, the "http-request" timeout applies, and if both
6237 are not set, "timeout client" still applies at the lower level. It should be
6238 set in the frontend to take effect, unless the frontend is in TCP mode, in
6239 which case the HTTP backend's timeout will be used.
6240
6241 See also : "timeout http-request", "timeout client".
6242
6243
Willy Tarreau036fae02008-01-06 13:24:40 +01006244timeout http-request <timeout>
6245 Set the maximum allowed time to wait for a complete HTTP request
6246 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006247 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01006248 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006249 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01006250 can be in any other unit if the number is suffixed by the unit,
6251 as explained at the top of this document.
6252
6253 In order to offer DoS protection, it may be required to lower the maximum
6254 accepted time to receive a complete HTTP request without affecting the client
6255 timeout. This helps protecting against established connections on which
6256 nothing is sent. The client timeout cannot offer a good protection against
6257 this abuse because it is an inactivity timeout, which means that if the
6258 attacker sends one character every now and then, the timeout will not
6259 trigger. With the HTTP request timeout, no matter what speed the client
6260 types, the request will be aborted if it does not complete in time.
6261
6262 Note that this timeout only applies to the header part of the request, and
6263 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01006264 used anymore. It is used again on keep-alive connections to wait for a second
6265 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01006266
6267 Generally it is enough to set it to a few seconds, as most clients send the
6268 full request immediately upon connection. Add 3 or more seconds to cover TCP
6269 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
6270 generally work on local networks as long as there are no packet losses. This
6271 will prevent people from sending bare HTTP requests using telnet.
6272
6273 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006274 chunk of the incoming request. It should be set in the frontend to take
6275 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
6276 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01006277
Willy Tarreaub16a5742010-01-10 14:46:16 +01006278 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01006279
Willy Tarreau844e3c52008-01-11 16:28:18 +01006280
6281timeout queue <timeout>
6282 Set the maximum time to wait in the queue for a connection slot to be free
6283 May be used in sections : defaults | frontend | listen | backend
6284 yes | no | yes | yes
6285 Arguments :
6286 <timeout> is the timeout value specified in milliseconds by default, but
6287 can be in any other unit if the number is suffixed by the unit,
6288 as explained at the top of this document.
6289
6290 When a server's maxconn is reached, connections are left pending in a queue
6291 which may be server-specific or global to the backend. In order not to wait
6292 indefinitely, a timeout is applied to requests pending in the queue. If the
6293 timeout is reached, it is considered that the request will almost never be
6294 served, so it is dropped and a 503 error is returned to the client.
6295
6296 The "timeout queue" statement allows to fix the maximum time for a request to
6297 be left pending in a queue. If unspecified, the same value as the backend's
6298 connection timeout ("timeout connect") is used, for backwards compatibility
6299 with older versions with no "timeout queue" parameter.
6300
6301 See also : "timeout connect", "contimeout".
6302
6303
6304timeout server <timeout>
6305timeout srvtimeout <timeout> (deprecated)
6306 Set the maximum inactivity time on the server side.
6307 May be used in sections : defaults | frontend | listen | backend
6308 yes | no | yes | yes
6309 Arguments :
6310 <timeout> is the timeout value specified in milliseconds by default, but
6311 can be in any other unit if the number is suffixed by the unit,
6312 as explained at the top of this document.
6313
6314 The inactivity timeout applies when the server is expected to acknowledge or
6315 send data. In HTTP mode, this timeout is particularly important to consider
6316 during the first phase of the server's response, when it has to send the
6317 headers, as it directly represents the server's processing time for the
6318 request. To find out what value to put there, it's often good to start with
6319 what would be considered as unacceptable response times, then check the logs
6320 to observe the response time distribution, and adjust the value accordingly.
6321
6322 The value is specified in milliseconds by default, but can be in any other
6323 unit if the number is suffixed by the unit, as specified at the top of this
6324 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
6325 recommended that the client timeout remains equal to the server timeout in
6326 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006327 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01006328 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01006329 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01006330
6331 This parameter is specific to backends, but can be specified once for all in
6332 "defaults" sections. This is in fact one of the easiest solutions not to
6333 forget about it. An unspecified timeout results in an infinite timeout, which
6334 is not recommended. Such a usage is accepted and works but reports a warning
6335 during startup because it may results in accumulation of expired sessions in
6336 the system if the system's timeouts are not configured either.
6337
6338 This parameter replaces the old, deprecated "srvtimeout". It is recommended
6339 to use it to write new configurations. The form "timeout srvtimeout" is
6340 provided only by backwards compatibility but its use is strongly discouraged.
6341
6342 See also : "srvtimeout", "timeout client".
6343
6344
6345timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01006346 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01006347 May be used in sections : defaults | frontend | listen | backend
6348 yes | yes | yes | yes
6349 Arguments :
6350 <timeout> is the tarpit duration specified in milliseconds by default, but
6351 can be in any other unit if the number is suffixed by the unit,
6352 as explained at the top of this document.
6353
6354 When a connection is tarpitted using "reqtarpit", it is maintained open with
6355 no activity for a certain amount of time, then closed. "timeout tarpit"
6356 defines how long it will be maintained open.
6357
6358 The value is specified in milliseconds by default, but can be in any other
6359 unit if the number is suffixed by the unit, as specified at the top of this
6360 document. If unspecified, the same value as the backend's connection timeout
6361 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01006362 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006363
6364 See also : "timeout connect", "contimeout".
6365
6366
6367transparent (deprecated)
6368 Enable client-side transparent proxying
6369 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006370 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006371 Arguments : none
6372
6373 This keyword was introduced in order to provide layer 7 persistence to layer
6374 3 load balancers. The idea is to use the OS's ability to redirect an incoming
6375 connection for a remote address to a local process (here HAProxy), and let
6376 this process know what address was initially requested. When this option is
6377 used, sessions without cookies will be forwarded to the original destination
6378 IP address of the incoming request (which should match that of another
6379 equipment), while requests with cookies will still be forwarded to the
6380 appropriate server.
6381
6382 The "transparent" keyword is deprecated, use "option transparent" instead.
6383
6384 Note that contrary to a common belief, this option does NOT make HAProxy
6385 present the client's IP to the server when establishing the connection.
6386
Willy Tarreau844e3c52008-01-11 16:28:18 +01006387 See also: "option transparent"
6388
6389
6390use_backend <backend> if <condition>
6391use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006392 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006393 May be used in sections : defaults | frontend | listen | backend
6394 no | yes | yes | no
6395 Arguments :
6396 <backend> is the name of a valid backend or "listen" section.
6397
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006398 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006399
6400 When doing content-switching, connections arrive on a frontend and are then
6401 dispatched to various backends depending on a number of conditions. The
6402 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006403 "use_backend" keyword. While it is normally used with HTTP processing, it can
6404 also be used in pure TCP, either without content using stateless ACLs (eg:
6405 source address validation) or combined with a "tcp-request" rule to wait for
6406 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006407
6408 There may be as many "use_backend" rules as desired. All of these rules are
6409 evaluated in their declaration order, and the first one which matches will
6410 assign the backend.
6411
6412 In the first form, the backend will be used if the condition is met. In the
6413 second form, the backend will be used if the condition is not met. If no
6414 condition is valid, the backend defined with "default_backend" will be used.
6415 If no default backend is defined, either the servers in the same section are
6416 used (in case of a "listen" section) or, in case of a frontend, no server is
6417 used and a 503 service unavailable response is returned.
6418
Willy Tarreau51aecc72009-07-12 09:47:04 +02006419 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006420 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02006421 and backend processing will immediately follow, or the backend will wait for
6422 a complete HTTP request to get in. This feature is useful when a frontend
6423 must decode several protocols on a unique port, one of them being HTTP.
6424
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006425 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006426
Willy Tarreau036fae02008-01-06 13:24:40 +01006427
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010064285. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01006429------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006430
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01006431The "server" and "default-server" keywords support a certain number of settings
6432which are all passed as arguments on the server line. The order in which those
6433arguments appear does not count, and they are all optional. Some of those
6434settings are single words (booleans) while others expect one or several values
6435after them. In this case, the values must immediately follow the setting name.
6436Except default-server, all those settings must be specified after the server's
6437address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02006438
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006439 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01006440 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02006441
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006442The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006443
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006444addr <ipv4>
6445 Using the "addr" parameter, it becomes possible to use a different IP address
6446 to send health-checks. On some servers, it may be desirable to dedicate an IP
6447 address to specific component able to perform complex tests which are more
6448 suitable to health-checks than the application. This parameter is ignored if
6449 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006450
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006451 Supported in default-server: No
6452
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006453backup
6454 When "backup" is present on a server line, the server is only used in load
6455 balancing when all other non-backup servers are unavailable. Requests coming
6456 with a persistence cookie referencing the server will always be served
6457 though. By default, only the first operational backup server is used, unless
6458 the "allbackups" option is set in the backend. See also the "allbackups"
6459 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006460
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006461 Supported in default-server: No
6462
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006463check
6464 This option enables health checks on the server. By default, a server is
6465 always considered available. If "check" is set, the server will receive
6466 periodic health checks to ensure that it is really able to serve requests.
6467 The default address and port to send the tests to are those of the server,
6468 and the default source is the same as the one defined in the backend. It is
6469 possible to change the address using the "addr" parameter, the port using the
6470 "port" parameter, the source address using the "source" address, and the
6471 interval and timers using the "inter", "rise" and "fall" parameters. The
6472 request method is define in the backend using the "httpchk", "smtpchk",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01006473 "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please refer to
6474 those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006475
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006476 Supported in default-server: No
6477
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006478cookie <value>
6479 The "cookie" parameter sets the cookie value assigned to the server to
6480 <value>. This value will be checked in incoming requests, and the first
6481 operational server possessing the same value will be selected. In return, in
6482 cookie insertion or rewrite modes, this value will be assigned to the cookie
6483 sent to the client. There is nothing wrong in having several servers sharing
6484 the same cookie value, and it is in fact somewhat common between normal and
6485 backup servers. See also the "cookie" keyword in backend section.
6486
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006487 Supported in default-server: No
6488
Willy Tarreau96839092010-03-29 10:02:24 +02006489disabled
6490 The "disabled" keyword starts the server in the "disabled" state. That means
6491 that it is marked down in maintenance mode, and no connection other than the
6492 ones allowed by persist mode will reach it. It is very well suited to setup
6493 new servers, because normal traffic will never reach them, while it is still
6494 possible to test the service by making use of the force-persist mechanism.
6495
6496 Supported in default-server: No
6497
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006498error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01006499 If health observing is enabled, the "error-limit" parameter specifies the
6500 number of consecutive errors that triggers event selected by the "on-error"
6501 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006502
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006503 Supported in default-server: Yes
6504
6505 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006506
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006507fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006508 The "fall" parameter states that a server will be considered as dead after
6509 <count> consecutive unsuccessful health checks. This value defaults to 3 if
6510 unspecified. See also the "check", "inter" and "rise" parameters.
6511
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006512 Supported in default-server: Yes
6513
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006514id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02006515 Set a persistent ID for the server. This ID must be positive and unique for
6516 the proxy. An unused ID will automatically be assigned if unset. The first
6517 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006518
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006519 Supported in default-server: No
6520
6521inter <delay>
6522fastinter <delay>
6523downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006524 The "inter" parameter sets the interval between two consecutive health checks
6525 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
6526 It is also possible to use "fastinter" and "downinter" to optimize delays
6527 between checks depending on the server state :
6528
6529 Server state | Interval used
6530 ---------------------------------+-----------------------------------------
6531 UP 100% (non-transitional) | "inter"
6532 ---------------------------------+-----------------------------------------
6533 Transitionally UP (going down), |
6534 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
6535 or yet unchecked. |
6536 ---------------------------------+-----------------------------------------
6537 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
6538 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01006539
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006540 Just as with every other time-based parameter, they can be entered in any
6541 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
6542 serves as a timeout for health checks sent to servers if "timeout check" is
6543 not set. In order to reduce "resonance" effects when multiple servers are
6544 hosted on the same hardware, the health-checks of all servers are started
6545 with a small time offset between them. It is also possible to add some random
6546 noise in the health checks interval using the global "spread-checks"
6547 keyword. This makes sense for instance when a lot of backends use the same
6548 servers.
6549
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006550 Supported in default-server: Yes
6551
6552maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006553 The "maxconn" parameter specifies the maximal number of concurrent
6554 connections that will be sent to this server. If the number of incoming
6555 concurrent requests goes higher than this value, they will be queued, waiting
6556 for a connection to be released. This parameter is very important as it can
6557 save fragile servers from going down under extreme loads. If a "minconn"
6558 parameter is specified, the limit becomes dynamic. The default value is "0"
6559 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
6560 the backend's "fullconn" keyword.
6561
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006562 Supported in default-server: Yes
6563
6564maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006565 The "maxqueue" parameter specifies the maximal number of connections which
6566 will wait in the queue for this server. If this limit is reached, next
6567 requests will be redispatched to other servers instead of indefinitely
6568 waiting to be served. This will break persistence but may allow people to
6569 quickly re-log in when the server they try to connect to is dying. The
6570 default value is "0" which means the queue is unlimited. See also the
6571 "maxconn" and "minconn" parameters.
6572
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006573 Supported in default-server: Yes
6574
6575minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006576 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
6577 limit following the backend's load. The server will always accept at least
6578 <minconn> connections, never more than <maxconn>, and the limit will be on
6579 the ramp between both values when the backend has less than <fullconn>
6580 concurrent connections. This makes it possible to limit the load on the
6581 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006582 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006583 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006584
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006585 Supported in default-server: Yes
6586
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006587observe <mode>
6588 This option enables health adjusting based on observing communication with
6589 the server. By default this functionality is disabled and enabling it also
6590 requires to enable health checks. There are two supported modes: "layer4" and
6591 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
6592 significant. In layer7, which is only allowed for http proxies, responses
6593 received from server are verified, like valid/wrong http code, unparsable
6594 headers, a timeout, etc.
6595
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006596 Supported in default-server: No
6597
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006598 See also the "check", "on-error" and "error-limit".
6599
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006600on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006601 Select what should happen when enough consecutive errors are detected.
6602 Currently, four modes are available:
6603 - fastinter: force fastinter
6604 - fail-check: simulate a failed check, also forces fastinter (default)
6605 - sudden-death: simulate a pre-fatal failed health check, one more failed
6606 check will mark a server down, forces fastinter
6607 - mark-down: mark the server immediately down and force fastinter
6608
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006609 Supported in default-server: Yes
6610
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01006611 See also the "check", "observe" and "error-limit".
6612
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006613port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006614 Using the "port" parameter, it becomes possible to use a different port to
6615 send health-checks. On some servers, it may be desirable to dedicate a port
6616 to a specific component able to perform complex tests which are more suitable
6617 to health-checks than the application. It is common to run a simple script in
6618 inetd for instance. This parameter is ignored if the "check" parameter is not
6619 set. See also the "addr" parameter.
6620
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006621 Supported in default-server: Yes
6622
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006623redir <prefix>
6624 The "redir" parameter enables the redirection mode for all GET and HEAD
6625 requests addressing this server. This means that instead of having HAProxy
6626 forward the request to the server, it will send an "HTTP 302" response with
6627 the "Location" header composed of this prefix immediately followed by the
6628 requested URI beginning at the leading '/' of the path component. That means
6629 that no trailing slash should be used after <prefix>. All invalid requests
6630 will be rejected, and all non-GET or HEAD requests will be normally served by
6631 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006632 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006633 requests are still analysed, making this solution completely usable to direct
6634 users to a remote location in case of local disaster. Main use consists in
6635 increasing bandwidth for static servers by having the clients directly
6636 connect to them. Note: never use a relative location here, it would cause a
6637 loop between the client and HAProxy!
6638
6639 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
6640
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006641 Supported in default-server: No
6642
6643rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006644 The "rise" parameter states that a server will be considered as operational
6645 after <count> consecutive successful health checks. This value defaults to 2
6646 if unspecified. See also the "check", "inter" and "fall" parameters.
6647
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006648 Supported in default-server: Yes
6649
6650slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006651 The "slowstart" parameter for a server accepts a value in milliseconds which
6652 indicates after how long a server which has just come back up will run at
6653 full speed. Just as with every other time-based parameter, it can be entered
6654 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
6655 linearly from 0 to 100% during this time. The limitation applies to two
6656 parameters :
6657
6658 - maxconn: the number of connections accepted by the server will grow from 1
6659 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
6660
6661 - weight: when the backend uses a dynamic weighted algorithm, the weight
6662 grows linearly from 1 to 100%. In this case, the weight is updated at every
6663 health-check. For this reason, it is important that the "inter" parameter
6664 is smaller than the "slowstart", in order to maximize the number of steps.
6665
6666 The slowstart never applies when haproxy starts, otherwise it would cause
6667 trouble to running servers. It only applies when a server has been previously
6668 seen as failed.
6669
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006670 Supported in default-server: Yes
6671
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006672source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02006673source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006674source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006675 The "source" parameter sets the source address which will be used when
6676 connecting to the server. It follows the exact same parameters and principle
6677 as the backend "source" keyword, except that it only applies to the server
6678 referencing it. Please consult the "source" keyword for details.
6679
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006680 Additionally, the "source" statement on a server line allows one to specify a
6681 source port range by indicating the lower and higher bounds delimited by a
6682 dash ('-'). Some operating systems might require a valid IP address when a
6683 source port range is specified. It is permitted to have the same IP/range for
6684 several servers. Doing so makes it possible to bypass the maximum of 64k
6685 total concurrent connections. The limit will then reach 64k connections per
6686 server.
6687
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006688 Supported in default-server: No
6689
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006690track [<proxy>/]<server>
6691 This option enables ability to set the current state of the server by
6692 tracking another one. Only a server with checks enabled can be tracked
6693 so it is not possible for example to track a server that tracks another
6694 one. If <proxy> is omitted the current one is used. If disable-on-404 is
6695 used, it has to be enabled on both proxies.
6696
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006697 Supported in default-server: No
6698
6699weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006700 The "weight" parameter is used to adjust the server's weight relative to
6701 other servers. All servers will receive a load proportional to their weight
6702 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02006703 load. The default weight is 1, and the maximal value is 256. A value of 0
6704 means the server will not participate in load-balancing but will still accept
6705 persistent connections. If this parameter is used to distribute the load
6706 according to server's capacity, it is recommended to start with values which
6707 can both grow and shrink, for instance between 10 and 100 to leave enough
6708 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006709
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01006710 Supported in default-server: Yes
6711
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006712
67136. HTTP header manipulation
6714---------------------------
6715
6716In HTTP mode, it is possible to rewrite, add or delete some of the request and
6717response headers based on regular expressions. It is also possible to block a
6718request or a response if a particular header matches a regular expression,
6719which is enough to stop most elementary protocol attacks, and to protect
6720against information leak from the internal network. But there is a limitation
6721to this : since HAProxy's HTTP engine does not support keep-alive, only headers
6722passed during the first request of a TCP session will be seen. All subsequent
6723headers will be considered data only and not analyzed. Furthermore, HAProxy
6724never touches data contents, it stops analysis at the end of headers.
6725
Willy Tarreau816b9792009-09-15 21:25:21 +02006726There is an exception though. If HAProxy encounters an "Informational Response"
6727(status code 1xx), it is able to process all rsp* rules which can allow, deny,
6728rewrite or delete a header, but it will refuse to add a header to any such
6729messages as this is not HTTP-compliant. The reason for still processing headers
6730in such responses is to stop and/or fix any possible information leak which may
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006731happen, for instance because another downstream equipment would unconditionally
Willy Tarreau816b9792009-09-15 21:25:21 +02006732add a header, or if a server name appears there. When such messages are seen,
6733normal processing still occurs on the next non-informational messages.
6734
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006735This section covers common usage of the following keywords, described in detail
6736in section 4.2 :
6737
6738 - reqadd <string>
6739 - reqallow <search>
6740 - reqiallow <search>
6741 - reqdel <search>
6742 - reqidel <search>
6743 - reqdeny <search>
6744 - reqideny <search>
6745 - reqpass <search>
6746 - reqipass <search>
6747 - reqrep <search> <replace>
6748 - reqirep <search> <replace>
6749 - reqtarpit <search>
6750 - reqitarpit <search>
6751 - rspadd <string>
6752 - rspdel <search>
6753 - rspidel <search>
6754 - rspdeny <search>
6755 - rspideny <search>
6756 - rsprep <search> <replace>
6757 - rspirep <search> <replace>
6758
6759With all these keywords, the same conventions are used. The <search> parameter
6760is a POSIX extended regular expression (regex) which supports grouping through
6761parenthesis (without the backslash). Spaces and other delimiters must be
6762prefixed with a backslash ('\') to avoid confusion with a field delimiter.
6763Other characters may be prefixed with a backslash to change their meaning :
6764
6765 \t for a tab
6766 \r for a carriage return (CR)
6767 \n for a new line (LF)
6768 \ to mark a space and differentiate it from a delimiter
6769 \# to mark a sharp and differentiate it from a comment
6770 \\ to use a backslash in a regex
6771 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
6772 \xXX to write the ASCII hex code XX as in the C language
6773
6774The <replace> parameter contains the string to be used to replace the largest
6775portion of text matching the regex. It can make use of the special characters
6776above, and can reference a substring which is delimited by parenthesis in the
6777regex, by writing a backslash ('\') immediately followed by one digit from 0 to
67789 indicating the group position (0 designating the entire line). This practice
6779is very common to users of the "sed" program.
6780
6781The <string> parameter represents the string which will systematically be added
6782after the last header line. It can also use special character sequences above.
6783
6784Notes related to these keywords :
6785---------------------------------
6786 - these keywords are not always convenient to allow/deny based on header
6787 contents. It is strongly recommended to use ACLs with the "block" keyword
6788 instead, resulting in far more flexible and manageable rules.
6789
6790 - lines are always considered as a whole. It is not possible to reference
6791 a header name only or a value only. This is important because of the way
6792 headers are written (notably the number of spaces after the colon).
6793
6794 - the first line is always considered as a header, which makes it possible to
6795 rewrite or filter HTTP requests URIs or response codes, but in turn makes
6796 it harder to distinguish between headers and request line. The regex prefix
6797 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
6798 ^[^ \t:]*: matches any header name followed by a colon.
6799
6800 - for performances reasons, the number of characters added to a request or to
6801 a response is limited at build time to values between 1 and 4 kB. This
6802 should normally be far more than enough for most usages. If it is too short
6803 on occasional usages, it is possible to gain some space by removing some
6804 useless headers before adding new ones.
6805
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006806 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006807 without the 'i' letter except that they ignore case when matching patterns.
6808
6809 - when a request passes through a frontend then a backend, all req* rules
6810 from the frontend will be evaluated, then all req* rules from the backend
6811 will be evaluated. The reverse path is applied to responses.
6812
6813 - req* statements are applied after "block" statements, so that "block" is
6814 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01006815 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006816
6817
Willy Tarreaub937b7e2010-01-12 15:27:54 +010068187. Using ACLs and pattern extraction
6819------------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006820
6821The use of Access Control Lists (ACL) provides a flexible solution to perform
6822content switching and generally to take decisions based on content extracted
6823from the request, the response or any environmental status. The principle is
6824simple :
6825
6826 - define test criteria with sets of values
6827 - perform actions only if a set of tests is valid
6828
6829The actions generally consist in blocking the request, or selecting a backend.
6830
6831In order to define a test, the "acl" keyword is used. The syntax is :
6832
6833 acl <aclname> <criterion> [flags] [operator] <value> ...
6834
6835This creates a new ACL <aclname> or completes an existing one with new tests.
6836Those tests apply to the portion of request/response specified in <criterion>
6837and may be adjusted with optional flags [flags]. Some criteria also support
6838an operator which may be specified before the set of values. The values are
6839of the type supported by the criterion, and are separated by spaces.
6840
6841ACL names must be formed from upper and lower case letters, digits, '-' (dash),
6842'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
6843which means that "my_acl" and "My_Acl" are two different ACLs.
6844
6845There is no enforced limit to the number of ACLs. The unused ones do not affect
6846performance, they just consume a small amount of memory.
6847
6848The following ACL flags are currently supported :
6849
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006850 -i : ignore case during matching of all subsequent patterns.
6851 -f : load patterns from a file.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006852 -- : force end of flags. Useful when a string looks like one of the flags.
6853
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006854The "-f" flag is special as it loads all of the lines it finds in the file
6855specified in argument and loads all of them before continuing. It is even
6856possible to pass multiple "-f" arguments if the patterns are to be loaded from
Willy Tarreau58215a02010-05-13 22:07:43 +02006857multiple files. Empty lines as well as lines beginning with a sharp ('#') will
6858be ignored. All leading spaces and tabs will be stripped. If it is absolutely
6859needed to insert a valid pattern beginning with a sharp, just prefix it with a
6860space so that it is not taken for a comment. Depending on the data type and
6861match method, haproxy may load the lines into a binary tree, allowing very fast
6862lookups. This is true for IPv4 and exact string matching. In this case,
6863duplicates will automatically be removed. Also, note that the "-i" flag applies
6864to subsequent entries and not to entries loaded from files preceeding it. For
6865instance :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02006866
6867 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
6868
6869In this example, each line of "exact-ua.lst" will be exactly matched against
6870the "user-agent" header of the request. Then each line of "generic-ua" will be
6871case-insensitively matched. Then the word "test" will be insensitively matched
6872too.
6873
6874Note that right now it is difficult for the ACL parsers to report errors, so if
6875a file is unreadable or unparsable, the most you'll get is a parse error in the
6876ACL. Thus, file-based ACLs should only be produced by reliable processes.
6877
Willy Tarreau6a06a402007-07-15 20:15:28 +02006878Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01006879
Willy Tarreau6a06a402007-07-15 20:15:28 +02006880 - integers or integer ranges
6881 - strings
6882 - regular expressions
6883 - IP addresses and networks
6884
6885
Willy Tarreauc57f0e22009-05-10 13:12:33 +020068867.1. Matching integers
6887----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006888
6889Matching integers is special in that ranges and operators are permitted. Note
6890that integer matching only applies to positive values. A range is a value
6891expressed with a lower and an upper bound separated with a colon, both of which
6892may be omitted.
6893
6894For instance, "1024:65535" is a valid range to represent a range of
6895unprivileged ports, and "1024:" would also work. "0:1023" is a valid
6896representation of privileged ports, and ":1023" would also work.
6897
Willy Tarreau62644772008-07-16 18:36:06 +02006898As a special case, some ACL functions support decimal numbers which are in fact
6899two integers separated by a dot. This is used with some version checks for
6900instance. All integer properties apply to those decimal numbers, including
6901ranges and operators.
6902
Willy Tarreau6a06a402007-07-15 20:15:28 +02006903For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01006904operators with ranges does not make much sense and is strongly discouraged.
6905Similarly, it does not make much sense to perform order comparisons with a set
6906of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006907
Willy Tarreau0ba27502007-12-24 16:55:16 +01006908Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02006909
6910 eq : true if the tested value equals at least one value
6911 ge : true if the tested value is greater than or equal to at least one value
6912 gt : true if the tested value is greater than at least one value
6913 le : true if the tested value is less than or equal to at least one value
6914 lt : true if the tested value is less than at least one value
6915
Willy Tarreau0ba27502007-12-24 16:55:16 +01006916For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02006917
6918 acl negative-length hdr_val(content-length) lt 0
6919
Willy Tarreau62644772008-07-16 18:36:06 +02006920This one matches SSL versions between 3.0 and 3.1 (inclusive) :
6921
6922 acl sslv3 req_ssl_ver 3:3.1
6923
Willy Tarreau6a06a402007-07-15 20:15:28 +02006924
Willy Tarreauc57f0e22009-05-10 13:12:33 +020069257.2. Matching strings
6926---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006927
6928String matching applies to verbatim strings as they are passed, with the
6929exception of the backslash ("\") which makes it possible to escape some
6930characters such as the space. If the "-i" flag is passed before the first
6931string, then the matching will be performed ignoring the case. In order
6932to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01006933before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02006934
6935
Willy Tarreauc57f0e22009-05-10 13:12:33 +020069367.3. Matching regular expressions (regexes)
6937-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006938
6939Just like with string matching, regex matching applies to verbatim strings as
6940they are passed, with the exception of the backslash ("\") which makes it
6941possible to escape some characters such as the space. If the "-i" flag is
6942passed before the first regex, then the matching will be performed ignoring
6943the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01006944the "--" flag before the first string. Same principle applies of course to
6945match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02006946
6947
Willy Tarreauc57f0e22009-05-10 13:12:33 +020069487.4. Matching IPv4 addresses
6949----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006950
6951IPv4 addresses values can be specified either as plain addresses or with a
6952netmask appended, in which case the IPv4 address matches whenever it is
6953within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006954host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01006955difficult to read and debug configurations. If hostnames are used, you should
6956at least ensure that they are present in /etc/hosts so that the configuration
6957does not depend on any random DNS match at the moment the configuration is
6958parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02006959
6960
Willy Tarreauc57f0e22009-05-10 13:12:33 +020069617.5. Available matching criteria
6962--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02006963
Willy Tarreauc57f0e22009-05-10 13:12:33 +020069647.5.1. Matching at Layer 4 and below
6965------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01006966
6967A first set of criteria applies to information which does not require any
6968analysis of the request or response contents. Those generally include TCP/IP
6969addresses and ports, as well as internal values independant on the stream.
6970
Willy Tarreau6a06a402007-07-15 20:15:28 +02006971always_false
6972 This one never matches. All values and flags are ignored. It may be used as
6973 a temporary replacement for another one when adjusting configurations.
6974
6975always_true
6976 This one always matches. All values and flags are ignored. It may be used as
6977 a temporary replacement for another one when adjusting configurations.
6978
Willy Tarreaud63335a2010-02-26 12:56:52 +01006979avg_queue <integer>
Willy Tarreau6cbd6472010-09-08 19:06:18 +02006980avg_queue(backend) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01006981 Returns the total number of queued connections of the designated backend
6982 divided by the number of active servers. This is very similar to "queue"
6983 except that the size of the farm is considered, in order to give a more
6984 accurate measurement of the time it may take for a new connection to be
6985 processed. The main usage is to return a sorry page to new users when it
6986 becomes certain they will get a degraded service. Note that in the event
6987 there would not be any active server anymore, we would consider twice the
6988 number of queued connections as the measured value. This is a fair estimate,
6989 as we expect one server to get back soon anyway, but we still prefer to send
6990 new traffic to another backend if in better shape. See also the "queue",
6991 "be_conn", and "be_sess_rate" criteria.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01006992
Willy Tarreaua36af912009-10-10 12:02:45 +02006993be_conn <integer>
Willy Tarreau6cbd6472010-09-08 19:06:18 +02006994be_conn(backend) <integer>
Willy Tarreaua36af912009-10-10 12:02:45 +02006995 Applies to the number of currently established connections on the backend,
6996 possibly including the connection being evaluated. If no backend name is
6997 specified, the current one is used. But it is also possible to check another
6998 backend. It can be used to use a specific farm when the nominal one is full.
6999 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007000
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007001be_id <integer>
7002 Applies to the backend's id. Can be used in frontends to check from which
7003 backend it was called.
7004
Willy Tarreaud63335a2010-02-26 12:56:52 +01007005be_sess_rate <integer>
7006be_sess_rate(backend) <integer>
7007 Returns true when the sessions creation rate on the backend matches the
7008 specified values or ranges, in number of new sessions per second. This is
7009 used to switch to an alternate backend when an expensive or fragile one
7010 reaches too high a session rate, or to limit abuse of service (eg. prevent
7011 sucking of an online dictionary).
7012
7013 Example :
7014 # Redirect to an error page if the dictionary is requested too often
7015 backend dynamic
7016 mode http
7017 acl being_scanned be_sess_rate gt 100
7018 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01007019
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007020connslots <integer>
7021connslots(backend) <integer>
7022 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02007023 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007024 usage; see "use_backend" keyword) can be redirected to a different backend.
7025
Willy Tarreau55165fe2009-05-10 12:02:55 +02007026 'connslots' = number of available server connection slots, + number of
7027 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007028
Willy Tarreaua36af912009-10-10 12:02:45 +02007029 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02007030 useful when you have a case of traffic going to one single ip, splitting into
7031 multiple backends (perhaps using acls to do name-based load balancing) and
7032 you want to be able to differentiate between different backends, and their
7033 available "connslots". Also, whereas "nbsrv" only measures servers that are
7034 actually *down*, this acl is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02007035 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007036
Willy Tarreau55165fe2009-05-10 12:02:55 +02007037 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
7038 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
7039 then this acl clearly does not make sense, in which case the value returned
7040 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007041
Willy Tarreaud63335a2010-02-26 12:56:52 +01007042dst <ip_address>
7043 Applies to the local IPv4 address the client connected to. It can be used to
7044 switch to a different backend for some alternative addresses.
Willy Tarreaua36af912009-10-10 12:02:45 +02007045
Willy Tarreaud63335a2010-02-26 12:56:52 +01007046dst_conn <integer>
7047 Applies to the number of currently established connections on the same socket
7048 including the one being evaluated. It can be used to either return a sorry
7049 page before hard-blocking, or to use a specific backend to drain new requests
7050 when the socket is considered saturated. This offers the ability to assign
7051 different limits to different listening ports or addresses. See also the
7052 "fe_conn" and "be_conn" criteria.
7053
7054dst_port <integer>
7055 Applies to the local port the client connected to. It can be used to switch
7056 to a different backend for some alternative ports.
7057
7058fe_conn <integer>
7059fe_conn(frontend) <integer>
7060 Applies to the number of currently established connections on the frontend,
7061 possibly including the connection being evaluated. If no frontend name is
7062 specified, the current one is used. But it is also possible to check another
7063 frontend. It can be used to either return a sorry page before hard-blocking,
7064 or to use a specific backend to drain new requests when the farm is
7065 considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
7066 criteria.
7067
7068fe_id <integer>
Cyril Bonté78caf842010-03-10 22:41:43 +01007069 Applies to the frontend's id. Can be used in backends to check from which
Willy Tarreaud63335a2010-02-26 12:56:52 +01007070 frontend it was called.
Willy Tarreaua36af912009-10-10 12:02:45 +02007071
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007072fe_sess_rate <integer>
7073fe_sess_rate(frontend) <integer>
7074 Returns true when the session creation rate on the current or the named
7075 frontend matches the specified values or ranges, expressed in new sessions
7076 per second. This is used to limit the connection rate to acceptable ranges in
7077 order to prevent abuse of service at the earliest moment. This can be
7078 combined with layer 4 ACLs in order to force the clients to wait a bit for
7079 the rate to go down below the limit.
7080
7081 Example :
7082 # This frontend limits incoming mails to 10/s with a max of 100
7083 # concurrent connections. We accept any connection below 10/s, and
7084 # force excess clients to wait for 100 ms. Since clients are limited to
7085 # 100 max, there cannot be more than 10 incoming mails per second.
7086 frontend mail
7087 bind :25
7088 mode tcp
7089 maxconn 100
7090 acl too_fast fe_sess_rate ge 10
7091 tcp-request inspect-delay 100ms
7092 tcp-request content accept if ! too_fast
7093 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01007094
Willy Tarreaud63335a2010-02-26 12:56:52 +01007095nbsrv <integer>
7096nbsrv(backend) <integer>
7097 Returns true when the number of usable servers of either the current backend
7098 or the named backend matches the values or ranges specified. This is used to
7099 switch to an alternate backend when the number of servers is too low to
7100 to handle some load. It is useful to report a failure when combined with
7101 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007102
Willy Tarreaud63335a2010-02-26 12:56:52 +01007103queue <integer>
Willy Tarreauf5a526f2010-09-01 08:06:18 +02007104queue(backend) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007105 Returns the total number of queued connections of the designated backend,
7106 including all the connections in server queues. If no backend name is
7107 specified, the current one is used, but it is also possible to check another
7108 one. This can be used to take actions when queuing goes above a known level,
7109 generally indicating a surge of traffic or a massive slowdown on the servers.
7110 One possible action could be to reject new users but still accept old ones.
7111 See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
7112
Willy Tarreaue9656522010-08-17 15:40:09 +02007113sc1_bytes_in_rate
7114sc2_bytes_in_rate
7115 Returns the average client-to-server bytes rate from the currently tracked
7116 counters, measured in amount of bytes over the period configured in the
7117 table. See also src_bytes_in_rate.
7118
7119sc1_bytes_out_rate
7120sc2_bytes_out_rate
7121 Returns the average server-to-client bytes rate from the currently tracked
7122 counters, measured in amount of bytes over the period configured in the
7123 table. See also src_bytes_out_rate.
7124
7125sc1_conn_cnt
7126sc2_conn_cnt
7127 Returns the cumulated number of incoming connections from currently tracked
7128 counters. See also src_conn_cnt.
7129
7130sc1_conn_cur
7131sc2_conn_cur
7132 Returns the current amount of concurrent connections tracking the same
7133 tracked counters. This number is automatically incremented when tracking
7134 begins and decremented when tracking stops. See also src_conn_cur.
7135
7136sc1_conn_rate
7137sc2_conn_rate
7138 Returns the average connection rate from the currently tracked counters,
7139 measured in amount of connections over the period configured in the table.
7140 See also src_conn_rate.
7141
7142sc1_get_gpc0
7143sc2_get_gpc0
7144 Returns the value of the first General Purpose Counter associated to the
7145 currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0.
7146
7147sc1_http_err_cnt
7148sc2_http_err_cnt
7149 Returns the cumulated number of HTTP errors from the currently tracked
7150 counters. This includes the both request errors and 4xx error responses.
7151 See also src_http_err_cnt.
7152
7153sc1_http_err_rate
7154sc2_http_err_rate
7155 Returns the average rate of HTTP errors from the currently tracked counters,
7156 measured in amount of errors over the period configured in the table. This
7157 includes the both request errors and 4xx error responses. See also
7158 src_http_err_rate.
7159
7160sc1_http_req_cnt
7161sc2_http_req_cnt
7162 Returns the cumulated number of HTTP requests from the currently tracked
7163 counters. This includes every started request, valid or not. See also
7164 src_http_req_cnt.
7165
7166sc1_http_req_rate
7167sc2_http_req_rate
7168 Returns the average rate of HTTP requests from the currently tracked
7169 counters, measured in amount of requests over the period configured in
7170 the table. This includes every started request, valid or not. See also
7171 src_http_req_rate.
7172
7173sc1_inc_gpc0
7174sc2_inc_gpc0
7175 Increments the first General Purpose Counter associated to the currently
7176 tracked counters, and returns its value. Before the first invocation, the
7177 stored value is zero, so first invocation will increase it to 1 and will
7178 return 1. The test can also be used alone and always returns true. This is
7179 typically used as a second ACL in an expression in order to mark a connection
7180 when a first ACL was verified :
7181
7182 acl abuse sc1_http_req_rate gt 10
7183 acl kill sc1_inc_gpc0
7184 tcp-request connection reject if abuse kill
7185
7186sc1_kbytes_in
7187sc2_kbytes_in
7188 Returns the amount of client-to-server data from the currently tracked
7189 counters, measured in kilobytes over the period configured in the table. The
7190 test is currently performed on 32-bit integers, which limits values to 4
7191 terabytes. See also src_kbytes_in.
7192
7193sc1_kbytes_out
7194sc2_kbytes_out
7195 Returns the amount of server-to-client data from the currently tracked
7196 counters, measured in kilobytes over the period configured in the table. The
7197 test is currently performed on 32-bit integers, which limits values to 4
7198 terabytes. See also src_kbytes_out.
7199
7200sc1_sess_cnt
7201sc2_sess_cnt
7202 Returns the cumulated number of incoming connections that were transformed
7203 into sessions, which means that they were accepted by a "tcp-request
7204 connection" rule, from the currently tracked counters. A backend may count
7205 more sessions than connections because each connection could result in many
7206 backend sessions if some HTTP keep-alive is performend over the connection
7207 with the client. See also src_sess_cnt.
7208
7209sc1_sess_rate
7210sc2_sess_rate
7211 Returns the average session rate from the currently tracked counters,
7212 measured in amount of sessions over the period configured in the table. A
7213 session is a connection that got past the early "tcp-request connection"
7214 rules. A backend may count more sessions than connections because each
7215 connection could result in many backend sessions if some HTTP keep-alive is
7216 performend over the connection with the client. See also src_sess_rate.
7217
Willy Tarreaud63335a2010-02-26 12:56:52 +01007218so_id <integer>
7219 Applies to the socket's id. Useful in frontends with many bind keywords.
7220
7221src <ip_address>
7222 Applies to the client's IPv4 address. It is usually used to limit access to
7223 certain resources such as statistics. Note that it is the TCP-level source
7224 address which is used, and not the address of a client behind a proxy.
7225
Willy Tarreauc9705a12010-07-27 20:05:50 +02007226src_bytes_in_rate <integer>
7227src_bytes_in_rate(table) <integer>
7228 Returns the average bytes rate from the connection's source IPv4 address in
7229 the current proxy's stick-table or in the designated stick-table, measured in
7230 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007231 not found, zero is returned. See also sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007232
7233src_bytes_out_rate <integer>
7234src_bytes_out_rate(table) <integer>
7235 Returns the average bytes rate to the connection's source IPv4 address in the
7236 current proxy's stick-table or in the designated stick-table, measured in
7237 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007238 not found, zero is returned. See also sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007239
7240src_conn_cnt <integer>
7241src_conn_cnt(table) <integer>
7242 Returns the cumulated number of connections initiated from the current
7243 connection's source IPv4 address in the current proxy's stick-table or in
7244 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02007245 See also sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007246
7247src_conn_cur <integer>
7248src_conn_cur(table) <integer>
7249 Returns the current amount of concurrent connections initiated from the
7250 current connection's source IPv4 address in the current proxy's stick-table
7251 or in the designated stick-table. If the address is not found, zero is
Willy Tarreaue9656522010-08-17 15:40:09 +02007252 returned. See also sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007253
7254src_conn_rate <integer>
7255src_conn_rate(table) <integer>
7256 Returns the average connection rate from the connection's source IPv4 address
7257 in the current proxy's stick-table or in the designated stick-table, measured
7258 in amount of connections over the period configured in the table. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02007259 address is not found, zero is returned. See also sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007260
7261src_get_gpc0 <integer>
7262src_get_gpc0(table) <integer>
7263 Returns the value of the first General Purpose Counter associated to the
7264 connection's source IPv4 address in the current proxy's stick-table or in
7265 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02007266 See also sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007267
7268src_http_err_cnt <integer>
7269src_http_err_cnt(table) <integer>
7270 Returns the cumulated number of HTTP errors from the current connection's
7271 source IPv4 address in the current proxy's stick-table or in the designated
7272 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreaue9656522010-08-17 15:40:09 +02007273 If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007274
7275src_http_err_rate <integer>
7276src_http_err_rate(table) <integer>
7277 Returns the average rate of HTTP errors from the current connection's source
7278 IPv4 address in the current proxy's stick-table or in the designated stick-
7279 table, measured in amount of errors over the period configured in the table.
7280 This includes the both request errors and 4xx error responses. If the address
Willy Tarreaue9656522010-08-17 15:40:09 +02007281 is not found, zero is returned. See also sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007282
7283src_http_req_cnt <integer>
7284src_http_req_cnt(table) <integer>
7285 Returns the cumulated number of HTTP requests from the current connection's
7286 source IPv4 address in the current proxy's stick-table or in the designated
7287 stick-table. This includes every started request, valid or not. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02007288 address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007289
7290src_http_req_rate <integer>
7291src_http_req_rate(table) <integer>
7292 Returns the average rate of HTTP requests from the current connection's
7293 source IPv4 address in the current proxy's stick-table or in the designated
7294 stick-table, measured in amount of requests over the period configured in the
7295 table. This includes every started request, valid or not. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02007296 not found, zero is returned. See also sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007297
7298src_inc_gpc0 <integer>
7299src_inc_gpc0(table) <integer>
7300 Increments the first General Purpose Counter associated to the connection's
7301 source IPv4 address in the current proxy's stick-table or in the designated
7302 stick-table, and returns its value. If the address is not found, an entry is
7303 created and 1 is returned. The test can also be used alone and always returns
7304 true. This is typically used as a second ACL in an expression in order to
7305 mark a connection when a first ACL was verified :
7306
7307 acl abuse src_http_req_rate gt 10
7308 acl kill src_inc_gpc0
Willy Tarreaue9656522010-08-17 15:40:09 +02007309 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02007310
7311src_kbytes_in <integer>
7312src_kbytes_in(table) <integer>
7313 Returns the amount of data received from the connection's source IPv4 address
7314 in the current proxy's stick-table or in the designated stick-table, measured
7315 in kilobytes over the period configured in the table. If the address is not
7316 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02007317 which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007318
7319src_kbytes_out <integer>
7320src_kbytes_out(table) <integer>
7321 Returns the amount of data sent to the connection's source IPv4 address in
7322 the current proxy's stick-table or in the designated stick-table, measured
7323 in kilobytes over the period configured in the table. If the address is not
7324 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02007325 which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007326
Willy Tarreaud63335a2010-02-26 12:56:52 +01007327src_port <integer>
7328 Applies to the client's TCP source port. This has a very limited usage.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01007329
Willy Tarreauc9705a12010-07-27 20:05:50 +02007330src_sess_cnt <integer>
7331src_sess_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 the
7334 designated stick-table, that were transformed into sessions, which means that
7335 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreaue9656522010-08-17 15:40:09 +02007336 is returned. See also sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007337
7338src_sess_rate <integer>
7339src_sess_rate(table) <integer>
7340 Returns the average session rate from the connection's source IPv4 address in
7341 the current proxy's stick-table or in the designated stick-table, measured in
7342 amount of sessions over the period configured in the table. A session is a
7343 connection that got past the early "tcp-request" rules. If the address is not
Willy Tarreaue9656522010-08-17 15:40:09 +02007344 found, zero is returned. See also sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007345
7346src_updt_conn_cnt <integer>
7347src_updt_conn_cnt(table) <integer>
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007348 Creates or updates the entry associated to the source IPv4 address in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02007349 current proxy's stick-table or in the designated stick-table. This table
7350 must be configured to store the "conn_cnt" data type, otherwise the match
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007351 will be ignored. The current count is incremented by one, and the expiration
7352 timer refreshed. The updated count is returned, so this match can't return
7353 zero. This is used to reject service abusers based on their source address.
Willy Tarreauc9705a12010-07-27 20:05:50 +02007354 Note: it is recommended to use the more complete "track-counters" instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007355
7356 Example :
7357 # This frontend limits incoming SSH connections to 3 per 10 second for
7358 # each source address, and rejects excess connections until a 10 second
7359 # silence is observed. At most 20 addresses are tracked.
7360 listen ssh
7361 bind :22
7362 mode tcp
7363 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02007364 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreaua975b8f2010-06-05 19:13:27 +02007365 tcp-request content reject if { src_update_count gt 3 }
7366 server local 127.0.0.1:22
7367
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007368srv_id <integer>
7369 Applies to the server's id. Can be used in frontends or backends.
7370
Willy Tarreau0b1cd942010-05-16 22:18:27 +02007371srv_is_up(<server>)
7372srv_is_up(<backend>/<server>)
7373 Returns true when the designated server is UP, and false when it is either
7374 DOWN or in maintenance mode. If <backend> is omitted, then the server is
7375 looked up in the current backend. The function takes no arguments since it
7376 is used as a boolean. It is mainly used to take action based on an external
7377 status reported via a health check (eg: a geographical site's availability).
7378 Another possible use which is more of a hack consists in using dummy servers
7379 as boolean variables that can be enabled or disabled from the CLI, so that
7380 rules depending on those ACLs can be tweaked in realtime.
7381
Willy Tarreau0ba27502007-12-24 16:55:16 +01007382
Willy Tarreaue9656522010-08-17 15:40:09 +020073837.5.2. Matching contents at Layer 4 (also called Layer 6)
7384---------------------------------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02007385
7386A second set of criteria depends on data found in buffers, but which can change
7387during analysis. This requires that some data has been buffered, for instance
Willy Tarreaue9656522010-08-17 15:40:09 +02007388through TCP request content inspection. Please see the "tcp-request content"
7389keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +02007390
7391req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02007392 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02007393 specified range. It is important to understand that this test does not
7394 return false as long as the buffer is changing. This means that a check with
7395 equality to zero will almost always immediately match at the beginning of the
7396 session, while a test for more data will wait for that data to come in and
7397 return false only when haproxy is certain that no more data will come in.
7398 This test was designed to be used with TCP request content inspection.
7399
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007400req_proto_http
7401 Returns true when data in the request buffer look like HTTP and correctly
7402 parses as such. It is the same parser as the common HTTP request parser which
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007403 is used so there should be no surprises. This test can be used for instance
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007404 to direct HTTP traffic to a given port and HTTPS traffic to another one
7405 using TCP request content inspection rules.
7406
Emeric Brunbede3d02009-06-30 17:54:00 +02007407req_rdp_cookie <string>
7408req_rdp_cookie(name) <string>
7409 Returns true when data in the request buffer look like the RDP protocol, and
7410 a cookie is present and equal to <string>. By default, any cookie name is
7411 checked, but a specific cookie name can be specified in parenthesis. The
7412 parser only checks for the first cookie, as illustrated in the RDP protocol
7413 specification. The cookie name is case insensitive. This ACL can be useful
7414 with the "MSTS" cookie, as it can contain the user name of the client
7415 connecting to the server if properly configured on the client. This can be
7416 used to restrict access to certain servers to certain users.
7417
7418req_rdp_cookie_cnt <integer>
7419req_rdp_cookie_cnt(name) <integer>
7420 Returns true when the data in the request buffer look like the RDP protocol
7421 and the number of RDP cookies matches the specified range (typically zero or
7422 one). Optionally a specific cookie name can be checked. This is a simple way
7423 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
7424 cookies.
7425
Willy Tarreau62644772008-07-16 18:36:06 +02007426req_ssl_ver <decimal>
7427 Returns true when data in the request buffer look like SSL, with a protocol
7428 version matching the specified range. Both SSLv2 hello messages and SSLv3
7429 messages are supported. The test tries to be strict enough to avoid being
7430 easily fooled. In particular, it waits for as many bytes as announced in the
7431 message header if this header looks valid (bound to the buffer size). Note
7432 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
7433 with TCP request content inspection.
7434
Emeric Brun392d1d82010-09-24 15:45:16 +02007435req_ssl_hello_type <integer>
7436 Returns true when data in the request buffer looks like a complete SSL (v3
7437 or superior) hello message and handshake type is equal to <integer>.
7438 This test was designed to be used with TCP request content inspection: an
7439 SSL session ID may be fetched.
7440
7441rep_ssl_hello_type <integer>
7442 Returns true when data in the response buffer looks like a complete SSL (v3
7443 or superior) hello message and handshake type is equal to <integer>.
7444 This test was designed to be used with TCP response content inspection: a
7445 SSL session ID may be fetched.
7446
Willy Tarreaub6fb4202008-07-20 11:18:28 +02007447wait_end
7448 Waits for the end of the analysis period to return true. This may be used in
7449 conjunction with content analysis to avoid returning a wrong verdict early.
7450 It may also be used to delay some actions, such as a delayed reject for some
7451 special addresses. Since it either stops the rules evaluation or immediately
7452 returns true, it is recommended to use this acl as the last one in a rule.
7453 Please note that the default ACL "WAIT_END" is always usable without prior
7454 declaration. This test was designed to be used with TCP request content
7455 inspection.
7456
7457 Examples :
7458 # delay every incoming request by 2 seconds
7459 tcp-request inspect-delay 2s
7460 tcp-request content accept if WAIT_END
7461
7462 # don't immediately tell bad guys they are rejected
7463 tcp-request inspect-delay 10s
7464 acl goodguys src 10.0.0.0/24
7465 acl badguys src 10.0.1.0/24
7466 tcp-request content accept if goodguys
7467 tcp-request content reject if badguys WAIT_END
7468 tcp-request content reject
7469
Willy Tarreau62644772008-07-16 18:36:06 +02007470
Willy Tarreauc57f0e22009-05-10 13:12:33 +020074717.5.3. Matching at Layer 7
7472--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007473
Willy Tarreau62644772008-07-16 18:36:06 +02007474A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01007475application layer (layer 7). Those require that a full HTTP request has been
7476read, and are only evaluated then. They may require slightly more CPU resources
7477than the layer 4 ones, but not much since the request and response are indexed.
7478
Willy Tarreaud63335a2010-02-26 12:56:52 +01007479hdr <string>
7480hdr(header) <string>
7481 Note: all the "hdr*" matching criteria either apply to all headers, or to a
7482 particular header whose name is passed between parenthesis and without any
7483 space. The header name is not case-sensitive. The header matching complies
7484 with RFC2616, and treats as separate headers all values delimited by commas.
7485 Use the shdr() variant for response headers sent by the server.
7486
7487 The "hdr" criteria returns true if any of the headers matching the criteria
7488 match any of the strings. This can be used to check exact for values. For
7489 instance, checking that "connection: close" is set :
7490
7491 hdr(Connection) -i close
7492
7493hdr_beg <string>
7494hdr_beg(header) <string>
7495 Returns true when one of the headers begins with one of the strings. See
7496 "hdr" for more information on header matching. Use the shdr_beg() variant for
7497 response headers sent by the server.
7498
7499hdr_cnt <integer>
7500hdr_cnt(header) <integer>
7501 Returns true when the number of occurrence of the specified header matches
7502 the values or ranges specified. It is important to remember that one header
7503 line may count as several headers if it has several values. This is used to
7504 detect presence, absence or abuse of a specific header, as well as to block
7505 request smuggling attacks by rejecting requests which contain more than one
7506 of certain headers. See "hdr" for more information on header matching. Use
7507 the shdr_cnt() variant for response headers sent by the server.
7508
7509hdr_dir <string>
7510hdr_dir(header) <string>
7511 Returns true when one of the headers contains one of the strings either
7512 isolated or delimited by slashes. This is used to perform filename or
7513 directory name matching, and may be used with Referer. See "hdr" for more
7514 information on header matching. Use the shdr_dir() variant for response
7515 headers sent by the server.
7516
7517hdr_dom <string>
7518hdr_dom(header) <string>
7519 Returns true when one of the headers contains one of the strings either
7520 isolated or delimited by dots. This is used to perform domain name matching,
7521 and may be used with the Host header. See "hdr" for more information on
7522 header matching. Use the shdr_dom() variant for response headers sent by the
7523 server.
7524
7525hdr_end <string>
7526hdr_end(header) <string>
7527 Returns true when one of the headers ends with one of the strings. See "hdr"
7528 for more information on header matching. Use the shdr_end() variant for
7529 response headers sent by the server.
7530
7531hdr_ip <ip_address>
7532hdr_ip(header) <ip_address>
7533 Returns true when one of the headers' values contains an IP address matching
7534 <ip_address>. This is mainly used with headers such as X-Forwarded-For or
7535 X-Client-IP. See "hdr" for more information on header matching. Use the
7536 shdr_ip() variant for response headers sent by the server.
7537
7538hdr_reg <regex>
7539hdr_reg(header) <regex>
7540 Returns true when one of the headers matches of the regular expressions. It
7541 can be used at any time, but it is important to remember that regex matching
7542 is slower than other methods. See also other "hdr_" criteria, as well as
7543 "hdr" for more information on header matching. Use the shdr_reg() variant for
7544 response headers sent by the server.
7545
7546hdr_sub <string>
7547hdr_sub(header) <string>
7548 Returns true when one of the headers contains one of the strings. See "hdr"
7549 for more information on header matching. Use the shdr_sub() variant for
7550 response headers sent by the server.
7551
7552hdr_val <integer>
7553hdr_val(header) <integer>
7554 Returns true when one of the headers starts with a number which matches the
7555 values or ranges specified. This may be used to limit content-length to
7556 acceptable values for example. See "hdr" for more information on header
7557 matching. Use the shdr_val() variant for response headers sent by the server.
7558
7559http_auth(userlist)
7560http_auth_group(userlist) <group> [<group>]*
7561 Returns true when authentication data received from the client matches
7562 username & password stored on the userlist. It is also possible to
7563 use http_auth_group to check if the user is assigned to at least one
7564 of specified groups.
7565
7566 Currently only http basic auth is supported.
7567
Willy Tarreau7f18e522010-10-22 20:04:13 +02007568http_req_first
7569 Returns true when the request being processed is the first one of the
7570 connection. This can be used to add or remove headers that may be missing
7571 from some requests when a request is not the first one, or even to perform
7572 some specific ACL checks only on the first request.
7573
Willy Tarreau6a06a402007-07-15 20:15:28 +02007574method <string>
7575 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
7576 already check for most common methods.
7577
Willy Tarreau6a06a402007-07-15 20:15:28 +02007578path <string>
7579 Returns true when the path part of the request, which starts at the first
7580 slash and ends before the question mark, equals one of the strings. It may be
7581 used to match known files, such as /favicon.ico.
7582
7583path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007584 Returns true when the path begins with one of the strings. This can be used
7585 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007586
Willy Tarreau6a06a402007-07-15 20:15:28 +02007587path_dir <string>
7588 Returns true when one of the strings is found isolated or delimited with
7589 slashes in the path. This is used to perform filename or directory name
7590 matching without the risk of wrong match due to colliding prefixes. See also
7591 "url_dir" and "path_sub".
7592
7593path_dom <string>
7594 Returns true when one of the strings is found isolated or delimited with dots
7595 in the path. This may be used to perform domain name matching in proxy
7596 requests. See also "path_sub" and "url_dom".
7597
Willy Tarreaud63335a2010-02-26 12:56:52 +01007598path_end <string>
7599 Returns true when the path ends with one of the strings. This may be used to
7600 control file name extension.
7601
Willy Tarreau6a06a402007-07-15 20:15:28 +02007602path_reg <regex>
7603 Returns true when the path matches one of the regular expressions. It can be
7604 used any time, but it is important to remember that regex matching is slower
7605 than other methods. See also "url_reg" and all "path_" criteria.
7606
Willy Tarreaud63335a2010-02-26 12:56:52 +01007607path_sub <string>
7608 Returns true when the path contains one of the strings. It can be used to
7609 detect particular patterns in paths, such as "../" for example. See also
7610 "path_dir".
7611
7612req_ver <string>
7613 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
7614 ACL already check for versions 1.0 and 1.1.
7615
7616status <integer>
7617 Applies to the HTTP status code in the HTTP response, eg: "302". It can be
7618 used to act on responses depending on status ranges, for instance, remove
7619 any Location header if the response is not a 3xx.
7620
Willy Tarreau6a06a402007-07-15 20:15:28 +02007621url <string>
7622 Applies to the whole URL passed in the request. The only real use is to match
7623 "*", for which there already is a predefined ACL.
7624
7625url_beg <string>
7626 Returns true when the URL begins with one of the strings. This can be used to
7627 check whether a URL begins with a slash or with a protocol scheme.
7628
Willy Tarreau6a06a402007-07-15 20:15:28 +02007629url_dir <string>
7630 Returns true when one of the strings is found isolated or delimited with
7631 slashes in the URL. This is used to perform filename or directory name
7632 matching without the risk of wrong match due to colliding prefixes. See also
7633 "path_dir" and "url_sub".
7634
7635url_dom <string>
7636 Returns true when one of the strings is found isolated or delimited with dots
7637 in the URL. This is used to perform domain name matching without the risk of
7638 wrong match due to colliding prefixes. See also "url_sub".
7639
Willy Tarreaud63335a2010-02-26 12:56:52 +01007640url_end <string>
7641 Returns true when the URL ends with one of the strings. It has very limited
7642 use. "path_end" should be used instead for filename matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007643
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007644url_ip <ip_address>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007645 Applies to the IP address specified in the absolute URI in an HTTP request.
7646 It can be used to prevent access to certain resources such as local network.
Willy Tarreau198a7442008-01-17 12:05:32 +01007647 It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007648
7649url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01007650 Applies to the port specified in the absolute URI in an HTTP request. It can
7651 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01007652 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01007653 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01007654
Willy Tarreaud63335a2010-02-26 12:56:52 +01007655url_reg <regex>
7656 Returns true when the URL matches one of the regular expressions. It can be
7657 used any time, but it is important to remember that regex matching is slower
7658 than other methods. See also "path_reg" and all "url_" criteria.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007659
Willy Tarreaud63335a2010-02-26 12:56:52 +01007660url_sub <string>
7661 Returns true when the URL contains one of the strings. It can be used to
7662 detect particular patterns in query strings for example. See also "path_sub".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01007663
Willy Tarreau198a7442008-01-17 12:05:32 +01007664
Willy Tarreauc57f0e22009-05-10 13:12:33 +020076657.6. Pre-defined ACLs
7666---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007667
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007668Some predefined ACLs are hard-coded so that they do not have to be declared in
7669every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +02007670order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +01007671
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007672ACL name Equivalent to Usage
7673---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007674FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +02007675HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007676HTTP_1.0 req_ver 1.0 match HTTP version 1.0
7677HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +01007678HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
7679HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
7680HTTP_URL_SLASH url_beg / match URL beginning with "/"
7681HTTP_URL_STAR url * match URL equal to "*"
7682LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007683METH_CONNECT method CONNECT match HTTP CONNECT method
7684METH_GET method GET HEAD match HTTP GET or HEAD method
7685METH_HEAD method HEAD match HTTP HEAD method
7686METH_OPTIONS method OPTIONS match HTTP OPTIONS method
7687METH_POST method POST match HTTP POST method
7688METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +02007689RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007690REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +01007691TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007692WAIT_END wait_end wait for end of content analysis
7693---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007694
Willy Tarreauced27012008-01-17 20:35:34 +01007695
Willy Tarreauc57f0e22009-05-10 13:12:33 +020076967.7. Using ACLs to form conditions
7697----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01007698
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007699Some actions are only performed upon a valid condition. A condition is a
7700combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01007701
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007702 - AND (implicit)
7703 - OR (explicit with the "or" keyword or the "||" operator)
7704 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01007705
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007706A condition is formed as a disjunctive form:
Willy Tarreauced27012008-01-17 20:35:34 +01007707
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007708 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01007709
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007710Such conditions are generally used after an "if" or "unless" statement,
7711indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01007712
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007713For instance, to block HTTP requests to the "*" URL with methods other than
7714"OPTIONS", as well as POST requests without content-length, and GET or HEAD
7715requests with a content-length greater than 0, and finally every request which
7716is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01007717
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007718 acl missing_cl hdr_cnt(Content-length) eq 0
7719 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
7720 block if METH_GET HTTP_CONTENT
7721 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01007722
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007723To select a different backend for requests to static contents on the "www" site
7724and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01007725
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007726 acl url_static path_beg /static /images /img /css
7727 acl url_static path_end .gif .png .jpg .css .js
7728 acl host_www hdr_beg(host) -i www
7729 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01007730
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007731 # now use backend "static" for all static-only hosts, and for static urls
7732 # of host "www". Use backend "www" for the rest.
7733 use_backend static if host_static or host_www url_static
7734 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01007735
Willy Tarreau95fa4692010-02-01 13:05:50 +01007736It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
7737expressions that are built on the fly without needing to be declared. They must
7738be enclosed between braces, with a space before and after each brace (because
7739the braces must be seen as independant words). Example :
7740
7741 The following rule :
7742
7743 acl missing_cl hdr_cnt(Content-length) eq 0
7744 block if METH_POST missing_cl
7745
7746 Can also be written that way :
7747
7748 block if METH_POST { hdr_cnt(Content-length) eq 0 }
7749
7750It is generally not recommended to use this construct because it's a lot easier
7751to leave errors in the configuration when written that way. However, for very
7752simple rules matching only one source IP address for instance, it can make more
7753sense to use them than to declare ACLs with random names. Another example of
7754good use is the following :
7755
7756 With named ACLs :
7757
7758 acl site_dead nbsrv(dynamic) lt 2
7759 acl site_dead nbsrv(static) lt 2
7760 monitor fail if site_dead
7761
7762 With anonymous ACLs :
7763
7764 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
7765
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007766See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01007767
Willy Tarreau5764b382007-11-30 17:46:49 +01007768
Willy Tarreaub937b7e2010-01-12 15:27:54 +010077697.8. Pattern extraction
7770-----------------------
7771
7772The stickiness features relies on pattern extraction in the request and
7773response. Sometimes the data needs to be converted first before being stored,
7774for instance converted from ASCII to IP or upper case to lower case.
7775
7776All these operations of data extraction and conversion are defined as
7777"pattern extraction rules". A pattern rule always has the same format. It
7778begins with a single pattern fetch word, potentially followed by a list of
7779arguments within parenthesis then an optional list of transformations. As
7780much as possible, the pattern fetch functions use the same name as their
7781equivalent used in ACLs.
7782
7783The list of currently supported pattern fetch functions is the following :
7784
7785 src This is the source IPv4 address of the client of the session.
7786 It is of type IP and only works with such tables.
7787
7788 dst This is the destination IPv4 address of the session on the
7789 client side, which is the address the client connected to.
7790 It can be useful when running in transparent mode. It is of
7791 typie IP and only works with such tables.
7792
7793 dst_port This is the destination TCP port of the session on the client
7794 side, which is the port the client connected to. This might be
7795 used when running in transparent mode or when assigning dynamic
7796 ports to some clients for a whole application session. It is of
7797 type integer and only works with such tables.
7798
Willy Tarreau4a568972010-05-12 08:08:50 +02007799 hdr(name) This extracts the last occurrence of header <name> in an HTTP
7800 request and converts it to an IP address. This IP address is
7801 then used to match the table. A typical use is with the
7802 x-forwarded-for header.
7803
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007804 payload(offset,length)
7805 This extracts a binary block of <length> bytes, and starting
7806 at bytes <offset> in the buffer of request or response (request
7807 on "stick on" or "stick match" or response in on "stick store
7808 response").
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007809
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007810 payload_lv(offset1,length[,offset2])
7811 This extracts a binary block. In a first step the size of the
7812 block is read from response or request buffer at <offset>
7813 bytes and considered coded on <length> bytes. In a second step
7814 data of the block are read from buffer at <offset2> bytes
7815 (by default <lengthoffset> + <lengthsize>).
7816 If <offset2> is prefixed by '+' or '-', it is relative to
7817 <lengthoffset> + <lengthsize> else it is absolute.
7818 Ex: see SSL session id example in "stick table" chapter.
7819
David Cournapeau16023ee2010-12-23 20:55:41 +09007820 url_param(name)
7821 This extracts the first occurrence of the parameter <name> in
7822 the query string of the request and uses the correponding value
7823 to match. A typical use is to get sticky session through url (e.g.
7824 http://example.com/foo?JESSIONID=some_id with
7825 url_param(JSESSIONID)), for cases where cookies cannot be used.
7826
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007827The currently available list of transformations include :
7828
7829 lower Convert a string pattern to lower case. This can only be placed
7830 after a string pattern fetch function or after a conversion
7831 function returning a string type. The result is of type string.
7832
7833 upper Convert a string pattern to upper case. This can only be placed
7834 after a string pattern fetch function or after a conversion
7835 function returning a string type. The result is of type string.
7836
Willy Tarreaud31d6eb2010-01-26 18:01:41 +01007837 ipmask(mask) Apply a mask to an IPv4 address, and use the result for lookups
7838 and storage. This can be used to make all hosts within a
7839 certain mask to share the same table entries and as such use
7840 the same server. The mask can be passed in dotted form (eg:
7841 255.255.255.0) or in CIDR form (eg: 24).
7842
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007843
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078448. Logging
7845----------
Willy Tarreau844e3c52008-01-11 16:28:18 +01007846
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007847One of HAProxy's strong points certainly lies is its precise logs. It probably
7848provides the finest level of information available for such a product, which is
7849very important for troubleshooting complex environments. Standard information
7850provided in logs include client ports, TCP/HTTP state timers, precise session
7851state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007852to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007853headers.
7854
7855In order to improve administrators reactivity, it offers a great transparency
7856about encountered problems, both internal and external, and it is possible to
7857send logs to different sources at the same time with different level filters :
7858
7859 - global process-level logs (system errors, start/stop, etc..)
7860 - per-instance system and internal errors (lack of resource, bugs, ...)
7861 - per-instance external troubles (servers up/down, max connections)
7862 - per-instance activity (client connections), either at the establishment or
7863 at the termination.
7864
7865The ability to distribute different levels of logs to different log servers
7866allow several production teams to interact and to fix their problems as soon
7867as possible. For example, the system team might monitor system-wide errors,
7868while the application team might be monitoring the up/down for their servers in
7869real time, and the security team might analyze the activity logs with one hour
7870delay.
7871
7872
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078738.1. Log levels
7874---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007875
7876TCP and HTTP connections can be logged with informations such as date, time,
7877source IP address, destination address, connection duration, response times,
7878HTTP request, the HTTP return code, number of bytes transmitted, the conditions
7879in which the session ended, and even exchanged cookies values, to track a
7880particular user's problems for example. All messages are sent to up to two
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007881syslog servers. Check the "log" keyword in section 4.2 for more info about log
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007882facilities.
7883
7884
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078858.2. Log formats
7886----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007887
Emeric Brun3a058f32009-06-30 18:26:00 +02007888HAProxy supports 4 log formats. Several fields are common between these formats
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007889and will be detailed in the next sections. A few of them may slightly vary with
7890the configuration, due to indicators specific to certain options. The supported
7891formats are the following ones :
7892
7893 - the default format, which is very basic and very rarely used. It only
7894 provides very basic information about the incoming connection at the moment
7895 it is accepted : source IP:port, destination IP:port, and frontend-name.
7896 This mode will eventually disappear so it will not be described to great
7897 extents.
7898
7899 - the TCP format, which is more advanced. This format is enabled when "option
7900 tcplog" is set on the frontend. HAProxy will then usually wait for the
7901 connection to terminate before logging. This format provides much richer
7902 information, such as timers, connection counts, queue size, etc... This
7903 format is recommended for pure TCP proxies.
7904
7905 - the HTTP format, which is the most advanced for HTTP proxying. This format
7906 is enabled when "option httplog" is set on the frontend. It provides the
7907 same information as the TCP format with some HTTP-specific fields such as
7908 the request, the status code, and captures of headers and cookies. This
7909 format is recommended for HTTP proxies.
7910
Emeric Brun3a058f32009-06-30 18:26:00 +02007911 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
7912 fields arranged in the same order as the CLF format. In this mode, all
7913 timers, captures, flags, etc... appear one per field after the end of the
7914 common fields, in the same order they appear in the standard HTTP format.
7915
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007916Next sections will go deeper into details for each of these formats. Format
7917specification will be performed on a "field" basis. Unless stated otherwise, a
7918field is a portion of text delimited by any number of spaces. Since syslog
7919servers are susceptible of inserting fields at the beginning of a line, it is
7920always assumed that the first field is the one containing the process name and
7921identifier.
7922
7923Note : Since log lines may be quite long, the log examples in sections below
7924 might be broken into multiple lines. The example log lines will be
7925 prefixed with 3 closing angle brackets ('>>>') and each time a log is
7926 broken into multiple lines, each non-final line will end with a
7927 backslash ('\') and the next line will start indented by two characters.
7928
7929
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079308.2.1. Default log format
7931-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007932
7933This format is used when no specific option is set. The log is emitted as soon
7934as the connection is accepted. One should note that this currently is the only
7935format which logs the request's destination IP and ports.
7936
7937 Example :
7938 listen www
7939 mode http
7940 log global
7941 server srv1 127.0.0.1:8000
7942
7943 >>> Feb 6 12:12:09 localhost \
7944 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
7945 (www/HTTP)
7946
7947 Field Format Extract from the example above
7948 1 process_name '[' pid ']:' haproxy[14385]:
7949 2 'Connect from' Connect from
7950 3 source_ip ':' source_port 10.0.1.2:33312
7951 4 'to' to
7952 5 destination_ip ':' destination_port 10.0.3.31:8012
7953 6 '(' frontend_name '/' mode ')' (www/HTTP)
7954
7955Detailed fields description :
7956 - "source_ip" is the IP address of the client which initiated the connection.
7957 - "source_port" is the TCP port of the client which initiated the connection.
7958 - "destination_ip" is the IP address the client connected to.
7959 - "destination_port" is the TCP port the client connected to.
7960 - "frontend_name" is the name of the frontend (or listener) which received
7961 and processed the connection.
7962 - "mode is the mode the frontend is operating (TCP or HTTP).
7963
Willy Tarreauceb24bc2010-11-09 12:46:41 +01007964In case of a UNIX socket, the source and destination addresses are marked as
7965"unix:" and the ports reflect the internal ID of the socket which accepted the
7966connection (the same ID as reported in the stats).
7967
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007968It is advised not to use this deprecated format for newer installations as it
7969will eventually disappear.
7970
7971
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079728.2.2. TCP log format
7973---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007974
7975The TCP format is used when "option tcplog" is specified in the frontend, and
7976is the recommended format for pure TCP proxies. It provides a lot of precious
7977information for troubleshooting. Since this format includes timers and byte
7978counts, the log is normally emitted at the end of the session. It can be
7979emitted earlier if "option logasap" is specified, which makes sense in most
7980environments with long sessions such as remote terminals. Sessions which match
7981the "monitor" rules are never logged. It is also possible not to emit logs for
7982sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02007983specifying "option dontlognull" in the frontend. Successful connections will
7984not be logged if "option dontlog-normal" is specified in the frontend. A few
7985fields may slightly vary depending on some configuration options, those are
7986marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007987
7988 Example :
7989 frontend fnt
7990 mode tcp
7991 option tcplog
7992 log global
7993 default_backend bck
7994
7995 backend bck
7996 server srv1 127.0.0.1:8000
7997
7998 >>> Feb 6 12:12:56 localhost \
7999 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
8000 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
8001
8002 Field Format Extract from the example above
8003 1 process_name '[' pid ']:' haproxy[14387]:
8004 2 client_ip ':' client_port 10.0.1.2:33313
8005 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
8006 4 frontend_name fnt
8007 5 backend_name '/' server_name bck/srv1
8008 6 Tw '/' Tc '/' Tt* 0/0/5007
8009 7 bytes_read* 212
8010 8 termination_state --
8011 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
8012 10 srv_queue '/' backend_queue 0/0
8013
8014Detailed fields description :
8015 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008016 connection to haproxy. If the connection was accepted on a UNIX socket
8017 instead, the IP address would be replaced with the word "unix". Note that
8018 when the connection is accepted on a socket configured with "accept-proxy"
8019 and the PROXY protocol is correctly used, then the logs will reflect the
8020 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008021
8022 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008023 If the connection was accepted on a UNIX socket instead, the port would be
8024 replaced with the ID of the accepting socket, which is also reported in the
8025 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008026
8027 - "accept_date" is the exact date when the connection was received by haproxy
8028 (which might be very slightly different from the date observed on the
8029 network if there was some queuing in the system's backlog). This is usually
8030 the same date which may appear in any upstream firewall's log.
8031
8032 - "frontend_name" is the name of the frontend (or listener) which received
8033 and processed the connection.
8034
8035 - "backend_name" is the name of the backend (or listener) which was selected
8036 to manage the connection to the server. This will be the same as the
8037 frontend if no switching rule has been applied, which is common for TCP
8038 applications.
8039
8040 - "server_name" is the name of the last server to which the connection was
8041 sent, which might differ from the first one if there were connection errors
8042 and a redispatch occurred. Note that this server belongs to the backend
8043 which processed the request. If the connection was aborted before reaching
8044 a server, "<NOSRV>" is indicated instead of a server name.
8045
8046 - "Tw" is the total time in milliseconds spent waiting in the various queues.
8047 It can be "-1" if the connection was aborted before reaching the queue.
8048 See "Timers" below for more details.
8049
8050 - "Tc" is the total time in milliseconds spent waiting for the connection to
8051 establish to the final server, including retries. It can be "-1" if the
8052 connection was aborted before a connection could be established. See
8053 "Timers" below for more details.
8054
8055 - "Tt" is the total time in milliseconds elapsed between the accept and the
8056 last close. It covers all possible processings. There is one exception, if
8057 "option logasap" was specified, then the time counting stops at the moment
8058 the log is emitted. In this case, a '+' sign is prepended before the value,
8059 indicating that the final one will be larger. See "Timers" below for more
8060 details.
8061
8062 - "bytes_read" is the total number of bytes transmitted from the server to
8063 the client when the log is emitted. If "option logasap" is specified, the
8064 this value will be prefixed with a '+' sign indicating that the final one
8065 may be larger. Please note that this value is a 64-bit counter, so log
8066 analysis tools must be able to handle it without overflowing.
8067
8068 - "termination_state" is the condition the session was in when the session
8069 ended. This indicates the session state, which side caused the end of
8070 session to happen, and for what reason (timeout, error, ...). The normal
8071 flags should be "--", indicating the session was closed by either end with
8072 no data remaining in buffers. See below "Session state at disconnection"
8073 for more details.
8074
8075 - "actconn" is the total number of concurrent connections on the process when
8076 the session was logged. It it useful to detect when some per-process system
8077 limits have been reached. For instance, if actconn is close to 512 when
8078 multiple connection errors occur, chances are high that the system limits
8079 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008080 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008081
8082 - "feconn" is the total number of concurrent connections on the frontend when
8083 the session was logged. It is useful to estimate the amount of resource
8084 required to sustain high loads, and to detect when the frontend's "maxconn"
8085 has been reached. Most often when this value increases by huge jumps, it is
8086 because there is congestion on the backend servers, but sometimes it can be
8087 caused by a denial of service attack.
8088
8089 - "beconn" is the total number of concurrent connections handled by the
8090 backend when the session was logged. It includes the total number of
8091 concurrent connections active on servers as well as the number of
8092 connections pending in queues. It is useful to estimate the amount of
8093 additional servers needed to support high loads for a given application.
8094 Most often when this value increases by huge jumps, it is because there is
8095 congestion on the backend servers, but sometimes it can be caused by a
8096 denial of service attack.
8097
8098 - "srv_conn" is the total number of concurrent connections still active on
8099 the server when the session was logged. It can never exceed the server's
8100 configured "maxconn" parameter. If this value is very often close or equal
8101 to the server's "maxconn", it means that traffic regulation is involved a
8102 lot, meaning that either the server's maxconn value is too low, or that
8103 there aren't enough servers to process the load with an optimal response
8104 time. When only one of the server's "srv_conn" is high, it usually means
8105 that this server has some trouble causing the connections to take longer to
8106 be processed than on other servers.
8107
8108 - "retries" is the number of connection retries experienced by this session
8109 when trying to connect to the server. It must normally be zero, unless a
8110 server is being stopped at the same moment the connection was attempted.
8111 Frequent retries generally indicate either a network problem between
8112 haproxy and the server, or a misconfigured system backlog on the server
8113 preventing new connections from being queued. This field may optionally be
8114 prefixed with a '+' sign, indicating that the session has experienced a
8115 redispatch after the maximal retry count has been reached on the initial
8116 server. In this case, the server name appearing in the log is the one the
8117 connection was redispatched to, and not the first one, though both may
8118 sometimes be the same in case of hashing for instance. So as a general rule
8119 of thumb, when a '+' is present in front of the retry count, this count
8120 should not be attributed to the logged server.
8121
8122 - "srv_queue" is the total number of requests which were processed before
8123 this one in the server queue. It is zero when the request has not gone
8124 through the server queue. It makes it possible to estimate the approximate
8125 server's response time by dividing the time spent in queue by the number of
8126 requests in the queue. It is worth noting that if a session experiences a
8127 redispatch and passes through two server queues, their positions will be
8128 cumulated. A request should not pass through both the server queue and the
8129 backend queue unless a redispatch occurs.
8130
8131 - "backend_queue" is the total number of requests which were processed before
8132 this one in the backend's global queue. It is zero when the request has not
8133 gone through the global queue. It makes it possible to estimate the average
8134 queue length, which easily translates into a number of missing servers when
8135 divided by a server's "maxconn" parameter. It is worth noting that if a
8136 session experiences a redispatch, it may pass twice in the backend's queue,
8137 and then both positions will be cumulated. A request should not pass
8138 through both the server queue and the backend queue unless a redispatch
8139 occurs.
8140
8141
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081428.2.3. HTTP log format
8143----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008144
8145The HTTP format is the most complete and the best suited for HTTP proxies. It
8146is enabled by when "option httplog" is specified in the frontend. It provides
8147the same level of information as the TCP format with additional features which
8148are specific to the HTTP protocol. Just like the TCP format, the log is usually
8149emitted at the end of the session, unless "option logasap" is specified, which
8150generally only makes sense for download sites. A session which matches the
8151"monitor" rules will never logged. It is also possible not to log sessions for
8152which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008153frontend. Successful connections will not be logged if "option dontlog-normal"
8154is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008155
8156Most fields are shared with the TCP log, some being different. A few fields may
8157slightly vary depending on some configuration options. Those ones are marked
8158with a star ('*') after the field name below.
8159
8160 Example :
8161 frontend http-in
8162 mode http
8163 option httplog
8164 log global
8165 default_backend bck
8166
8167 backend static
8168 server srv1 127.0.0.1:8000
8169
8170 >>> Feb 6 12:14:14 localhost \
8171 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
8172 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 +01008173 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008174
8175 Field Format Extract from the example above
8176 1 process_name '[' pid ']:' haproxy[14389]:
8177 2 client_ip ':' client_port 10.0.1.2:33317
8178 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
8179 4 frontend_name http-in
8180 5 backend_name '/' server_name static/srv1
8181 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
8182 7 status_code 200
8183 8 bytes_read* 2750
8184 9 captured_request_cookie -
8185 10 captured_response_cookie -
8186 11 termination_state ----
8187 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
8188 13 srv_queue '/' backend_queue 0/0
8189 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
8190 15 '{' captured_response_headers* '}' {}
8191 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +01008192
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008193
8194Detailed fields description :
8195 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008196 connection to haproxy. If the connection was accepted on a UNIX socket
8197 instead, the IP address would be replaced with the word "unix". Note that
8198 when the connection is accepted on a socket configured with "accept-proxy"
8199 and the PROXY protocol is correctly used, then the logs will reflect the
8200 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008201
8202 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01008203 If the connection was accepted on a UNIX socket instead, the port would be
8204 replaced with the ID of the accepting socket, which is also reported in the
8205 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008206
8207 - "accept_date" is the exact date when the TCP connection was received by
8208 haproxy (which might be very slightly different from the date observed on
8209 the network if there was some queuing in the system's backlog). This is
8210 usually the same date which may appear in any upstream firewall's log. This
8211 does not depend on the fact that the client has sent the request or not.
8212
8213 - "frontend_name" is the name of the frontend (or listener) which received
8214 and processed the connection.
8215
8216 - "backend_name" is the name of the backend (or listener) which was selected
8217 to manage the connection to the server. This will be the same as the
8218 frontend if no switching rule has been applied.
8219
8220 - "server_name" is the name of the last server to which the connection was
8221 sent, which might differ from the first one if there were connection errors
8222 and a redispatch occurred. Note that this server belongs to the backend
8223 which processed the request. If the request was aborted before reaching a
8224 server, "<NOSRV>" is indicated instead of a server name. If the request was
8225 intercepted by the stats subsystem, "<STATS>" is indicated instead.
8226
8227 - "Tq" is the total time in milliseconds spent waiting for the client to send
8228 a full HTTP request, not counting data. It can be "-1" if the connection
8229 was aborted before a complete request could be received. It should always
8230 be very small because a request generally fits in one single packet. Large
8231 times here generally indicate network trouble between the client and
8232 haproxy. See "Timers" below for more details.
8233
8234 - "Tw" is the total time in milliseconds spent waiting in the various queues.
8235 It can be "-1" if the connection was aborted before reaching the queue.
8236 See "Timers" below for more details.
8237
8238 - "Tc" is the total time in milliseconds spent waiting for the connection to
8239 establish to the final server, including retries. It can be "-1" if the
8240 request was aborted before a connection could be established. See "Timers"
8241 below for more details.
8242
8243 - "Tr" is the total time in milliseconds spent waiting for the server to send
8244 a full HTTP response, not counting data. It can be "-1" if the request was
8245 aborted before a complete response could be received. It generally matches
8246 the server's processing time for the request, though it may be altered by
8247 the amount of data sent by the client to the server. Large times here on
8248 "GET" requests generally indicate an overloaded server. See "Timers" below
8249 for more details.
8250
8251 - "Tt" is the total time in milliseconds elapsed between the accept and the
8252 last close. It covers all possible processings. There is one exception, if
8253 "option logasap" was specified, then the time counting stops at the moment
8254 the log is emitted. In this case, a '+' sign is prepended before the value,
8255 indicating that the final one will be larger. See "Timers" below for more
8256 details.
8257
8258 - "status_code" is the HTTP status code returned to the client. This status
8259 is generally set by the server, but it might also be set by haproxy when
8260 the server cannot be reached or when its response is blocked by haproxy.
8261
8262 - "bytes_read" is the total number of bytes transmitted to the client when
8263 the log is emitted. This does include HTTP headers. If "option logasap" is
8264 specified, the this value will be prefixed with a '+' sign indicating that
8265 the final one may be larger. Please note that this value is a 64-bit
8266 counter, so log analysis tools must be able to handle it without
8267 overflowing.
8268
8269 - "captured_request_cookie" is an optional "name=value" entry indicating that
8270 the client had this cookie in the request. The cookie name and its maximum
8271 length are defined by the "capture cookie" statement in the frontend
8272 configuration. The field is a single dash ('-') when the option is not
8273 set. Only one cookie may be captured, it is generally used to track session
8274 ID exchanges between a client and a server to detect session crossing
8275 between clients due to application bugs. For more details, please consult
8276 the section "Capturing HTTP headers and cookies" below.
8277
8278 - "captured_response_cookie" is an optional "name=value" entry indicating
8279 that the server has returned a cookie with its response. The cookie name
8280 and its maximum length are defined by the "capture cookie" statement in the
8281 frontend configuration. The field is a single dash ('-') when the option is
8282 not set. Only one cookie may be captured, it is generally used to track
8283 session ID exchanges between a client and a server to detect session
8284 crossing between clients due to application bugs. For more details, please
8285 consult the section "Capturing HTTP headers and cookies" below.
8286
8287 - "termination_state" is the condition the session was in when the session
8288 ended. This indicates the session state, which side caused the end of
8289 session to happen, for what reason (timeout, error, ...), just like in TCP
8290 logs, and information about persistence operations on cookies in the last
8291 two characters. The normal flags should begin with "--", indicating the
8292 session was closed by either end with no data remaining in buffers. See
8293 below "Session state at disconnection" for more details.
8294
8295 - "actconn" is the total number of concurrent connections on the process when
8296 the session was logged. It it useful to detect when some per-process system
8297 limits have been reached. For instance, if actconn is close to 512 or 1024
8298 when multiple connection errors occur, chances are high that the system
8299 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008300 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008301 system.
8302
8303 - "feconn" is the total number of concurrent connections on the frontend when
8304 the session was logged. It is useful to estimate the amount of resource
8305 required to sustain high loads, and to detect when the frontend's "maxconn"
8306 has been reached. Most often when this value increases by huge jumps, it is
8307 because there is congestion on the backend servers, but sometimes it can be
8308 caused by a denial of service attack.
8309
8310 - "beconn" is the total number of concurrent connections handled by the
8311 backend when the session was logged. It includes the total number of
8312 concurrent connections active on servers as well as the number of
8313 connections pending in queues. It is useful to estimate the amount of
8314 additional servers needed to support high loads for a given application.
8315 Most often when this value increases by huge jumps, it is because there is
8316 congestion on the backend servers, but sometimes it can be caused by a
8317 denial of service attack.
8318
8319 - "srv_conn" is the total number of concurrent connections still active on
8320 the server when the session was logged. It can never exceed the server's
8321 configured "maxconn" parameter. If this value is very often close or equal
8322 to the server's "maxconn", it means that traffic regulation is involved a
8323 lot, meaning that either the server's maxconn value is too low, or that
8324 there aren't enough servers to process the load with an optimal response
8325 time. When only one of the server's "srv_conn" is high, it usually means
8326 that this server has some trouble causing the requests to take longer to be
8327 processed than on other servers.
8328
8329 - "retries" is the number of connection retries experienced by this session
8330 when trying to connect to the server. It must normally be zero, unless a
8331 server is being stopped at the same moment the connection was attempted.
8332 Frequent retries generally indicate either a network problem between
8333 haproxy and the server, or a misconfigured system backlog on the server
8334 preventing new connections from being queued. This field may optionally be
8335 prefixed with a '+' sign, indicating that the session has experienced a
8336 redispatch after the maximal retry count has been reached on the initial
8337 server. In this case, the server name appearing in the log is the one the
8338 connection was redispatched to, and not the first one, though both may
8339 sometimes be the same in case of hashing for instance. So as a general rule
8340 of thumb, when a '+' is present in front of the retry count, this count
8341 should not be attributed to the logged server.
8342
8343 - "srv_queue" is the total number of requests which were processed before
8344 this one in the server queue. It is zero when the request has not gone
8345 through the server queue. It makes it possible to estimate the approximate
8346 server's response time by dividing the time spent in queue by the number of
8347 requests in the queue. It is worth noting that if a session experiences a
8348 redispatch and passes through two server queues, their positions will be
8349 cumulated. A request should not pass through both the server queue and the
8350 backend queue unless a redispatch occurs.
8351
8352 - "backend_queue" is the total number of requests which were processed before
8353 this one in the backend's global queue. It is zero when the request has not
8354 gone through the global queue. It makes it possible to estimate the average
8355 queue length, which easily translates into a number of missing servers when
8356 divided by a server's "maxconn" parameter. It is worth noting that if a
8357 session experiences a redispatch, it may pass twice in the backend's queue,
8358 and then both positions will be cumulated. A request should not pass
8359 through both the server queue and the backend queue unless a redispatch
8360 occurs.
8361
8362 - "captured_request_headers" is a list of headers captured in the request due
8363 to the presence of the "capture request header" statement in the frontend.
8364 Multiple headers can be captured, they will be delimited by a vertical bar
8365 ('|'). When no capture is enabled, the braces do not appear, causing a
8366 shift of remaining fields. It is important to note that this field may
8367 contain spaces, and that using it requires a smarter log parser than when
8368 it's not used. Please consult the section "Capturing HTTP headers and
8369 cookies" below for more details.
8370
8371 - "captured_response_headers" is a list of headers captured in the response
8372 due to the presence of the "capture response header" statement in the
8373 frontend. Multiple headers can be captured, they will be delimited by a
8374 vertical bar ('|'). When no capture is enabled, the braces do not appear,
8375 causing a shift of remaining fields. It is important to note that this
8376 field may contain spaces, and that using it requires a smarter log parser
8377 than when it's not used. Please consult the section "Capturing HTTP headers
8378 and cookies" below for more details.
8379
8380 - "http_request" is the complete HTTP request line, including the method,
8381 request and HTTP version string. Non-printable characters are encoded (see
8382 below the section "Non-printable characters"). This is always the last
8383 field, and it is always delimited by quotes and is the only one which can
8384 contain quotes. If new fields are added to the log format, they will be
8385 added before this field. This field might be truncated if the request is
8386 huge and does not fit in the standard syslog buffer (1024 characters). This
8387 is the reason why this field must always remain the last one.
8388
8389
Willy Tarreauc57f0e22009-05-10 13:12:33 +020083908.3. Advanced logging options
8391-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008392
8393Some advanced logging options are often looked for but are not easy to find out
8394just by looking at the various options. Here is an entry point for the few
8395options which can enable better logging. Please refer to the keywords reference
8396for more information about their usage.
8397
8398
Willy Tarreauc57f0e22009-05-10 13:12:33 +020083998.3.1. Disabling logging of external tests
8400------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008401
8402It is quite common to have some monitoring tools perform health checks on
8403haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
8404commercial load-balancer, and sometimes it will simply be a more complete
8405monitoring system such as Nagios. When the tests are very frequent, users often
8406ask how to disable logging for those checks. There are three possibilities :
8407
8408 - if connections come from everywhere and are just TCP probes, it is often
8409 desired to simply disable logging of connections without data exchange, by
8410 setting "option dontlognull" in the frontend. It also disables logging of
8411 port scans, which may or may not be desired.
8412
8413 - if the connection come from a known source network, use "monitor-net" to
8414 declare this network as monitoring only. Any host in this network will then
8415 only be able to perform health checks, and their requests will not be
8416 logged. This is generally appropriate to designate a list of equipments
8417 such as other load-balancers.
8418
8419 - if the tests are performed on a known URI, use "monitor-uri" to declare
8420 this URI as dedicated to monitoring. Any host sending this request will
8421 only get the result of a health-check, and the request will not be logged.
8422
8423
Willy Tarreauc57f0e22009-05-10 13:12:33 +020084248.3.2. Logging before waiting for the session to terminate
8425----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008426
8427The problem with logging at end of connection is that you have no clue about
8428what is happening during very long sessions, such as remote terminal sessions
8429or large file downloads. This problem can be worked around by specifying
8430"option logasap" in the frontend. Haproxy will then log as soon as possible,
8431just before data transfer begins. This means that in case of TCP, it will still
8432log the connection status to the server, and in case of HTTP, it will log just
8433after processing the server headers. In this case, the number of bytes reported
8434is the number of header bytes sent to the client. In order to avoid confusion
8435with normal logs, the total time field and the number of bytes are prefixed
8436with a '+' sign which means that real numbers are certainly larger.
8437
8438
Willy Tarreauc57f0e22009-05-10 13:12:33 +020084398.3.3. Raising log level upon errors
8440------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008441
8442Sometimes it is more convenient to separate normal traffic from errors logs,
8443for instance in order to ease error monitoring from log files. When the option
8444"log-separate-errors" is used, connections which experience errors, timeouts,
8445retries, redispatches or HTTP status codes 5xx will see their syslog level
8446raised from "info" to "err". This will help a syslog daemon store the log in
8447a separate file. It is very important to keep the errors in the normal traffic
8448file too, so that log ordering is not altered. You should also be careful if
8449you already have configured your syslog daemon to store all logs higher than
8450"notice" in an "admin" file, because the "err" level is higher than "notice".
8451
8452
Willy Tarreauc57f0e22009-05-10 13:12:33 +020084538.3.4. Disabling logging of successful connections
8454--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008455
8456Although this may sound strange at first, some large sites have to deal with
8457multiple thousands of logs per second and are experiencing difficulties keeping
8458them intact for a long time or detecting errors within them. If the option
8459"dontlog-normal" is set on the frontend, all normal connections will not be
8460logged. In this regard, a normal connection is defined as one without any
8461error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
8462and a response with a status 5xx is not considered normal and will be logged
8463too. Of course, doing is is really discouraged as it will remove most of the
8464useful information from the logs. Do this only if you have no other
8465alternative.
8466
8467
Willy Tarreauc57f0e22009-05-10 13:12:33 +020084688.4. Timing events
8469------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008470
8471Timers provide a great help in troubleshooting network problems. All values are
8472reported in milliseconds (ms). These timers should be used in conjunction with
8473the session termination flags. In TCP mode with "option tcplog" set on the
8474frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
8475mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
8476
8477 - Tq: total time to get the client request (HTTP mode only). It's the time
8478 elapsed between the moment the client connection was accepted and the
8479 moment the proxy received the last HTTP header. The value "-1" indicates
8480 that the end of headers (empty line) has never been seen. This happens when
8481 the client closes prematurely or times out.
8482
8483 - Tw: total time spent in the queues waiting for a connection slot. It
8484 accounts for backend queue as well as the server queues, and depends on the
8485 queue size, and the time needed for the server to complete previous
8486 requests. The value "-1" means that the request was killed before reaching
8487 the queue, which is generally what happens with invalid or denied requests.
8488
8489 - Tc: total time to establish the TCP connection to the server. It's the time
8490 elapsed between the moment the proxy sent the connection request, and the
8491 moment it was acknowledged by the server, or between the TCP SYN packet and
8492 the matching SYN/ACK packet in return. The value "-1" means that the
8493 connection never established.
8494
8495 - Tr: server response time (HTTP mode only). It's the time elapsed between
8496 the moment the TCP connection was established to the server and the moment
8497 the server sent its complete response headers. It purely shows its request
8498 processing time, without the network overhead due to the data transmission.
8499 It is worth noting that when the client has data to send to the server, for
8500 instance during a POST request, the time already runs, and this can distort
8501 apparent response time. For this reason, it's generally wise not to trust
8502 too much this field for POST requests initiated from clients behind an
8503 untrusted network. A value of "-1" here means that the last the response
8504 header (empty line) was never seen, most likely because the server timeout
8505 stroke before the server managed to process the request.
8506
8507 - Tt: total session duration time, between the moment the proxy accepted it
8508 and the moment both ends were closed. The exception is when the "logasap"
8509 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
8510 prefixed with a '+' sign. From this field, we can deduce "Td", the data
8511 transmission time, by substracting other timers when valid :
8512
8513 Td = Tt - (Tq + Tw + Tc + Tr)
8514
8515 Timers with "-1" values have to be excluded from this equation. In TCP
8516 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
8517 negative.
8518
8519These timers provide precious indications on trouble causes. Since the TCP
8520protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
8521that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008522due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008523close to a timeout value specified in the configuration, it often means that a
8524session has been aborted on timeout.
8525
8526Most common cases :
8527
8528 - If "Tq" is close to 3000, a packet has probably been lost between the
8529 client and the proxy. This is very rare on local networks but might happen
8530 when clients are on far remote networks and send large requests. It may
8531 happen that values larger than usual appear here without any network cause.
8532 Sometimes, during an attack or just after a resource starvation has ended,
8533 haproxy may accept thousands of connections in a few milliseconds. The time
8534 spent accepting these connections will inevitably slightly delay processing
8535 of other connections, and it can happen that request times in the order of
8536 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +02008537 connections have been accepted at once. Setting "option http-server-close"
8538 may display larger request times since "Tq" also measures the time spent
8539 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008540
8541 - If "Tc" is close to 3000, a packet has probably been lost between the
8542 server and the proxy during the server connection phase. This value should
8543 always be very low, such as 1 ms on local networks and less than a few tens
8544 of ms on remote networks.
8545
Willy Tarreau55165fe2009-05-10 12:02:55 +02008546 - If "Tr" is nearly always lower than 3000 except some rare values which seem
8547 to be the average majored by 3000, there are probably some packets lost
8548 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008549
8550 - If "Tt" is large even for small byte counts, it generally is because
8551 neither the client nor the server decides to close the connection, for
8552 instance because both have agreed on a keep-alive connection mode. In order
8553 to solve this issue, it will be needed to specify "option httpclose" on
8554 either the frontend or the backend. If the problem persists, it means that
8555 the server ignores the "close" connection mode and expects the client to
8556 close. Then it will be required to use "option forceclose". Having the
8557 smallest possible 'Tt' is important when connection regulation is used with
8558 the "maxconn" option on the servers, since no new connection will be sent
8559 to the server until another one is released.
8560
8561Other noticeable HTTP log cases ('xx' means any value to be ignored) :
8562
8563 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
8564 was emitted before the data phase. All the timers are valid
8565 except "Tt" which is shorter than reality.
8566
8567 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
8568 or it aborted too early. Check the session termination flags
8569 then "timeout http-request" and "timeout client" settings.
8570
8571 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
8572 servers were out of order, because the request was invalid
8573 or forbidden by ACL rules. Check the session termination
8574 flags.
8575
8576 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
8577 actively refused it or it timed out after Tt-(Tq+Tw) ms.
8578 Check the session termination flags, then check the
8579 "timeout connect" setting. Note that the tarpit action might
8580 return similar-looking patterns, with "Tw" equal to the time
8581 the client connection was maintained open.
8582
8583 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
8584 a complete response in time, or it closed its connexion
8585 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
8586 termination flags, then check the "timeout server" setting.
8587
8588
Willy Tarreauc57f0e22009-05-10 13:12:33 +020085898.5. Session state at disconnection
8590-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008591
8592TCP and HTTP logs provide a session termination indicator in the
8593"termination_state" field, just before the number of active connections. It is
85942-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
8595each of which has a special meaning :
8596
8597 - On the first character, a code reporting the first event which caused the
8598 session to terminate :
8599
8600 C : the TCP session was unexpectedly aborted by the client.
8601
8602 S : the TCP session was unexpectedly aborted by the server, or the
8603 server explicitly refused it.
8604
8605 P : the session was prematurely aborted by the proxy, because of a
8606 connection limit enforcement, because a DENY filter was matched,
8607 because of a security check which detected and blocked a dangerous
8608 error in server response which might have caused information leak
8609 (eg: cacheable cookie), or because the response was processed by
8610 the proxy (redirect, stats, etc...).
8611
8612 R : a resource on the proxy has been exhausted (memory, sockets, source
8613 ports, ...). Usually, this appears during the connection phase, and
8614 system logs should contain a copy of the precise error. If this
8615 happens, it must be considered as a very serious anomaly which
8616 should be fixed as soon as possible by any means.
8617
8618 I : an internal error was identified by the proxy during a self-check.
8619 This should NEVER happen, and you are encouraged to report any log
8620 containing this, because this would almost certainly be a bug. It
8621 would be wise to preventively restart the process after such an
8622 event too, in case it would be caused by memory corruption.
8623
8624 c : the client-side timeout expired while waiting for the client to
8625 send or receive data.
8626
8627 s : the server-side timeout expired while waiting for the server to
8628 send or receive data.
8629
8630 - : normal session completion, both the client and the server closed
8631 with nothing left in the buffers.
8632
8633 - on the second character, the TCP or HTTP session state when it was closed :
8634
Willy Tarreauf7b30a92010-12-06 22:59:17 +01008635 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008636 (HTTP mode only). Nothing was sent to any server.
8637
8638 Q : the proxy was waiting in the QUEUE for a connection slot. This can
8639 only happen when servers have a 'maxconn' parameter set. It can
8640 also happen in the global queue after a redispatch consecutive to
8641 a failed attempt to connect to a dying server. If no redispatch is
8642 reported, then no connection attempt was made to any server.
8643
8644 C : the proxy was waiting for the CONNECTION to establish on the
8645 server. The server might at most have noticed a connection attempt.
8646
8647 H : the proxy was waiting for complete, valid response HEADERS from the
8648 server (HTTP only).
8649
8650 D : the session was in the DATA phase.
8651
8652 L : the proxy was still transmitting LAST data to the client while the
8653 server had already finished. This one is very rare as it can only
8654 happen when the client dies while receiving the last packets.
8655
8656 T : the request was tarpitted. It has been held open with the client
8657 during the whole "timeout tarpit" duration or until the client
8658 closed, both of which will be reported in the "Tw" timer.
8659
8660 - : normal session completion after end of data transfer.
8661
8662 - the third character tells whether the persistence cookie was provided by
8663 the client (only in HTTP mode) :
8664
8665 N : the client provided NO cookie. This is usually the case for new
8666 visitors, so counting the number of occurrences of this flag in the
8667 logs generally indicate a valid trend for the site frequentation.
8668
8669 I : the client provided an INVALID cookie matching no known server.
8670 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02008671 cookies between HTTP/HTTPS sites, persistence conditionally
8672 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008673
8674 D : the client provided a cookie designating a server which was DOWN,
8675 so either "option persist" was used and the client was sent to
8676 this server, or it was not set and the client was redispatched to
8677 another server.
8678
Willy Tarreau996a92c2010-10-13 19:30:47 +02008679 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008680 server.
8681
Willy Tarreau996a92c2010-10-13 19:30:47 +02008682 E : the client provided a valid cookie, but with a last date which was
8683 older than what is allowed by the "maxidle" cookie parameter, so
8684 the cookie is consider EXPIRED and is ignored. The request will be
8685 redispatched just as if there was no cookie.
8686
8687 O : the client provided a valid cookie, but with a first date which was
8688 older than what is allowed by the "maxlife" cookie parameter, so
8689 the cookie is consider too OLD and is ignored. The request will be
8690 redispatched just as if there was no cookie.
8691
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008692 - : does not apply (no cookie set in configuration).
8693
8694 - the last character reports what operations were performed on the persistence
8695 cookie returned by the server (only in HTTP mode) :
8696
8697 N : NO cookie was provided by the server, and none was inserted either.
8698
8699 I : no cookie was provided by the server, and the proxy INSERTED one.
8700 Note that in "cookie insert" mode, if the server provides a cookie,
8701 it will still be overwritten and reported as "I" here.
8702
Willy Tarreau996a92c2010-10-13 19:30:47 +02008703 U : the proxy UPDATED the last date in the cookie that was presented by
8704 the client. This can only happen in insert mode with "maxidle". It
8705 happens everytime there is activity at a different date than the
8706 date indicated in the cookie. If any other change happens, such as
8707 a redispatch, then the cookie will be marked as inserted instead.
8708
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008709 P : a cookie was PROVIDED by the server and transmitted as-is.
8710
8711 R : the cookie provided by the server was REWRITTEN by the proxy, which
8712 happens in "cookie rewrite" or "cookie prefix" modes.
8713
8714 D : the cookie provided by the server was DELETED by the proxy.
8715
8716 - : does not apply (no cookie set in configuration).
8717
Willy Tarreau996a92c2010-10-13 19:30:47 +02008718The combination of the two first flags gives a lot of information about what
8719was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008720helpful to detect server saturation, network troubles, local system resource
8721starvation, attacks, etc...
8722
8723The most common termination flags combinations are indicated below. They are
8724alphabetically sorted, with the lowercase set just after the upper case for
8725easier finding and understanding.
8726
8727 Flags Reason
8728
8729 -- Normal termination.
8730
8731 CC The client aborted before the connection could be established to the
8732 server. This can happen when haproxy tries to connect to a recently
8733 dead (or unchecked) server, and the client aborts while haproxy is
8734 waiting for the server to respond or for "timeout connect" to expire.
8735
8736 CD The client unexpectedly aborted during data transfer. This can be
8737 caused by a browser crash, by an intermediate equipment between the
8738 client and haproxy which decided to actively break the connection,
8739 by network routing issues between the client and haproxy, or by a
8740 keep-alive session between the server and the client terminated first
8741 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +01008742
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008743 cD The client did not send nor acknowledge any data for as long as the
8744 "timeout client" delay. This is often caused by network failures on
8745 the client side, or the client simply leaving the net uncleanly.
8746
8747 CH The client aborted while waiting for the server to start responding.
8748 It might be the server taking too long to respond or the client
8749 clicking the 'Stop' button too fast.
8750
8751 cH The "timeout client" stroke while waiting for client data during a
8752 POST request. This is sometimes caused by too large TCP MSS values
8753 for PPPoE networks which cannot transport full-sized packets. It can
8754 also happen when client timeout is smaller than server timeout and
8755 the server takes too long to respond.
8756
8757 CQ The client aborted while its session was queued, waiting for a server
8758 with enough empty slots to accept it. It might be that either all the
8759 servers were saturated or that the assigned server was taking too
8760 long a time to respond.
8761
8762 CR The client aborted before sending a full HTTP request. Most likely
8763 the request was typed by hand using a telnet client, and aborted
8764 too early. The HTTP status code is likely a 400 here. Sometimes this
8765 might also be caused by an IDS killing the connection between haproxy
8766 and the client.
8767
8768 cR The "timeout http-request" stroke before the client sent a full HTTP
8769 request. This is sometimes caused by too large TCP MSS values on the
8770 client side for PPPoE networks which cannot transport full-sized
8771 packets, or by clients sending requests by hand and not typing fast
8772 enough, or forgetting to enter the empty line at the end of the
8773 request. The HTTP status code is likely a 408 here.
8774
8775 CT The client aborted while its session was tarpitted. It is important to
8776 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +02008777 wrong tarpit rules have been written. If a lot of them happen, it
8778 might make sense to lower the "timeout tarpit" value to something
8779 closer to the average reported "Tw" timer, in order not to consume
8780 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008781
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008782 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008783 the TCP connection (the proxy received a TCP RST or an ICMP message
8784 in return). Under some circumstances, it can also be the network
8785 stack telling the proxy that the server is unreachable (eg: no route,
8786 or no ARP response on local network). When this happens in HTTP mode,
8787 the status code is likely a 502 or 503 here.
8788
8789 sC The "timeout connect" stroke before a connection to the server could
8790 complete. When this happens in HTTP mode, the status code is likely a
8791 503 or 504 here.
8792
8793 SD The connection to the server died with an error during the data
8794 transfer. This usually means that haproxy has received an RST from
8795 the server or an ICMP message from an intermediate equipment while
8796 exchanging data with the server. This can be caused by a server crash
8797 or by a network issue on an intermediate equipment.
8798
8799 sD The server did not send nor acknowledge any data for as long as the
8800 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008801 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008802 load-balancers, ...), as well as keep-alive sessions maintained
8803 between the client and the server expiring first on haproxy.
8804
8805 SH The server aborted before sending its full HTTP response headers, or
8806 it crashed while processing the request. Since a server aborting at
8807 this moment is very rare, it would be wise to inspect its logs to
8808 control whether it crashed and why. The logged request may indicate a
8809 small set of faulty requests, demonstrating bugs in the application.
8810 Sometimes this might also be caused by an IDS killing the connection
8811 between haproxy and the server.
8812
8813 sH The "timeout server" stroke before the server could return its
8814 response headers. This is the most common anomaly, indicating too
8815 long transactions, probably caused by server or database saturation.
8816 The immediate workaround consists in increasing the "timeout server"
8817 setting, but it is important to keep in mind that the user experience
8818 will suffer from these long response times. The only long term
8819 solution is to fix the application.
8820
8821 sQ The session spent too much time in queue and has been expired. See
8822 the "timeout queue" and "timeout connect" settings to find out how to
8823 fix this if it happens too often. If it often happens massively in
8824 short periods, it may indicate general problems on the affected
8825 servers due to I/O or database congestion, or saturation caused by
8826 external attacks.
8827
8828 PC The proxy refused to establish a connection to the server because the
8829 process' socket limit has been reached while attempting to connect.
8830 The global "maxconn" parameter may be increased in the configuration
8831 so that it does not happen anymore. This status is very rare and
8832 might happen when the global "ulimit-n" parameter is forced by hand.
8833
Willy Tarreaued2fd2d2010-12-29 11:23:27 +01008834 PD The proxy blocked an incorrectly formatted chunked encoded message in
8835 a request or a response, after the server has emitted its headers. In
8836 most cases, this will indicate an invalid message from the server to
8837 the client.
8838
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008839 PH The proxy blocked the server's response, because it was invalid,
8840 incomplete, dangerous (cache control), or matched a security filter.
8841 In any case, an HTTP 502 error is sent to the client. One possible
8842 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +01008843 containing unauthorized characters. It is also possible but quite
8844 rare, that the proxy blocked a chunked-encoding request from the
8845 client due to an invalid syntax, before the server responded. In this
8846 case, an HTTP 400 error is sent to the client and reported in the
8847 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008848
8849 PR The proxy blocked the client's HTTP request, either because of an
8850 invalid HTTP syntax, in which case it returned an HTTP 400 error to
8851 the client, or because a deny filter matched, in which case it
8852 returned an HTTP 403 error.
8853
8854 PT The proxy blocked the client's request and has tarpitted its
8855 connection before returning it a 500 server error. Nothing was sent
8856 to the server. The connection was maintained open for as long as
8857 reported by the "Tw" timer field.
8858
8859 RC A local resource has been exhausted (memory, sockets, source ports)
8860 preventing the connection to the server from establishing. The error
8861 logs will tell precisely what was missing. This is very rare and can
8862 only be solved by proper system tuning.
8863
Willy Tarreau996a92c2010-10-13 19:30:47 +02008864The combination of the two last flags gives a lot of information about how
8865persistence was handled by the client, the server and by haproxy. This is very
8866important to troubleshoot disconnections, when users complain they have to
8867re-authenticate. The commonly encountered flags are :
8868
8869 -- Persistence cookie is not enabled.
8870
8871 NN No cookie was provided by the client, none was inserted in the
8872 response. For instance, this can be in insert mode with "postonly"
8873 set on a GET request.
8874
8875 II A cookie designating an invalid server was provided by the client,
8876 a valid one was inserted in the response. This typically happens when
8877 a "server" entry is removed from the configuraton, since its cookie
8878 value can be presented by a client when no other server knows it.
8879
8880 NI No cookie was provided by the client, one was inserted in the
8881 response. This typically happens for first requests from every user
8882 in "insert" mode, which makes it an easy way to count real users.
8883
8884 VN A cookie was provided by the client, none was inserted in the
8885 response. This happens for most responses for which the client has
8886 already got a cookie.
8887
8888 VU A cookie was provided by the client, with a last visit date which is
8889 not completely up-to-date, so an updated cookie was provided in
8890 response. This can also happen if there was no date at all, or if
8891 there was a date but the "maxidle" parameter was not set, so that the
8892 cookie can be switched to unlimited time.
8893
8894 EI A cookie was provided by the client, with a last visit date which is
8895 too old for the "maxidle" parameter, so the cookie was ignored and a
8896 new cookie was inserted in the response.
8897
8898 OI A cookie was provided by the client, with a first visit date which is
8899 too old for the "maxlife" parameter, so the cookie was ignored and a
8900 new cookie was inserted in the response.
8901
8902 DI The server designated by the cookie was down, a new server was
8903 selected and a new cookie was emitted in the response.
8904
8905 VI The server designated by the cookie was not marked dead but could not
8906 be reached. A redispatch happened and selected another one, which was
8907 then advertised in the response.
8908
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008909
Willy Tarreauc57f0e22009-05-10 13:12:33 +020089108.6. Non-printable characters
8911-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008912
8913In order not to cause trouble to log analysis tools or terminals during log
8914consulting, non-printable characters are not sent as-is into log files, but are
8915converted to the two-digits hexadecimal representation of their ASCII code,
8916prefixed by the character '#'. The only characters that can be logged without
8917being escaped are comprised between 32 and 126 (inclusive). Obviously, the
8918escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
8919is the same for the character '"' which becomes "#22", as well as '{', '|' and
8920'}' when logging headers.
8921
8922Note that the space character (' ') is not encoded in headers, which can cause
8923issues for tools relying on space count to locate fields. A typical header
8924containing spaces is "User-Agent".
8925
8926Last, it has been observed that some syslog daemons such as syslog-ng escape
8927the quote ('"') with a backslash ('\'). The reverse operation can safely be
8928performed since no quote may appear anywhere else in the logs.
8929
8930
Willy Tarreauc57f0e22009-05-10 13:12:33 +020089318.7. Capturing HTTP cookies
8932---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008933
8934Cookie capture simplifies the tracking a complete user session. This can be
8935achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008936section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008937cookie will simultaneously be checked in the request ("Cookie:" header) and in
8938the response ("Set-Cookie:" header). The respective values will be reported in
8939the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008940locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008941not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
8942user switches to a new session for example, because the server will reassign it
8943a new cookie. It is also possible to detect if a server unexpectedly sets a
8944wrong cookie to a client, leading to session crossing.
8945
8946 Examples :
8947 # capture the first cookie whose name starts with "ASPSESSION"
8948 capture cookie ASPSESSION len 32
8949
8950 # capture the first cookie whose name is exactly "vgnvisitor"
8951 capture cookie vgnvisitor= len 32
8952
8953
Willy Tarreauc57f0e22009-05-10 13:12:33 +020089548.8. Capturing HTTP headers
8955---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008956
8957Header captures are useful to track unique request identifiers set by an upper
8958proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
8959the response, one can search for information about the response length, how the
8960server asked the cache to behave, or an object location during a redirection.
8961
8962Header captures are performed using the "capture request header" and "capture
8963response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008964section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008965
8966It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008967time. Non-existent headers are logged as empty strings, and if one header
8968appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008969are grouped within braces '{' and '}' in the same order as they were declared,
8970and delimited with a vertical bar '|' without any space. Response headers
8971follow the same representation, but are displayed after a space following the
8972request headers block. These blocks are displayed just before the HTTP request
8973in the logs.
8974
8975 Example :
8976 # This instance chains to the outgoing proxy
8977 listen proxy-out
8978 mode http
8979 option httplog
8980 option logasap
8981 log global
8982 server cache1 192.168.1.1:3128
8983
8984 # log the name of the virtual server
8985 capture request header Host len 20
8986
8987 # log the amount of data uploaded during a POST
8988 capture request header Content-Length len 10
8989
8990 # log the beginning of the referrer
8991 capture request header Referer len 20
8992
8993 # server name (useful for outgoing proxies only)
8994 capture response header Server len 20
8995
8996 # logging the content-length is useful with "option logasap"
8997 capture response header Content-Length len 10
8998
8999 # log the expected cache behaviour on the response
9000 capture response header Cache-Control len 8
9001
9002 # the Via header will report the next proxy's name
9003 capture response header Via len 20
9004
9005 # log the URL location during a redirection
9006 capture response header Location len 20
9007
9008 >>> Aug 9 20:26:09 localhost \
9009 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
9010 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
9011 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
9012 "GET http://fr.adserver.yahoo.com/"
9013
9014 >>> Aug 9 20:30:46 localhost \
9015 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
9016 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
9017 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009018 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009019
9020 >>> Aug 9 20:30:46 localhost \
9021 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
9022 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
9023 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
9024 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009025 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009026
9027
Willy Tarreauc57f0e22009-05-10 13:12:33 +020090288.9. Examples of logs
9029---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009030
9031These are real-world examples of logs accompanied with an explanation. Some of
9032them have been made up by hand. The syslog part has been removed for better
9033reading. Their sole purpose is to explain how to decipher them.
9034
9035 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
9036 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
9037 "HEAD / HTTP/1.0"
9038
9039 => long request (6.5s) entered by hand through 'telnet'. The server replied
9040 in 147 ms, and the session ended normally ('----')
9041
9042 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
9043 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
9044 0/9 "HEAD / HTTP/1.0"
9045
9046 => Idem, but the request was queued in the global queue behind 9 other
9047 requests, and waited there for 1230 ms.
9048
9049 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
9050 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
9051 "GET /image.iso HTTP/1.0"
9052
9053 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009054 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009055 14 ms, 243 bytes of headers were sent to the client, and total time from
9056 accept to first data byte is 30 ms.
9057
9058 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
9059 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
9060 "GET /cgi-bin/bug.cgi? HTTP/1.0"
9061
9062 => the proxy blocked a server response either because of an "rspdeny" or
9063 "rspideny" filter, or because the response was improperly formatted and
9064 not HTTP-compliant, or because it blocked sensible information which
9065 risked being cached. In this case, the response is replaced with a "502
9066 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
9067 to return the 502 and not the server.
9068
9069 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009070 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 +01009071
9072 => the client never completed its request and aborted itself ("C---") after
9073 8.5s, while the proxy was waiting for the request headers ("-R--").
9074 Nothing was sent to any server.
9075
9076 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
9077 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
9078
9079 => The client never completed its request, which was aborted by the
9080 time-out ("c---") after 50s, while the proxy was waiting for the request
9081 headers ("-R--"). Nothing was sent to any server, but the proxy could
9082 send a 408 return code to the client.
9083
9084 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
9085 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
9086
9087 => This log was produced with "option tcplog". The client timed out after
9088 5 seconds ("c----").
9089
9090 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
9091 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +01009092 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009093
9094 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009095 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009096 (config says 'retries 3'), and no redispatch (otherwise we would have
9097 seen "/+3"). Status code 503 was returned to the client. There were 115
9098 connections on this server, 202 connections on this proxy, and 205 on
9099 the global process. It is possible that the server refused the
9100 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009101
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009102
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091039. Statistics and monitoring
9104----------------------------
9105
9106It is possible to query HAProxy about its status. The most commonly used
9107mechanism is the HTTP statistics page. This page also exposes an alternative
9108CSV output format for monitoring tools. The same format is provided on the
9109Unix socket.
9110
9111
91129.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009113---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009114
Willy Tarreau7f062c42009-03-05 18:43:00 +01009115The statistics may be consulted either from the unix socket or from the HTTP
9116page. Both means provide a CSV format whose fields follow.
9117
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009118 0. pxname: proxy name
9119 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
9120 for server)
9121 2. qcur: current queued requests
9122 3. qmax: max queued requests
9123 4. scur: current sessions
9124 5. smax: max sessions
9125 6. slim: sessions limit
9126 7. stot: total sessions
9127 8. bin: bytes in
9128 9. bout: bytes out
9129 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009130 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009131 12. ereq: request errors
9132 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +01009133 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009134 15. wretr: retries (warning)
9135 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +01009136 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01009137 18. weight: server weight (server), total weight (backend)
9138 19. act: server is active (server), number of active servers (backend)
9139 20. bck: server is backup (server), number of backup servers (backend)
9140 21. chkfail: number of failed checks
9141 22. chkdown: number of UP->DOWN transitions
9142 23. lastchg: last status change (in seconds)
9143 24. downtime: total downtime (in seconds)
9144 25. qlimit: queue limit
9145 26. pid: process id (0 for first instance, 1 for second, ...)
9146 27. iid: unique proxy id
9147 28. sid: service id (unique inside a proxy)
9148 29. throttle: warm up status
9149 30. lbtot: total number of times a server was selected
9150 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02009151 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +02009152 33. rate: number of sessions per second over last elapsed second
9153 34. rate_lim: limit on new sessions per second
9154 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02009155 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +01009156 UNK -> unknown
9157 INI -> initializing
9158 SOCKERR -> socket error
9159 L4OK -> check passed on layer 4, no upper layers testing enabled
9160 L4TMOUT -> layer 1-4 timeout
9161 L4CON -> layer 1-4 connection problem, for example
9162 "Connection refused" (tcp rst) or "No route to host" (icmp)
9163 L6OK -> check passed on layer 6
9164 L6TOUT -> layer 6 (SSL) timeout
9165 L6RSP -> layer 6 invalid response - protocol error
9166 L7OK -> check passed on layer 7
9167 L7OKC -> check conditionally passed on layer 7, for example 404 with
9168 disable-on-404
9169 L7TOUT -> layer 7 (HTTP/SMTP) timeout
9170 L7RSP -> layer 7 invalid response - protocol error
9171 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02009172 37. check_code: layer5-7 code, if available
9173 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009174 39. hrsp_1xx: http responses with 1xx code
9175 40. hrsp_2xx: http responses with 2xx code
9176 41. hrsp_3xx: http responses with 3xx code
9177 42. hrsp_4xx: http responses with 4xx code
9178 43. hrsp_5xx: http responses with 5xx code
9179 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +01009180 45. hanafail: failed health checks details
9181 46. req_rate: HTTP requests per second over last elapsed second
9182 47. req_rate_max: max number of HTTP requests per second observed
9183 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +01009184 49. cli_abrt: number of data transfers aborted by the client
9185 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau844e3c52008-01-11 16:28:18 +01009186
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009187
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091889.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009189-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009190
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009191The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009192must be terminated by a line feed. The socket supports pipelining, so that it
9193is possible to chain multiple commands at once provided they are delimited by
9194a semi-colon or a line feed, although the former is more reliable as it has no
9195risk of being truncated over the network. The responses themselves will each be
9196followed by an empty line, so it will be easy for an external script to match a
9197given response with a given request. By default one command line is processed
9198then the connection closes, but there is an interactive allowing multiple lines
9199to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009200
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009201It is important to understand that when multiple haproxy processes are started
9202on the same sockets, any process may pick up the request and will output its
9203own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009204
Willy Tarreaud63335a2010-02-26 12:56:52 +01009205clear counters
9206 Clear the max values of the statistics counters in each proxy (frontend &
9207 backend) and in each server. The cumulated counters are not affected. This
9208 can be used to get clean counters after an incident, without having to
9209 restart nor to clear traffic counters. This command is restricted and can
9210 only be issued on sockets configured for levels "operator" or "admin".
9211
9212clear counters all
9213 Clear all statistics counters in each proxy (frontend & backend) and in each
9214 server. This has the same effect as restarting. This command is restricted
9215 and can only be issued on sockets configured for level "admin".
9216
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009217clear table <table> key <key>
9218 Remove entry <key> from the stick-table <table>. The key must be of the same
9219 type as the table, which currently is limited to IPv4. This is typically used
9220 un unblock some users complaining they have been abusively denied access to a
9221 service, but this can also be used to clear some stickiness entries matching
9222 a server that is going to be replaced (see "show table" below for details).
9223 Note that sometimes, removal of a key will be refused because it is currently
9224 tracked by a session. Retrying a few seconds later after the session ends is
9225 usuall enough.
9226
9227 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009228 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009229 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +02009230 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
9231 bytes_out_rate(60000)=187
9232 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9233 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009234
9235 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
9236
9237 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009238 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +02009239 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9240 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009241
Willy Tarreaud63335a2010-02-26 12:56:52 +01009242disable server <backend>/<server>
9243 Mark the server DOWN for maintenance. In this mode, no more checks will be
9244 performed on the server until it leaves maintenance.
9245 If the server is tracked by other servers, those servers will be set to DOWN
9246 during the maintenance.
9247
9248 In the statistics page, a server DOWN for maintenance will appear with a
9249 "MAINT" status, its tracking servers with the "MAINT(via)" one.
9250
9251 Both the backend and the server may be specified either by their name or by
9252 their numeric ID, prefixed with a dash ('#').
9253
9254 This command is restricted and can only be issued on sockets configured for
9255 level "admin".
9256
9257enable server <backend>/<server>
9258 If the server was previously marked as DOWN for maintenance, this marks the
9259 server UP and checks are re-enabled.
9260
9261 Both the backend and the server may be specified either by their name or by
9262 their numeric ID, prefixed with a dash ('#').
9263
9264 This command is restricted and can only be issued on sockets configured for
9265 level "admin".
9266
9267get weight <backend>/<server>
9268 Report the current weight and the initial weight of server <server> in
9269 backend <backend> or an error if either doesn't exist. The initial weight is
9270 the one that appears in the configuration file. Both are normally equal
9271 unless the current weight has been changed. Both the backend and the server
9272 may be specified either by their name or by their numeric ID, prefixed with a
9273 dash ('#').
9274
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009275help
9276 Print the list of known keywords and their basic usage. The same help screen
9277 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01009278
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009279prompt
9280 Toggle the prompt at the beginning of the line and enter or leave interactive
9281 mode. In interactive mode, the connection is not closed after a command
9282 completes. Instead, the prompt will appear again, indicating the user that
9283 the interpreter is waiting for a new command. The prompt consists in a right
9284 angle bracket followed by a space "> ". This mode is particularly convenient
9285 when one wants to periodically check information such as stats or errors.
9286 It is also a good idea to enter interactive mode before issuing a "help"
9287 command.
9288
9289quit
9290 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009291
Willy Tarreaud63335a2010-02-26 12:56:52 +01009292set timeout cli <delay>
9293 Change the CLI interface timeout for current connection. This can be useful
9294 during long debugging sessions where the user needs to constantly inspect
9295 some indicators without being disconnected. The delay is passed in seconds.
9296
9297set weight <backend>/<server> <weight>[%]
9298 Change a server's weight to the value passed in argument. If the value ends
9299 with the '%' sign, then the new weight will be relative to the initially
9300 configured weight. Relative weights are only permitted between 0 and 100%,
9301 and absolute weights are permitted between 0 and 256. Servers which are part
9302 of a farm running a static load-balancing algorithm have stricter limitations
9303 because the weight cannot change once set. Thus for these servers, the only
9304 accepted values are 0 and 100% (or 0 and the initial weight). Changes take
9305 effect immediately, though certain LB algorithms require a certain amount of
9306 requests to consider changes. A typical usage of this command is to disable
9307 a server during an update by setting its weight to zero, then to enable it
9308 again after the update by setting it back to 100%. This command is restricted
9309 and can only be issued on sockets configured for level "admin". Both the
9310 backend and the server may be specified either by their name or by their
9311 numeric ID, prefixed with a dash ('#').
9312
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009313show errors [<iid>]
9314 Dump last known request and response errors collected by frontends and
9315 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +02009316 either frontend or backend whose ID is <iid>. This command is restricted
9317 and can only be issued on sockets configured for levels "operator" or
9318 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009319
9320 The errors which may be collected are the last request and response errors
9321 caused by protocol violations, often due to invalid characters in header
9322 names. The report precisely indicates what exact character violated the
9323 protocol. Other important information such as the exact date the error was
9324 detected, frontend and backend names, the server name (when known), the
9325 internal session ID and the source address which has initiated the session
9326 are reported too.
9327
9328 All characters are returned, and non-printable characters are encoded. The
9329 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
9330 letter following a backslash. The backslash itself is encoded as '\\' to
9331 avoid confusion. Other non-printable characters are encoded '\xNN' where
9332 NN is the two-digits hexadecimal representation of the character's ASCII
9333 code.
9334
9335 Lines are prefixed with the position of their first character, starting at 0
9336 for the beginning of the buffer. At most one input line is printed per line,
9337 and large lines will be broken into multiple consecutive output lines so that
9338 the output never goes beyond 79 characters wide. It is easy to detect if a
9339 line was broken, because it will not end with '\n' and the next line's offset
9340 will be followed by a '+' sign, indicating it is a continuation of previous
9341 line.
9342
9343 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009344 $ echo "show errors" | socat stdio /tmp/sock1
9345 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009346 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
9347 response length 213 bytes, error at position 23:
9348
9349 00000 HTTP/1.0 200 OK\r\n
9350 00017 header/bizarre:blah\r\n
9351 00038 Location: blah\r\n
9352 00054 Long-line: this is a very long line which should b
9353 00104+ e broken into multiple lines on the output buffer,
9354 00154+ otherwise it would be too large to print in a ter
9355 00204+ minal\r\n
9356 00211 \r\n
9357
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009358 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01009359 ID 2 has blocked an invalid response from its server s2 which has internal
9360 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
9361 received by frontend fe-eth0 whose ID is 1. The total response length was
9362 213 bytes when the error was detected, and the error was at byte 23. This
9363 is the slash ('/') in header name "header/bizarre", which is not a valid
9364 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01009365
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009366show info
9367 Dump info about haproxy status on current process.
9368
9369show sess
9370 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +02009371 be huge. This command is restricted and can only be issued on sockets
9372 configured for levels "operator" or "admin".
9373
Willy Tarreau66dc20a2010-03-05 17:53:32 +01009374show sess <id>
9375 Display a lot of internal information about the specified session identifier.
9376 This identifier is the first field at the beginning of the lines in the dumps
9377 of "show sess" (it corresponds to the session pointer). Those information are
9378 useless to most users but may be used by haproxy developers to troubleshoot a
9379 complex bug. The output format is intentionally not documented so that it can
9380 freely evolve depending on demands.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009381
9382show stat [<iid> <type> <sid>]
9383 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
9384 possible to dump only selected items :
9385 - <iid> is a proxy ID, -1 to dump everything
9386 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
9387 backends, 4 for servers, -1 for everything. These values can be ORed,
9388 for example:
9389 1 + 2 = 3 -> frontend + backend.
9390 1 + 2 + 4 = 7 -> frontend + backend + server.
9391 - <sid> is a server ID, -1 to dump everything from the selected proxy.
9392
9393 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009394 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
9395 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009396 Version: 1.4-dev2-49
9397 Release_date: 2009/09/23
9398 Nbproc: 1
9399 Process_num: 1
9400 (...)
9401
9402 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
9403 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
9404 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
9405 (...)
9406 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
9407
9408 $
9409
9410 Here, two commands have been issued at once. That way it's easy to find
9411 which process the stats apply to in multi-process mode. Notice the empty
9412 line after the information output which marks the end of the first block.
9413 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009414 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02009415
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009416show table
9417 Dump general information on all known stick-tables. Their name is returned
9418 (the name of the proxy which holds them), their type (currently zero, always
9419 IP), their size in maximum possible number of entries, and the number of
9420 entries currently in use.
9421
9422 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009423 $ echo "show table" | socat stdio /tmp/sock1
9424 >>> # table: front_pub, type: 0, size:204800, used:171454
9425 >>> # table: back_rdp, type: 0, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009426
9427show table <name> [ data.<type> <operator> <value> ]
9428 Dump contents of stick-table <name>. In this mode, a first line of generic
9429 information about the table is reported as with "show table", then all
9430 entries are dumped. Since this can be quite heavy, it is possible to specify
9431 a filter in order to specify what entries to display. The filter then applies
9432 to the stored data (see "stick-table" in section 4.2). One stored data type
9433 has to be specified in <type>, and this data type must be stored in the table
9434 otherwise an error is reported. The data is compared according to <operator>
9435 with the 64-bit integer <value>. Operators are the same as with the ACLs :
9436 - eq : match entries whose data is equal to this value
9437 - ne : match entries whose data is not equal to this value
9438 - le : match entries whose data is less than or equal to this value
9439 - ge : match entries whose data is greater than or equal to this value
9440 - lt : match entries whose data is less than this value
9441 - gt : match entries whose data is greater than this value
9442
9443 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009444 $ echo "show table http_proxy" | socat stdio /tmp/sock1
9445 >>> # table: http_proxy, type: 0, size:204800, used:2
9446 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
9447 bytes_out_rate(60000)=187
9448 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9449 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009450
Willy Tarreau62a36c42010-08-17 15:53:10 +02009451 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
9452 >>> # table: http_proxy, type: 0, size:204800, used:2
9453 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9454 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009455
Willy Tarreau62a36c42010-08-17 15:53:10 +02009456 $ echo "show table http_proxy data.conn_rate gt 5" | \
9457 socat stdio /tmp/sock1
9458 >>> # table: http_proxy, type: 0, size:204800, used:2
9459 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
9460 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009461
9462 When the data criterion applies to a dynamic value dependent on time such as
9463 a bytes rate, the value is dynamically computed during the evaluation of the
9464 entry in order to decide whether it has to be dumped or not. This means that
9465 such a filter could match for some time then not match anymore because as
9466 time goes, the average event rate drops.
9467
9468 It is possible to use this to extract lists of IP addresses abusing the
9469 service, in order to monitor them or even blacklist them in a firewall.
9470 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +02009471 $ echo "show table http_proxy data.gpc0 gt 0" \
9472 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +02009473 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
9474 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +02009475
Willy Tarreau0ba27502007-12-24 16:55:16 +01009476/*
9477 * Local variables:
9478 * fill-column: 79
9479 * End:
9480 */