blob: 19df5ae54ef7446acf63b78cb6d55038210ea385 [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 Tarreaub55c46e2014-09-02 13:54:16 +02005 version 1.5.4
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreaub55c46e2014-09-02 13:54:16 +02007 2014/09/02
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
660ssl-default-server-ciphers <ciphers>
661 This setting is only available when support for OpenSSL was built in. It
662 sets the default string describing the list of cipher algorithms that are
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300663 negotiated during the SSL/TLS handshake with the server, for all "server"
Willy Tarreau610f04b2014-02-13 11:36:41 +0100664 lines which do not explicitly define theirs. The format of the string is
665 defined in "man 1 ciphers". Please check the "server" keyword for more
666 information.
667
Emeric Brun850efd52014-01-29 12:24:34 +0100668ssl-server-verify [none|required]
669 The default behavior for SSL verify on servers side. If specified to 'none',
670 servers certificates are not verified. The default is 'required' except if
671 forced using cmdline option '-dV'.
672
Willy Tarreauabb175f2012-09-24 12:43:26 +0200673stats socket [<address:port>|<path>] [param*]
674 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
675 Connections to this socket will return various statistics outputs and even
676 allow some commands to be issued to change some runtime settings. Please
677 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200678
Willy Tarreauabb175f2012-09-24 12:43:26 +0200679 All parameters supported by "bind" lines are supported, for instance to
680 restrict access to some users or their access rights. Please consult
681 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200682
683stats timeout <timeout, in milliseconds>
684 The default timeout on the stats socket is set to 10 seconds. It is possible
685 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100686 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200687
688stats maxconn <connections>
689 By default, the stats socket is limited to 10 concurrent connections. It is
690 possible to change this value with "stats maxconn".
691
Willy Tarreau6a06a402007-07-15 20:15:28 +0200692uid <number>
693 Changes the process' user ID to <number>. It is recommended that the user ID
694 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
695 be started with superuser privileges in order to be able to switch to another
696 one. See also "gid" and "user".
697
698ulimit-n <number>
699 Sets the maximum number of per-process file-descriptors to <number>. By
700 default, it is automatically computed, so it is recommended not to use this
701 option.
702
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100703unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
704 [ group <group> ] [ gid <gid> ]
705
706 Fixes common settings to UNIX listening sockets declared in "bind" statements.
707 This is mainly used to simplify declaration of those UNIX sockets and reduce
708 the risk of errors, since those settings are most commonly required but are
709 also process-specific. The <prefix> setting can be used to force all socket
710 path to be relative to that directory. This might be needed to access another
711 component's chroot. Note that those paths are resolved before haproxy chroots
712 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
713 all have the same meaning as their homonyms used by the "bind" statement. If
714 both are specified, the "bind" statement has priority, meaning that the
715 "unix-bind" settings may be seen as process-wide default settings.
716
Willy Tarreau6a06a402007-07-15 20:15:28 +0200717user <user name>
718 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
719 See also "uid" and "group".
720
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200721node <name>
722 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
723
724 This statement is useful in HA configurations where two or more processes or
725 servers share the same IP address. By setting a different node-name on all
726 nodes, it becomes easy to immediately spot what server is handling the
727 traffic.
728
729description <text>
730 Add a text that describes the instance.
731
732 Please note that it is required to escape certain characters (# for example)
733 and this text is inserted into a html page so you should avoid using
734 "<" and ">" characters.
735
Willy Tarreau6a06a402007-07-15 20:15:28 +0200736
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007373.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200738-----------------------
739
Willy Tarreau1746eec2014-04-25 10:46:47 +0200740max-spread-checks <delay in milliseconds>
741 By default, haproxy tries to spread the start of health checks across the
742 smallest health check interval of all the servers in a farm. The principle is
743 to avoid hammering services running on the same server. But when using large
744 check intervals (10 seconds or more), the last servers in the farm take some
745 time before starting to be tested, which can be a problem. This parameter is
746 used to enforce an upper bound on delay between the first and the last check,
747 even if the servers' check intervals are larger. When servers run with
748 shorter intervals, their intervals will be respected though.
749
Willy Tarreau6a06a402007-07-15 20:15:28 +0200750maxconn <number>
751 Sets the maximum per-process number of concurrent connections to <number>. It
752 is equivalent to the command-line argument "-n". Proxies will stop accepting
753 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +0200754 automatically adjusted according to this value. See also "ulimit-n". Note:
755 the "select" poller cannot reliably use more than 1024 file descriptors on
756 some platforms. If your platform only supports select and reports "select
757 FAILED" on startup, you need to reduce maxconn until it works (slightly
758 below 500 in general).
Willy Tarreau6a06a402007-07-15 20:15:28 +0200759
Willy Tarreau81c25d02011-09-07 15:17:21 +0200760maxconnrate <number>
761 Sets the maximum per-process number of connections per second to <number>.
762 Proxies will stop accepting connections when this limit is reached. It can be
763 used to limit the global capacity regardless of each frontend capacity. It is
764 important to note that this can only be used as a service protection measure,
765 as there will not necessarily be a fair share between frontends when the
766 limit is reached, so it's a good idea to also limit each frontend to some
767 value close to its expected share. Also, lowering tune.maxaccept can improve
768 fairness.
769
William Lallemandd85f9172012-11-09 17:05:39 +0100770maxcomprate <number>
771 Sets the maximum per-process input compression rate to <number> kilobytes
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300772 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +0100773 level will be decreased during the session. If the maximum is reached at the
774 beginning of a session, the session will not compress at all. If the maximum
775 is not reached, the compression level will be increased up to
776 tune.comp.maxlevel. A value of zero means there is no limit, this is the
777 default value.
778
William Lallemand072a2bf2012-11-20 17:01:01 +0100779maxcompcpuusage <number>
780 Sets the maximum CPU usage HAProxy can reach before stopping the compression
781 for new requests or decreasing the compression level of current requests.
782 It works like 'maxcomprate' but measures CPU usage instead of incoming data
783 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
784 case of multiple processes (nbproc > 1), each process manages its individual
785 usage. A value of 100 disable the limit. The default value is 100. Setting
786 a lower value will prevent the compression work from slowing the whole
787 process down and from introducing high latencies.
788
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100789maxpipes <number>
790 Sets the maximum per-process number of pipes to <number>. Currently, pipes
791 are only used by kernel-based tcp splicing. Since a pipe contains two file
792 descriptors, the "ulimit-n" value will be increased accordingly. The default
793 value is maxconn/4, which seems to be more than enough for most heavy usages.
794 The splice code dynamically allocates and releases pipes, and can fall back
795 to standard copy, so setting this value too low may only impact performance.
796
Willy Tarreau93e7c002013-10-07 18:51:07 +0200797maxsessrate <number>
798 Sets the maximum per-process number of sessions per second to <number>.
799 Proxies will stop accepting connections when this limit is reached. It can be
800 used to limit the global capacity regardless of each frontend capacity. It is
801 important to note that this can only be used as a service protection measure,
802 as there will not necessarily be a fair share between frontends when the
803 limit is reached, so it's a good idea to also limit each frontend to some
804 value close to its expected share. Also, lowering tune.maxaccept can improve
805 fairness.
806
Willy Tarreau403edff2012-09-06 11:58:37 +0200807maxsslconn <number>
808 Sets the maximum per-process number of concurrent SSL connections to
809 <number>. By default there is no SSL-specific limit, which means that the
810 global maxconn setting will apply to all connections. Setting this limit
811 avoids having openssl use too much memory and crash when malloc returns NULL
812 (since it unfortunately does not reliably check for such conditions). Note
813 that the limit applies both to incoming and outgoing connections, so one
814 connection which is deciphered then ciphered accounts for 2 SSL connections.
815
Willy Tarreaue43d5322013-10-07 20:01:52 +0200816maxsslrate <number>
817 Sets the maximum per-process number of SSL sessions per second to <number>.
818 SSL listeners will stop accepting connections when this limit is reached. It
819 can be used to limit the global SSL CPU usage regardless of each frontend
820 capacity. It is important to note that this can only be used as a service
821 protection measure, as there will not necessarily be a fair share between
822 frontends when the limit is reached, so it's a good idea to also limit each
823 frontend to some value close to its expected share. It is also important to
824 note that the sessions are accounted before they enter the SSL stack and not
825 after, which also protects the stack against bad handshakes. Also, lowering
826 tune.maxaccept can improve fairness.
827
William Lallemand9d5f5482012-11-07 16:12:57 +0100828maxzlibmem <number>
829 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
830 When the maximum amount is reached, future sessions will not compress as long
831 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +0100832 The default value is 0. The value is available in bytes on the UNIX socket
833 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
834 "ZlibMemUsage" in bytes.
835
Willy Tarreau6a06a402007-07-15 20:15:28 +0200836noepoll
837 Disables the use of the "epoll" event polling system on Linux. It is
838 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100839 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200840
841nokqueue
842 Disables the use of the "kqueue" event polling system on BSD. It is
843 equivalent to the command-line argument "-dk". The next polling system
844 used will generally be "poll". See also "nopoll".
845
846nopoll
847 Disables the use of the "poll" event polling system. It is equivalent to the
848 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100849 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100850 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200851
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100852nosplice
853 Disables the use of kernel tcp splicing between sockets on Linux. It is
854 equivalent to the command line argument "-dS". Data will then be copied
855 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100856 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100857 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
858 be used. This option makes it easier to globally disable kernel splicing in
859 case of doubt. See also "option splice-auto", "option splice-request" and
860 "option splice-response".
861
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300862nogetaddrinfo
863 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
864 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
865
Willy Tarreaufe255b72007-10-14 23:09:26 +0200866spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +0900867 Sometimes it is desirable to avoid sending agent and health checks to
868 servers at exact intervals, for instance when many logical servers are
869 located on the same physical server. With the help of this parameter, it
870 becomes possible to add some randomness in the check interval between 0
871 and +/- 50%. A value between 2 and 5 seems to show good results. The
872 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +0200873
Willy Tarreau27a674e2009-08-17 07:23:33 +0200874tune.bufsize <number>
875 Sets the buffer size to this size (in bytes). Lower values allow more
876 sessions to coexist in the same amount of RAM, and higher values allow some
877 applications with very large cookies to work. The default value is 16384 and
878 can be changed at build time. It is strongly recommended not to change this
879 from the default value, as very low values will break some services such as
880 statistics, and values larger than default size will increase memory usage,
881 possibly causing the system to run out of memory. At least the global maxconn
882 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +0400883 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
884 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
885 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +0200886
Willy Tarreau43961d52010-10-04 20:39:20 +0200887tune.chksize <number>
888 Sets the check buffer size to this size (in bytes). Higher values may help
889 find string or regex patterns in very large pages, though doing so may imply
890 more memory and CPU usage. The default value is 16384 and can be changed at
891 build time. It is not recommended to change this value, but to use better
892 checks whenever possible.
893
William Lallemandf3747832012-11-09 12:33:10 +0100894tune.comp.maxlevel <number>
895 Sets the maximum compression level. The compression level affects CPU
896 usage during compression. This value affects CPU usage during compression.
897 Each session using compression initializes the compression algorithm with
898 this value. The default value is 1.
899
Willy Tarreau193b8c62012-11-22 00:17:38 +0100900tune.http.cookielen <number>
901 Sets the maximum length of captured cookies. This is the maximum value that
902 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
903 will automatically be truncated to this one. It is important not to set too
904 high a value because all cookie captures still allocate this size whatever
905 their configured value (they share a same pool). This value is per request
906 per response, so the memory allocated is twice this value per connection.
907 When not specified, the limit is set to 63 characters. It is recommended not
908 to change this value.
909
Willy Tarreauac1932d2011-10-24 19:14:41 +0200910tune.http.maxhdr <number>
911 Sets the maximum number of headers in a request. When a request comes with a
912 number of headers greater than this value (including the first line), it is
913 rejected with a "400 Bad Request" status code. Similarly, too large responses
914 are blocked with "502 Bad Gateway". The default value is 101, which is enough
915 for all usages, considering that the widely deployed Apache server uses the
916 same limit. It can be useful to push this limit further to temporarily allow
917 a buggy application to work by the time it gets fixed. Keep in mind that each
918 new header consumes 32bits of memory for each session, so don't push this
919 limit too high.
920
Willy Tarreau7e312732014-02-12 16:35:14 +0100921tune.idletimer <timeout>
922 Sets the duration after which haproxy will consider that an empty buffer is
923 probably associated with an idle stream. This is used to optimally adjust
924 some packet sizes while forwarding large and small data alternatively. The
925 decision to use splice() or to send large buffers in SSL is modulated by this
926 parameter. The value is in milliseconds between 0 and 65535. A value of zero
927 means that haproxy will not try to detect idle streams. The default is 1000,
928 which seems to correctly detect end user pauses (eg: read a page before
929 clicking). There should be not reason for changing this value. Please check
930 tune.ssl.maxrecord below.
931
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100932tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +0100933 Sets the maximum number of consecutive connections a process may accept in a
934 row before switching to other work. In single process mode, higher numbers
935 give better performance at high connection rates. However in multi-process
936 modes, keeping a bit of fairness between processes generally is better to
937 increase performance. This value applies individually to each listener, so
938 that the number of processes a listener is bound to is taken into account.
939 This value defaults to 64. In multi-process mode, it is divided by twice
940 the number of processes the listener is bound to. Setting this value to -1
941 completely disables the limitation. It should normally not be needed to tweak
942 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100943
944tune.maxpollevents <number>
945 Sets the maximum amount of events that can be processed at once in a call to
946 the polling system. The default value is adapted to the operating system. It
947 has been noticed that reducing it below 200 tends to slightly decrease
948 latency at the expense of network bandwidth, and increasing it above 200
949 tends to trade latency for slightly increased bandwidth.
950
Willy Tarreau27a674e2009-08-17 07:23:33 +0200951tune.maxrewrite <number>
952 Sets the reserved buffer space to this size in bytes. The reserved space is
953 used for header rewriting or appending. The first reads on sockets will never
954 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
955 bufsize, though that does not make much sense since there are rarely large
956 numbers of headers to add. Setting it too high prevents processing of large
957 requests or responses. Setting it too low prevents addition of new headers
958 to already large requests or to POST requests. It is generally wise to set it
959 to about 1024. It is automatically readjusted to half of bufsize if it is
960 larger than that. This means you don't have to worry about it when changing
961 bufsize.
962
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200963tune.pipesize <number>
964 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
965 are the default size for the system. But sometimes when using TCP splicing,
966 it can improve performance to increase pipe sizes, especially if it is
967 suspected that pipes are not filled and that many calls to splice() are
968 performed. This has an impact on the kernel's memory footprint, so this must
969 not be changed if impacts are not understood.
970
Willy Tarreaue803de22010-01-21 17:43:04 +0100971tune.rcvbuf.client <number>
972tune.rcvbuf.server <number>
973 Forces the kernel socket receive buffer size on the client or the server side
974 to the specified value in bytes. This value applies to all TCP/HTTP frontends
975 and backends. It should normally never be set, and the default size (0) lets
976 the kernel autotune this value depending on the amount of available memory.
977 However it can sometimes help to set it to very low values (eg: 4096) in
978 order to save kernel memory by preventing it from buffering too large amounts
979 of received data. Lower values will significantly increase CPU usage though.
980
981tune.sndbuf.client <number>
982tune.sndbuf.server <number>
983 Forces the kernel socket send buffer size on the client or the server side to
984 the specified value in bytes. This value applies to all TCP/HTTP frontends
985 and backends. It should normally never be set, and the default size (0) lets
986 the kernel autotune this value depending on the amount of available memory.
987 However it can sometimes help to set it to very low values (eg: 4096) in
988 order to save kernel memory by preventing it from buffering too large amounts
989 of received data. Lower values will significantly increase CPU usage though.
990 Another use case is to prevent write timeouts with extremely slow clients due
991 to the kernel waiting for a large part of the buffer to be read before
992 notifying haproxy again.
993
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100994tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +0100995 Sets the size of the global SSL session cache, in a number of blocks. A block
996 is large enough to contain an encoded session without peer certificate.
997 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300998 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +0100999 200 bytes of memory. The default value may be forced at build time, otherwise
1000 defaults to 20000. When the cache is full, the most idle entries are purged
1001 and reassigned. Higher values reduce the occurrence of such a purge, hence
1002 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1003 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001004 and are shared between all processes if "nbproc" is greater than 1. Setting
1005 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001006
Emeric Brun8dc60392014-05-09 13:52:00 +02001007tune.ssl.force-private-cache
1008 This boolean disables SSL session cache sharing between all processes. It
1009 should normally not be used since it will force many renegotiations due to
1010 clients hitting a random process. But it may be required on some operating
1011 systems where none of the SSL cache synchronization method may be used. In
1012 this case, adding a first layer of hash-based load balancing before the SSL
1013 layer might limit the impact of the lack of session sharing.
1014
Emeric Brun4f65bff2012-11-16 15:11:00 +01001015tune.ssl.lifetime <timeout>
1016 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001017 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001018 does not guarantee that sessions will last that long, because if the cache is
1019 full, the longest idle sessions will be purged despite their configured
1020 lifetime. The real usefulness of this setting is to prevent sessions from
1021 being used for too long.
1022
Willy Tarreaubfd59462013-02-21 07:46:09 +01001023tune.ssl.maxrecord <number>
1024 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
1025 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
1026 data only once it has received a full record. With large records, it means
1027 that clients might have to download up to 16kB of data before starting to
1028 process them. Limiting the value can improve page load times on browsers
1029 located over high latency or low bandwidth networks. It is suggested to find
1030 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
1031 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
1032 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
1033 2859 gave good results during tests. Use "strace -e trace=write" to find the
Willy Tarreau7e312732014-02-12 16:35:14 +01001034 best value. Haproxy will automatically switch to this setting after an idle
1035 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01001036
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001037tune.ssl.default-dh-param <number>
1038 Sets the maximum size of the Diffie-Hellman parameters used for generating
1039 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
1040 final size will try to match the size of the server's RSA (or DSA) key (e.g,
1041 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
1042 this maximum value. Default value if 1024. Only 1024 or higher values are
1043 allowed. Higher values will increase the CPU load, and values greater than
1044 1024 bits are not supported by Java 7 and earlier clients. This value is not
1045 used if static Diffie-Hellman parameters are supplied via the certificate file.
1046
William Lallemanda509e4c2012-11-07 16:54:34 +01001047tune.zlib.memlevel <number>
1048 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001049 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01001050 state. A value of 1 uses minimum memory but is slow and reduces compression
1051 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
1052 between 1 and 9. The default value is 8.
1053
1054tune.zlib.windowsize <number>
1055 Sets the window size (the size of the history buffer) as a parameter of the
1056 zlib initialization for each session. Larger values of this parameter result
1057 in better compression at the expense of memory usage. Can be a value between
1058 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001059
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010603.3. Debugging
1061--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02001062
1063debug
1064 Enables debug mode which dumps to stdout all exchanges, and disables forking
1065 into background. It is the equivalent of the command-line argument "-d". It
1066 should never be used in a production configuration since it may prevent full
1067 system startup.
1068
1069quiet
1070 Do not display any message during startup. It is equivalent to the command-
1071 line argument "-q".
1072
Emeric Brunf099e792010-09-27 12:05:28 +02001073
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010010743.4. Userlists
1075--------------
1076It is possible to control access to frontend/backend/listen sections or to
1077http stats by allowing only authenticated and authorized users. To do this,
1078it is required to create at least one userlist and to define users.
1079
1080userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01001081 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001082 used to store authentication & authorization data for independent customers.
1083
1084group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01001085 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001086 attach users to this group by using a comma separated list of names
1087 proceeded by "users" keyword.
1088
Cyril Bontéf0c60612010-02-06 14:44:47 +01001089user <username> [password|insecure-password <password>]
1090 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001091 Adds user <username> to the current userlist. Both secure (encrypted) and
1092 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +01001093 evaluated using the crypt(3) function so depending of the system's
1094 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001095 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001096 DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001097
1098
1099 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01001100 userlist L1
1101 group G1 users tiger,scott
1102 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001103
Cyril Bontéf0c60612010-02-06 14:44:47 +01001104 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
1105 user scott insecure-password elgato
1106 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001107
Cyril Bontéf0c60612010-02-06 14:44:47 +01001108 userlist L2
1109 group G1
1110 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001111
Cyril Bontéf0c60612010-02-06 14:44:47 +01001112 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
1113 user scott insecure-password elgato groups G1,G2
1114 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001115
1116 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001117
Emeric Brunf099e792010-09-27 12:05:28 +02001118
11193.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02001120----------
Emeric Brunf099e792010-09-27 12:05:28 +02001121It is possible to synchronize server entries in stick tables between several
1122haproxy instances over TCP connections in a multi-master fashion. Each instance
1123pushes its local updates and insertions to remote peers. Server IDs are used to
1124identify servers remotely, so it is important that configurations look similar
1125or at least that the same IDs are forced on each server on all participants.
1126Interrupted exchanges are automatically detected and recovered from the last
1127known point. In addition, during a soft restart, the old process connects to
1128the new one using such a TCP connection to push all its entries before the new
1129process tries to connect to other peers. That ensures very fast replication
1130during a reload, it typically takes a fraction of a second even for large
1131tables.
1132
1133peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001134 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001135 which is referenced by one or more stick-tables.
1136
1137peer <peername> <ip>:<port>
1138 Defines a peer inside a peers section.
1139 If <peername> is set to the local peer name (by default hostname, or forced
1140 using "-L" command line option), haproxy will listen for incoming remote peer
1141 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1142 to join the remote peer, and <peername> is used at the protocol level to
1143 identify and validate the remote peer on the server side.
1144
1145 During a soft restart, local peer <ip>:<port> is used by the old instance to
1146 connect the new one and initiate a complete replication (teaching process).
1147
1148 It is strongly recommended to have the exact same peers declaration on all
1149 peers and to only rely on the "-L" command line argument to change the local
1150 peer name. This makes it easier to maintain coherent configuration files
1151 across all peers.
1152
Willy Tarreaudad36a32013-03-11 01:20:04 +01001153 Any part of the address string may reference any number of environment
1154 variables by preceding their name with a dollar sign ('$') and optionally
1155 enclosing them with braces ('{}'), similarly to what is done in Bourne shell.
1156
Cyril Bontédc4d9032012-04-08 21:57:39 +02001157 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001158 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001159 peer haproxy1 192.168.0.1:1024
1160 peer haproxy2 192.168.0.2:1024
1161 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001162
1163 backend mybackend
1164 mode tcp
1165 balance roundrobin
1166 stick-table type ip size 20k peers mypeers
1167 stick on src
1168
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001169 server srv1 192.168.0.30:80
1170 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001171
1172
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011734. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001174----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001175
Willy Tarreau6a06a402007-07-15 20:15:28 +02001176Proxy configuration can be located in a set of sections :
1177 - defaults <name>
1178 - frontend <name>
1179 - backend <name>
1180 - listen <name>
1181
1182A "defaults" section sets default parameters for all other sections following
1183its declaration. Those default parameters are reset by the next "defaults"
1184section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001185section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001186
1187A "frontend" section describes a set of listening sockets accepting client
1188connections.
1189
1190A "backend" section describes a set of servers to which the proxy will connect
1191to forward incoming connections.
1192
1193A "listen" section defines a complete proxy with its frontend and backend
1194parts combined in one section. It is generally useful for TCP-only traffic.
1195
Willy Tarreau0ba27502007-12-24 16:55:16 +01001196All proxy names must be formed from upper and lower case letters, digits,
1197'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1198case-sensitive, which means that "www" and "WWW" are two different proxies.
1199
1200Historically, all proxy names could overlap, it just caused troubles in the
1201logs. Since the introduction of content switching, it is mandatory that two
1202proxies with overlapping capabilities (frontend/backend) have different names.
1203However, it is still permitted that a frontend and a backend share the same
1204name, as this configuration seems to be commonly encountered.
1205
1206Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1207and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001208bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001209protocol, and can interact with it by allowing, blocking, switching, adding,
1210modifying, or removing arbitrary contents in requests or responses, based on
1211arbitrary criteria.
1212
Willy Tarreau70dffda2014-01-30 03:07:23 +01001213In HTTP mode, the processing applied to requests and responses flowing over
1214a connection depends in the combination of the frontend's HTTP options and
1215the backend's. HAProxy supports 5 connection modes :
1216
1217 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
1218 requests and responses are processed, and connections remain open but idle
1219 between responses and new requests.
1220
1221 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
1222 1.0 to 1.5-dev21 : only the first request and response are processed, and
1223 everything else is forwarded with no analysis at all. This mode should not
1224 be used as it creates lots of trouble with logging and HTTP processing.
1225
1226 - PCL: passive close ("option httpclose") : exactly the same as tunnel mode,
1227 but with "Connection: close" appended in both directions to try to make
1228 both ends close after the first request/response exchange.
1229
1230 - SCL: server close ("option http-server-close") : the server-facing
1231 connection is closed after the end of the response is received, but the
1232 client-facing connection remains open.
1233
1234 - FCL: forced close ("option forceclose") : the connection is actively closed
1235 after the end of the response.
1236
1237The effective mode that will be applied to a connection passing through a
1238frontend and a backend can be determined by both proxy modes according to the
1239following matrix, but in short, the modes are symmetric, keep-alive is the
1240weakest option and force close is the strongest.
1241
1242 Backend mode
1243
1244 | KAL | TUN | PCL | SCL | FCL
1245 ----+-----+-----+-----+-----+----
1246 KAL | KAL | TUN | PCL | SCL | FCL
1247 ----+-----+-----+-----+-----+----
1248 TUN | TUN | TUN | PCL | SCL | FCL
1249 Frontend ----+-----+-----+-----+-----+----
1250 mode PCL | PCL | PCL | PCL | FCL | FCL
1251 ----+-----+-----+-----+-----+----
1252 SCL | SCL | SCL | FCL | SCL | FCL
1253 ----+-----+-----+-----+-----+----
1254 FCL | FCL | FCL | FCL | FCL | FCL
1255
Willy Tarreau0ba27502007-12-24 16:55:16 +01001256
Willy Tarreau70dffda2014-01-30 03:07:23 +01001257
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012584.1. Proxy keywords matrix
1259--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001260
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001261The following list of keywords is supported. Most of them may only be used in a
1262limited set of section types. Some of them are marked as "deprecated" because
1263they are inherited from an old syntax which may be confusing or functionally
1264limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001265marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001266option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001267and must be disabled for a specific instance. Such options may also be prefixed
1268with "default" in order to restore default settings regardless of what has been
1269specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001270
Willy Tarreau6a06a402007-07-15 20:15:28 +02001271
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001272 keyword defaults frontend listen backend
1273------------------------------------+----------+----------+---------+---------
1274acl - X X X
1275appsession - - X X
1276backlog X X X -
1277balance X - X X
1278bind - X X -
1279bind-process X X X X
1280block - X X X
1281capture cookie - X X -
1282capture request header - X X -
1283capture response header - X X -
1284clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001285compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001286contimeout (deprecated) X - X X
1287cookie X - X X
1288default-server X - X X
1289default_backend X X X -
1290description - X X X
1291disabled X X X X
1292dispatch - - X X
1293enabled X X X X
1294errorfile X X X X
1295errorloc X X X X
1296errorloc302 X X X X
1297-- keyword -------------------------- defaults - frontend - listen -- backend -
1298errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001299force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001300fullconn X - X X
1301grace X X X X
1302hash-type X - X X
1303http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001304http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001305http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001306http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02001307http-response - X X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02001308http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001309id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001310ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001311log (*) X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02001312max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001313maxconn X X X -
1314mode X X X X
1315monitor fail - X X -
1316monitor-net X X X -
1317monitor-uri X X X -
1318option abortonclose (*) X - X X
1319option accept-invalid-http-request (*) X X X -
1320option accept-invalid-http-response (*) X - X X
1321option allbackups (*) X - X X
1322option checkcache (*) X - X X
1323option clitcpka (*) X X X -
1324option contstats (*) X X X -
1325option dontlog-normal (*) X X X -
1326option dontlognull (*) X X X -
1327option forceclose (*) X X X X
1328-- keyword -------------------------- defaults - frontend - listen -- backend -
1329option forwardfor X X X X
Willy Tarreau16bfb022010-01-16 19:48:41 +01001330option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001331option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001332option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001333option http-server-close (*) X X X X
Willy Tarreau02bce8b2014-01-30 00:15:28 +01001334option http-tunnel (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001335option http-use-proxy-header (*) X X X -
1336option httpchk X - X X
1337option httpclose (*) X X X X
1338option httplog X X X X
1339option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001340option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001341option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001342option log-health-checks (*) X - X X
1343option log-separate-errors (*) X X X -
1344option logasap (*) X X X -
1345option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001346option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001347option nolinger (*) X X X X
1348option originalto X X X X
1349option persist (*) X - X X
1350option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001351option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001352option smtpchk X - X X
1353option socket-stats (*) X X X -
1354option splice-auto (*) X X X X
1355option splice-request (*) X X X X
1356option splice-response (*) X X X X
1357option srvtcpka (*) X - X X
1358option ssl-hello-chk X - X X
1359-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01001360option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001361option tcp-smart-accept (*) X X X -
1362option tcp-smart-connect (*) X - X X
1363option tcpka X X X X
1364option tcplog X X X X
1365option transparent (*) X - X X
1366persist rdp-cookie X - X X
1367rate-limit sessions X X X -
1368redirect - X X X
1369redisp (deprecated) X - X X
1370redispatch (deprecated) X - X X
1371reqadd - X X X
1372reqallow - X X X
1373reqdel - X X X
1374reqdeny - X X X
1375reqiallow - X X X
1376reqidel - X X X
1377reqideny - X X X
1378reqipass - X X X
1379reqirep - X X X
1380reqisetbe - X X X
1381reqitarpit - X X X
1382reqpass - X X X
1383reqrep - X X X
1384-- keyword -------------------------- defaults - frontend - listen -- backend -
1385reqsetbe - X X X
1386reqtarpit - X X X
1387retries X - X X
1388rspadd - X X X
1389rspdel - X X X
1390rspdeny - X X X
1391rspidel - X X X
1392rspideny - X X X
1393rspirep - X X X
1394rsprep - X X X
1395server - - X X
1396source X - X X
1397srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001398stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001399stats auth X - X X
1400stats enable X - X X
1401stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001402stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001403stats realm X - X X
1404stats refresh X - X X
1405stats scope X - X X
1406stats show-desc X - X X
1407stats show-legends X - X X
1408stats show-node X - X X
1409stats uri X - X X
1410-- keyword -------------------------- defaults - frontend - listen -- backend -
1411stick match - - X X
1412stick on - - X X
1413stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001414stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001415stick-table - - X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02001416tcp-check connect - - X X
1417tcp-check expect - - X X
1418tcp-check send - - X X
1419tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001420tcp-request connection - X X -
1421tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001422tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001423tcp-response content - - X X
1424tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001425timeout check X - X X
1426timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02001427timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001428timeout clitimeout (deprecated) X X X -
1429timeout connect X - X X
1430timeout contimeout (deprecated) X - X X
1431timeout http-keep-alive X X X X
1432timeout http-request X X X X
1433timeout queue X - X X
1434timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02001435timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001436timeout srvtimeout (deprecated) X - X X
1437timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001438timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001439transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001440unique-id-format X X X -
1441unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001442use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001443use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001444------------------------------------+----------+----------+---------+---------
1445 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001446
Willy Tarreau0ba27502007-12-24 16:55:16 +01001447
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014484.2. Alphabetically sorted keywords reference
1449---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001450
1451This section provides a description of each keyword and its usage.
1452
1453
1454acl <aclname> <criterion> [flags] [operator] <value> ...
1455 Declare or complete an access list.
1456 May be used in sections : defaults | frontend | listen | backend
1457 no | yes | yes | yes
1458 Example:
1459 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1460 acl invalid_src src_port 0:1023
1461 acl local_dst hdr(host) -i localhost
1462
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001463 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001464
1465
Cyril Bontéb21570a2009-11-29 20:04:48 +01001466appsession <cookie> len <length> timeout <holdtime>
1467 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001468 Define session stickiness on an existing application cookie.
1469 May be used in sections : defaults | frontend | listen | backend
1470 no | no | yes | yes
1471 Arguments :
1472 <cookie> this is the name of the cookie used by the application and which
1473 HAProxy will have to learn for each new session.
1474
Cyril Bontéb21570a2009-11-29 20:04:48 +01001475 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001476 checked in each cookie value.
1477
1478 <holdtime> this is the time after which the cookie will be removed from
1479 memory if unused. If no unit is specified, this time is in
1480 milliseconds.
1481
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001482 request-learn
1483 If this option is specified, then haproxy will be able to learn
1484 the cookie found in the request in case the server does not
1485 specify any in response. This is typically what happens with
1486 PHPSESSID cookies, or when haproxy's session expires before
1487 the application's session and the correct server is selected.
1488 It is recommended to specify this option to improve reliability.
1489
Cyril Bontéb21570a2009-11-29 20:04:48 +01001490 prefix When this option is specified, haproxy will match on the cookie
1491 prefix (or URL parameter prefix). The appsession value is the
1492 data following this prefix.
1493
1494 Example :
1495 appsession ASPSESSIONID len 64 timeout 3h prefix
1496
1497 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1498 the appsession value will be XXXX=XXXXX.
1499
1500 mode This option allows to change the URL parser mode.
1501 2 modes are currently supported :
1502 - path-parameters :
1503 The parser looks for the appsession in the path parameters
1504 part (each parameter is separated by a semi-colon), which is
1505 convenient for JSESSIONID for example.
1506 This is the default mode if the option is not set.
1507 - query-string :
1508 In this mode, the parser will look for the appsession in the
1509 query string.
1510
Willy Tarreau0ba27502007-12-24 16:55:16 +01001511 When an application cookie is defined in a backend, HAProxy will check when
1512 the server sets such a cookie, and will store its value in a table, and
1513 associate it with the server's identifier. Up to <length> characters from
1514 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001515 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1516 the mode used). If a known value is found, the client will be directed to the
1517 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001518 applied. Cookies are automatically removed from memory when they have been
1519 unused for a duration longer than <holdtime>.
1520
1521 The definition of an application cookie is limited to one per backend.
1522
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001523 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1524 unless you know what you do : memory is not shared between the
1525 processes, which can result in random behaviours.
1526
Willy Tarreau0ba27502007-12-24 16:55:16 +01001527 Example :
1528 appsession JSESSIONID len 52 timeout 3h
1529
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001530 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1531 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001532
1533
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001534backlog <conns>
1535 Give hints to the system about the approximate listen backlog desired size
1536 May be used in sections : defaults | frontend | listen | backend
1537 yes | yes | yes | no
1538 Arguments :
1539 <conns> is the number of pending connections. Depending on the operating
1540 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001541 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001542
1543 In order to protect against SYN flood attacks, one solution is to increase
1544 the system's SYN backlog size. Depending on the system, sometimes it is just
1545 tunable via a system parameter, sometimes it is not adjustable at all, and
1546 sometimes the system relies on hints given by the application at the time of
1547 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1548 to the listen() syscall. On systems which can make use of this value, it can
1549 sometimes be useful to be able to specify a different value, hence this
1550 backlog parameter.
1551
1552 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1553 used as a hint and the system accepts up to the smallest greater power of
1554 two, and never more than some limits (usually 32768).
1555
1556 See also : "maxconn" and the target operating system's tuning guide.
1557
1558
Willy Tarreau0ba27502007-12-24 16:55:16 +01001559balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02001560balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001561 Define the load balancing algorithm to be used in a backend.
1562 May be used in sections : defaults | frontend | listen | backend
1563 yes | no | yes | yes
1564 Arguments :
1565 <algorithm> is the algorithm used to select a server when doing load
1566 balancing. This only applies when no persistence information
1567 is available, or when a connection is redispatched to another
1568 server. <algorithm> may be one of the following :
1569
1570 roundrobin Each server is used in turns, according to their weights.
1571 This is the smoothest and fairest algorithm when the server's
1572 processing time remains equally distributed. This algorithm
1573 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001574 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08001575 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02001576 large farms, when a server becomes up after having been down
1577 for a very short time, it may sometimes take a few hundreds
1578 requests for it to be re-integrated into the farm and start
1579 receiving traffic. This is normal, though very rare. It is
1580 indicated here in case you would have the chance to observe
1581 it, so that you don't worry.
1582
1583 static-rr Each server is used in turns, according to their weights.
1584 This algorithm is as similar to roundrobin except that it is
1585 static, which means that changing a server's weight on the
1586 fly will have no effect. On the other hand, it has no design
1587 limitation on the number of servers, and when a server goes
1588 up, it is always immediately reintroduced into the farm, once
1589 the full map is recomputed. It also uses slightly less CPU to
1590 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001591
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001592 leastconn The server with the lowest number of connections receives the
1593 connection. Round-robin is performed within groups of servers
1594 of the same load to ensure that all servers will be used. Use
1595 of this algorithm is recommended where very long sessions are
1596 expected, such as LDAP, SQL, TSE, etc... but is not very well
1597 suited for protocols using short sessions such as HTTP. This
1598 algorithm is dynamic, which means that server weights may be
1599 adjusted on the fly for slow starts for instance.
1600
Willy Tarreauf09c6602012-02-13 17:12:08 +01001601 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001602 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01001603 identifier to the highest (see server parameter "id"), which
1604 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001605 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001606 not make sense to use this algorithm without setting maxconn.
1607 The purpose of this algorithm is to always use the smallest
1608 number of servers so that extra servers can be powered off
1609 during non-intensive hours. This algorithm ignores the server
1610 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001611 or IMAP than HTTP, though it can be useful there too. In
1612 order to use this algorithm efficiently, it is recommended
1613 that a cloud controller regularly checks server usage to turn
1614 them off when unused, and regularly checks backend queue to
1615 turn new servers on when the queue inflates. Alternatively,
1616 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001617
Willy Tarreau0ba27502007-12-24 16:55:16 +01001618 source The source IP address is hashed and divided by the total
1619 weight of the running servers to designate which server will
1620 receive the request. This ensures that the same client IP
1621 address will always reach the same server as long as no
1622 server goes down or up. If the hash result changes due to the
1623 number of running servers changing, many clients will be
1624 directed to a different server. This algorithm is generally
1625 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001626 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001627 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001628 static by default, which means that changing a server's
1629 weight on the fly will have no effect, but this can be
1630 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001631
Oskar Stolc8dc41842012-05-19 10:19:54 +01001632 uri This algorithm hashes either the left part of the URI (before
1633 the question mark) or the whole URI (if the "whole" parameter
1634 is present) and divides the hash value by the total weight of
1635 the running servers. The result designates which server will
1636 receive the request. This ensures that the same URI will
1637 always be directed to the same server as long as no server
1638 goes up or down. This is used with proxy caches and
1639 anti-virus proxies in order to maximize the cache hit rate.
1640 Note that this algorithm may only be used in an HTTP backend.
1641 This algorithm is static by default, which means that
1642 changing a server's weight on the fly will have no effect,
1643 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001644
Oskar Stolc8dc41842012-05-19 10:19:54 +01001645 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001646 "depth", both followed by a positive integer number. These
1647 options may be helpful when it is needed to balance servers
1648 based on the beginning of the URI only. The "len" parameter
1649 indicates that the algorithm should only consider that many
1650 characters at the beginning of the URI to compute the hash.
1651 Note that having "len" set to 1 rarely makes sense since most
1652 URIs start with a leading "/".
1653
1654 The "depth" parameter indicates the maximum directory depth
1655 to be used to compute the hash. One level is counted for each
1656 slash in the request. If both parameters are specified, the
1657 evaluation stops when either is reached.
1658
Willy Tarreau0ba27502007-12-24 16:55:16 +01001659 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001660 the query string of each HTTP GET request.
1661
1662 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001663 request entity will be searched for the parameter argument,
1664 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02001665 ('?') in the URL. The message body will only start to be
1666 analyzed once either the advertised amount of data has been
1667 received or the request buffer is full. In the unlikely event
1668 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02001669 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02001670 be randomly balanced if at all. This keyword used to support
1671 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001672
1673 If the parameter is found followed by an equal sign ('=') and
1674 a value, then the value is hashed and divided by the total
1675 weight of the running servers. The result designates which
1676 server will receive the request.
1677
1678 This is used to track user identifiers in requests and ensure
1679 that a same user ID will always be sent to the same server as
1680 long as no server goes up or down. If no value is found or if
1681 the parameter is not found, then a round robin algorithm is
1682 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001683 backend. This algorithm is static by default, which means
1684 that changing a server's weight on the fly will have no
1685 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001686
Cyril Bontédc4d9032012-04-08 21:57:39 +02001687 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1688 request. Just as with the equivalent ACL 'hdr()' function,
1689 the header name in parenthesis is not case sensitive. If the
1690 header is absent or if it does not contain any value, the
1691 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001692
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001693 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001694 reducing the hash algorithm to the main domain part with some
1695 specific headers such as 'Host'. For instance, in the Host
1696 value "haproxy.1wt.eu", only "1wt" will be considered.
1697
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001698 This algorithm is static by default, which means that
1699 changing a server's weight on the fly will have no effect,
1700 but this can be changed using "hash-type".
1701
Emeric Brun736aa232009-06-30 17:56:00 +02001702 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001703 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001704 The RDP cookie <name> (or "mstshash" if omitted) will be
1705 looked up and hashed for each incoming TCP request. Just as
1706 with the equivalent ACL 'req_rdp_cookie()' function, the name
1707 is not case-sensitive. This mechanism is useful as a degraded
1708 persistence mode, as it makes it possible to always send the
1709 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001710 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001711 used instead.
1712
1713 Note that for this to work, the frontend must ensure that an
1714 RDP cookie is already present in the request buffer. For this
1715 you must use 'tcp-request content accept' rule combined with
1716 a 'req_rdp_cookie_cnt' ACL.
1717
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001718 This algorithm is static by default, which means that
1719 changing a server's weight on the fly will have no effect,
1720 but this can be changed using "hash-type".
1721
Cyril Bontédc4d9032012-04-08 21:57:39 +02001722 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09001723
Willy Tarreau0ba27502007-12-24 16:55:16 +01001724 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001725 algorithms. Right now, only "url_param" and "uri" support an
1726 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001727
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001728 The load balancing algorithm of a backend is set to roundrobin when no other
1729 algorithm, mode nor option have been set. The algorithm may only be set once
1730 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001731
1732 Examples :
1733 balance roundrobin
1734 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001735 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001736 balance hdr(User-Agent)
1737 balance hdr(host)
1738 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001739
1740 Note: the following caveats and limitations on using the "check_post"
1741 extension with "url_param" must be considered :
1742
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001743 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001744 to determine if the parameters will be found in the body or entity which
1745 may contain binary data. Therefore another method may be required to
1746 restrict consideration of POST requests that have no URL parameters in
1747 the body. (see acl reqideny http_end)
1748
1749 - using a <max_wait> value larger than the request buffer size does not
1750 make sense and is useless. The buffer size is set at build time, and
1751 defaults to 16 kB.
1752
1753 - Content-Encoding is not supported, the parameter search will probably
1754 fail; and load balancing will fall back to Round Robin.
1755
1756 - Expect: 100-continue is not supported, load balancing will fall back to
1757 Round Robin.
1758
1759 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1760 If the entire parameter value is not present in the first chunk, the
1761 selection of server is undefined (actually, defined by how little
1762 actually appeared in the first chunk).
1763
1764 - This feature does not support generation of a 100, 411 or 501 response.
1765
1766 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001767 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001768 white space or control characters are found, indicating the end of what
1769 might be a URL parameter list. This is probably not a concern with SGML
1770 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001771
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001772 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1773 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001774
1775
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001776bind [<address>]:<port_range> [, ...] [param*]
1777bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001778 Define one or several listening addresses and/or ports in a frontend.
1779 May be used in sections : defaults | frontend | listen | backend
1780 no | yes | yes | no
1781 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001782 <address> is optional and can be a host name, an IPv4 address, an IPv6
1783 address, or '*'. It designates the address the frontend will
1784 listen on. If unset, all IPv4 addresses of the system will be
1785 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001786 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01001787 Optionally, an address family prefix may be used before the
1788 address to force the family regardless of the address format,
1789 which can be useful to specify a path to a unix socket with
1790 no slash ('/'). Currently supported prefixes are :
1791 - 'ipv4@' -> address is always IPv4
1792 - 'ipv6@' -> address is always IPv6
1793 - 'unix@' -> address is a path to a local unix socket
Willy Tarreaub4fca5d2014-07-08 00:37:50 +02001794 - 'abns@' -> address is in abstract namespace (Linux only).
1795 Note: since abstract sockets are not "rebindable", they
1796 do not cope well with multi-process mode during
1797 soft-restart, so it is better to avoid them if
1798 nbproc is greater than 1. The effect is that if the
1799 new process fails to start, only one of the old ones
1800 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01001801 - 'fd@<n>' -> use file descriptor <n> inherited from the
1802 parent. The fd must be bound and may or may not already
1803 be listening.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001804 Any part of the address string may reference any number of
1805 environment variables by preceding their name with a dollar
1806 sign ('$') and optionally enclosing them with braces ('{}'),
1807 similarly to what is done in Bourne shell.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001808
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001809 <port_range> is either a unique TCP port, or a port range for which the
1810 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001811 above. The port is mandatory for TCP listeners. Note that in
1812 the case of an IPv6 address, the port is always the number
1813 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001814 - a numerical port (ex: '80')
1815 - a dash-delimited ports range explicitly stating the lower
1816 and upper bounds (ex: '2000-2100') which are included in
1817 the range.
1818
1819 Particular care must be taken against port ranges, because
1820 every <address:port> couple consumes one socket (= a file
1821 descriptor), so it's easy to consume lots of descriptors
1822 with a simple range, and to run out of sockets. Also, each
1823 <address:port> couple must be used only once among all
1824 instances running on a same system. Please note that binding
1825 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001826 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001827 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001828
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001829 <path> is a UNIX socket path beginning with a slash ('/'). This is
1830 alternative to the TCP listening port. Haproxy will then
1831 receive UNIX connections on the socket located at this place.
1832 The path must begin with a slash and by default is absolute.
1833 It can be relative to the prefix defined by "unix-bind" in
1834 the global section. Note that the total length of the prefix
1835 followed by the socket path cannot exceed some system limits
1836 for UNIX sockets, which commonly are set to 107 characters.
1837
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001838 <param*> is a list of parameters common to all sockets declared on the
1839 same line. These numerous parameters depend on OS and build
1840 options and have a complete section dedicated to them. Please
1841 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001842
Willy Tarreau0ba27502007-12-24 16:55:16 +01001843 It is possible to specify a list of address:port combinations delimited by
1844 commas. The frontend will then listen on all of these addresses. There is no
1845 fixed limit to the number of addresses and ports which can be listened on in
1846 a frontend, as well as there is no limit to the number of "bind" statements
1847 in a frontend.
1848
1849 Example :
1850 listen http_proxy
1851 bind :80,:443
1852 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001853 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001854
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001855 listen http_https_proxy
1856 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02001857 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001858
Willy Tarreau24709282013-03-10 21:32:12 +01001859 listen http_https_proxy_explicit
1860 bind ipv6@:80
1861 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
1862 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
1863
Willy Tarreaudad36a32013-03-11 01:20:04 +01001864 listen external_bind_app1
1865 bind fd@${FD_APP1}
1866
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001867 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001868 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001869
1870
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001871bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001872 Limit visibility of an instance to a certain set of processes numbers.
1873 May be used in sections : defaults | frontend | listen | backend
1874 yes | yes | yes | yes
1875 Arguments :
1876 all All process will see this instance. This is the default. It
1877 may be used to override a default value.
1878
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001879 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001880 option may be combined with other numbers.
1881
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001882 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001883 option may be combined with other numbers. Do not use it
1884 with less than 2 processes otherwise some instances might be
1885 missing from all processes.
1886
Willy Tarreau110ecc12012-11-15 17:50:01 +01001887 number The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001888 whose values must all be between 1 and 32 or 64 depending on
Willy Tarreau102df612014-05-07 23:56:38 +02001889 the machine's word size. If a proxy is bound to process
1890 numbers greater than the configured global.nbproc, it will
1891 either be forced to process #1 if a single process was
1892 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001893
1894 This keyword limits binding of certain instances to certain processes. This
1895 is useful in order not to have too many processes listening to the same
1896 ports. For instance, on a dual-core machine, it might make sense to set
1897 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1898 and 'even' instances.
1899
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001900 At the moment, it is not possible to reference more than 32 or 64 processes
1901 using this keyword, but this should be more than enough for most setups.
1902 Please note that 'all' really means all processes regardless of the machine's
1903 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001904
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02001905 Each "bind" line may further be limited to a subset of the proxy's processes,
1906 please consult the "process" bind keyword in section 5.1.
1907
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001908 If some backends are referenced by frontends bound to other processes, the
1909 backend automatically inherits the frontend's processes.
1910
1911 Example :
1912 listen app_ip1
1913 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001914 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001915
1916 listen app_ip2
1917 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001918 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001919
1920 listen management
1921 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001922 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001923
Willy Tarreau110ecc12012-11-15 17:50:01 +01001924 listen management
1925 bind 10.0.0.4:80
1926 bind-process 1-4
1927
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02001928 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001929
1930
Willy Tarreau0ba27502007-12-24 16:55:16 +01001931block { if | unless } <condition>
1932 Block a layer 7 request if/unless a condition is matched
1933 May be used in sections : defaults | frontend | listen | backend
1934 no | yes | yes | yes
1935
1936 The HTTP request will be blocked very early in the layer 7 processing
1937 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001938 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001939 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001940 conditions are met or not met. There is no fixed limit to the number of
1941 "block" statements per instance.
1942
1943 Example:
1944 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1945 acl invalid_src src_port 0:1023
1946 acl local_dst hdr(host) -i localhost
1947 block if invalid_src || local_dst
1948
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001949 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001950
1951
1952capture cookie <name> len <length>
1953 Capture and log a cookie in the request and in the response.
1954 May be used in sections : defaults | frontend | listen | backend
1955 no | yes | yes | no
1956 Arguments :
1957 <name> is the beginning of the name of the cookie to capture. In order
1958 to match the exact name, simply suffix the name with an equal
1959 sign ('='). The full name will appear in the logs, which is
1960 useful with application servers which adjust both the cookie name
1961 and value (eg: ASPSESSIONXXXXX).
1962
1963 <length> is the maximum number of characters to report in the logs, which
1964 include the cookie name, the equal sign and the value, all in the
1965 standard "name=value" form. The string will be truncated on the
1966 right if it exceeds <length>.
1967
1968 Only the first cookie is captured. Both the "cookie" request headers and the
1969 "set-cookie" response headers are monitored. This is particularly useful to
1970 check for application bugs causing session crossing or stealing between
1971 users, because generally the user's cookies can only change on a login page.
1972
1973 When the cookie was not presented by the client, the associated log column
1974 will report "-". When a request does not cause a cookie to be assigned by the
1975 server, a "-" is reported in the response column.
1976
1977 The capture is performed in the frontend only because it is necessary that
1978 the log format does not change for a given frontend depending on the
1979 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01001980 "capture cookie" statement in a frontend. The maximum capture length is set
1981 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
1982 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001983
1984 Example:
1985 capture cookie ASPSESSION len 32
1986
1987 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001988 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001989
1990
1991capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001992 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001993 May be used in sections : defaults | frontend | listen | backend
1994 no | yes | yes | no
1995 Arguments :
1996 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001997 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001998 appear in the requests, with the first letter of each word in
1999 upper case. The header name will not appear in the logs, only the
2000 value is reported, but the position in the logs is respected.
2001
2002 <length> is the maximum number of characters to extract from the value and
2003 report in the logs. The string will be truncated on the right if
2004 it exceeds <length>.
2005
Willy Tarreau4460d032012-11-21 23:37:37 +01002006 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002007 value will be added to the logs between braces ('{}'). If multiple headers
2008 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002009 in the same order they were declared in the configuration. Non-existent
2010 headers will be logged just as an empty string. Common uses for request
2011 header captures include the "Host" field in virtual hosting environments, the
2012 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002013 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002014 environments to find where the request came from.
2015
2016 Note that when capturing headers such as "User-agent", some spaces may be
2017 logged, making the log analysis more difficult. Thus be careful about what
2018 you log if you know your log parser is not smart enough to rely on the
2019 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002020
Willy Tarreau0900abb2012-11-22 00:21:46 +01002021 There is no limit to the number of captured request headers nor to their
2022 length, though it is wise to keep them low to limit memory usage per session.
2023 In order to keep log format consistent for a same frontend, header captures
2024 can only be declared in a frontend. It is not possible to specify a capture
2025 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002026
2027 Example:
2028 capture request header Host len 15
2029 capture request header X-Forwarded-For len 15
2030 capture request header Referrer len 15
2031
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002032 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002033 about logging.
2034
2035
2036capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002037 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002038 May be used in sections : defaults | frontend | listen | backend
2039 no | yes | yes | no
2040 Arguments :
2041 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002042 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002043 appear in the response, with the first letter of each word in
2044 upper case. The header name will not appear in the logs, only the
2045 value is reported, but the position in the logs is respected.
2046
2047 <length> is the maximum number of characters to extract from the value and
2048 report in the logs. The string will be truncated on the right if
2049 it exceeds <length>.
2050
Willy Tarreau4460d032012-11-21 23:37:37 +01002051 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002052 result will be added to the logs between braces ('{}') after the captured
2053 request headers. If multiple headers are captured, they will be delimited by
2054 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002055 the configuration. Non-existent headers will be logged just as an empty
2056 string. Common uses for response header captures include the "Content-length"
2057 header which indicates how many bytes are expected to be returned, the
2058 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002059
Willy Tarreau0900abb2012-11-22 00:21:46 +01002060 There is no limit to the number of captured response headers nor to their
2061 length, though it is wise to keep them low to limit memory usage per session.
2062 In order to keep log format consistent for a same frontend, header captures
2063 can only be declared in a frontend. It is not possible to specify a capture
2064 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002065
2066 Example:
2067 capture response header Content-length len 9
2068 capture response header Location len 15
2069
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002070 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002071 about logging.
2072
2073
Cyril Bontéf0c60612010-02-06 14:44:47 +01002074clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002075 Set the maximum inactivity time on the client side.
2076 May be used in sections : defaults | frontend | listen | backend
2077 yes | yes | yes | no
2078 Arguments :
2079 <timeout> is the timeout value is specified in milliseconds by default, but
2080 can be in any other unit if the number is suffixed by the unit,
2081 as explained at the top of this document.
2082
2083 The inactivity timeout applies when the client is expected to acknowledge or
2084 send data. In HTTP mode, this timeout is particularly important to consider
2085 during the first phase, when the client sends the request, and during the
2086 response while it is reading data sent by the server. The value is specified
2087 in milliseconds by default, but can be in any other unit if the number is
2088 suffixed by the unit, as specified at the top of this document. In TCP mode
2089 (and to a lesser extent, in HTTP mode), it is highly recommended that the
2090 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002091 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01002092 losses by specifying timeouts that are slightly above multiples of 3 seconds
2093 (eg: 4 or 5 seconds).
2094
2095 This parameter is specific to frontends, but can be specified once for all in
2096 "defaults" sections. This is in fact one of the easiest solutions not to
2097 forget about it. An unspecified timeout results in an infinite timeout, which
2098 is not recommended. Such a usage is accepted and works but reports a warning
2099 during startup because it may results in accumulation of expired sessions in
2100 the system if the system's timeouts are not configured either.
2101
2102 This parameter is provided for compatibility but is currently deprecated.
2103 Please use "timeout client" instead.
2104
Willy Tarreau036fae02008-01-06 13:24:40 +01002105 See also : "timeout client", "timeout http-request", "timeout server", and
2106 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002107
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002108compression algo <algorithm> ...
2109compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02002110compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02002111 Enable HTTP compression.
2112 May be used in sections : defaults | frontend | listen | backend
2113 yes | yes | yes | yes
2114 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002115 algo is followed by the list of supported compression algorithms.
2116 type is followed by the list of MIME types that will be compressed.
2117 offload makes haproxy work as a compression offloader only (see notes).
2118
2119 The currently supported algorithms are :
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002120 identity this is mostly for debugging, and it was useful for developing
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002121 the compression feature. Identity does not apply any change on
2122 data.
2123
2124 gzip applies gzip compression. This setting is only available when
2125 support for zlib was built in.
2126
2127 deflate same as gzip, but with deflate algorithm and zlib format.
2128 Note that this algorithm has ambiguous support on many browsers
2129 and no support at all from recent ones. It is strongly
2130 recommended not to use it for anything else than experimentation.
2131 This setting is only available when support for zlib was built
2132 in.
2133
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002134 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002135 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002136 If backend servers support HTTP compression, these directives
2137 will be no-op: haproxy will see the compressed response and will not
2138 compress again. If backend servers do not support HTTP compression and
2139 there is Accept-Encoding header in request, haproxy will compress the
2140 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02002141
2142 The "offload" setting makes haproxy remove the Accept-Encoding header to
2143 prevent backend servers from compressing responses. It is strongly
2144 recommended not to do this because this means that all the compression work
2145 will be done on the single point where haproxy is located. However in some
2146 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002147 with broken HTTP compression implementation which can't be turned off.
2148 In that case haproxy can be used to prevent that gateway from emitting
2149 invalid payloads. In this case, simply removing the header in the
2150 configuration does not work because it applies before the header is parsed,
2151 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreau4cf57af2014-07-12 16:37:02 +02002152 then be used for such scenarios. Note: for now, the "offload" setting is
2153 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02002154
William Lallemand05097442012-11-20 12:14:28 +01002155 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002156 * the request does not advertise a supported compression algorithm in the
2157 "Accept-Encoding" header
2158 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01002159 * HTTP status code is not 200
William Lallemand8bb4e342013-12-10 17:28:48 +01002160 * response header "Transfer-Encoding" contains "chunked" (Temporary
2161 Workaround)
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002162 * response contain neither a "Content-Length" header nor a
2163 "Transfer-Encoding" whose last value is "chunked"
2164 * response contains a "Content-Type" header whose first value starts with
2165 "multipart"
2166 * the response contains the "no-transform" value in the "Cache-control"
2167 header
2168 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
2169 and later
2170 * The response contains a "Content-Encoding" header, indicating that the
2171 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01002172
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002173 Note: The compression does not rewrite Etag headers, and does not emit the
2174 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01002175
William Lallemand82fe75c2012-10-23 10:25:10 +02002176 Examples :
2177 compression algo gzip
2178 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002179
Cyril Bontéf0c60612010-02-06 14:44:47 +01002180contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002181 Set the maximum time to wait for a connection attempt to a server to succeed.
2182 May be used in sections : defaults | frontend | listen | backend
2183 yes | no | yes | yes
2184 Arguments :
2185 <timeout> is the timeout value is specified in milliseconds by default, but
2186 can be in any other unit if the number is suffixed by the unit,
2187 as explained at the top of this document.
2188
2189 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002190 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01002191 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01002192 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
2193 connect timeout also presets the queue timeout to the same value if this one
2194 has not been specified. Historically, the contimeout was also used to set the
2195 tarpit timeout in a listen section, which is not possible in a pure frontend.
2196
2197 This parameter is specific to backends, but can be specified once for all in
2198 "defaults" sections. This is in fact one of the easiest solutions not to
2199 forget about it. An unspecified timeout results in an infinite timeout, which
2200 is not recommended. Such a usage is accepted and works but reports a warning
2201 during startup because it may results in accumulation of failed sessions in
2202 the system if the system's timeouts are not configured either.
2203
2204 This parameter is provided for backwards compatibility but is currently
2205 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
2206 instead.
2207
2208 See also : "timeout connect", "timeout queue", "timeout tarpit",
2209 "timeout server", "contimeout".
2210
2211
Willy Tarreau55165fe2009-05-10 12:02:55 +02002212cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02002213 [ postonly ] [ preserve ] [ httponly ] [ secure ]
2214 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002215 Enable cookie-based persistence in a backend.
2216 May be used in sections : defaults | frontend | listen | backend
2217 yes | no | yes | yes
2218 Arguments :
2219 <name> is the name of the cookie which will be monitored, modified or
2220 inserted in order to bring persistence. This cookie is sent to
2221 the client via a "Set-Cookie" header in the response, and is
2222 brought back by the client in a "Cookie" header in all requests.
2223 Special care should be taken to choose a name which does not
2224 conflict with any likely application cookie. Also, if the same
2225 backends are subject to be used by the same clients (eg:
2226 HTTP/HTTPS), care should be taken to use different cookie names
2227 between all backends if persistence between them is not desired.
2228
2229 rewrite This keyword indicates that the cookie will be provided by the
2230 server and that haproxy will have to modify its value to set the
2231 server's identifier in it. This mode is handy when the management
2232 of complex combinations of "Set-cookie" and "Cache-control"
2233 headers is left to the application. The application can then
2234 decide whether or not it is appropriate to emit a persistence
2235 cookie. Since all responses should be monitored, this mode only
2236 works in HTTP close mode. Unless the application behaviour is
2237 very complex and/or broken, it is advised not to start with this
2238 mode for new deployments. This keyword is incompatible with
2239 "insert" and "prefix".
2240
2241 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02002242 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002243
Willy Tarreaua79094d2010-08-31 22:54:15 +02002244 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002245 server. When used without the "preserve" option, if the server
2246 emits a cookie with the same name, it will be remove before
2247 processing. For this reason, this mode can be used to upgrade
2248 existing configurations running in the "rewrite" mode. The cookie
2249 will only be a session cookie and will not be stored on the
2250 client's disk. By default, unless the "indirect" option is added,
2251 the server will see the cookies emitted by the client. Due to
2252 caching effects, it is generally wise to add the "nocache" or
2253 "postonly" keywords (see below). The "insert" keyword is not
2254 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002255
2256 prefix This keyword indicates that instead of relying on a dedicated
2257 cookie for the persistence, an existing one will be completed.
2258 This may be needed in some specific environments where the client
2259 does not support more than one single cookie and the application
2260 already needs it. In this case, whenever the server sets a cookie
2261 named <name>, it will be prefixed with the server's identifier
2262 and a delimiter. The prefix will be removed from all client
2263 requests so that the server still finds the cookie it emitted.
2264 Since all requests and responses are subject to being modified,
2265 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02002266 not compatible with "rewrite" and "insert". Note: it is highly
2267 recommended not to use "indirect" with "prefix", otherwise server
2268 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002269
Willy Tarreaua79094d2010-08-31 22:54:15 +02002270 indirect When this option is specified, no cookie will be emitted to a
2271 client which already has a valid one for the server which has
2272 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002273 it will be removed, unless the "preserve" option is also set. In
2274 "insert" mode, this will additionally remove cookies from the
2275 requests transmitted to the server, making the persistence
2276 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02002277 Note: it is highly recommended not to use "indirect" with
2278 "prefix", otherwise server cookie updates would not be sent to
2279 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002280
2281 nocache This option is recommended in conjunction with the insert mode
2282 when there is a cache between the client and HAProxy, as it
2283 ensures that a cacheable response will be tagged non-cacheable if
2284 a cookie needs to be inserted. This is important because if all
2285 persistence cookies are added on a cacheable home page for
2286 instance, then all customers will then fetch the page from an
2287 outer cache and will all share the same persistence cookie,
2288 leading to one server receiving much more traffic than others.
2289 See also the "insert" and "postonly" options.
2290
2291 postonly This option ensures that cookie insertion will only be performed
2292 on responses to POST requests. It is an alternative to the
2293 "nocache" option, because POST responses are not cacheable, so
2294 this ensures that the persistence cookie will never get cached.
2295 Since most sites do not need any sort of persistence before the
2296 first POST which generally is a login request, this is a very
2297 efficient method to optimize caching without risking to find a
2298 persistence cookie in the cache.
2299 See also the "insert" and "nocache" options.
2300
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002301 preserve This option may only be used with "insert" and/or "indirect". It
2302 allows the server to emit the persistence cookie itself. In this
2303 case, if a cookie is found in the response, haproxy will leave it
2304 untouched. This is useful in order to end persistence after a
2305 logout request for instance. For this, the server just has to
2306 emit a cookie with an invalid value (eg: empty) or with a date in
2307 the past. By combining this mechanism with the "disable-on-404"
2308 check option, it is possible to perform a completely graceful
2309 shutdown because users will definitely leave the server after
2310 they logout.
2311
Willy Tarreau4992dd22012-05-31 21:02:17 +02002312 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2313 when a cookie is inserted. This attribute is used so that a
2314 user agent doesn't share the cookie with non-HTTP components.
2315 Please check RFC6265 for more information on this attribute.
2316
2317 secure This option tells haproxy to add a "Secure" cookie attribute when
2318 a cookie is inserted. This attribute is used so that a user agent
2319 never emits this cookie over non-secure channels, which means
2320 that a cookie learned with this flag will be presented only over
2321 SSL/TLS connections. Please check RFC6265 for more information on
2322 this attribute.
2323
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002324 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002325 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002326 name. If the domain begins with a dot, the browser is allowed to
2327 use it for any host ending with that name. It is also possible to
2328 specify several domain names by invoking this option multiple
2329 times. Some browsers might have small limits on the number of
2330 domains, so be careful when doing that. For the record, sending
2331 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002332
Willy Tarreau996a92c2010-10-13 19:30:47 +02002333 maxidle This option allows inserted cookies to be ignored after some idle
2334 time. It only works with insert-mode cookies. When a cookie is
2335 sent to the client, the date this cookie was emitted is sent too.
2336 Upon further presentations of this cookie, if the date is older
2337 than the delay indicated by the parameter (in seconds), it will
2338 be ignored. Otherwise, it will be refreshed if needed when the
2339 response is sent to the client. This is particularly useful to
2340 prevent users who never close their browsers from remaining for
2341 too long on the same server (eg: after a farm size change). When
2342 this option is set and a cookie has no date, it is always
2343 accepted, but gets refreshed in the response. This maintains the
2344 ability for admins to access their sites. Cookies that have a
2345 date in the future further than 24 hours are ignored. Doing so
2346 lets admins fix timezone issues without risking kicking users off
2347 the site.
2348
2349 maxlife This option allows inserted cookies to be ignored after some life
2350 time, whether they're in use or not. It only works with insert
2351 mode cookies. When a cookie is first sent to the client, the date
2352 this cookie was emitted is sent too. Upon further presentations
2353 of this cookie, if the date is older than the delay indicated by
2354 the parameter (in seconds), it will be ignored. If the cookie in
2355 the request has no date, it is accepted and a date will be set.
2356 Cookies that have a date in the future further than 24 hours are
2357 ignored. Doing so lets admins fix timezone issues without risking
2358 kicking users off the site. Contrary to maxidle, this value is
2359 not refreshed, only the first visit date counts. Both maxidle and
2360 maxlife may be used at the time. This is particularly useful to
2361 prevent users who never close their browsers from remaining for
2362 too long on the same server (eg: after a farm size change). This
2363 is stronger than the maxidle method in that it forces a
2364 redispatch after some absolute delay.
2365
Willy Tarreau0ba27502007-12-24 16:55:16 +01002366 There can be only one persistence cookie per HTTP backend, and it can be
2367 declared in a defaults section. The value of the cookie will be the value
2368 indicated after the "cookie" keyword in a "server" statement. If no cookie
2369 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002370
Willy Tarreau0ba27502007-12-24 16:55:16 +01002371 Examples :
2372 cookie JSESSIONID prefix
2373 cookie SRV insert indirect nocache
2374 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002375 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002376
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002377 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002378 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002379
Willy Tarreau983e01e2010-01-11 18:42:06 +01002380
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002381default-server [param*]
2382 Change default options for a server in a backend
2383 May be used in sections : defaults | frontend | listen | backend
2384 yes | no | yes | yes
2385 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002386 <param*> is a list of parameters for this server. The "default-server"
2387 keyword accepts an important number of options and has a complete
2388 section dedicated to it. Please refer to section 5 for more
2389 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002390
Willy Tarreau983e01e2010-01-11 18:42:06 +01002391 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002392 default-server inter 1000 weight 13
2393
2394 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002395
Willy Tarreau983e01e2010-01-11 18:42:06 +01002396
Willy Tarreau0ba27502007-12-24 16:55:16 +01002397default_backend <backend>
2398 Specify the backend to use when no "use_backend" rule has been matched.
2399 May be used in sections : defaults | frontend | listen | backend
2400 yes | yes | yes | no
2401 Arguments :
2402 <backend> is the name of the backend to use.
2403
2404 When doing content-switching between frontend and backends using the
2405 "use_backend" keyword, it is often useful to indicate which backend will be
2406 used when no rule has matched. It generally is the dynamic backend which
2407 will catch all undetermined requests.
2408
Willy Tarreau0ba27502007-12-24 16:55:16 +01002409 Example :
2410
2411 use_backend dynamic if url_dyn
2412 use_backend static if url_css url_img extension_img
2413 default_backend dynamic
2414
Willy Tarreau2769aa02007-12-27 18:26:09 +01002415 See also : "use_backend", "reqsetbe", "reqisetbe"
2416
Willy Tarreau0ba27502007-12-24 16:55:16 +01002417
Baptiste Assmann27f51342013-10-09 06:51:49 +02002418description <string>
2419 Describe a listen, frontend or backend.
2420 May be used in sections : defaults | frontend | listen | backend
2421 no | yes | yes | yes
2422 Arguments : string
2423
2424 Allows to add a sentence to describe the related object in the HAProxy HTML
2425 stats page. The description will be printed on the right of the object name
2426 it describes.
2427 No need to backslash spaces in the <string> arguments.
2428
2429
Willy Tarreau0ba27502007-12-24 16:55:16 +01002430disabled
2431 Disable a proxy, frontend or backend.
2432 May be used in sections : defaults | frontend | listen | backend
2433 yes | yes | yes | yes
2434 Arguments : none
2435
2436 The "disabled" keyword is used to disable an instance, mainly in order to
2437 liberate a listening port or to temporarily disable a service. The instance
2438 will still be created and its configuration will be checked, but it will be
2439 created in the "stopped" state and will appear as such in the statistics. It
2440 will not receive any traffic nor will it send any health-checks or logs. It
2441 is possible to disable many instances at once by adding the "disabled"
2442 keyword in a "defaults" section.
2443
2444 See also : "enabled"
2445
2446
Willy Tarreau5ce94572010-06-07 14:35:41 +02002447dispatch <address>:<port>
2448 Set a default server address
2449 May be used in sections : defaults | frontend | listen | backend
2450 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002451 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002452
2453 <address> is the IPv4 address of the default server. Alternatively, a
2454 resolvable hostname is supported, but this name will be resolved
2455 during start-up.
2456
2457 <ports> is a mandatory port specification. All connections will be sent
2458 to this port, and it is not permitted to use port offsets as is
2459 possible with normal servers.
2460
Willy Tarreau787aed52011-04-15 06:45:37 +02002461 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002462 server can take the connection. In the past it was used to forward non
2463 persistent connections to an auxiliary load balancer. Due to its simple
2464 syntax, it has also been used for simple TCP relays. It is recommended not to
2465 use it for more clarity, and to use the "server" directive instead.
2466
2467 See also : "server"
2468
2469
Willy Tarreau0ba27502007-12-24 16:55:16 +01002470enabled
2471 Enable a proxy, frontend or backend.
2472 May be used in sections : defaults | frontend | listen | backend
2473 yes | yes | yes | yes
2474 Arguments : none
2475
2476 The "enabled" keyword is used to explicitly enable an instance, when the
2477 defaults has been set to "disabled". This is very rarely used.
2478
2479 See also : "disabled"
2480
2481
2482errorfile <code> <file>
2483 Return a file contents instead of errors generated by HAProxy
2484 May be used in sections : defaults | frontend | listen | backend
2485 yes | yes | yes | yes
2486 Arguments :
2487 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002488 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002489
2490 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002491 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002492 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002493 error pages, and to use absolute paths, since files are read
2494 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002495
2496 It is important to understand that this keyword is not meant to rewrite
2497 errors returned by the server, but errors detected and returned by HAProxy.
2498 This is why the list of supported errors is limited to a small set.
2499
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002500 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2501
Willy Tarreau0ba27502007-12-24 16:55:16 +01002502 The files are returned verbatim on the TCP socket. This allows any trick such
2503 as redirections to another URL or site, as well as tricks to clean cookies,
2504 force enable or disable caching, etc... The package provides default error
2505 files returning the same contents as default errors.
2506
Willy Tarreau59140a22009-02-22 12:02:30 +01002507 The files should not exceed the configured buffer size (BUFSIZE), which
2508 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2509 not to put any reference to local contents (eg: images) in order to avoid
2510 loops between the client and HAProxy when all servers are down, causing an
2511 error to be returned instead of an image. For better HTTP compliance, it is
2512 recommended that all header lines end with CR-LF and not LF alone.
2513
Willy Tarreau0ba27502007-12-24 16:55:16 +01002514 The files are read at the same time as the configuration and kept in memory.
2515 For this reason, the errors continue to be returned even when the process is
2516 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002517 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002518 403 status code and interrogating a blocked URL.
2519
2520 See also : "errorloc", "errorloc302", "errorloc303"
2521
Willy Tarreau59140a22009-02-22 12:02:30 +01002522 Example :
2523 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau2705a612014-05-23 17:38:34 +02002524 errorfile 408 /dev/null # workaround Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01002525 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2526 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2527
Willy Tarreau2769aa02007-12-27 18:26:09 +01002528
2529errorloc <code> <url>
2530errorloc302 <code> <url>
2531 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2532 May be used in sections : defaults | frontend | listen | backend
2533 yes | yes | yes | yes
2534 Arguments :
2535 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002536 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002537
2538 <url> it is the exact contents of the "Location" header. It may contain
2539 either a relative URI to an error page hosted on the same site,
2540 or an absolute URI designating an error page on another site.
2541 Special care should be given to relative URIs to avoid redirect
2542 loops if the URI itself may generate the same error (eg: 500).
2543
2544 It is important to understand that this keyword is not meant to rewrite
2545 errors returned by the server, but errors detected and returned by HAProxy.
2546 This is why the list of supported errors is limited to a small set.
2547
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002548 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2549
Willy Tarreau2769aa02007-12-27 18:26:09 +01002550 Note that both keyword return the HTTP 302 status code, which tells the
2551 client to fetch the designated URL using the same HTTP method. This can be
2552 quite problematic in case of non-GET methods such as POST, because the URL
2553 sent to the client might not be allowed for something other than GET. To
2554 workaround this problem, please use "errorloc303" which send the HTTP 303