blob: 3ae662428480bca2345ae4a409ea5f982308cdf6 [file] [log] [blame]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001 ----------------------
Willy Tarreau8317b282014-04-23 01:49:41 +02002 HAProxy
Willy Tarreau6a06a402007-07-15 20:15:28 +02003 Configuration Manual
4 ----------------------
Willy Tarreaucd069922015-02-01 07:54:32 +01005 version 1.5.11
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreaucd069922015-02-01 07:54:32 +01007 2015/02/01
Willy Tarreau6a06a402007-07-15 20:15:28 +02008
9
10This document covers the configuration language as implemented in the version
11specified above. It does not provide any hint, example or advice. For such
Willy Tarreau0ba27502007-12-24 16:55:16 +010012documentation, please refer to the Reference Manual or the Architecture Manual.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013The summary below is meant to help you search sections by name and navigate
14through the document.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016Note to documentation contributors :
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017 This document is formatted with 80 columns per line, with even number of
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018 spaces for indentation and without tabs. Please follow these rules strictly
19 so that it remains easily printable everywhere. If a line needs to be
20 printed verbatim and does not fit, please end each line with a backslash
Willy Tarreau62a36c42010-08-17 15:53:10 +020021 ('\') and continue on next line, indented by two characters. It is also
22 sometimes useful to prefix all output lines (logs, console outs) with 3
23 closing angle brackets ('>>>') in order to help get the difference between
24 inputs and outputs when it can become ambiguous. If you add sections,
25 please update the summary below for easier searching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020026
27
28Summary
29-------
30
311. Quick reminder about HTTP
321.1. The HTTP transaction model
331.2. HTTP request
341.2.1. The Request line
351.2.2. The request headers
361.3. HTTP response
371.3.1. The Response line
381.3.2. The response headers
39
402. Configuring HAProxy
412.1. Configuration file format
422.2. Time format
Patrick Mezard35da19c2010-06-12 17:02:47 +0200432.3. Examples
Willy Tarreauc57f0e22009-05-10 13:12:33 +020044
453. Global parameters
463.1. Process management and security
473.2. Performance tuning
483.3. Debugging
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100493.4. Userlists
Cyril Bontédc4d9032012-04-08 21:57:39 +0200503.5. Peers
Willy Tarreauc57f0e22009-05-10 13:12:33 +020051
524. Proxies
534.1. Proxy keywords matrix
544.2. Alphabetically sorted keywords reference
55
Willy Tarreau086fbf52012-09-24 20:34:51 +0200565. Bind and Server options
575.1. Bind options
585.2. Server and default-server options
Willy Tarreauc57f0e22009-05-10 13:12:33 +020059
606. HTTP header manipulation
61
Willy Tarreau74ca5042013-06-11 23:12:07 +0200627. Using ACLs and fetching samples
637.1. ACL basics
647.1.1. Matching booleans
657.1.2. Matching integers
667.1.3. Matching strings
677.1.4. Matching regular expressions (regexes)
687.1.5. Matching arbitrary data blocks
697.1.6. Matching IPv4 and IPv6 addresses
707.2. Using ACLs to form conditions
717.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200727.3.1. Converters
737.3.2. Fetching samples from internal states
747.3.3. Fetching samples at Layer 4
757.3.4. Fetching samples at Layer 5
767.3.5. Fetching samples from buffer contents (Layer 6)
777.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +0200787.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079
808. Logging
818.1. Log levels
828.2. Log formats
838.2.1. Default log format
848.2.2. TCP log format
858.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100868.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100878.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200888.3. Advanced logging options
898.3.1. Disabling logging of external tests
908.3.2. Logging before waiting for the session to terminate
918.3.3. Raising log level upon errors
928.3.4. Disabling logging of successful connections
938.4. Timing events
948.5. Session state at disconnection
958.6. Non-printable characters
968.7. Capturing HTTP cookies
978.8. Capturing HTTP headers
988.9. Examples of logs
99
1009. Statistics and monitoring
1019.1. CSV format
1029.2. Unix Socket commands
103
104
1051. Quick reminder about HTTP
106----------------------------
107
108When haproxy is running in HTTP mode, both the request and the response are
109fully analyzed and indexed, thus it becomes possible to build matching criteria
110on almost anything found in the contents.
111
112However, it is important to understand how HTTP requests and responses are
113formed, and how HAProxy decomposes them. It will then become easier to write
114correct rules and to debug existing configurations.
115
116
1171.1. The HTTP transaction model
118-------------------------------
119
120The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100121to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200122from the client to the server, a request is sent by the client on the
123connection, the server responds and the connection is closed. A new request
124will involve a new connection :
125
126 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
127
128In this mode, called the "HTTP close" mode, there are as many connection
129establishments as there are HTTP transactions. Since the connection is closed
130by the server after the response, the client does not need to know the content
131length.
132
133Due to the transactional nature of the protocol, it was possible to improve it
134to avoid closing a connection between two subsequent transactions. In this mode
135however, it is mandatory that the server indicates the content length for each
136response so that the client does not wait indefinitely. For this, a special
137header is used: "Content-length". This mode is called the "keep-alive" mode :
138
139 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
140
141Its advantages are a reduced latency between transactions, and less processing
142power required on the server side. It is generally better than the close mode,
143but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200144a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200145
146A last improvement in the communications is the pipelining mode. It still uses
147keep-alive, but the client does not wait for the first response to send the
148second request. This is useful for fetching large number of images composing a
149page :
150
151 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
152
153This can obviously have a tremendous benefit on performance because the network
154latency is eliminated between subsequent requests. Many HTTP agents do not
155correctly support pipelining since there is no way to associate a response with
156the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100157server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200158
Willy Tarreau70dffda2014-01-30 03:07:23 +0100159By default HAProxy operates in keep-alive mode with regards to persistent
160connections: for each connection it processes each request and response, and
161leaves the connection idle on both sides between the end of a response and the
162start of a new request.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200163
Willy Tarreau70dffda2014-01-30 03:07:23 +0100164HAProxy supports 5 connection modes :
165 - keep alive : all requests and responses are processed (default)
166 - tunnel : only the first request and response are processed,
167 everything else is forwarded with no analysis.
168 - passive close : tunnel with "Connection: close" added in both directions.
169 - server close : the server-facing connection is closed after the response.
170 - forced close : the connection is actively closed after end of response.
171
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172
1731.2. HTTP request
174-----------------
175
176First, let's consider this HTTP request :
177
178 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100179 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200180 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
181 2 Host: www.mydomain.com
182 3 User-agent: my small browser
183 4 Accept: image/jpeg, image/gif
184 5 Accept: image/png
185
186
1871.2.1. The Request line
188-----------------------
189
190Line 1 is the "request line". It is always composed of 3 fields :
191
192 - a METHOD : GET
193 - a URI : /serv/login.php?lang=en&profile=2
194 - a version tag : HTTP/1.1
195
196All of them are delimited by what the standard calls LWS (linear white spaces),
197which are commonly spaces, but can also be tabs or line feeds/carriage returns
198followed by spaces/tabs. The method itself cannot contain any colon (':') and
199is limited to alphabetic letters. All those various combinations make it
200desirable that HAProxy performs the splitting itself rather than leaving it to
201the user to write a complex or inaccurate regular expression.
202
203The URI itself can have several forms :
204
205 - A "relative URI" :
206
207 /serv/login.php?lang=en&profile=2
208
209 It is a complete URL without the host part. This is generally what is
210 received by servers, reverse proxies and transparent proxies.
211
212 - An "absolute URI", also called a "URL" :
213
214 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
215
216 It is composed of a "scheme" (the protocol name followed by '://'), a host
217 name or address, optionally a colon (':') followed by a port number, then
218 a relative URI beginning at the first slash ('/') after the address part.
219 This is generally what proxies receive, but a server supporting HTTP/1.1
220 must accept this form too.
221
222 - a star ('*') : this form is only accepted in association with the OPTIONS
223 method and is not relayable. It is used to inquiry a next hop's
224 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100225
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200226 - an address:port combination : 192.168.0.12:80
227 This is used with the CONNECT method, which is used to establish TCP
228 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
229 other protocols too.
230
231In a relative URI, two sub-parts are identified. The part before the question
232mark is called the "path". It is typically the relative path to static objects
233on the server. The part after the question mark is called the "query string".
234It is mostly used with GET requests sent to dynamic scripts and is very
235specific to the language, framework or application in use.
236
237
2381.2.2. The request headers
239--------------------------
240
241The headers start at the second line. They are composed of a name at the
242beginning of the line, immediately followed by a colon (':'). Traditionally,
243an LWS is added after the colon but that's not required. Then come the values.
244Multiple identical headers may be folded into one single line, delimiting the
245values with commas, provided that their order is respected. This is commonly
246encountered in the "Cookie:" field. A header may span over multiple lines if
247the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
248define a total of 3 values for the "Accept:" header.
249
250Contrary to a common mis-conception, header names are not case-sensitive, and
251their values are not either if they refer to other header names (such as the
252"Connection:" header).
253
254The end of the headers is indicated by the first empty line. People often say
255that it's a double line feed, which is not exact, even if a double line feed
256is one valid form of empty line.
257
258Fortunately, HAProxy takes care of all these complex combinations when indexing
259headers, checking values and counting them, so there is no reason to worry
260about the way they could be written, but it is important not to accuse an
261application of being buggy if it does unusual, valid things.
262
263Important note:
264 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
265 in the middle of headers by LWS in order to join multi-line headers. This
266 is necessary for proper analysis and helps less capable HTTP parsers to work
267 correctly and not to be fooled by such complex constructs.
268
269
2701.3. HTTP response
271------------------
272
273An HTTP response looks very much like an HTTP request. Both are called HTTP
274messages. Let's consider this HTTP response :
275
276 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100277 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200278 1 HTTP/1.1 200 OK
279 2 Content-length: 350
280 3 Content-Type: text/html
281
Willy Tarreau816b9792009-09-15 21:25:21 +0200282As a special case, HTTP supports so called "Informational responses" as status
283codes 1xx. These messages are special in that they don't convey any part of the
284response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100285continue to post its request for instance. In the case of a status 100 response
286the requested information will be carried by the next non-100 response message
287following the informational one. This implies that multiple responses may be
288sent to a single request, and that this only works when keep-alive is enabled
289(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
290correctly forward and skip them, and only process the next non-100 response. As
291such, these messages are neither logged nor transformed, unless explicitly
292state otherwise. Status 101 messages indicate that the protocol is changing
293over the same connection and that haproxy must switch to tunnel mode, just as
294if a CONNECT had occurred. Then the Upgrade header would contain additional
295information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200296
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200297
2981.3.1. The Response line
299------------------------
300
301Line 1 is the "response line". It is always composed of 3 fields :
302
303 - a version tag : HTTP/1.1
304 - a status code : 200
305 - a reason : OK
306
307The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200308 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200309 - 2xx = OK, content is following (eg: 200, 206)
310 - 3xx = OK, no content following (eg: 302, 304)
311 - 4xx = error caused by the client (eg: 401, 403, 404)
312 - 5xx = error caused by the server (eg: 500, 502, 503)
313
314Please refer to RFC2616 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100315"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200316found there, but it's a common practice to respect the well-established
317messages. It can be composed of one or multiple words, such as "OK", "Found",
318or "Authentication Required".
319
320Haproxy may emit the following status codes by itself :
321
322 Code When / reason
323 200 access to stats page, and when replying to monitoring requests
324 301 when performing a redirection, depending on the configured code
325 302 when performing a redirection, depending on the configured code
326 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100327 307 when performing a redirection, depending on the configured code
328 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200329 400 for an invalid or too large request
330 401 when an authentication is required to perform the action (when
331 accessing the stats page)
332 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
333 408 when the request timeout strikes before the request is complete
334 500 when haproxy encounters an unrecoverable internal error, such as a
335 memory allocation failure, which should never happen
336 502 when the server returns an empty, invalid or incomplete response, or
337 when an "rspdeny" filter blocks the response.
338 503 when no server was available to handle the request, or in response to
339 monitoring requests which match the "monitor fail" condition
340 504 when the response timeout strikes before the server responds
341
342The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3434.2).
344
345
3461.3.2. The response headers
347---------------------------
348
349Response headers work exactly like request headers, and as such, HAProxy uses
350the same parsing function for both. Please refer to paragraph 1.2.2 for more
351details.
352
353
3542. Configuring HAProxy
355----------------------
356
3572.1. Configuration file format
358------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200359
360HAProxy's configuration process involves 3 major sources of parameters :
361
362 - the arguments from the command-line, which always take precedence
363 - the "global" section, which sets process-wide parameters
364 - the proxies sections which can take form of "defaults", "listen",
365 "frontend" and "backend".
366
Willy Tarreau0ba27502007-12-24 16:55:16 +0100367The configuration file syntax consists in lines beginning with a keyword
368referenced in this manual, optionally followed by one or several parameters
369delimited by spaces. If spaces have to be entered in strings, then they must be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100370preceded by a backslash ('\') to be escaped. Backslashes also have to be
Willy Tarreau0ba27502007-12-24 16:55:16 +0100371escaped by doubling them.
372
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200373
3742.2. Time format
375----------------
376
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100377Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100378values are generally expressed in milliseconds (unless explicitly stated
379otherwise) but may be expressed in any other unit by suffixing the unit to the
380numeric value. It is important to consider this because it will not be repeated
381for every keyword. Supported units are :
382
383 - us : microseconds. 1 microsecond = 1/1000000 second
384 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
385 - s : seconds. 1s = 1000ms
386 - m : minutes. 1m = 60s = 60000ms
387 - h : hours. 1h = 60m = 3600s = 3600000ms
388 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
389
390
Patrick Mezard35da19c2010-06-12 17:02:47 +02003912.3. Examples
392-------------
393
394 # Simple configuration for an HTTP proxy listening on port 80 on all
395 # interfaces and forwarding requests to a single backend "servers" with a
396 # single server "server1" listening on 127.0.0.1:8000
397 global
398 daemon
399 maxconn 256
400
401 defaults
402 mode http
403 timeout connect 5000ms
404 timeout client 50000ms
405 timeout server 50000ms
406
407 frontend http-in
408 bind *:80
409 default_backend servers
410
411 backend servers
412 server server1 127.0.0.1:8000 maxconn 32
413
414
415 # The same configuration defined with a single listen block. Shorter but
416 # less expressive, especially in HTTP mode.
417 global
418 daemon
419 maxconn 256
420
421 defaults
422 mode http
423 timeout connect 5000ms
424 timeout client 50000ms
425 timeout server 50000ms
426
427 listen http-in
428 bind *:80
429 server server1 127.0.0.1:8000 maxconn 32
430
431
432Assuming haproxy is in $PATH, test these configurations in a shell with:
433
Willy Tarreauccb289d2010-12-11 20:19:38 +0100434 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200435
436
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004373. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200438--------------------
439
440Parameters in the "global" section are process-wide and often OS-specific. They
441are generally set once for all and do not need being changed once correct. Some
442of them have command-line equivalents.
443
444The following keywords are supported in the "global" section :
445
446 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200447 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200448 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200449 - crt-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200450 - daemon
451 - gid
452 - group
453 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100454 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200455 - nbproc
456 - pidfile
457 - uid
458 - ulimit-n
459 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200460 - stats
Emeric Brun850efd52014-01-29 12:24:34 +0100461 - ssl-server-verify
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200462 - node
463 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100464 - unix-bind
Willy Tarreaud72758d2010-01-12 10:42:19 +0100465
Willy Tarreau6a06a402007-07-15 20:15:28 +0200466 * Performance tuning
Willy Tarreau1746eec2014-04-25 10:46:47 +0200467 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200468 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200469 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100470 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100471 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100472 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200473 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200474 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200475 - maxsslrate
Willy Tarreau6a06a402007-07-15 20:15:28 +0200476 - noepoll
477 - nokqueue
478 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100479 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300480 - nogetaddrinfo
Willy Tarreaufe255b72007-10-14 23:09:26 +0200481 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200482 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200483 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100484 - tune.comp.maxlevel
Willy Tarreau193b8c62012-11-22 00:17:38 +0100485 - tune.http.cookielen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200486 - tune.http.maxhdr
Willy Tarreau7e312732014-02-12 16:35:14 +0100487 - tune.idletimer
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100488 - tune.maxaccept
489 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200490 - tune.maxrewrite
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200491 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100492 - tune.rcvbuf.client
493 - tune.rcvbuf.server
494 - tune.sndbuf.client
495 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100496 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100497 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200498 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100499 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200500 - tune.ssl.default-dh-param
William Lallemanda509e4c2012-11-07 16:54:34 +0100501 - tune.zlib.memlevel
502 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100503
Willy Tarreau6a06a402007-07-15 20:15:28 +0200504 * Debugging
505 - debug
506 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200507
508
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005093.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200510------------------------------------
511
Emeric Brunc8e8d122012-10-02 18:42:10 +0200512ca-base <dir>
513 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200514 relative path is used with "ca-file" or "crl-file" directives. Absolute
515 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200516
Willy Tarreau6a06a402007-07-15 20:15:28 +0200517chroot <jail dir>
518 Changes current directory to <jail dir> and performs a chroot() there before
519 dropping privileges. This increases the security level in case an unknown
520 vulnerability would be exploited, since it would make it very hard for the
521 attacker to exploit the system. This only works when the process is started
522 with superuser privileges. It is important to ensure that <jail_dir> is both
523 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100524
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100525cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>...
526 On Linux 2.6 and above, it is possible to bind a process to a specific CPU
527 set. This means that the process will never run on other CPUs. The "cpu-map"
528 directive specifies CPU sets for process sets. The first argument is the
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100529 process number to bind. This process must have a number between 1 and 32 or
530 64, depending on the machine's word size, and any process IDs above nbproc
531 are ignored. It is possible to specify all processes at once using "all",
532 only odd numbers using "odd" or even numbers using "even", just like with the
533 "bind-process" directive. The second and forthcoming arguments are CPU sets.
534 Each CPU set is either a unique number between 0 and 31 or 63 or a range with
535 two such numbers delimited by a dash ('-'). Multiple CPU numbers or ranges
536 may be specified, and the processes will be allowed to bind to all of them.
537 Obviously, multiple "cpu-map" directives may be specified. Each "cpu-map"
538 directive will replace the previous ones when they overlap.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100539
Emeric Brunc8e8d122012-10-02 18:42:10 +0200540crt-base <dir>
541 Assigns a default directory to fetch SSL certificates from when a relative
542 path is used with "crtfile" directives. Absolute locations specified after
543 "crtfile" prevail and ignore "crt-base".
544
Willy Tarreau6a06a402007-07-15 20:15:28 +0200545daemon
546 Makes the process fork into background. This is the recommended mode of
547 operation. It is equivalent to the command line "-D" argument. It can be
548 disabled by the command line "-db" argument.
549
550gid <number>
551 Changes the process' group ID to <number>. It is recommended that the group
552 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
553 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100554 Note that if haproxy is started from a user having supplementary groups, it
555 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200556 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100557
Willy Tarreau6a06a402007-07-15 20:15:28 +0200558group <group name>
559 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
560 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100561
Willy Tarreaudc2695c2014-06-27 18:10:07 +0200562log <address> [len <length>] <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200563 Adds a global syslog server. Up to two global servers can be defined. They
564 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100565 configured with "log global".
566
567 <address> can be one of:
568
Willy Tarreau2769aa02007-12-27 18:26:09 +0100569 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100570 no port is specified, 514 is used by default (the standard syslog
571 port).
572
David du Colombier24bb5f52011-03-17 10:40:23 +0100573 - An IPv6 address followed by a colon and optionally a UDP port. If
574 no port is specified, 514 is used by default (the standard syslog
575 port).
576
Robert Tsai81ae1952007-12-05 10:47:29 +0100577 - A filesystem path to a UNIX domain socket, keeping in mind
578 considerations for chroot (be sure the path is accessible inside
579 the chroot) and uid/gid (be sure the path is appropriately
580 writeable).
581
Willy Tarreaudad36a32013-03-11 01:20:04 +0100582 Any part of the address string may reference any number of environment
583 variables by preceding their name with a dollar sign ('$') and
584 optionally enclosing them with braces ('{}'), similarly to what is done
585 in Bourne shell.
586
Willy Tarreaudc2695c2014-06-27 18:10:07 +0200587 <length> is an optional maximum line length. Log lines larger than this value
588 will be truncated before being sent. The reason is that syslog
589 servers act differently on log line length. All servers support the
590 default value of 1024, but some servers simply drop larger lines
591 while others do log them. If a server supports long lines, it may
592 make sense to set this value here in order to avoid truncating long
593 lines. Similarly, if a server drops long lines, it is preferable to
594 truncate them before sending them. Accepted values are 80 to 65535
595 inclusive. The default value of 1024 is generally fine for all
596 standard usages. Some specific cases of long captures or
597 JSON-formated logs may require larger values.
598
Robert Tsai81ae1952007-12-05 10:47:29 +0100599 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200600
601 kern user mail daemon auth syslog lpr news
602 uucp cron auth2 ftp ntp audit alert cron2
603 local0 local1 local2 local3 local4 local5 local6 local7
604
605 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200606 all messages are sent. If a maximum level is specified, only messages with a
607 severity at least as important as this level will be sent. An optional minimum
608 level can be specified. If it is set, logs emitted with a more severe level
609 than this one will be capped to this level. This is used to avoid sending
610 "emerg" messages on all terminals on some default syslog configurations.
611 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200612
Cyril Bontédc4d9032012-04-08 21:57:39 +0200613 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200614
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100615log-send-hostname [<string>]
616 Sets the hostname field in the syslog header. If optional "string" parameter
617 is set the header is set to the string contents, otherwise uses the hostname
618 of the system. Generally used if one is not relaying logs through an
619 intermediate syslog server or for simply customizing the hostname printed in
620 the logs.
621
Kevinm48936af2010-12-22 16:08:21 +0000622log-tag <string>
623 Sets the tag field in the syslog header to this string. It defaults to the
624 program name as launched from the command line, which usually is "haproxy".
625 Sometimes it can be useful to differentiate between multiple processes
626 running on the same host.
627
Willy Tarreau6a06a402007-07-15 20:15:28 +0200628nbproc <number>
629 Creates <number> processes when going daemon. This requires the "daemon"
630 mode. By default, only one process is created, which is the recommended mode
631 of operation. For systems limited to small sets of file descriptors per
632 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
633 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
634
635pidfile <pidfile>
636 Writes pids of all daemons into file <pidfile>. This option is equivalent to
637 the "-p" command line argument. The file must be accessible to the user
638 starting the process. See also "daemon".
639
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100640stats bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200641 Limits the stats socket to a certain set of processes numbers. By default the
642 stats socket is bound to all processes, causing a warning to be emitted when
643 nbproc is greater than 1 because there is no way to select the target process
644 when connecting. However, by using this setting, it becomes possible to pin
645 the stats socket to a specific set of processes, typically the first one. The
646 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100647 the number of processes used. The maximum process ID depends on the machine's
Willy Tarreauae302532014-05-07 19:22:24 +0200648 word size (32 or 64). A better option consists in using the "process" setting
649 of the "stats socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +0200650
Willy Tarreau610f04b2014-02-13 11:36:41 +0100651ssl-default-bind-ciphers <ciphers>
652 This setting is only available when support for OpenSSL was built in. It sets
653 the default string describing the list of cipher algorithms ("cipher suite")
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300654 that are negotiated during the SSL/TLS handshake for all "bind" lines which
Willy Tarreau610f04b2014-02-13 11:36:41 +0100655 do not explicitly define theirs. The format of the string is defined in
656 "man 1 ciphers" from OpenSSL man pages, and can be for instance a string such
657 as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). Please check the
658 "bind" keyword for more information.
659
Emeric Brun42a3e202014-10-30 15:56:50 +0100660ssl-default-bind-options [<option>]...
661 This setting is only available when support for OpenSSL was built in. It sets
662 default ssl-options to force on all "bind" lines. Please check the "bind"
663 keyword to see available options.
664
665 Example:
666 global
667 ssl-default-bind-options no-sslv3 no-tls-tickets
668
Willy Tarreau610f04b2014-02-13 11:36:41 +0100669ssl-default-server-ciphers <ciphers>
670 This setting is only available when support for OpenSSL was built in. It
671 sets the default string describing the list of cipher algorithms that are
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300672 negotiated during the SSL/TLS handshake with the server, for all "server"
Willy Tarreau610f04b2014-02-13 11:36:41 +0100673 lines which do not explicitly define theirs. The format of the string is
674 defined in "man 1 ciphers". Please check the "server" keyword for more
675 information.
676
Emeric Brun42a3e202014-10-30 15:56:50 +0100677ssl-default-server-options [<option>]...
678 This setting is only available when support for OpenSSL was built in. It sets
679 default ssl-options to force on all "server" lines. Please check the "server"
680 keyword to see available options.
681
Emeric Brun850efd52014-01-29 12:24:34 +0100682ssl-server-verify [none|required]
683 The default behavior for SSL verify on servers side. If specified to 'none',
684 servers certificates are not verified. The default is 'required' except if
685 forced using cmdline option '-dV'.
686
Willy Tarreauabb175f2012-09-24 12:43:26 +0200687stats socket [<address:port>|<path>] [param*]
688 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
689 Connections to this socket will return various statistics outputs and even
690 allow some commands to be issued to change some runtime settings. Please
691 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200692
Willy Tarreauabb175f2012-09-24 12:43:26 +0200693 All parameters supported by "bind" lines are supported, for instance to
694 restrict access to some users or their access rights. Please consult
695 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200696
697stats timeout <timeout, in milliseconds>
698 The default timeout on the stats socket is set to 10 seconds. It is possible
699 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100700 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200701
702stats maxconn <connections>
703 By default, the stats socket is limited to 10 concurrent connections. It is
704 possible to change this value with "stats maxconn".
705
Willy Tarreau6a06a402007-07-15 20:15:28 +0200706uid <number>
707 Changes the process' user ID to <number>. It is recommended that the user ID
708 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
709 be started with superuser privileges in order to be able to switch to another
710 one. See also "gid" and "user".
711
712ulimit-n <number>
713 Sets the maximum number of per-process file-descriptors to <number>. By
714 default, it is automatically computed, so it is recommended not to use this
715 option.
716
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100717unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
718 [ group <group> ] [ gid <gid> ]
719
720 Fixes common settings to UNIX listening sockets declared in "bind" statements.
721 This is mainly used to simplify declaration of those UNIX sockets and reduce
722 the risk of errors, since those settings are most commonly required but are
723 also process-specific. The <prefix> setting can be used to force all socket
724 path to be relative to that directory. This might be needed to access another
725 component's chroot. Note that those paths are resolved before haproxy chroots
726 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
727 all have the same meaning as their homonyms used by the "bind" statement. If
728 both are specified, the "bind" statement has priority, meaning that the
729 "unix-bind" settings may be seen as process-wide default settings.
730
Willy Tarreau6a06a402007-07-15 20:15:28 +0200731user <user name>
732 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
733 See also "uid" and "group".
734
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200735node <name>
736 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
737
738 This statement is useful in HA configurations where two or more processes or
739 servers share the same IP address. By setting a different node-name on all
740 nodes, it becomes easy to immediately spot what server is handling the
741 traffic.
742
743description <text>
744 Add a text that describes the instance.
745
746 Please note that it is required to escape certain characters (# for example)
747 and this text is inserted into a html page so you should avoid using
748 "<" and ">" characters.
749
Willy Tarreau6a06a402007-07-15 20:15:28 +0200750
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007513.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200752-----------------------
753
Willy Tarreau1746eec2014-04-25 10:46:47 +0200754max-spread-checks <delay in milliseconds>
755 By default, haproxy tries to spread the start of health checks across the
756 smallest health check interval of all the servers in a farm. The principle is
757 to avoid hammering services running on the same server. But when using large
758 check intervals (10 seconds or more), the last servers in the farm take some
759 time before starting to be tested, which can be a problem. This parameter is
760 used to enforce an upper bound on delay between the first and the last check,
761 even if the servers' check intervals are larger. When servers run with
762 shorter intervals, their intervals will be respected though.
763
Willy Tarreau6a06a402007-07-15 20:15:28 +0200764maxconn <number>
765 Sets the maximum per-process number of concurrent connections to <number>. It
766 is equivalent to the command-line argument "-n". Proxies will stop accepting
767 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +0200768 automatically adjusted according to this value. See also "ulimit-n". Note:
769 the "select" poller cannot reliably use more than 1024 file descriptors on
770 some platforms. If your platform only supports select and reports "select
771 FAILED" on startup, you need to reduce maxconn until it works (slightly
772 below 500 in general).
Willy Tarreau6a06a402007-07-15 20:15:28 +0200773
Willy Tarreau81c25d02011-09-07 15:17:21 +0200774maxconnrate <number>
775 Sets the maximum per-process number of connections per second to <number>.
776 Proxies will stop accepting connections when this limit is reached. It can be
777 used to limit the global capacity regardless of each frontend capacity. It is
778 important to note that this can only be used as a service protection measure,
779 as there will not necessarily be a fair share between frontends when the
780 limit is reached, so it's a good idea to also limit each frontend to some
781 value close to its expected share. Also, lowering tune.maxaccept can improve
782 fairness.
783
William Lallemandd85f9172012-11-09 17:05:39 +0100784maxcomprate <number>
785 Sets the maximum per-process input compression rate to <number> kilobytes
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300786 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +0100787 level will be decreased during the session. If the maximum is reached at the
788 beginning of a session, the session will not compress at all. If the maximum
789 is not reached, the compression level will be increased up to
790 tune.comp.maxlevel. A value of zero means there is no limit, this is the
791 default value.
792
William Lallemand072a2bf2012-11-20 17:01:01 +0100793maxcompcpuusage <number>
794 Sets the maximum CPU usage HAProxy can reach before stopping the compression
795 for new requests or decreasing the compression level of current requests.
796 It works like 'maxcomprate' but measures CPU usage instead of incoming data
797 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
798 case of multiple processes (nbproc > 1), each process manages its individual
799 usage. A value of 100 disable the limit. The default value is 100. Setting
800 a lower value will prevent the compression work from slowing the whole
801 process down and from introducing high latencies.
802
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100803maxpipes <number>
804 Sets the maximum per-process number of pipes to <number>. Currently, pipes
805 are only used by kernel-based tcp splicing. Since a pipe contains two file
806 descriptors, the "ulimit-n" value will be increased accordingly. The default
807 value is maxconn/4, which seems to be more than enough for most heavy usages.
808 The splice code dynamically allocates and releases pipes, and can fall back
809 to standard copy, so setting this value too low may only impact performance.
810
Willy Tarreau93e7c002013-10-07 18:51:07 +0200811maxsessrate <number>
812 Sets the maximum per-process number of sessions per second to <number>.
813 Proxies will stop accepting connections when this limit is reached. It can be
814 used to limit the global capacity regardless of each frontend capacity. It is
815 important to note that this can only be used as a service protection measure,
816 as there will not necessarily be a fair share between frontends when the
817 limit is reached, so it's a good idea to also limit each frontend to some
818 value close to its expected share. Also, lowering tune.maxaccept can improve
819 fairness.
820
Willy Tarreau403edff2012-09-06 11:58:37 +0200821maxsslconn <number>
822 Sets the maximum per-process number of concurrent SSL connections to
823 <number>. By default there is no SSL-specific limit, which means that the
824 global maxconn setting will apply to all connections. Setting this limit
825 avoids having openssl use too much memory and crash when malloc returns NULL
826 (since it unfortunately does not reliably check for such conditions). Note
827 that the limit applies both to incoming and outgoing connections, so one
828 connection which is deciphered then ciphered accounts for 2 SSL connections.
829
Willy Tarreaue43d5322013-10-07 20:01:52 +0200830maxsslrate <number>
831 Sets the maximum per-process number of SSL sessions per second to <number>.
832 SSL listeners will stop accepting connections when this limit is reached. It
833 can be used to limit the global SSL CPU usage regardless of each frontend
834 capacity. It is important to note that this can only be used as a service
835 protection measure, as there will not necessarily be a fair share between
836 frontends when the limit is reached, so it's a good idea to also limit each
837 frontend to some value close to its expected share. It is also important to
838 note that the sessions are accounted before they enter the SSL stack and not
839 after, which also protects the stack against bad handshakes. Also, lowering
840 tune.maxaccept can improve fairness.
841
William Lallemand9d5f5482012-11-07 16:12:57 +0100842maxzlibmem <number>
843 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
844 When the maximum amount is reached, future sessions will not compress as long
845 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +0100846 The default value is 0. The value is available in bytes on the UNIX socket
847 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
848 "ZlibMemUsage" in bytes.
849
Willy Tarreau6a06a402007-07-15 20:15:28 +0200850noepoll
851 Disables the use of the "epoll" event polling system on Linux. It is
852 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100853 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200854
855nokqueue
856 Disables the use of the "kqueue" event polling system on BSD. It is
857 equivalent to the command-line argument "-dk". The next polling system
858 used will generally be "poll". See also "nopoll".
859
860nopoll
861 Disables the use of the "poll" event polling system. It is equivalent to the
862 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100863 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100864 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200865
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100866nosplice
867 Disables the use of kernel tcp splicing between sockets on Linux. It is
868 equivalent to the command line argument "-dS". Data will then be copied
869 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100870 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100871 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
872 be used. This option makes it easier to globally disable kernel splicing in
873 case of doubt. See also "option splice-auto", "option splice-request" and
874 "option splice-response".
875
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300876nogetaddrinfo
877 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
878 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
879
Willy Tarreaufe255b72007-10-14 23:09:26 +0200880spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +0900881 Sometimes it is desirable to avoid sending agent and health checks to
882 servers at exact intervals, for instance when many logical servers are
883 located on the same physical server. With the help of this parameter, it
884 becomes possible to add some randomness in the check interval between 0
885 and +/- 50%. A value between 2 and 5 seems to show good results. The
886 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +0200887
Willy Tarreau27a674e2009-08-17 07:23:33 +0200888tune.bufsize <number>
889 Sets the buffer size to this size (in bytes). Lower values allow more
890 sessions to coexist in the same amount of RAM, and higher values allow some
891 applications with very large cookies to work. The default value is 16384 and
892 can be changed at build time. It is strongly recommended not to change this
893 from the default value, as very low values will break some services such as
894 statistics, and values larger than default size will increase memory usage,
895 possibly causing the system to run out of memory. At least the global maxconn
896 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +0400897 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
898 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
899 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +0200900
Willy Tarreau43961d52010-10-04 20:39:20 +0200901tune.chksize <number>
902 Sets the check buffer size to this size (in bytes). Higher values may help
903 find string or regex patterns in very large pages, though doing so may imply
904 more memory and CPU usage. The default value is 16384 and can be changed at
905 build time. It is not recommended to change this value, but to use better
906 checks whenever possible.
907
William Lallemandf3747832012-11-09 12:33:10 +0100908tune.comp.maxlevel <number>
909 Sets the maximum compression level. The compression level affects CPU
910 usage during compression. This value affects CPU usage during compression.
911 Each session using compression initializes the compression algorithm with
912 this value. The default value is 1.
913
Willy Tarreau193b8c62012-11-22 00:17:38 +0100914tune.http.cookielen <number>
915 Sets the maximum length of captured cookies. This is the maximum value that
916 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
917 will automatically be truncated to this one. It is important not to set too
918 high a value because all cookie captures still allocate this size whatever
919 their configured value (they share a same pool). This value is per request
920 per response, so the memory allocated is twice this value per connection.
921 When not specified, the limit is set to 63 characters. It is recommended not
922 to change this value.
923
Willy Tarreauac1932d2011-10-24 19:14:41 +0200924tune.http.maxhdr <number>
925 Sets the maximum number of headers in a request. When a request comes with a
926 number of headers greater than this value (including the first line), it is
927 rejected with a "400 Bad Request" status code. Similarly, too large responses
928 are blocked with "502 Bad Gateway". The default value is 101, which is enough
929 for all usages, considering that the widely deployed Apache server uses the
930 same limit. It can be useful to push this limit further to temporarily allow
931 a buggy application to work by the time it gets fixed. Keep in mind that each
932 new header consumes 32bits of memory for each session, so don't push this
933 limit too high.
934
Willy Tarreau7e312732014-02-12 16:35:14 +0100935tune.idletimer <timeout>
936 Sets the duration after which haproxy will consider that an empty buffer is
937 probably associated with an idle stream. This is used to optimally adjust
938 some packet sizes while forwarding large and small data alternatively. The
939 decision to use splice() or to send large buffers in SSL is modulated by this
940 parameter. The value is in milliseconds between 0 and 65535. A value of zero
941 means that haproxy will not try to detect idle streams. The default is 1000,
942 which seems to correctly detect end user pauses (eg: read a page before
943 clicking). There should be not reason for changing this value. Please check
944 tune.ssl.maxrecord below.
945
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100946tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +0100947 Sets the maximum number of consecutive connections a process may accept in a
948 row before switching to other work. In single process mode, higher numbers
949 give better performance at high connection rates. However in multi-process
950 modes, keeping a bit of fairness between processes generally is better to
951 increase performance. This value applies individually to each listener, so
952 that the number of processes a listener is bound to is taken into account.
953 This value defaults to 64. In multi-process mode, it is divided by twice
954 the number of processes the listener is bound to. Setting this value to -1
955 completely disables the limitation. It should normally not be needed to tweak
956 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100957
958tune.maxpollevents <number>
959 Sets the maximum amount of events that can be processed at once in a call to
960 the polling system. The default value is adapted to the operating system. It
961 has been noticed that reducing it below 200 tends to slightly decrease
962 latency at the expense of network bandwidth, and increasing it above 200
963 tends to trade latency for slightly increased bandwidth.
964
Willy Tarreau27a674e2009-08-17 07:23:33 +0200965tune.maxrewrite <number>
966 Sets the reserved buffer space to this size in bytes. The reserved space is
967 used for header rewriting or appending. The first reads on sockets will never
968 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
969 bufsize, though that does not make much sense since there are rarely large
970 numbers of headers to add. Setting it too high prevents processing of large
971 requests or responses. Setting it too low prevents addition of new headers
972 to already large requests or to POST requests. It is generally wise to set it
973 to about 1024. It is automatically readjusted to half of bufsize if it is
974 larger than that. This means you don't have to worry about it when changing
975 bufsize.
976
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200977tune.pipesize <number>
978 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
979 are the default size for the system. But sometimes when using TCP splicing,
980 it can improve performance to increase pipe sizes, especially if it is
981 suspected that pipes are not filled and that many calls to splice() are
982 performed. This has an impact on the kernel's memory footprint, so this must
983 not be changed if impacts are not understood.
984
Willy Tarreaue803de22010-01-21 17:43:04 +0100985tune.rcvbuf.client <number>
986tune.rcvbuf.server <number>
987 Forces the kernel socket receive buffer size on the client or the server side
988 to the specified value in bytes. This value applies to all TCP/HTTP frontends
989 and backends. It should normally never be set, and the default size (0) lets
990 the kernel autotune this value depending on the amount of available memory.
991 However it can sometimes help to set it to very low values (eg: 4096) in
992 order to save kernel memory by preventing it from buffering too large amounts
993 of received data. Lower values will significantly increase CPU usage though.
994
995tune.sndbuf.client <number>
996tune.sndbuf.server <number>
997 Forces the kernel socket send buffer size on the client or the server side to
998 the specified value in bytes. This value applies to all TCP/HTTP frontends
999 and backends. It should normally never be set, and the default size (0) lets
1000 the kernel autotune this value depending on the amount of available memory.
1001 However it can sometimes help to set it to very low values (eg: 4096) in
1002 order to save kernel memory by preventing it from buffering too large amounts
1003 of received data. Lower values will significantly increase CPU usage though.
1004 Another use case is to prevent write timeouts with extremely slow clients due
1005 to the kernel waiting for a large part of the buffer to be read before
1006 notifying haproxy again.
1007
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001008tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01001009 Sets the size of the global SSL session cache, in a number of blocks. A block
1010 is large enough to contain an encoded session without peer certificate.
1011 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001012 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01001013 200 bytes of memory. The default value may be forced at build time, otherwise
1014 defaults to 20000. When the cache is full, the most idle entries are purged
1015 and reassigned. Higher values reduce the occurrence of such a purge, hence
1016 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1017 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001018 and are shared between all processes if "nbproc" is greater than 1. Setting
1019 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001020
Emeric Brun8dc60392014-05-09 13:52:00 +02001021tune.ssl.force-private-cache
1022 This boolean disables SSL session cache sharing between all processes. It
1023 should normally not be used since it will force many renegotiations due to
1024 clients hitting a random process. But it may be required on some operating
1025 systems where none of the SSL cache synchronization method may be used. In
1026 this case, adding a first layer of hash-based load balancing before the SSL
1027 layer might limit the impact of the lack of session sharing.
1028
Emeric Brun4f65bff2012-11-16 15:11:00 +01001029tune.ssl.lifetime <timeout>
1030 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001031 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001032 does not guarantee that sessions will last that long, because if the cache is
1033 full, the longest idle sessions will be purged despite their configured
1034 lifetime. The real usefulness of this setting is to prevent sessions from
1035 being used for too long.
1036
Willy Tarreaubfd59462013-02-21 07:46:09 +01001037tune.ssl.maxrecord <number>
1038 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
1039 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
1040 data only once it has received a full record. With large records, it means
1041 that clients might have to download up to 16kB of data before starting to
1042 process them. Limiting the value can improve page load times on browsers
1043 located over high latency or low bandwidth networks. It is suggested to find
1044 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
1045 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
1046 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
1047 2859 gave good results during tests. Use "strace -e trace=write" to find the
Willy Tarreau7e312732014-02-12 16:35:14 +01001048 best value. Haproxy will automatically switch to this setting after an idle
1049 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01001050
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001051tune.ssl.default-dh-param <number>
1052 Sets the maximum size of the Diffie-Hellman parameters used for generating
1053 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
1054 final size will try to match the size of the server's RSA (or DSA) key (e.g,
1055 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
1056 this maximum value. Default value if 1024. Only 1024 or higher values are
1057 allowed. Higher values will increase the CPU load, and values greater than
1058 1024 bits are not supported by Java 7 and earlier clients. This value is not
1059 used if static Diffie-Hellman parameters are supplied via the certificate file.
1060
William Lallemanda509e4c2012-11-07 16:54:34 +01001061tune.zlib.memlevel <number>
1062 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001063 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01001064 state. A value of 1 uses minimum memory but is slow and reduces compression
1065 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
1066 between 1 and 9. The default value is 8.
1067
1068tune.zlib.windowsize <number>
1069 Sets the window size (the size of the history buffer) as a parameter of the
1070 zlib initialization for each session. Larger values of this parameter result
1071 in better compression at the expense of memory usage. Can be a value between
1072 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001073
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010743.3. Debugging
1075--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02001076
1077debug
1078 Enables debug mode which dumps to stdout all exchanges, and disables forking
1079 into background. It is the equivalent of the command-line argument "-d". It
1080 should never be used in a production configuration since it may prevent full
1081 system startup.
1082
1083quiet
1084 Do not display any message during startup. It is equivalent to the command-
1085 line argument "-q".
1086
Emeric Brunf099e792010-09-27 12:05:28 +02001087
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010010883.4. Userlists
1089--------------
1090It is possible to control access to frontend/backend/listen sections or to
1091http stats by allowing only authenticated and authorized users. To do this,
1092it is required to create at least one userlist and to define users.
1093
1094userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01001095 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001096 used to store authentication & authorization data for independent customers.
1097
1098group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01001099 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001100 attach users to this group by using a comma separated list of names
1101 proceeded by "users" keyword.
1102
Cyril Bontéf0c60612010-02-06 14:44:47 +01001103user <username> [password|insecure-password <password>]
1104 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001105 Adds user <username> to the current userlist. Both secure (encrypted) and
1106 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +01001107 evaluated using the crypt(3) function so depending of the system's
1108 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001109 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001110 DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001111
1112
1113 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01001114 userlist L1
1115 group G1 users tiger,scott
1116 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001117
Cyril Bontéf0c60612010-02-06 14:44:47 +01001118 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
1119 user scott insecure-password elgato
1120 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001121
Cyril Bontéf0c60612010-02-06 14:44:47 +01001122 userlist L2
1123 group G1
1124 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001125
Cyril Bontéf0c60612010-02-06 14:44:47 +01001126 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
1127 user scott insecure-password elgato groups G1,G2
1128 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001129
1130 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001131
Emeric Brunf099e792010-09-27 12:05:28 +02001132
11333.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02001134----------
Emeric Brunf099e792010-09-27 12:05:28 +02001135It is possible to synchronize server entries in stick tables between several
1136haproxy instances over TCP connections in a multi-master fashion. Each instance
1137pushes its local updates and insertions to remote peers. Server IDs are used to
1138identify servers remotely, so it is important that configurations look similar
1139or at least that the same IDs are forced on each server on all participants.
1140Interrupted exchanges are automatically detected and recovered from the last
1141known point. In addition, during a soft restart, the old process connects to
1142the new one using such a TCP connection to push all its entries before the new
1143process tries to connect to other peers. That ensures very fast replication
1144during a reload, it typically takes a fraction of a second even for large
1145tables.
1146
1147peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001148 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001149 which is referenced by one or more stick-tables.
1150
1151peer <peername> <ip>:<port>
1152 Defines a peer inside a peers section.
1153 If <peername> is set to the local peer name (by default hostname, or forced
1154 using "-L" command line option), haproxy will listen for incoming remote peer
1155 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1156 to join the remote peer, and <peername> is used at the protocol level to
1157 identify and validate the remote peer on the server side.
1158
1159 During a soft restart, local peer <ip>:<port> is used by the old instance to
1160 connect the new one and initiate a complete replication (teaching process).
1161
1162 It is strongly recommended to have the exact same peers declaration on all
1163 peers and to only rely on the "-L" command line argument to change the local
1164 peer name. This makes it easier to maintain coherent configuration files
1165 across all peers.
1166
Willy Tarreaudad36a32013-03-11 01:20:04 +01001167 Any part of the address string may reference any number of environment
1168 variables by preceding their name with a dollar sign ('$') and optionally
1169 enclosing them with braces ('{}'), similarly to what is done in Bourne shell.
1170
Cyril Bontédc4d9032012-04-08 21:57:39 +02001171 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001172 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001173 peer haproxy1 192.168.0.1:1024
1174 peer haproxy2 192.168.0.2:1024
1175 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001176
1177 backend mybackend
1178 mode tcp
1179 balance roundrobin
1180 stick-table type ip size 20k peers mypeers
1181 stick on src
1182
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001183 server srv1 192.168.0.30:80
1184 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001185
1186
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011874. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001188----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001189
Willy Tarreau6a06a402007-07-15 20:15:28 +02001190Proxy configuration can be located in a set of sections :
1191 - defaults <name>
1192 - frontend <name>
1193 - backend <name>
1194 - listen <name>
1195
1196A "defaults" section sets default parameters for all other sections following
1197its declaration. Those default parameters are reset by the next "defaults"
1198section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001199section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001200
1201A "frontend" section describes a set of listening sockets accepting client
1202connections.
1203
1204A "backend" section describes a set of servers to which the proxy will connect
1205to forward incoming connections.
1206
1207A "listen" section defines a complete proxy with its frontend and backend
1208parts combined in one section. It is generally useful for TCP-only traffic.
1209
Willy Tarreau0ba27502007-12-24 16:55:16 +01001210All proxy names must be formed from upper and lower case letters, digits,
1211'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1212case-sensitive, which means that "www" and "WWW" are two different proxies.
1213
1214Historically, all proxy names could overlap, it just caused troubles in the
1215logs. Since the introduction of content switching, it is mandatory that two
1216proxies with overlapping capabilities (frontend/backend) have different names.
1217However, it is still permitted that a frontend and a backend share the same
1218name, as this configuration seems to be commonly encountered.
1219
1220Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1221and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001222bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001223protocol, and can interact with it by allowing, blocking, switching, adding,
1224modifying, or removing arbitrary contents in requests or responses, based on
1225arbitrary criteria.
1226
Willy Tarreau70dffda2014-01-30 03:07:23 +01001227In HTTP mode, the processing applied to requests and responses flowing over
1228a connection depends in the combination of the frontend's HTTP options and
1229the backend's. HAProxy supports 5 connection modes :
1230
1231 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
1232 requests and responses are processed, and connections remain open but idle
1233 between responses and new requests.
1234
1235 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
1236 1.0 to 1.5-dev21 : only the first request and response are processed, and
1237 everything else is forwarded with no analysis at all. This mode should not
1238 be used as it creates lots of trouble with logging and HTTP processing.
1239
1240 - PCL: passive close ("option httpclose") : exactly the same as tunnel mode,
1241 but with "Connection: close" appended in both directions to try to make
1242 both ends close after the first request/response exchange.
1243
1244 - SCL: server close ("option http-server-close") : the server-facing
1245 connection is closed after the end of the response is received, but the
1246 client-facing connection remains open.
1247
1248 - FCL: forced close ("option forceclose") : the connection is actively closed
1249 after the end of the response.
1250
1251The effective mode that will be applied to a connection passing through a
1252frontend and a backend can be determined by both proxy modes according to the
1253following matrix, but in short, the modes are symmetric, keep-alive is the
1254weakest option and force close is the strongest.
1255
1256 Backend mode
1257
1258 | KAL | TUN | PCL | SCL | FCL
1259 ----+-----+-----+-----+-----+----
1260 KAL | KAL | TUN | PCL | SCL | FCL
1261 ----+-----+-----+-----+-----+----
1262 TUN | TUN | TUN | PCL | SCL | FCL
1263 Frontend ----+-----+-----+-----+-----+----
1264 mode PCL | PCL | PCL | PCL | FCL | FCL
1265 ----+-----+-----+-----+-----+----
1266 SCL | SCL | SCL | FCL | SCL | FCL
1267 ----+-----+-----+-----+-----+----
1268 FCL | FCL | FCL | FCL | FCL | FCL
1269
Willy Tarreau0ba27502007-12-24 16:55:16 +01001270
Willy Tarreau70dffda2014-01-30 03:07:23 +01001271
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012724.1. Proxy keywords matrix
1273--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001274
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001275The following list of keywords is supported. Most of them may only be used in a
1276limited set of section types. Some of them are marked as "deprecated" because
1277they are inherited from an old syntax which may be confusing or functionally
1278limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001279marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001280option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001281and must be disabled for a specific instance. Such options may also be prefixed
1282with "default" in order to restore default settings regardless of what has been
1283specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001284
Willy Tarreau6a06a402007-07-15 20:15:28 +02001285
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001286 keyword defaults frontend listen backend
1287------------------------------------+----------+----------+---------+---------
1288acl - X X X
1289appsession - - X X
1290backlog X X X -
1291balance X - X X
1292bind - X X -
1293bind-process X X X X
1294block - X X X
1295capture cookie - X X -
1296capture request header - X X -
1297capture response header - X X -
1298clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001299compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001300contimeout (deprecated) X - X X
1301cookie X - X X
1302default-server X - X X
1303default_backend X X X -
1304description - X X X
1305disabled X X X X
1306dispatch - - X X
1307enabled X X X X
1308errorfile X X X X
1309errorloc X X X X
1310errorloc302 X X X X
1311-- keyword -------------------------- defaults - frontend - listen -- backend -
1312errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001313force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001314fullconn X - X X
1315grace X X X X
1316hash-type X - X X
1317http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001318http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001319http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001320http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02001321http-response - X X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02001322http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001323id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001324ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001325log (*) X X X X
Willy Tarreau14104732015-01-07 14:55:17 +01001326log-format X X X -
Willy Tarreauc35362a2014-04-25 13:58:37 +02001327max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001328maxconn X X X -
1329mode X X X X
1330monitor fail - X X -
1331monitor-net X X X -
1332monitor-uri X X X -
1333option abortonclose (*) X - X X
1334option accept-invalid-http-request (*) X X X -
1335option accept-invalid-http-response (*) X - X X
1336option allbackups (*) X - X X
1337option checkcache (*) X - X X
1338option clitcpka (*) X X X -
1339option contstats (*) X X X -
1340option dontlog-normal (*) X X X -
1341option dontlognull (*) X X X -
1342option forceclose (*) X X X X
1343-- keyword -------------------------- defaults - frontend - listen -- backend -
1344option forwardfor X X X X
Willy Tarreau16bfb022010-01-16 19:48:41 +01001345option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001346option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001347option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001348option http-server-close (*) X X X X
Willy Tarreau02bce8b2014-01-30 00:15:28 +01001349option http-tunnel (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001350option http-use-proxy-header (*) X X X -
1351option httpchk X - X X
1352option httpclose (*) X X X X
1353option httplog X X X X
1354option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001355option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001356option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001357option log-health-checks (*) X - X X
1358option log-separate-errors (*) X X X -
1359option logasap (*) X X X -
1360option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001361option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001362option nolinger (*) X X X X
1363option originalto X X X X
1364option persist (*) X - X X
1365option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001366option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001367option smtpchk X - X X
1368option socket-stats (*) X X X -
1369option splice-auto (*) X X X X
1370option splice-request (*) X X X X
1371option splice-response (*) X X X X
1372option srvtcpka (*) X - X X
1373option ssl-hello-chk X - X X
1374-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01001375option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001376option tcp-smart-accept (*) X X X -
1377option tcp-smart-connect (*) X - X X
1378option tcpka X X X X
1379option tcplog X X X X
1380option transparent (*) X - X X
1381persist rdp-cookie X - X X
1382rate-limit sessions X X X -
1383redirect - X X X
1384redisp (deprecated) X - X X
1385redispatch (deprecated) X - X X
1386reqadd - X X X
1387reqallow - X X X
1388reqdel - X X X
1389reqdeny - X X X
1390reqiallow - X X X
1391reqidel - X X X
1392reqideny - X X X
1393reqipass - X X X
1394reqirep - X X X
1395reqisetbe - X X X
1396reqitarpit - X X X
1397reqpass - X X X
1398reqrep - X X X
1399-- keyword -------------------------- defaults - frontend - listen -- backend -
1400reqsetbe - X X X
1401reqtarpit - X X X
1402retries X - X X
1403rspadd - X X X
1404rspdel - X X X
1405rspdeny - X X X
1406rspidel - X X X
1407rspideny - X X X
1408rspirep - X X X
1409rsprep - X X X
1410server - - X X
1411source X - X X
1412srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001413stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001414stats auth X - X X
1415stats enable X - X X
1416stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001417stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001418stats realm X - X X
1419stats refresh X - X X
1420stats scope X - X X
1421stats show-desc X - X X
1422stats show-legends X - X X
1423stats show-node X - X X
1424stats uri X - X X
1425-- keyword -------------------------- defaults - frontend - listen -- backend -
1426stick match - - X X
1427stick on - - X X
1428stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001429stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001430stick-table - - X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02001431tcp-check connect - - X X
1432tcp-check expect - - X X
1433tcp-check send - - X X
1434tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001435tcp-request connection - X X -
1436tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001437tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001438tcp-response content - - X X
1439tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001440timeout check X - X X
1441timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02001442timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001443timeout clitimeout (deprecated) X X X -
1444timeout connect X - X X
1445timeout contimeout (deprecated) X - X X
1446timeout http-keep-alive X X X X
1447timeout http-request X X X X
1448timeout queue X - X X
1449timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02001450timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001451timeout srvtimeout (deprecated) X - X X
1452timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001453timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001454transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001455unique-id-format X X X -
1456unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001457use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001458use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001459------------------------------------+----------+----------+---------+---------
1460 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001461
Willy Tarreau0ba27502007-12-24 16:55:16 +01001462
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014634.2. Alphabetically sorted keywords reference
1464---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001465
1466This section provides a description of each keyword and its usage.
1467
1468
1469acl <aclname> <criterion> [flags] [operator] <value> ...
1470 Declare or complete an access list.
1471 May be used in sections : defaults | frontend | listen | backend
1472 no | yes | yes | yes
1473 Example:
1474 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1475 acl invalid_src src_port 0:1023
1476 acl local_dst hdr(host) -i localhost
1477
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001478 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001479
1480
Cyril Bontéb21570a2009-11-29 20:04:48 +01001481appsession <cookie> len <length> timeout <holdtime>
1482 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001483 Define session stickiness on an existing application cookie.
1484 May be used in sections : defaults | frontend | listen | backend
1485 no | no | yes | yes
1486 Arguments :
1487 <cookie> this is the name of the cookie used by the application and which
1488 HAProxy will have to learn for each new session.
1489
Cyril Bontéb21570a2009-11-29 20:04:48 +01001490 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001491 checked in each cookie value.
1492
1493 <holdtime> this is the time after which the cookie will be removed from
1494 memory if unused. If no unit is specified, this time is in
1495 milliseconds.
1496
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001497 request-learn
1498 If this option is specified, then haproxy will be able to learn
1499 the cookie found in the request in case the server does not
1500 specify any in response. This is typically what happens with
1501 PHPSESSID cookies, or when haproxy's session expires before
1502 the application's session and the correct server is selected.
1503 It is recommended to specify this option to improve reliability.
1504
Cyril Bontéb21570a2009-11-29 20:04:48 +01001505 prefix When this option is specified, haproxy will match on the cookie
1506 prefix (or URL parameter prefix). The appsession value is the
1507 data following this prefix.
1508
1509 Example :
1510 appsession ASPSESSIONID len 64 timeout 3h prefix
1511
1512 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1513 the appsession value will be XXXX=XXXXX.
1514
1515 mode This option allows to change the URL parser mode.
1516 2 modes are currently supported :
1517 - path-parameters :
1518 The parser looks for the appsession in the path parameters
1519 part (each parameter is separated by a semi-colon), which is
1520 convenient for JSESSIONID for example.
1521 This is the default mode if the option is not set.
1522 - query-string :
1523 In this mode, the parser will look for the appsession in the
1524 query string.
1525
Willy Tarreau0ba27502007-12-24 16:55:16 +01001526 When an application cookie is defined in a backend, HAProxy will check when
1527 the server sets such a cookie, and will store its value in a table, and
1528 associate it with the server's identifier. Up to <length> characters from
1529 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001530 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1531 the mode used). If a known value is found, the client will be directed to the
1532 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001533 applied. Cookies are automatically removed from memory when they have been
1534 unused for a duration longer than <holdtime>.
1535
1536 The definition of an application cookie is limited to one per backend.
1537
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001538 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1539 unless you know what you do : memory is not shared between the
1540 processes, which can result in random behaviours.
1541
Willy Tarreau0ba27502007-12-24 16:55:16 +01001542 Example :
1543 appsession JSESSIONID len 52 timeout 3h
1544
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001545 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1546 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001547
1548
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001549backlog <conns>
1550 Give hints to the system about the approximate listen backlog desired size
1551 May be used in sections : defaults | frontend | listen | backend
1552 yes | yes | yes | no
1553 Arguments :
1554 <conns> is the number of pending connections. Depending on the operating
1555 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001556 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001557
1558 In order to protect against SYN flood attacks, one solution is to increase
1559 the system's SYN backlog size. Depending on the system, sometimes it is just
1560 tunable via a system parameter, sometimes it is not adjustable at all, and
1561 sometimes the system relies on hints given by the application at the time of
1562 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1563 to the listen() syscall. On systems which can make use of this value, it can
1564 sometimes be useful to be able to specify a different value, hence this
1565 backlog parameter.
1566
1567 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1568 used as a hint and the system accepts up to the smallest greater power of
1569 two, and never more than some limits (usually 32768).
1570
1571 See also : "maxconn" and the target operating system's tuning guide.
1572
1573
Willy Tarreau0ba27502007-12-24 16:55:16 +01001574balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02001575balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001576 Define the load balancing algorithm to be used in a backend.
1577 May be used in sections : defaults | frontend | listen | backend
1578 yes | no | yes | yes
1579 Arguments :
1580 <algorithm> is the algorithm used to select a server when doing load
1581 balancing. This only applies when no persistence information
1582 is available, or when a connection is redispatched to another
1583 server. <algorithm> may be one of the following :
1584
1585 roundrobin Each server is used in turns, according to their weights.
1586 This is the smoothest and fairest algorithm when the server's
1587 processing time remains equally distributed. This algorithm
1588 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001589 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08001590 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02001591 large farms, when a server becomes up after having been down
1592 for a very short time, it may sometimes take a few hundreds
1593 requests for it to be re-integrated into the farm and start
1594 receiving traffic. This is normal, though very rare. It is
1595 indicated here in case you would have the chance to observe
1596 it, so that you don't worry.
1597
1598 static-rr Each server is used in turns, according to their weights.
1599 This algorithm is as similar to roundrobin except that it is
1600 static, which means that changing a server's weight on the
1601 fly will have no effect. On the other hand, it has no design
1602 limitation on the number of servers, and when a server goes
1603 up, it is always immediately reintroduced into the farm, once
1604 the full map is recomputed. It also uses slightly less CPU to
1605 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001606
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001607 leastconn The server with the lowest number of connections receives the
1608 connection. Round-robin is performed within groups of servers
1609 of the same load to ensure that all servers will be used. Use
1610 of this algorithm is recommended where very long sessions are
1611 expected, such as LDAP, SQL, TSE, etc... but is not very well
1612 suited for protocols using short sessions such as HTTP. This
1613 algorithm is dynamic, which means that server weights may be
1614 adjusted on the fly for slow starts for instance.
1615
Willy Tarreauf09c6602012-02-13 17:12:08 +01001616 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001617 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01001618 identifier to the highest (see server parameter "id"), which
1619 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001620 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001621 not make sense to use this algorithm without setting maxconn.
1622 The purpose of this algorithm is to always use the smallest
1623 number of servers so that extra servers can be powered off
1624 during non-intensive hours. This algorithm ignores the server
1625 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001626 or IMAP than HTTP, though it can be useful there too. In
1627 order to use this algorithm efficiently, it is recommended
1628 that a cloud controller regularly checks server usage to turn
1629 them off when unused, and regularly checks backend queue to
1630 turn new servers on when the queue inflates. Alternatively,
1631 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001632
Willy Tarreau0ba27502007-12-24 16:55:16 +01001633 source The source IP address is hashed and divided by the total
1634 weight of the running servers to designate which server will
1635 receive the request. This ensures that the same client IP
1636 address will always reach the same server as long as no
1637 server goes down or up. If the hash result changes due to the
1638 number of running servers changing, many clients will be
1639 directed to a different server. This algorithm is generally
1640 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001641 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001642 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001643 static by default, which means that changing a server's
1644 weight on the fly will have no effect, but this can be
1645 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001646
Oskar Stolc8dc41842012-05-19 10:19:54 +01001647 uri This algorithm hashes either the left part of the URI (before
1648 the question mark) or the whole URI (if the "whole" parameter
1649 is present) and divides the hash value by the total weight of
1650 the running servers. The result designates which server will
1651 receive the request. This ensures that the same URI will
1652 always be directed to the same server as long as no server
1653 goes up or down. This is used with proxy caches and
1654 anti-virus proxies in order to maximize the cache hit rate.
1655 Note that this algorithm may only be used in an HTTP backend.
1656 This algorithm is static by default, which means that
1657 changing a server's weight on the fly will have no effect,
1658 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001659
Oskar Stolc8dc41842012-05-19 10:19:54 +01001660 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001661 "depth", both followed by a positive integer number. These
1662 options may be helpful when it is needed to balance servers
1663 based on the beginning of the URI only. The "len" parameter
1664 indicates that the algorithm should only consider that many
1665 characters at the beginning of the URI to compute the hash.
1666 Note that having "len" set to 1 rarely makes sense since most
1667 URIs start with a leading "/".
1668
1669 The "depth" parameter indicates the maximum directory depth
1670 to be used to compute the hash. One level is counted for each
1671 slash in the request. If both parameters are specified, the
1672 evaluation stops when either is reached.
1673
Willy Tarreau0ba27502007-12-24 16:55:16 +01001674 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001675 the query string of each HTTP GET request.
1676
1677 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001678 request entity will be searched for the parameter argument,
1679 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02001680 ('?') in the URL. The message body will only start to be
1681 analyzed once either the advertised amount of data has been
1682 received or the request buffer is full. In the unlikely event
1683 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02001684 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02001685 be randomly balanced if at all. This keyword used to support
1686 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001687
1688 If the parameter is found followed by an equal sign ('=') and
1689 a value, then the value is hashed and divided by the total
1690 weight of the running servers. The result designates which
1691 server will receive the request.
1692
1693 This is used to track user identifiers in requests and ensure
1694 that a same user ID will always be sent to the same server as
1695 long as no server goes up or down. If no value is found or if
1696 the parameter is not found, then a round robin algorithm is
1697 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001698 backend. This algorithm is static by default, which means
1699 that changing a server's weight on the fly will have no
1700 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001701
Cyril Bontédc4d9032012-04-08 21:57:39 +02001702 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1703 request. Just as with the equivalent ACL 'hdr()' function,
1704 the header name in parenthesis is not case sensitive. If the
1705 header is absent or if it does not contain any value, the
1706 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001707
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001708 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001709 reducing the hash algorithm to the main domain part with some
1710 specific headers such as 'Host'. For instance, in the Host
1711 value "haproxy.1wt.eu", only "1wt" will be considered.
1712
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001713 This algorithm is static by default, which means that
1714 changing a server's weight on the fly will have no effect,
1715 but this can be changed using "hash-type".
1716
Emeric Brun736aa232009-06-30 17:56:00 +02001717 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001718 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001719 The RDP cookie <name> (or "mstshash" if omitted) will be
1720 looked up and hashed for each incoming TCP request. Just as
1721 with the equivalent ACL 'req_rdp_cookie()' function, the name
1722 is not case-sensitive. This mechanism is useful as a degraded
1723 persistence mode, as it makes it possible to always send the
1724 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001725 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001726 used instead.
1727
1728 Note that for this to work, the frontend must ensure that an
1729 RDP cookie is already present in the request buffer. For this
1730 you must use 'tcp-request content accept' rule combined with
1731 a 'req_rdp_cookie_cnt' ACL.
1732
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001733 This algorithm is static by default, which means that
1734 changing a server's weight on the fly will have no effect,
1735 but this can be changed using "hash-type".
1736
Cyril Bontédc4d9032012-04-08 21:57:39 +02001737 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09001738
Willy Tarreau0ba27502007-12-24 16:55:16 +01001739 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001740 algorithms. Right now, only "url_param" and "uri" support an
1741 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001742
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001743 The load balancing algorithm of a backend is set to roundrobin when no other
1744 algorithm, mode nor option have been set. The algorithm may only be set once
1745 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001746
1747 Examples :
1748 balance roundrobin
1749 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001750 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001751 balance hdr(User-Agent)
1752 balance hdr(host)
1753 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001754
1755 Note: the following caveats and limitations on using the "check_post"
1756 extension with "url_param" must be considered :
1757
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001758 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001759 to determine if the parameters will be found in the body or entity which
1760 may contain binary data. Therefore another method may be required to
1761 restrict consideration of POST requests that have no URL parameters in
1762 the body. (see acl reqideny http_end)
1763
1764 - using a <max_wait> value larger than the request buffer size does not
1765 make sense and is useless. The buffer size is set at build time, and
1766 defaults to 16 kB.
1767
1768 - Content-Encoding is not supported, the parameter search will probably
1769 fail; and load balancing will fall back to Round Robin.
1770
1771 - Expect: 100-continue is not supported, load balancing will fall back to
1772 Round Robin.
1773
1774 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1775 If the entire parameter value is not present in the first chunk, the
1776 selection of server is undefined (actually, defined by how little
1777 actually appeared in the first chunk).
1778
1779 - This feature does not support generation of a 100, 411 or 501 response.
1780
1781 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001782 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001783 white space or control characters are found, indicating the end of what
1784 might be a URL parameter list. This is probably not a concern with SGML
1785 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001786
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001787 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1788 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001789
1790
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001791bind [<address>]:<port_range> [, ...] [param*]
1792bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001793 Define one or several listening addresses and/or ports in a frontend.
1794 May be used in sections : defaults | frontend | listen | backend
1795 no | yes | yes | no
1796 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001797 <address> is optional and can be a host name, an IPv4 address, an IPv6
1798 address, or '*'. It designates the address the frontend will
1799 listen on. If unset, all IPv4 addresses of the system will be
1800 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001801 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01001802 Optionally, an address family prefix may be used before the
1803 address to force the family regardless of the address format,
1804 which can be useful to specify a path to a unix socket with
1805 no slash ('/'). Currently supported prefixes are :
1806 - 'ipv4@' -> address is always IPv4
1807 - 'ipv6@' -> address is always IPv6
1808 - 'unix@' -> address is a path to a local unix socket
Willy Tarreaub4fca5d2014-07-08 00:37:50 +02001809 - 'abns@' -> address is in abstract namespace (Linux only).
1810 Note: since abstract sockets are not "rebindable", they
1811 do not cope well with multi-process mode during
1812 soft-restart, so it is better to avoid them if
1813 nbproc is greater than 1. The effect is that if the
1814 new process fails to start, only one of the old ones
1815 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01001816 - 'fd@<n>' -> use file descriptor <n> inherited from the
1817 parent. The fd must be bound and may or may not already
1818 be listening.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001819 Any part of the address string may reference any number of
1820 environment variables by preceding their name with a dollar
1821 sign ('$') and optionally enclosing them with braces ('{}'),
1822 similarly to what is done in Bourne shell.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001823
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001824 <port_range> is either a unique TCP port, or a port range for which the
1825 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001826 above. The port is mandatory for TCP listeners. Note that in
1827 the case of an IPv6 address, the port is always the number
1828 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001829 - a numerical port (ex: '80')
1830 - a dash-delimited ports range explicitly stating the lower
1831 and upper bounds (ex: '2000-2100') which are included in
1832 the range.
1833
1834 Particular care must be taken against port ranges, because
1835 every <address:port> couple consumes one socket (= a file
1836 descriptor), so it's easy to consume lots of descriptors
1837 with a simple range, and to run out of sockets. Also, each
1838 <address:port> couple must be used only once among all
1839 instances running on a same system. Please note that binding
1840 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001841 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001842 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001843
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001844 <path> is a UNIX socket path beginning with a slash ('/'). This is
1845 alternative to the TCP listening port. Haproxy will then
1846 receive UNIX connections on the socket located at this place.
1847 The path must begin with a slash and by default is absolute.
1848 It can be relative to the prefix defined by "unix-bind" in
1849 the global section. Note that the total length of the prefix
1850 followed by the socket path cannot exceed some system limits
1851 for UNIX sockets, which commonly are set to 107 characters.
1852
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001853 <param*> is a list of parameters common to all sockets declared on the
1854 same line. These numerous parameters depend on OS and build
1855 options and have a complete section dedicated to them. Please
1856 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001857
Willy Tarreau0ba27502007-12-24 16:55:16 +01001858 It is possible to specify a list of address:port combinations delimited by
1859 commas. The frontend will then listen on all of these addresses. There is no
1860 fixed limit to the number of addresses and ports which can be listened on in
1861 a frontend, as well as there is no limit to the number of "bind" statements
1862 in a frontend.
1863
1864 Example :
1865 listen http_proxy
1866 bind :80,:443
1867 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001868 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001869
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001870 listen http_https_proxy
1871 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02001872 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001873
Willy Tarreau24709282013-03-10 21:32:12 +01001874 listen http_https_proxy_explicit
1875 bind ipv6@:80
1876 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
1877 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
1878
Willy Tarreaudad36a32013-03-11 01:20:04 +01001879 listen external_bind_app1
1880 bind fd@${FD_APP1}
1881
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001882 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001883 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001884
1885
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001886bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001887 Limit visibility of an instance to a certain set of processes numbers.
1888 May be used in sections : defaults | frontend | listen | backend
1889 yes | yes | yes | yes
1890 Arguments :
1891 all All process will see this instance. This is the default. It
1892 may be used to override a default value.
1893
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001894 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001895 option may be combined with other numbers.
1896
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001897 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001898 option may be combined with other numbers. Do not use it
1899 with less than 2 processes otherwise some instances might be
1900 missing from all processes.
1901
Willy Tarreau110ecc12012-11-15 17:50:01 +01001902 number The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001903 whose values must all be between 1 and 32 or 64 depending on
Willy Tarreau102df612014-05-07 23:56:38 +02001904 the machine's word size. If a proxy is bound to process
1905 numbers greater than the configured global.nbproc, it will
1906 either be forced to process #1 if a single process was
1907 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001908
1909 This keyword limits binding of certain instances to certain processes. This
1910 is useful in order not to have too many processes listening to the same
1911 ports. For instance, on a dual-core machine, it might make sense to set
1912 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1913 and 'even' instances.
1914
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001915 At the moment, it is not possible to reference more than 32 or 64 processes
1916 using this keyword, but this should be more than enough for most setups.
1917 Please note that 'all' really means all processes regardless of the machine's
1918 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001919
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02001920 Each "bind" line may further be limited to a subset of the proxy's processes,
1921 please consult the "process" bind keyword in section 5.1.
1922
Willy Tarreaue56c4f12014-09-16 13:21:03 +02001923 When a frontend has no explicit "bind-process" line, it tries to bind to all
1924 the processes referenced by its "bind" lines. That means that frontends can
1925 easily adapt to their listeners' processes.
1926
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001927 If some backends are referenced by frontends bound to other processes, the
1928 backend automatically inherits the frontend's processes.
1929
1930 Example :
1931 listen app_ip1
1932 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001933 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001934
1935 listen app_ip2
1936 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001937 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001938
1939 listen management
1940 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001941 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001942
Willy Tarreau110ecc12012-11-15 17:50:01 +01001943 listen management
1944 bind 10.0.0.4:80
1945 bind-process 1-4
1946
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02001947 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001948
1949
Willy Tarreau0ba27502007-12-24 16:55:16 +01001950block { if | unless } <condition>
1951 Block a layer 7 request if/unless a condition is matched
1952 May be used in sections : defaults | frontend | listen | backend
1953 no | yes | yes | yes
1954
1955 The HTTP request will be blocked very early in the layer 7 processing
1956 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001957 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001958 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001959 conditions are met or not met. There is no fixed limit to the number of
1960 "block" statements per instance.
1961
1962 Example:
1963 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1964 acl invalid_src src_port 0:1023
1965 acl local_dst hdr(host) -i localhost
1966 block if invalid_src || local_dst
1967
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001968 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001969
1970
1971capture cookie <name> len <length>
1972 Capture and log a cookie in the request and in the response.
1973 May be used in sections : defaults | frontend | listen | backend
1974 no | yes | yes | no
1975 Arguments :
1976 <name> is the beginning of the name of the cookie to capture. In order
1977 to match the exact name, simply suffix the name with an equal
1978 sign ('='). The full name will appear in the logs, which is
1979 useful with application servers which adjust both the cookie name
1980 and value (eg: ASPSESSIONXXXXX).
1981
1982 <length> is the maximum number of characters to report in the logs, which
1983 include the cookie name, the equal sign and the value, all in the
1984 standard "name=value" form. The string will be truncated on the
1985 right if it exceeds <length>.
1986
1987 Only the first cookie is captured. Both the "cookie" request headers and the
1988 "set-cookie" response headers are monitored. This is particularly useful to
1989 check for application bugs causing session crossing or stealing between
1990 users, because generally the user's cookies can only change on a login page.
1991
1992 When the cookie was not presented by the client, the associated log column
1993 will report "-". When a request does not cause a cookie to be assigned by the
1994 server, a "-" is reported in the response column.
1995
1996 The capture is performed in the frontend only because it is necessary that
1997 the log format does not change for a given frontend depending on the
1998 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01001999 "capture cookie" statement in a frontend. The maximum capture length is set
2000 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
2001 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002002
2003 Example:
2004 capture cookie ASPSESSION len 32
2005
2006 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002007 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002008
2009
2010capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002011 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002012 May be used in sections : defaults | frontend | listen | backend
2013 no | yes | yes | no
2014 Arguments :
2015 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002016 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002017 appear in the requests, with the first letter of each word in
2018 upper case. The header name will not appear in the logs, only the
2019 value is reported, but the position in the logs is respected.
2020
2021 <length> is the maximum number of characters to extract from the value and
2022 report in the logs. The string will be truncated on the right if
2023 it exceeds <length>.
2024
Willy Tarreau4460d032012-11-21 23:37:37 +01002025 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002026 value will be added to the logs between braces ('{}'). If multiple headers
2027 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002028 in the same order they were declared in the configuration. Non-existent
2029 headers will be logged just as an empty string. Common uses for request
2030 header captures include the "Host" field in virtual hosting environments, the
2031 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002032 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002033 environments to find where the request came from.
2034
2035 Note that when capturing headers such as "User-agent", some spaces may be
2036 logged, making the log analysis more difficult. Thus be careful about what
2037 you log if you know your log parser is not smart enough to rely on the
2038 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002039
Willy Tarreau0900abb2012-11-22 00:21:46 +01002040 There is no limit to the number of captured request headers nor to their
2041 length, though it is wise to keep them low to limit memory usage per session.
2042 In order to keep log format consistent for a same frontend, header captures
2043 can only be declared in a frontend. It is not possible to specify a capture
2044 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002045
2046 Example:
2047 capture request header Host len 15
2048 capture request header X-Forwarded-For len 15
2049 capture request header Referrer len 15
2050
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002051 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002052 about logging.
2053
2054
2055capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002056 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002057 May be used in sections : defaults | frontend | listen | backend
2058 no | yes | yes | no
2059 Arguments :
2060 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002061 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002062 appear in the response, with the first letter of each word in
2063 upper case. The header name will not appear in the logs, only the
2064 value is reported, but the position in the logs is respected.
2065
2066 <length> is the maximum number of characters to extract from the value and
2067 report in the logs. The string will be truncated on the right if
2068 it exceeds <length>.
2069
Willy Tarreau4460d032012-11-21 23:37:37 +01002070 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002071 result will be added to the logs between braces ('{}') after the captured
2072 request headers. If multiple headers are captured, they will be delimited by
2073 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002074 the configuration. Non-existent headers will be logged just as an empty
2075 string. Common uses for response header captures include the "Content-length"
2076 header which indicates how many bytes are expected to be returned, the
2077 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002078
Willy Tarreau0900abb2012-11-22 00:21:46 +01002079 There is no limit to the number of captured response headers nor to their
2080 length, though it is wise to keep them low to limit memory usage per session.
2081 In order to keep log format consistent for a same frontend, header captures
2082 can only be declared in a frontend. It is not possible to specify a capture
2083 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002084
2085 Example:
2086 capture response header Content-length len 9
2087 capture response header Location len 15
2088
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002089 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002090 about logging.
2091
2092
Cyril Bontéf0c60612010-02-06 14:44:47 +01002093clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002094 Set the maximum inactivity time on the client side.
2095 May be used in sections : defaults | frontend | listen | backend
2096 yes | yes | yes | no
2097 Arguments :
2098 <timeout> is the timeout value is specified in milliseconds by default, but
2099 can be in any other unit if the number is suffixed by the unit,
2100 as explained at the top of this document.
2101
2102 The inactivity timeout applies when the client is expected to acknowledge or
2103 send data. In HTTP mode, this timeout is particularly important to consider
2104 during the first phase, when the client sends the request, and during the
2105 response while it is reading data sent by the server. The value is specified
2106 in milliseconds by default, but can be in any other unit if the number is
2107 suffixed by the unit, as specified at the top of this document. In TCP mode
2108 (and to a lesser extent, in HTTP mode), it is highly recommended that the
2109 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002110 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01002111 losses by specifying timeouts that are slightly above multiples of 3 seconds
2112 (eg: 4 or 5 seconds).
2113
2114 This parameter is specific to frontends, but can be specified once for all in
2115 "defaults" sections. This is in fact one of the easiest solutions not to
2116 forget about it. An unspecified timeout results in an infinite timeout, which
2117 is not recommended. Such a usage is accepted and works but reports a warning
2118 during startup because it may results in accumulation of expired sessions in
2119 the system if the system's timeouts are not configured either.
2120
2121 This parameter is provided for compatibility but is currently deprecated.
2122 Please use "timeout client" instead.
2123
Willy Tarreau036fae02008-01-06 13:24:40 +01002124 See also : "timeout client", "timeout http-request", "timeout server", and
2125 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002126
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002127compression algo <algorithm> ...
2128compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02002129compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02002130 Enable HTTP compression.
2131 May be used in sections : defaults | frontend | listen | backend
2132 yes | yes | yes | yes
2133 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002134 algo is followed by the list of supported compression algorithms.
2135 type is followed by the list of MIME types that will be compressed.
2136 offload makes haproxy work as a compression offloader only (see notes).
2137
2138 The currently supported algorithms are :
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002139 identity this is mostly for debugging, and it was useful for developing
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002140 the compression feature. Identity does not apply any change on
2141 data.
2142
2143 gzip applies gzip compression. This setting is only available when
2144 support for zlib was built in.
2145
2146 deflate same as gzip, but with deflate algorithm and zlib format.
2147 Note that this algorithm has ambiguous support on many browsers
2148 and no support at all from recent ones. It is strongly
2149 recommended not to use it for anything else than experimentation.
2150 This setting is only available when support for zlib was built
2151 in.
2152
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002153 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002154 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002155 If backend servers support HTTP compression, these directives
2156 will be no-op: haproxy will see the compressed response and will not
2157 compress again. If backend servers do not support HTTP compression and
2158 there is Accept-Encoding header in request, haproxy will compress the
2159 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02002160
2161 The "offload" setting makes haproxy remove the Accept-Encoding header to
2162 prevent backend servers from compressing responses. It is strongly
2163 recommended not to do this because this means that all the compression work
2164 will be done on the single point where haproxy is located. However in some
2165 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002166 with broken HTTP compression implementation which can't be turned off.
2167 In that case haproxy can be used to prevent that gateway from emitting
2168 invalid payloads. In this case, simply removing the header in the
2169 configuration does not work because it applies before the header is parsed,
2170 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreau4cf57af2014-07-12 16:37:02 +02002171 then be used for such scenarios. Note: for now, the "offload" setting is
2172 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02002173
William Lallemand05097442012-11-20 12:14:28 +01002174 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002175 * the request does not advertise a supported compression algorithm in the
2176 "Accept-Encoding" header
2177 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01002178 * HTTP status code is not 200
William Lallemand8bb4e342013-12-10 17:28:48 +01002179 * response header "Transfer-Encoding" contains "chunked" (Temporary
2180 Workaround)
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002181 * response contain neither a "Content-Length" header nor a
2182 "Transfer-Encoding" whose last value is "chunked"
2183 * response contains a "Content-Type" header whose first value starts with
2184 "multipart"
2185 * the response contains the "no-transform" value in the "Cache-control"
2186 header
2187 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
2188 and later
2189 * The response contains a "Content-Encoding" header, indicating that the
2190 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01002191
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002192 Note: The compression does not rewrite Etag headers, and does not emit the
2193 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01002194
William Lallemand82fe75c2012-10-23 10:25:10 +02002195 Examples :
2196 compression algo gzip
2197 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002198
Cyril Bontéf0c60612010-02-06 14:44:47 +01002199contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002200 Set the maximum time to wait for a connection attempt to a server to succeed.
2201 May be used in sections : defaults | frontend | listen | backend
2202 yes | no | yes | yes
2203 Arguments :
2204 <timeout> is the timeout value is specified in milliseconds by default, but
2205 can be in any other unit if the number is suffixed by the unit,
2206 as explained at the top of this document.
2207
2208 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002209 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01002210 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01002211 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
2212 connect timeout also presets the queue timeout to the same value if this one
2213 has not been specified. Historically, the contimeout was also used to set the
2214 tarpit timeout in a listen section, which is not possible in a pure frontend.
2215
2216 This parameter is specific to backends, but can be specified once for all in
2217 "defaults" sections. This is in fact one of the easiest solutions not to
2218 forget about it. An unspecified timeout results in an infinite timeout, which
2219 is not recommended. Such a usage is accepted and works but reports a warning
2220 during startup because it may results in accumulation of failed sessions in
2221 the system if the system's timeouts are not configured either.
2222
2223 This parameter is provided for backwards compatibility but is currently
2224 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
2225 instead.
2226
2227 See also : "timeout connect", "timeout queue", "timeout tarpit",
2228 "timeout server", "contimeout".
2229
2230
Willy Tarreau55165fe2009-05-10 12:02:55 +02002231cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02002232 [ postonly ] [ preserve ] [ httponly ] [ secure ]
2233 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002234 Enable cookie-based persistence in a backend.
2235 May be used in sections : defaults | frontend | listen | backend
2236 yes | no | yes | yes
2237 Arguments :
2238 <name> is the name of the cookie which will be monitored, modified or
2239 inserted in order to bring persistence. This cookie is sent to
2240 the client via a "Set-Cookie" header in the response, and is
2241 brought back by the client in a "Cookie" header in all requests.
2242 Special care should be taken to choose a name which does not
2243 conflict with any likely application cookie. Also, if the same
2244 backends are subject to be used by the same clients (eg:
2245 HTTP/HTTPS), care should be taken to use different cookie names
2246 between all backends if persistence between them is not desired.
2247
2248 rewrite This keyword indicates that the cookie will be provided by the
2249 server and that haproxy will have to modify its value to set the
2250 server's identifier in it. This mode is handy when the management
2251 of complex combinations of "Set-cookie" and "Cache-control"
2252 headers is left to the application. The application can then
2253 decide whether or not it is appropriate to emit a persistence
2254 cookie. Since all responses should be monitored, this mode only
2255 works in HTTP close mode. Unless the application behaviour is
2256 very complex and/or broken, it is advised not to start with this
2257 mode for new deployments. This keyword is incompatible with
2258 "insert" and "prefix".
2259
2260 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02002261 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002262
Willy Tarreaua79094d2010-08-31 22:54:15 +02002263 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002264 server. When used without the "preserve" option, if the server
2265 emits a cookie with the same name, it will be remove before
2266 processing. For this reason, this mode can be used to upgrade
2267 existing configurations running in the "rewrite" mode. The cookie
2268 will only be a session cookie and will not be stored on the
2269 client's disk. By default, unless the "indirect" option is added,
2270 the server will see the cookies emitted by the client. Due to
2271 caching effects, it is generally wise to add the "nocache" or
2272 "postonly" keywords (see below). The "insert" keyword is not
2273 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002274
2275 prefix This keyword indicates that instead of relying on a dedicated
2276 cookie for the persistence, an existing one will be completed.
2277 This may be needed in some specific environments where the client
2278 does not support more than one single cookie and the application
2279 already needs it. In this case, whenever the server sets a cookie
2280 named <name>, it will be prefixed with the server's identifier
2281 and a delimiter. The prefix will be removed from all client
2282 requests so that the server still finds the cookie it emitted.
2283 Since all requests and responses are subject to being modified,
2284 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02002285 not compatible with "rewrite" and "insert". Note: it is highly
2286 recommended not to use "indirect" with "prefix", otherwise server
2287 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002288
Willy Tarreaua79094d2010-08-31 22:54:15 +02002289 indirect When this option is specified, no cookie will be emitted to a
2290 client which already has a valid one for the server which has
2291 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002292 it will be removed, unless the "preserve" option is also set. In
2293 "insert" mode, this will additionally remove cookies from the
2294 requests transmitted to the server, making the persistence
2295 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02002296 Note: it is highly recommended not to use "indirect" with
2297 "prefix", otherwise server cookie updates would not be sent to
2298 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002299
2300 nocache This option is recommended in conjunction with the insert mode
2301 when there is a cache between the client and HAProxy, as it
2302 ensures that a cacheable response will be tagged non-cacheable if
2303 a cookie needs to be inserted. This is important because if all
2304 persistence cookies are added on a cacheable home page for
2305 instance, then all customers will then fetch the page from an
2306 outer cache and will all share the same persistence cookie,
2307 leading to one server receiving much more traffic than others.
2308 See also the "insert" and "postonly" options.
2309
2310 postonly This option ensures that cookie insertion will only be performed
2311 on responses to POST requests. It is an alternative to the
2312 "nocache" option, because POST responses are not cacheable, so
2313 this ensures that the persistence cookie will never get cached.
2314 Since most sites do not need any sort of persistence before the
2315 first POST which generally is a login request, this is a very
2316 efficient method to optimize caching without risking to find a
2317 persistence cookie in the cache.
2318 See also the "insert" and "nocache" options.
2319
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002320 preserve This option may only be used with "insert" and/or "indirect". It
2321 allows the server to emit the persistence cookie itself. In this
2322 case, if a cookie is found in the response, haproxy will leave it
2323 untouched. This is useful in order to end persistence after a
2324 logout request for instance. For this, the server just has to
2325 emit a cookie with an invalid value (eg: empty) or with a date in
2326 the past. By combining this mechanism with the "disable-on-404"
2327 check option, it is possible to perform a completely graceful
2328 shutdown because users will definitely leave the server after
2329 they logout.
2330
Willy Tarreau4992dd22012-05-31 21:02:17 +02002331 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2332 when a cookie is inserted. This attribute is used so that a
2333 user agent doesn't share the cookie with non-HTTP components.
2334 Please check RFC6265 for more information on this attribute.
2335
2336 secure This option tells haproxy to add a "Secure" cookie attribute when
2337 a cookie is inserted. This attribute is used so that a user agent
2338 never emits this cookie over non-secure channels, which means
2339 that a cookie learned with this flag will be presented only over
2340 SSL/TLS connections. Please check RFC6265 for more information on
2341 this attribute.
2342
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002343 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002344 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002345 name. If the domain begins with a dot, the browser is allowed to
2346 use it for any host ending with that name. It is also possible to
2347 specify several domain names by invoking this option multiple
2348 times. Some browsers might have small limits on the number of
2349 domains, so be careful when doing that. For the record, sending
2350 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002351
Willy Tarreau996a92c2010-10-13 19:30:47 +02002352 maxidle This option allows inserted cookies to be ignored after some idle
2353 time. It only works with insert-mode cookies. When a cookie is
2354 sent to the client, the date this cookie was emitted is sent too.
2355 Upon further presentations of this cookie, if the date is older
2356 than the delay indicated by the parameter (in seconds), it will
2357 be ignored. Otherwise, it will be refreshed if needed when the
2358 response is sent to the client. This is particularly useful to
2359 prevent users who never close their browsers from remaining for
2360 too long on the same server (eg: after a farm size change). When
2361 this option is set and a cookie has no date, it is always
2362 accepted, but gets refreshed in the response. This maintains the
2363 ability for admins to access their sites. Cookies that have a
2364 date in the future further than 24 hours are ignored. Doing so
2365 lets admins fix timezone issues without risking kicking users off
2366 the site.
2367
2368 maxlife This option allows inserted cookies to be ignored after some life
2369 time, whether they're in use or not. It only works with insert
2370 mode cookies. When a cookie is first sent to the client, the date
2371 this cookie was emitted is sent too. Upon further presentations
2372 of this cookie, if the date is older than the delay indicated by
2373 the parameter (in seconds), it will be ignored. If the cookie in
2374 the request has no date, it is accepted and a date will be set.
2375 Cookies that have a date in the future further than 24 hours are
2376 ignored. Doing so lets admins fix timezone issues without risking
2377 kicking users off the site. Contrary to maxidle, this value is
2378 not refreshed, only the first visit date counts. Both maxidle and
2379 maxlife may be used at the time. This is particularly useful to
2380 prevent users who never close their browsers from remaining for
2381 too long on the same server (eg: after a farm size change). This
2382 is stronger than the maxidle method in that it forces a
2383 redispatch after some absolute delay.
2384
Willy Tarreau0ba27502007-12-24 16:55:16 +01002385 There can be only one persistence cookie per HTTP backend, and it can be
2386 declared in a defaults section. The value of the cookie will be the value
2387 indicated after the "cookie" keyword in a "server" statement. If no cookie
2388 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002389
Willy Tarreau0ba27502007-12-24 16:55:16 +01002390 Examples :
2391 cookie JSESSIONID prefix
2392 cookie SRV insert indirect nocache
2393 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002394 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002395
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002396 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002397 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002398
Willy Tarreau983e01e2010-01-11 18:42:06 +01002399
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002400default-server [param*]
2401 Change default options for a server in a backend
2402 May be used in sections : defaults | frontend | listen | backend
2403 yes | no | yes | yes
2404 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002405 <param*> is a list of parameters for this server. The "default-server"
2406 keyword accepts an important number of options and has a complete
2407 section dedicated to it. Please refer to section 5 for more
2408 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002409
Willy Tarreau983e01e2010-01-11 18:42:06 +01002410 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002411 default-server inter 1000 weight 13
2412
2413 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002414
Willy Tarreau983e01e2010-01-11 18:42:06 +01002415
Willy Tarreau0ba27502007-12-24 16:55:16 +01002416default_backend <backend>
2417 Specify the backend to use when no "use_backend" rule has been matched.
2418 May be used in sections : defaults | frontend | listen | backend
2419 yes | yes | yes | no
2420 Arguments :
2421 <backend> is the name of the backend to use.
2422
2423 When doing content-switching between frontend and backends using the
2424 "use_backend" keyword, it is often useful to indicate which backend will be
2425 used when no rule has matched. It generally is the dynamic backend which
2426 will catch all undetermined requests.
2427
Willy Tarreau0ba27502007-12-24 16:55:16 +01002428 Example :
2429
2430 use_backend dynamic if url_dyn
2431 use_backend static if url_css url_img extension_img
2432 default_backend dynamic
2433
Willy Tarreau2769aa02007-12-27 18:26:09 +01002434 See also : "use_backend", "reqsetbe", "reqisetbe"
2435
Willy Tarreau0ba27502007-12-24 16:55:16 +01002436
Baptiste Assmann27f51342013-10-09 06:51:49 +02002437description <string>
2438 Describe a listen, frontend or backend.
2439 May be used in sections : defaults | frontend | listen | backend
2440 no | yes | yes | yes
2441 Arguments : string
2442
2443 Allows to add a sentence to describe the related object in the HAProxy HTML
2444 stats page. The description will be printed on the right of the object name
2445 it describes.
2446 No need to backslash spaces in the <string> arguments.
2447
2448
Willy Tarreau0ba27502007-12-24 16:55:16 +01002449disabled
2450 Disable a proxy, frontend or backend.
2451 May be used in sections : defaults | frontend | listen | backend
2452 yes | yes | yes | yes
2453 Arguments : none
2454
2455 The "disabled" keyword is used to disable an instance, mainly in order to
2456 liberate a listening port or to temporarily disable a service. The instance
2457 will still be created and its configuration will be checked, but it will be
2458 created in the "stopped" state and will appear as such in the statistics. It
2459 will not receive any traffic nor will it send any health-checks or logs. It
2460 is possible to disable many instances at once by adding the "disabled"
2461 keyword in a "defaults" section.
2462
2463 See also : "enabled"
2464
2465
Willy Tarreau5ce94572010-06-07 14:35:41 +02002466dispatch <address>:<port>
2467 Set a default server address
2468 May be used in sections : defaults | frontend | listen | backend
2469 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002470 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002471
2472 <address> is the IPv4 address of the default server. Alternatively, a
2473 resolvable hostname is supported, but this name will be resolved
2474 during start-up.
2475
2476 <ports> is a mandatory port specification. All connections will be sent
2477 to this port, and it is not permitted to use port offsets as is
2478 possible with normal servers.
2479
Willy Tarreau787aed52011-04-15 06:45:37 +02002480 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002481 server can take the connection. In the past it was used to forward non
2482 persistent connections to an auxiliary load balancer. Due to its simple
2483 syntax, it has also been used for simple TCP relays. It is recommended not to
2484 use it for more clarity, and to use the "server" directive instead.
2485
2486 See also : "server"
2487
2488
Willy Tarreau0ba27502007-12-24 16:55:16 +01002489enabled
2490 Enable a proxy, frontend or backend.
2491 May be used in sections : defaults | frontend | listen | backend
2492 yes | yes | yes | yes
2493 Arguments : none
2494
2495 The "enabled" keyword is used to explicitly enable an instance, when the
2496 defaults has been set to "disabled". This is very rarely used.
2497
2498 See also : "disabled"
2499
2500
2501errorfile <code> <file>
2502 Return a file contents instead of errors generated by HAProxy
2503 May be used in sections : defaults | frontend | listen | backend
2504 yes | yes | yes | yes
2505 Arguments :
2506 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002507 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002508
2509 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002510 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002511 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002512 error pages, and to use absolute paths, since files are read
2513 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002514
2515 It is important to understand that this keyword is not meant to rewrite
2516 errors returned by the server, but errors detected and returned by HAProxy.
2517 This is why the list of supported errors is limited to a small set.
2518
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002519 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2520
Willy Tarreau0ba27502007-12-24 16:55:16 +01002521 The files are returned verbatim on the TCP socket. This allows any trick such
2522 as redirections to another URL or site, as well as tricks to clean cookies,
2523 force enable or disable caching, etc... The package provides default error
2524 files returning the same contents as default errors.
2525
Willy Tarreau59140a22009-02-22 12:02:30 +01002526 The files should not exceed the configured buffer size (BUFSIZE), which
2527 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2528 not to put any reference to local contents (eg: images) in order to avoid
2529 loops between the client and HAProxy when all servers are down, causing an
2530 error to be returned instead of an image. For better HTTP compliance, it is
2531 recommended that all header lines end with CR-LF and not LF alone.
2532
Willy Tarreau0ba27502007-12-24 16:55:16 +01002533 The files are read at the same time as the configuration and kept in memory.
2534 For this reason, the errors continue to be returned even when the process is
2535 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002536 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002537 403 status code and interrogating a blocked URL.
2538
2539 See also : "errorloc", "errorloc302", "errorloc303"
2540
Willy Tarreau59140a22009-02-22 12:02:30 +01002541 Example :
2542 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau2705a612014-05-23 17:38:34 +02002543 errorfile 408 /dev/null # workaround Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01002544 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2545 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2546
Willy Tarreau2769aa02007-12-27 18:26:09 +01002547
2548errorloc <code> <url>
2549errorloc302 <code> <url>
2550 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2551 May be used in sections : defaults | frontend | listen | backend
2552 yes | yes | yes | yes
2553 Arguments :
2554