blob: e455368c94b0cc5a61aad08d0355ae34fe9c2d98 [file] [log] [blame]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001 ----------------------
2 HAProxy
3 Configuration Manual
4 ----------------------
Willy Tarreau79158882009-06-09 11:59:08 +02005 version 1.4
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreaub03d2982009-07-29 22:38:32 +02007 2009/07/27
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
21 ('\') and continue on next line. If you add sections, please update the
22 summary below for easier searching.
23
24
25Summary
26-------
27
281. Quick reminder about HTTP
291.1. The HTTP transaction model
301.2. HTTP request
311.2.1. The Request line
321.2.2. The request headers
331.3. HTTP response
341.3.1. The Response line
351.3.2. The response headers
36
372. Configuring HAProxy
382.1. Configuration file format
392.2. Time format
40
413. Global parameters
423.1. Process management and security
433.2. Performance tuning
443.3. Debugging
45
464. Proxies
474.1. Proxy keywords matrix
484.2. Alphabetically sorted keywords reference
49
505. Server options
51
526. HTTP header manipulation
53
547. Using ACLs
557.1. Matching integers
567.2. Matching strings
577.3. Matching regular expressions (regexes)
587.4. Matching IPv4 addresses
597.5. Available matching criteria
607.5.1. Matching at Layer 4 and below
617.5.2. Matching contents at Layer 4
627.5.3. Matching at Layer 7
637.6. Pre-defined ACLs
647.7. Using ACLs to form conditions
65
668. Logging
678.1. Log levels
688.2. Log formats
698.2.1. Default log format
708.2.2. TCP log format
718.2.3. HTTP log format
728.3. Advanced logging options
738.3.1. Disabling logging of external tests
748.3.2. Logging before waiting for the session to terminate
758.3.3. Raising log level upon errors
768.3.4. Disabling logging of successful connections
778.4. Timing events
788.5. Session state at disconnection
798.6. Non-printable characters
808.7. Capturing HTTP cookies
818.8. Capturing HTTP headers
828.9. Examples of logs
83
849. Statistics and monitoring
859.1. CSV format
869.2. Unix Socket commands
87
88
891. Quick reminder about HTTP
90----------------------------
91
92When haproxy is running in HTTP mode, both the request and the response are
93fully analyzed and indexed, thus it becomes possible to build matching criteria
94on almost anything found in the contents.
95
96However, it is important to understand how HTTP requests and responses are
97formed, and how HAProxy decomposes them. It will then become easier to write
98correct rules and to debug existing configurations.
99
100
1011.1. The HTTP transaction model
102-------------------------------
103
104The HTTP protocol is transaction-driven. This means that each request will lead
105to one and only one response. Traditionnally, a TCP connection is established
106from the client to the server, a request is sent by the client on the
107connection, the server responds and the connection is closed. A new request
108will involve a new connection :
109
110 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
111
112In this mode, called the "HTTP close" mode, there are as many connection
113establishments as there are HTTP transactions. Since the connection is closed
114by the server after the response, the client does not need to know the content
115length.
116
117Due to the transactional nature of the protocol, it was possible to improve it
118to avoid closing a connection between two subsequent transactions. In this mode
119however, it is mandatory that the server indicates the content length for each
120response so that the client does not wait indefinitely. For this, a special
121header is used: "Content-length". This mode is called the "keep-alive" mode :
122
123 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
124
125Its advantages are a reduced latency between transactions, and less processing
126power required on the server side. It is generally better than the close mode,
127but not always because the clients often limit their concurrent connections to
128a smaller value. HAProxy currently does not support the HTTP keep-alive mode,
129but knows how to transform it to the close mode.
130
131A last improvement in the communications is the pipelining mode. It still uses
132keep-alive, but the client does not wait for the first response to send the
133second request. This is useful for fetching large number of images composing a
134page :
135
136 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
137
138This can obviously have a tremendous benefit on performance because the network
139latency is eliminated between subsequent requests. Many HTTP agents do not
140correctly support pipelining since there is no way to associate a response with
141the corresponding request in HTTP. For this reason, it is mandatory for the
142server to reply in the exact same order as the requests were received.
143
144Right now, HAProxy only supports the first mode (HTTP close) if it needs to
145process the request. This means that for each request, there will be one TCP
146connection. If keep-alive or pipelining are required, HAProxy will still
147support them, but will only see the first request and the first response of
148each transaction. While this is generally problematic with regards to logs,
149content switching or filtering, it most often causes no problem for persistence
150with cookie insertion.
151
152
1531.2. HTTP request
154-----------------
155
156First, let's consider this HTTP request :
157
158 Line Contents
159 number
160 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
161 2 Host: www.mydomain.com
162 3 User-agent: my small browser
163 4 Accept: image/jpeg, image/gif
164 5 Accept: image/png
165
166
1671.2.1. The Request line
168-----------------------
169
170Line 1 is the "request line". It is always composed of 3 fields :
171
172 - a METHOD : GET
173 - a URI : /serv/login.php?lang=en&profile=2
174 - a version tag : HTTP/1.1
175
176All of them are delimited by what the standard calls LWS (linear white spaces),
177which are commonly spaces, but can also be tabs or line feeds/carriage returns
178followed by spaces/tabs. The method itself cannot contain any colon (':') and
179is limited to alphabetic letters. All those various combinations make it
180desirable that HAProxy performs the splitting itself rather than leaving it to
181the user to write a complex or inaccurate regular expression.
182
183The URI itself can have several forms :
184
185 - A "relative URI" :
186
187 /serv/login.php?lang=en&profile=2
188
189 It is a complete URL without the host part. This is generally what is
190 received by servers, reverse proxies and transparent proxies.
191
192 - An "absolute URI", also called a "URL" :
193
194 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
195
196 It is composed of a "scheme" (the protocol name followed by '://'), a host
197 name or address, optionally a colon (':') followed by a port number, then
198 a relative URI beginning at the first slash ('/') after the address part.
199 This is generally what proxies receive, but a server supporting HTTP/1.1
200 must accept this form too.
201
202 - a star ('*') : this form is only accepted in association with the OPTIONS
203 method and is not relayable. It is used to inquiry a next hop's
204 capabilities.
205
206 - an address:port combination : 192.168.0.12:80
207 This is used with the CONNECT method, which is used to establish TCP
208 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
209 other protocols too.
210
211In a relative URI, two sub-parts are identified. The part before the question
212mark is called the "path". It is typically the relative path to static objects
213on the server. The part after the question mark is called the "query string".
214It is mostly used with GET requests sent to dynamic scripts and is very
215specific to the language, framework or application in use.
216
217
2181.2.2. The request headers
219--------------------------
220
221The headers start at the second line. They are composed of a name at the
222beginning of the line, immediately followed by a colon (':'). Traditionally,
223an LWS is added after the colon but that's not required. Then come the values.
224Multiple identical headers may be folded into one single line, delimiting the
225values with commas, provided that their order is respected. This is commonly
226encountered in the "Cookie:" field. A header may span over multiple lines if
227the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
228define a total of 3 values for the "Accept:" header.
229
230Contrary to a common mis-conception, header names are not case-sensitive, and
231their values are not either if they refer to other header names (such as the
232"Connection:" header).
233
234The end of the headers is indicated by the first empty line. People often say
235that it's a double line feed, which is not exact, even if a double line feed
236is one valid form of empty line.
237
238Fortunately, HAProxy takes care of all these complex combinations when indexing
239headers, checking values and counting them, so there is no reason to worry
240about the way they could be written, but it is important not to accuse an
241application of being buggy if it does unusual, valid things.
242
243Important note:
244 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
245 in the middle of headers by LWS in order to join multi-line headers. This
246 is necessary for proper analysis and helps less capable HTTP parsers to work
247 correctly and not to be fooled by such complex constructs.
248
249
2501.3. HTTP response
251------------------
252
253An HTTP response looks very much like an HTTP request. Both are called HTTP
254messages. Let's consider this HTTP response :
255
256 Line Contents
257 number
258 1 HTTP/1.1 200 OK
259 2 Content-length: 350
260 3 Content-Type: text/html
261
Willy Tarreau816b9792009-09-15 21:25:21 +0200262As a special case, HTTP supports so called "Informational responses" as status
263codes 1xx. These messages are special in that they don't convey any part of the
264response, they're just used as sort of a signaling message to ask a client to
265continue to post its request for instance. The requested information will be
266carried by the next non-1xx response message following the informational one.
267This implies that multiple responses may be sent to a single request, and that
268this only works when keep-alive is enabled (1xx messages are HTTP/1.1 only).
269HAProxy handles these messages and is able to correctly forward and skip them,
270and only process the next non-1xx response. As such, these messages are neither
271logged nor transformed, unless explicitly state otherwise.
272
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200273
2741.3.1. The Response line
275------------------------
276
277Line 1 is the "response line". It is always composed of 3 fields :
278
279 - a version tag : HTTP/1.1
280 - a status code : 200
281 - a reason : OK
282
283The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200284 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200285 - 2xx = OK, content is following (eg: 200, 206)
286 - 3xx = OK, no content following (eg: 302, 304)
287 - 4xx = error caused by the client (eg: 401, 403, 404)
288 - 5xx = error caused by the server (eg: 500, 502, 503)
289
290Please refer to RFC2616 for the detailed meaning of all such codes. The
291"reason" field is just a hint, but is not parsed by clients. Anything can be
292found there, but it's a common practice to respect the well-established
293messages. It can be composed of one or multiple words, such as "OK", "Found",
294or "Authentication Required".
295
296Haproxy may emit the following status codes by itself :
297
298 Code When / reason
299 200 access to stats page, and when replying to monitoring requests
300 301 when performing a redirection, depending on the configured code
301 302 when performing a redirection, depending on the configured code
302 303 when performing a redirection, depending on the configured code
303 400 for an invalid or too large request
304 401 when an authentication is required to perform the action (when
305 accessing the stats page)
306 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
307 408 when the request timeout strikes before the request is complete
308 500 when haproxy encounters an unrecoverable internal error, such as a
309 memory allocation failure, which should never happen
310 502 when the server returns an empty, invalid or incomplete response, or
311 when an "rspdeny" filter blocks the response.
312 503 when no server was available to handle the request, or in response to
313 monitoring requests which match the "monitor fail" condition
314 504 when the response timeout strikes before the server responds
315
316The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3174.2).
318
319
3201.3.2. The response headers
321---------------------------
322
323Response headers work exactly like request headers, and as such, HAProxy uses
324the same parsing function for both. Please refer to paragraph 1.2.2 for more
325details.
326
327
3282. Configuring HAProxy
329----------------------
330
3312.1. Configuration file format
332------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200333
334HAProxy's configuration process involves 3 major sources of parameters :
335
336 - the arguments from the command-line, which always take precedence
337 - the "global" section, which sets process-wide parameters
338 - the proxies sections which can take form of "defaults", "listen",
339 "frontend" and "backend".
340
Willy Tarreau0ba27502007-12-24 16:55:16 +0100341The configuration file syntax consists in lines beginning with a keyword
342referenced in this manual, optionally followed by one or several parameters
343delimited by spaces. If spaces have to be entered in strings, then they must be
344preceeded by a backslash ('\') to be escaped. Backslashes also have to be
345escaped by doubling them.
346
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200347
3482.2. Time format
349----------------
350
Willy Tarreau0ba27502007-12-24 16:55:16 +0100351Some parameters involve values representating time, such as timeouts. These
352values are generally expressed in milliseconds (unless explicitly stated
353otherwise) but may be expressed in any other unit by suffixing the unit to the
354numeric value. It is important to consider this because it will not be repeated
355for every keyword. Supported units are :
356
357 - us : microseconds. 1 microsecond = 1/1000000 second
358 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
359 - s : seconds. 1s = 1000ms
360 - m : minutes. 1m = 60s = 60000ms
361 - h : hours. 1h = 60m = 3600s = 3600000ms
362 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
363
364
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003653. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200366--------------------
367
368Parameters in the "global" section are process-wide and often OS-specific. They
369are generally set once for all and do not need being changed once correct. Some
370of them have command-line equivalents.
371
372The following keywords are supported in the "global" section :
373
374 * Process management and security
375 - chroot
376 - daemon
377 - gid
378 - group
379 - log
380 - nbproc
381 - pidfile
382 - uid
383 - ulimit-n
384 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200385 - stats
Willy Tarreau6a06a402007-07-15 20:15:28 +0200386
387 * Performance tuning
388 - maxconn
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100389 - maxpipes
Willy Tarreau6a06a402007-07-15 20:15:28 +0200390 - noepoll
391 - nokqueue
392 - nopoll
393 - nosepoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100394 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200395 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200396 - tune.bufsize
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100397 - tune.maxaccept
398 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200399 - tune.maxrewrite
Willy Tarreau6a06a402007-07-15 20:15:28 +0200400
401 * Debugging
402 - debug
403 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200404
405
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004063.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200407------------------------------------
408
409chroot <jail dir>
410 Changes current directory to <jail dir> and performs a chroot() there before
411 dropping privileges. This increases the security level in case an unknown
412 vulnerability would be exploited, since it would make it very hard for the
413 attacker to exploit the system. This only works when the process is started
414 with superuser privileges. It is important to ensure that <jail_dir> is both
415 empty and unwritable to anyone.
416
417daemon
418 Makes the process fork into background. This is the recommended mode of
419 operation. It is equivalent to the command line "-D" argument. It can be
420 disabled by the command line "-db" argument.
421
422gid <number>
423 Changes the process' group ID to <number>. It is recommended that the group
424 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
425 be started with a user belonging to this group, or with superuser privileges.
426 See also "group" and "uid".
427
428group <group name>
429 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
430 See also "gid" and "user".
431
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200432log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200433 Adds a global syslog server. Up to two global servers can be defined. They
434 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100435 configured with "log global".
436
437 <address> can be one of:
438
Willy Tarreau2769aa02007-12-27 18:26:09 +0100439 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100440 no port is specified, 514 is used by default (the standard syslog
441 port).
442
443 - A filesystem path to a UNIX domain socket, keeping in mind
444 considerations for chroot (be sure the path is accessible inside
445 the chroot) and uid/gid (be sure the path is appropriately
446 writeable).
447
448 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200449
450 kern user mail daemon auth syslog lpr news
451 uucp cron auth2 ftp ntp audit alert cron2
452 local0 local1 local2 local3 local4 local5 local6 local7
453
454 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200455 all messages are sent. If a maximum level is specified, only messages with a
456 severity at least as important as this level will be sent. An optional minimum
457 level can be specified. If it is set, logs emitted with a more severe level
458 than this one will be capped to this level. This is used to avoid sending
459 "emerg" messages on all terminals on some default syslog configurations.
460 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200461
462 emerg alert crit err warning notice info debug
463
464nbproc <number>
465 Creates <number> processes when going daemon. This requires the "daemon"
466 mode. By default, only one process is created, which is the recommended mode
467 of operation. For systems limited to small sets of file descriptors per
468 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
469 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
470
471pidfile <pidfile>
472 Writes pids of all daemons into file <pidfile>. This option is equivalent to
473 the "-p" command line argument. The file must be accessible to the user
474 starting the process. See also "daemon".
475
Willy Tarreaufbee7132007-10-18 13:53:22 +0200476stats socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>]
477 Creates a UNIX socket in stream mode at location <path>. Any previously
478 existing socket will be backed up then replaced. Connections to this socket
479 will get a CSV-formated output of the process statistics in response to the
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +0100480 "show stat" command followed by a line feed, more general process information
481 in response to the "show info" command followed by a line feed, and a
482 complete list of all existing sessions in response to the "show sess" command
483 followed by a line feed.
Willy Tarreaua8efd362008-01-03 10:19:15 +0100484
485 On platforms which support it, it is possible to restrict access to this
486 socket by specifying numerical IDs after "uid" and "gid", or valid user and
487 group names after the "user" and "group" keywords. It is also possible to
488 restrict permissions on the socket by passing an octal value after the "mode"
489 keyword (same syntax as chmod). Depending on the platform, the permissions on
490 the socket will be inherited from the directory which hosts it, or from the
491 user the process is started with.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200492
493stats timeout <timeout, in milliseconds>
494 The default timeout on the stats socket is set to 10 seconds. It is possible
495 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100496 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200497
498stats maxconn <connections>
499 By default, the stats socket is limited to 10 concurrent connections. It is
500 possible to change this value with "stats maxconn".
501
Willy Tarreau6a06a402007-07-15 20:15:28 +0200502uid <number>
503 Changes the process' user ID to <number>. It is recommended that the user ID
504 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
505 be started with superuser privileges in order to be able to switch to another
506 one. See also "gid" and "user".
507
508ulimit-n <number>
509 Sets the maximum number of per-process file-descriptors to <number>. By
510 default, it is automatically computed, so it is recommended not to use this
511 option.
512
513user <user name>
514 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
515 See also "uid" and "group".
516
517
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005183.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200519-----------------------
520
521maxconn <number>
522 Sets the maximum per-process number of concurrent connections to <number>. It
523 is equivalent to the command-line argument "-n". Proxies will stop accepting
524 connections when this limit is reached. The "ulimit-n" parameter is
525 automatically adjusted according to this value. See also "ulimit-n".
526
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100527maxpipes <number>
528 Sets the maximum per-process number of pipes to <number>. Currently, pipes
529 are only used by kernel-based tcp splicing. Since a pipe contains two file
530 descriptors, the "ulimit-n" value will be increased accordingly. The default
531 value is maxconn/4, which seems to be more than enough for most heavy usages.
532 The splice code dynamically allocates and releases pipes, and can fall back
533 to standard copy, so setting this value too low may only impact performance.
534
Willy Tarreau6a06a402007-07-15 20:15:28 +0200535noepoll
536 Disables the use of the "epoll" event polling system on Linux. It is
537 equivalent to the command-line argument "-de". The next polling system
538 used will generally be "poll". See also "nosepoll", and "nopoll".
539
540nokqueue
541 Disables the use of the "kqueue" event polling system on BSD. It is
542 equivalent to the command-line argument "-dk". The next polling system
543 used will generally be "poll". See also "nopoll".
544
545nopoll
546 Disables the use of the "poll" event polling system. It is equivalent to the
547 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100548 It should never be needed to disable "poll" since it's available on all
Willy Tarreau6a06a402007-07-15 20:15:28 +0200549 platforms supported by HAProxy. See also "nosepoll", and "nopoll" and
550 "nokqueue".
551
552nosepoll
553 Disables the use of the "speculative epoll" event polling system on Linux. It
554 is equivalent to the command-line argument "-ds". The next polling system
555 used will generally be "epoll". See also "nosepoll", and "nopoll".
556
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100557nosplice
558 Disables the use of kernel tcp splicing between sockets on Linux. It is
559 equivalent to the command line argument "-dS". Data will then be copied
560 using conventional and more portable recv/send calls. Kernel tcp splicing is
561 limited to some very recent instances of kernel 2.6. Most verstions between
562 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
563 be used. This option makes it easier to globally disable kernel splicing in
564 case of doubt. See also "option splice-auto", "option splice-request" and
565 "option splice-response".
566
Willy Tarreaufe255b72007-10-14 23:09:26 +0200567spread-checks <0..50, in percent>
568 Sometimes it is desirable to avoid sending health checks to servers at exact
569 intervals, for instance when many logical servers are located on the same
570 physical server. With the help of this parameter, it becomes possible to add
571 some randomness in the check interval between 0 and +/- 50%. A value between
572 2 and 5 seems to show good results. The default value remains at 0.
573
Willy Tarreau27a674e2009-08-17 07:23:33 +0200574tune.bufsize <number>
575 Sets the buffer size to this size (in bytes). Lower values allow more
576 sessions to coexist in the same amount of RAM, and higher values allow some
577 applications with very large cookies to work. The default value is 16384 and
578 can be changed at build time. It is strongly recommended not to change this
579 from the default value, as very low values will break some services such as
580 statistics, and values larger than default size will increase memory usage,
581 possibly causing the system to run out of memory. At least the global maxconn
582 parameter should be decreased by the same factor as this one is increased.
583
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100584tune.maxaccept <number>
585 Sets the maximum number of consecutive accepts that a process may perform on
586 a single wake up. High values give higher priority to high connection rates,
587 while lower values give higher priority to already established connections.
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100588 This value is limited to 100 by default in single process mode. However, in
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100589 multi-process mode (nbproc > 1), it defaults to 8 so that when one process
590 wakes up, it does not take all incoming connections for itself and leaves a
Willy Tarreauf49d1df2009-03-01 08:35:41 +0100591 part of them to other processes. Setting this value to -1 completely disables
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100592 the limitation. It should normally not be needed to tweak this value.
593
594tune.maxpollevents <number>
595 Sets the maximum amount of events that can be processed at once in a call to
596 the polling system. The default value is adapted to the operating system. It
597 has been noticed that reducing it below 200 tends to slightly decrease
598 latency at the expense of network bandwidth, and increasing it above 200
599 tends to trade latency for slightly increased bandwidth.
600
Willy Tarreau27a674e2009-08-17 07:23:33 +0200601tune.maxrewrite <number>
602 Sets the reserved buffer space to this size in bytes. The reserved space is
603 used for header rewriting or appending. The first reads on sockets will never
604 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
605 bufsize, though that does not make much sense since there are rarely large
606 numbers of headers to add. Setting it too high prevents processing of large
607 requests or responses. Setting it too low prevents addition of new headers
608 to already large requests or to POST requests. It is generally wise to set it
609 to about 1024. It is automatically readjusted to half of bufsize if it is
610 larger than that. This means you don't have to worry about it when changing
611 bufsize.
612
Willy Tarreau6a06a402007-07-15 20:15:28 +0200613
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006143.3. Debugging
615--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200616
617debug
618 Enables debug mode which dumps to stdout all exchanges, and disables forking
619 into background. It is the equivalent of the command-line argument "-d". It
620 should never be used in a production configuration since it may prevent full
621 system startup.
622
623quiet
624 Do not display any message during startup. It is equivalent to the command-
625 line argument "-q".
626
Willy Tarreau6a06a402007-07-15 20:15:28 +0200627
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006284. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +0200629----------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100630
Willy Tarreau6a06a402007-07-15 20:15:28 +0200631Proxy configuration can be located in a set of sections :
632 - defaults <name>
633 - frontend <name>
634 - backend <name>
635 - listen <name>
636
637A "defaults" section sets default parameters for all other sections following
638its declaration. Those default parameters are reset by the next "defaults"
639section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +0100640section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200641
642A "frontend" section describes a set of listening sockets accepting client
643connections.
644
645A "backend" section describes a set of servers to which the proxy will connect
646to forward incoming connections.
647
648A "listen" section defines a complete proxy with its frontend and backend
649parts combined in one section. It is generally useful for TCP-only traffic.
650
Willy Tarreau0ba27502007-12-24 16:55:16 +0100651All proxy names must be formed from upper and lower case letters, digits,
652'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
653case-sensitive, which means that "www" and "WWW" are two different proxies.
654
655Historically, all proxy names could overlap, it just caused troubles in the
656logs. Since the introduction of content switching, it is mandatory that two
657proxies with overlapping capabilities (frontend/backend) have different names.
658However, it is still permitted that a frontend and a backend share the same
659name, as this configuration seems to be commonly encountered.
660
661Right now, two major proxy modes are supported : "tcp", also known as layer 4,
662and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
663bidirectionnal traffic between two sides. In layer 7 mode, HAProxy analyzes the
664protocol, and can interact with it by allowing, blocking, switching, adding,
665modifying, or removing arbitrary contents in requests or responses, based on
666arbitrary criteria.
667
Willy Tarreau0ba27502007-12-24 16:55:16 +0100668
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006694.1. Proxy keywords matrix
670--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100671
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200672The following list of keywords is supported. Most of them may only be used in a
673limited set of section types. Some of them are marked as "deprecated" because
674they are inherited from an old syntax which may be confusing or functionally
675limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau3842f002009-06-14 11:39:52 +0200676listed with [no] can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200677option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +0200678and must be disabled for a specific instance. Such options may also be prefixed
679with "default" in order to restore default settings regardless of what has been
680specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100681
Willy Tarreau6a06a402007-07-15 20:15:28 +0200682
683keyword defaults frontend listen backend
684----------------------+----------+----------+---------+---------
685acl - X X X
686appsession - - X X
Willy Tarreauc73ce2b2008-01-06 10:55:10 +0100687backlog X X X -
Willy Tarreau0ba27502007-12-24 16:55:16 +0100688balance X - X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200689bind - X X -
Willy Tarreau0b9c02c2009-02-04 22:05:05 +0100690bind-process X X X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200691block - X X X
Willy Tarreau0ba27502007-12-24 16:55:16 +0100692capture cookie - X X -
693capture request header - X X -
694capture response header - X X -
Willy Tarreaue219db72007-12-03 01:30:13 +0100695clitimeout X X X - (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +0100696contimeout X - X X (deprecated)
Willy Tarreau6a06a402007-07-15 20:15:28 +0200697cookie X - X X
698default_backend - X X -
Willy Tarreau0ba27502007-12-24 16:55:16 +0100699disabled X X X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200700dispatch - - X X
Willy Tarreau0ba27502007-12-24 16:55:16 +0100701enabled X X X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200702errorfile X X X X
703errorloc X X X X
704errorloc302 X X X X
705errorloc303 X X X X
706fullconn X - X X
707grace - X X X
Willy Tarreaudbc36f62007-11-30 12:29:11 +0100708http-check disable-on-404 X - X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200709log X X X X
710maxconn X X X -
711mode X X X X
Willy Tarreauc7246fc2007-12-02 17:31:20 +0100712monitor fail - X X -
Willy Tarreau6a06a402007-07-15 20:15:28 +0200713monitor-net X X X -
714monitor-uri X X X -
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100715[no] option abortonclose X - X X
Willy Tarreau4076a152009-04-02 15:18:36 +0200716[no] option accept-invalid-
717 http-request X X X -
718[no] option accept-invalid-
719 http-response X - X X
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100720[no] option allbackups X - X X
721[no] option checkcache X - X X
722[no] option clitcpka X X X -
723[no] option contstats X X X -
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +0200724[no] option dontlog-normal X X X -
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100725[no] option dontlognull X X X -
726[no] option forceclose X - X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200727option forwardfor X X X X
728option httpchk X - X X
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100729[no] option httpclose X X X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200730option httplog X X X X
Willy Tarreau55165fe2009-05-10 12:02:55 +0200731[no] option http_proxy X X X X
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +0200732[no] option log-separate-
733 errors X X X -
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100734[no] option logasap X X X -
735[no] option nolinger X X X X
Willy Tarreau55165fe2009-05-10 12:02:55 +0200736option originalto X X X X
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100737[no] option persist X - X X
738[no] option redispatch X - X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200739option smtpchk X - X X
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100740[no] option splice-auto X X X X
741[no] option splice-request X X X X
742[no] option splice-response X X X X
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100743[no] option srvtcpka X - X X
Willy Tarreau6a06a402007-07-15 20:15:28 +0200744option ssl-hello-chk X - X X
Willy Tarreau9ea05a72009-06-14 12:07:01 +0200745[no] option tcp-smart-
746 accept X X X -
Willy Tarreau6a06a402007-07-15 20:15:28 +0200747option tcpka X X X X
748option tcplog X X X X
Willy Tarreau4b1f8592008-12-23 23:13:55 +0100749[no] option transparent X - X X
Emeric Brun647caf12009-06-30 17:57:00 +0200750persist rdp-cookie X - X X
Willy Tarreau3a7d2072009-03-05 23:48:25 +0100751rate-limit sessions X X X -
Willy Tarreaub463dfb2008-06-07 23:08:56 +0200752redirect - X X X
Krzysztof Oledzki336d4752007-12-25 02:40:22 +0100753redisp X - X X (deprecated)
754redispatch X - X X (deprecated)
Willy Tarreau6a06a402007-07-15 20:15:28 +0200755reqadd - X X X
756reqallow - X X X
757reqdel - X X X
758reqdeny - X X X
759reqiallow - X X X
760reqidel - X X X
761reqideny - X X X
762reqipass - X X X
763reqirep - X X X
764reqisetbe - X X X
765reqitarpit - X X X
766reqpass - X X X
767reqrep - X X X
768reqsetbe - X X X
769reqtarpit - X X X
770retries X - X X
771rspadd - X X X
772rspdel - X X X
773rspdeny - X X X
774rspidel - X X X
775rspideny - X X X
776rspirep - X X X
777rsprep - X X X
778server - - X X
779source X - X X
Willy Tarreaue219db72007-12-03 01:30:13 +0100780srvtimeout X - X X (deprecated)
Willy Tarreau24e779b2007-07-24 23:43:37 +0200781stats auth X - X X
782stats enable X - X X
783stats realm X - X X
Willy Tarreaubbd42122007-07-25 07:26:38 +0200784stats refresh X - X X
Willy Tarreau24e779b2007-07-24 23:43:37 +0200785stats scope X - X X
786stats uri X - X X
Krzysztof Oledzkid9db9272007-10-15 10:05:11 +0200787stats hide-version X - X X
Willy Tarreau62644772008-07-16 18:36:06 +0200788tcp-request content accept - X X -
789tcp-request content reject - X X -
790tcp-request inspect-delay - X X -
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +0100791timeout check X - X X
Willy Tarreaue219db72007-12-03 01:30:13 +0100792timeout client X X X -
793timeout clitimeout X X X - (deprecated)
794timeout connect X - X X
795timeout contimeout X - X X (deprecated)
Willy Tarreaucd7afc02009-07-12 10:03:17 +0200796timeout http-request X X X X
Willy Tarreaue219db72007-12-03 01:30:13 +0100797timeout queue X - X X
798timeout server X - X X
799timeout srvtimeout X - X X (deprecated)
Willy Tarreau51c9bde2008-01-06 13:40:03 +0100800timeout tarpit X X X X
Willy Tarreau4b1f8592008-12-23 23:13:55 +0100801transparent X - X X (deprecated)
Willy Tarreau6a06a402007-07-15 20:15:28 +0200802use_backend - X X -
Willy Tarreau6a06a402007-07-15 20:15:28 +0200803----------------------+----------+----------+---------+---------
804keyword defaults frontend listen backend
805
Willy Tarreau0ba27502007-12-24 16:55:16 +0100806
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008074.2. Alphabetically sorted keywords reference
808---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100809
810This section provides a description of each keyword and its usage.
811
812
813acl <aclname> <criterion> [flags] [operator] <value> ...
814 Declare or complete an access list.
815 May be used in sections : defaults | frontend | listen | backend
816 no | yes | yes | yes
817 Example:
818 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
819 acl invalid_src src_port 0:1023
820 acl local_dst hdr(host) -i localhost
821
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200822 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100823
824
825appsession <cookie> len <length> timeout <holdtime>
826 Define session stickiness on an existing application cookie.
827 May be used in sections : defaults | frontend | listen | backend
828 no | no | yes | yes
829 Arguments :
830 <cookie> this is the name of the cookie used by the application and which
831 HAProxy will have to learn for each new session.
832
833 <length> this is the number of characters that will be memorized and
834 checked in each cookie value.
835
836 <holdtime> this is the time after which the cookie will be removed from
837 memory if unused. If no unit is specified, this time is in
838 milliseconds.
839
840 When an application cookie is defined in a backend, HAProxy will check when
841 the server sets such a cookie, and will store its value in a table, and
842 associate it with the server's identifier. Up to <length> characters from
843 the value will be retained. On each connection, haproxy will look for this
844 cookie both in the "Cookie:" headers, and as a URL parameter in the query
845 string. If a known value is found, the client will be directed to the server
846 associated with this value. Otherwise, the load balancing algorithm is
847 applied. Cookies are automatically removed from memory when they have been
848 unused for a duration longer than <holdtime>.
849
850 The definition of an application cookie is limited to one per backend.
851
852 Example :
853 appsession JSESSIONID len 52 timeout 3h
854
855 See also : "cookie", "capture cookie" and "balance".
856
857
Willy Tarreauc73ce2b2008-01-06 10:55:10 +0100858backlog <conns>
859 Give hints to the system about the approximate listen backlog desired size
860 May be used in sections : defaults | frontend | listen | backend
861 yes | yes | yes | no
862 Arguments :
863 <conns> is the number of pending connections. Depending on the operating
864 system, it may represent the number of already acknowledged
865 connections, of non-acknowledged ones, or both.
866
867 In order to protect against SYN flood attacks, one solution is to increase
868 the system's SYN backlog size. Depending on the system, sometimes it is just
869 tunable via a system parameter, sometimes it is not adjustable at all, and
870 sometimes the system relies on hints given by the application at the time of
871 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
872 to the listen() syscall. On systems which can make use of this value, it can
873 sometimes be useful to be able to specify a different value, hence this
874 backlog parameter.
875
876 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
877 used as a hint and the system accepts up to the smallest greater power of
878 two, and never more than some limits (usually 32768).
879
880 See also : "maxconn" and the target operating system's tuning guide.
881
882
Willy Tarreau0ba27502007-12-24 16:55:16 +0100883balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +0200884balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +0100885 Define the load balancing algorithm to be used in a backend.
886 May be used in sections : defaults | frontend | listen | backend
887 yes | no | yes | yes
888 Arguments :
889 <algorithm> is the algorithm used to select a server when doing load
890 balancing. This only applies when no persistence information
891 is available, or when a connection is redispatched to another
892 server. <algorithm> may be one of the following :
893
894 roundrobin Each server is used in turns, according to their weights.
895 This is the smoothest and fairest algorithm when the server's
896 processing time remains equally distributed. This algorithm
897 is dynamic, which means that server weights may be adjusted
898 on the fly for slow starts for instance.
899
Willy Tarreau2d2a7f82008-03-17 12:07:56 +0100900 leastconn The server with the lowest number of connections receives the
901 connection. Round-robin is performed within groups of servers
902 of the same load to ensure that all servers will be used. Use
903 of this algorithm is recommended where very long sessions are
904 expected, such as LDAP, SQL, TSE, etc... but is not very well
905 suited for protocols using short sessions such as HTTP. This
906 algorithm is dynamic, which means that server weights may be
907 adjusted on the fly for slow starts for instance.
908
Willy Tarreau0ba27502007-12-24 16:55:16 +0100909 source The source IP address is hashed and divided by the total
910 weight of the running servers to designate which server will
911 receive the request. This ensures that the same client IP
912 address will always reach the same server as long as no
913 server goes down or up. If the hash result changes due to the
914 number of running servers changing, many clients will be
915 directed to a different server. This algorithm is generally
916 used in TCP mode where no cookie may be inserted. It may also
917 be used on the Internet to provide a best-effort stickyness
918 to clients which refuse session cookies. This algorithm is
919 static, which means that changing a server's weight on the
920 fly will have no effect.
921
922 uri The left part of the URI (before the question mark) is hashed
923 and divided by the total weight of the running servers. The
924 result designates which server will receive the request. This
925 ensures that a same URI will always be directed to the same
926 server as long as no server goes up or down. This is used
927 with proxy caches and anti-virus proxies in order to maximize
928 the cache hit rate. Note that this algorithm may only be used
929 in an HTTP backend. This algorithm is static, which means
930 that changing a server's weight on the fly will have no
931 effect.
932
Marek Majkowski9c30fc12008-04-27 23:25:55 +0200933 This algorithm support two optional parameters "len" and
934 "depth", both followed by a positive integer number. These
935 options may be helpful when it is needed to balance servers
936 based on the beginning of the URI only. The "len" parameter
937 indicates that the algorithm should only consider that many
938 characters at the beginning of the URI to compute the hash.
939 Note that having "len" set to 1 rarely makes sense since most
940 URIs start with a leading "/".
941
942 The "depth" parameter indicates the maximum directory depth
943 to be used to compute the hash. One level is counted for each
944 slash in the request. If both parameters are specified, the
945 evaluation stops when either is reached.
946
Willy Tarreau0ba27502007-12-24 16:55:16 +0100947 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +0200948 the query string of each HTTP GET request.
949
950 If the modifier "check_post" is used, then an HTTP POST
951 request entity will be searched for the parameter argument,
952 when the question mark indicating a query string ('?') is not
953 present in the URL. Optionally, specify a number of octets to
954 wait for before attempting to search the message body. If the
955 entity can not be searched, then round robin is used for each
956 request. For instance, if your clients always send the LB
957 parameter in the first 128 bytes, then specify that. The
958 default is 48. The entity data will not be scanned until the
959 required number of octets have arrived at the gateway, this
960 is the minimum of: (default/max_wait, Content-Length or first
961 chunk length). If Content-Length is missing or zero, it does
962 not need to wait for more data than the client promised to
963 send. When Content-Length is present and larger than
964 <max_wait>, then waiting is limited to <max_wait> and it is
965 assumed that this will be enough data to search for the
966 presence of the parameter. In the unlikely event that
967 Transfer-Encoding: chunked is used, only the first chunk is
968 scanned. Parameter values separated by a chunk boundary, may
969 be randomly balanced if at all.
970
971 If the parameter is found followed by an equal sign ('=') and
972 a value, then the value is hashed and divided by the total
973 weight of the running servers. The result designates which
974 server will receive the request.
975
976 This is used to track user identifiers in requests and ensure
977 that a same user ID will always be sent to the same server as
978 long as no server goes up or down. If no value is found or if
979 the parameter is not found, then a round robin algorithm is
980 applied. Note that this algorithm may only be used in an HTTP
981 backend. This algorithm is static, which means that changing a
982 server's weight on the fly will have no effect.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100983
Benoitaffb4812009-03-25 13:02:10 +0100984 hdr(name) The HTTP header <name> will be looked up in each HTTP request.
985 Just as with the equivalent ACL 'hdr()' function, the header
986 name in parenthesis is not case sensitive. If the header is
987 absent or if it does not contain any value, the round-robin
988 algorithm is applied instead.
989
990 An optionnal 'use_domain_only' parameter is available, for
991 reducing the hash algorithm to the main domain part with some
992 specific headers such as 'Host'. For instance, in the Host
993 value "haproxy.1wt.eu", only "1wt" will be considered.
994
Emeric Brun736aa232009-06-30 17:56:00 +0200995 rdp-cookie
996 rdp-cookie(name)
997 The RDP cookie <name> (or "mstshash" if omitted) will be
998 looked up and hashed for each incoming TCP request. Just as
999 with the equivalent ACL 'req_rdp_cookie()' function, the name
1000 is not case-sensitive. This mechanism is useful as a degraded
1001 persistence mode, as it makes it possible to always send the
1002 same user (or the same session ID) to the same server. If the
1003 cookie is not found, the normal round-robind algorithm is
1004 used instead.
1005
1006 Note that for this to work, the frontend must ensure that an
1007 RDP cookie is already present in the request buffer. For this
1008 you must use 'tcp-request content accept' rule combined with
1009 a 'req_rdp_cookie_cnt' ACL.
1010
Willy Tarreau0ba27502007-12-24 16:55:16 +01001011 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001012 algorithms. Right now, only "url_param" and "uri" support an
1013 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001014
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001015 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001016 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001017
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001018 The load balancing algorithm of a backend is set to roundrobin when no other
1019 algorithm, mode nor option have been set. The algorithm may only be set once
1020 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001021
1022 Examples :
1023 balance roundrobin
1024 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001025 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001026 balance hdr(User-Agent)
1027 balance hdr(host)
1028 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001029
1030 Note: the following caveats and limitations on using the "check_post"
1031 extension with "url_param" must be considered :
1032
1033 - all POST requests are eligable for consideration, because there is no way
1034 to determine if the parameters will be found in the body or entity which
1035 may contain binary data. Therefore another method may be required to
1036 restrict consideration of POST requests that have no URL parameters in
1037 the body. (see acl reqideny http_end)
1038
1039 - using a <max_wait> value larger than the request buffer size does not
1040 make sense and is useless. The buffer size is set at build time, and
1041 defaults to 16 kB.
1042
1043 - Content-Encoding is not supported, the parameter search will probably
1044 fail; and load balancing will fall back to Round Robin.
1045
1046 - Expect: 100-continue is not supported, load balancing will fall back to
1047 Round Robin.
1048
1049 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1050 If the entire parameter value is not present in the first chunk, the
1051 selection of server is undefined (actually, defined by how little
1052 actually appeared in the first chunk).
1053
1054 - This feature does not support generation of a 100, 411 or 501 response.
1055
1056 - In some cases, requesting "check_post" MAY attempt to scan the entire
1057 contents of a message body. Scaning normally terminates when linear
1058 white space or control characters are found, indicating the end of what
1059 might be a URL parameter list. This is probably not a concern with SGML
1060 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001061
1062 See also : "dispatch", "cookie", "appsession", "transparent" and "http_proxy".
1063
1064
1065bind [<address>]:<port> [, ...]
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001066bind [<address>]:<port> [, ...] interface <interface>
Willy Tarreaube1b9182009-06-14 18:48:19 +02001067bind [<address>]:<port> [, ...] mss <maxseg>
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001068bind [<address>]:<port> [, ...] transparent
Willy Tarreau0ba27502007-12-24 16:55:16 +01001069 Define one or several listening addresses and/or ports in a frontend.
1070 May be used in sections : defaults | frontend | listen | backend
1071 no | yes | yes | no
1072 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001073 <address> is optional and can be a host name, an IPv4 address, an IPv6
1074 address, or '*'. It designates the address the frontend will
1075 listen on. If unset, all IPv4 addresses of the system will be
1076 listened on. The same will apply for '*' or the system's
1077 special address "0.0.0.0".
1078
1079 <port> is the TCP port number the proxy will listen on. The port is
1080 mandatory. Note that in the case of an IPv6 address, the port
1081 is always the number after the last colon (':').
Willy Tarreau0ba27502007-12-24 16:55:16 +01001082
Willy Tarreau5e6e2042009-02-04 17:19:29 +01001083 <interface> is an optional physical interface name. This is currently
1084 only supported on Linux. The interface must be a physical
1085 interface, not an aliased interface. When specified, all
1086 addresses on the same line will only be accepted if the
1087 incoming packet physically come through the designated
1088 interface. It is also possible to bind multiple frontends to
1089 the same address if they are bound to different interfaces.
1090 Note that binding to a physical interface requires root
1091 privileges.
1092
Willy Tarreaube1b9182009-06-14 18:48:19 +02001093 <maxseg> is an optional TCP Maximum Segment Size (MSS) value to be
1094 advertised on incoming connections. This can be used to force
1095 a lower MSS for certain specific ports, for instance for
1096 connections passing through a VPN. Note that this relies on a
1097 kernel feature which is theorically supported under Linux but
1098 was buggy in all versions prior to 2.6.28. It may or may not
1099 work on other operating systems. The commonly advertised
1100 value on Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP).
1101
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001102 transparent is an optional keyword which is supported only on certain
1103 Linux kernels. It indicates that the addresses will be bound
1104 even if they do not belong to the local machine. Any packet
1105 targetting any of these addresses will be caught just as if
1106 the address was locally configured. This normally requires
1107 that IP forwarding is enabled. Caution! do not use this with
1108 the default address '*', as it would redirect any traffic for
1109 the specified port. This keyword is available only when
1110 HAProxy is built with USE_LINUX_TPROXY=1.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001111
1112 It is possible to specify a list of address:port combinations delimited by
1113 commas. The frontend will then listen on all of these addresses. There is no
1114 fixed limit to the number of addresses and ports which can be listened on in
1115 a frontend, as well as there is no limit to the number of "bind" statements
1116 in a frontend.
1117
1118 Example :
1119 listen http_proxy
1120 bind :80,:443
1121 bind 10.0.0.1:10080,10.0.0.1:10443
1122
1123 See also : "source".
1124
1125
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001126bind-process [ all | odd | even | <number 1-32> ] ...
1127 Limit visibility of an instance to a certain set of processes numbers.
1128 May be used in sections : defaults | frontend | listen | backend
1129 yes | yes | yes | yes
1130 Arguments :
1131 all All process will see this instance. This is the default. It
1132 may be used to override a default value.
1133
1134 odd This instance will be enabled on processes 1,3,5,...31. This
1135 option may be combined with other numbers.
1136
1137 even This instance will be enabled on processes 2,4,6,...32. This
1138 option may be combined with other numbers. Do not use it
1139 with less than 2 processes otherwise some instances might be
1140 missing from all processes.
1141
1142 number The instance will be enabled on this process number, between
1143 1 and 32. You must be careful not to reference a process
1144 number greater than the configured global.nbproc, otherwise
1145 some instances might be missing from all processes.
1146
1147 This keyword limits binding of certain instances to certain processes. This
1148 is useful in order not to have too many processes listening to the same
1149 ports. For instance, on a dual-core machine, it might make sense to set
1150 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1151 and 'even' instances.
1152
1153 At the moment, it is not possible to reference more than 32 processes using
1154 this keyword, but this should be more than enough for most setups. Please
1155 note that 'all' really means all processes and is not limited to the first
1156 32.
1157
1158 If some backends are referenced by frontends bound to other processes, the
1159 backend automatically inherits the frontend's processes.
1160
1161 Example :
1162 listen app_ip1
1163 bind 10.0.0.1:80
1164 bind_process odd
1165
1166 listen app_ip2
1167 bind 10.0.0.2:80
1168 bind_process even
1169
1170 listen management
1171 bind 10.0.0.3:80
1172 bind_process 1 2 3 4
1173
1174 See also : "nbproc" in global section.
1175
1176
Willy Tarreau0ba27502007-12-24 16:55:16 +01001177block { if | unless } <condition>
1178 Block a layer 7 request if/unless a condition is matched
1179 May be used in sections : defaults | frontend | listen | backend
1180 no | yes | yes | yes
1181
1182 The HTTP request will be blocked very early in the layer 7 processing
1183 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001184 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001185 typically used to deny access to certain sensible resources if some
1186 conditions are met or not met. There is no fixed limit to the number of
1187 "block" statements per instance.
1188
1189 Example:
1190 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1191 acl invalid_src src_port 0:1023
1192 acl local_dst hdr(host) -i localhost
1193 block if invalid_src || local_dst
1194
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001195 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001196
1197
1198capture cookie <name> len <length>
1199 Capture and log a cookie in the request and in the response.
1200 May be used in sections : defaults | frontend | listen | backend
1201 no | yes | yes | no
1202 Arguments :
1203 <name> is the beginning of the name of the cookie to capture. In order
1204 to match the exact name, simply suffix the name with an equal
1205 sign ('='). The full name will appear in the logs, which is
1206 useful with application servers which adjust both the cookie name
1207 and value (eg: ASPSESSIONXXXXX).
1208
1209 <length> is the maximum number of characters to report in the logs, which
1210 include the cookie name, the equal sign and the value, all in the
1211 standard "name=value" form. The string will be truncated on the
1212 right if it exceeds <length>.
1213
1214 Only the first cookie is captured. Both the "cookie" request headers and the
1215 "set-cookie" response headers are monitored. This is particularly useful to
1216 check for application bugs causing session crossing or stealing between
1217 users, because generally the user's cookies can only change on a login page.
1218
1219 When the cookie was not presented by the client, the associated log column
1220 will report "-". When a request does not cause a cookie to be assigned by the
1221 server, a "-" is reported in the response column.
1222
1223 The capture is performed in the frontend only because it is necessary that
1224 the log format does not change for a given frontend depending on the
1225 backends. This may change in the future. Note that there can be only one
1226 "capture cookie" statement in a frontend. The maximum capture length is
1227 configured in the souces by default to 64 characters. It is not possible to
1228 specify a capture in a "defaults" section.
1229
1230 Example:
1231 capture cookie ASPSESSION len 32
1232
1233 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001234 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001235
1236
1237capture request header <name> len <length>
1238 Capture and log the first occurrence of the specified request header.
1239 May be used in sections : defaults | frontend | listen | backend
1240 no | yes | yes | no
1241 Arguments :
1242 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001243 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001244 appear in the requests, with the first letter of each word in
1245 upper case. The header name will not appear in the logs, only the
1246 value is reported, but the position in the logs is respected.
1247
1248 <length> is the maximum number of characters to extract from the value and
1249 report in the logs. The string will be truncated on the right if
1250 it exceeds <length>.
1251
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001252 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001253 value will be added to the logs between braces ('{}'). If multiple headers
1254 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001255 in the same order they were declared in the configuration. Non-existent
1256 headers will be logged just as an empty string. Common uses for request
1257 header captures include the "Host" field in virtual hosting environments, the
1258 "Content-length" when uploads are supported, "User-agent" to quickly
1259 differenciate between real users and robots, and "X-Forwarded-For" in proxied
1260 environments to find where the request came from.
1261
1262 Note that when capturing headers such as "User-agent", some spaces may be
1263 logged, making the log analysis more difficult. Thus be careful about what
1264 you log if you know your log parser is not smart enough to rely on the
1265 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001266
1267 There is no limit to the number of captured request headers, but each capture
1268 is limited to 64 characters. In order to keep log format consistent for a
1269 same frontend, header captures can only be declared in a frontend. It is not
1270 possible to specify a capture in a "defaults" section.
1271
1272 Example:
1273 capture request header Host len 15
1274 capture request header X-Forwarded-For len 15
1275 capture request header Referrer len 15
1276
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001277 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001278 about logging.
1279
1280
1281capture response header <name> len <length>
1282 Capture and log the first occurrence of the specified response header.
1283 May be used in sections : defaults | frontend | listen | backend
1284 no | yes | yes | no
1285 Arguments :
1286 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001287 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001288 appear in the response, with the first letter of each word in
1289 upper case. The header name will not appear in the logs, only the
1290 value is reported, but the position in the logs is respected.
1291
1292 <length> is the maximum number of characters to extract from the value and
1293 report in the logs. The string will be truncated on the right if
1294 it exceeds <length>.
1295
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001296 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001297 result will be added to the logs between braces ('{}') after the captured
1298 request headers. If multiple headers are captured, they will be delimited by
1299 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001300 the configuration. Non-existent headers will be logged just as an empty
1301 string. Common uses for response header captures include the "Content-length"
1302 header which indicates how many bytes are expected to be returned, the
1303 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001304
1305 There is no limit to the number of captured response headers, but each
1306 capture is limited to 64 characters. In order to keep log format consistent
1307 for a same frontend, header captures can only be declared in a frontend. It
1308 is not possible to specify a capture in a "defaults" section.
1309
1310 Example:
1311 capture response header Content-length len 9
1312 capture response header Location len 15
1313
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001314 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001315 about logging.
1316
1317
1318clitimeout <timeout>
1319 Set the maximum inactivity time on the client side.
1320 May be used in sections : defaults | frontend | listen | backend
1321 yes | yes | yes | no
1322 Arguments :
1323 <timeout> is the timeout value is specified in milliseconds by default, but
1324 can be in any other unit if the number is suffixed by the unit,
1325 as explained at the top of this document.
1326
1327 The inactivity timeout applies when the client is expected to acknowledge or
1328 send data. In HTTP mode, this timeout is particularly important to consider
1329 during the first phase, when the client sends the request, and during the
1330 response while it is reading data sent by the server. The value is specified
1331 in milliseconds by default, but can be in any other unit if the number is
1332 suffixed by the unit, as specified at the top of this document. In TCP mode
1333 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1334 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001335 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001336 losses by specifying timeouts that are slightly above multiples of 3 seconds
1337 (eg: 4 or 5 seconds).
1338
1339 This parameter is specific to frontends, but can be specified once for all in
1340 "defaults" sections. This is in fact one of the easiest solutions not to
1341 forget about it. An unspecified timeout results in an infinite timeout, which
1342 is not recommended. Such a usage is accepted and works but reports a warning
1343 during startup because it may results in accumulation of expired sessions in
1344 the system if the system's timeouts are not configured either.
1345
1346 This parameter is provided for compatibility but is currently deprecated.
1347 Please use "timeout client" instead.
1348
Willy Tarreau036fae02008-01-06 13:24:40 +01001349 See also : "timeout client", "timeout http-request", "timeout server", and
1350 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001351
1352
1353contimeout <timeout>
1354 Set the maximum time to wait for a connection attempt to a server to succeed.
1355 May be used in sections : defaults | frontend | listen | backend
1356 yes | no | yes | yes
1357 Arguments :
1358 <timeout> is the timeout value is specified in milliseconds by default, but
1359 can be in any other unit if the number is suffixed by the unit,
1360 as explained at the top of this document.
1361
1362 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001363 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreau0ba27502007-12-24 16:55:16 +01001364 cover one or several TCP packet losses by specifying timeouts that are
1365 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
1366 connect timeout also presets the queue timeout to the same value if this one
1367 has not been specified. Historically, the contimeout was also used to set the
1368 tarpit timeout in a listen section, which is not possible in a pure frontend.
1369
1370 This parameter is specific to backends, but can be specified once for all in
1371 "defaults" sections. This is in fact one of the easiest solutions not to
1372 forget about it. An unspecified timeout results in an infinite timeout, which
1373 is not recommended. Such a usage is accepted and works but reports a warning
1374 during startup because it may results in accumulation of failed sessions in
1375 the system if the system's timeouts are not configured either.
1376
1377 This parameter is provided for backwards compatibility but is currently
1378 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
1379 instead.
1380
1381 See also : "timeout connect", "timeout queue", "timeout tarpit",
1382 "timeout server", "contimeout".
1383
1384
Willy Tarreau55165fe2009-05-10 12:02:55 +02001385cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
1386 [ postonly ] [ domain <domain> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001387 Enable cookie-based persistence in a backend.
1388 May be used in sections : defaults | frontend | listen | backend
1389 yes | no | yes | yes
1390 Arguments :
1391 <name> is the name of the cookie which will be monitored, modified or
1392 inserted in order to bring persistence. This cookie is sent to
1393 the client via a "Set-Cookie" header in the response, and is
1394 brought back by the client in a "Cookie" header in all requests.
1395 Special care should be taken to choose a name which does not
1396 conflict with any likely application cookie. Also, if the same
1397 backends are subject to be used by the same clients (eg:
1398 HTTP/HTTPS), care should be taken to use different cookie names
1399 between all backends if persistence between them is not desired.
1400
1401 rewrite This keyword indicates that the cookie will be provided by the
1402 server and that haproxy will have to modify its value to set the
1403 server's identifier in it. This mode is handy when the management
1404 of complex combinations of "Set-cookie" and "Cache-control"
1405 headers is left to the application. The application can then
1406 decide whether or not it is appropriate to emit a persistence
1407 cookie. Since all responses should be monitored, this mode only
1408 works in HTTP close mode. Unless the application behaviour is
1409 very complex and/or broken, it is advised not to start with this
1410 mode for new deployments. This keyword is incompatible with
1411 "insert" and "prefix".
1412
1413 insert This keyword indicates that the persistence cookie will have to
1414 be inserted by haproxy in the responses. If the server emits a
1415 cookie with the same name, it will be replaced anyway. For this
1416 reason, this mode can be used to upgrade existing configurations
1417 running in the "rewrite" mode. The cookie will only be a session
1418 cookie and will not be stored on the client's disk. Due to
1419 caching effects, it is generally wise to add the "indirect" and
1420 "nocache" or "postonly" keywords (see below). The "insert"
1421 keyword is not compatible with "rewrite" and "prefix".
1422
1423 prefix This keyword indicates that instead of relying on a dedicated
1424 cookie for the persistence, an existing one will be completed.
1425 This may be needed in some specific environments where the client
1426 does not support more than one single cookie and the application
1427 already needs it. In this case, whenever the server sets a cookie
1428 named <name>, it will be prefixed with the server's identifier
1429 and a delimiter. The prefix will be removed from all client
1430 requests so that the server still finds the cookie it emitted.
1431 Since all requests and responses are subject to being modified,
1432 this mode requires the HTTP close mode. The "prefix" keyword is
1433 not compatible with "rewrite" and "insert".
1434
1435 indirect When this option is specified in insert mode, cookies will only
1436 be added when the server was not reached after a direct access,
1437 which means that only when a server is elected after applying a
1438 load-balancing algorithm, or after a redispatch, then the cookie
1439 will be inserted. If the client has all the required information
1440 to connect to the same server next time, no further cookie will
1441 be inserted. In all cases, when the "indirect" option is used in
1442 insert mode, the cookie is always removed from the requests
1443 transmitted to the server. The persistence mechanism then becomes
1444 totally transparent from the application point of view.
1445
1446 nocache This option is recommended in conjunction with the insert mode
1447 when there is a cache between the client and HAProxy, as it
1448 ensures that a cacheable response will be tagged non-cacheable if
1449 a cookie needs to be inserted. This is important because if all
1450 persistence cookies are added on a cacheable home page for
1451 instance, then all customers will then fetch the page from an
1452 outer cache and will all share the same persistence cookie,
1453 leading to one server receiving much more traffic than others.
1454 See also the "insert" and "postonly" options.
1455
1456 postonly This option ensures that cookie insertion will only be performed
1457 on responses to POST requests. It is an alternative to the
1458 "nocache" option, because POST responses are not cacheable, so
1459 this ensures that the persistence cookie will never get cached.
1460 Since most sites do not need any sort of persistence before the
1461 first POST which generally is a login request, this is a very
1462 efficient method to optimize caching without risking to find a
1463 persistence cookie in the cache.
1464 See also the "insert" and "nocache" options.
1465
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02001466 domain This option allows to specify the domain at which a cookie is
1467 inserted. It requires exactly one paramater: a valid domain
1468 name.
1469
Willy Tarreau0ba27502007-12-24 16:55:16 +01001470 There can be only one persistence cookie per HTTP backend, and it can be
1471 declared in a defaults section. The value of the cookie will be the value
1472 indicated after the "cookie" keyword in a "server" statement. If no cookie
1473 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001474
Willy Tarreau0ba27502007-12-24 16:55:16 +01001475 Examples :
1476 cookie JSESSIONID prefix
1477 cookie SRV insert indirect nocache
1478 cookie SRV insert postonly indirect
1479
1480 See also : "appsession", "balance source", "capture cookie", "server".
1481
1482
1483default_backend <backend>
1484 Specify the backend to use when no "use_backend" rule has been matched.
1485 May be used in sections : defaults | frontend | listen | backend
1486 yes | yes | yes | no
1487 Arguments :
1488 <backend> is the name of the backend to use.
1489
1490 When doing content-switching between frontend and backends using the
1491 "use_backend" keyword, it is often useful to indicate which backend will be
1492 used when no rule has matched. It generally is the dynamic backend which
1493 will catch all undetermined requests.
1494
Willy Tarreau0ba27502007-12-24 16:55:16 +01001495 Example :
1496
1497 use_backend dynamic if url_dyn
1498 use_backend static if url_css url_img extension_img
1499 default_backend dynamic
1500
Willy Tarreau2769aa02007-12-27 18:26:09 +01001501 See also : "use_backend", "reqsetbe", "reqisetbe"
1502
Willy Tarreau0ba27502007-12-24 16:55:16 +01001503
1504disabled
1505 Disable a proxy, frontend or backend.
1506 May be used in sections : defaults | frontend | listen | backend
1507 yes | yes | yes | yes
1508 Arguments : none
1509
1510 The "disabled" keyword is used to disable an instance, mainly in order to
1511 liberate a listening port or to temporarily disable a service. The instance
1512 will still be created and its configuration will be checked, but it will be
1513 created in the "stopped" state and will appear as such in the statistics. It
1514 will not receive any traffic nor will it send any health-checks or logs. It
1515 is possible to disable many instances at once by adding the "disabled"
1516 keyword in a "defaults" section.
1517
1518 See also : "enabled"
1519
1520
1521enabled
1522 Enable a proxy, frontend or backend.
1523 May be used in sections : defaults | frontend | listen | backend
1524 yes | yes | yes | yes
1525 Arguments : none
1526
1527 The "enabled" keyword is used to explicitly enable an instance, when the
1528 defaults has been set to "disabled". This is very rarely used.
1529
1530 See also : "disabled"
1531
1532
1533errorfile <code> <file>
1534 Return a file contents instead of errors generated by HAProxy
1535 May be used in sections : defaults | frontend | listen | backend
1536 yes | yes | yes | yes
1537 Arguments :
1538 <code> is the HTTP status code. Currently, HAProxy is capable of
1539 generating codes 400, 403, 408, 500, 502, 503, and 504.
1540
1541 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001542 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01001543 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01001544 error pages, and to use absolute paths, since files are read
1545 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001546
1547 It is important to understand that this keyword is not meant to rewrite
1548 errors returned by the server, but errors detected and returned by HAProxy.
1549 This is why the list of supported errors is limited to a small set.
1550
1551 The files are returned verbatim on the TCP socket. This allows any trick such
1552 as redirections to another URL or site, as well as tricks to clean cookies,
1553 force enable or disable caching, etc... The package provides default error
1554 files returning the same contents as default errors.
1555
Willy Tarreau59140a22009-02-22 12:02:30 +01001556 The files should not exceed the configured buffer size (BUFSIZE), which
1557 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
1558 not to put any reference to local contents (eg: images) in order to avoid
1559 loops between the client and HAProxy when all servers are down, causing an
1560 error to be returned instead of an image. For better HTTP compliance, it is
1561 recommended that all header lines end with CR-LF and not LF alone.
1562
Willy Tarreau0ba27502007-12-24 16:55:16 +01001563 The files are read at the same time as the configuration and kept in memory.
1564 For this reason, the errors continue to be returned even when the process is
1565 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01001566 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001567 403 status code and interrogating a blocked URL.
1568
1569 See also : "errorloc", "errorloc302", "errorloc303"
1570
Willy Tarreau59140a22009-02-22 12:02:30 +01001571 Example :
1572 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
1573 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
1574 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
1575
Willy Tarreau2769aa02007-12-27 18:26:09 +01001576
1577errorloc <code> <url>
1578errorloc302 <code> <url>
1579 Return an HTTP redirection to a URL instead of errors generated by HAProxy
1580 May be used in sections : defaults | frontend | listen | backend
1581 yes | yes | yes | yes
1582 Arguments :
1583 <code> is the HTTP status code. Currently, HAProxy is capable of
1584 generating codes 400, 403, 408, 500, 502, 503, and 504.
1585
1586 <url> it is the exact contents of the "Location" header. It may contain
1587 either a relative URI to an error page hosted on the same site,
1588 or an absolute URI designating an error page on another site.
1589 Special care should be given to relative URIs to avoid redirect
1590 loops if the URI itself may generate the same error (eg: 500).
1591
1592 It is important to understand that this keyword is not meant to rewrite
1593 errors returned by the server, but errors detected and returned by HAProxy.
1594 This is why the list of supported errors is limited to a small set.
1595
1596 Note that both keyword return the HTTP 302 status code, which tells the
1597 client to fetch the designated URL using the same HTTP method. This can be
1598 quite problematic in case of non-GET methods such as POST, because the URL
1599 sent to the client might not be allowed for something other than GET. To
1600 workaround this problem, please use "errorloc303" which send the HTTP 303
1601 status code, indicating to the client that the URL must be fetched with a GET
1602 request.
1603
1604 See also : "errorfile", "errorloc303"
1605
1606
1607errorloc303 <code> <url>
1608 Return an HTTP redirection to a URL instead of errors generated by HAProxy
1609 May be used in sections : defaults | frontend | listen | backend
1610 yes | yes | yes | yes
1611 Arguments :
1612 <code> is the HTTP status code. Currently, HAProxy is capable of
1613 generating codes 400, 403, 408, 500, 502, 503, and 504.
1614
1615 <url> it is the exact contents of the "Location" header. It may contain
1616 either a relative URI to an error page hosted on the same site,
1617 or an absolute URI designating an error page on another site.
1618 Special care should be given to relative URIs to avoid redirect
1619 loops if the URI itself may generate the same error (eg: 500).
1620
1621 It is important to understand that this keyword is not meant to rewrite
1622 errors returned by the server, but errors detected and returned by HAProxy.
1623 This is why the list of supported errors is limited to a small set.
1624
1625 Note that both keyword return the HTTP 303 status code, which tells the
1626 client to fetch the designated URL using the same HTTP GET method. This
1627 solves the usual problems associated with "errorloc" and the 302 code. It is
1628 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001629 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01001630
1631 See also : "errorfile", "errorloc", "errorloc302"
1632
1633
1634fullconn <conns>
1635 Specify at what backend load the servers will reach their maxconn
1636 May be used in sections : defaults | frontend | listen | backend
1637 yes | no | yes | yes
1638 Arguments :
1639 <conns> is the number of connections on the backend which will make the
1640 servers use the maximal number of connections.
1641
Willy Tarreau198a7442008-01-17 12:05:32 +01001642 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01001643 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01001644 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01001645 load. The server will then always accept at least <minconn> connections,
1646 never more than <maxconn>, and the limit will be on the ramp between both
1647 values when the backend has less than <conns> concurrent connections. This
1648 makes it possible to limit the load on the servers during normal loads, but
1649 push it further for important loads without overloading the servers during
1650 exceptionnal loads.
1651
1652 Example :
1653 # The servers will accept between 100 and 1000 concurrent connections each
1654 # and the maximum of 1000 will be reached when the backend reaches 10000
1655 # connections.
1656 backend dynamic
1657 fullconn 10000
1658 server srv1 dyn1:80 minconn 100 maxconn 1000
1659 server srv2 dyn2:80 minconn 100 maxconn 1000
1660
1661 See also : "maxconn", "server"
1662
1663
1664grace <time>
1665 Maintain a proxy operational for some time after a soft stop
1666 May be used in sections : defaults | frontend | listen | backend
1667 no | yes | yes | yes
1668 Arguments :
1669 <time> is the time (by default in milliseconds) for which the instance
1670 will remain operational with the frontend sockets still listening
1671 when a soft-stop is received via the SIGUSR1 signal.
1672
1673 This may be used to ensure that the services disappear in a certain order.
1674 This was designed so that frontends which are dedicated to monitoring by an
1675 external equipement fail immediately while other ones remain up for the time
1676 needed by the equipment to detect the failure.
1677
1678 Note that currently, there is very little benefit in using this parameter,
1679 and it may in fact complicate the soft-reconfiguration process more than
1680 simplify it.
1681
Willy Tarreau0ba27502007-12-24 16:55:16 +01001682
1683http-check disable-on-404
1684 Enable a maintenance mode upon HTTP/404 response to health-checks
1685 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01001686 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01001687 Arguments : none
1688
1689 When this option is set, a server which returns an HTTP code 404 will be
1690 excluded from further load-balancing, but will still receive persistent
1691 connections. This provides a very convenient method for Web administrators
1692 to perform a graceful shutdown of their servers. It is also important to note
1693 that a server which is detected as failed while it was in this mode will not
1694 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
1695 will immediately be reinserted into the farm. The status on the stats page
1696 reports "NOLB" for a server in this mode. It is important to note that this
1697 option only works in conjunction with the "httpchk" option.
1698
Willy Tarreau2769aa02007-12-27 18:26:09 +01001699 See also : "option httpchk"
1700
1701
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01001702id <value>
1703 Set a persistent value for proxy ID. Must be unique and larger than 1000, as
1704 smaller values are reserved for auto-assigned ids.
1705
1706
Willy Tarreau2769aa02007-12-27 18:26:09 +01001707log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001708log <address> <facility> [<level> [<minlevel>]]
Willy Tarreau2769aa02007-12-27 18:26:09 +01001709 Enable per-instance logging of events and traffic.
1710 May be used in sections : defaults | frontend | listen | backend
1711 yes | yes | yes | yes
1712 Arguments :
1713 global should be used when the instance's logging parameters are the
1714 same as the global ones. This is the most common usage. "global"
1715 replaces <address>, <facility> and <level> with those of the log
1716 entries found in the "global" section. Only one "log global"
1717 statement may be used per instance, and this form takes no other
1718 parameter.
1719
1720 <address> indicates where to send the logs. It takes the same format as
1721 for the "global" section's logs, and can be one of :
1722
1723 - An IPv4 address optionally followed by a colon (':') and a UDP
1724 port. If no port is specified, 514 is used by default (the
1725 standard syslog port).
1726
1727 - A filesystem path to a UNIX domain socket, keeping in mind
1728 considerations for chroot (be sure the path is accessible
1729 inside the chroot) and uid/gid (be sure the path is
1730 appropriately writeable).
1731
1732 <facility> must be one of the 24 standard syslog facilities :
1733
1734 kern user mail daemon auth syslog lpr news
1735 uucp cron auth2 ftp ntp audit alert cron2
1736 local0 local1 local2 local3 local4 local5 local6 local7
1737
1738 <level> is optional and can be specified to filter outgoing messages. By
1739 default, all messages are sent. If a level is specified, only
1740 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001741 will be sent. An optional minimum level can be specified. If it
1742 is set, logs emitted with a more severe level than this one will
1743 be capped to this level. This is used to avoid sending "emerg"
1744 messages on all terminals on some default syslog configurations.
1745 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01001746
1747 emerg alert crit err warning notice info debug
1748
1749 Note that up to two "log" entries may be specified per instance. However, if
1750 "log global" is used and if the "global" section already contains 2 log
1751 entries, then additional log entries will be ignored.
1752
1753 Also, it is important to keep in mind that it is the frontend which decides
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001754 what to log from a connection, and that in case of content switching, the log
1755 entries from the backend will be ignored. Connections are logged at level
1756 "info".
1757
1758 However, backend log declaration define how and where servers status changes
1759 will be logged. Level "notice" will be used to indicate a server going up,
1760 "warning" will be used for termination signals and definitive service
1761 termination, and "alert" will be used for when a server goes down.
1762
1763 Note : According to RFC3164, messages are truncated to 1024 bytes before
1764 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01001765
1766 Example :
1767 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001768 log 127.0.0.1:514 local0 notice # only send important events
1769 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreau2769aa02007-12-27 18:26:09 +01001770
1771
1772maxconn <conns>
1773 Fix the maximum number of concurrent connections on a frontend
1774 May be used in sections : defaults | frontend | listen | backend
1775 yes | yes | yes | no
1776 Arguments :
1777 <conns> is the maximum number of concurrent connections the frontend will
1778 accept to serve. Excess connections will be queued by the system
1779 in the socket's listen queue and will be served once a connection
1780 closes.
1781
1782 If the system supports it, it can be useful on big sites to raise this limit
1783 very high so that haproxy manages connection queues, instead of leaving the
1784 clients with unanswered connection attempts. This value should not exceed the
1785 global maxconn. Also, keep in mind that a connection contains two buffers
1786 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
1787 consumed per established connection. That means that a medium system equipped
1788 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
1789 properly tuned.
1790
1791 Also, when <conns> is set to large values, it is possible that the servers
1792 are not sized to accept such loads, and for this reason it is generally wise
1793 to assign them some reasonable connection limits.
1794
1795 See also : "server", global section's "maxconn", "fullconn"
1796
1797
1798mode { tcp|http|health }
1799 Set the running mode or protocol of the instance
1800 May be used in sections : defaults | frontend | listen | backend
1801 yes | yes | yes | yes
1802 Arguments :
1803 tcp The instance will work in pure TCP mode. A full-duplex connection
1804 will be established between clients and servers, and no layer 7
1805 examination will be performed. This is the default mode. It
1806 should be used for SSL, SSH, SMTP, ...
1807
1808 http The instance will work in HTTP mode. The client request will be
1809 analyzed in depth before connecting to any server. Any request
1810 which is not RFC-compliant will be rejected. Layer 7 filtering,
1811 processing and switching will be possible. This is the mode which
1812 brings HAProxy most of its value.
1813
1814 health The instance will work in "health" mode. It will just reply "OK"
1815 to incoming connections and close the connection. Nothing will be
1816 logged. This mode is used to reply to external components health
1817 checks. This mode is deprecated and should not be used anymore as
1818 it is possible to do the same and even better by combining TCP or
1819 HTTP modes with the "monitor" keyword.
1820
1821 When doing content switching, it is mandatory that the frontend and the
1822 backend are in the same mode (generally HTTP), otherwise the configuration
1823 will be refused.
1824
1825 Example :
1826 defaults http_instances
1827 mode http
1828
1829 See also : "monitor", "monitor-net"
1830
Willy Tarreau0ba27502007-12-24 16:55:16 +01001831
1832monitor fail [if | unless] <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01001833 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001834 May be used in sections : defaults | frontend | listen | backend
1835 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01001836 Arguments :
1837 if <cond> the monitor request will fail if the condition is satisfied,
1838 and will succeed otherwise. The condition should describe a
1839 combinated test which must induce a failure if all conditions
1840 are met, for instance a low number of servers both in a
1841 backend and its backup.
1842
1843 unless <cond> the monitor request will succeed only if the condition is
1844 satisfied, and will fail otherwise. Such a condition may be
1845 based on a test on the presence of a minimum number of active
1846 servers in a list of backends.
1847
1848 This statement adds a condition which can force the response to a monitor
1849 request to report a failure. By default, when an external component queries
1850 the URI dedicated to monitoring, a 200 response is returned. When one of the
1851 conditions above is met, haproxy will return 503 instead of 200. This is
1852 very useful to report a site failure to an external component which may base
1853 routing advertisements between multiple sites on the availability reported by
1854 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreau2769aa02007-12-27 18:26:09 +01001855 criterion. Note that "monitor fail" only works in HTTP mode.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001856
1857 Example:
1858 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01001859 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01001860 acl site_dead nbsrv(dynamic) lt 2
1861 acl site_dead nbsrv(static) lt 2
1862 monitor-uri /site_alive
1863 monitor fail if site_dead
1864
Willy Tarreau2769aa02007-12-27 18:26:09 +01001865 See also : "monitor-net", "monitor-uri"
1866
1867
1868monitor-net <source>
1869 Declare a source network which is limited to monitor requests
1870 May be used in sections : defaults | frontend | listen | backend
1871 yes | yes | yes | no
1872 Arguments :
1873 <source> is the source IPv4 address or network which will only be able to
1874 get monitor responses to any request. It can be either an IPv4
1875 address, a host name, or an address followed by a slash ('/')
1876 followed by a mask.
1877
1878 In TCP mode, any connection coming from a source matching <source> will cause
1879 the connection to be immediately closed without any log. This allows another
1880 equipement to probe the port and verify that it is still listening, without
1881 forwarding the connection to a remote server.
1882
1883 In HTTP mode, a connection coming from a source matching <source> will be
1884 accepted, the following response will be sent without waiting for a request,
1885 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
1886 enough for any front-end HTTP probe to detect that the service is UP and
1887 running without forwarding the request to a backend server.
1888
1889 Monitor requests are processed very early. It is not possible to block nor
1890 divert them using ACLs. They cannot be logged either, and it is the intended
1891 purpose. They are only used to report HAProxy's health to an upper component,
1892 nothing more. Right now, it is not possible to set failure conditions on
1893 requests caught by "monitor-net".
1894
1895 Example :
1896 # addresses .252 and .253 are just probing us.
1897 frontend www
1898 monitor-net 192.168.0.252/31
1899
1900 See also : "monitor fail", "monitor-uri"
1901
1902
1903monitor-uri <uri>
1904 Intercept a URI used by external components' monitor requests
1905 May be used in sections : defaults | frontend | listen | backend
1906 yes | yes | yes | no
1907 Arguments :
1908 <uri> is the exact URI which we want to intercept to return HAProxy's
1909 health status instead of forwarding the request.
1910
1911 When an HTTP request referencing <uri> will be received on a frontend,
1912 HAProxy will not forward it nor log it, but instead will return either
1913 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
1914 conditions defined with "monitor fail". This is normally enough for any
1915 front-end HTTP probe to detect that the service is UP and running without
1916 forwarding the request to a backend server. Note that the HTTP method, the
1917 version and all headers are ignored, but the request must at least be valid
1918 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
1919
1920 Monitor requests are processed very early. It is not possible to block nor
1921 divert them using ACLs. They cannot be logged either, and it is the intended
1922 purpose. They are only used to report HAProxy's health to an upper component,
1923 nothing more. However, it is possible to add any number of conditions using
1924 "monitor fail" and ACLs so that the result can be adjusted to whatever check
1925 can be imagined (most often the number of available servers in a backend).
1926
1927 Example :
1928 # Use /haproxy_test to report haproxy's status
1929 frontend www
1930 mode http
1931 monitor-uri /haproxy_test
1932
1933 See also : "monitor fail", "monitor-net"
1934
Willy Tarreau0ba27502007-12-24 16:55:16 +01001935
Willy Tarreaubf1f8162007-12-28 17:42:56 +01001936option abortonclose
1937no option abortonclose
1938 Enable or disable early dropping of aborted requests pending in queues.
1939 May be used in sections : defaults | frontend | listen | backend
1940 yes | no | yes | yes
1941 Arguments : none
1942
1943 In presence of very high loads, the servers will take some time to respond.
1944 The per-instance connection queue will inflate, and the response time will
1945 increase respective to the size of the queue times the average per-session
1946 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01001947 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01001948 the queue, and slowing down other users, and the servers as well, because the
1949 request will eventually be served, then aborted at the first error
1950 encountered while delivering the response.
1951
1952 As there is no way to distinguish between a full STOP and a simple output
1953 close on the client side, HTTP agents should be conservative and consider
1954 that the client might only have closed its output channel while waiting for
1955 the response. However, this introduces risks of congestion when lots of users
1956 do the same, and is completely useless nowadays because probably no client at
1957 all will close the session while waiting for the response. Some HTTP agents
1958 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
1959 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01001960 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01001961 of being the single component to break rare but valid traffic is extremely
1962 low, which adds to the temptation to be able to abort a session early while
1963 still not served and not pollute the servers.
1964
1965 In HAProxy, the user can choose the desired behaviour using the option
1966 "abortonclose". By default (without the option) the behaviour is HTTP
1967 compliant and aborted requests will be served. But when the option is
1968 specified, a session with an incoming channel closed will be aborted while
1969 it is still possible, either pending in the queue for a connection slot, or
1970 during the connection establishment if the server has not yet acknowledged
1971 the connection request. This considerably reduces the queue size and the load
1972 on saturated servers when users are tempted to click on STOP, which in turn
1973 reduces the response time for other users.
1974
1975 If this option has been enabled in a "defaults" section, it can be disabled
1976 in a specific instance by prepending the "no" keyword before it.
1977
1978 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
1979
1980
Willy Tarreau4076a152009-04-02 15:18:36 +02001981option accept-invalid-http-request
1982no option accept-invalid-http-request
1983 Enable or disable relaxing of HTTP request parsing
1984 May be used in sections : defaults | frontend | listen | backend
1985 yes | yes | yes | no
1986 Arguments : none
1987
1988 By default, HAProxy complies with RFC2616 in terms of message parsing. This
1989 means that invalid characters in header names are not permitted and cause an
1990 error to be returned to the client. This is the desired behaviour as such
1991 forbidden characters are essentially used to build attacks exploiting server
1992 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
1993 server will emit invalid header names for whatever reason (configuration,
1994 implementation) and the issue will not be immediately fixed. In such a case,
1995 it is possible to relax HAProxy's header name parser to accept any character
1996 even if that does not make sense, by specifying this option.
1997
1998 This option should never be enabled by default as it hides application bugs
1999 and open security breaches. It should only be deployed after a problem has
2000 been confirmed.
2001
2002 When this option is enabled, erroneous header names will still be accepted in
2003 requests, but the complete request will be captured in order to permit later
2004 analysis using the "show errors" request on the UNIX stats socket. Doing this
2005 also helps confirming that the issue has been solved.
2006
2007 If this option has been enabled in a "defaults" section, it can be disabled
2008 in a specific instance by prepending the "no" keyword before it.
2009
2010 See also : "option accept-invalid-http-response" and "show errors" on the
2011 stats socket.
2012
2013
2014option accept-invalid-http-response
2015no option accept-invalid-http-response
2016 Enable or disable relaxing of HTTP response parsing
2017 May be used in sections : defaults | frontend | listen | backend
2018 yes | no | yes | yes
2019 Arguments : none
2020
2021 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2022 means that invalid characters in header names are not permitted and cause an
2023 error to be returned to the client. This is the desired behaviour as such
2024 forbidden characters are essentially used to build attacks exploiting server
2025 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2026 server will emit invalid header names for whatever reason (configuration,
2027 implementation) and the issue will not be immediately fixed. In such a case,
2028 it is possible to relax HAProxy's header name parser to accept any character
2029 even if that does not make sense, by specifying this option.
2030
2031 This option should never be enabled by default as it hides application bugs
2032 and open security breaches. It should only be deployed after a problem has
2033 been confirmed.
2034
2035 When this option is enabled, erroneous header names will still be accepted in
2036 responses, but the complete response will be captured in order to permit
2037 later analysis using the "show errors" request on the UNIX stats socket.
2038 Doing this also helps confirming that the issue has been solved.
2039
2040 If this option has been enabled in a "defaults" section, it can be disabled
2041 in a specific instance by prepending the "no" keyword before it.
2042
2043 See also : "option accept-invalid-http-request" and "show errors" on the
2044 stats socket.
2045
2046
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002047option allbackups
2048no option allbackups
2049 Use either all backup servers at a time or only the first one
2050 May be used in sections : defaults | frontend | listen | backend
2051 yes | no | yes | yes
2052 Arguments : none
2053
2054 By default, the first operational backup server gets all traffic when normal
2055 servers are all down. Sometimes, it may be preferred to use multiple backups
2056 at once, because one will not be enough. When "option allbackups" is enabled,
2057 the load balancing will be performed among all backup servers when all normal
2058 ones are unavailable. The same load balancing algorithm will be used and the
2059 servers' weights will be respected. Thus, there will not be any priority
2060 order between the backup servers anymore.
2061
2062 This option is mostly used with static server farms dedicated to return a
2063 "sorry" page when an application is completely offline.
2064
2065 If this option has been enabled in a "defaults" section, it can be disabled
2066 in a specific instance by prepending the "no" keyword before it.
2067
2068
2069option checkcache
2070no option checkcache
2071 Analyze all server responses and block requests with cachable cookies
2072 May be used in sections : defaults | frontend | listen | backend
2073 yes | no | yes | yes
2074 Arguments : none
2075
2076 Some high-level frameworks set application cookies everywhere and do not
2077 always let enough control to the developer to manage how the responses should
2078 be cached. When a session cookie is returned on a cachable object, there is a
2079 high risk of session crossing or stealing between users traversing the same
2080 caches. In some situations, it is better to block the response than to let
2081 some sensible session information go in the wild.
2082
2083 The option "checkcache" enables deep inspection of all server responses for
2084 strict compliance with HTTP specification in terms of cachability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01002085 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002086 response to check if there's a risk of caching a cookie on a client-side
2087 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01002088 to the client are :
2089 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002090 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01002091 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002092 - all those that come from a POST request, provided that the server has not
2093 set a 'Cache-Control: public' header ;
2094 - those with a 'Pragma: no-cache' header
2095 - those with a 'Cache-control: private' header
2096 - those with a 'Cache-control: no-store' header
2097 - those with a 'Cache-control: max-age=0' header
2098 - those with a 'Cache-control: s-maxage=0' header
2099 - those with a 'Cache-control: no-cache' header
2100 - those with a 'Cache-control: no-cache="set-cookie"' header
2101 - those with a 'Cache-control: no-cache="set-cookie,' header
2102 (allowing other fields after set-cookie)
2103
2104 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01002105 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002106 The session state shows "PH--" meaning that the proxy blocked the response
2107 during headers processing. Additionnaly, an alert will be sent in the logs so
2108 that admins are informed that there's something to be fixed.
2109
2110 Due to the high impact on the application, the application should be tested
2111 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002112 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002113 production, as it will report potentially dangerous application behaviours.
2114
2115 If this option has been enabled in a "defaults" section, it can be disabled
2116 in a specific instance by prepending the "no" keyword before it.
2117
2118
2119option clitcpka
2120no option clitcpka
2121 Enable or disable the sending of TCP keepalive packets on the client side
2122 May be used in sections : defaults | frontend | listen | backend
2123 yes | yes | yes | no
2124 Arguments : none
2125
2126 When there is a firewall or any session-aware component between a client and
2127 a server, and when the protocol involves very long sessions with long idle
2128 periods (eg: remote desktops), there is a risk that one of the intermediate
2129 components decides to expire a session which has remained idle for too long.
2130
2131 Enabling socket-level TCP keep-alives makes the system regularly send packets
2132 to the other end of the connection, leaving it active. The delay between
2133 keep-alive probes is controlled by the system only and depends both on the
2134 operating system and its tuning parameters.
2135
2136 It is important to understand that keep-alive packets are neither emitted nor
2137 received at the application level. It is only the network stacks which sees
2138 them. For this reason, even if one side of the proxy already uses keep-alives
2139 to maintain its connection alive, those keep-alive packets will not be
2140 forwarded to the other side of the proxy.
2141
2142 Please note that this has nothing to do with HTTP keep-alive.
2143
2144 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
2145 client side of a connection, which should help when session expirations are
2146 noticed between HAProxy and a client.
2147
2148 If this option has been enabled in a "defaults" section, it can be disabled
2149 in a specific instance by prepending the "no" keyword before it.
2150
2151 See also : "option srvtcpka", "option tcpka"
2152
2153
Willy Tarreau0ba27502007-12-24 16:55:16 +01002154option contstats
2155 Enable continuous traffic statistics updates
2156 May be used in sections : defaults | frontend | listen | backend
2157 yes | yes | yes | no
2158 Arguments : none
2159
2160 By default, counters used for statistics calculation are incremented
2161 only when a session finishes. It works quite well when serving small
2162 objects, but with big ones (for example large images or archives) or
2163 with A/V streaming, a graph generated from haproxy counters looks like
2164 a hedgehog. With this option enabled counters get incremented continuously,
2165 during a whole session. Recounting touches a hotpath directly so
2166 it is not enabled by default, as it has small performance impact (~0.5%).
2167
2168
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002169option dontlog-normal
2170no option dontlog-normal
2171 Enable or disable logging of normal, successful connections
2172 May be used in sections : defaults | frontend | listen | backend
2173 yes | yes | yes | no
2174 Arguments : none
2175
2176 There are large sites dealing with several thousand connections per second
2177 and for which logging is a major pain. Some of them are even forced to turn
2178 logs off and cannot debug production issues. Setting this option ensures that
2179 normal connections, those which experience no error, no timeout, no retry nor
2180 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
2181 mode, the response status code is checked and return codes 5xx will still be
2182 logged.
2183
2184 It is strongly discouraged to use this option as most of the time, the key to
2185 complex issues is in the normal logs which will not be logged here. If you
2186 need to separate logs, see the "log-separate-errors" option instead.
2187
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002188 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002189 logging.
2190
2191
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002192option dontlognull
2193no option dontlognull
2194 Enable or disable logging of null connections
2195 May be used in sections : defaults | frontend | listen | backend
2196 yes | yes | yes | no
2197 Arguments : none
2198
2199 In certain environments, there are components which will regularly connect to
2200 various systems to ensure that they are still alive. It can be the case from
2201 another load balancer as well as from monitoring systems. By default, even a
2202 simple port probe or scan will produce a log. If those connections pollute
2203 the logs too much, it is possible to enable option "dontlognull" to indicate
2204 that a connection on which no data has been transferred will not be logged,
2205 which typically corresponds to those probes.
2206
2207 It is generally recommended not to use this option in uncontrolled
2208 environments (eg: internet), otherwise scans and other malicious activities
2209 would not be logged.
2210
2211 If this option has been enabled in a "defaults" section, it can be disabled
2212 in a specific instance by prepending the "no" keyword before it.
2213
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002214 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002215
2216
2217option forceclose
2218no option forceclose
2219 Enable or disable active connection closing after response is transferred.
2220 May be used in sections : defaults | frontend | listen | backend
2221 yes | no | yes | yes
2222 Arguments : none
2223
2224 Some HTTP servers do not necessarily close the connections when they receive
2225 the "Connection: close" set by "option httpclose", and if the client does not
2226 close either, then the connection remains open till the timeout expires. This
2227 causes high number of simultaneous connections on the servers and shows high
2228 global session times in the logs.
2229
2230 When this happens, it is possible to use "option forceclose". It will
2231 actively close the outgoing server channel as soon as the server begins to
2232 reply and only if the request buffer is empty. Note that this should NOT be
2233 used if CONNECT requests are expected between the client and the server. This
2234 option implicitly enables the "httpclose" option.
2235
2236 If this option has been enabled in a "defaults" section, it can be disabled
2237 in a specific instance by prepending the "no" keyword before it.
2238
2239 See also : "option httpclose"
2240
2241
Ross Westaf72a1d2008-08-03 10:51:45 +02002242option forwardfor [ except <network> ] [ header <name> ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01002243 Enable insertion of the X-Forwarded-For header to requests sent to servers
2244 May be used in sections : defaults | frontend | listen | backend
2245 yes | yes | yes | yes
2246 Arguments :
2247 <network> is an optional argument used to disable this option for sources
2248 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02002249 <name> an optional argument to specify a different "X-Forwarded-For"
2250 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01002251
2252 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
2253 their client address. This is sometimes annoying when the client's IP address
2254 is expected in server logs. To solve this problem, the well-known HTTP header
2255 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
2256 This header contains a value representing the client's IP address. Since this
2257 header is always appended at the end of the existing header list, the server
2258 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02002259 the server's manual to find how to enable use of this standard header. Note
2260 that only the last occurrence of the header must be used, since it is really
2261 possible that the client has already brought one.
2262
2263 The keyword "header" may be used to supply a different header name to replace
2264 the default "X-Forwarded-For". This can be useful where you might already
2265 have a "X-Forwarded-For" header from a different application (eg: stunnel),
2266 and you need preserve it. Also if your backend server doesn't use the
2267 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
2268 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01002269
2270 Sometimes, a same HAProxy instance may be shared between a direct client
2271 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
2272 used to decrypt HTTPS traffic). It is possible to disable the addition of the
2273 header for a known source address or network by adding the "except" keyword
2274 followed by the network address. In this case, any source IP matching the
2275 network will not cause an addition of this header. Most common uses are with
2276 private networks or 127.0.0.1.
2277
2278 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02002279 least one of them uses it, the header will be added. Note that the backend's
2280 setting of the header subargument takes precedence over the frontend's if
2281 both are defined.
Willy Tarreauc27debf2008-01-06 08:57:02 +01002282
2283 It is important to note that as long as HAProxy does not support keep-alive
2284 connections, only the first request of a connection will receive the header.
2285 For this reason, it is important to ensure that "option httpclose" is set
2286 when using this option.
2287
Ross Westaf72a1d2008-08-03 10:51:45 +02002288 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01002289 # Public HTTP address also used by stunnel on the same machine
2290 frontend www
2291 mode http
2292 option forwardfor except 127.0.0.1 # stunnel already adds the header
2293
Ross Westaf72a1d2008-08-03 10:51:45 +02002294 # Those servers want the IP Address in X-Client
2295 backend www
2296 mode http
2297 option forwardfor header X-Client
2298
Willy Tarreauc27debf2008-01-06 08:57:02 +01002299 See also : "option httpclose"
2300
2301
Willy Tarreauc27debf2008-01-06 08:57:02 +01002302option httpchk
2303option httpchk <uri>
2304option httpchk <method> <uri>
2305option httpchk <method> <uri> <version>
2306 Enable HTTP protocol to check on the servers health
2307 May be used in sections : defaults | frontend | listen | backend
2308 yes | no | yes | yes
2309 Arguments :
2310 <method> is the optional HTTP method used with the requests. When not set,
2311 the "OPTIONS" method is used, as it generally requires low server
2312 processing and is easy to filter out from the logs. Any method
2313 may be used, though it is not recommended to invent non-standard
2314 ones.
2315
2316 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
2317 which is accessible by default on almost any server, but may be
2318 changed to any other URI. Query strings are permitted.
2319
2320 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
2321 but some servers might behave incorrectly in HTTP 1.0, so turning
2322 it to HTTP/1.1 may sometimes help. Note that the Host field is
2323 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
2324 after "\r\n" following the version string.
2325
2326 By default, server health checks only consist in trying to establish a TCP
2327 connection. When "option httpchk" is specified, a complete HTTP request is
2328 sent once the TCP connection is established, and responses 2xx and 3xx are
2329 considered valid, while all other ones indicate a server failure, including
2330 the lack of any response.
2331
2332 The port and interval are specified in the server configuration.
2333
2334 This option does not necessarily require an HTTP backend, it also works with
2335 plain TCP backends. This is particularly useful to check simple scripts bound
2336 to some dedicated ports using the inetd daemon.
2337
2338 Examples :
2339 # Relay HTTPS traffic to Apache instance and check service availability
2340 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
2341 backend https_relay
2342 mode tcp
Willy Tarreauebaf21a2008-03-21 20:17:14 +01002343 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
Willy Tarreauc27debf2008-01-06 08:57:02 +01002344 server apache1 192.168.1.1:443 check port 80
2345
2346 See also : "option ssl-hello-chk", "option smtpchk", "http-check" and the
2347 "check", "port" and "interval" server options.
2348
2349
2350option httpclose
2351no option httpclose
2352 Enable or disable passive HTTP connection closing
2353 May be used in sections : defaults | frontend | listen | backend
2354 yes | yes | yes | yes
2355 Arguments : none
2356
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002357 As stated in section 1, HAProxy does not yes support the HTTP keep-alive
Willy Tarreauc27debf2008-01-06 08:57:02 +01002358 mode. So by default, if a client communicates with a server in this mode, it
2359 will only analyze, log, and process the first request of each connection. To
2360 workaround this limitation, it is possible to specify "option httpclose". It
2361 will check if a "Connection: close" header is already set in each direction,
2362 and will add one if missing. Each end should react to this by actively
2363 closing the TCP connection after each transfer, thus resulting in a switch to
2364 the HTTP close mode. Any "Connection" header different from "close" will also
2365 be removed.
2366
2367 It seldom happens that some servers incorrectly ignore this header and do not
2368 close the connection eventough they reply "Connection: close". For this
2369 reason, they are not compatible with older HTTP 1.0 browsers. If this
2370 happens it is possible to use the "option forceclose" which actively closes
2371 the request connection once the server responds.
2372
2373 This option may be set both in a frontend and in a backend. It is enabled if
2374 at least one of the frontend or backend holding a connection has it enabled.
2375 If "option forceclose" is specified too, it has precedence over "httpclose".
2376
2377 If this option has been enabled in a "defaults" section, it can be disabled
2378 in a specific instance by prepending the "no" keyword before it.
2379
2380 See also : "option forceclose"
2381
2382
Emeric Brun3a058f32009-06-30 18:26:00 +02002383option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01002384 Enable logging of HTTP request, session state and timers
2385 May be used in sections : defaults | frontend | listen | backend
2386 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02002387 Arguments :
2388 clf if the "clf" argument is added, then the output format will be
2389 the CLF format instead of HAProxy's default HTTP format. You can
2390 use this when you need to feed HAProxy's logs through a specific
2391 log analyser which only support the CLF format and which is not
2392 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01002393
2394 By default, the log output format is very poor, as it only contains the
2395 source and destination addresses, and the instance name. By specifying
2396 "option httplog", each log line turns into a much richer format including,
2397 but not limited to, the HTTP request, the connection timers, the session
2398 status, the connections numbers, the captured headers and cookies, the
2399 frontend, backend and server name, and of course the source address and
2400 ports.
2401
2402 This option may be set either in the frontend or the backend.
2403
Emeric Brun3a058f32009-06-30 18:26:00 +02002404 If this option has been enabled in a "defaults" section, it can be disabled
2405 in a specific instance by prepending the "no" keyword before it. Specifying
2406 only "option httplog" will automatically clear the 'clf' mode if it was set
2407 by default.
2408
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002409 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01002410
Willy Tarreau55165fe2009-05-10 12:02:55 +02002411
2412option http_proxy
2413no option http_proxy
2414 Enable or disable plain HTTP proxy mode
2415 May be used in sections : defaults | frontend | listen | backend
2416 yes | yes | yes | yes
2417 Arguments : none
2418
2419 It sometimes happens that people need a pure HTTP proxy which understands
2420 basic proxy requests without caching nor any fancy feature. In this case,
2421 it may be worth setting up an HAProxy instance with the "option http_proxy"
2422 set. In this mode, no server is declared, and the connection is forwarded to
2423 the IP address and port found in the URL after the "http://" scheme.
2424
2425 No host address resolution is performed, so this only works when pure IP
2426 addresses are passed. Since this option's usage perimeter is rather limited,
2427 it will probably be used only by experts who know they need exactly it. Last,
2428 if the clients are susceptible of sending keep-alive requests, it will be
2429 needed to add "option http_close" to ensure that all requests will correctly
2430 be analyzed.
2431
2432 If this option has been enabled in a "defaults" section, it can be disabled
2433 in a specific instance by prepending the "no" keyword before it.
2434
2435 Example :
2436 # this backend understands HTTP proxy requests and forwards them directly.
2437 backend direct_forward
2438 option httpclose
2439 option http_proxy
2440
2441 See also : "option httpclose"
2442
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002443
2444option log-separate-errors
2445no option log-separate-errors
2446 Change log level for non-completely successful connections
2447 May be used in sections : defaults | frontend | listen | backend
2448 yes | yes | yes | no
2449 Arguments : none
2450
2451 Sometimes looking for errors in logs is not easy. This option makes haproxy
2452 raise the level of logs containing potentially interesting information such
2453 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
2454 level changes from "info" to "err". This makes it possible to log them
2455 separately to a different file with most syslog daemons. Be careful not to
2456 remove them from the original file, otherwise you would lose ordering which
2457 provides very important information.
2458
2459 Using this option, large sites dealing with several thousand connections per
2460 second may log normal traffic to a rotating buffer and only archive smaller
2461 error logs.
2462
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002463 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02002464 logging.
2465
Willy Tarreauc27debf2008-01-06 08:57:02 +01002466
2467option logasap
2468no option logasap
2469 Enable or disable early logging of HTTP requests
2470 May be used in sections : defaults | frontend | listen | backend
2471 yes | yes | yes | no
2472 Arguments : none
2473
2474 By default, HTTP requests are logged upon termination so that the total
2475 transfer time and the number of bytes appear in the logs. When large objects
2476 are being transferred, it may take a while before the request appears in the
2477 logs. Using "option logasap", the request gets logged as soon as the server
2478 sends the complete headers. The only missing information in the logs will be
2479 the total number of bytes which will indicate everything except the amount
2480 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002481 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01002482 "Content-Length" response header so that the logs at least indicate how many
2483 bytes are expected to be transferred.
2484
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002485 Examples :
2486 listen http_proxy 0.0.0.0:80
2487 mode http
2488 option httplog
2489 option logasap
2490 log 192.168.2.200 local3
2491
2492 >>> Feb 6 12:14:14 localhost \
2493 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
2494 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
2495 "GET /image.iso HTTP/1.0"
2496
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002497 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01002498 logging.
2499
2500
Willy Tarreaua453bdd2008-01-08 19:50:52 +01002501option nolinger
2502no option nolinger
2503 Enable or disable immediate session ressource cleaning after close
2504 May be used in sections: defaults | frontend | listen | backend
2505 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01002506 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01002507
2508 When clients or servers abort connections in a dirty way (eg: they are
2509 physically disconnected), the session timeouts triggers and the session is
2510 closed. But it will remain in FIN_WAIT1 state for some time in the system,
2511 using some resources and possibly limiting the ability to establish newer
2512 connections.
2513
2514 When this happens, it is possible to activate "option nolinger" which forces
2515 the system to immediately remove any socket's pending data on close. Thus,
2516 the session is instantly purged from the system's tables. This usually has
2517 side effects such as increased number of TCP resets due to old retransmits
2518 getting immediately rejected. Some firewalls may sometimes complain about
2519 this too.
2520
2521 For this reason, it is not recommended to use this option when not absolutely
2522 needed. You know that you need it when you have thousands of FIN_WAIT1
2523 sessions on your system (TIME_WAIT ones do not count).
2524
2525 This option may be used both on frontends and backends, depending on the side
2526 where it is required. Use it on the frontend for clients, and on the backend
2527 for servers.
2528
2529 If this option has been enabled in a "defaults" section, it can be disabled
2530 in a specific instance by prepending the "no" keyword before it.
2531
2532
Willy Tarreau55165fe2009-05-10 12:02:55 +02002533option originalto [ except <network> ] [ header <name> ]
2534 Enable insertion of the X-Original-To header to requests sent to servers
2535 May be used in sections : defaults | frontend | listen | backend
2536 yes | yes | yes | yes
2537 Arguments :
2538 <network> is an optional argument used to disable this option for sources
2539 matching <network>
2540 <name> an optional argument to specify a different "X-Original-To"
2541 header name.
2542
2543 Since HAProxy can work in transparent mode, every request from a client can
2544 be redirected to the proxy and HAProxy itself can proxy every request to a
2545 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
2546 be lost. This is annoying when you want access rules based on destination ip
2547 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
2548 added by HAProxy to all requests sent to the server. This header contains a
2549 value representing the original destination IP address. Since this must be
2550 configured to always use the last occurrence of this header only. Note that
2551 only the last occurrence of the header must be used, since it is really
2552 possible that the client has already brought one.
2553
2554 The keyword "header" may be used to supply a different header name to replace
2555 the default "X-Original-To". This can be useful where you might already
2556 have a "X-Original-To" header from a different application, and you need
2557 preserve it. Also if your backend server doesn't use the "X-Original-To"
2558 header and requires different one.
2559
2560 Sometimes, a same HAProxy instance may be shared between a direct client
2561 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
2562 used to decrypt HTTPS traffic). It is possible to disable the addition of the
2563 header for a known source address or network by adding the "except" keyword
2564 followed by the network address. In this case, any source IP matching the
2565 network will not cause an addition of this header. Most common uses are with
2566 private networks or 127.0.0.1.
2567
2568 This option may be specified either in the frontend or in the backend. If at
2569 least one of them uses it, the header will be added. Note that the backend's
2570 setting of the header subargument takes precedence over the frontend's if
2571 both are defined.
2572
2573 It is important to note that as long as HAProxy does not support keep-alive
2574 connections, only the first request of a connection will receive the header.
2575 For this reason, it is important to ensure that "option httpclose" is set
2576 when using this option.
2577
2578 Examples :
2579 # Original Destination address
2580 frontend www
2581 mode http
2582 option originalto except 127.0.0.1
2583
2584 # Those servers want the IP Address in X-Client-Dst
2585 backend www
2586 mode http
2587 option originalto header X-Client-Dst
2588
2589 See also : "option httpclose"
2590
2591
Willy Tarreaua453bdd2008-01-08 19:50:52 +01002592option persist
2593no option persist
2594 Enable or disable forced persistence on down servers
2595 May be used in sections: defaults | frontend | listen | backend
2596 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01002597 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01002598
2599 When an HTTP request reaches a backend with a cookie which references a dead
2600 server, by default it is redispatched to another server. It is possible to
2601 force the request to be sent to the dead server first using "option persist"
2602 if absolutely needed. A common use case is when servers are under extreme
2603 load and spend their time flapping. In this case, the users would still be
2604 directed to the server they opened the session on, in the hope they would be
2605 correctly served. It is recommended to use "option redispatch" in conjunction
2606 with this option so that in the event it would not be possible to connect to
2607 the server at all (server definitely dead), the client would finally be
2608 redirected to another valid server.
2609
2610 If this option has been enabled in a "defaults" section, it can be disabled
2611 in a specific instance by prepending the "no" keyword before it.
2612
2613 See also : "option redispatch", "retries"
2614
2615
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01002616option redispatch
2617no option redispatch
2618 Enable or disable session redistribution in case of connection failure
2619 May be used in sections: defaults | frontend | listen | backend
2620 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01002621 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01002622
2623 In HTTP mode, if a server designated by a cookie is down, clients may
2624 definitely stick to it because they cannot flush the cookie, so they will not
2625 be able to access the service anymore.
2626
2627 Specifying "option redispatch" will allow the proxy to break their
2628 persistence and redistribute them to a working server.
2629
2630 It also allows to retry last connection to another server in case of multiple
2631 connection failures. Of course, it requires having "retries" set to a nonzero
2632 value.
2633
2634 This form is the preferred form, which replaces both the "redispatch" and
2635 "redisp" keywords.
2636
2637 If this option has been enabled in a "defaults" section, it can be disabled
2638 in a specific instance by prepending the "no" keyword before it.
2639
2640 See also : "redispatch", "retries"
2641
Willy Tarreaua453bdd2008-01-08 19:50:52 +01002642
2643option smtpchk
2644option smtpchk <hello> <domain>
2645 Use SMTP health checks for server testing
2646 May be used in sections : defaults | frontend | listen | backend
2647 yes | no | yes | yes
2648 Arguments :
2649 <hello> is an optional argument. It is the "hello" command to use. It can
2650 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
2651 values will be turned into the default command ("HELO").
2652
2653 <domain> is the domain name to present to the server. It may only be
2654 specified (and is mandatory) if the hello command has been
2655 specified. By default, "localhost" is used.
2656
2657 When "option smtpchk" is set, the health checks will consist in TCP
2658 connections followed by an SMTP command. By default, this command is
2659 "HELO localhost". The server's return code is analyzed and only return codes
2660 starting with a "2" will be considered as valid. All other responses,
2661 including a lack of response will constitute an error and will indicate a
2662 dead server.
2663
2664 This test is meant to be used with SMTP servers or relays. Depending on the
2665 request, it is possible that some servers do not log each connection attempt,
2666 so you may want to experiment to improve the behaviour. Using telnet on port
2667 25 is often easier than adjusting the configuration.
2668
2669 Most often, an incoming SMTP server needs to see the client's IP address for
2670 various purposes, including spam filtering, anti-spoofing and logging. When
2671 possible, it is often wise to masquerade the client's IP address when
2672 connecting to the server using the "usesrc" argument of the "source" keyword,
2673 which requires the cttproxy feature to be compiled in.
2674
2675 Example :
2676 option smtpchk HELO mydomain.org
2677
2678 See also : "option httpchk", "source"
2679
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01002680
Willy Tarreauff4f82d2009-02-06 11:28:13 +01002681option splice-auto
2682no option splice-auto
2683 Enable or disable automatic kernel acceleration on sockets in both directions
2684 May be used in sections : defaults | frontend | listen | backend
2685 yes | yes | yes | yes
2686 Arguments : none
2687
2688 When this option is enabled either on a frontend or on a backend, haproxy
2689 will automatically evaluate the opportunity to use kernel tcp splicing to
2690 forward data between the client and the server, in either direction. Haproxy
2691 uses heuristics to estimate if kernel splicing might improve performance or
2692 not. Both directions are handled independantly. Note that the heuristics used
2693 are not much aggressive in order to limit excessive use of splicing. This
2694 option requires splicing to be enabled at compile time, and may be globally
2695 disabled with the global option "nosplice". Since splice uses pipes, using it
2696 requires that there are enough spare pipes.
2697
2698 Important note: kernel-based TCP splicing is a Linux-specific feature which
2699 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
2700 transfer data between sockets without copying these data to user-space, thus
2701 providing noticeable performance gains and CPU cycles savings. Since many
2702 early implementations are buggy, corrupt data and/or are inefficient, this
2703 feature is not enabled by default, and it should be used with extreme care.
2704 While it is not possible to detect the correctness of an implementation,
2705 2.6.29 is the first version offering a properly working implementation. In
2706 case of doubt, splicing may be globally disabled using the global "nosplice"
2707 keyword.
2708
2709 Example :
2710 option splice-auto
2711
2712 If this option has been enabled in a "defaults" section, it can be disabled
2713 in a specific instance by prepending the "no" keyword before it.
2714
2715 See also : "option splice-request", "option splice-response", and global
2716 options "nosplice" and "maxpipes"
2717
2718
2719option splice-request
2720no option splice-request
2721 Enable or disable automatic kernel acceleration on sockets for requests
2722 May be used in sections : defaults | frontend | listen | backend
2723 yes | yes | yes | yes
2724 Arguments : none
2725
2726 When this option is enabled either on a frontend or on a backend, haproxy
2727 will user kernel tcp splicing whenever possible to forward data going from
2728 the client to the server. It might still use the recv/send scheme if there
2729 are no spare pipes left. This option requires splicing to be enabled at
2730 compile time, and may be globally disabled with the global option "nosplice".
2731 Since splice uses pipes, using it requires that there are enough spare pipes.
2732
2733 Important note: see "option splice-auto" for usage limitations.
2734
2735 Example :
2736 option splice-request
2737
2738 If this option has been enabled in a "defaults" section, it can be disabled
2739 in a specific instance by prepending the "no" keyword before it.
2740
2741 See also : "option splice-auto", "option splice-response", and global options
2742 "nosplice" and "maxpipes"
2743
2744
2745option splice-response
2746no option splice-response
2747 Enable or disable automatic kernel acceleration on sockets for responses
2748 May be used in sections : defaults | frontend | listen | backend
2749 yes | yes | yes | yes
2750 Arguments : none
2751
2752 When this option is enabled either on a frontend or on a backend, haproxy
2753 will user kernel tcp splicing whenever possible to forward data going from
2754 the server to the client. It might still use the recv/send scheme if there
2755 are no spare pipes left. This option requires splicing to be enabled at
2756 compile time, and may be globally disabled with the global option "nosplice".
2757 Since splice uses pipes, using it requires that there are enough spare pipes.
2758
2759 Important note: see "option splice-auto" for usage limitations.
2760
2761 Example :
2762 option splice-response
2763
2764 If this option has been enabled in a "defaults" section, it can be disabled
2765 in a specific instance by prepending the "no" keyword before it.
2766
2767 See also : "option splice-auto", "option splice-request", and global options
2768 "nosplice" and "maxpipes"
2769
2770
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002771option srvtcpka
2772no option srvtcpka
2773 Enable or disable the sending of TCP keepalive packets on the server side
2774 May be used in sections : defaults | frontend | listen | backend
2775 yes | no | yes | yes
2776 Arguments : none
2777
2778 When there is a firewall or any session-aware component between a client and
2779 a server, and when the protocol involves very long sessions with long idle
2780 periods (eg: remote desktops), there is a risk that one of the intermediate
2781 components decides to expire a session which has remained idle for too long.
2782
2783 Enabling socket-level TCP keep-alives makes the system regularly send packets
2784 to the other end of the connection, leaving it active. The delay between
2785 keep-alive probes is controlled by the system only and depends both on the
2786 operating system and its tuning parameters.
2787
2788 It is important to understand that keep-alive packets are neither emitted nor
2789 received at the application level. It is only the network stacks which sees
2790 them. For this reason, even if one side of the proxy already uses keep-alives
2791 to maintain its connection alive, those keep-alive packets will not be
2792 forwarded to the other side of the proxy.
2793
2794 Please note that this has nothing to do with HTTP keep-alive.
2795
2796 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
2797 server side of a connection, which should help when session expirations are
2798 noticed between HAProxy and a server.
2799
2800 If this option has been enabled in a "defaults" section, it can be disabled
2801 in a specific instance by prepending the "no" keyword before it.
2802
2803 See also : "option clitcpka", "option tcpka"
2804
2805
Willy Tarreaua453bdd2008-01-08 19:50:52 +01002806option ssl-hello-chk
2807 Use SSLv3 client hello health checks for server testing
2808 May be used in sections : defaults | frontend | listen | backend
2809 yes | no | yes | yes
2810 Arguments : none
2811
2812 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
2813 possible to test that the server correctly talks SSL instead of just testing
2814 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
2815 SSLv3 client hello messages are sent once the connection is established to
2816 the server, and the response is analyzed to find an SSL server hello message.
2817 The server is considered valid only when the response contains this server
2818 hello message.
2819
2820 All servers tested till there correctly reply to SSLv3 client hello messages,
2821 and most servers tested do not even log the requests containing only hello
2822 messages, which is appreciable.
2823
2824 See also: "option httpchk"
2825
2826
Willy Tarreau9ea05a72009-06-14 12:07:01 +02002827option tcp-smart-accept
2828no option tcp-smart-accept
2829 Enable or disable the saving of one ACK packet during the accept sequence
2830 May be used in sections : defaults | frontend | listen | backend
2831 yes | yes | yes | no
2832 Arguments : none
2833
2834 When an HTTP connection request comes in, the system acknowledges it on
2835 behalf of HAProxy, then the client immediately sends its request, and the
2836 system acknowledges it too while it is notifying HAProxy about the new
2837 connection. HAProxy then reads the request and responds. This means that we
2838 have one TCP ACK sent by the system for nothing, because the request could
2839 very well be acknowledged by HAProxy when it sends its response.
2840
2841 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
2842 sending this useless ACK on platforms which support it (currently at least
2843 Linux). It must not cause any problem, because the system will send it anyway
2844 after 40 ms if the response takes more time than expected to come.
2845
2846 During complex network debugging sessions, it may be desirable to disable
2847 this optimization because delayed ACKs can make troubleshooting more complex
2848 when trying to identify where packets are delayed. It is then possible to
2849 fall back to normal behaviour by specifying "no option tcp-smart-accept".
2850
2851 It is also possible to force it for non-HTTP proxies by simply specifying
2852 "option tcp-smart-accept". For instance, it can make sense with some services
2853 such as SMTP where the server speaks first.
2854
2855 It is recommended to avoid forcing this option in a defaults section. In case
2856 of doubt, consider setting it back to automatic values by prepending the
2857 "default" keyword before it, or disabling it using the "no" keyword.
2858
Willy Tarreaud88edf22009-06-14 15:48:17 +02002859 See also : "option tcp-smart-connect"
2860
2861
2862option tcp-smart-connect
2863no option tcp-smart-connect
2864 Enable or disable the saving of one ACK packet during the connect sequence
2865 May be used in sections : defaults | frontend | listen | backend
2866 yes | no | yes | yes
2867 Arguments : none
2868
2869 On certain systems (at least Linux), HAProxy can ask the kernel not to
2870 immediately send an empty ACK upon a connection request, but to directly
2871 send the buffer request instead. This saves one packet on the network and
2872 thus boosts performance. It can also be useful for some servers, because they
2873 immediately get the request along with the incoming connection.
2874
2875 This feature is enabled when "option tcp-smart-connect" is set in a backend.
2876 It is not enabled by default because it makes network troubleshooting more
2877 complex.
2878
2879 It only makes sense to enable it with protocols where the client speaks first
2880 such as HTTP. In other situations, if there is no data to send in place of
2881 the ACK, a normal ACK is sent.
2882
2883 If this option has been enabled in a "defaults" section, it can be disabled
2884 in a specific instance by prepending the "no" keyword before it.
2885
2886 See also : "option tcp-smart-accept"
2887
Willy Tarreau9ea05a72009-06-14 12:07:01 +02002888
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002889option tcpka
2890 Enable or disable the sending of TCP keepalive packets on both sides
2891 May be used in sections : defaults | frontend | listen | backend
2892 yes | yes | yes | yes
2893 Arguments : none
2894
2895 When there is a firewall or any session-aware component between a client and
2896 a server, and when the protocol involves very long sessions with long idle
2897 periods (eg: remote desktops), there is a risk that one of the intermediate
2898 components decides to expire a session which has remained idle for too long.
2899
2900 Enabling socket-level TCP keep-alives makes the system regularly send packets
2901 to the other end of the connection, leaving it active. The delay between
2902 keep-alive probes is controlled by the system only and depends both on the
2903 operating system and its tuning parameters.
2904
2905 It is important to understand that keep-alive packets are neither emitted nor
2906 received at the application level. It is only the network stacks which sees
2907 them. For this reason, even if one side of the proxy already uses keep-alives
2908 to maintain its connection alive, those keep-alive packets will not be
2909 forwarded to the other side of the proxy.
2910
2911 Please note that this has nothing to do with HTTP keep-alive.
2912
2913 Using option "tcpka" enables the emission of TCP keep-alive probes on both
2914 the client and server sides of a connection. Note that this is meaningful
2915 only in "defaults" or "listen" sections. If this option is used in a
2916 frontend, only the client side will get keep-alives, and if this option is
2917 used in a backend, only the server side will get keep-alives. For this
2918 reason, it is strongly recommended to explicitly use "option clitcpka" and
2919 "option srvtcpka" when the configuration is split between frontends and
2920 backends.
2921
2922 See also : "option clitcpka", "option srvtcpka"
2923
Willy Tarreau844e3c52008-01-11 16:28:18 +01002924
2925option tcplog
2926 Enable advanced logging of TCP connections with session state and timers
2927 May be used in sections : defaults | frontend | listen | backend
2928 yes | yes | yes | yes
2929 Arguments : none
2930
2931 By default, the log output format is very poor, as it only contains the
2932 source and destination addresses, and the instance name. By specifying
2933 "option tcplog", each log line turns into a much richer format including, but
2934 not limited to, the connection timers, the session status, the connections
2935 numbers, the frontend, backend and server name, and of course the source
2936 address and ports. This option is useful for pure TCP proxies in order to
2937 find which of the client or server disconnects or times out. For normal HTTP
2938 proxies, it's better to use "option httplog" which is even more complete.
2939
2940 This option may be set either in the frontend or the backend.
2941
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002942 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01002943
2944
Willy Tarreau844e3c52008-01-11 16:28:18 +01002945option transparent
2946no option transparent
2947 Enable client-side transparent proxying
2948 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01002949 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01002950 Arguments : none
2951
2952 This option was introduced in order to provide layer 7 persistence to layer 3
2953 load balancers. The idea is to use the OS's ability to redirect an incoming
2954 connection for a remote address to a local process (here HAProxy), and let
2955 this process know what address was initially requested. When this option is
2956 used, sessions without cookies will be forwarded to the original destination
2957 IP address of the incoming request (which should match that of another
2958 equipment), while requests with cookies will still be forwarded to the
2959 appropriate server.
2960
2961 Note that contrary to a common belief, this option does NOT make HAProxy
2962 present the client's IP to the server when establishing the connection.
2963
Willy Tarreaueabeafa2008-01-16 16:17:06 +01002964 See also: the "usersrc" argument of the "source" keyword, and the
2965 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01002966
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002967
Emeric Brun647caf12009-06-30 17:57:00 +02002968persist rdp-cookie
2969persist rdp-cookie(name)
2970 Enable RDP cookie-based persistence
2971 May be used in sections : defaults | frontend | listen | backend
2972 yes | no | yes | yes
2973 Arguments :
2974 <name> is the optional name of the RDP cookie to check. If omitted, the
2975 default cookie name "mstshash" will be used. There currently is
2976 no valid reason to change this name.
2977
2978 This statement enables persistence based on an RDP cookie. The RDP cookie
2979 contains all information required to find the server in the list of known
2980 servers. So when this option is set in the backend, the request is analysed
2981 and if an RDP cookie is found, it is decoded. If it matches a known server
2982 which is still UP (or if "option persist" is set), then the connection is
2983 forwarded to this server.
2984
2985 Note that this only makes sense in a TCP backend, but for this to work, the
2986 frontend must have waited long enough to ensure that an RDP cookie is present
2987 in the request buffer. This is the same requirement as with the "rdp-cookie"
2988 load-balancing method. Thus it is higly recommended to put all statements in
2989 a single "listen" section.
2990
2991 Example :
2992 listen tse-farm
2993 bind :3389
2994 # wait up to 5s for an RDP cookie in the request
2995 tcp-request inspect-delay 5s
2996 tcp-request content accept if RDP_COOKIE
2997 # apply RDP cookie persistence
2998 persist rdp-cookie
2999 # if server is unknown, let's balance on the same cookie.
3000 # alternatively, "balance leastconn" may be useful too.
3001 balance rdp-cookie
3002 server srv1 1.1.1.1:3389
3003 server srv2 1.1.1.2:3389
3004
3005 See also : "balance rdp-cookie", "tcp-request" and the "req_rdp_cookie" ACL.
3006
3007
Willy Tarreau3a7d2072009-03-05 23:48:25 +01003008rate-limit sessions <rate>
3009 Set a limit on the number of new sessions accepted per second on a frontend
3010 May be used in sections : defaults | frontend | listen | backend
3011 yes | yes | yes | no
3012 Arguments :
3013 <rate> The <rate> parameter is an integer designating the maximum number
3014 of new sessions per second to accept on the frontend.
3015
3016 When the frontend reaches the specified number of new sessions per second, it
3017 stops accepting new connections until the rate drops below the limit again.
3018 During this time, the pending sessions will be kept in the socket's backlog
3019 (in system buffers) and haproxy will not even be aware that sessions are
3020 pending. When applying very low limit on a highly loaded service, it may make
3021 sense to increase the socket's backlog using the "backlog" keyword.
3022
3023 This feature is particularly efficient at blocking connection-based attacks
3024 or service abuse on fragile servers. Since the session rate is measured every
3025 millisecond, it is extremely accurate. Also, the limit applies immediately,
3026 no delay is needed at all to detect the threshold.
3027
3028 Example : limit the connection rate on SMTP to 10 per second max
3029 listen smtp
3030 mode tcp
3031 bind :25
3032 rate-limit sessions 10
3033 server 127.0.0.1:1025
3034
3035 Note : when the maximum rate is reached, the frontend's status appears as
3036 "FULL" in the statistics, exactly as when it is saturated.
3037
3038 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
3039
3040
Willy Tarreau0140f252008-11-19 21:07:09 +01003041redirect location <to> [code <code>] <option> {if | unless} <condition>
3042redirect prefix <to> [code <code>] <option> {if | unless} <condition>
Willy Tarreaub463dfb2008-06-07 23:08:56 +02003043 Return an HTTP redirection if/unless a condition is matched
3044 May be used in sections : defaults | frontend | listen | backend
3045 no | yes | yes | yes
3046
3047 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreau0140f252008-11-19 21:07:09 +01003048 response.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02003049
Willy Tarreau0140f252008-11-19 21:07:09 +01003050 Arguments :
3051 <to> With "redirect location", the exact value in <to> is placed into
3052 the HTTP "Location" header. In case of "redirect prefix", the
3053 "Location" header is built from the concatenation of <to> and the
3054 complete URI, including the query string, unless the "drop-query"
Willy Tarreaufe651a52008-11-19 21:15:17 +01003055 option is specified (see below). As a special case, if <to>
3056 equals exactly "/" in prefix mode, then nothing is inserted
3057 before the original URI. It allows one to redirect to the same
3058 URL.
Willy Tarreau0140f252008-11-19 21:07:09 +01003059
3060 <code> The code is optional. It indicates which type of HTTP redirection
3061 is desired. Only codes 301, 302 and 303 are supported, and 302 is
3062 used if no code is specified. 301 means "Moved permanently", and
3063 a browser may cache the Location. 302 means "Moved permanently"
3064 and means that the browser should not cache the redirection. 303
3065 is equivalent to 302 except that the browser will fetch the
3066 location with a GET method.
3067
3068 <option> There are several options which can be specified to adjust the
3069 expected behaviour of a redirection :
3070
3071 - "drop-query"
3072 When this keyword is used in a prefix-based redirection, then the
3073 location will be set without any possible query-string, which is useful
3074 for directing users to a non-secure page for instance. It has no effect
3075 with a location-type redirect.
3076
3077 - "set-cookie NAME[=value]"
3078 A "Set-Cookie" header will be added with NAME (and optionally "=value")
3079 to the response. This is sometimes used to indicate that a user has
3080 been seen, for instance to protect against some types of DoS. No other
3081 cookie option is added, so the cookie will be a session cookie. Note
3082 that for a browser, a sole cookie name without an equal sign is
3083 different from a cookie with an equal sign.
3084
3085 - "clear-cookie NAME[=]"
3086 A "Set-Cookie" header will be added with NAME (and optionally "="), but
3087 with the "Max-Age" attribute set to zero. This will tell the browser to
3088 delete this cookie. It is useful for instance on logout pages. It is
3089 important to note that clearing the cookie "NAME" will not remove a
3090 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
3091 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02003092
3093 Example: move the login URL only to HTTPS.
3094 acl clear dst_port 80
3095 acl secure dst_port 8080
3096 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01003097 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01003098 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01003099 acl cookie_set hdr_sub(cookie) SEEN=1
3100
3101 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01003102 redirect prefix https://mysite.com if login_page !secure
3103 redirect prefix http://mysite.com drop-query if login_page !uid_given
3104 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01003105 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02003106
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003107 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02003108
3109
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003110redisp (deprecated)
3111redispatch (deprecated)
3112 Enable or disable session redistribution in case of connection failure
3113 May be used in sections: defaults | frontend | listen | backend
3114 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003115 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003116
3117 In HTTP mode, if a server designated by a cookie is down, clients may
3118 definitely stick to it because they cannot flush the cookie, so they will not
3119 be able to access the service anymore.
3120
3121 Specifying "redispatch" will allow the proxy to break their persistence and
3122 redistribute them to a working server.
3123
3124 It also allows to retry last connection to another server in case of multiple
3125 connection failures. Of course, it requires having "retries" set to a nonzero
3126 value.
3127
3128 This form is deprecated, do not use it in any new configuration, use the new
3129 "option redispatch" instead.
3130
3131 See also : "option redispatch"
3132
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003133
Willy Tarreau303c0352008-01-17 19:01:39 +01003134reqadd <string>
3135 Add a header at the end of the HTTP request
3136 May be used in sections : defaults | frontend | listen | backend
3137 no | yes | yes | yes
3138 Arguments :
3139 <string> is the complete line to be added. Any space or known delimiter
3140 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003141 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01003142
3143 A new line consisting in <string> followed by a line feed will be added after
3144 the last header of an HTTP request.
3145
3146 Header transformations only apply to traffic which passes through HAProxy,
3147 and not to traffic generated by HAProxy, such as health-checks or error
3148 responses.
3149
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003150 See also: "rspadd" and section 6 about HTTP header manipulation
Willy Tarreau303c0352008-01-17 19:01:39 +01003151
3152
3153reqallow <search>
3154reqiallow <search> (ignore case)
3155 Definitely allow an HTTP request if a line matches a regular expression
3156 May be used in sections : defaults | frontend | listen | backend
3157 no | yes | yes | yes
3158 Arguments :
3159 <search> is the regular expression applied to HTTP headers and to the
3160 request line. This is an extended regular expression. Parenthesis
3161 grouping is supported and no preliminary backslash is required.
3162 Any space or known delimiter must be escaped using a backslash
3163 ('\'). The pattern applies to a full line at a time. The
3164 "reqallow" keyword strictly matches case while "reqiallow"
3165 ignores case.
3166
3167 A request containing any line which matches extended regular expression
3168 <search> will mark the request as allowed, even if any later test would
3169 result in a deny. The test applies both to the request line and to request
3170 headers. Keep in mind that URLs in request line are case-sensitive while
3171 header names are not.
3172
3173 It is easier, faster and more powerful to use ACLs to write access policies.
3174 Reqdeny, reqallow and reqpass should be avoided in new designs.
3175
3176 Example :
3177 # allow www.* but refuse *.local
3178 reqiallow ^Host:\ www\.
3179 reqideny ^Host:\ .*\.local
3180
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003181 See also: "reqdeny", "acl", "block" and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003182 manipulation
3183
3184
3185reqdel <search>
3186reqidel <search> (ignore case)
3187 Delete all headers matching a regular expression in an HTTP request
3188 May be used in sections : defaults | frontend | listen | backend
3189 no | yes | yes | yes
3190 Arguments :
3191 <search> is the regular expression applied to HTTP headers and to the
3192 request line. This is an extended regular expression. Parenthesis
3193 grouping is supported and no preliminary backslash is required.
3194 Any space or known delimiter must be escaped using a backslash
3195 ('\'). The pattern applies to a full line at a time. The "reqdel"
3196 keyword strictly matches case while "reqidel" ignores case.
3197
3198 Any header line matching extended regular expression <search> in the request
3199 will be completely deleted. Most common use of this is to remove unwanted
3200 and/or dangerous headers or cookies from a request before passing it to the
3201 next servers.
3202
3203 Header transformations only apply to traffic which passes through HAProxy,
3204 and not to traffic generated by HAProxy, such as health-checks or error
3205 responses. Keep in mind that header names are not case-sensitive.
3206
3207 Example :
3208 # remove X-Forwarded-For header and SERVER cookie
3209 reqidel ^X-Forwarded-For:.*
3210 reqidel ^Cookie:.*SERVER=
3211
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003212 See also: "reqadd", "reqrep", "rspdel" and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003213 manipulation
3214
3215
3216reqdeny <search>
3217reqideny <search> (ignore case)
3218 Deny an HTTP request if a line matches a regular expression
3219 May be used in sections : defaults | frontend | listen | backend
3220 no | yes | yes | yes
3221 Arguments :
3222 <search> is the regular expression applied to HTTP headers and to the
3223 request line. This is an extended regular expression. Parenthesis
3224 grouping is supported and no preliminary backslash is required.
3225 Any space or known delimiter must be escaped using a backslash
3226 ('\'). The pattern applies to a full line at a time. The
3227 "reqdeny" keyword strictly matches case while "reqideny" ignores
3228 case.
3229
3230 A request containing any line which matches extended regular expression
3231 <search> will mark the request as denied, even if any later test would
3232 result in an allow. The test applies both to the request line and to request
3233 headers. Keep in mind that URLs in request line are case-sensitive while
3234 header names are not.
3235
Willy Tarreauced27012008-01-17 20:35:34 +01003236 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003237 complete request has been parsed. This is consistent with what is practiced
Willy Tarreauced27012008-01-17 20:35:34 +01003238 using ACLs.
3239
Willy Tarreau303c0352008-01-17 19:01:39 +01003240 It is easier, faster and more powerful to use ACLs to write access policies.
3241 Reqdeny, reqallow and reqpass should be avoided in new designs.
3242
3243 Example :
3244 # refuse *.local, then allow www.*
3245 reqideny ^Host:\ .*\.local
3246 reqiallow ^Host:\ www\.
3247
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003248 See also: "reqallow", "rspdeny", "acl", "block" and section 6 about HTTP
Willy Tarreau303c0352008-01-17 19:01:39 +01003249 header manipulation
3250
3251
3252reqpass <search>
3253reqipass <search> (ignore case)
3254 Ignore any HTTP request line matching a regular expression in next rules
3255 May be used in sections : defaults | frontend | listen | backend
3256 no | yes | yes | yes
3257 Arguments :
3258 <search> is the regular expression applied to HTTP headers and to the
3259 request line. This is an extended regular expression. Parenthesis
3260 grouping is supported and no preliminary backslash is required.
3261 Any space or known delimiter must be escaped using a backslash
3262 ('\'). The pattern applies to a full line at a time. The
3263 "reqpass" keyword strictly matches case while "reqipass" ignores
3264 case.
3265
3266 A request containing any line which matches extended regular expression
3267 <search> will skip next rules, without assigning any deny or allow verdict.
3268 The test applies both to the request line and to request headers. Keep in
3269 mind that URLs in request line are case-sensitive while header names are not.
3270
3271 It is easier, faster and more powerful to use ACLs to write access policies.
3272 Reqdeny, reqallow and reqpass should be avoided in new designs.
3273
3274 Example :
3275 # refuse *.local, then allow www.*, but ignore "www.private.local"
3276 reqipass ^Host:\ www.private\.local
3277 reqideny ^Host:\ .*\.local
3278 reqiallow ^Host:\ www\.
3279
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003280 See also: "reqallow", "reqdeny", "acl", "block" and section 6 about HTTP
Willy Tarreau303c0352008-01-17 19:01:39 +01003281 header manipulation
3282
3283
3284reqrep <search> <string>
3285reqirep <search> <string> (ignore case)
3286 Replace a regular expression with a string in an HTTP request line
3287 May be used in sections : defaults | frontend | listen | backend
3288 no | yes | yes | yes
3289 Arguments :
3290 <search> is the regular expression applied to HTTP headers and to the
3291 request line. This is an extended regular expression. Parenthesis
3292 grouping is supported and no preliminary backslash is required.
3293 Any space or known delimiter must be escaped using a backslash
3294 ('\'). The pattern applies to a full line at a time. The "reqrep"
3295 keyword strictly matches case while "reqirep" ignores case.
3296
3297 <string> is the complete line to be added. Any space or known delimiter
3298 must be escaped using a backslash ('\'). References to matched
3299 pattern groups are possible using the common \N form, with N
3300 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003301 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01003302
3303 Any line matching extended regular expression <search> in the request (both
3304 the request line and header lines) will be completely replaced with <string>.
3305 Most common use of this is to rewrite URLs or domain names in "Host" headers.
3306
3307 Header transformations only apply to traffic which passes through HAProxy,
3308 and not to traffic generated by HAProxy, such as health-checks or error
3309 responses. Note that for increased readability, it is suggested to add enough
3310 spaces between the request and the response. Keep in mind that URLs in
3311 request line are case-sensitive while header names are not.
3312
3313 Example :
3314 # replace "/static/" with "/" at the beginning of any request path.
3315 reqrep ^([^\ ]*)\ /static/(.*) \1\ /\2
3316 # replace "www.mydomain.com" with "www" in the host name.
3317 reqirep ^Host:\ www.mydomain.com Host:\ www
3318
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003319 See also: "reqadd", "reqdel", "rsprep" and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003320 manipulation
3321
3322
3323reqtarpit <search>
3324reqitarpit <search> (ignore case)
3325 Tarpit an HTTP request containing a line matching a regular expression
3326 May be used in sections : defaults | frontend | listen | backend
3327 no | yes | yes | yes
3328 Arguments :
3329 <search> is the regular expression applied to HTTP headers and to the
3330 request line. This is an extended regular expression. Parenthesis
3331 grouping is supported and no preliminary backslash is required.
3332 Any space or known delimiter must be escaped using a backslash
3333 ('\'). The pattern applies to a full line at a time. The
3334 "reqtarpit" keyword strictly matches case while "reqitarpit"
3335 ignores case.
3336
3337 A request containing any line which matches extended regular expression
3338 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01003339 be kept open for a pre-defined time, then will return an HTTP error 500 so
3340 that the attacker does not suspect it has been tarpitted. The status 500 will
3341 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01003342 delay is defined by "timeout tarpit", or "timeout connect" if the former is
3343 not set.
3344
3345 The goal of the tarpit is to slow down robots attacking servers with
3346 identifiable requests. Many robots limit their outgoing number of connections
3347 and stay connected waiting for a reply which can take several minutes to
3348 come. Depending on the environment and attack, it may be particularly
3349 efficient at reducing the load on the network and firewalls.
3350
3351 Example :
3352 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
3353 # block all others.
3354 reqipass ^User-Agent:\.*(Mozilla|MSIE)
3355 reqitarpit ^User-Agent:
3356
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003357 See also: "reqallow", "reqdeny", "reqpass", and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003358 manipulation
3359
3360
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02003361retries <value>
3362 Set the number of retries to perform on a server after a connection failure
3363 May be used in sections: defaults | frontend | listen | backend
3364 yes | no | yes | yes
3365 Arguments :
3366 <value> is the number of times a connection attempt should be retried on
3367 a server when a connection either is refused or times out. The
3368 default value is 3.
3369
3370 It is important to understand that this value applies to the number of
3371 connection attempts, not full requests. When a connection has effectively
3372 been established to a server, there will be no more retry.
3373
3374 In order to avoid immediate reconnections to a server which is restarting,
3375 a turn-around timer of 1 second is applied before a retry occurs.
3376
3377 When "option redispatch" is set, the last retry may be performed on another
3378 server even if a cookie references a different server.
3379
3380 See also : "option redispatch"
3381
3382
Willy Tarreau303c0352008-01-17 19:01:39 +01003383rspadd <string>
3384 Add a header at the end of the HTTP response
3385 May be used in sections : defaults | frontend | listen | backend
3386 no | yes | yes | yes
3387 Arguments :
3388 <string> is the complete line to be added. Any space or known delimiter
3389 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003390 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01003391
3392 A new line consisting in <string> followed by a line feed will be added after
3393 the last header of an HTTP response.
3394
3395 Header transformations only apply to traffic which passes through HAProxy,
3396 and not to traffic generated by HAProxy, such as health-checks or error
3397 responses.
3398
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003399 See also: "reqadd" and section 6 about HTTP header manipulation
Willy Tarreau303c0352008-01-17 19:01:39 +01003400
3401
3402rspdel <search>
3403rspidel <search> (ignore case)
3404 Delete all headers matching a regular expression in an HTTP response
3405 May be used in sections : defaults | frontend | listen | backend
3406 no | yes | yes | yes
3407 Arguments :
3408 <search> is the regular expression applied to HTTP headers and to the
3409 response line. This is an extended regular expression, so
3410 parenthesis grouping is supported and no preliminary backslash
3411 is required. Any space or known delimiter must be escaped using
3412 a backslash ('\'). The pattern applies to a full line at a time.
3413 The "rspdel" keyword strictly matches case while "rspidel"
3414 ignores case.
3415
3416 Any header line matching extended regular expression <search> in the response
3417 will be completely deleted. Most common use of this is to remove unwanted
3418 and/or sensible headers or cookies from a response before passing it to the
3419 client.
3420
3421 Header transformations only apply to traffic which passes through HAProxy,
3422 and not to traffic generated by HAProxy, such as health-checks or error
3423 responses. Keep in mind that header names are not case-sensitive.
3424
3425 Example :
3426 # remove the Server header from responses
3427 reqidel ^Server:.*
3428
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003429 See also: "rspadd", "rsprep", "reqdel" and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003430 manipulation
3431
3432
3433rspdeny <search>
3434rspideny <search> (ignore case)
3435 Block an HTTP response if a line matches a regular expression
3436 May be used in sections : defaults | frontend | listen | backend
3437 no | yes | yes | yes
3438 Arguments :
3439 <search> is the regular expression applied to HTTP headers and to the
3440 response line. This is an extended regular expression, so
3441 parenthesis grouping is supported and no preliminary backslash
3442 is required. Any space or known delimiter must be escaped using
3443 a backslash ('\'). The pattern applies to a full line at a time.
3444 The "rspdeny" keyword strictly matches case while "rspideny"
3445 ignores case.
3446
3447 A response containing any line which matches extended regular expression
3448 <search> will mark the request as denied. The test applies both to the
3449 response line and to response headers. Keep in mind that header names are not
3450 case-sensitive.
3451
3452 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01003453 block the response before it reaches the client. If a response is denied, it
3454 will be replaced with an HTTP 502 error so that the client never retrieves
3455 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01003456
3457 It is easier, faster and more powerful to use ACLs to write access policies.
3458 Rspdeny should be avoided in new designs.
3459
3460 Example :
3461 # Ensure that no content type matching ms-word will leak
3462 rspideny ^Content-type:\.*/ms-word
3463
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003464 See also: "reqdeny", "acl", "block" and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003465 manipulation
3466
3467
3468rsprep <search> <string>
3469rspirep <search> <string> (ignore case)
3470 Replace a regular expression with a string in an HTTP response line
3471 May be used in sections : defaults | frontend | listen | backend
3472 no | yes | yes | yes
3473 Arguments :
3474 <search> is the regular expression applied to HTTP headers and to the
3475 response line. This is an extended regular expression, so
3476 parenthesis grouping is supported and no preliminary backslash
3477 is required. Any space or known delimiter must be escaped using
3478 a backslash ('\'). The pattern applies to a full line at a time.
3479 The "rsprep" keyword strictly matches case while "rspirep"
3480 ignores case.
3481
3482 <string> is the complete line to be added. Any space or known delimiter
3483 must be escaped using a backslash ('\'). References to matched
3484 pattern groups are possible using the common \N form, with N
3485 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003486 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01003487
3488 Any line matching extended regular expression <search> in the response (both
3489 the response line and header lines) will be completely replaced with
3490 <string>. Most common use of this is to rewrite Location headers.
3491
3492 Header transformations only apply to traffic which passes through HAProxy,
3493 and not to traffic generated by HAProxy, such as health-checks or error
3494 responses. Note that for increased readability, it is suggested to add enough
3495 spaces between the request and the response. Keep in mind that header names
3496 are not case-sensitive.
3497
3498 Example :
3499 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
3500 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
3501
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003502 See also: "rspadd", "rspdel", "reqrep" and section 6 about HTTP header
Willy Tarreau303c0352008-01-17 19:01:39 +01003503 manipulation
3504
3505
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003506server <name> <address>[:port] [param*]
3507 Declare a server in a backend
3508 May be used in sections : defaults | frontend | listen | backend
3509 no | no | yes | yes
3510 Arguments :
3511 <name> is the internal name assigned to this server. This name will
3512 appear in logs and alerts.
3513
3514 <address> is the IPv4 address of the server. Alternatively, a resolvable
3515 hostname is supported, but this name will be resolved during
3516 start-up.
3517
3518 <ports> is an optional port specification. If set, all connections will
3519 be sent to this port. If unset, the same port the client
3520 connected to will be used. The port may also be prefixed by a "+"
3521 or a "-". In this case, the server's port will be determined by
3522 adding this value to the client's port.
3523
3524 <param*> is a list of parameters for this server. The "server" keywords
3525 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003526 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003527
3528 Examples :
3529 server first 10.1.1.1:1080 cookie first check inter 1000
3530 server second 10.1.1.2:1080 cookie second check inter 1000
3531
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003532 See also : section 5 about server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003533
3534
3535source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01003536source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003537 Set the source address for outgoing connections
3538 May be used in sections : defaults | frontend | listen | backend
3539 yes | no | yes | yes
3540 Arguments :
3541 <addr> is the IPv4 address HAProxy will bind to before connecting to a
3542 server. This address is also used as a source for health checks.
3543 The default value of 0.0.0.0 means that the system will select
3544 the most appropriate address to reach its destination.
3545
3546 <port> is an optional port. It is normally not needed but may be useful
3547 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02003548 the system will select a free port. Note that port ranges are not
3549 supported in the backend. If you want to force port ranges, you
3550 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003551
3552 <addr2> is the IP address to present to the server when connections are
3553 forwarded in full transparent proxy mode. This is currently only
3554 supported on some patched Linux kernels. When this address is
3555 specified, clients connecting to the server will be presented
3556 with this address, while health checks will still use the address
3557 <addr>.
3558
3559 <port2> is the optional port to present to the server when connections
3560 are forwarded in full transparent proxy mode (see <addr2> above).
3561 The default value of zero means the system will select a free
3562 port.
3563
Willy Tarreaud53f96b2009-02-04 18:46:54 +01003564 <name> is an optional interface name to which to bind to for outgoing
3565 traffic. On systems supporting this features (currently, only
3566 Linux), this allows one to bind all traffic to the server to
3567 this interface even if it is not the one the system would select
3568 based on routing tables. This should be used with extreme care.
3569 Note that using this option requires root privileges.
3570
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003571 The "source" keyword is useful in complex environments where a specific
3572 address only is allowed to connect to the servers. It may be needed when a
3573 private address must be used through a public gateway for instance, and it is
3574 known that the system cannot determine the adequate source address by itself.
3575
3576 An extension which is available on certain patched Linux kernels may be used
3577 through the "usesrc" optional keyword. It makes it possible to connect to the
3578 servers with an IP address which does not belong to the system itself. This
3579 is called "full transparent proxy mode". For this to work, the destination
3580 servers have to route their traffic back to this address through the machine
3581 running HAProxy, and IP forwarding must generally be enabled on this machine.
3582
3583 In this "full transparent proxy" mode, it is possible to force a specific IP
3584 address to be presented to the servers. This is not much used in fact. A more
3585 common use is to tell HAProxy to present the client's IP address. For this,
3586 there are two methods :
3587
3588 - present the client's IP and port addresses. This is the most transparent
3589 mode, but it can cause problems when IP connection tracking is enabled on
3590 the machine, because a same connection may be seen twice with different
3591 states. However, this solution presents the huge advantage of not
3592 limiting the system to the 64k outgoing address+port couples, because all
3593 of the client ranges may be used.
3594
3595 - present only the client's IP address and select a spare port. This
3596 solution is still quite elegant but slightly less transparent (downstream
3597 firewalls logs will not match upstream's). It also presents the downside
3598 of limiting the number of concurrent connections to the usual 64k ports.
3599 However, since the upstream and downstream ports are different, local IP
3600 connection tracking on the machine will not be upset by the reuse of the
3601 same session.
3602
3603 Note that depending on the transparent proxy technology used, it may be
3604 required to force the source address. In fact, cttproxy version 2 requires an
3605 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
3606 IP address because it creates NAT entries which much match the exact outgoing
3607 address. Tproxy version 4 and some other kernel patches which work in pure
3608 forwarding mode generally will not have this limitation.
3609
3610 This option sets the default source for all servers in the backend. It may
3611 also be specified in a "defaults" section. Finer source address specification
3612 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003613 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003614
3615 Examples :
3616 backend private
3617 # Connect to the servers using our 192.168.1.200 source address
3618 source 192.168.1.200
3619
3620 backend transparent_ssl1
3621 # Connect to the SSL farm from the client's source address
3622 source 192.168.1.200 usesrc clientip
3623
3624 backend transparent_ssl2
3625 # Connect to the SSL farm from the client's source address and port
3626 # not recommended if IP conntrack is present on the local machine.
3627 source 192.168.1.200 usesrc client
3628
3629 backend transparent_ssl3
3630 # Connect to the SSL farm from the client's source address. It
3631 # is more conntrack-friendly.
3632 source 192.168.1.200 usesrc clientip
3633
3634 backend transparent_smtp
3635 # Connect to the SMTP farm from the client's source address/port
3636 # with Tproxy version 4.
3637 source 0.0.0.0 usesrc clientip
3638
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003639 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003640 the Linux kernel on www.balabit.com, the "bind" keyword.
3641
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003642
Willy Tarreau844e3c52008-01-11 16:28:18 +01003643srvtimeout <timeout> (deprecated)
3644 Set the maximum inactivity time on the server side.
3645 May be used in sections : defaults | frontend | listen | backend
3646 yes | no | yes | yes
3647 Arguments :
3648 <timeout> is the timeout value specified in milliseconds by default, but
3649 can be in any other unit if the number is suffixed by the unit,
3650 as explained at the top of this document.
3651
3652 The inactivity timeout applies when the server is expected to acknowledge or
3653 send data. In HTTP mode, this timeout is particularly important to consider
3654 during the first phase of the server's response, when it has to send the
3655 headers, as it directly represents the server's processing time for the
3656 request. To find out what value to put there, it's often good to start with
3657 what would be considered as unacceptable response times, then check the logs
3658 to observe the response time distribution, and adjust the value accordingly.
3659
3660 The value is specified in milliseconds by default, but can be in any other
3661 unit if the number is suffixed by the unit, as specified at the top of this
3662 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
3663 recommended that the client timeout remains equal to the server timeout in
3664 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003665 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01003666 packet losses by specifying timeouts that are slightly above multiples of 3
3667 seconds (eg: 4 or 5 seconds minimum).
3668
3669 This parameter is specific to backends, but can be specified once for all in
3670 "defaults" sections. This is in fact one of the easiest solutions not to
3671 forget about it. An unspecified timeout results in an infinite timeout, which
3672 is not recommended. Such a usage is accepted and works but reports a warning
3673 during startup because it may results in accumulation of expired sessions in
3674 the system if the system's timeouts are not configured either.
3675
3676 This parameter is provided for compatibility but is currently deprecated.
3677 Please use "timeout server" instead.
3678
3679 See also : "timeout server", "timeout client" and "clitimeout".
3680
3681
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003682stats auth <user>:<passwd>
3683 Enable statistics with authentication and grant access to an account
3684 May be used in sections : defaults | frontend | listen | backend
3685 yes | no | yes | yes
3686 Arguments :
3687 <user> is a user name to grant access to
3688
3689 <passwd> is the cleartext password associated to this user
3690
3691 This statement enables statistics with default settings, and restricts access
3692 to declared users only. It may be repeated as many times as necessary to
3693 allow as many users as desired. When a user tries to access the statistics
3694 without a valid account, a "401 Forbidden" response will be returned so that
3695 the browser asks the user to provide a valid user and password. The real
3696 which will be returned to the browser is configurable using "stats realm".
3697
3698 Since the authentication method is HTTP Basic Authentication, the passwords
3699 circulate in cleartext on the network. Thus, it was decided that the
3700 configuration file would also use cleartext passwords to remind the users
3701 that those ones should not be sensible and not shared with any other account.
3702
3703 It is also possible to reduce the scope of the proxies which appear in the
3704 report using "stats scope".
3705
3706 Though this statement alone is enough to enable statistics reporting, it is
3707 recommended to set all other settings in order to avoid relying on default
3708 unobvious parameters.
3709
3710 Example :
3711 # public access (limited to this backend only)
3712 backend public_www
3713 server srv1 192.168.0.1:80
3714 stats enable
3715 stats hide-version
3716 stats scope .
3717 stats uri /admin?stats
3718 stats realm Haproxy\ Statistics
3719 stats auth admin1:AdMiN123
3720 stats auth admin2:AdMiN321
3721
3722 # internal monitoring access (unlimited)
3723 backend private_monitoring
3724 stats enable
3725 stats uri /admin?stats
3726 stats refresh 5s
3727
3728 See also : "stats enable", "stats realm", "stats scope", "stats uri"
3729
3730
3731stats enable
3732 Enable statistics reporting with default settings
3733 May be used in sections : defaults | frontend | listen | backend
3734 yes | no | yes | yes
3735 Arguments : none
3736
3737 This statement enables statistics reporting with default settings defined
3738 at build time. Unless stated otherwise, these settings are used :
3739 - stats uri : /haproxy?stats
3740 - stats realm : "HAProxy Statistics"
3741 - stats auth : no authentication
3742 - stats scope : no restriction
3743
3744 Though this statement alone is enough to enable statistics reporting, it is
3745 recommended to set all other settings in order to avoid relying on default
3746 unobvious parameters.
3747
3748 Example :
3749 # public access (limited to this backend only)
3750 backend public_www
3751 server srv1 192.168.0.1:80
3752 stats enable
3753 stats hide-version
3754 stats scope .
3755 stats uri /admin?stats
3756 stats realm Haproxy\ Statistics
3757 stats auth admin1:AdMiN123
3758 stats auth admin2:AdMiN321
3759
3760 # internal monitoring access (unlimited)
3761 backend private_monitoring
3762 stats enable
3763 stats uri /admin?stats
3764 stats refresh 5s
3765
3766 See also : "stats auth", "stats realm", "stats uri"
3767
3768
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02003769stats node-name [ <name> ]
3770 Enable reporting of a host name on the statistics page.
3771 May be used in sections : defaults | frontend | listen | backend
3772 yes | no | yes | yes
3773 Arguments :
3774 <name> is an optional name to be reported. If unspecified, the system's
3775 hostname is automatically used instead.
3776
3777 The node-name is read as a single word, so any spaces in it should be escaped
3778 using a backslash ('\'). If it is left unspecified, the system's hostname is
3779 used instead.
3780
3781 This statement is useful in HA configurations where two or more processes or
3782 servers share a same IP address. By setting a different node-name on all
3783 nodes, it becomes easy to immediately spot what server is handling the
3784 traffic.
3785
3786 Though this statement alone is enough to enable statistics reporting, it is
3787 recommended to set all other settings in order to avoid relying on default
3788 unobvious parameters.
3789
3790 Example :
3791 # internal monitoring access (unlimited)
3792 backend private_monitoring
3793 stats enable
3794 stats node-name master
3795 stats uri /admin?stats
3796 stats refresh 5s
3797
3798 See also : "stats enable", "stats uri"
3799
3800
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003801stats realm <realm>
3802 Enable statistics and set authentication realm
3803 May be used in sections : defaults | frontend | listen | backend
3804 yes | no | yes | yes
3805 Arguments :
3806 <realm> is the name of the HTTP Basic Authentication realm reported to
3807 the browser. The browser uses it to display it in the pop-up
3808 inviting the user to enter a valid username and password.
3809
3810 The realm is read as a single word, so any spaces in it should be escaped
3811 using a backslash ('\').
3812
3813 This statement is useful only in conjunction with "stats auth" since it is
3814 only related to authentication.
3815
3816 Though this statement alone is enough to enable statistics reporting, it is
3817 recommended to set all other settings in order to avoid relying on default
3818 unobvious parameters.
3819
3820 Example :
3821 # public access (limited to this backend only)
3822 backend public_www
3823 server srv1 192.168.0.1:80
3824 stats enable
3825 stats hide-version
3826 stats scope .
3827 stats uri /admin?stats
3828 stats realm Haproxy\ Statistics
3829 stats auth admin1:AdMiN123
3830 stats auth admin2:AdMiN321
3831
3832 # internal monitoring access (unlimited)
3833 backend private_monitoring
3834 stats enable
3835 stats uri /admin?stats
3836 stats refresh 5s
3837
3838 See also : "stats auth", "stats enable", "stats uri"
3839
3840
3841stats refresh <delay>
3842 Enable statistics with automatic refresh
3843 May be used in sections : defaults | frontend | listen | backend
3844 yes | no | yes | yes
3845 Arguments :
3846 <delay> is the suggested refresh delay, specified in seconds, which will
3847 be returned to the browser consulting the report page. While the
3848 browser is free to apply any delay, it will generally respect it
3849 and refresh the page this every seconds. The refresh interval may
3850 be specified in any other non-default time unit, by suffixing the
3851 unit after the value, as explained at the top of this document.
3852
3853 This statement is useful on monitoring displays with a permanent page
3854 reporting the load balancer's activity. When set, the HTML report page will
3855 include a link "refresh"/"stop refresh" so that the user can select whether
3856 he wants automatic refresh of the page or not.
3857
3858 Though this statement alone is enough to enable statistics reporting, it is
3859 recommended to set all other settings in order to avoid relying on default
3860 unobvious parameters.
3861
3862 Example :
3863 # public access (limited to this backend only)
3864 backend public_www
3865 server srv1 192.168.0.1:80
3866 stats enable
3867 stats hide-version
3868 stats scope .
3869 stats uri /admin?stats
3870 stats realm Haproxy\ Statistics
3871 stats auth admin1:AdMiN123
3872 stats auth admin2:AdMiN321
3873
3874 # internal monitoring access (unlimited)
3875 backend private_monitoring
3876 stats enable
3877 stats uri /admin?stats
3878 stats refresh 5s
3879
3880 See also : "stats auth", "stats enable", "stats realm", "stats uri"
3881
3882
3883stats scope { <name> | "." }
3884 Enable statistics and limit access scope
3885 May be used in sections : defaults | frontend | listen | backend
3886 yes | no | yes | yes
3887 Arguments :
3888 <name> is the name of a listen, frontend or backend section to be
3889 reported. The special name "." (a single dot) designates the
3890 section in which the statement appears.
3891
3892 When this statement is specified, only the sections enumerated with this
3893 statement will appear in the report. All other ones will be hidden. This
3894 statement may appear as many times as needed if multiple sections need to be
3895 reported. Please note that the name checking is performed as simple string
3896 comparisons, and that it is never checked that a give section name really
3897 exists.
3898
3899 Though this statement alone is enough to enable statistics reporting, it is
3900 recommended to set all other settings in order to avoid relying on default
3901 unobvious parameters.
3902
3903 Example :
3904 # public access (limited to this backend only)
3905 backend public_www
3906 server srv1 192.168.0.1:80
3907 stats enable
3908 stats hide-version
3909 stats scope .
3910 stats uri /admin?stats
3911 stats realm Haproxy\ Statistics
3912 stats auth admin1:AdMiN123
3913 stats auth admin2:AdMiN321
3914
3915 # internal monitoring access (unlimited)
3916 backend private_monitoring
3917 stats enable
3918 stats uri /admin?stats
3919 stats refresh 5s
3920
3921 See also : "stats auth", "stats enable", "stats realm", "stats uri"
3922
3923
3924stats uri <prefix>
3925 Enable statistics and define the URI prefix to access them
3926 May be used in sections : defaults | frontend | listen | backend
3927 yes | no | yes | yes
3928 Arguments :
3929 <prefix> is the prefix of any URI which will be redirected to stats. This
3930 prefix may contain a question mark ('?') to indicate part of a
3931 query string.
3932
3933 The statistics URI is intercepted on the relayed traffic, so it appears as a
3934 page within the normal application. It is strongly advised to ensure that the
3935 selected URI will never appear in the application, otherwise it will never be
3936 possible to reach it in the application.
3937
3938 The default URI compiled in haproxy is "/haproxy?stats", but this may be
3939 changed at build time, so it's better to always explictly specify it here.
3940 It is generally a good idea to include a question mark in the URI so that
3941 intermediate proxies refrain from caching the results. Also, since any string
3942 beginning with the prefix will be accepted as a stats request, the question
3943 mark helps ensuring that no valid URI will begin with the same words.
3944
3945 It is sometimes very convenient to use "/" as the URI prefix, and put that
3946 statement in a "listen" instance of its own. That makes it easy to dedicate
3947 an address or a port to statistics only.
3948
3949 Though this statement alone is enough to enable statistics reporting, it is
3950 recommended to set all other settings in order to avoid relying on default
3951 unobvious parameters.
3952
3953 Example :
3954 # public access (limited to this backend only)
3955 backend public_www
3956 server srv1 192.168.0.1:80
3957 stats enable
3958 stats hide-version
3959 stats scope .
3960 stats uri /admin?stats
3961 stats realm Haproxy\ Statistics
3962 stats auth admin1:AdMiN123
3963 stats auth admin2:AdMiN321
3964
3965 # internal monitoring access (unlimited)
3966 backend private_monitoring
3967 stats enable
3968 stats uri /admin?stats
3969 stats refresh 5s
3970
3971 See also : "stats auth", "stats enable", "stats realm"
3972
3973
3974stats hide-version
3975 Enable statistics and hide HAProxy version reporting
3976 May be used in sections : defaults | frontend | listen | backend
3977 yes | no | yes | yes
3978 Arguments : none
3979
3980 By default, the stats page reports some useful status information along with
3981 the statistics. Among them is HAProxy's version. However, it is generally
3982 considered dangerous to report precise version to anyone, as it can help them
3983 target known weaknesses with specific attacks. The "stats hide-version"
3984 statement removes the version from the statistics report. This is recommended
3985 for public sites or any site with a weak login/password.
3986
3987 Though this statement alone is enough to enable statistics reporting, it is
3988 recommended to set all other settings in order to avoid relying on default
3989 unobvious parameters.
3990
3991 Example :
3992 # public access (limited to this backend only)
3993 backend public_www
3994 server srv1 192.168.0.1:80
3995 stats enable
3996 stats hide-version
3997 stats scope .
3998 stats uri /admin?stats
3999 stats realm Haproxy\ Statistics
4000 stats auth admin1:AdMiN123
4001 stats auth admin2:AdMiN321
4002
4003 # internal monitoring access (unlimited)
4004 backend private_monitoring
4005 stats enable
4006 stats uri /admin?stats
4007 stats refresh 5s
4008
4009 See also : "stats auth", "stats enable", "stats realm", "stats uri"
4010
4011
Willy Tarreau62644772008-07-16 18:36:06 +02004012tcp-request content accept [{if | unless} <condition>]
4013 Accept a connection if/unless a content inspection condition is matched
4014 May be used in sections : defaults | frontend | listen | backend
4015 no | yes | yes | no
4016
4017 During TCP content inspection, the connection is immediately validated if the
4018 condition is true (when used with "if") or false (when used with "unless").
4019 Most of the time during content inspection, a condition will be in an
4020 uncertain state which is neither true nor false. The evaluation immediately
4021 stops when such a condition is encountered. It is important to understand
4022 that "accept" and "reject" rules are evaluated in their exact declaration
4023 order, so that it is possible to build complex rules from them. There is no
4024 specific limit to the number of rules which may be inserted.
4025
4026 Note that the "if/unless" condition is optionnal. If no condition is set on
4027 the action, it is simply performed unconditionally.
4028
4029 If no "tcp-request content" rules are matched, the default action already is
4030 "accept". Thus, this statement alone does not bring anything without another
4031 "reject" statement.
4032
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004033 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02004034
Willy Tarreau55165fe2009-05-10 12:02:55 +02004035 See also : "tcp-request content reject", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02004036
4037
4038tcp-request content reject [{if | unless} <condition>]
4039 Reject a connection if/unless a content inspection condition is matched
4040 May be used in sections : defaults | frontend | listen | backend
4041 no | yes | yes | no
4042
4043 During TCP content inspection, the connection is immediately rejected if the
4044 condition is true (when used with "if") or false (when used with "unless").
4045 Most of the time during content inspection, a condition will be in an
4046 uncertain state which is neither true nor false. The evaluation immediately
4047 stops when such a condition is encountered. It is important to understand
4048 that "accept" and "reject" rules are evaluated in their exact declaration
4049 order, so that it is possible to build complex rules from them. There is no
4050 specific limit to the number of rules which may be inserted.
4051
4052 Note that the "if/unless" condition is optionnal. If no condition is set on
4053 the action, it is simply performed unconditionally.
4054
4055 If no "tcp-request content" rules are matched, the default action is set to
4056 "accept".
4057
4058 Example:
4059 # reject SMTP connection if client speaks first
4060 tcp-request inspect-delay 30s
4061 acl content_present req_len gt 0
4062 tcp-request reject if content_present
4063
4064 # Forward HTTPS connection only if client speaks
4065 tcp-request inspect-delay 30s
4066 acl content_present req_len gt 0
4067 tcp-request accept if content_present
4068 tcp-request reject
4069
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004070 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02004071
Willy Tarreau55165fe2009-05-10 12:02:55 +02004072 See also : "tcp-request content accept", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02004073
4074
4075tcp-request inspect-delay <timeout>
4076 Set the maximum allowed time to wait for data during content inspection
4077 May be used in sections : defaults | frontend | listen | backend
4078 no | yes | yes | no
4079 Arguments :
4080 <timeout> is the timeout value specified in milliseconds by default, but
4081 can be in any other unit if the number is suffixed by the unit,
4082 as explained at the top of this document.
4083
4084 People using haproxy primarily as a TCP relay are often worried about the
4085 risk of passing any type of protocol to a server without any analysis. In
4086 order to be able to analyze the request contents, we must first withhold
4087 the data then analyze them. This statement simply enables withholding of
4088 data for at most the specified amount of time.
4089
4090 Note that when performing content inspection, haproxy will evaluate the whole
4091 rules for every new chunk which gets in, taking into account the fact that
4092 those data are partial. If no rule matches before the aforementionned delay,
4093 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01004094 contents are definitive. If no delay is set, haproxy will not wait at all
4095 and will immediately apply a verdict based on the available information.
4096 Obviously this is unlikely to be very useful and might even be racy, so such
4097 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02004098
4099 As soon as a rule matches, the request is released and continues as usual. If
4100 the timeout is reached and no rule matches, the default policy will be to let
4101 it pass through unaffected.
4102
4103 For most protocols, it is enough to set it to a few seconds, as most clients
4104 send the full request immediately upon connection. Add 3 or more seconds to
4105 cover TCP retransmits but that's all. For some protocols, it may make sense
4106 to use large values, for instance to ensure that the client never talks
4107 before the server (eg: SMTP), or to wait for a client to talk before passing
4108 data to the server (eg: SSL). Note that the client timeout must cover at
4109 least the inspection delay, otherwise it will expire first.
4110
Willy Tarreau55165fe2009-05-10 12:02:55 +02004111 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02004112 "timeout client".
4113
4114
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01004115timeout check <timeout>
4116 Set additional check timeout, but only after a connection has been already
4117 established.
4118
4119 May be used in sections: defaults | frontend | listen | backend
4120 yes | no | yes | yes
4121 Arguments:
4122 <timeout> is the timeout value specified in milliseconds by default, but
4123 can be in any other unit if the number is suffixed by the unit,
4124 as explained at the top of this document.
4125
4126 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
4127 for check and "timeout check" as an additional read timeout. The "min" is
4128 used so that people running with *very* long "timeout connect" (eg. those
4129 who needed this due to the queue or tarpit) do not slow down their checks.
4130 Of course it is better to use "check queue" and "check tarpit" instead of
4131 long "timeout connect".
4132
4133 If "timeout check" is not set haproxy uses "inter" for complete check
4134 timeout (connect + read) exactly like all <1.3.15 version.
4135
4136 In most cases check request is much simpler and faster to handle than normal
4137 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01004138 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01004139
4140 This parameter is specific to backends, but can be specified once for all in
4141 "defaults" sections. This is in fact one of the easiest solutions not to
4142 forget about it.
4143
Willy Tarreau41a340d2008-01-22 12:25:31 +01004144 See also: "timeout connect", "timeout queue", "timeout server",
4145 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01004146
4147
Willy Tarreau0ba27502007-12-24 16:55:16 +01004148timeout client <timeout>
4149timeout clitimeout <timeout> (deprecated)
4150 Set the maximum inactivity time on the client side.
4151 May be used in sections : defaults | frontend | listen | backend
4152 yes | yes | yes | no
4153 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01004154 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01004155 can be in any other unit if the number is suffixed by the unit,
4156 as explained at the top of this document.
4157
4158 The inactivity timeout applies when the client is expected to acknowledge or
4159 send data. In HTTP mode, this timeout is particularly important to consider
4160 during the first phase, when the client sends the request, and during the
4161 response while it is reading data sent by the server. The value is specified
4162 in milliseconds by default, but can be in any other unit if the number is
4163 suffixed by the unit, as specified at the top of this document. In TCP mode
4164 (and to a lesser extent, in HTTP mode), it is highly recommended that the
4165 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004166 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01004167 losses by specifying timeouts that are slightly above multiples of 3 seconds
4168 (eg: 4 or 5 seconds).
4169
4170 This parameter is specific to frontends, but can be specified once for all in
4171 "defaults" sections. This is in fact one of the easiest solutions not to
4172 forget about it. An unspecified timeout results in an infinite timeout, which
4173 is not recommended. Such a usage is accepted and works but reports a warning
4174 during startup because it may results in accumulation of expired sessions in
4175 the system if the system's timeouts are not configured either.
4176
4177 This parameter replaces the old, deprecated "clitimeout". It is recommended
4178 to use it to write new configurations. The form "timeout clitimeout" is
4179 provided only by backwards compatibility but its use is strongly discouraged.
4180
4181 See also : "clitimeout", "timeout server".
4182
4183
4184timeout connect <timeout>
4185timeout contimeout <timeout> (deprecated)
4186 Set the maximum time to wait for a connection attempt to a server to succeed.
4187 May be used in sections : defaults | frontend | listen | backend
4188 yes | no | yes | yes
4189 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01004190 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01004191 can be in any other unit if the number is suffixed by the unit,
4192 as explained at the top of this document.
4193
4194 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004195 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreau0ba27502007-12-24 16:55:16 +01004196 cover one or several TCP packet losses by specifying timeouts that are
4197 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01004198 connect timeout also presets both queue and tarpit timeouts to the same value
4199 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004200
4201 This parameter is specific to backends, but can be specified once for all in
4202 "defaults" sections. This is in fact one of the easiest solutions not to
4203 forget about it. An unspecified timeout results in an infinite timeout, which
4204 is not recommended. Such a usage is accepted and works but reports a warning
4205 during startup because it may results in accumulation of failed sessions in
4206 the system if the system's timeouts are not configured either.
4207
4208 This parameter replaces the old, deprecated "contimeout". It is recommended
4209 to use it to write new configurations. The form "timeout contimeout" is
4210 provided only by backwards compatibility but its use is strongly discouraged.
4211
Willy Tarreau41a340d2008-01-22 12:25:31 +01004212 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
4213 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01004214
4215
Willy Tarreau036fae02008-01-06 13:24:40 +01004216timeout http-request <timeout>
4217 Set the maximum allowed time to wait for a complete HTTP request
4218 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02004219 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01004220 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01004221 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01004222 can be in any other unit if the number is suffixed by the unit,
4223 as explained at the top of this document.
4224
4225 In order to offer DoS protection, it may be required to lower the maximum
4226 accepted time to receive a complete HTTP request without affecting the client
4227 timeout. This helps protecting against established connections on which
4228 nothing is sent. The client timeout cannot offer a good protection against
4229 this abuse because it is an inactivity timeout, which means that if the
4230 attacker sends one character every now and then, the timeout will not
4231 trigger. With the HTTP request timeout, no matter what speed the client
4232 types, the request will be aborted if it does not complete in time.
4233
4234 Note that this timeout only applies to the header part of the request, and
4235 not to any data. As soon as the empty line is received, this timeout is not
4236 used anymore.
4237
4238 Generally it is enough to set it to a few seconds, as most clients send the
4239 full request immediately upon connection. Add 3 or more seconds to cover TCP
4240 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
4241 generally work on local networks as long as there are no packet losses. This
4242 will prevent people from sending bare HTTP requests using telnet.
4243
4244 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02004245 chunk of the incoming request. It should be set in the frontend to take
4246 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
4247 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01004248
4249 See also : "timeout client".
4250
Willy Tarreau844e3c52008-01-11 16:28:18 +01004251
4252timeout queue <timeout>
4253 Set the maximum time to wait in the queue for a connection slot to be free
4254 May be used in sections : defaults | frontend | listen | backend
4255 yes | no | yes | yes
4256 Arguments :
4257 <timeout> is the timeout value specified in milliseconds by default, but
4258 can be in any other unit if the number is suffixed by the unit,
4259 as explained at the top of this document.
4260
4261 When a server's maxconn is reached, connections are left pending in a queue
4262 which may be server-specific or global to the backend. In order not to wait
4263 indefinitely, a timeout is applied to requests pending in the queue. If the
4264 timeout is reached, it is considered that the request will almost never be
4265 served, so it is dropped and a 503 error is returned to the client.
4266
4267 The "timeout queue" statement allows to fix the maximum time for a request to
4268 be left pending in a queue. If unspecified, the same value as the backend's
4269 connection timeout ("timeout connect") is used, for backwards compatibility
4270 with older versions with no "timeout queue" parameter.
4271
4272 See also : "timeout connect", "contimeout".
4273
4274
4275timeout server <timeout>
4276timeout srvtimeout <timeout> (deprecated)
4277 Set the maximum inactivity time on the server side.
4278 May be used in sections : defaults | frontend | listen | backend
4279 yes | no | yes | yes
4280 Arguments :
4281 <timeout> is the timeout value specified in milliseconds by default, but
4282 can be in any other unit if the number is suffixed by the unit,
4283 as explained at the top of this document.
4284
4285 The inactivity timeout applies when the server is expected to acknowledge or
4286 send data. In HTTP mode, this timeout is particularly important to consider
4287 during the first phase of the server's response, when it has to send the
4288 headers, as it directly represents the server's processing time for the
4289 request. To find out what value to put there, it's often good to start with
4290 what would be considered as unacceptable response times, then check the logs
4291 to observe the response time distribution, and adjust the value accordingly.
4292
4293 The value is specified in milliseconds by default, but can be in any other
4294 unit if the number is suffixed by the unit, as specified at the top of this
4295 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
4296 recommended that the client timeout remains equal to the server timeout in
4297 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004298 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01004299 packet losses by specifying timeouts that are slightly above multiples of 3
4300 seconds (eg: 4 or 5 seconds minimum).
4301
4302 This parameter is specific to backends, but can be specified once for all in
4303 "defaults" sections. This is in fact one of the easiest solutions not to
4304 forget about it. An unspecified timeout results in an infinite timeout, which
4305 is not recommended. Such a usage is accepted and works but reports a warning
4306 during startup because it may results in accumulation of expired sessions in
4307 the system if the system's timeouts are not configured either.
4308
4309 This parameter replaces the old, deprecated "srvtimeout". It is recommended
4310 to use it to write new configurations. The form "timeout srvtimeout" is
4311 provided only by backwards compatibility but its use is strongly discouraged.
4312
4313 See also : "srvtimeout", "timeout client".
4314
4315
4316timeout tarpit <timeout>
4317 Set the duration for which tapitted connections will be maintained
4318 May be used in sections : defaults | frontend | listen | backend
4319 yes | yes | yes | yes
4320 Arguments :
4321 <timeout> is the tarpit duration specified in milliseconds by default, but
4322 can be in any other unit if the number is suffixed by the unit,
4323 as explained at the top of this document.
4324
4325 When a connection is tarpitted using "reqtarpit", it is maintained open with
4326 no activity for a certain amount of time, then closed. "timeout tarpit"
4327 defines how long it will be maintained open.
4328
4329 The value is specified in milliseconds by default, but can be in any other
4330 unit if the number is suffixed by the unit, as specified at the top of this
4331 document. If unspecified, the same value as the backend's connection timeout
4332 ("timeout connect") is used, for backwards compatibility with older versions
4333 with no "timeout tapit" parameter.
4334
4335 See also : "timeout connect", "contimeout".
4336
4337
4338transparent (deprecated)
4339 Enable client-side transparent proxying
4340 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004341 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004342 Arguments : none
4343
4344 This keyword was introduced in order to provide layer 7 persistence to layer
4345 3 load balancers. The idea is to use the OS's ability to redirect an incoming
4346 connection for a remote address to a local process (here HAProxy), and let
4347 this process know what address was initially requested. When this option is
4348 used, sessions without cookies will be forwarded to the original destination
4349 IP address of the incoming request (which should match that of another
4350 equipment), while requests with cookies will still be forwarded to the
4351 appropriate server.
4352
4353 The "transparent" keyword is deprecated, use "option transparent" instead.
4354
4355 Note that contrary to a common belief, this option does NOT make HAProxy
4356 present the client's IP to the server when establishing the connection.
4357
Willy Tarreau844e3c52008-01-11 16:28:18 +01004358 See also: "option transparent"
4359
4360
4361use_backend <backend> if <condition>
4362use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02004363 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004364 May be used in sections : defaults | frontend | listen | backend
4365 no | yes | yes | no
4366 Arguments :
4367 <backend> is the name of a valid backend or "listen" section.
4368
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004369 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004370
4371 When doing content-switching, connections arrive on a frontend and are then
4372 dispatched to various backends depending on a number of conditions. The
4373 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02004374 "use_backend" keyword. While it is normally used with HTTP processing, it can
4375 also be used in pure TCP, either without content using stateless ACLs (eg:
4376 source address validation) or combined with a "tcp-request" rule to wait for
4377 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004378
4379 There may be as many "use_backend" rules as desired. All of these rules are
4380 evaluated in their declaration order, and the first one which matches will
4381 assign the backend.
4382
4383 In the first form, the backend will be used if the condition is met. In the
4384 second form, the backend will be used if the condition is not met. If no
4385 condition is valid, the backend defined with "default_backend" will be used.
4386 If no default backend is defined, either the servers in the same section are
4387 used (in case of a "listen" section) or, in case of a frontend, no server is
4388 used and a 503 service unavailable response is returned.
4389
Willy Tarreau51aecc72009-07-12 09:47:04 +02004390 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
4391 this case, etiher the frontend has already checked that the protocol is HTTP,
4392 and backend processing will immediately follow, or the backend will wait for
4393 a complete HTTP request to get in. This feature is useful when a frontend
4394 must decode several protocols on a unique port, one of them being HTTP.
4395
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02004396 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004397
Willy Tarreau036fae02008-01-06 13:24:40 +01004398
Willy Tarreauc57f0e22009-05-10 13:12:33 +020043995. Server options
4400-----------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02004401
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004402The "server" keyword supports a certain number of settings which are all passed
4403as arguments on the server line. The order in which those arguments appear does
4404not count, and they are all optional. Some of those settings are single words
4405(booleans) while others expect one or several values after them. In this case,
4406the values must immediately follow the setting name. All those settings must be
4407specified after the server's address if they are used :
Willy Tarreau6a06a402007-07-15 20:15:28 +02004408
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004409 server <name> <address>[:port] [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02004410
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004411The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004412
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004413addr <ipv4>
4414 Using the "addr" parameter, it becomes possible to use a different IP address
4415 to send health-checks. On some servers, it may be desirable to dedicate an IP
4416 address to specific component able to perform complex tests which are more
4417 suitable to health-checks than the application. This parameter is ignored if
4418 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02004419
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004420backup
4421 When "backup" is present on a server line, the server is only used in load
4422 balancing when all other non-backup servers are unavailable. Requests coming
4423 with a persistence cookie referencing the server will always be served
4424 though. By default, only the first operational backup server is used, unless
4425 the "allbackups" option is set in the backend. See also the "allbackups"
4426 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02004427
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004428check
4429 This option enables health checks on the server. By default, a server is
4430 always considered available. If "check" is set, the server will receive
4431 periodic health checks to ensure that it is really able to serve requests.
4432 The default address and port to send the tests to are those of the server,
4433 and the default source is the same as the one defined in the backend. It is
4434 possible to change the address using the "addr" parameter, the port using the
4435 "port" parameter, the source address using the "source" address, and the
4436 interval and timers using the "inter", "rise" and "fall" parameters. The
4437 request method is define in the backend using the "httpchk", "smtpchk",
4438 and "ssl-hello-chk" options. Please refer to those options and parameters for
4439 more information.
4440
4441cookie <value>
4442 The "cookie" parameter sets the cookie value assigned to the server to
4443 <value>. This value will be checked in incoming requests, and the first
4444 operational server possessing the same value will be selected. In return, in
4445 cookie insertion or rewrite modes, this value will be assigned to the cookie
4446 sent to the client. There is nothing wrong in having several servers sharing
4447 the same cookie value, and it is in fact somewhat common between normal and
4448 backup servers. See also the "cookie" keyword in backend section.
4449
4450fall <count>
4451 The "fall" parameter states that a server will be considered as dead after
4452 <count> consecutive unsuccessful health checks. This value defaults to 3 if
4453 unspecified. See also the "check", "inter" and "rise" parameters.
4454
4455id <value>
4456 Set a persistent value for server ID. Must be unique and larger than 1000, as
4457 smaller values are reserved for auto-assigned ids.
4458
4459inter <delay>
4460fastinter <delay>
4461downinter <delay>
4462 The "inter" parameter sets the interval between two consecutive health checks
4463 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
4464 It is also possible to use "fastinter" and "downinter" to optimize delays
4465 between checks depending on the server state :
4466
4467 Server state | Interval used
4468 ---------------------------------+-----------------------------------------
4469 UP 100% (non-transitional) | "inter"
4470 ---------------------------------+-----------------------------------------
4471 Transitionally UP (going down), |
4472 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
4473 or yet unchecked. |
4474 ---------------------------------+-----------------------------------------
4475 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
4476 ---------------------------------+-----------------------------------------
4477
4478 Just as with every other time-based parameter, they can be entered in any
4479 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
4480 serves as a timeout for health checks sent to servers if "timeout check" is
4481 not set. In order to reduce "resonance" effects when multiple servers are
4482 hosted on the same hardware, the health-checks of all servers are started
4483 with a small time offset between them. It is also possible to add some random
4484 noise in the health checks interval using the global "spread-checks"
4485 keyword. This makes sense for instance when a lot of backends use the same
4486 servers.
4487
4488maxconn <maxconn>
4489 The "maxconn" parameter specifies the maximal number of concurrent
4490 connections that will be sent to this server. If the number of incoming
4491 concurrent requests goes higher than this value, they will be queued, waiting
4492 for a connection to be released. This parameter is very important as it can
4493 save fragile servers from going down under extreme loads. If a "minconn"
4494 parameter is specified, the limit becomes dynamic. The default value is "0"
4495 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
4496 the backend's "fullconn" keyword.
4497
4498maxqueue <maxqueue>
4499 The "maxqueue" parameter specifies the maximal number of connections which
4500 will wait in the queue for this server. If this limit is reached, next
4501 requests will be redispatched to other servers instead of indefinitely
4502 waiting to be served. This will break persistence but may allow people to
4503 quickly re-log in when the server they try to connect to is dying. The
4504 default value is "0" which means the queue is unlimited. See also the
4505 "maxconn" and "minconn" parameters.
4506
4507minconn <minconn>
4508 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
4509 limit following the backend's load. The server will always accept at least
4510 <minconn> connections, never more than <maxconn>, and the limit will be on
4511 the ramp between both values when the backend has less than <fullconn>
4512 concurrent connections. This makes it possible to limit the load on the
4513 server during normal loads, but push it further for important loads without
4514 overloading the server during exceptionnal loads. See also the "maxconn"
4515 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
4516
4517port <port>
4518 Using the "port" parameter, it becomes possible to use a different port to
4519 send health-checks. On some servers, it may be desirable to dedicate a port
4520 to a specific component able to perform complex tests which are more suitable
4521 to health-checks than the application. It is common to run a simple script in
4522 inetd for instance. This parameter is ignored if the "check" parameter is not
4523 set. See also the "addr" parameter.
4524
4525redir <prefix>
4526 The "redir" parameter enables the redirection mode for all GET and HEAD
4527 requests addressing this server. This means that instead of having HAProxy
4528 forward the request to the server, it will send an "HTTP 302" response with
4529 the "Location" header composed of this prefix immediately followed by the
4530 requested URI beginning at the leading '/' of the path component. That means
4531 that no trailing slash should be used after <prefix>. All invalid requests
4532 will be rejected, and all non-GET or HEAD requests will be normally served by
4533 the server. Note that since the response is completely forged, no header
4534 mangling nor cookie insertion is possible in the respose. However, cookies in
4535 requests are still analysed, making this solution completely usable to direct
4536 users to a remote location in case of local disaster. Main use consists in
4537 increasing bandwidth for static servers by having the clients directly
4538 connect to them. Note: never use a relative location here, it would cause a
4539 loop between the client and HAProxy!
4540
4541 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
4542
4543rise <count>
4544 The "rise" parameter states that a server will be considered as operational
4545 after <count> consecutive successful health checks. This value defaults to 2
4546 if unspecified. See also the "check", "inter" and "fall" parameters.
4547
4548slowstart <start_time_in_ms>
4549 The "slowstart" parameter for a server accepts a value in milliseconds which
4550 indicates after how long a server which has just come back up will run at
4551 full speed. Just as with every other time-based parameter, it can be entered
4552 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
4553 linearly from 0 to 100% during this time. The limitation applies to two
4554 parameters :
4555
4556 - maxconn: the number of connections accepted by the server will grow from 1
4557 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
4558
4559 - weight: when the backend uses a dynamic weighted algorithm, the weight
4560 grows linearly from 1 to 100%. In this case, the weight is updated at every
4561 health-check. For this reason, it is important that the "inter" parameter
4562 is smaller than the "slowstart", in order to maximize the number of steps.
4563
4564 The slowstart never applies when haproxy starts, otherwise it would cause
4565 trouble to running servers. It only applies when a server has been previously
4566 seen as failed.
4567
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004568source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
4569source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004570 The "source" parameter sets the source address which will be used when
4571 connecting to the server. It follows the exact same parameters and principle
4572 as the backend "source" keyword, except that it only applies to the server
4573 referencing it. Please consult the "source" keyword for details.
4574
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004575 Additionally, the "source" statement on a server line allows one to specify a
4576 source port range by indicating the lower and higher bounds delimited by a
4577 dash ('-'). Some operating systems might require a valid IP address when a
4578 source port range is specified. It is permitted to have the same IP/range for
4579 several servers. Doing so makes it possible to bypass the maximum of 64k
4580 total concurrent connections. The limit will then reach 64k connections per
4581 server.
4582
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004583track [<proxy>/]<server>
4584 This option enables ability to set the current state of the server by
4585 tracking another one. Only a server with checks enabled can be tracked
4586 so it is not possible for example to track a server that tracks another
4587 one. If <proxy> is omitted the current one is used. If disable-on-404 is
4588 used, it has to be enabled on both proxies.
4589
4590weight <weight>
4591 The "weight" parameter is used to adjust the server's weight relative to
4592 other servers. All servers will receive a load proportional to their weight
4593 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02004594 load. The default weight is 1, and the maximal value is 256. A value of 0
4595 means the server will not participate in load-balancing but will still accept
4596 persistent connections. If this parameter is used to distribute the load
4597 according to server's capacity, it is recommended to start with values which
4598 can both grow and shrink, for instance between 10 and 100 to leave enough
4599 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004600
4601
46026. HTTP header manipulation
4603---------------------------
4604
4605In HTTP mode, it is possible to rewrite, add or delete some of the request and
4606response headers based on regular expressions. It is also possible to block a
4607request or a response if a particular header matches a regular expression,
4608which is enough to stop most elementary protocol attacks, and to protect
4609against information leak from the internal network. But there is a limitation
4610to this : since HAProxy's HTTP engine does not support keep-alive, only headers
4611passed during the first request of a TCP session will be seen. All subsequent
4612headers will be considered data only and not analyzed. Furthermore, HAProxy
4613never touches data contents, it stops analysis at the end of headers.
4614
Willy Tarreau816b9792009-09-15 21:25:21 +02004615There is an exception though. If HAProxy encounters an "Informational Response"
4616(status code 1xx), it is able to process all rsp* rules which can allow, deny,
4617rewrite or delete a header, but it will refuse to add a header to any such
4618messages as this is not HTTP-compliant. The reason for still processing headers
4619in such responses is to stop and/or fix any possible information leak which may
4620happen, for instance because another downstream equipment would inconditionally
4621add a header, or if a server name appears there. When such messages are seen,
4622normal processing still occurs on the next non-informational messages.
4623
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004624This section covers common usage of the following keywords, described in detail
4625in section 4.2 :
4626
4627 - reqadd <string>
4628 - reqallow <search>
4629 - reqiallow <search>
4630 - reqdel <search>
4631 - reqidel <search>
4632 - reqdeny <search>
4633 - reqideny <search>
4634 - reqpass <search>
4635 - reqipass <search>
4636 - reqrep <search> <replace>
4637 - reqirep <search> <replace>
4638 - reqtarpit <search>
4639 - reqitarpit <search>
4640 - rspadd <string>
4641 - rspdel <search>
4642 - rspidel <search>
4643 - rspdeny <search>
4644 - rspideny <search>
4645 - rsprep <search> <replace>
4646 - rspirep <search> <replace>
4647
4648With all these keywords, the same conventions are used. The <search> parameter
4649is a POSIX extended regular expression (regex) which supports grouping through
4650parenthesis (without the backslash). Spaces and other delimiters must be
4651prefixed with a backslash ('\') to avoid confusion with a field delimiter.
4652Other characters may be prefixed with a backslash to change their meaning :
4653
4654 \t for a tab
4655 \r for a carriage return (CR)
4656 \n for a new line (LF)
4657 \ to mark a space and differentiate it from a delimiter
4658 \# to mark a sharp and differentiate it from a comment
4659 \\ to use a backslash in a regex
4660 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
4661 \xXX to write the ASCII hex code XX as in the C language
4662
4663The <replace> parameter contains the string to be used to replace the largest
4664portion of text matching the regex. It can make use of the special characters
4665above, and can reference a substring which is delimited by parenthesis in the
4666regex, by writing a backslash ('\') immediately followed by one digit from 0 to
46679 indicating the group position (0 designating the entire line). This practice
4668is very common to users of the "sed" program.
4669
4670The <string> parameter represents the string which will systematically be added
4671after the last header line. It can also use special character sequences above.
4672
4673Notes related to these keywords :
4674---------------------------------
4675 - these keywords are not always convenient to allow/deny based on header
4676 contents. It is strongly recommended to use ACLs with the "block" keyword
4677 instead, resulting in far more flexible and manageable rules.
4678
4679 - lines are always considered as a whole. It is not possible to reference
4680 a header name only or a value only. This is important because of the way
4681 headers are written (notably the number of spaces after the colon).
4682
4683 - the first line is always considered as a header, which makes it possible to
4684 rewrite or filter HTTP requests URIs or response codes, but in turn makes
4685 it harder to distinguish between headers and request line. The regex prefix
4686 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
4687 ^[^ \t:]*: matches any header name followed by a colon.
4688
4689 - for performances reasons, the number of characters added to a request or to
4690 a response is limited at build time to values between 1 and 4 kB. This
4691 should normally be far more than enough for most usages. If it is too short
4692 on occasional usages, it is possible to gain some space by removing some
4693 useless headers before adding new ones.
4694
4695 - keywords beginning with "reqi" and "rspi" are the same as their couterpart
4696 without the 'i' letter except that they ignore case when matching patterns.
4697
4698 - when a request passes through a frontend then a backend, all req* rules
4699 from the frontend will be evaluated, then all req* rules from the backend
4700 will be evaluated. The reverse path is applied to responses.
4701
4702 - req* statements are applied after "block" statements, so that "block" is
4703 always the first one, but before "use_backend" in order to permit rewriting
4704 before switching.
4705
4706
47077. Using ACLs
4708-------------
4709
4710The use of Access Control Lists (ACL) provides a flexible solution to perform
4711content switching and generally to take decisions based on content extracted
4712from the request, the response or any environmental status. The principle is
4713simple :
4714
4715 - define test criteria with sets of values
4716 - perform actions only if a set of tests is valid
4717
4718The actions generally consist in blocking the request, or selecting a backend.
4719
4720In order to define a test, the "acl" keyword is used. The syntax is :
4721
4722 acl <aclname> <criterion> [flags] [operator] <value> ...
4723
4724This creates a new ACL <aclname> or completes an existing one with new tests.
4725Those tests apply to the portion of request/response specified in <criterion>
4726and may be adjusted with optional flags [flags]. Some criteria also support
4727an operator which may be specified before the set of values. The values are
4728of the type supported by the criterion, and are separated by spaces.
4729
4730ACL names must be formed from upper and lower case letters, digits, '-' (dash),
4731'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
4732which means that "my_acl" and "My_Acl" are two different ACLs.
4733
4734There is no enforced limit to the number of ACLs. The unused ones do not affect
4735performance, they just consume a small amount of memory.
4736
4737The following ACL flags are currently supported :
4738
4739 -i : ignore case during matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02004740 -- : force end of flags. Useful when a string looks like one of the flags.
4741
4742Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01004743
Willy Tarreau6a06a402007-07-15 20:15:28 +02004744 - integers or integer ranges
4745 - strings
4746 - regular expressions
4747 - IP addresses and networks
4748
4749
Willy Tarreauc57f0e22009-05-10 13:12:33 +020047507.1. Matching integers
4751----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02004752
4753Matching integers is special in that ranges and operators are permitted. Note
4754that integer matching only applies to positive values. A range is a value
4755expressed with a lower and an upper bound separated with a colon, both of which
4756may be omitted.
4757
4758For instance, "1024:65535" is a valid range to represent a range of
4759unprivileged ports, and "1024:" would also work. "0:1023" is a valid
4760representation of privileged ports, and ":1023" would also work.
4761
Willy Tarreau62644772008-07-16 18:36:06 +02004762As a special case, some ACL functions support decimal numbers which are in fact
4763two integers separated by a dot. This is used with some version checks for
4764instance. All integer properties apply to those decimal numbers, including
4765ranges and operators.
4766
Willy Tarreau6a06a402007-07-15 20:15:28 +02004767For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01004768operators with ranges does not make much sense and is strongly discouraged.
4769Similarly, it does not make much sense to perform order comparisons with a set
4770of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02004771
Willy Tarreau0ba27502007-12-24 16:55:16 +01004772Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02004773
4774 eq : true if the tested value equals at least one value
4775 ge : true if the tested value is greater than or equal to at least one value
4776 gt : true if the tested value is greater than at least one value
4777 le : true if the tested value is less than or equal to at least one value
4778 lt : true if the tested value is less than at least one value
4779
Willy Tarreau0ba27502007-12-24 16:55:16 +01004780For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02004781
4782 acl negative-length hdr_val(content-length) lt 0
4783
Willy Tarreau62644772008-07-16 18:36:06 +02004784This one matches SSL versions between 3.0 and 3.1 (inclusive) :
4785
4786 acl sslv3 req_ssl_ver 3:3.1
4787
Willy Tarreau6a06a402007-07-15 20:15:28 +02004788
Willy Tarreauc57f0e22009-05-10 13:12:33 +020047897.2. Matching strings
4790---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02004791
4792String matching applies to verbatim strings as they are passed, with the
4793exception of the backslash ("\") which makes it possible to escape some
4794characters such as the space. If the "-i" flag is passed before the first
4795string, then the matching will be performed ignoring the case. In order
4796to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01004797before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02004798
4799
Willy Tarreauc57f0e22009-05-10 13:12:33 +020048007.3. Matching regular expressions (regexes)
4801-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02004802
4803Just like with string matching, regex matching applies to verbatim strings as
4804they are passed, with the exception of the backslash ("\") which makes it
4805possible to escape some characters such as the space. If the "-i" flag is
4806passed before the first regex, then the matching will be performed ignoring
4807the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01004808the "--" flag before the first string. Same principle applies of course to
4809match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02004810
4811
Willy Tarreauc57f0e22009-05-10 13:12:33 +020048127.4. Matching IPv4 addresses
4813----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02004814
4815IPv4 addresses values can be specified either as plain addresses or with a
4816netmask appended, in which case the IPv4 address matches whenever it is
4817within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004818host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01004819difficult to read and debug configurations. If hostnames are used, you should
4820at least ensure that they are present in /etc/hosts so that the configuration
4821does not depend on any random DNS match at the moment the configuration is
4822parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02004823
4824
Willy Tarreauc57f0e22009-05-10 13:12:33 +020048257.5. Available matching criteria
4826--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02004827
Willy Tarreauc57f0e22009-05-10 13:12:33 +020048287.5.1. Matching at Layer 4 and below
4829------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01004830
4831A first set of criteria applies to information which does not require any
4832analysis of the request or response contents. Those generally include TCP/IP
4833addresses and ports, as well as internal values independant on the stream.
4834
Willy Tarreau6a06a402007-07-15 20:15:28 +02004835always_false
4836 This one never matches. All values and flags are ignored. It may be used as
4837 a temporary replacement for another one when adjusting configurations.
4838
4839always_true
4840 This one always matches. All values and flags are ignored. It may be used as
4841 a temporary replacement for another one when adjusting configurations.
4842
4843src <ip_address>
Willy Tarreau0ba27502007-12-24 16:55:16 +01004844 Applies to the client's IPv4 address. It is usually used to limit access to
Willy Tarreau6a06a402007-07-15 20:15:28 +02004845 certain resources such as statistics. Note that it is the TCP-level source
4846 address which is used, and not the address of a client behind a proxy.
4847
4848src_port <integer>
4849 Applies to the client's TCP source port. This has a very limited usage.
4850
4851dst <ip_address>
Willy Tarreau0ba27502007-12-24 16:55:16 +01004852 Applies to the local IPv4 address the client connected to. It can be used to
Willy Tarreau6a06a402007-07-15 20:15:28 +02004853 switch to a different backend for some alternative addresses.
4854
4855dst_port <integer>
4856 Applies to the local port the client connected to. It can be used to switch
4857 to a different backend for some alternative ports.
4858
4859dst_conn <integer>
4860 Applies to the number of currently established connections on the frontend,
4861 including the one being evaluated. It can be used to either return a sorry
Willy Tarreau0ba27502007-12-24 16:55:16 +01004862 page before hard-blocking, or to use a specific backend to drain new requests
Willy Tarreau6a06a402007-07-15 20:15:28 +02004863 when the farm is considered saturated.
4864
Willy Tarreau0ba27502007-12-24 16:55:16 +01004865nbsrv <integer>
4866nbsrv(backend) <integer>
4867 Returns true when the number of usable servers of either the current backend
4868 or the named backend matches the values or ranges specified. This is used to
4869 switch to an alternate backend when the number of servers is too low to
4870 to handle some load. It is useful to report a failure when combined with
4871 "monitor fail".
4872
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08004873connslots <integer>
4874connslots(backend) <integer>
4875 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02004876 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08004877 usage; see "use_backend" keyword) can be redirected to a different backend.
4878
Willy Tarreau55165fe2009-05-10 12:02:55 +02004879 'connslots' = number of available server connection slots, + number of
4880 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08004881
Willy Tarreau55165fe2009-05-10 12:02:55 +02004882 Note that while "dst_conn" may be used, "connslots" comes in especially
4883 useful when you have a case of traffic going to one single ip, splitting into
4884 multiple backends (perhaps using acls to do name-based load balancing) and
4885 you want to be able to differentiate between different backends, and their
4886 available "connslots". Also, whereas "nbsrv" only measures servers that are
4887 actually *down*, this acl is more fine-grained and looks into the number of
4888 available connection slots as well.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08004889
Willy Tarreau55165fe2009-05-10 12:02:55 +02004890 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
4891 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
4892 then this acl clearly does not make sense, in which case the value returned
4893 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08004894
Willy Tarreau079ff0a2009-03-05 21:34:28 +01004895fe_sess_rate <integer>
4896fe_sess_rate(frontend) <integer>
4897 Returns true when the session creation rate on the current or the named
4898 frontend matches the specified values or ranges, expressed in new sessions
4899 per second. This is used to limit the connection rate to acceptable ranges in
4900 order to prevent abuse of service at the earliest moment. This can be
4901 combined with layer 4 ACLs in order to force the clients to wait a bit for
4902 the rate to go down below the limit.
4903
4904 Example :
4905 # This frontend limits incoming mails to 10/s with a max of 100
4906 # concurrent connections. We accept any connection below 10/s, and
4907 # force excess clients to wait for 100 ms. Since clients are limited to
4908 # 100 max, there cannot be more than 10 incoming mails per second.
4909 frontend mail
4910 bind :25
4911 mode tcp
4912 maxconn 100
4913 acl too_fast fe_sess_rate ge 10
4914 tcp-request inspect-delay 100ms
4915 tcp-request content accept if ! too_fast
4916 tcp-request content accept if WAIT_END
4917
4918be_sess_rate <integer>
4919be_sess_rate(backend) <integer>
4920 Returns true when the sessions creation rate on the backend matches the
4921 specified values or ranges, in number of new sessions per second. This is
4922 used to switch to an alternate backend when an expensive or fragile one
4923 reaches too high a session rate, or to limite abuse of service (eg. prevent
4924 sucking of an online dictionary).
4925
4926 Example :
4927 # Redirect to an error page if the dictionary is requested too often
4928 backend dynamic
4929 mode http
4930 acl being_scanned be_sess_rate gt 100
4931 redirect location /denied.html if being_scanned
4932
Willy Tarreau0ba27502007-12-24 16:55:16 +01004933
Willy Tarreauc57f0e22009-05-10 13:12:33 +020049347.5.2. Matching contents at Layer 4
4935-----------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02004936
4937A second set of criteria depends on data found in buffers, but which can change
4938during analysis. This requires that some data has been buffered, for instance
4939through TCP request content inspection. Please see the "tcp-request" keyword
4940for more detailed information on the subject.
4941
4942req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02004943 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02004944 specified range. It is important to understand that this test does not
4945 return false as long as the buffer is changing. This means that a check with
4946 equality to zero will almost always immediately match at the beginning of the
4947 session, while a test for more data will wait for that data to come in and
4948 return false only when haproxy is certain that no more data will come in.
4949 This test was designed to be used with TCP request content inspection.
4950
Willy Tarreau2492d5b2009-07-11 00:06:00 +02004951req_proto_http
4952 Returns true when data in the request buffer look like HTTP and correctly
4953 parses as such. It is the same parser as the common HTTP request parser which
4954 is used so there should be no surprizes. This test can be used for instance
4955 to direct HTTP traffic to a given port and HTTPS traffic to another one
4956 using TCP request content inspection rules.
4957
Emeric Brunbede3d02009-06-30 17:54:00 +02004958req_rdp_cookie <string>
4959req_rdp_cookie(name) <string>
4960 Returns true when data in the request buffer look like the RDP protocol, and
4961 a cookie is present and equal to <string>. By default, any cookie name is
4962 checked, but a specific cookie name can be specified in parenthesis. The
4963 parser only checks for the first cookie, as illustrated in the RDP protocol
4964 specification. The cookie name is case insensitive. This ACL can be useful
4965 with the "MSTS" cookie, as it can contain the user name of the client
4966 connecting to the server if properly configured on the client. This can be
4967 used to restrict access to certain servers to certain users.
4968
4969req_rdp_cookie_cnt <integer>
4970req_rdp_cookie_cnt(name) <integer>
4971 Returns true when the data in the request buffer look like the RDP protocol
4972 and the number of RDP cookies matches the specified range (typically zero or
4973 one). Optionally a specific cookie name can be checked. This is a simple way
4974 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
4975 cookies.
4976
Willy Tarreau62644772008-07-16 18:36:06 +02004977req_ssl_ver <decimal>
4978 Returns true when data in the request buffer look like SSL, with a protocol
4979 version matching the specified range. Both SSLv2 hello messages and SSLv3
4980 messages are supported. The test tries to be strict enough to avoid being
4981 easily fooled. In particular, it waits for as many bytes as announced in the
4982 message header if this header looks valid (bound to the buffer size). Note
4983 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
4984 with TCP request content inspection.
4985
Willy Tarreaub6fb4202008-07-20 11:18:28 +02004986wait_end
4987 Waits for the end of the analysis period to return true. This may be used in
4988 conjunction with content analysis to avoid returning a wrong verdict early.
4989 It may also be used to delay some actions, such as a delayed reject for some
4990 special addresses. Since it either stops the rules evaluation or immediately
4991 returns true, it is recommended to use this acl as the last one in a rule.
4992 Please note that the default ACL "WAIT_END" is always usable without prior
4993 declaration. This test was designed to be used with TCP request content
4994 inspection.
4995
4996 Examples :
4997 # delay every incoming request by 2 seconds
4998 tcp-request inspect-delay 2s
4999 tcp-request content accept if WAIT_END
5000
5001 # don't immediately tell bad guys they are rejected
5002 tcp-request inspect-delay 10s
5003 acl goodguys src 10.0.0.0/24
5004 acl badguys src 10.0.1.0/24
5005 tcp-request content accept if goodguys
5006 tcp-request content reject if badguys WAIT_END
5007 tcp-request content reject
5008
Willy Tarreau62644772008-07-16 18:36:06 +02005009
Willy Tarreauc57f0e22009-05-10 13:12:33 +020050107.5.3. Matching at Layer 7
5011--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01005012
Willy Tarreau62644772008-07-16 18:36:06 +02005013A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01005014application layer (layer 7). Those require that a full HTTP request has been
5015read, and are only evaluated then. They may require slightly more CPU resources
5016than the layer 4 ones, but not much since the request and response are indexed.
5017
Willy Tarreau6a06a402007-07-15 20:15:28 +02005018method <string>
5019 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
5020 already check for most common methods.
5021
5022req_ver <string>
5023 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
5024 ACL already check for versions 1.0 and 1.1.
5025
5026path <string>
5027 Returns true when the path part of the request, which starts at the first
5028 slash and ends before the question mark, equals one of the strings. It may be
5029 used to match known files, such as /favicon.ico.
5030
5031path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01005032 Returns true when the path begins with one of the strings. This can be used
5033 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02005034
5035path_end <string>
5036 Returns true when the path ends with one of the strings. This may be used to
5037 control file name extension.
5038
5039path_sub <string>
5040 Returns true when the path contains one of the strings. It can be used to
5041 detect particular patterns in paths, such as "../" for example. See also
5042 "path_dir".
5043
5044path_dir <string>
5045 Returns true when one of the strings is found isolated or delimited with
5046 slashes in the path. This is used to perform filename or directory name
5047 matching without the risk of wrong match due to colliding prefixes. See also
5048 "url_dir" and "path_sub".
5049
5050path_dom <string>
5051 Returns true when one of the strings is found isolated or delimited with dots
5052 in the path. This may be used to perform domain name matching in proxy
5053 requests. See also "path_sub" and "url_dom".
5054
5055path_reg <regex>
5056 Returns true when the path matches one of the regular expressions. It can be
5057 used any time, but it is important to remember that regex matching is slower
5058 than other methods. See also "url_reg" and all "path_" criteria.
5059
5060url <string>
5061 Applies to the whole URL passed in the request. The only real use is to match
5062 "*", for which there already is a predefined ACL.
5063
5064url_beg <string>
5065 Returns true when the URL begins with one of the strings. This can be used to
5066 check whether a URL begins with a slash or with a protocol scheme.
5067
5068url_end <string>
5069 Returns true when the URL ends with one of the strings. It has very limited
5070 use. "path_end" should be used instead for filename matching.
5071
5072url_sub <string>
5073 Returns true when the URL contains one of the strings. It can be used to
5074 detect particular patterns in query strings for example. See also "path_sub".
5075
5076url_dir <string>
5077 Returns true when one of the strings is found isolated or delimited with
5078 slashes in the URL. This is used to perform filename or directory name
5079 matching without the risk of wrong match due to colliding prefixes. See also
5080 "path_dir" and "url_sub".
5081
5082url_dom <string>
5083 Returns true when one of the strings is found isolated or delimited with dots
5084 in the URL. This is used to perform domain name matching without the risk of
5085 wrong match due to colliding prefixes. See also "url_sub".
5086
5087url_reg <regex>
5088 Returns true when the URL matches one of the regular expressions. It can be
5089 used any time, but it is important to remember that regex matching is slower
5090 than other methods. See also "path_reg" and all "url_" criteria.
5091
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01005092url_ip <ip_address>
Willy Tarreau0ba27502007-12-24 16:55:16 +01005093 Applies to the IP address specified in the absolute URI in an HTTP request.
5094 It can be used to prevent access to certain resources such as local network.
Willy Tarreau198a7442008-01-17 12:05:32 +01005095 It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01005096
5097url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01005098 Applies to the port specified in the absolute URI in an HTTP request. It can
5099 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01005100 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01005101 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01005102
Willy Tarreau6a06a402007-07-15 20:15:28 +02005103hdr <string>
5104hdr(header) <string>
5105 Note: all the "hdr*" matching criteria either apply to all headers, or to a
5106 particular header whose name is passed between parenthesis and without any
Willy Tarreau0ba27502007-12-24 16:55:16 +01005107 space. The header name is not case-sensitive. The header matching complies
5108 with RFC2616, and treats as separate headers all values delimited by commas.
Willy Tarreau6a06a402007-07-15 20:15:28 +02005109
5110 The "hdr" criteria returns true if any of the headers matching the criteria
Willy Tarreau0ba27502007-12-24 16:55:16 +01005111 match any of the strings. This can be used to check exact for values. For
Willy Tarreau6a06a402007-07-15 20:15:28 +02005112 instance, checking that "connection: close" is set :
5113
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005114 hdr(Connection) -i close
Willy Tarreau21d2af32008-02-14 20:25:24 +01005115
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005116hdr_beg <string>
5117hdr_beg(header) <string>
5118 Returns true when one of the headers begins with one of the strings. See
5119 "hdr" for more information on header matching.
Willy Tarreau21d2af32008-02-14 20:25:24 +01005120
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005121hdr_end <string>
5122hdr_end(header) <string>
5123 Returns true when one of the headers ends with one of the strings. See "hdr"
5124 for more information on header matching.
Willy Tarreau198a7442008-01-17 12:05:32 +01005125
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005126hdr_sub <string>
5127hdr_sub(header) <string>
5128 Returns true when one of the headers contains one of the strings. See "hdr"
5129 for more information on header matching.
Willy Tarreau5764b382007-11-30 17:46:49 +01005130
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005131hdr_dir <string>
5132hdr_dir(header) <string>
5133 Returns true when one of the headers contains one of the strings either
5134 isolated or delimited by slashes. This is used to perform filename or
5135 directory name matching, and may be used with Referer. See "hdr" for more
5136 information on header matching.
Willy Tarreau5764b382007-11-30 17:46:49 +01005137
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005138hdr_dom <string>
5139hdr_dom(header) <string>
5140 Returns true when one of the headers contains one of the strings either
5141 isolated or delimited by dots. This is used to perform domain name matching,
5142 and may be used with the Host header. See "hdr" for more information on
5143 header matching.
Willy Tarreau5764b382007-11-30 17:46:49 +01005144
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005145hdr_reg <regex>
5146hdr_reg(header) <regex>
5147 Returns true when one of the headers matches of the regular expressions. It
5148 can be used at any time, but it is important to remember that regex matching
5149 is slower than other methods. See also other "hdr_" criteria, as well as
5150 "hdr" for more information on header matching.
Willy Tarreau5764b382007-11-30 17:46:49 +01005151
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005152hdr_val <integer>
5153hdr_val(header) <integer>
5154 Returns true when one of the headers starts with a number which matches the
5155 values or ranges specified. This may be used to limit content-length to
5156 acceptable values for example. See "hdr" for more information on header
5157 matching.
Willy Tarreau198a7442008-01-17 12:05:32 +01005158
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005159hdr_cnt <integer>
5160hdr_cnt(header) <integer>
5161 Returns true when the number of occurrence of the specified header matches
5162 the values or ranges specified. It is important to remember that one header
5163 line may count as several headers if it has several values. This is used to
5164 detect presence, absence or abuse of a specific header, as well as to block
5165 request smugling attacks by rejecting requests which contain more than one
5166 of certain headers. See "hdr" for more information on header matching.
Krzysztof Piotr Oledzkic8b16fc2008-02-18 01:26:35 +01005167
Willy Tarreau106f9792009-09-19 07:54:16 +02005168hdr_ip <ip_address>
5169hdr_ip(header) <ip_address>
5170 Returns true when one of the headers' values contains an IP address matching
5171 <ip_address>. This is mainly used with headers such as X-Forwarded-For or
5172 X-Client-IP. See "hdr" for more information on header matching.
5173
Willy Tarreau198a7442008-01-17 12:05:32 +01005174
Willy Tarreauc57f0e22009-05-10 13:12:33 +020051757.6. Pre-defined ACLs
5176---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01005177
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005178Some predefined ACLs are hard-coded so that they do not have to be declared in
5179every frontend which needs them. They all have their names in upper case in
5180order to avoid confusion. Their equivalence is provided below. Please note that
5181only the first three ones are not layer 7 based.
Willy Tarreauced27012008-01-17 20:35:34 +01005182
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005183ACL name Equivalent to Usage
5184---------------+-----------------------------+---------------------------------
5185TRUE always_true always match
5186FALSE always_false never match
5187LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreau2492d5b2009-07-11 00:06:00 +02005188HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005189HTTP_1.0 req_ver 1.0 match HTTP version 1.0
5190HTTP_1.1 req_ver 1.1 match HTTP version 1.1
5191METH_CONNECT method CONNECT match HTTP CONNECT method
5192METH_GET method GET HEAD match HTTP GET or HEAD method
5193METH_HEAD method HEAD match HTTP HEAD method
5194METH_OPTIONS method OPTIONS match HTTP OPTIONS method
5195METH_POST method POST match HTTP POST method
5196METH_TRACE method TRACE match HTTP TRACE method
5197HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
5198HTTP_URL_SLASH url_beg / match URL begining with "/"
5199HTTP_URL_STAR url * match URL equal to "*"
5200HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
Emeric Brunbede3d02009-06-30 17:54:00 +02005201RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005202REQ_CONTENT req_len gt 0 match data in the request buffer
5203WAIT_END wait_end wait for end of content analysis
5204---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01005205
Willy Tarreauced27012008-01-17 20:35:34 +01005206
Willy Tarreauc57f0e22009-05-10 13:12:33 +020052077.7. Using ACLs to form conditions
5208----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01005209
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005210Some actions are only performed upon a valid condition. A condition is a
5211combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01005212
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005213 - AND (implicit)
5214 - OR (explicit with the "or" keyword or the "||" operator)
5215 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01005216
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005217A condition is formed as a disjonctive form :
Willy Tarreauced27012008-01-17 20:35:34 +01005218
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005219 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01005220
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005221Such conditions are generally used after an "if" or "unless" statement,
5222indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01005223
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005224For instance, to block HTTP requests to the "*" URL with methods other than
5225"OPTIONS", as well as POST requests without content-length, and GET or HEAD
5226requests with a content-length greater than 0, and finally every request which
5227is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01005228
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005229 acl missing_cl hdr_cnt(Content-length) eq 0
5230 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
5231 block if METH_GET HTTP_CONTENT
5232 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01005233
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005234To select a different backend for requests to static contents on the "www" site
5235and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01005236
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005237 acl url_static path_beg /static /images /img /css
5238 acl url_static path_end .gif .png .jpg .css .js
5239 acl host_www hdr_beg(host) -i www
5240 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01005241
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005242 # now use backend "static" for all static-only hosts, and for static urls
5243 # of host "www". Use backend "www" for the rest.
5244 use_backend static if host_static or host_www url_static
5245 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01005246
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005247See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01005248
Willy Tarreau5764b382007-11-30 17:46:49 +01005249
Willy Tarreauc57f0e22009-05-10 13:12:33 +020052508. Logging
5251----------
Willy Tarreau844e3c52008-01-11 16:28:18 +01005252
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005253One of HAProxy's strong points certainly lies is its precise logs. It probably
5254provides the finest level of information available for such a product, which is
5255very important for troubleshooting complex environments. Standard information
5256provided in logs include client ports, TCP/HTTP state timers, precise session
5257state at termination and precise termination cause, information about decisions
5258to direct trafic to a server, and of course the ability to capture arbitrary
5259headers.
5260
5261In order to improve administrators reactivity, it offers a great transparency
5262about encountered problems, both internal and external, and it is possible to
5263send logs to different sources at the same time with different level filters :
5264
5265 - global process-level logs (system errors, start/stop, etc..)
5266 - per-instance system and internal errors (lack of resource, bugs, ...)
5267 - per-instance external troubles (servers up/down, max connections)
5268 - per-instance activity (client connections), either at the establishment or
5269 at the termination.
5270
5271The ability to distribute different levels of logs to different log servers
5272allow several production teams to interact and to fix their problems as soon
5273as possible. For example, the system team might monitor system-wide errors,
5274while the application team might be monitoring the up/down for their servers in
5275real time, and the security team might analyze the activity logs with one hour
5276delay.
5277
5278
Willy Tarreauc57f0e22009-05-10 13:12:33 +020052798.1. Log levels
5280---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005281
5282TCP and HTTP connections can be logged with informations such as date, time,
5283source IP address, destination address, connection duration, response times,
5284HTTP request, the HTTP return code, number of bytes transmitted, the conditions
5285in which the session ended, and even exchanged cookies values, to track a
5286particular user's problems for example. All messages are sent to up to two
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005287syslog servers. Check the "log" keyword in section 4.2 for more info about log
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005288facilities.
5289
5290
Willy Tarreauc57f0e22009-05-10 13:12:33 +020052918.2. Log formats
5292----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005293
Emeric Brun3a058f32009-06-30 18:26:00 +02005294HAProxy supports 4 log formats. Several fields are common between these formats
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005295and will be detailed in the next sections. A few of them may slightly vary with
5296the configuration, due to indicators specific to certain options. The supported
5297formats are the following ones :
5298
5299 - the default format, which is very basic and very rarely used. It only
5300 provides very basic information about the incoming connection at the moment
5301 it is accepted : source IP:port, destination IP:port, and frontend-name.
5302 This mode will eventually disappear so it will not be described to great
5303 extents.
5304
5305 - the TCP format, which is more advanced. This format is enabled when "option
5306 tcplog" is set on the frontend. HAProxy will then usually wait for the
5307 connection to terminate before logging. This format provides much richer
5308 information, such as timers, connection counts, queue size, etc... This
5309 format is recommended for pure TCP proxies.
5310
5311 - the HTTP format, which is the most advanced for HTTP proxying. This format
5312 is enabled when "option httplog" is set on the frontend. It provides the
5313 same information as the TCP format with some HTTP-specific fields such as
5314 the request, the status code, and captures of headers and cookies. This
5315 format is recommended for HTTP proxies.
5316
Emeric Brun3a058f32009-06-30 18:26:00 +02005317 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
5318 fields arranged in the same order as the CLF format. In this mode, all
5319 timers, captures, flags, etc... appear one per field after the end of the
5320 common fields, in the same order they appear in the standard HTTP format.
5321
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005322Next sections will go deeper into details for each of these formats. Format
5323specification will be performed on a "field" basis. Unless stated otherwise, a
5324field is a portion of text delimited by any number of spaces. Since syslog
5325servers are susceptible of inserting fields at the beginning of a line, it is
5326always assumed that the first field is the one containing the process name and
5327identifier.
5328
5329Note : Since log lines may be quite long, the log examples in sections below
5330 might be broken into multiple lines. The example log lines will be
5331 prefixed with 3 closing angle brackets ('>>>') and each time a log is
5332 broken into multiple lines, each non-final line will end with a
5333 backslash ('\') and the next line will start indented by two characters.
5334
5335
Willy Tarreauc57f0e22009-05-10 13:12:33 +020053368.2.1. Default log format
5337-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005338
5339This format is used when no specific option is set. The log is emitted as soon
5340as the connection is accepted. One should note that this currently is the only
5341format which logs the request's destination IP and ports.
5342
5343 Example :
5344 listen www
5345 mode http
5346 log global
5347 server srv1 127.0.0.1:8000
5348
5349 >>> Feb 6 12:12:09 localhost \
5350 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
5351 (www/HTTP)
5352
5353 Field Format Extract from the example above
5354 1 process_name '[' pid ']:' haproxy[14385]:
5355 2 'Connect from' Connect from
5356 3 source_ip ':' source_port 10.0.1.2:33312
5357 4 'to' to
5358 5 destination_ip ':' destination_port 10.0.3.31:8012
5359 6 '(' frontend_name '/' mode ')' (www/HTTP)
5360
5361Detailed fields description :
5362 - "source_ip" is the IP address of the client which initiated the connection.
5363 - "source_port" is the TCP port of the client which initiated the connection.
5364 - "destination_ip" is the IP address the client connected to.
5365 - "destination_port" is the TCP port the client connected to.
5366 - "frontend_name" is the name of the frontend (or listener) which received
5367 and processed the connection.
5368 - "mode is the mode the frontend is operating (TCP or HTTP).
5369
5370It is advised not to use this deprecated format for newer installations as it
5371will eventually disappear.
5372
5373
Willy Tarreauc57f0e22009-05-10 13:12:33 +020053748.2.2. TCP log format
5375---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005376
5377The TCP format is used when "option tcplog" is specified in the frontend, and
5378is the recommended format for pure TCP proxies. It provides a lot of precious
5379information for troubleshooting. Since this format includes timers and byte
5380counts, the log is normally emitted at the end of the session. It can be
5381emitted earlier if "option logasap" is specified, which makes sense in most
5382environments with long sessions such as remote terminals. Sessions which match
5383the "monitor" rules are never logged. It is also possible not to emit logs for
5384sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005385specifying "option dontlognull" in the frontend. Successful connections will
5386not be logged if "option dontlog-normal" is specified in the frontend. A few
5387fields may slightly vary depending on some configuration options, those are
5388marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005389
5390 Example :
5391 frontend fnt
5392 mode tcp
5393 option tcplog
5394 log global
5395 default_backend bck
5396
5397 backend bck
5398 server srv1 127.0.0.1:8000
5399
5400 >>> Feb 6 12:12:56 localhost \
5401 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
5402 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
5403
5404 Field Format Extract from the example above
5405 1 process_name '[' pid ']:' haproxy[14387]:
5406 2 client_ip ':' client_port 10.0.1.2:33313
5407 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
5408 4 frontend_name fnt
5409 5 backend_name '/' server_name bck/srv1
5410 6 Tw '/' Tc '/' Tt* 0/0/5007
5411 7 bytes_read* 212
5412 8 termination_state --
5413 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
5414 10 srv_queue '/' backend_queue 0/0
5415
5416Detailed fields description :
5417 - "client_ip" is the IP address of the client which initiated the TCP
5418 connection to haproxy.
5419
5420 - "client_port" is the TCP port of the client which initiated the connection.
5421
5422 - "accept_date" is the exact date when the connection was received by haproxy
5423 (which might be very slightly different from the date observed on the
5424 network if there was some queuing in the system's backlog). This is usually
5425 the same date which may appear in any upstream firewall's log.
5426
5427 - "frontend_name" is the name of the frontend (or listener) which received
5428 and processed the connection.
5429
5430 - "backend_name" is the name of the backend (or listener) which was selected
5431 to manage the connection to the server. This will be the same as the
5432 frontend if no switching rule has been applied, which is common for TCP
5433 applications.
5434
5435 - "server_name" is the name of the last server to which the connection was
5436 sent, which might differ from the first one if there were connection errors
5437 and a redispatch occurred. Note that this server belongs to the backend
5438 which processed the request. If the connection was aborted before reaching
5439 a server, "<NOSRV>" is indicated instead of a server name.
5440
5441 - "Tw" is the total time in milliseconds spent waiting in the various queues.
5442 It can be "-1" if the connection was aborted before reaching the queue.
5443 See "Timers" below for more details.
5444
5445 - "Tc" is the total time in milliseconds spent waiting for the connection to
5446 establish to the final server, including retries. It can be "-1" if the
5447 connection was aborted before a connection could be established. See
5448 "Timers" below for more details.
5449
5450 - "Tt" is the total time in milliseconds elapsed between the accept and the
5451 last close. It covers all possible processings. There is one exception, if
5452 "option logasap" was specified, then the time counting stops at the moment
5453 the log is emitted. In this case, a '+' sign is prepended before the value,
5454 indicating that the final one will be larger. See "Timers" below for more
5455 details.
5456
5457 - "bytes_read" is the total number of bytes transmitted from the server to
5458 the client when the log is emitted. If "option logasap" is specified, the
5459 this value will be prefixed with a '+' sign indicating that the final one
5460 may be larger. Please note that this value is a 64-bit counter, so log
5461 analysis tools must be able to handle it without overflowing.
5462
5463 - "termination_state" is the condition the session was in when the session
5464 ended. This indicates the session state, which side caused the end of
5465 session to happen, and for what reason (timeout, error, ...). The normal
5466 flags should be "--", indicating the session was closed by either end with
5467 no data remaining in buffers. See below "Session state at disconnection"
5468 for more details.
5469
5470 - "actconn" is the total number of concurrent connections on the process when
5471 the session was logged. It it useful to detect when some per-process system
5472 limits have been reached. For instance, if actconn is close to 512 when
5473 multiple connection errors occur, chances are high that the system limits
5474 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005475 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005476
5477 - "feconn" is the total number of concurrent connections on the frontend when
5478 the session was logged. It is useful to estimate the amount of resource
5479 required to sustain high loads, and to detect when the frontend's "maxconn"
5480 has been reached. Most often when this value increases by huge jumps, it is
5481 because there is congestion on the backend servers, but sometimes it can be
5482 caused by a denial of service attack.
5483
5484 - "beconn" is the total number of concurrent connections handled by the
5485 backend when the session was logged. It includes the total number of
5486 concurrent connections active on servers as well as the number of
5487 connections pending in queues. It is useful to estimate the amount of
5488 additional servers needed to support high loads for a given application.
5489 Most often when this value increases by huge jumps, it is because there is
5490 congestion on the backend servers, but sometimes it can be caused by a
5491 denial of service attack.
5492
5493 - "srv_conn" is the total number of concurrent connections still active on
5494 the server when the session was logged. It can never exceed the server's
5495 configured "maxconn" parameter. If this value is very often close or equal
5496 to the server's "maxconn", it means that traffic regulation is involved a
5497 lot, meaning that either the server's maxconn value is too low, or that
5498 there aren't enough servers to process the load with an optimal response
5499 time. When only one of the server's "srv_conn" is high, it usually means
5500 that this server has some trouble causing the connections to take longer to
5501 be processed than on other servers.
5502
5503 - "retries" is the number of connection retries experienced by this session
5504 when trying to connect to the server. It must normally be zero, unless a
5505 server is being stopped at the same moment the connection was attempted.
5506 Frequent retries generally indicate either a network problem between
5507 haproxy and the server, or a misconfigured system backlog on the server
5508 preventing new connections from being queued. This field may optionally be
5509 prefixed with a '+' sign, indicating that the session has experienced a
5510 redispatch after the maximal retry count has been reached on the initial
5511 server. In this case, the server name appearing in the log is the one the
5512 connection was redispatched to, and not the first one, though both may
5513 sometimes be the same in case of hashing for instance. So as a general rule
5514 of thumb, when a '+' is present in front of the retry count, this count
5515 should not be attributed to the logged server.
5516
5517 - "srv_queue" is the total number of requests which were processed before
5518 this one in the server queue. It is zero when the request has not gone
5519 through the server queue. It makes it possible to estimate the approximate
5520 server's response time by dividing the time spent in queue by the number of
5521 requests in the queue. It is worth noting that if a session experiences a
5522 redispatch and passes through two server queues, their positions will be
5523 cumulated. A request should not pass through both the server queue and the
5524 backend queue unless a redispatch occurs.
5525
5526 - "backend_queue" is the total number of requests which were processed before
5527 this one in the backend's global queue. It is zero when the request has not
5528 gone through the global queue. It makes it possible to estimate the average
5529 queue length, which easily translates into a number of missing servers when
5530 divided by a server's "maxconn" parameter. It is worth noting that if a
5531 session experiences a redispatch, it may pass twice in the backend's queue,
5532 and then both positions will be cumulated. A request should not pass
5533 through both the server queue and the backend queue unless a redispatch
5534 occurs.
5535
5536
Willy Tarreauc57f0e22009-05-10 13:12:33 +020055378.2.3. HTTP log format
5538----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005539
5540The HTTP format is the most complete and the best suited for HTTP proxies. It
5541is enabled by when "option httplog" is specified in the frontend. It provides
5542the same level of information as the TCP format with additional features which
5543are specific to the HTTP protocol. Just like the TCP format, the log is usually
5544emitted at the end of the session, unless "option logasap" is specified, which
5545generally only makes sense for download sites. A session which matches the
5546"monitor" rules will never logged. It is also possible not to log sessions for
5547which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005548frontend. Successful connections will not be logged if "option dontlog-normal"
5549is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005550
5551Most fields are shared with the TCP log, some being different. A few fields may
5552slightly vary depending on some configuration options. Those ones are marked
5553with a star ('*') after the field name below.
5554
5555 Example :
5556 frontend http-in
5557 mode http
5558 option httplog
5559 log global
5560 default_backend bck
5561
5562 backend static
5563 server srv1 127.0.0.1:8000
5564
5565 >>> Feb 6 12:14:14 localhost \
5566 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
5567 static/srv1 10/0/30/69/109 200 2750 - - ---- 1/1/1/1/0 0/0 {1wt.eu} \
5568 {} "GET /index.html HTTP/1.1"
5569
5570 Field Format Extract from the example above
5571 1 process_name '[' pid ']:' haproxy[14389]:
5572 2 client_ip ':' client_port 10.0.1.2:33317
5573 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
5574 4 frontend_name http-in
5575 5 backend_name '/' server_name static/srv1
5576 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
5577 7 status_code 200
5578 8 bytes_read* 2750
5579 9 captured_request_cookie -
5580 10 captured_response_cookie -
5581 11 termination_state ----
5582 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
5583 13 srv_queue '/' backend_queue 0/0
5584 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
5585 15 '{' captured_response_headers* '}' {}
5586 16 '"' http_request '"' "GET /index.html HTTP/1.1"
5587
5588
5589Detailed fields description :
5590 - "client_ip" is the IP address of the client which initiated the TCP
5591 connection to haproxy.
5592
5593 - "client_port" is the TCP port of the client which initiated the connection.
5594
5595 - "accept_date" is the exact date when the TCP connection was received by
5596 haproxy (which might be very slightly different from the date observed on
5597 the network if there was some queuing in the system's backlog). This is
5598 usually the same date which may appear in any upstream firewall's log. This
5599 does not depend on the fact that the client has sent the request or not.
5600
5601 - "frontend_name" is the name of the frontend (or listener) which received
5602 and processed the connection.
5603
5604 - "backend_name" is the name of the backend (or listener) which was selected
5605 to manage the connection to the server. This will be the same as the
5606 frontend if no switching rule has been applied.
5607
5608 - "server_name" is the name of the last server to which the connection was
5609 sent, which might differ from the first one if there were connection errors
5610 and a redispatch occurred. Note that this server belongs to the backend
5611 which processed the request. If the request was aborted before reaching a
5612 server, "<NOSRV>" is indicated instead of a server name. If the request was
5613 intercepted by the stats subsystem, "<STATS>" is indicated instead.
5614
5615 - "Tq" is the total time in milliseconds spent waiting for the client to send
5616 a full HTTP request, not counting data. It can be "-1" if the connection
5617 was aborted before a complete request could be received. It should always
5618 be very small because a request generally fits in one single packet. Large
5619 times here generally indicate network trouble between the client and
5620 haproxy. See "Timers" below for more details.
5621
5622 - "Tw" is the total time in milliseconds spent waiting in the various queues.
5623 It can be "-1" if the connection was aborted before reaching the queue.
5624 See "Timers" below for more details.
5625
5626 - "Tc" is the total time in milliseconds spent waiting for the connection to
5627 establish to the final server, including retries. It can be "-1" if the
5628 request was aborted before a connection could be established. See "Timers"
5629 below for more details.
5630
5631 - "Tr" is the total time in milliseconds spent waiting for the server to send
5632 a full HTTP response, not counting data. It can be "-1" if the request was
5633 aborted before a complete response could be received. It generally matches
5634 the server's processing time for the request, though it may be altered by
5635 the amount of data sent by the client to the server. Large times here on
5636 "GET" requests generally indicate an overloaded server. See "Timers" below
5637 for more details.
5638
5639 - "Tt" is the total time in milliseconds elapsed between the accept and the
5640 last close. It covers all possible processings. There is one exception, if
5641 "option logasap" was specified, then the time counting stops at the moment
5642 the log is emitted. In this case, a '+' sign is prepended before the value,
5643 indicating that the final one will be larger. See "Timers" below for more
5644 details.
5645
5646 - "status_code" is the HTTP status code returned to the client. This status
5647 is generally set by the server, but it might also be set by haproxy when
5648 the server cannot be reached or when its response is blocked by haproxy.
5649
5650 - "bytes_read" is the total number of bytes transmitted to the client when
5651 the log is emitted. This does include HTTP headers. If "option logasap" is
5652 specified, the this value will be prefixed with a '+' sign indicating that
5653 the final one may be larger. Please note that this value is a 64-bit
5654 counter, so log analysis tools must be able to handle it without
5655 overflowing.
5656
5657 - "captured_request_cookie" is an optional "name=value" entry indicating that
5658 the client had this cookie in the request. The cookie name and its maximum
5659 length are defined by the "capture cookie" statement in the frontend
5660 configuration. The field is a single dash ('-') when the option is not
5661 set. Only one cookie may be captured, it is generally used to track session
5662 ID exchanges between a client and a server to detect session crossing
5663 between clients due to application bugs. For more details, please consult
5664 the section "Capturing HTTP headers and cookies" below.
5665
5666 - "captured_response_cookie" is an optional "name=value" entry indicating
5667 that the server has returned a cookie with its response. The cookie name
5668 and its maximum length are defined by the "capture cookie" statement in the
5669 frontend configuration. The field is a single dash ('-') when the option is
5670 not set. Only one cookie may be captured, it is generally used to track
5671 session ID exchanges between a client and a server to detect session
5672 crossing between clients due to application bugs. For more details, please
5673 consult the section "Capturing HTTP headers and cookies" below.
5674
5675 - "termination_state" is the condition the session was in when the session
5676 ended. This indicates the session state, which side caused the end of
5677 session to happen, for what reason (timeout, error, ...), just like in TCP
5678 logs, and information about persistence operations on cookies in the last
5679 two characters. The normal flags should begin with "--", indicating the
5680 session was closed by either end with no data remaining in buffers. See
5681 below "Session state at disconnection" for more details.
5682
5683 - "actconn" is the total number of concurrent connections on the process when
5684 the session was logged. It it useful to detect when some per-process system
5685 limits have been reached. For instance, if actconn is close to 512 or 1024
5686 when multiple connection errors occur, chances are high that the system
5687 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005688 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005689 system.
5690
5691 - "feconn" is the total number of concurrent connections on the frontend when
5692 the session was logged. It is useful to estimate the amount of resource
5693 required to sustain high loads, and to detect when the frontend's "maxconn"
5694 has been reached. Most often when this value increases by huge jumps, it is
5695 because there is congestion on the backend servers, but sometimes it can be
5696 caused by a denial of service attack.
5697
5698 - "beconn" is the total number of concurrent connections handled by the
5699 backend when the session was logged. It includes the total number of
5700 concurrent connections active on servers as well as the number of
5701 connections pending in queues. It is useful to estimate the amount of
5702 additional servers needed to support high loads for a given application.
5703 Most often when this value increases by huge jumps, it is because there is
5704 congestion on the backend servers, but sometimes it can be caused by a
5705 denial of service attack.
5706
5707 - "srv_conn" is the total number of concurrent connections still active on
5708 the server when the session was logged. It can never exceed the server's
5709 configured "maxconn" parameter. If this value is very often close or equal
5710 to the server's "maxconn", it means that traffic regulation is involved a
5711 lot, meaning that either the server's maxconn value is too low, or that
5712 there aren't enough servers to process the load with an optimal response
5713 time. When only one of the server's "srv_conn" is high, it usually means
5714 that this server has some trouble causing the requests to take longer to be
5715 processed than on other servers.
5716
5717 - "retries" is the number of connection retries experienced by this session
5718 when trying to connect to the server. It must normally be zero, unless a
5719 server is being stopped at the same moment the connection was attempted.
5720 Frequent retries generally indicate either a network problem between
5721 haproxy and the server, or a misconfigured system backlog on the server
5722 preventing new connections from being queued. This field may optionally be
5723 prefixed with a '+' sign, indicating that the session has experienced a
5724 redispatch after the maximal retry count has been reached on the initial
5725 server. In this case, the server name appearing in the log is the one the
5726 connection was redispatched to, and not the first one, though both may
5727 sometimes be the same in case of hashing for instance. So as a general rule
5728 of thumb, when a '+' is present in front of the retry count, this count
5729 should not be attributed to the logged server.
5730
5731 - "srv_queue" is the total number of requests which were processed before
5732 this one in the server queue. It is zero when the request has not gone
5733 through the server queue. It makes it possible to estimate the approximate
5734 server's response time by dividing the time spent in queue by the number of
5735 requests in the queue. It is worth noting that if a session experiences a
5736 redispatch and passes through two server queues, their positions will be
5737 cumulated. A request should not pass through both the server queue and the
5738 backend queue unless a redispatch occurs.
5739
5740 - "backend_queue" is the total number of requests which were processed before
5741 this one in the backend's global queue. It is zero when the request has not
5742 gone through the global queue. It makes it possible to estimate the average
5743 queue length, which easily translates into a number of missing servers when
5744 divided by a server's "maxconn" parameter. It is worth noting that if a
5745 session experiences a redispatch, it may pass twice in the backend's queue,
5746 and then both positions will be cumulated. A request should not pass
5747 through both the server queue and the backend queue unless a redispatch
5748 occurs.
5749
5750 - "captured_request_headers" is a list of headers captured in the request due
5751 to the presence of the "capture request header" statement in the frontend.
5752 Multiple headers can be captured, they will be delimited by a vertical bar
5753 ('|'). When no capture is enabled, the braces do not appear, causing a
5754 shift of remaining fields. It is important to note that this field may
5755 contain spaces, and that using it requires a smarter log parser than when
5756 it's not used. Please consult the section "Capturing HTTP headers and
5757 cookies" below for more details.
5758
5759 - "captured_response_headers" is a list of headers captured in the response
5760 due to the presence of the "capture response header" statement in the
5761 frontend. Multiple headers can be captured, they will be delimited by a
5762 vertical bar ('|'). When no capture is enabled, the braces do not appear,
5763 causing a shift of remaining fields. It is important to note that this
5764 field may contain spaces, and that using it requires a smarter log parser
5765 than when it's not used. Please consult the section "Capturing HTTP headers
5766 and cookies" below for more details.
5767
5768 - "http_request" is the complete HTTP request line, including the method,
5769 request and HTTP version string. Non-printable characters are encoded (see
5770 below the section "Non-printable characters"). This is always the last
5771 field, and it is always delimited by quotes and is the only one which can
5772 contain quotes. If new fields are added to the log format, they will be
5773 added before this field. This field might be truncated if the request is
5774 huge and does not fit in the standard syslog buffer (1024 characters). This
5775 is the reason why this field must always remain the last one.
5776
5777
Willy Tarreauc57f0e22009-05-10 13:12:33 +020057788.3. Advanced logging options
5779-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005780
5781Some advanced logging options are often looked for but are not easy to find out
5782just by looking at the various options. Here is an entry point for the few
5783options which can enable better logging. Please refer to the keywords reference
5784for more information about their usage.
5785
5786
Willy Tarreauc57f0e22009-05-10 13:12:33 +020057878.3.1. Disabling logging of external tests
5788------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005789
5790It is quite common to have some monitoring tools perform health checks on
5791haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
5792commercial load-balancer, and sometimes it will simply be a more complete
5793monitoring system such as Nagios. When the tests are very frequent, users often
5794ask how to disable logging for those checks. There are three possibilities :
5795
5796 - if connections come from everywhere and are just TCP probes, it is often
5797 desired to simply disable logging of connections without data exchange, by
5798 setting "option dontlognull" in the frontend. It also disables logging of
5799 port scans, which may or may not be desired.
5800
5801 - if the connection come from a known source network, use "monitor-net" to
5802 declare this network as monitoring only. Any host in this network will then
5803 only be able to perform health checks, and their requests will not be
5804 logged. This is generally appropriate to designate a list of equipments
5805 such as other load-balancers.
5806
5807 - if the tests are performed on a known URI, use "monitor-uri" to declare
5808 this URI as dedicated to monitoring. Any host sending this request will
5809 only get the result of a health-check, and the request will not be logged.
5810
5811
Willy Tarreauc57f0e22009-05-10 13:12:33 +020058128.3.2. Logging before waiting for the session to terminate
5813----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005814
5815The problem with logging at end of connection is that you have no clue about
5816what is happening during very long sessions, such as remote terminal sessions
5817or large file downloads. This problem can be worked around by specifying
5818"option logasap" in the frontend. Haproxy will then log as soon as possible,
5819just before data transfer begins. This means that in case of TCP, it will still
5820log the connection status to the server, and in case of HTTP, it will log just
5821after processing the server headers. In this case, the number of bytes reported
5822is the number of header bytes sent to the client. In order to avoid confusion
5823with normal logs, the total time field and the number of bytes are prefixed
5824with a '+' sign which means that real numbers are certainly larger.
5825
5826
Willy Tarreauc57f0e22009-05-10 13:12:33 +020058278.3.3. Raising log level upon errors
5828------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005829
5830Sometimes it is more convenient to separate normal traffic from errors logs,
5831for instance in order to ease error monitoring from log files. When the option
5832"log-separate-errors" is used, connections which experience errors, timeouts,
5833retries, redispatches or HTTP status codes 5xx will see their syslog level
5834raised from "info" to "err". This will help a syslog daemon store the log in
5835a separate file. It is very important to keep the errors in the normal traffic
5836file too, so that log ordering is not altered. You should also be careful if
5837you already have configured your syslog daemon to store all logs higher than
5838"notice" in an "admin" file, because the "err" level is higher than "notice".
5839
5840
Willy Tarreauc57f0e22009-05-10 13:12:33 +020058418.3.4. Disabling logging of successful connections
5842--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005843
5844Although this may sound strange at first, some large sites have to deal with
5845multiple thousands of logs per second and are experiencing difficulties keeping
5846them intact for a long time or detecting errors within them. If the option
5847"dontlog-normal" is set on the frontend, all normal connections will not be
5848logged. In this regard, a normal connection is defined as one without any
5849error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
5850and a response with a status 5xx is not considered normal and will be logged
5851too. Of course, doing is is really discouraged as it will remove most of the
5852useful information from the logs. Do this only if you have no other
5853alternative.
5854
5855
Willy Tarreauc57f0e22009-05-10 13:12:33 +020058568.4. Timing events
5857------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005858
5859Timers provide a great help in troubleshooting network problems. All values are
5860reported in milliseconds (ms). These timers should be used in conjunction with
5861the session termination flags. In TCP mode with "option tcplog" set on the
5862frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
5863mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
5864
5865 - Tq: total time to get the client request (HTTP mode only). It's the time
5866 elapsed between the moment the client connection was accepted and the
5867 moment the proxy received the last HTTP header. The value "-1" indicates
5868 that the end of headers (empty line) has never been seen. This happens when
5869 the client closes prematurely or times out.
5870
5871 - Tw: total time spent in the queues waiting for a connection slot. It
5872 accounts for backend queue as well as the server queues, and depends on the
5873 queue size, and the time needed for the server to complete previous
5874 requests. The value "-1" means that the request was killed before reaching
5875 the queue, which is generally what happens with invalid or denied requests.
5876
5877 - Tc: total time to establish the TCP connection to the server. It's the time
5878 elapsed between the moment the proxy sent the connection request, and the
5879 moment it was acknowledged by the server, or between the TCP SYN packet and
5880 the matching SYN/ACK packet in return. The value "-1" means that the
5881 connection never established.
5882
5883 - Tr: server response time (HTTP mode only). It's the time elapsed between
5884 the moment the TCP connection was established to the server and the moment
5885 the server sent its complete response headers. It purely shows its request
5886 processing time, without the network overhead due to the data transmission.
5887 It is worth noting that when the client has data to send to the server, for
5888 instance during a POST request, the time already runs, and this can distort
5889 apparent response time. For this reason, it's generally wise not to trust
5890 too much this field for POST requests initiated from clients behind an
5891 untrusted network. A value of "-1" here means that the last the response
5892 header (empty line) was never seen, most likely because the server timeout
5893 stroke before the server managed to process the request.
5894
5895 - Tt: total session duration time, between the moment the proxy accepted it
5896 and the moment both ends were closed. The exception is when the "logasap"
5897 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
5898 prefixed with a '+' sign. From this field, we can deduce "Td", the data
5899 transmission time, by substracting other timers when valid :
5900
5901 Td = Tt - (Tq + Tw + Tc + Tr)
5902
5903 Timers with "-1" values have to be excluded from this equation. In TCP
5904 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
5905 negative.
5906
5907These timers provide precious indications on trouble causes. Since the TCP
5908protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
5909that timers close to multiples of 3s are nearly always related to lost packets
5910due to network problems (wires, negociation, congestion). Moreover, if "Tt" is
5911close to a timeout value specified in the configuration, it often means that a
5912session has been aborted on timeout.
5913
5914Most common cases :
5915
5916 - If "Tq" is close to 3000, a packet has probably been lost between the
5917 client and the proxy. This is very rare on local networks but might happen
5918 when clients are on far remote networks and send large requests. It may
5919 happen that values larger than usual appear here without any network cause.
5920 Sometimes, during an attack or just after a resource starvation has ended,
5921 haproxy may accept thousands of connections in a few milliseconds. The time
5922 spent accepting these connections will inevitably slightly delay processing
5923 of other connections, and it can happen that request times in the order of
5924 a few tens of milliseconds are measured after a few thousands of new
5925 connections have been accepted at once.
5926
5927 - If "Tc" is close to 3000, a packet has probably been lost between the
5928 server and the proxy during the server connection phase. This value should
5929 always be very low, such as 1 ms on local networks and less than a few tens
5930 of ms on remote networks.
5931
Willy Tarreau55165fe2009-05-10 12:02:55 +02005932 - If "Tr" is nearly always lower than 3000 except some rare values which seem
5933 to be the average majored by 3000, there are probably some packets lost
5934 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005935
5936 - If "Tt" is large even for small byte counts, it generally is because
5937 neither the client nor the server decides to close the connection, for
5938 instance because both have agreed on a keep-alive connection mode. In order
5939 to solve this issue, it will be needed to specify "option httpclose" on
5940 either the frontend or the backend. If the problem persists, it means that
5941 the server ignores the "close" connection mode and expects the client to
5942 close. Then it will be required to use "option forceclose". Having the
5943 smallest possible 'Tt' is important when connection regulation is used with
5944 the "maxconn" option on the servers, since no new connection will be sent
5945 to the server until another one is released.
5946
5947Other noticeable HTTP log cases ('xx' means any value to be ignored) :
5948
5949 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
5950 was emitted before the data phase. All the timers are valid
5951 except "Tt" which is shorter than reality.
5952
5953 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
5954 or it aborted too early. Check the session termination flags
5955 then "timeout http-request" and "timeout client" settings.
5956
5957 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
5958 servers were out of order, because the request was invalid
5959 or forbidden by ACL rules. Check the session termination
5960 flags.
5961
5962 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
5963 actively refused it or it timed out after Tt-(Tq+Tw) ms.
5964 Check the session termination flags, then check the
5965 "timeout connect" setting. Note that the tarpit action might
5966 return similar-looking patterns, with "Tw" equal to the time
5967 the client connection was maintained open.
5968
5969 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
5970 a complete response in time, or it closed its connexion
5971 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
5972 termination flags, then check the "timeout server" setting.
5973
5974
Willy Tarreauc57f0e22009-05-10 13:12:33 +020059758.5. Session state at disconnection
5976-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005977
5978TCP and HTTP logs provide a session termination indicator in the
5979"termination_state" field, just before the number of active connections. It is
59802-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
5981each of which has a special meaning :
5982
5983 - On the first character, a code reporting the first event which caused the
5984 session to terminate :
5985
5986 C : the TCP session was unexpectedly aborted by the client.
5987
5988 S : the TCP session was unexpectedly aborted by the server, or the
5989 server explicitly refused it.
5990
5991 P : the session was prematurely aborted by the proxy, because of a
5992 connection limit enforcement, because a DENY filter was matched,
5993 because of a security check which detected and blocked a dangerous
5994 error in server response which might have caused information leak
5995 (eg: cacheable cookie), or because the response was processed by
5996 the proxy (redirect, stats, etc...).
5997
5998 R : a resource on the proxy has been exhausted (memory, sockets, source
5999 ports, ...). Usually, this appears during the connection phase, and
6000 system logs should contain a copy of the precise error. If this
6001 happens, it must be considered as a very serious anomaly which
6002 should be fixed as soon as possible by any means.
6003
6004 I : an internal error was identified by the proxy during a self-check.
6005 This should NEVER happen, and you are encouraged to report any log
6006 containing this, because this would almost certainly be a bug. It
6007 would be wise to preventively restart the process after such an
6008 event too, in case it would be caused by memory corruption.
6009
6010 c : the client-side timeout expired while waiting for the client to
6011 send or receive data.
6012
6013 s : the server-side timeout expired while waiting for the server to
6014 send or receive data.
6015
6016 - : normal session completion, both the client and the server closed
6017 with nothing left in the buffers.
6018
6019 - on the second character, the TCP or HTTP session state when it was closed :
6020
6021 R : th proxy was waiting for a complete, valid REQUEST from the client
6022 (HTTP mode only). Nothing was sent to any server.
6023
6024 Q : the proxy was waiting in the QUEUE for a connection slot. This can
6025 only happen when servers have a 'maxconn' parameter set. It can
6026 also happen in the global queue after a redispatch consecutive to
6027 a failed attempt to connect to a dying server. If no redispatch is
6028 reported, then no connection attempt was made to any server.
6029
6030 C : the proxy was waiting for the CONNECTION to establish on the
6031 server. The server might at most have noticed a connection attempt.
6032
6033 H : the proxy was waiting for complete, valid response HEADERS from the
6034 server (HTTP only).
6035
6036 D : the session was in the DATA phase.
6037
6038 L : the proxy was still transmitting LAST data to the client while the
6039 server had already finished. This one is very rare as it can only
6040 happen when the client dies while receiving the last packets.
6041
6042 T : the request was tarpitted. It has been held open with the client
6043 during the whole "timeout tarpit" duration or until the client
6044 closed, both of which will be reported in the "Tw" timer.
6045
6046 - : normal session completion after end of data transfer.
6047
6048 - the third character tells whether the persistence cookie was provided by
6049 the client (only in HTTP mode) :
6050
6051 N : the client provided NO cookie. This is usually the case for new
6052 visitors, so counting the number of occurrences of this flag in the
6053 logs generally indicate a valid trend for the site frequentation.
6054
6055 I : the client provided an INVALID cookie matching no known server.
6056 This might be caused by a recent configuration change, mixed
6057 cookies between HTTP/HTTPS sites, or an attack.
6058
6059 D : the client provided a cookie designating a server which was DOWN,
6060 so either "option persist" was used and the client was sent to
6061 this server, or it was not set and the client was redispatched to
6062 another server.
6063
6064 V : the client provided a valid cookie, and was sent to the associated
6065 server.
6066
6067 - : does not apply (no cookie set in configuration).
6068
6069 - the last character reports what operations were performed on the persistence
6070 cookie returned by the server (only in HTTP mode) :
6071
6072 N : NO cookie was provided by the server, and none was inserted either.
6073
6074 I : no cookie was provided by the server, and the proxy INSERTED one.
6075 Note that in "cookie insert" mode, if the server provides a cookie,
6076 it will still be overwritten and reported as "I" here.
6077
6078 P : a cookie was PROVIDED by the server and transmitted as-is.
6079
6080 R : the cookie provided by the server was REWRITTEN by the proxy, which
6081 happens in "cookie rewrite" or "cookie prefix" modes.
6082
6083 D : the cookie provided by the server was DELETED by the proxy.
6084
6085 - : does not apply (no cookie set in configuration).
6086
6087The combination of the two first flags give a lot of information about what was
6088happening when the session terminated, and why it did terminate. It can be
6089helpful to detect server saturation, network troubles, local system resource
6090starvation, attacks, etc...
6091
6092The most common termination flags combinations are indicated below. They are
6093alphabetically sorted, with the lowercase set just after the upper case for
6094easier finding and understanding.
6095
6096 Flags Reason
6097
6098 -- Normal termination.
6099
6100 CC The client aborted before the connection could be established to the
6101 server. This can happen when haproxy tries to connect to a recently
6102 dead (or unchecked) server, and the client aborts while haproxy is
6103 waiting for the server to respond or for "timeout connect" to expire.
6104
6105 CD The client unexpectedly aborted during data transfer. This can be
6106 caused by a browser crash, by an intermediate equipment between the
6107 client and haproxy which decided to actively break the connection,
6108 by network routing issues between the client and haproxy, or by a
6109 keep-alive session between the server and the client terminated first
6110 by the client.
6111
6112 cD The client did not send nor acknowledge any data for as long as the
6113 "timeout client" delay. This is often caused by network failures on
6114 the client side, or the client simply leaving the net uncleanly.
6115
6116 CH The client aborted while waiting for the server to start responding.
6117 It might be the server taking too long to respond or the client
6118 clicking the 'Stop' button too fast.
6119
6120 cH The "timeout client" stroke while waiting for client data during a
6121 POST request. This is sometimes caused by too large TCP MSS values
6122 for PPPoE networks which cannot transport full-sized packets. It can
6123 also happen when client timeout is smaller than server timeout and
6124 the server takes too long to respond.
6125
6126 CQ The client aborted while its session was queued, waiting for a server
6127 with enough empty slots to accept it. It might be that either all the
6128 servers were saturated or that the assigned server was taking too
6129 long a time to respond.
6130
6131 CR The client aborted before sending a full HTTP request. Most likely
6132 the request was typed by hand using a telnet client, and aborted
6133 too early. The HTTP status code is likely a 400 here. Sometimes this
6134 might also be caused by an IDS killing the connection between haproxy
6135 and the client.
6136
6137 cR The "timeout http-request" stroke before the client sent a full HTTP
6138 request. This is sometimes caused by too large TCP MSS values on the
6139 client side for PPPoE networks which cannot transport full-sized
6140 packets, or by clients sending requests by hand and not typing fast
6141 enough, or forgetting to enter the empty line at the end of the
6142 request. The HTTP status code is likely a 408 here.
6143
6144 CT The client aborted while its session was tarpitted. It is important to
6145 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +02006146 wrong tarpit rules have been written. If a lot of them happen, it
6147 might make sense to lower the "timeout tarpit" value to something
6148 closer to the average reported "Tw" timer, in order not to consume
6149 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006150
6151 SC The server or an equipement between it and haproxy explicitly refused
6152 the TCP connection (the proxy received a TCP RST or an ICMP message
6153 in return). Under some circumstances, it can also be the network
6154 stack telling the proxy that the server is unreachable (eg: no route,
6155 or no ARP response on local network). When this happens in HTTP mode,
6156 the status code is likely a 502 or 503 here.
6157
6158 sC The "timeout connect" stroke before a connection to the server could
6159 complete. When this happens in HTTP mode, the status code is likely a
6160 503 or 504 here.
6161
6162 SD The connection to the server died with an error during the data
6163 transfer. This usually means that haproxy has received an RST from
6164 the server or an ICMP message from an intermediate equipment while
6165 exchanging data with the server. This can be caused by a server crash
6166 or by a network issue on an intermediate equipment.
6167
6168 sD The server did not send nor acknowledge any data for as long as the
6169 "timeout server" setting during the data phase. This is often caused
6170 by too short timeouts on L4 equipements before the server (firewalls,
6171 load-balancers, ...), as well as keep-alive sessions maintained
6172 between the client and the server expiring first on haproxy.
6173
6174 SH The server aborted before sending its full HTTP response headers, or
6175 it crashed while processing the request. Since a server aborting at
6176 this moment is very rare, it would be wise to inspect its logs to
6177 control whether it crashed and why. The logged request may indicate a
6178 small set of faulty requests, demonstrating bugs in the application.
6179 Sometimes this might also be caused by an IDS killing the connection
6180 between haproxy and the server.
6181
6182 sH The "timeout server" stroke before the server could return its
6183 response headers. This is the most common anomaly, indicating too
6184 long transactions, probably caused by server or database saturation.
6185 The immediate workaround consists in increasing the "timeout server"
6186 setting, but it is important to keep in mind that the user experience
6187 will suffer from these long response times. The only long term
6188 solution is to fix the application.
6189
6190 sQ The session spent too much time in queue and has been expired. See
6191 the "timeout queue" and "timeout connect" settings to find out how to
6192 fix this if it happens too often. If it often happens massively in
6193 short periods, it may indicate general problems on the affected
6194 servers due to I/O or database congestion, or saturation caused by
6195 external attacks.
6196
6197 PC The proxy refused to establish a connection to the server because the
6198 process' socket limit has been reached while attempting to connect.
6199 The global "maxconn" parameter may be increased in the configuration
6200 so that it does not happen anymore. This status is very rare and
6201 might happen when the global "ulimit-n" parameter is forced by hand.
6202
6203 PH The proxy blocked the server's response, because it was invalid,
6204 incomplete, dangerous (cache control), or matched a security filter.
6205 In any case, an HTTP 502 error is sent to the client. One possible
6206 cause for this error is an invalid syntax in an HTTP header name
6207 containing unauthorized characters.
6208
6209 PR The proxy blocked the client's HTTP request, either because of an
6210 invalid HTTP syntax, in which case it returned an HTTP 400 error to
6211 the client, or because a deny filter matched, in which case it
6212 returned an HTTP 403 error.
6213
6214 PT The proxy blocked the client's request and has tarpitted its
6215 connection before returning it a 500 server error. Nothing was sent
6216 to the server. The connection was maintained open for as long as
6217 reported by the "Tw" timer field.
6218
6219 RC A local resource has been exhausted (memory, sockets, source ports)
6220 preventing the connection to the server from establishing. The error
6221 logs will tell precisely what was missing. This is very rare and can
6222 only be solved by proper system tuning.
6223
6224
Willy Tarreauc57f0e22009-05-10 13:12:33 +020062258.6. Non-printable characters
6226-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006227
6228In order not to cause trouble to log analysis tools or terminals during log
6229consulting, non-printable characters are not sent as-is into log files, but are
6230converted to the two-digits hexadecimal representation of their ASCII code,
6231prefixed by the character '#'. The only characters that can be logged without
6232being escaped are comprised between 32 and 126 (inclusive). Obviously, the
6233escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
6234is the same for the character '"' which becomes "#22", as well as '{', '|' and
6235'}' when logging headers.
6236
6237Note that the space character (' ') is not encoded in headers, which can cause
6238issues for tools relying on space count to locate fields. A typical header
6239containing spaces is "User-Agent".
6240
6241Last, it has been observed that some syslog daemons such as syslog-ng escape
6242the quote ('"') with a backslash ('\'). The reverse operation can safely be
6243performed since no quote may appear anywhere else in the logs.
6244
6245
Willy Tarreauc57f0e22009-05-10 13:12:33 +020062468.7. Capturing HTTP cookies
6247---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006248
6249Cookie capture simplifies the tracking a complete user session. This can be
6250achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006251section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006252cookie will simultaneously be checked in the request ("Cookie:" header) and in
6253the response ("Set-Cookie:" header). The respective values will be reported in
6254the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006255locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006256not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
6257user switches to a new session for example, because the server will reassign it
6258a new cookie. It is also possible to detect if a server unexpectedly sets a
6259wrong cookie to a client, leading to session crossing.
6260
6261 Examples :
6262 # capture the first cookie whose name starts with "ASPSESSION"
6263 capture cookie ASPSESSION len 32
6264
6265 # capture the first cookie whose name is exactly "vgnvisitor"
6266 capture cookie vgnvisitor= len 32
6267
6268
Willy Tarreauc57f0e22009-05-10 13:12:33 +020062698.8. Capturing HTTP headers
6270---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006271
6272Header captures are useful to track unique request identifiers set by an upper
6273proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
6274the response, one can search for information about the response length, how the
6275server asked the cache to behave, or an object location during a redirection.
6276
6277Header captures are performed using the "capture request header" and "capture
6278response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006279section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006280
6281It is possible to include both request headers and response headers at the same
6282time. Non-existant headers are logged as empty strings, and if one header
6283appears more than once, only its last occurence will be logged. Request headers
6284are grouped within braces '{' and '}' in the same order as they were declared,
6285and delimited with a vertical bar '|' without any space. Response headers
6286follow the same representation, but are displayed after a space following the
6287request headers block. These blocks are displayed just before the HTTP request
6288in the logs.
6289
6290 Example :
6291 # This instance chains to the outgoing proxy
6292 listen proxy-out
6293 mode http
6294 option httplog
6295 option logasap
6296 log global
6297 server cache1 192.168.1.1:3128
6298
6299 # log the name of the virtual server
6300 capture request header Host len 20
6301
6302 # log the amount of data uploaded during a POST
6303 capture request header Content-Length len 10
6304
6305 # log the beginning of the referrer
6306 capture request header Referer len 20
6307
6308 # server name (useful for outgoing proxies only)
6309 capture response header Server len 20
6310
6311 # logging the content-length is useful with "option logasap"
6312 capture response header Content-Length len 10
6313
6314 # log the expected cache behaviour on the response
6315 capture response header Cache-Control len 8
6316
6317 # the Via header will report the next proxy's name
6318 capture response header Via len 20
6319
6320 # log the URL location during a redirection
6321 capture response header Location len 20
6322
6323 >>> Aug 9 20:26:09 localhost \
6324 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
6325 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
6326 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
6327 "GET http://fr.adserver.yahoo.com/"
6328
6329 >>> Aug 9 20:30:46 localhost \
6330 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
6331 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
6332 {w.ods.org||} {Formilux/0.1.8|3495|||} \
6333 "GET http://trafic.1wt.eu/ HTTP/1.1"
6334
6335 >>> Aug 9 20:30:46 localhost \
6336 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
6337 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
6338 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
6339 {Apache|230|||http://www.sytadin.} \
6340 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
6341
6342
Willy Tarreauc57f0e22009-05-10 13:12:33 +020063438.9. Examples of logs
6344---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006345
6346These are real-world examples of logs accompanied with an explanation. Some of
6347them have been made up by hand. The syslog part has been removed for better
6348reading. Their sole purpose is to explain how to decipher them.
6349
6350 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
6351 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
6352 "HEAD / HTTP/1.0"
6353
6354 => long request (6.5s) entered by hand through 'telnet'. The server replied
6355 in 147 ms, and the session ended normally ('----')
6356
6357 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
6358 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
6359 0/9 "HEAD / HTTP/1.0"
6360
6361 => Idem, but the request was queued in the global queue behind 9 other
6362 requests, and waited there for 1230 ms.
6363
6364 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
6365 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
6366 "GET /image.iso HTTP/1.0"
6367
6368 => request for a long data transfer. The "logasap" option was specified, so
6369 the log was produced just before transfering data. The server replied in
6370 14 ms, 243 bytes of headers were sent to the client, and total time from
6371 accept to first data byte is 30 ms.
6372
6373 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
6374 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
6375 "GET /cgi-bin/bug.cgi? HTTP/1.0"
6376
6377 => the proxy blocked a server response either because of an "rspdeny" or
6378 "rspideny" filter, or because the response was improperly formatted and
6379 not HTTP-compliant, or because it blocked sensible information which
6380 risked being cached. In this case, the response is replaced with a "502
6381 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
6382 to return the 502 and not the server.
6383
6384 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
6385 px-http/<NOSRV> -1/-1/-1/-1/8490 -1 0 - - CR-- 2/2/2/0/0 0/0 ""
6386
6387 => the client never completed its request and aborted itself ("C---") after
6388 8.5s, while the proxy was waiting for the request headers ("-R--").
6389 Nothing was sent to any server.
6390
6391 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
6392 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
6393
6394 => The client never completed its request, which was aborted by the
6395 time-out ("c---") after 50s, while the proxy was waiting for the request
6396 headers ("-R--"). Nothing was sent to any server, but the proxy could
6397 send a 408 return code to the client.
6398
6399 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
6400 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
6401
6402 => This log was produced with "option tcplog". The client timed out after
6403 5 seconds ("c----").
6404
6405 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
6406 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
6407 0/0 "HEAD / HTTP/1.0"
6408
6409 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006410 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006411 (config says 'retries 3'), and no redispatch (otherwise we would have
6412 seen "/+3"). Status code 503 was returned to the client. There were 115
6413 connections on this server, 202 connections on this proxy, and 205 on
6414 the global process. It is possible that the server refused the
6415 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006416
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006417
Willy Tarreauc57f0e22009-05-10 13:12:33 +020064189. Statistics and monitoring
6419----------------------------
6420
6421It is possible to query HAProxy about its status. The most commonly used
6422mechanism is the HTTP statistics page. This page also exposes an alternative
6423CSV output format for monitoring tools. The same format is provided on the
6424Unix socket.
6425
6426
64279.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006428---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01006429
Willy Tarreau7f062c42009-03-05 18:43:00 +01006430The statistics may be consulted either from the unix socket or from the HTTP
6431page. Both means provide a CSV format whose fields follow.
6432
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01006433 0. pxname: proxy name
6434 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
6435 for server)
6436 2. qcur: current queued requests
6437 3. qmax: max queued requests
6438 4. scur: current sessions
6439 5. smax: max sessions
6440 6. slim: sessions limit
6441 7. stot: total sessions
6442 8. bin: bytes in
6443 9. bout: bytes out
6444 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01006445 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01006446 12. ereq: request errors
6447 13. econ: connection errors
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01006448 14. eresp: response errors
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01006449 15. wretr: retries (warning)
6450 16. wredis: redispatches (warning)
6451 17. status: status (UP/DOWN/...)
6452 18. weight: server weight (server), total weight (backend)
6453 19. act: server is active (server), number of active servers (backend)
6454 20. bck: server is backup (server), number of backup servers (backend)
6455 21. chkfail: number of failed checks
6456 22. chkdown: number of UP->DOWN transitions
6457 23. lastchg: last status change (in seconds)
6458 24. downtime: total downtime (in seconds)
6459 25. qlimit: queue limit
6460 26. pid: process id (0 for first instance, 1 for second, ...)
6461 27. iid: unique proxy id
6462 28. sid: service id (unique inside a proxy)
6463 29. throttle: warm up status
6464 30. lbtot: total number of times a server was selected
6465 31. tracked: id of proxy/server if tracking is enabled
6466 32. type (0=frontend, 1=backend, 2=server)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +02006467 33. rate: number of sessions per second over last elapsed second
6468 34. rate_lim: limit on new sessions per second
6469 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +02006470 36. check_status: status of last health check, one of:
6471 UNK -> unknown
6472 INI -> initializing
6473 SOCKERR -> socket error
6474 L4OK -> check passed on layer 4, no upper layers testing enabled
6475 L4TMOUT -> layer 1-4 timeout
6476 L4CON -> layer 1-4 connection problem, for example "Connection refused"
6477 (tcp rst) or "No route to host" (icmp)
6478 L6OK -> check passed on layer 6
6479 L6TOUT -> layer 6 (SSL) timeout
6480 L6RSP -> layer 6 invalid response - protocol error
6481 L7OK -> check passed on layer 7
6482 L7OKC -> check conditionally passed on layer 7, for example 404 with
6483 disable-on-404
6484 L7TOUT -> layer 7 (HTTP/SMTP) timeout
6485 L7RSP -> layer 7 invalid response - protocol error
6486 L7STS -> layer 7 response error, for example HTTP 5xx
6487 37. check_code: layer5-7 code, if available
6488 38. check_duration: time in ms took to finish last health check
Willy Tarreau844e3c52008-01-11 16:28:18 +01006489
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006490
Willy Tarreauc57f0e22009-05-10 13:12:33 +020064919.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006492-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01006493
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006494The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02006495must be terminated by a line feed. The socket supports pipelining, so that it
6496is possible to chain multiple commands at once provided they are delimited by
6497a semi-colon or a line feed, although the former is more reliable as it has no
6498risk of being truncated over the network. The responses themselves will each be
6499followed by an empty line, so it will be easy for an external script to match a
6500given response with a given request. By default one command line is processed
6501then the connection closes, but there is an interactive allowing multiple lines
6502to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006503
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02006504It is important to understand that when multiple haproxy processes are started
6505on the same sockets, any process may pick up the request and will output its
6506own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006507
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02006508help
6509 Print the list of known keywords and their basic usage. The same help screen
6510 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +01006511
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02006512prompt
6513 Toggle the prompt at the beginning of the line and enter or leave interactive
6514 mode. In interactive mode, the connection is not closed after a command
6515 completes. Instead, the prompt will appear again, indicating the user that
6516 the interpreter is waiting for a new command. The prompt consists in a right
6517 angle bracket followed by a space "> ". This mode is particularly convenient
6518 when one wants to periodically check information such as stats or errors.
6519 It is also a good idea to enter interactive mode before issuing a "help"
6520 command.
6521
6522quit
6523 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01006524
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01006525show errors [<iid>]
6526 Dump last known request and response errors collected by frontends and
6527 backends. If <iid> is specified, the limit the dump to errors concerning
6528 either frontend or backend whose ID is <iid>.
6529
6530 The errors which may be collected are the last request and response errors
6531 caused by protocol violations, often due to invalid characters in header
6532 names. The report precisely indicates what exact character violated the
6533 protocol. Other important information such as the exact date the error was
6534 detected, frontend and backend names, the server name (when known), the
6535 internal session ID and the source address which has initiated the session
6536 are reported too.
6537
6538 All characters are returned, and non-printable characters are encoded. The
6539 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
6540 letter following a backslash. The backslash itself is encoded as '\\' to
6541 avoid confusion. Other non-printable characters are encoded '\xNN' where
6542 NN is the two-digits hexadecimal representation of the character's ASCII
6543 code.
6544
6545 Lines are prefixed with the position of their first character, starting at 0
6546 for the beginning of the buffer. At most one input line is printed per line,
6547 and large lines will be broken into multiple consecutive output lines so that
6548 the output never goes beyond 79 characters wide. It is easy to detect if a
6549 line was broken, because it will not end with '\n' and the next line's offset
6550 will be followed by a '+' sign, indicating it is a continuation of previous
6551 line.
6552
6553 Example :
6554 >>> $ echo "show errors" | socat stdio /tmp/sock1
6555 [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
6556 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
6557 response length 213 bytes, error at position 23:
6558
6559 00000 HTTP/1.0 200 OK\r\n
6560 00017 header/bizarre:blah\r\n
6561 00038 Location: blah\r\n
6562 00054 Long-line: this is a very long line which should b
6563 00104+ e broken into multiple lines on the output buffer,
6564 00154+ otherwise it would be too large to print in a ter
6565 00204+ minal\r\n
6566 00211 \r\n
6567
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006568 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +01006569 ID 2 has blocked an invalid response from its server s2 which has internal
6570 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
6571 received by frontend fe-eth0 whose ID is 1. The total response length was
6572 213 bytes when the error was detected, and the error was at byte 23. This
6573 is the slash ('/') in header name "header/bizarre", which is not a valid
6574 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +01006575
Willy Tarreau9a42c0d2009-09-22 19:31:03 +02006576show info
6577 Dump info about haproxy status on current process.
6578
6579show sess
6580 Dump all known sessions. Avoid doing this on slow connections as this can
6581 be huge.
6582
6583show stat [<iid> <type> <sid>]
6584 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
6585 possible to dump only selected items :
6586 - <iid> is a proxy ID, -1 to dump everything
6587 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
6588 backends, 4 for servers, -1 for everything. These values can be ORed,
6589 for example:
6590 1 + 2 = 3 -> frontend + backend.
6591 1 + 2 + 4 = 7 -> frontend + backend + server.
6592 - <sid> is a server ID, -1 to dump everything from the selected proxy.
6593
6594 Example :
6595 >>> $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
6596 Name: HAProxy
6597 Version: 1.4-dev2-49
6598 Release_date: 2009/09/23
6599 Nbproc: 1
6600 Process_num: 1
6601 (...)
6602
6603 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
6604 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
6605 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
6606 (...)
6607 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
6608
6609 $
6610
6611 Here, two commands have been issued at once. That way it's easy to find
6612 which process the stats apply to in multi-process mode. Notice the empty
6613 line after the information output which marks the end of the first block.
6614 A similar empty line appears at the end of the second block (stats) so that
6615 the reader knows the output has not been trucated.
6616
Willy Tarreau0ba27502007-12-24 16:55:16 +01006617/*
6618 * Local variables:
6619 * fill-column: 79
6620 * End:
6621 */