blob: 9ce88bc4343b56cf64ff8310e8a85d9af8a8d214 [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 Tarreaub3066502017-11-26 19:50:17 +01005 version 1.9
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreaubddf2922018-10-28 20:39:31 +01007 2018/10/28
Willy Tarreau6a06a402007-07-15 20:15:28 +02008
9
10This document covers the configuration language as implemented in the version
Davor Ocelice9ed2812017-12-25 17:49:28 +010011specified above. It does not provide any hints, examples, or advice. For such
Willy Tarreau0ba27502007-12-24 16:55:16 +010012documentation, please refer to the Reference Manual or the Architecture Manual.
Davor Ocelice9ed2812017-12-25 17:49:28 +010013The summary below is meant to help you find sections by name and navigate
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014through 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
Davor Ocelice9ed2812017-12-25 17:49:28 +010022 sometimes useful to prefix all output lines (logs, console outputs) with 3
23 closing angle brackets ('>>>') in order to emphasize the difference between
24 inputs and outputs when they may be ambiguous. If you add sections,
Willy Tarreau62a36c42010-08-17 15:53:10 +020025 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
Davor Ocelice9ed2812017-12-25 17:49:28 +0100341.2.1. The request line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200351.2.2. The request headers
361.3. HTTP response
Davor Ocelice9ed2812017-12-25 17:49:28 +0100371.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200381.3.2. The response headers
39
402. Configuring HAProxy
412.1. Configuration file format
William Lallemandf9873ba2015-05-05 17:37:14 +0200422.2. Quoting and escaping
William Lallemandb2f07452015-05-12 14:27:13 +0200432.3. Environment variables
442.4. Time format
452.5. Examples
Willy Tarreauc57f0e22009-05-10 13:12:33 +020046
473. Global parameters
483.1. Process management and security
493.2. Performance tuning
503.3. Debugging
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100513.4. Userlists
Cyril Bontédc4d9032012-04-08 21:57:39 +0200523.5. Peers
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200533.6. Mailers
Willy Tarreauc57f0e22009-05-10 13:12:33 +020054
554. Proxies
564.1. Proxy keywords matrix
574.2. Alphabetically sorted keywords reference
58
Davor Ocelice9ed2812017-12-25 17:49:28 +0100595. Bind and server options
Willy Tarreau086fbf52012-09-24 20:34:51 +0200605.1. Bind options
615.2. Server and default-server options
Baptiste Assmann1fa66662015-04-14 00:28:47 +0200625.3. Server DNS resolution
635.3.1. Global overview
645.3.2. The resolvers section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020065
666. HTTP header manipulation
67
Willy Tarreau74ca5042013-06-11 23:12:07 +0200687. Using ACLs and fetching samples
697.1. ACL basics
707.1.1. Matching booleans
717.1.2. Matching integers
727.1.3. Matching strings
737.1.4. Matching regular expressions (regexes)
747.1.5. Matching arbitrary data blocks
757.1.6. Matching IPv4 and IPv6 addresses
767.2. Using ACLs to form conditions
777.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200787.3.1. Converters
797.3.2. Fetching samples from internal states
807.3.3. Fetching samples at Layer 4
817.3.4. Fetching samples at Layer 5
827.3.5. Fetching samples from buffer contents (Layer 6)
837.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +0200847.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020085
868. Logging
878.1. Log levels
888.2. Log formats
898.2.1. Default log format
908.2.2. TCP log format
918.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100928.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100938.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200948.3. Advanced logging options
958.3.1. Disabling logging of external tests
968.3.2. Logging before waiting for the session to terminate
978.3.3. Raising log level upon errors
988.3.4. Disabling logging of successful connections
998.4. Timing events
1008.5. Session state at disconnection
1018.6. Non-printable characters
1028.7. Capturing HTTP cookies
1038.8. Capturing HTTP headers
1048.9. Examples of logs
105
Christopher Fauletc3fe5332016-04-07 15:30:10 +02001069. Supported filters
1079.1. Trace
1089.2. HTTP compression
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001099.3. Stream Processing Offload Engine (SPOE)
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200110
William Lallemand86d0df02017-11-24 21:36:45 +010011110. Cache
Cyril Bonté7b888f12017-11-26 22:24:31 +010011210.1. Limitation
11310.2. Setup
11410.2.1. Cache section
11510.2.2. Proxy section
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116
1171. Quick reminder about HTTP
118----------------------------
119
Davor Ocelice9ed2812017-12-25 17:49:28 +0100120When HAProxy is running in HTTP mode, both the request and the response are
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200121fully analyzed and indexed, thus it becomes possible to build matching criteria
122on almost anything found in the contents.
123
124However, it is important to understand how HTTP requests and responses are
125formed, and how HAProxy decomposes them. It will then become easier to write
126correct rules and to debug existing configurations.
127
128
1291.1. The HTTP transaction model
130-------------------------------
131
132The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100133to one and only one response. Traditionally, a TCP connection is established
Davor Ocelice9ed2812017-12-25 17:49:28 +0100134from the client to the server, a request is sent by the client through the
135connection, the server responds, and the connection is closed. A new request
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200136will involve a new connection :
137
138 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
139
140In this mode, called the "HTTP close" mode, there are as many connection
141establishments as there are HTTP transactions. Since the connection is closed
142by the server after the response, the client does not need to know the content
143length.
144
145Due to the transactional nature of the protocol, it was possible to improve it
146to avoid closing a connection between two subsequent transactions. In this mode
147however, it is mandatory that the server indicates the content length for each
148response so that the client does not wait indefinitely. For this, a special
149header is used: "Content-length". This mode is called the "keep-alive" mode :
150
151 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
152
153Its advantages are a reduced latency between transactions, and less processing
154power required on the server side. It is generally better than the close mode,
155but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200156a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200157
Willy Tarreau95c4e142017-11-26 12:18:55 +0100158Another improvement in the communications is the pipelining mode. It still uses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200159keep-alive, but the client does not wait for the first response to send the
160second request. This is useful for fetching large number of images composing a
161page :
162
163 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
164
165This can obviously have a tremendous benefit on performance because the network
166latency is eliminated between subsequent requests. Many HTTP agents do not
167correctly support pipelining since there is no way to associate a response with
168the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100169server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170
Willy Tarreau95c4e142017-11-26 12:18:55 +0100171The next improvement is the multiplexed mode, as implemented in HTTP/2. This
172time, each transaction is assigned a single stream identifier, and all streams
173are multiplexed over an existing connection. Many requests can be sent in
174parallel by the client, and responses can arrive in any order since they also
175carry the stream identifier.
176
Willy Tarreau70dffda2014-01-30 03:07:23 +0100177By default HAProxy operates in keep-alive mode with regards to persistent
178connections: for each connection it processes each request and response, and
179leaves the connection idle on both sides between the end of a response and the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100180start of a new request. When it receives HTTP/2 connections from a client, it
181processes all the requests in parallel and leaves the connection idling,
182waiting for new requests, just as if it was a keep-alive HTTP connection.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200183
Christopher Faulet315b39c2018-09-21 16:26:19 +0200184HAProxy supports 4 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +0100185 - keep alive : all requests and responses are processed (default)
186 - tunnel : only the first request and response are processed,
187 everything else is forwarded with no analysis.
Willy Tarreau70dffda2014-01-30 03:07:23 +0100188 - server close : the server-facing connection is closed after the response.
Christopher Faulet315b39c2018-09-21 16:26:19 +0200189 - close : the connection is actively closed after end of response.
Willy Tarreau70dffda2014-01-30 03:07:23 +0100190
Davor Ocelice9ed2812017-12-25 17:49:28 +0100191For HTTP/2, the connection mode resembles more the "server close" mode : given
192the independence of all streams, there is currently no place to hook the idle
Willy Tarreau95c4e142017-11-26 12:18:55 +0100193server connection after a response, so it is closed after the response. HTTP/2
194is only supported for incoming connections, not on connections going to
195servers.
196
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200197
1981.2. HTTP request
199-----------------
200
201First, let's consider this HTTP request :
202
203 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100204 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200205 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
206 2 Host: www.mydomain.com
207 3 User-agent: my small browser
208 4 Accept: image/jpeg, image/gif
209 5 Accept: image/png
210
211
2121.2.1. The Request line
213-----------------------
214
215Line 1 is the "request line". It is always composed of 3 fields :
216
217 - a METHOD : GET
218 - a URI : /serv/login.php?lang=en&profile=2
219 - a version tag : HTTP/1.1
220
221All of them are delimited by what the standard calls LWS (linear white spaces),
222which are commonly spaces, but can also be tabs or line feeds/carriage returns
223followed by spaces/tabs. The method itself cannot contain any colon (':') and
224is limited to alphabetic letters. All those various combinations make it
225desirable that HAProxy performs the splitting itself rather than leaving it to
226the user to write a complex or inaccurate regular expression.
227
228The URI itself can have several forms :
229
230 - A "relative URI" :
231
232 /serv/login.php?lang=en&profile=2
233
234 It is a complete URL without the host part. This is generally what is
235 received by servers, reverse proxies and transparent proxies.
236
237 - An "absolute URI", also called a "URL" :
238
239 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
240
241 It is composed of a "scheme" (the protocol name followed by '://'), a host
242 name or address, optionally a colon (':') followed by a port number, then
243 a relative URI beginning at the first slash ('/') after the address part.
244 This is generally what proxies receive, but a server supporting HTTP/1.1
245 must accept this form too.
246
247 - a star ('*') : this form is only accepted in association with the OPTIONS
248 method and is not relayable. It is used to inquiry a next hop's
249 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100250
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200251 - an address:port combination : 192.168.0.12:80
252 This is used with the CONNECT method, which is used to establish TCP
253 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
254 other protocols too.
255
256In a relative URI, two sub-parts are identified. The part before the question
257mark is called the "path". It is typically the relative path to static objects
258on the server. The part after the question mark is called the "query string".
259It is mostly used with GET requests sent to dynamic scripts and is very
260specific to the language, framework or application in use.
261
Willy Tarreau95c4e142017-11-26 12:18:55 +0100262HTTP/2 doesn't convey a version information with the request, so the version is
Davor Ocelice9ed2812017-12-25 17:49:28 +0100263assumed to be the same as the one of the underlying protocol (i.e. "HTTP/2").
Willy Tarreau95c4e142017-11-26 12:18:55 +0100264However, haproxy natively processes HTTP/1.x requests and headers, so requests
265received over an HTTP/2 connection are transcoded to HTTP/1.1 before being
266processed. This explains why they still appear as "HTTP/1.1" in haproxy's logs
267as well as in server logs.
268
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200269
2701.2.2. The request headers
271--------------------------
272
273The headers start at the second line. They are composed of a name at the
274beginning of the line, immediately followed by a colon (':'). Traditionally,
275an LWS is added after the colon but that's not required. Then come the values.
276Multiple identical headers may be folded into one single line, delimiting the
277values with commas, provided that their order is respected. This is commonly
278encountered in the "Cookie:" field. A header may span over multiple lines if
279the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
280define a total of 3 values for the "Accept:" header.
281
Davor Ocelice9ed2812017-12-25 17:49:28 +0100282Contrary to a common misconception, header names are not case-sensitive, and
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200283their values are not either if they refer to other header names (such as the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100284"Connection:" header). In HTTP/2, header names are always sent in lower case,
285as can be seen when running in debug mode.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200286
287The end of the headers is indicated by the first empty line. People often say
288that it's a double line feed, which is not exact, even if a double line feed
289is one valid form of empty line.
290
291Fortunately, HAProxy takes care of all these complex combinations when indexing
292headers, checking values and counting them, so there is no reason to worry
293about the way they could be written, but it is important not to accuse an
294application of being buggy if it does unusual, valid things.
295
296Important note:
Lukas Tribus23953682017-04-28 13:24:30 +0000297 As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200298 in the middle of headers by LWS in order to join multi-line headers. This
299 is necessary for proper analysis and helps less capable HTTP parsers to work
300 correctly and not to be fooled by such complex constructs.
301
302
3031.3. HTTP response
304------------------
305
306An HTTP response looks very much like an HTTP request. Both are called HTTP
307messages. Let's consider this HTTP response :
308
309 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100310 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200311 1 HTTP/1.1 200 OK
312 2 Content-length: 350
313 3 Content-Type: text/html
314
Willy Tarreau816b9792009-09-15 21:25:21 +0200315As a special case, HTTP supports so called "Informational responses" as status
316codes 1xx. These messages are special in that they don't convey any part of the
317response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100318continue to post its request for instance. In the case of a status 100 response
319the requested information will be carried by the next non-100 response message
320following the informational one. This implies that multiple responses may be
321sent to a single request, and that this only works when keep-alive is enabled
322(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
323correctly forward and skip them, and only process the next non-100 response. As
324such, these messages are neither logged nor transformed, unless explicitly
325state otherwise. Status 101 messages indicate that the protocol is changing
326over the same connection and that haproxy must switch to tunnel mode, just as
327if a CONNECT had occurred. Then the Upgrade header would contain additional
328information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200329
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200330
Davor Ocelice9ed2812017-12-25 17:49:28 +01003311.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200332------------------------
333
334Line 1 is the "response line". It is always composed of 3 fields :
335
336 - a version tag : HTTP/1.1
337 - a status code : 200
338 - a reason : OK
339
340The status code is always 3-digit. The first digit indicates a general status :
Davor Ocelice9ed2812017-12-25 17:49:28 +0100341 - 1xx = informational message to be skipped (e.g. 100, 101)
342 - 2xx = OK, content is following (e.g. 200, 206)
343 - 3xx = OK, no content following (e.g. 302, 304)
344 - 4xx = error caused by the client (e.g. 401, 403, 404)
345 - 5xx = error caused by the server (e.g. 500, 502, 503)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200346
Lukas Tribus23953682017-04-28 13:24:30 +0000347Please refer to RFC7231 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100348"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200349found there, but it's a common practice to respect the well-established
350messages. It can be composed of one or multiple words, such as "OK", "Found",
351or "Authentication Required".
352
Davor Ocelice9ed2812017-12-25 17:49:28 +0100353HAProxy may emit the following status codes by itself :
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200354
355 Code When / reason
356 200 access to stats page, and when replying to monitoring requests
357 301 when performing a redirection, depending on the configured code
358 302 when performing a redirection, depending on the configured code
359 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100360 307 when performing a redirection, depending on the configured code
361 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200362 400 for an invalid or too large request
363 401 when an authentication is required to perform the action (when
364 accessing the stats page)
365 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
366 408 when the request timeout strikes before the request is complete
367 500 when haproxy encounters an unrecoverable internal error, such as a
368 memory allocation failure, which should never happen
369 502 when the server returns an empty, invalid or incomplete response, or
370 when an "rspdeny" filter blocks the response.
371 503 when no server was available to handle the request, or in response to
372 monitoring requests which match the "monitor fail" condition
373 504 when the response timeout strikes before the server responds
374
375The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3764.2).
377
378
3791.3.2. The response headers
380---------------------------
381
382Response headers work exactly like request headers, and as such, HAProxy uses
383the same parsing function for both. Please refer to paragraph 1.2.2 for more
384details.
385
386
3872. Configuring HAProxy
388----------------------
389
3902.1. Configuration file format
391------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200392
393HAProxy's configuration process involves 3 major sources of parameters :
394
395 - the arguments from the command-line, which always take precedence
396 - the "global" section, which sets process-wide parameters
397 - the proxies sections which can take form of "defaults", "listen",
398 "frontend" and "backend".
399
Willy Tarreau0ba27502007-12-24 16:55:16 +0100400The configuration file syntax consists in lines beginning with a keyword
401referenced in this manual, optionally followed by one or several parameters
William Lallemandf9873ba2015-05-05 17:37:14 +0200402delimited by spaces.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100403
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200404
William Lallemandf9873ba2015-05-05 17:37:14 +02004052.2. Quoting and escaping
406-------------------------
407
408HAProxy's configuration introduces a quoting and escaping system similar to
409many programming languages. The configuration file supports 3 types: escaping
410with a backslash, weak quoting with double quotes, and strong quoting with
411single quotes.
412
413If spaces have to be entered in strings, then they must be escaped by preceding
414them by a backslash ('\') or by quoting them. Backslashes also have to be
415escaped by doubling or strong quoting them.
416
417Escaping is achieved by preceding a special character by a backslash ('\'):
418
419 \ to mark a space and differentiate it from a delimiter
420 \# to mark a hash and differentiate it from a comment
421 \\ to use a backslash
422 \' to use a single quote and differentiate it from strong quoting
423 \" to use a double quote and differentiate it from weak quoting
424
425Weak quoting is achieved by using double quotes (""). Weak quoting prevents
426the interpretation of:
427
428 space as a parameter separator
429 ' single quote as a strong quoting delimiter
430 # hash as a comment start
431
William Lallemandb2f07452015-05-12 14:27:13 +0200432Weak quoting permits the interpretation of variables, if you want to use a non
433-interpreted dollar within a double quoted string, you should escape it with a
434backslash ("\$"), it does not work outside weak quoting.
435
436Interpretation of escaping and special characters are not prevented by weak
William Lallemandf9873ba2015-05-05 17:37:14 +0200437quoting.
438
439Strong quoting is achieved by using single quotes (''). Inside single quotes,
440nothing is interpreted, it's the efficient way to quote regexes.
441
442Quoted and escaped strings are replaced in memory by their interpreted
443equivalent, it allows you to perform concatenation.
444
445 Example:
446 # those are equivalents:
447 log-format %{+Q}o\ %t\ %s\ %{-Q}r
448 log-format "%{+Q}o %t %s %{-Q}r"
449 log-format '%{+Q}o %t %s %{-Q}r'
450 log-format "%{+Q}o %t"' %s %{-Q}r'
451 log-format "%{+Q}o %t"' %s'\ %{-Q}r
452
453 # those are equivalents:
454 reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2
455 reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2'
456 reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2"
457 reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2"
458
459
William Lallemandb2f07452015-05-12 14:27:13 +02004602.3. Environment variables
461--------------------------
462
463HAProxy's configuration supports environment variables. Those variables are
464interpreted only within double quotes. Variables are expanded during the
465configuration parsing. Variable names must be preceded by a dollar ("$") and
466optionally enclosed with braces ("{}") similarly to what is done in Bourne
467shell. Variable names can contain alphanumerical characters or the character
468underscore ("_") but should not start with a digit.
469
470 Example:
471
472 bind "fd@${FD_APP1}"
473
474 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
475
476 user "$HAPROXY_USER"
477
William Lallemanddaf4cd22018-04-17 16:46:13 +0200478A special variable $HAPROXY_LOCALPEER is defined at the startup of the process
479which contains the name of the local peer. (See "-L" in the management guide.)
480
William Lallemandb2f07452015-05-12 14:27:13 +0200481
4822.4. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200483----------------
484
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100485Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100486values are generally expressed in milliseconds (unless explicitly stated
487otherwise) but may be expressed in any other unit by suffixing the unit to the
488numeric value. It is important to consider this because it will not be repeated
489for every keyword. Supported units are :
490
491 - us : microseconds. 1 microsecond = 1/1000000 second
492 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
493 - s : seconds. 1s = 1000ms
494 - m : minutes. 1m = 60s = 60000ms
495 - h : hours. 1h = 60m = 3600s = 3600000ms
496 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
497
498
Lukas Tribusaa83a312017-03-21 09:25:09 +00004992.5. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200500-------------
501
502 # Simple configuration for an HTTP proxy listening on port 80 on all
503 # interfaces and forwarding requests to a single backend "servers" with a
504 # single server "server1" listening on 127.0.0.1:8000
505 global
506 daemon
507 maxconn 256
508
509 defaults
510 mode http
511 timeout connect 5000ms
512 timeout client 50000ms
513 timeout server 50000ms
514
515 frontend http-in
516 bind *:80
517 default_backend servers
518
519 backend servers
520 server server1 127.0.0.1:8000 maxconn 32
521
522
523 # The same configuration defined with a single listen block. Shorter but
524 # less expressive, especially in HTTP mode.
525 global
526 daemon
527 maxconn 256
528
529 defaults
530 mode http
531 timeout connect 5000ms
532 timeout client 50000ms
533 timeout server 50000ms
534
535 listen http-in
536 bind *:80
537 server server1 127.0.0.1:8000 maxconn 32
538
539
540Assuming haproxy is in $PATH, test these configurations in a shell with:
541
Willy Tarreauccb289d2010-12-11 20:19:38 +0100542 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200543
544
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005453. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200546--------------------
547
548Parameters in the "global" section are process-wide and often OS-specific. They
549are generally set once for all and do not need being changed once correct. Some
550of them have command-line equivalents.
551
552The following keywords are supported in the "global" section :
553
554 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200555 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200556 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200557 - crt-base
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200558 - cpu-map
Willy Tarreau6a06a402007-07-15 20:15:28 +0200559 - daemon
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200560 - description
561 - deviceatlas-json-file
562 - deviceatlas-log-level
563 - deviceatlas-separator
564 - deviceatlas-properties-cookie
Simon Horman98637e52014-06-20 12:30:16 +0900565 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200566 - gid
567 - group
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100568 - hard-stop-after
Willy Tarreau6a06a402007-07-15 20:15:28 +0200569 - log
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200570 - log-tag
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100571 - log-send-hostname
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200572 - lua-load
Willy Tarreau6a06a402007-07-15 20:15:28 +0200573 - nbproc
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200574 - nbthread
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200575 - node
Willy Tarreau6a06a402007-07-15 20:15:28 +0200576 - pidfile
Willy Tarreau1d549722016-02-16 12:41:57 +0100577 - presetenv
578 - resetenv
Willy Tarreau6a06a402007-07-15 20:15:28 +0200579 - uid
580 - ulimit-n
581 - user
Willy Tarreau1d549722016-02-16 12:41:57 +0100582 - setenv
Willy Tarreaufbee7132007-10-18 13:53:22 +0200583 - stats
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200584 - ssl-default-bind-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200585 - ssl-default-bind-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200586 - ssl-default-bind-options
587 - ssl-default-server-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200588 - ssl-default-server-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200589 - ssl-default-server-options
590 - ssl-dh-param-file
Emeric Brun850efd52014-01-29 12:24:34 +0100591 - ssl-server-verify
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100592 - unix-bind
Willy Tarreau1d549722016-02-16 12:41:57 +0100593 - unsetenv
Thomas Holmesdb04f192015-05-18 13:21:39 +0100594 - 51degrees-data-file
595 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +0200596 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200597 - 51degrees-cache-size
scientiamobiled0027ed2016-11-04 10:55:08 +0100598 - wurfl-data-file
599 - wurfl-information-list
600 - wurfl-information-list-separator
601 - wurfl-engine-mode
602 - wurfl-cache-size
603 - wurfl-useragent-priority
Willy Tarreaud72758d2010-01-12 10:42:19 +0100604
Willy Tarreau6a06a402007-07-15 20:15:28 +0200605 * Performance tuning
Willy Tarreau1746eec2014-04-25 10:46:47 +0200606 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200607 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200608 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100609 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100610 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100611 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200612 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200613 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200614 - maxsslrate
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200615 - maxzlibmem
Willy Tarreau6a06a402007-07-15 20:15:28 +0200616 - noepoll
617 - nokqueue
618 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100619 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300620 - nogetaddrinfo
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +0000621 - noreuseport
Willy Tarreaufe255b72007-10-14 23:09:26 +0200622 - spread-checks
Baptiste Assmann5626f482015-08-23 10:00:10 +0200623 - server-state-base
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200624 - server-state-file
Grant Zhang872f9c22017-01-21 01:10:18 +0000625 - ssl-engine
Grant Zhangfa6c7ee2017-01-14 01:42:15 +0000626 - ssl-mode-async
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200627 - tune.buffers.limit
628 - tune.buffers.reserve
Willy Tarreau27a674e2009-08-17 07:23:33 +0200629 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200630 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100631 - tune.comp.maxlevel
Willy Tarreaufe20e5b2017-07-27 11:42:14 +0200632 - tune.h2.header-table-size
Willy Tarreaue6baec02017-07-27 11:45:11 +0200633 - tune.h2.initial-window-size
Willy Tarreau5242ef82017-07-27 11:47:28 +0200634 - tune.h2.max-concurrent-streams
Willy Tarreau193b8c62012-11-22 00:17:38 +0100635 - tune.http.cookielen
Stéphane Cottin23e9e932017-05-18 08:58:41 +0200636 - tune.http.logurilen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200637 - tune.http.maxhdr
Willy Tarreau7e312732014-02-12 16:35:14 +0100638 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100639 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +0100640 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100641 - tune.lua.session-timeout
642 - tune.lua.task-timeout
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +0200643 - tune.lua.service-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100644 - tune.maxaccept
645 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200646 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +0200647 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200648 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100649 - tune.rcvbuf.client
650 - tune.rcvbuf.server
Willy Tarreaub22fc302015-12-14 12:04:35 +0100651 - tune.recv_enough
Olivier Houchard1599b802018-05-24 18:59:04 +0200652 - tune.runqueue-depth
Willy Tarreaue803de22010-01-21 17:43:04 +0100653 - tune.sndbuf.client
654 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100655 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100656 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200657 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100658 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200659 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +0200660 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER5bf77322017-02-25 12:45:22 +0100661 - tune.ssl.capture-cipherlist-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200662 - tune.vars.global-max-size
Christopher Fauletff2613e2016-11-09 11:36:17 +0100663 - tune.vars.proc-max-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200664 - tune.vars.reqres-max-size
665 - tune.vars.sess-max-size
666 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +0100667 - tune.zlib.memlevel
668 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100669
Willy Tarreau6a06a402007-07-15 20:15:28 +0200670 * Debugging
671 - debug
672 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200673
674
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006753.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200676------------------------------------
677
Emeric Brunc8e8d122012-10-02 18:42:10 +0200678ca-base <dir>
679 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200680 relative path is used with "ca-file" or "crl-file" directives. Absolute
681 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200682
Willy Tarreau6a06a402007-07-15 20:15:28 +0200683chroot <jail dir>
684 Changes current directory to <jail dir> and performs a chroot() there before
685 dropping privileges. This increases the security level in case an unknown
686 vulnerability would be exploited, since it would make it very hard for the
687 attacker to exploit the system. This only works when the process is started
688 with superuser privileges. It is important to ensure that <jail_dir> is both
Davor Ocelice9ed2812017-12-25 17:49:28 +0100689 empty and non-writable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100690
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100691cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>...
692 On Linux 2.6 and above, it is possible to bind a process or a thread to a
693 specific CPU set. This means that the process or the thread will never run on
694 other CPUs. The "cpu-map" directive specifies CPU sets for process or thread
695 sets. The first argument is a process set, eventually followed by a thread
696 set. These sets have the format
697
698 all | odd | even | number[-[number]]
699
700 <number>> must be a number between 1 and 32 or 64, depending on the machine's
Davor Ocelice9ed2812017-12-25 17:49:28 +0100701 word size. Any process IDs above nbproc and any thread IDs above nbthread are
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100702 ignored. It is possible to specify a range with two such number delimited by
703 a dash ('-'). It also is possible to specify all processes at once using
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100704 "all", only odd numbers using "odd" or even numbers using "even", just like
705 with the "bind-process" directive. The second and forthcoming arguments are
Davor Ocelice9ed2812017-12-25 17:49:28 +0100706 CPU sets. Each CPU set is either a unique number between 0 and 31 or 63 or a
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100707 range with two such numbers delimited by a dash ('-'). Multiple CPU numbers
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100708 or ranges may be specified, and the processes or threads will be allowed to
Davor Ocelice9ed2812017-12-25 17:49:28 +0100709 bind to all of them. Obviously, multiple "cpu-map" directives may be
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100710 specified. Each "cpu-map" directive will replace the previous ones when they
711 overlap. A thread will be bound on the intersection of its mapping and the
712 one of the process on which it is attached. If the intersection is null, no
713 specific binding will be set for the thread.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100714
Christopher Fauletff4121f2017-11-22 16:38:49 +0100715 Ranges can be partially defined. The higher bound can be omitted. In such
716 case, it is replaced by the corresponding maximum value, 32 or 64 depending
717 on the machine's word size.
718
Christopher Faulet26028f62017-11-22 15:01:51 +0100719 The prefix "auto:" can be added before the process set to let HAProxy
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100720 automatically bind a process or a thread to a CPU by incrementing
721 process/thread and CPU sets. To be valid, both sets must have the same
722 size. No matter the declaration order of the CPU sets, it will be bound from
723 the lowest to the highest bound. Having a process and a thread range with the
724 "auto:" prefix is not supported. Only one range is supported, the other one
725 must be a fixed number.
Christopher Faulet26028f62017-11-22 15:01:51 +0100726
727 Examples:
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100728 cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs
729
730 cpu-map 1/all 0-3 # bind all threads of the first process on the
731 # first 4 CPUs
732
733 cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63"
734 # or "cpu-map 1-32 0-31" depending on the machine's
735 # word size.
736
Christopher Faulet26028f62017-11-22 15:01:51 +0100737 # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100738 # and so on.
Christopher Faulet26028f62017-11-22 15:01:51 +0100739 cpu-map auto:1-4 0-3
740 cpu-map auto:1-4 0-1 2-3
741 cpu-map auto:1-4 3 2 1 0
742
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100743 # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
744 # and so on.
745 cpu-map auto:1/1-4 0-3
746 cpu-map auto:1/1-4 0-1 2-3
747 cpu-map auto:1/1-4 3 2 1 0
748
Davor Ocelice9ed2812017-12-25 17:49:28 +0100749 # bind each process to exactly one CPU using all/odd/even keyword
Christopher Faulet26028f62017-11-22 15:01:51 +0100750 cpu-map auto:all 0-63
751 cpu-map auto:even 0-31
752 cpu-map auto:odd 32-63
753
754 # invalid cpu-map because process and CPU sets have different sizes.
755 cpu-map auto:1-4 0 # invalid
756 cpu-map auto:1 0-3 # invalid
757
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100758 # invalid cpu-map because automatic binding is used with a process range
759 # and a thread range.
760 cpu-map auto:all/all 0 # invalid
761 cpu-map auto:all/1-4 0 # invalid
762 cpu-map auto:1-4/all 0 # invalid
763
Emeric Brunc8e8d122012-10-02 18:42:10 +0200764crt-base <dir>
765 Assigns a default directory to fetch SSL certificates from when a relative
766 path is used with "crtfile" directives. Absolute locations specified after
767 "crtfile" prevail and ignore "crt-base".
768
Willy Tarreau6a06a402007-07-15 20:15:28 +0200769daemon
770 Makes the process fork into background. This is the recommended mode of
771 operation. It is equivalent to the command line "-D" argument. It can be
Lukas Tribusf46bf952017-11-21 12:39:34 +0100772 disabled by the command line "-db" argument. This option is ignored in
773 systemd mode.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200774
David Carlier8167f302015-06-01 13:50:06 +0200775deviceatlas-json-file <path>
776 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
Davor Ocelice9ed2812017-12-25 17:49:28 +0100777 The path must be a valid JSON data file and accessible by HAProxy process.
David Carlier8167f302015-06-01 13:50:06 +0200778
779deviceatlas-log-level <value>
Davor Ocelice9ed2812017-12-25 17:49:28 +0100780 Sets the level of information returned by the API. This directive is
David Carlier8167f302015-06-01 13:50:06 +0200781 optional and set to 0 by default if not set.
782
783deviceatlas-separator <char>
784 Sets the character separator for the API properties results. This directive
785 is optional and set to | by default if not set.
786
Cyril Bonté0306c4a2015-10-26 22:37:38 +0100787deviceatlas-properties-cookie <name>
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200788 Sets the client cookie's name used for the detection if the DeviceAtlas
789 Client-side component was used during the request. This directive is optional
790 and set to DAPROPS by default if not set.
David Carlier29b3ca32015-09-25 14:09:21 +0100791
Simon Horman98637e52014-06-20 12:30:16 +0900792external-check
793 Allows the use of an external agent to perform health checks.
794 This is disabled by default as a security precaution.
795 See "option external-check".
796
Willy Tarreau6a06a402007-07-15 20:15:28 +0200797gid <number>
798 Changes the process' group ID to <number>. It is recommended that the group
799 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
800 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100801 Note that if haproxy is started from a user having supplementary groups, it
802 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200803 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100804
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100805hard-stop-after <time>
806 Defines the maximum time allowed to perform a clean soft-stop.
807
808 Arguments :
809 <time> is the maximum time (by default in milliseconds) for which the
810 instance will remain alive when a soft-stop is received via the
811 SIGUSR1 signal.
812
813 This may be used to ensure that the instance will quit even if connections
814 remain opened during a soft-stop (for example with long timeouts for a proxy
815 in tcp mode). It applies both in TCP and HTTP mode.
816
817 Example:
818 global
819 hard-stop-after 30s
820
Willy Tarreau6a06a402007-07-15 20:15:28 +0200821group <group name>
822 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
823 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100824
Dragan Dosen7ad31542015-09-28 17:16:47 +0200825log <address> [len <length>] [format <format>] <facility> [max level [min level]]
Cyril Bonté3e954872018-03-20 23:30:27 +0100826 Adds a global syslog server. Several global servers can be defined. They
Davor Ocelice9ed2812017-12-25 17:49:28 +0100827 will receive logs for starts and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100828 configured with "log global".
829
830 <address> can be one of:
831
Willy Tarreau2769aa02007-12-27 18:26:09 +0100832 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100833 no port is specified, 514 is used by default (the standard syslog
834 port).
835
David du Colombier24bb5f52011-03-17 10:40:23 +0100836 - An IPv6 address followed by a colon and optionally a UDP port. If
837 no port is specified, 514 is used by default (the standard syslog
838 port).
839
Robert Tsai81ae1952007-12-05 10:47:29 +0100840 - A filesystem path to a UNIX domain socket, keeping in mind
841 considerations for chroot (be sure the path is accessible inside
842 the chroot) and uid/gid (be sure the path is appropriately
Davor Ocelice9ed2812017-12-25 17:49:28 +0100843 writable).
Robert Tsai81ae1952007-12-05 10:47:29 +0100844
William Lallemandb2f07452015-05-12 14:27:13 +0200845 You may want to reference some environment variables in the address
846 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +0100847
Willy Tarreau18324f52014-06-27 18:10:07 +0200848 <length> is an optional maximum line length. Log lines larger than this value
849 will be truncated before being sent. The reason is that syslog
850 servers act differently on log line length. All servers support the
851 default value of 1024, but some servers simply drop larger lines
852 while others do log them. If a server supports long lines, it may
853 make sense to set this value here in order to avoid truncating long
854 lines. Similarly, if a server drops long lines, it is preferable to
855 truncate them before sending them. Accepted values are 80 to 65535
856 inclusive. The default value of 1024 is generally fine for all
857 standard usages. Some specific cases of long captures or
Davor Ocelice9ed2812017-12-25 17:49:28 +0100858 JSON-formatted logs may require larger values. You may also need to
859 increase "tune.http.logurilen" if your request URIs are truncated.
Willy Tarreau18324f52014-06-27 18:10:07 +0200860
Dragan Dosen7ad31542015-09-28 17:16:47 +0200861 <format> is the log format used when generating syslog messages. It may be
862 one of the following :
863
864 rfc3164 The RFC3164 syslog message format. This is the default.
865 (https://tools.ietf.org/html/rfc3164)
866
867 rfc5424 The RFC5424 syslog message format.
868 (https://tools.ietf.org/html/rfc5424)
869
Robert Tsai81ae1952007-12-05 10:47:29 +0100870 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200871
872 kern user mail daemon auth syslog lpr news
873 uucp cron auth2 ftp ntp audit alert cron2
874 local0 local1 local2 local3 local4 local5 local6 local7
875
876 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200877 all messages are sent. If a maximum level is specified, only messages with a
878 severity at least as important as this level will be sent. An optional minimum
879 level can be specified. If it is set, logs emitted with a more severe level
880 than this one will be capped to this level. This is used to avoid sending
881 "emerg" messages on all terminals on some default syslog configurations.
882 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200883
Cyril Bontédc4d9032012-04-08 21:57:39 +0200884 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200885
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100886log-send-hostname [<string>]
887 Sets the hostname field in the syslog header. If optional "string" parameter
888 is set the header is set to the string contents, otherwise uses the hostname
889 of the system. Generally used if one is not relaying logs through an
890 intermediate syslog server or for simply customizing the hostname printed in
891 the logs.
892
Kevinm48936af2010-12-22 16:08:21 +0000893log-tag <string>
894 Sets the tag field in the syslog header to this string. It defaults to the
895 program name as launched from the command line, which usually is "haproxy".
896 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +0100897 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +0000898
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100899lua-load <file>
900 This global directive loads and executes a Lua file. This directive can be
901 used multiple times.
902
William Lallemand4cfede82017-11-24 22:02:34 +0100903master-worker [no-exit-on-failure]
William Lallemande202b1e2017-06-01 17:38:56 +0200904 Master-worker mode. It is equivalent to the command line "-W" argument.
905 This mode will launch a "master" which will monitor the "workers". Using
906 this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
Davor Ocelice9ed2812017-12-25 17:49:28 +0100907 the master. The master-worker mode is compatible either with the foreground
William Lallemande202b1e2017-06-01 17:38:56 +0200908 or daemon mode. It is recommended to use this mode with multiprocess and
909 systemd.
William Lallemand4cfede82017-11-24 22:02:34 +0100910 By default, if a worker exits with a bad return code, in the case of a
911 segfault for example, all workers will be killed, and the master will leave.
912 It is convenient to combine this behavior with Restart=on-failure in a
913 systemd unit file in order to relaunch the whole process. If you don't want
914 this behavior, you must use the keyword "no-exit-on-failure".
William Lallemande202b1e2017-06-01 17:38:56 +0200915
William Lallemand4cfede82017-11-24 22:02:34 +0100916 See also "-W" in the management guide.
William Lallemande202b1e2017-06-01 17:38:56 +0200917
Willy Tarreau6a06a402007-07-15 20:15:28 +0200918nbproc <number>
919 Creates <number> processes when going daemon. This requires the "daemon"
920 mode. By default, only one process is created, which is the recommended mode
921 of operation. For systems limited to small sets of file descriptors per
922 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
923 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
924
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200925nbthread <number>
926 This setting is only available when support for threads was built in. It
927 creates <number> threads for each created processes. It means if HAProxy is
928 started in foreground, it only creates <number> threads for the first
929 process. FOR NOW, THREADS SUPPORT IN HAPROXY IS HIGHLY EXPERIMENTAL AND IT
930 MUST BE ENABLED WITH CAUTION AND AT YOUR OWN RISK. See also "nbproc".
931
Willy Tarreau6a06a402007-07-15 20:15:28 +0200932pidfile <pidfile>
Davor Ocelice9ed2812017-12-25 17:49:28 +0100933 Writes PIDs of all daemons into file <pidfile>. This option is equivalent to
Willy Tarreau6a06a402007-07-15 20:15:28 +0200934 the "-p" command line argument. The file must be accessible to the user
935 starting the process. See also "daemon".
936
Willy Tarreau1d549722016-02-16 12:41:57 +0100937presetenv <name> <value>
938 Sets environment variable <name> to value <value>. If the variable exists, it
939 is NOT overwritten. The changes immediately take effect so that the next line
940 in the configuration file sees the new value. See also "setenv", "resetenv",
941 and "unsetenv".
942
943resetenv [<name> ...]
944 Removes all environment variables except the ones specified in argument. It
945 allows to use a clean controlled environment before setting new values with
946 setenv or unsetenv. Please note that some internal functions may make use of
947 some environment variables, such as time manipulation functions, but also
948 OpenSSL or even external checks. This must be used with extreme care and only
949 after complete validation. The changes immediately take effect so that the
950 next line in the configuration file sees the new environment. See also
951 "setenv", "presetenv", and "unsetenv".
952
Christopher Fauletff4121f2017-11-22 16:38:49 +0100953stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200954 Limits the stats socket to a certain set of processes numbers. By default the
955 stats socket is bound to all processes, causing a warning to be emitted when
956 nbproc is greater than 1 because there is no way to select the target process
957 when connecting. However, by using this setting, it becomes possible to pin
958 the stats socket to a specific set of processes, typically the first one. The
959 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100960 the number of processes used. The maximum process ID depends on the machine's
Christopher Fauletff4121f2017-11-22 16:38:49 +0100961 word size (32 or 64). Ranges can be partially defined. The higher bound can
962 be omitted. In such case, it is replaced by the corresponding maximum
963 value. A better option consists in using the "process" setting of the "stats
964 socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +0200965
Baptiste Assmann5626f482015-08-23 10:00:10 +0200966server-state-base <directory>
967 Specifies the directory prefix to be prepended in front of all servers state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +0200968 file names which do not start with a '/'. See also "server-state-file",
969 "load-server-state-from-file" and "server-state-file-name".
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200970
971server-state-file <file>
972 Specifies the path to the file containing state of servers. If the path starts
973 with a slash ('/'), it is considered absolute, otherwise it is considered
974 relative to the directory specified using "server-state-base" (if set) or to
975 the current directory. Before reloading HAProxy, it is possible to save the
976 servers' current state using the stats command "show servers state". The
977 output of this command must be written in the file pointed by <file>. When
978 starting up, before handling traffic, HAProxy will read, load and apply state
979 for each server found in the file and available in its current running
Baptiste Assmann01c6cc32015-08-23 11:45:29 +0200980 configuration. See also "server-state-base" and "show servers state",
981 "load-server-state-from-file" and "server-state-file-name"
Baptiste Assmann5626f482015-08-23 10:00:10 +0200982
Willy Tarreau1d549722016-02-16 12:41:57 +0100983setenv <name> <value>
984 Sets environment variable <name> to value <value>. If the variable exists, it
985 is overwritten. The changes immediately take effect so that the next line in
986 the configuration file sees the new value. See also "presetenv", "resetenv",
987 and "unsetenv".
988
Willy Tarreau610f04b2014-02-13 11:36:41 +0100989ssl-default-bind-ciphers <ciphers>
990 This setting is only available when support for OpenSSL was built in. It sets
991 the default string describing the list of cipher algorithms ("cipher suite")
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200992 that are negotiated during the SSL/TLS handshake except for TLSv1.3 for all
993 "bind" lines which do not explicitly define theirs. The format of the string
994 is defined in "man 1 ciphers" from OpenSSL man pages, and can be for instance
995 a string such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). For
996 TLSv1.3 cipher configuration, please check the "ssl-default-bind-ciphersuites"
997 keyword. Please check the "bind" keyword for more information.
998
999ssl-default-bind-ciphersuites <ciphersuites>
1000 This setting is only available when support for OpenSSL was built in and
1001 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
1002 describing the list of cipher algorithms ("cipher suite") that are negotiated
1003 during the TLSv1.3 handshake for all "bind" lines which do not explicitly define
1004 theirs. The format of the string is defined in
1005 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites", and can
1006 be for instance a string such as
1007 "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
1008 (without quotes). For cipher configuration for TLSv1.2 and earlier, please check
1009 the "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more
1010 information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001011
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001012ssl-default-bind-options [<option>]...
1013 This setting is only available when support for OpenSSL was built in. It sets
1014 default ssl-options to force on all "bind" lines. Please check the "bind"
1015 keyword to see available options.
1016
1017 Example:
1018 global
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +02001019 ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001020
Willy Tarreau610f04b2014-02-13 11:36:41 +01001021ssl-default-server-ciphers <ciphers>
1022 This setting is only available when support for OpenSSL was built in. It
1023 sets the default string describing the list of cipher algorithms that are
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001024 negotiated during the SSL/TLS handshake except for TLSv1.3 with the server,
1025 for all "server" lines which do not explicitly define theirs. The format of
1026 the string is defined in "man 1 ciphers". For TLSv1.3 cipher configuration,
1027 please check the "ssl-default-server-ciphersuites" keyword. Please check the
1028 "server" keyword for more information.
1029
1030ssl-default-server-ciphersuites <ciphersuites>
1031 This setting is only available when support for OpenSSL was built in and
1032 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
1033 string describing the list of cipher algorithms that are negotiated during
1034 the TLSv1.3 handshake with the server, for all "server" lines which do not
1035 explicitly define theirs. The format of the string is defined in
1036 "man 1 ciphers" under the "ciphersuites" section. For cipher configuration for
1037 TLSv1.2 and earlier, please check the "ssl-default-server-ciphers" keyword.
1038 Please check the "server" keyword for more information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001039
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001040ssl-default-server-options [<option>]...
1041 This setting is only available when support for OpenSSL was built in. It sets
1042 default ssl-options to force on all "server" lines. Please check the "server"
1043 keyword to see available options.
1044
Remi Gacogne47783ef2015-05-29 15:53:22 +02001045ssl-dh-param-file <file>
1046 This setting is only available when support for OpenSSL was built in. It sets
1047 the default DH parameters that are used during the SSL/TLS handshake when
1048 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
Davor Ocelice9ed2812017-12-25 17:49:28 +01001049 which do not explicitly define theirs. It will be overridden by custom DH
Remi Gacogne47783ef2015-05-29 15:53:22 +02001050 parameters found in a bind certificate file if any. If custom DH parameters
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001051 are not specified either by using ssl-dh-param-file or by setting them
1052 directly in the certificate file, pre-generated DH parameters of the size
1053 specified by tune.ssl.default-dh-param will be used. Custom parameters are
1054 known to be more secure and therefore their use is recommended.
Remi Gacogne47783ef2015-05-29 15:53:22 +02001055 Custom DH parameters may be generated by using the OpenSSL command
1056 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
1057 parameters should not be considered secure anymore.
1058
Emeric Brun850efd52014-01-29 12:24:34 +01001059ssl-server-verify [none|required]
1060 The default behavior for SSL verify on servers side. If specified to 'none',
1061 servers certificates are not verified. The default is 'required' except if
1062 forced using cmdline option '-dV'.
1063
Willy Tarreauabb175f2012-09-24 12:43:26 +02001064stats socket [<address:port>|<path>] [param*]
1065 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
1066 Connections to this socket will return various statistics outputs and even
1067 allow some commands to be issued to change some runtime settings. Please
Willy Tarreau1af20c72017-06-23 16:01:14 +02001068 consult section 9.3 "Unix Socket commands" of Management Guide for more
Kevin Decherf949c7202015-10-13 23:26:44 +02001069 details.
Willy Tarreau6162db22009-10-10 17:13:00 +02001070
Willy Tarreauabb175f2012-09-24 12:43:26 +02001071 All parameters supported by "bind" lines are supported, for instance to
1072 restrict access to some users or their access rights. Please consult
1073 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001074
1075stats timeout <timeout, in milliseconds>
1076 The default timeout on the stats socket is set to 10 seconds. It is possible
1077 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +01001078 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001079
1080stats maxconn <connections>
1081 By default, the stats socket is limited to 10 concurrent connections. It is
1082 possible to change this value with "stats maxconn".
1083
Willy Tarreau6a06a402007-07-15 20:15:28 +02001084uid <number>
1085 Changes the process' user ID to <number>. It is recommended that the user ID
1086 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
1087 be started with superuser privileges in order to be able to switch to another
1088 one. See also "gid" and "user".
1089
1090ulimit-n <number>
1091 Sets the maximum number of per-process file-descriptors to <number>. By
1092 default, it is automatically computed, so it is recommended not to use this
1093 option.
1094
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001095unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
1096 [ group <group> ] [ gid <gid> ]
1097
1098 Fixes common settings to UNIX listening sockets declared in "bind" statements.
1099 This is mainly used to simplify declaration of those UNIX sockets and reduce
1100 the risk of errors, since those settings are most commonly required but are
1101 also process-specific. The <prefix> setting can be used to force all socket
1102 path to be relative to that directory. This might be needed to access another
1103 component's chroot. Note that those paths are resolved before haproxy chroots
1104 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
1105 all have the same meaning as their homonyms used by the "bind" statement. If
1106 both are specified, the "bind" statement has priority, meaning that the
1107 "unix-bind" settings may be seen as process-wide default settings.
1108
Willy Tarreau1d549722016-02-16 12:41:57 +01001109unsetenv [<name> ...]
1110 Removes environment variables specified in arguments. This can be useful to
1111 hide some sensitive information that are occasionally inherited from the
1112 user's environment during some operations. Variables which did not exist are
1113 silently ignored so that after the operation, it is certain that none of
1114 these variables remain. The changes immediately take effect so that the next
1115 line in the configuration file will not see these variables. See also
1116 "setenv", "presetenv", and "resetenv".
1117
Willy Tarreau6a06a402007-07-15 20:15:28 +02001118user <user name>
1119 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
1120 See also "uid" and "group".
1121
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02001122node <name>
1123 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
1124
1125 This statement is useful in HA configurations where two or more processes or
1126 servers share the same IP address. By setting a different node-name on all
1127 nodes, it becomes easy to immediately spot what server is handling the
1128 traffic.
1129
1130description <text>
1131 Add a text that describes the instance.
1132
1133 Please note that it is required to escape certain characters (# for example)
1134 and this text is inserted into a html page so you should avoid using
1135 "<" and ">" characters.
1136
Thomas Holmesdb04f192015-05-18 13:21:39 +0100113751degrees-data-file <file path>
1138 The path of the 51Degrees data file to provide device detection services. The
Davor Ocelice9ed2812017-12-25 17:49:28 +01001139 file should be unzipped and accessible by HAProxy with relevant permissions.
Thomas Holmesdb04f192015-05-18 13:21:39 +01001140
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001141 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001142 compiled with USE_51DEGREES.
1143
Ben Shillitof25e8e52016-12-02 14:25:37 +0000114451degrees-property-name-list [<string> ...]
Thomas Holmesdb04f192015-05-18 13:21:39 +01001145 A list of 51Degrees property names to be load from the dataset. A full list
1146 of names is available on the 51Degrees website:
1147 https://51degrees.com/resources/property-dictionary
1148
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001149 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001150 compiled with USE_51DEGREES.
1151
Dragan Dosen93b38d92015-06-29 16:43:25 +0200115251degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +01001153 A char that will be appended to every property value in a response header
1154 containing 51Degrees results. If not set that will be set as ','.
1155
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001156 Please note that this option is only available when haproxy has been
1157 compiled with USE_51DEGREES.
1158
115951degrees-cache-size <number>
1160 Sets the size of the 51Degrees converter cache to <number> entries. This
1161 is an LRU cache which reminds previous device detections and their results.
1162 By default, this cache is disabled.
1163
1164 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001165 compiled with USE_51DEGREES.
1166
scientiamobiled0027ed2016-11-04 10:55:08 +01001167wurfl-data-file <file path>
1168 The path of the WURFL data file to provide device detection services. The
1169 file should be accessible by HAProxy with relevant permissions.
1170
1171 Please note that this option is only available when haproxy has been compiled
1172 with USE_WURFL=1.
1173
1174wurfl-information-list [<capability>]*
1175 A space-delimited list of WURFL capabilities, virtual capabilities, property
1176 names we plan to use in injected headers. A full list of capability and
1177 virtual capability names is available on the Scientiamobile website :
1178
1179 https://www.scientiamobile.com/wurflCapability
1180
1181 Valid WURFL properties are:
1182 - wurfl_id Contains the device ID of the matched device.
1183
1184 - wurfl_root_id Contains the device root ID of the matched
1185 device.
1186
1187 - wurfl_isdevroot Tells if the matched device is a root device.
1188 Possible values are "TRUE" or "FALSE".
1189
1190 - wurfl_useragent The original useragent coming with this
1191 particular web request.
1192
1193 - wurfl_api_version Contains a string representing the currently
1194 used Libwurfl API version.
1195
1196 - wurfl_engine_target Contains a string representing the currently
1197 set WURFL Engine Target. Possible values are
1198 "HIGH_ACCURACY", "HIGH_PERFORMANCE", "INVALID".
1199
1200 - wurfl_info A string containing information on the parsed
1201 wurfl.xml and its full path.
1202
1203 - wurfl_last_load_time Contains the UNIX timestamp of the last time
1204 WURFL has been loaded successfully.
1205
1206 - wurfl_normalized_useragent The normalized useragent.
1207
1208 - wurfl_useragent_priority The user agent priority used by WURFL.
1209
1210 Please note that this option is only available when haproxy has been compiled
1211 with USE_WURFL=1.
1212
1213wurfl-information-list-separator <char>
1214 A char that will be used to separate values in a response header containing
1215 WURFL results. If not set that a comma (',') will be used by default.
1216
1217 Please note that this option is only available when haproxy has been compiled
1218 with USE_WURFL=1.
1219
1220wurfl-patch-file [<file path>]
1221 A list of WURFL patch file paths. Note that patches are loaded during startup
1222 thus before the chroot.
1223
1224 Please note that this option is only available when haproxy has been compiled
1225 with USE_WURFL=1.
1226
1227wurfl-engine-mode { accuracy | performance }
1228 Sets the WURFL engine target. You can choose between 'accuracy' or
1229 'performance' targets. In performance mode, desktop web browser detection is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001230 done programmatically without referencing the WURFL data. As a result, most
scientiamobiled0027ed2016-11-04 10:55:08 +01001231 desktop web browsers are returned as generic_web_browser WURFL ID for
Davor Ocelice9ed2812017-12-25 17:49:28 +01001232 performance. If either performance or accuracy are not defined, performance
scientiamobiled0027ed2016-11-04 10:55:08 +01001233 mode is enabled by default.
1234
1235 Please note that this option is only available when haproxy has been compiled
1236 with USE_WURFL=1.
1237
1238wurfl-cache-size <U>[,<D>]
1239 Sets the WURFL caching strategy. Here <U> is the Useragent cache size, and
1240 <D> is the internal device cache size. There are three possibilities here :
1241 - "0" : no cache is used.
1242 - <U> : the Single LRU cache is used, the size is expressed in elements.
1243 - <U>,<D> : the Double LRU cache is used, both sizes are in elements. This is
1244 the highest performing option.
1245
1246 Please note that this option is only available when haproxy has been compiled
1247 with USE_WURFL=1.
1248
1249wurfl-useragent-priority { plain | sideloaded_browser }
1250 Tells WURFL if it should prioritize use of the plain user agent ('plain')
1251 over the default sideloaded browser user agent ('sideloaded_browser').
1252
1253 Please note that this option is only available when haproxy has been compiled
1254 with USE_WURFL=1.
1255
Willy Tarreau6a06a402007-07-15 20:15:28 +02001256
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012573.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +02001258-----------------------
1259
Willy Tarreau1746eec2014-04-25 10:46:47 +02001260max-spread-checks <delay in milliseconds>
1261 By default, haproxy tries to spread the start of health checks across the
1262 smallest health check interval of all the servers in a farm. The principle is
1263 to avoid hammering services running on the same server. But when using large
1264 check intervals (10 seconds or more), the last servers in the farm take some
1265 time before starting to be tested, which can be a problem. This parameter is
1266 used to enforce an upper bound on delay between the first and the last check,
1267 even if the servers' check intervals are larger. When servers run with
1268 shorter intervals, their intervals will be respected though.
1269
Willy Tarreau6a06a402007-07-15 20:15:28 +02001270maxconn <number>
1271 Sets the maximum per-process number of concurrent connections to <number>. It
1272 is equivalent to the command-line argument "-n". Proxies will stop accepting
1273 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +02001274 automatically adjusted according to this value. See also "ulimit-n". Note:
1275 the "select" poller cannot reliably use more than 1024 file descriptors on
1276 some platforms. If your platform only supports select and reports "select
1277 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaud0256482015-01-15 21:45:22 +01001278 below 500 in general). If this value is not set, it will default to the value
1279 set in DEFAULT_MAXCONN at build time (reported in haproxy -vv) if no memory
1280 limit is enforced, or will be computed based on the memory limit, the buffer
1281 size, memory allocated to compression, SSL cache size, and use or not of SSL
1282 and the associated maxsslconn (which can also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +02001283
Willy Tarreau81c25d02011-09-07 15:17:21 +02001284maxconnrate <number>
1285 Sets the maximum per-process number of connections per second to <number>.
1286 Proxies will stop accepting connections when this limit is reached. It can be
1287 used to limit the global capacity regardless of each frontend capacity. It is
1288 important to note that this can only be used as a service protection measure,
1289 as there will not necessarily be a fair share between frontends when the
1290 limit is reached, so it's a good idea to also limit each frontend to some
1291 value close to its expected share. Also, lowering tune.maxaccept can improve
1292 fairness.
1293
William Lallemandd85f9172012-11-09 17:05:39 +01001294maxcomprate <number>
1295 Sets the maximum per-process input compression rate to <number> kilobytes
Davor Ocelice9ed2812017-12-25 17:49:28 +01001296 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +01001297 level will be decreased during the session. If the maximum is reached at the
1298 beginning of a session, the session will not compress at all. If the maximum
1299 is not reached, the compression level will be increased up to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001300 tune.comp.maxlevel. A value of zero means there is no limit, this is the
William Lallemandd85f9172012-11-09 17:05:39 +01001301 default value.
1302
William Lallemand072a2bf2012-11-20 17:01:01 +01001303maxcompcpuusage <number>
1304 Sets the maximum CPU usage HAProxy can reach before stopping the compression
1305 for new requests or decreasing the compression level of current requests.
1306 It works like 'maxcomprate' but measures CPU usage instead of incoming data
1307 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
1308 case of multiple processes (nbproc > 1), each process manages its individual
1309 usage. A value of 100 disable the limit. The default value is 100. Setting
1310 a lower value will prevent the compression work from slowing the whole
1311 process down and from introducing high latencies.
1312
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001313maxpipes <number>
1314 Sets the maximum per-process number of pipes to <number>. Currently, pipes
1315 are only used by kernel-based tcp splicing. Since a pipe contains two file
1316 descriptors, the "ulimit-n" value will be increased accordingly. The default
1317 value is maxconn/4, which seems to be more than enough for most heavy usages.
1318 The splice code dynamically allocates and releases pipes, and can fall back
1319 to standard copy, so setting this value too low may only impact performance.
1320
Willy Tarreau93e7c002013-10-07 18:51:07 +02001321maxsessrate <number>
1322 Sets the maximum per-process number of sessions per second to <number>.
1323 Proxies will stop accepting connections when this limit is reached. It can be
1324 used to limit the global capacity regardless of each frontend capacity. It is
1325 important to note that this can only be used as a service protection measure,
1326 as there will not necessarily be a fair share between frontends when the
1327 limit is reached, so it's a good idea to also limit each frontend to some
1328 value close to its expected share. Also, lowering tune.maxaccept can improve
1329 fairness.
1330
Willy Tarreau403edff2012-09-06 11:58:37 +02001331maxsslconn <number>
1332 Sets the maximum per-process number of concurrent SSL connections to
1333 <number>. By default there is no SSL-specific limit, which means that the
1334 global maxconn setting will apply to all connections. Setting this limit
1335 avoids having openssl use too much memory and crash when malloc returns NULL
1336 (since it unfortunately does not reliably check for such conditions). Note
1337 that the limit applies both to incoming and outgoing connections, so one
1338 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +01001339 If this value is not set, but a memory limit is enforced, this value will be
1340 automatically computed based on the memory limit, maxconn, the buffer size,
1341 memory allocated to compression, SSL cache size, and use of SSL in either
1342 frontends, backends or both. If neither maxconn nor maxsslconn are specified
1343 when there is a memory limit, haproxy will automatically adjust these values
1344 so that 100% of the connections can be made over SSL with no risk, and will
1345 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +02001346
Willy Tarreaue43d5322013-10-07 20:01:52 +02001347maxsslrate <number>
1348 Sets the maximum per-process number of SSL sessions per second to <number>.
1349 SSL listeners will stop accepting connections when this limit is reached. It
1350 can be used to limit the global SSL CPU usage regardless of each frontend
1351 capacity. It is important to note that this can only be used as a service
1352 protection measure, as there will not necessarily be a fair share between
1353 frontends when the limit is reached, so it's a good idea to also limit each
1354 frontend to some value close to its expected share. It is also important to
1355 note that the sessions are accounted before they enter the SSL stack and not
1356 after, which also protects the stack against bad handshakes. Also, lowering
1357 tune.maxaccept can improve fairness.
1358
William Lallemand9d5f5482012-11-07 16:12:57 +01001359maxzlibmem <number>
1360 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
1361 When the maximum amount is reached, future sessions will not compress as long
1362 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01001363 The default value is 0. The value is available in bytes on the UNIX socket
1364 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
1365 "ZlibMemUsage" in bytes.
1366
Willy Tarreau6a06a402007-07-15 20:15:28 +02001367noepoll
1368 Disables the use of the "epoll" event polling system on Linux. It is
1369 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001370 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001371
1372nokqueue
1373 Disables the use of the "kqueue" event polling system on BSD. It is
1374 equivalent to the command-line argument "-dk". The next polling system
1375 used will generally be "poll". See also "nopoll".
1376
1377nopoll
1378 Disables the use of the "poll" event polling system. It is equivalent to the
1379 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001380 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001381 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001382
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001383nosplice
1384 Disables the use of kernel tcp splicing between sockets on Linux. It is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001385 equivalent to the command line argument "-dS". Data will then be copied
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001386 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001387 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001388 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
1389 be used. This option makes it easier to globally disable kernel splicing in
1390 case of doubt. See also "option splice-auto", "option splice-request" and
1391 "option splice-response".
1392
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001393nogetaddrinfo
1394 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
1395 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
1396
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00001397noreuseport
1398 Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the
1399 command line argument "-dR".
1400
Willy Tarreaufe255b72007-10-14 23:09:26 +02001401spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09001402 Sometimes it is desirable to avoid sending agent and health checks to
1403 servers at exact intervals, for instance when many logical servers are
1404 located on the same physical server. With the help of this parameter, it
1405 becomes possible to add some randomness in the check interval between 0
1406 and +/- 50%. A value between 2 and 5 seems to show good results. The
1407 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02001408
Davor Ocelice9ed2812017-12-25 17:49:28 +01001409ssl-engine <name> [algo <comma-separated list of algorithms>]
Grant Zhang872f9c22017-01-21 01:10:18 +00001410 Sets the OpenSSL engine to <name>. List of valid values for <name> may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01001411 obtained using the command "openssl engine". This statement may be used
Grant Zhang872f9c22017-01-21 01:10:18 +00001412 multiple times, it will simply enable multiple crypto engines. Referencing an
1413 unsupported engine will prevent haproxy from starting. Note that many engines
1414 will lead to lower HTTPS performance than pure software with recent
1415 processors. The optional command "algo" sets the default algorithms an ENGINE
1416 will supply using the OPENSSL function ENGINE_set_default_string(). A value
Davor Ocelice9ed2812017-12-25 17:49:28 +01001417 of "ALL" uses the engine for all cryptographic operations. If no list of
1418 algo is specified then the value of "ALL" is used. A comma-separated list
Grant Zhang872f9c22017-01-21 01:10:18 +00001419 of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND,
1420 CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that
1421 openssl configuration file uses:
1422 https://www.openssl.org/docs/man1.0.2/apps/config.html
1423
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001424ssl-mode-async
1425 Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS
Emeric Brun3854e012017-05-17 20:42:48 +02001426 I/O operations if asynchronous capable SSL engines are used. The current
Emeric Brunb5e42a82017-06-06 12:35:14 +00001427 implementation supports a maximum of 32 engines. The Openssl ASYNC API
1428 doesn't support moving read/write buffers and is not compliant with
1429 haproxy's buffer management. So the asynchronous mode is disabled on
1430 read/write operations (it is only enabled during initial and reneg
1431 handshakes).
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001432
Willy Tarreau33cb0652014-12-23 22:52:37 +01001433tune.buffers.limit <number>
1434 Sets a hard limit on the number of buffers which may be allocated per process.
1435 The default value is zero which means unlimited. The minimum non-zero value
1436 will always be greater than "tune.buffers.reserve" and should ideally always
1437 be about twice as large. Forcing this value can be particularly useful to
1438 limit the amount of memory a process may take, while retaining a sane
Davor Ocelice9ed2812017-12-25 17:49:28 +01001439 behavior. When this limit is reached, sessions which need a buffer wait for
Willy Tarreau33cb0652014-12-23 22:52:37 +01001440 another one to be released by another session. Since buffers are dynamically
1441 allocated and released, the waiting time is very short and not perceptible
1442 provided that limits remain reasonable. In fact sometimes reducing the limit
1443 may even increase performance by increasing the CPU cache's efficiency. Tests
1444 have shown good results on average HTTP traffic with a limit to 1/10 of the
1445 expected global maxconn setting, which also significantly reduces memory
1446 usage. The memory savings come from the fact that a number of connections
1447 will not allocate 2*tune.bufsize. It is best not to touch this value unless
1448 advised to do so by an haproxy core developer.
1449
Willy Tarreau1058ae72014-12-23 22:40:40 +01001450tune.buffers.reserve <number>
1451 Sets the number of buffers which are pre-allocated and reserved for use only
1452 during memory shortage conditions resulting in failed memory allocations. The
1453 minimum value is 2 and is also the default. There is no reason a user would
1454 want to change this value, it's mostly aimed at haproxy core developers.
1455
Willy Tarreau27a674e2009-08-17 07:23:33 +02001456tune.bufsize <number>
1457 Sets the buffer size to this size (in bytes). Lower values allow more
1458 sessions to coexist in the same amount of RAM, and higher values allow some
1459 applications with very large cookies to work. The default value is 16384 and
1460 can be changed at build time. It is strongly recommended not to change this
1461 from the default value, as very low values will break some services such as
1462 statistics, and values larger than default size will increase memory usage,
1463 possibly causing the system to run out of memory. At least the global maxconn
Willy Tarreau45a66cc2017-11-24 11:28:00 +01001464 parameter should be decreased by the same factor as this one is increased. In
1465 addition, use of HTTP/2 mandates that this value must be 16384 or more. If an
1466 HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04001467 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
1468 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +02001469
Willy Tarreau43961d52010-10-04 20:39:20 +02001470tune.chksize <number>
1471 Sets the check buffer size to this size (in bytes). Higher values may help
1472 find string or regex patterns in very large pages, though doing so may imply
1473 more memory and CPU usage. The default value is 16384 and can be changed at
1474 build time. It is not recommended to change this value, but to use better
1475 checks whenever possible.
1476
William Lallemandf3747832012-11-09 12:33:10 +01001477tune.comp.maxlevel <number>
1478 Sets the maximum compression level. The compression level affects CPU
1479 usage during compression. This value affects CPU usage during compression.
1480 Each session using compression initializes the compression algorithm with
1481 this value. The default value is 1.
1482
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02001483tune.h2.header-table-size <number>
1484 Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and
1485 cannot be larger than 65536 bytes. A larger value may help certain clients
1486 send more compact requests, depending on their capabilities. This amount of
1487 memory is consumed for each HTTP/2 connection. It is recommended not to
1488 change it.
1489
Willy Tarreaue6baec02017-07-27 11:45:11 +02001490tune.h2.initial-window-size <number>
1491 Sets the HTTP/2 initial window size, which is the number of bytes the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01001492 can upload before waiting for an acknowledgment from haproxy. This setting
1493 only affects payload contents (i.e. the body of POST requests), not headers.
Willy Tarreaue6baec02017-07-27 11:45:11 +02001494 The default value is 65535, which roughly allows up to 5 Mbps of upload
1495 bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps
1496 over a 1-ms local network. It can make sense to increase this value to allow
1497 faster uploads, or to reduce it to increase fairness when dealing with many
1498 clients. It doesn't affect resource usage.
1499
Willy Tarreau5242ef82017-07-27 11:47:28 +02001500tune.h2.max-concurrent-streams <number>
1501 Sets the HTTP/2 maximum number of concurrent streams per connection (ie the
1502 number of outstanding requests on a single connection). The default value is
1503 100. A larger one may slightly improve page load time for complex sites when
1504 visited over high latency networks, but increases the amount of resources a
1505 single client may allocate. A value of zero disables the limit so a single
1506 client may create as many streams as allocatable by haproxy. It is highly
1507 recommended not to change this value.
1508
Willy Tarreau193b8c62012-11-22 00:17:38 +01001509tune.http.cookielen <number>
1510 Sets the maximum length of captured cookies. This is the maximum value that
1511 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
1512 will automatically be truncated to this one. It is important not to set too
1513 high a value because all cookie captures still allocate this size whatever
1514 their configured value (they share a same pool). This value is per request
1515 per response, so the memory allocated is twice this value per connection.
1516 When not specified, the limit is set to 63 characters. It is recommended not
1517 to change this value.
1518
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001519tune.http.logurilen <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001520 Sets the maximum length of request URI in logs. This prevents truncating long
1521 request URIs with valuable query strings in log lines. This is not related
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001522 to syslog limits. If you increase this limit, you may also increase the
Davor Ocelice9ed2812017-12-25 17:49:28 +01001523 'log ... len yyy' parameter. Your syslog daemon may also need specific
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001524 configuration directives too.
1525 The default value is 1024.
1526
Willy Tarreauac1932d2011-10-24 19:14:41 +02001527tune.http.maxhdr <number>
1528 Sets the maximum number of headers in a request. When a request comes with a
1529 number of headers greater than this value (including the first line), it is
1530 rejected with a "400 Bad Request" status code. Similarly, too large responses
1531 are blocked with "502 Bad Gateway". The default value is 101, which is enough
1532 for all usages, considering that the widely deployed Apache server uses the
1533 same limit. It can be useful to push this limit further to temporarily allow
Christopher Faulet50174f32017-06-21 16:31:35 +02001534 a buggy application to work by the time it gets fixed. The accepted range is
1535 1..32767. Keep in mind that each new header consumes 32bits of memory for
1536 each session, so don't push this limit too high.
Willy Tarreauac1932d2011-10-24 19:14:41 +02001537
Willy Tarreau7e312732014-02-12 16:35:14 +01001538tune.idletimer <timeout>
1539 Sets the duration after which haproxy will consider that an empty buffer is
1540 probably associated with an idle stream. This is used to optimally adjust
1541 some packet sizes while forwarding large and small data alternatively. The
1542 decision to use splice() or to send large buffers in SSL is modulated by this
1543 parameter. The value is in milliseconds between 0 and 65535. A value of zero
1544 means that haproxy will not try to detect idle streams. The default is 1000,
Davor Ocelice9ed2812017-12-25 17:49:28 +01001545 which seems to correctly detect end user pauses (e.g. read a page before
Willy Tarreau7e312732014-02-12 16:35:14 +01001546 clicking). There should be not reason for changing this value. Please check
1547 tune.ssl.maxrecord below.
1548
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001549tune.lua.forced-yield <number>
1550 This directive forces the Lua engine to execute a yield each <number> of
Tim Düsterhus4896c442016-11-29 02:15:19 +01001551 instructions executed. This permits interrupting a long script and allows the
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001552 HAProxy scheduler to process other tasks like accepting connections or
1553 forwarding traffic. The default value is 10000 instructions. If HAProxy often
Davor Ocelice9ed2812017-12-25 17:49:28 +01001554 executes some Lua code but more responsiveness is required, this value can be
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001555 lowered. If the Lua code is quite long and its result is absolutely required
1556 to process the data, the <number> can be increased.
1557
Willy Tarreau32f61e22015-03-18 17:54:59 +01001558tune.lua.maxmem
1559 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
1560 default it is zero which means unlimited. It is important to set a limit to
1561 ensure that a bug in a script will not result in the system running out of
1562 memory.
1563
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001564tune.lua.session-timeout <timeout>
1565 This is the execution timeout for the Lua sessions. This is useful for
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001566 preventing infinite loops or spending too much time in Lua. This timeout
1567 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001568 not taken in account. The default timeout is 4s.
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001569
1570tune.lua.task-timeout <timeout>
1571 Purpose is the same as "tune.lua.session-timeout", but this timeout is
1572 dedicated to the tasks. By default, this timeout isn't set because a task may
1573 remain alive during of the lifetime of HAProxy. For example, a task used to
1574 check servers.
1575
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001576tune.lua.service-timeout <timeout>
1577 This is the execution timeout for the Lua services. This is useful for
1578 preventing infinite loops or spending too much time in Lua. This timeout
1579 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001580 not taken in account. The default timeout is 4s.
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001581
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001582tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01001583 Sets the maximum number of consecutive connections a process may accept in a
1584 row before switching to other work. In single process mode, higher numbers
1585 give better performance at high connection rates. However in multi-process
1586 modes, keeping a bit of fairness between processes generally is better to
1587 increase performance. This value applies individually to each listener, so
1588 that the number of processes a listener is bound to is taken into account.
1589 This value defaults to 64. In multi-process mode, it is divided by twice
1590 the number of processes the listener is bound to. Setting this value to -1
1591 completely disables the limitation. It should normally not be needed to tweak
1592 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001593
1594tune.maxpollevents <number>
1595 Sets the maximum amount of events that can be processed at once in a call to
1596 the polling system. The default value is adapted to the operating system. It
1597 has been noticed that reducing it below 200 tends to slightly decrease
1598 latency at the expense of network bandwidth, and increasing it above 200
1599 tends to trade latency for slightly increased bandwidth.
1600
Willy Tarreau27a674e2009-08-17 07:23:33 +02001601tune.maxrewrite <number>
1602 Sets the reserved buffer space to this size in bytes. The reserved space is
1603 used for header rewriting or appending. The first reads on sockets will never
1604 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
1605 bufsize, though that does not make much sense since there are rarely large
1606 numbers of headers to add. Setting it too high prevents processing of large
1607 requests or responses. Setting it too low prevents addition of new headers
1608 to already large requests or to POST requests. It is generally wise to set it
1609 to about 1024. It is automatically readjusted to half of bufsize if it is
1610 larger than that. This means you don't have to worry about it when changing
1611 bufsize.
1612
Willy Tarreauf3045d22015-04-29 16:24:50 +02001613tune.pattern.cache-size <number>
1614 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
1615 cache which reminds previous lookups and their results. It is used by ACLs
1616 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
1617 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
1618 strings. It applies to pattern expressions which means that it will be able
1619 to memorize the result of a lookup among all the patterns specified on a
1620 configuration line (including all those loaded from files). It automatically
1621 invalidates entries which are updated using HTTP actions or on the CLI. The
1622 default cache size is set to 10000 entries, which limits its footprint to
1623 about 5 MB on 32-bit systems and 8 MB on 64-bit systems. There is a very low
1624 risk of collision in this cache, which is in the order of the size of the
1625 cache divided by 2^64. Typically, at 10000 requests per second with the
1626 default cache size of 10000 entries, there's 1% chance that a brute force
1627 attack could cause a single collision after 60 years, or 0.1% after 6 years.
1628 This is considered much lower than the risk of a memory corruption caused by
1629 aging components. If this is not acceptable, the cache can be disabled by
1630 setting this parameter to 0.
1631
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02001632tune.pipesize <number>
1633 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
1634 are the default size for the system. But sometimes when using TCP splicing,
1635 it can improve performance to increase pipe sizes, especially if it is
1636 suspected that pipes are not filled and that many calls to splice() are
1637 performed. This has an impact on the kernel's memory footprint, so this must
1638 not be changed if impacts are not understood.
1639
Willy Tarreaue803de22010-01-21 17:43:04 +01001640tune.rcvbuf.client <number>
1641tune.rcvbuf.server <number>
1642 Forces the kernel socket receive buffer size on the client or the server side
1643 to the specified value in bytes. This value applies to all TCP/HTTP frontends
1644 and backends. It should normally never be set, and the default size (0) lets
1645 the kernel autotune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001646 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01001647 order to save kernel memory by preventing it from buffering too large amounts
1648 of received data. Lower values will significantly increase CPU usage though.
1649
Willy Tarreaub22fc302015-12-14 12:04:35 +01001650tune.recv_enough <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001651 HAProxy uses some hints to detect that a short read indicates the end of the
Willy Tarreaub22fc302015-12-14 12:04:35 +01001652 socket buffers. One of them is that a read returns more than <recv_enough>
1653 bytes, which defaults to 10136 (7 segments of 1448 each). This default value
1654 may be changed by this setting to better deal with workloads involving lots
1655 of short messages such as telnet or SSH sessions.
1656
Olivier Houchard1599b802018-05-24 18:59:04 +02001657tune.runqueue-depth <number>
1658 Sets the maxinum amount of task that can be processed at once when running
1659 tasks. The default value is 200. Increasing it may incur latency when
1660 dealing with I/Os, making it too small can incur extra overhead.
1661
Willy Tarreaue803de22010-01-21 17:43:04 +01001662tune.sndbuf.client <number>
1663tune.sndbuf.server <number>
1664 Forces the kernel socket send buffer size on the client or the server side to
1665 the specified value in bytes. This value applies to all TCP/HTTP frontends
1666 and backends. It should normally never be set, and the default size (0) lets
1667 the kernel autotune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001668 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01001669 order to save kernel memory by preventing it from buffering too large amounts
1670 of received data. Lower values will significantly increase CPU usage though.
1671 Another use case is to prevent write timeouts with extremely slow clients due
1672 to the kernel waiting for a large part of the buffer to be read before
1673 notifying haproxy again.
1674
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001675tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01001676 Sets the size of the global SSL session cache, in a number of blocks. A block
1677 is large enough to contain an encoded session without peer certificate.
1678 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001679 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01001680 200 bytes of memory. The default value may be forced at build time, otherwise
Davor Ocelice9ed2812017-12-25 17:49:28 +01001681 defaults to 20000. When the cache is full, the most idle entries are purged
Emeric Brunaf9619d2012-11-28 18:47:52 +01001682 and reassigned. Higher values reduce the occurrence of such a purge, hence
1683 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1684 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001685 and are shared between all processes if "nbproc" is greater than 1. Setting
1686 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001687
Emeric Brun8dc60392014-05-09 13:52:00 +02001688tune.ssl.force-private-cache
Lukas Tribus27935782018-10-01 02:00:16 +02001689 This option disables SSL session cache sharing between all processes. It
Emeric Brun8dc60392014-05-09 13:52:00 +02001690 should normally not be used since it will force many renegotiations due to
1691 clients hitting a random process. But it may be required on some operating
1692 systems where none of the SSL cache synchronization method may be used. In
1693 this case, adding a first layer of hash-based load balancing before the SSL
1694 layer might limit the impact of the lack of session sharing.
1695
Emeric Brun4f65bff2012-11-16 15:11:00 +01001696tune.ssl.lifetime <timeout>
1697 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001698 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001699 does not guarantee that sessions will last that long, because if the cache is
1700 full, the longest idle sessions will be purged despite their configured
1701 lifetime. The real usefulness of this setting is to prevent sessions from
1702 being used for too long.
1703
Willy Tarreaubfd59462013-02-21 07:46:09 +01001704tune.ssl.maxrecord <number>
1705 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
1706 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
1707 data only once it has received a full record. With large records, it means
1708 that clients might have to download up to 16kB of data before starting to
1709 process them. Limiting the value can improve page load times on browsers
1710 located over high latency or low bandwidth networks. It is suggested to find
1711 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
1712 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
1713 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
1714 2859 gave good results during tests. Use "strace -e trace=write" to find the
Davor Ocelice9ed2812017-12-25 17:49:28 +01001715 best value. HAProxy will automatically switch to this setting after an idle
Willy Tarreau7e312732014-02-12 16:35:14 +01001716 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01001717
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001718tune.ssl.default-dh-param <number>
1719 Sets the maximum size of the Diffie-Hellman parameters used for generating
1720 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
1721 final size will try to match the size of the server's RSA (or DSA) key (e.g,
1722 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
1723 this maximum value. Default value if 1024. Only 1024 or higher values are
1724 allowed. Higher values will increase the CPU load, and values greater than
1725 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02001726 used if static Diffie-Hellman parameters are supplied either directly
1727 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001728
Christopher Faulet31af49d2015-06-09 17:29:50 +02001729tune.ssl.ssl-ctx-cache-size <number>
1730 Sets the size of the cache used to store generated certificates to <number>
1731 entries. This is a LRU cache. Because generating a SSL certificate
1732 dynamically is expensive, they are cached. The default cache size is set to
1733 1000 entries.
1734
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01001735tune.ssl.capture-cipherlist-size <number>
1736 Sets the maximum size of the buffer used for capturing client-hello cipher
1737 list. If the value is 0 (default value) the capture is disabled, otherwise
1738 a buffer is allocated for each SSL/TLS connection.
1739
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001740tune.vars.global-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01001741tune.vars.proc-max-size <size>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001742tune.vars.reqres-max-size <size>
1743tune.vars.sess-max-size <size>
1744tune.vars.txn-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01001745 These five tunes help to manage the maximum amount of memory used by the
1746 variables system. "global" limits the overall amount of memory available for
1747 all scopes. "proc" limits the memory for the process scope, "sess" limits the
1748 memory for the session scope, "txn" for the transaction scope, and "reqres"
1749 limits the memory for each request or response processing.
1750 Memory accounting is hierarchical, meaning more coarse grained limits include
1751 the finer grained ones: "proc" includes "sess", "sess" includes "txn", and
1752 "txn" includes "reqres".
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001753
Daniel Schneller0b547052016-03-21 20:46:57 +01001754 For example, when "tune.vars.sess-max-size" is limited to 100,
1755 "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed
1756 100 either. If we create a variable "txn.var" that contains 100 bytes,
1757 all available space is consumed.
1758 Notice that exceeding the limits at runtime will not result in an error
1759 message, but values might be cut off or corrupted. So make sure to accurately
1760 plan for the amount of space needed to store all your variables.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001761
William Lallemanda509e4c2012-11-07 16:54:34 +01001762tune.zlib.memlevel <number>
1763 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001764 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01001765 state. A value of 1 uses minimum memory but is slow and reduces compression
Davor Ocelice9ed2812017-12-25 17:49:28 +01001766 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
William Lallemanda509e4c2012-11-07 16:54:34 +01001767 between 1 and 9. The default value is 8.
1768
1769tune.zlib.windowsize <number>
1770 Sets the window size (the size of the history buffer) as a parameter of the
1771 zlib initialization for each session. Larger values of this parameter result
Davor Ocelice9ed2812017-12-25 17:49:28 +01001772 in better compression at the expense of memory usage. Can be a value between
1773 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001774
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017753.3. Debugging
1776--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02001777
1778debug
1779 Enables debug mode which dumps to stdout all exchanges, and disables forking
1780 into background. It is the equivalent of the command-line argument "-d". It
1781 should never be used in a production configuration since it may prevent full
1782 system startup.
1783
1784quiet
1785 Do not display any message during startup. It is equivalent to the command-
1786 line argument "-q".
1787
Emeric Brunf099e792010-09-27 12:05:28 +02001788
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010017893.4. Userlists
1790--------------
1791It is possible to control access to frontend/backend/listen sections or to
1792http stats by allowing only authenticated and authorized users. To do this,
1793it is required to create at least one userlist and to define users.
1794
1795userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01001796 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001797 used to store authentication & authorization data for independent customers.
1798
1799group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01001800 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001801 attach users to this group by using a comma separated list of names
1802 proceeded by "users" keyword.
1803
Cyril Bontéf0c60612010-02-06 14:44:47 +01001804user <username> [password|insecure-password <password>]
1805 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001806 Adds user <username> to the current userlist. Both secure (encrypted) and
1807 insecure (unencrypted) passwords can be used. Encrypted passwords are
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01001808 evaluated using the crypt(3) function, so depending on the system's
1809 capabilities, different algorithms are supported. For example, modern Glibc
1810 based Linux systems support MD5, SHA-256, SHA-512, and, of course, the
1811 classic DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001812
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01001813 Attention: Be aware that using encrypted passwords might cause significantly
1814 increased CPU usage, depending on the number of requests, and the algorithm
1815 used. For any of the hashed variants, the password for each request must
1816 be processed through the chosen algorithm, before it can be compared to the
1817 value specified in the config file. Most current algorithms are deliberately
1818 designed to be expensive to compute to achieve resistance against brute
1819 force attacks. They do not simply salt/hash the clear text password once,
1820 but thousands of times. This can quickly become a major factor in haproxy's
1821 overall CPU consumption!
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001822
1823 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01001824 userlist L1
1825 group G1 users tiger,scott
1826 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001827
Cyril Bontéf0c60612010-02-06 14:44:47 +01001828 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
1829 user scott insecure-password elgato
1830 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001831
Cyril Bontéf0c60612010-02-06 14:44:47 +01001832 userlist L2
1833 group G1
1834 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001835
Cyril Bontéf0c60612010-02-06 14:44:47 +01001836 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
1837 user scott insecure-password elgato groups G1,G2
1838 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001839
1840 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001841
Emeric Brunf099e792010-09-27 12:05:28 +02001842
18433.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02001844----------
Emeric Brun94900952015-06-11 18:25:54 +02001845It is possible to propagate entries of any data-types in stick-tables between
1846several haproxy instances over TCP connections in a multi-master fashion. Each
1847instance pushes its local updates and insertions to remote peers. The pushed
1848values overwrite remote ones without aggregation. Interrupted exchanges are
1849automatically detected and recovered from the last known point.
1850In addition, during a soft restart, the old process connects to the new one
1851using such a TCP connection to push all its entries before the new process
1852tries to connect to other peers. That ensures very fast replication during a
1853reload, it typically takes a fraction of a second even for large tables.
1854Note that Server IDs are used to identify servers remotely, so it is important
1855that configurations look similar or at least that the same IDs are forced on
1856each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02001857
1858peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001859 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001860 which is referenced by one or more stick-tables.
1861
Willy Tarreau77e4bd12015-05-01 20:02:17 +02001862disabled
1863 Disables a peers section. It disables both listening and any synchronization
1864 related to this section. This is provided to disable synchronization of stick
1865 tables without having to comment out all "peers" references.
1866
1867enable
1868 This re-enables a disabled peers section which was previously disabled.
1869
Emeric Brunf099e792010-09-27 12:05:28 +02001870peer <peername> <ip>:<port>
1871 Defines a peer inside a peers section.
1872 If <peername> is set to the local peer name (by default hostname, or forced
1873 using "-L" command line option), haproxy will listen for incoming remote peer
1874 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1875 to join the remote peer, and <peername> is used at the protocol level to
1876 identify and validate the remote peer on the server side.
1877
1878 During a soft restart, local peer <ip>:<port> is used by the old instance to
1879 connect the new one and initiate a complete replication (teaching process).
1880
1881 It is strongly recommended to have the exact same peers declaration on all
1882 peers and to only rely on the "-L" command line argument to change the local
1883 peer name. This makes it easier to maintain coherent configuration files
1884 across all peers.
1885
William Lallemandb2f07452015-05-12 14:27:13 +02001886 You may want to reference some environment variables in the address
1887 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001888
Cyril Bontédc4d9032012-04-08 21:57:39 +02001889 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001890 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001891 peer haproxy1 192.168.0.1:1024
1892 peer haproxy2 192.168.0.2:1024
1893 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001894
1895 backend mybackend
1896 mode tcp
1897 balance roundrobin
1898 stick-table type ip size 20k peers mypeers
1899 stick on src
1900
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001901 server srv1 192.168.0.30:80
1902 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001903
1904
Simon Horman51a1cf62015-02-03 13:00:44 +090019053.6. Mailers
1906------------
1907It is possible to send email alerts when the state of servers changes.
1908If configured email alerts are sent to each mailer that is configured
1909in a mailers section. Email is sent to mailers using SMTP.
1910
Pieter Baauw386a1272015-08-16 15:26:24 +02001911mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09001912 Creates a new mailer list with the name <mailersect>. It is an
1913 independent section which is referenced by one or more proxies.
1914
1915mailer <mailername> <ip>:<port>
1916 Defines a mailer inside a mailers section.
1917
1918 Example:
1919 mailers mymailers
1920 mailer smtp1 192.168.0.1:587
1921 mailer smtp2 192.168.0.2:587
1922
1923 backend mybackend
1924 mode tcp
1925 balance roundrobin
1926
1927 email-alert mailers mymailers
1928 email-alert from test1@horms.org
1929 email-alert to test2@horms.org
1930
1931 server srv1 192.168.0.30:80
1932 server srv2 192.168.0.31:80
1933
Pieter Baauw235fcfc2016-02-13 15:33:40 +01001934timeout mail <time>
1935 Defines the time available for a mail/connection to be made and send to
1936 the mail-server. If not defined the default value is 10 seconds. To allow
1937 for at least two SYN-ACK packets to be send during initial TCP handshake it
1938 is advised to keep this value above 4 seconds.
1939
1940 Example:
1941 mailers mymailers
1942 timeout mail 20s
1943 mailer smtp1 192.168.0.1:587
Simon Horman51a1cf62015-02-03 13:00:44 +09001944
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019454. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001946----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001947
Willy Tarreau6a06a402007-07-15 20:15:28 +02001948Proxy configuration can be located in a set of sections :
William Lallemand6e62fb62015-04-28 16:55:23 +02001949 - defaults [<name>]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001950 - frontend <name>
1951 - backend <name>
1952 - listen <name>
1953
1954A "defaults" section sets default parameters for all other sections following
1955its declaration. Those default parameters are reset by the next "defaults"
1956section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001957section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001958
1959A "frontend" section describes a set of listening sockets accepting client
1960connections.
1961
1962A "backend" section describes a set of servers to which the proxy will connect
1963to forward incoming connections.
1964
1965A "listen" section defines a complete proxy with its frontend and backend
1966parts combined in one section. It is generally useful for TCP-only traffic.
1967
Willy Tarreau0ba27502007-12-24 16:55:16 +01001968All proxy names must be formed from upper and lower case letters, digits,
1969'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1970case-sensitive, which means that "www" and "WWW" are two different proxies.
1971
1972Historically, all proxy names could overlap, it just caused troubles in the
1973logs. Since the introduction of content switching, it is mandatory that two
1974proxies with overlapping capabilities (frontend/backend) have different names.
1975However, it is still permitted that a frontend and a backend share the same
1976name, as this configuration seems to be commonly encountered.
1977
1978Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1979and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001980bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001981protocol, and can interact with it by allowing, blocking, switching, adding,
1982modifying, or removing arbitrary contents in requests or responses, based on
1983arbitrary criteria.
1984
Willy Tarreau70dffda2014-01-30 03:07:23 +01001985In HTTP mode, the processing applied to requests and responses flowing over
1986a connection depends in the combination of the frontend's HTTP options and
Christopher Faulet315b39c2018-09-21 16:26:19 +02001987the backend's. HAProxy supports 4 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +01001988
1989 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
1990 requests and responses are processed, and connections remain open but idle
1991 between responses and new requests.
1992
1993 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
1994 1.0 to 1.5-dev21 : only the first request and response are processed, and
1995 everything else is forwarded with no analysis at all. This mode should not
Christopher Faulet4212a302018-09-21 10:42:19 +02001996 be used as it creates lots of trouble with logging and HTTP processing. It
1997 is supported only on frontends.
Willy Tarreau70dffda2014-01-30 03:07:23 +01001998
Willy Tarreau70dffda2014-01-30 03:07:23 +01001999 - SCL: server close ("option http-server-close") : the server-facing
2000 connection is closed after the end of the response is received, but the
2001 client-facing connection remains open.
2002
Christopher Faulet315b39c2018-09-21 16:26:19 +02002003 - CLO: close ("option httpclose"): the connection is closed after the end of
2004 the response and "Connection: close" appended in both directions.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002005
2006The effective mode that will be applied to a connection passing through a
2007frontend and a backend can be determined by both proxy modes according to the
2008following matrix, but in short, the modes are symmetric, keep-alive is the
Christopher Faulet315b39c2018-09-21 16:26:19 +02002009weakest option and close is the strongest.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002010
Christopher Faulet315b39c2018-09-21 16:26:19 +02002011 Backend mode
Willy Tarreau70dffda2014-01-30 03:07:23 +01002012
Christopher Faulet315b39c2018-09-21 16:26:19 +02002013 | KAL | SCL | CLO
2014 ----+-----+-----+----
2015 KAL | KAL | SCL | CLO
2016 ----+-----+-----+----
2017 TUN | TUN | SCL | CLO
2018 Frontend ----+-----+-----+----
2019 mode SCL | SCL | SCL | CLO
2020 ----+-----+-----+----
2021 CLO | CLO | CLO | CLO
Willy Tarreau70dffda2014-01-30 03:07:23 +01002022
Willy Tarreau0ba27502007-12-24 16:55:16 +01002023
Willy Tarreau70dffda2014-01-30 03:07:23 +01002024
Willy Tarreauc57f0e22009-05-10 13:12:33 +020020254.1. Proxy keywords matrix
2026--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002027
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002028The following list of keywords is supported. Most of them may only be used in a
2029limited set of section types. Some of them are marked as "deprecated" because
2030they are inherited from an old syntax which may be confusing or functionally
2031limited, and there are new recommended keywords to replace them. Keywords
Davor Ocelice9ed2812017-12-25 17:49:28 +01002032marked with "(*)" can be optionally inverted using the "no" prefix, e.g. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002033option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02002034and must be disabled for a specific instance. Such options may also be prefixed
2035with "default" in order to restore default settings regardless of what has been
2036specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002037
Willy Tarreau6a06a402007-07-15 20:15:28 +02002038
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002039 keyword defaults frontend listen backend
2040------------------------------------+----------+----------+---------+---------
2041acl - X X X
Willy Tarreau294d0f02015-08-10 19:40:12 +02002042appsession - - - -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002043backlog X X X -
2044balance X - X X
2045bind - X X -
2046bind-process X X X X
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002047block (deprecated) - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002048capture cookie - X X -
2049capture request header - X X -
2050capture response header - X X -
2051clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02002052compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002053contimeout (deprecated) X - X X
2054cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02002055declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002056default-server X - X X
2057default_backend X X X -
2058description - X X X
2059disabled X X X X
2060dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002061email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09002062email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002063email-alert mailers X X X X
2064email-alert myhostname X X X X
2065email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002066enabled X X X X
2067errorfile X X X X
2068errorloc X X X X
2069errorloc302 X X X X
2070-- keyword -------------------------- defaults - frontend - listen -- backend -
2071errorloc303 X X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002072force-persist - - X X
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002073filter - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002074fullconn X - X X
2075grace X X X X
2076hash-type X - X X
2077http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01002078http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02002079http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002080http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02002081http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02002082http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02002083http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002084id - X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002085ignore-persist - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002086load-server-state-from-file X - X X
William Lallemand0f99e342011-10-12 17:50:54 +02002087log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01002088log-format X X X -
Dragan Dosen7ad31542015-09-28 17:16:47 +02002089log-format-sd X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01002090log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02002091max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002092maxconn X X X -
2093mode X X X X
2094monitor fail - X X -
2095monitor-net X X X -
2096monitor-uri X X X -
2097option abortonclose (*) X - X X
2098option accept-invalid-http-request (*) X X X -
2099option accept-invalid-http-response (*) X - X X
2100option allbackups (*) X - X X
2101option checkcache (*) X - X X
2102option clitcpka (*) X X X -
2103option contstats (*) X X X -
2104option dontlog-normal (*) X X X -
2105option dontlognull (*) X X X -
Christopher Faulet315b39c2018-09-21 16:26:19 +02002106option forceclose (deprectated) (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002107-- keyword -------------------------- defaults - frontend - listen -- backend -
2108option forwardfor X X X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02002109option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02002110option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01002111option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02002112option http-no-delay (*) X X X X
Christopher Faulet98db9762018-09-21 10:25:19 +02002113option http-pretend-keepalive (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002114option http-server-close (*) X X X X
Christopher Faulet4212a302018-09-21 10:42:19 +02002115option http-tunnel (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002116option http-use-proxy-header (*) X X X -
Willy Tarreau68ad3a42018-10-22 11:49:15 +02002117option http-use-htx (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002118option httpchk X - X X
2119option httpclose (*) X X X X
2120option httplog X X X X
2121option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002122option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02002123option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002124option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002125option log-health-checks (*) X - X X
2126option log-separate-errors (*) X X X -
2127option logasap (*) X X X -
2128option mysql-check X - X X
2129option nolinger (*) X X X X
2130option originalto X X X X
2131option persist (*) X - X X
Baptiste Assmann809e22a2015-10-12 20:22:55 +02002132option pgsql-check X - X X
2133option prefer-last-server (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002134option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02002135option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002136option smtpchk X - X X
2137option socket-stats (*) X X X -
2138option splice-auto (*) X X X X
2139option splice-request (*) X X X X
2140option splice-response (*) X X X X
Christopher Fauletba7bc162016-11-07 21:07:38 +01002141option spop-check - - - X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002142option srvtcpka (*) X - X X
2143option ssl-hello-chk X - X X
2144-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01002145option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002146option tcp-smart-accept (*) X X X -
2147option tcp-smart-connect (*) X - X X
2148option tcpka X X X X
2149option tcplog X X X X
2150option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002151external-check command X - X X
2152external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002153persist rdp-cookie X - X X
2154rate-limit sessions X X X -
2155redirect - X X X
2156redisp (deprecated) X - X X
2157redispatch (deprecated) X - X X
2158reqadd - X X X
2159reqallow - X X X
2160reqdel - X X X
2161reqdeny - X X X
2162reqiallow - X X X
2163reqidel - X X X
2164reqideny - X X X
2165reqipass - X X X
2166reqirep - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002167reqitarpit - X X X
2168reqpass - X X X
2169reqrep - X X X
2170-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002171reqtarpit - X X X
2172retries X - X X
2173rspadd - X X X
2174rspdel - X X X
2175rspdeny - X X X
2176rspidel - X X X
2177rspideny - X X X
2178rspirep - X X X
2179rsprep - X X X
2180server - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002181server-state-file-name X - X X
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02002182server-template - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002183source X - X X
2184srvtimeout (deprecated) X - X X
Baptiste Assmann5a549212015-10-12 20:30:24 +02002185stats admin - X X X
2186stats auth X X X X
2187stats enable X X X X
2188stats hide-version X X X X
2189stats http-request - X X X
2190stats realm X X X X
2191stats refresh X X X X
2192stats scope X X X X
2193stats show-desc X X X X
2194stats show-legends X X X X
2195stats show-node X X X X
2196stats uri X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002197-- keyword -------------------------- defaults - frontend - listen -- backend -
2198stick match - - X X
2199stick on - - X X
2200stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02002201stick store-response - - X X
Adam Spiers68af3c12017-04-06 16:31:39 +01002202stick-table - X X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02002203tcp-check connect - - X X
2204tcp-check expect - - X X
2205tcp-check send - - X X
2206tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02002207tcp-request connection - X X -
2208tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02002209tcp-request inspect-delay - X X X
Willy Tarreau4f614292016-10-21 17:49:36 +02002210tcp-request session - X X -
Emeric Brun0a3b67f2010-09-24 15:34:53 +02002211tcp-response content - - X X
2212tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002213timeout check X - X X
2214timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02002215timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002216timeout clitimeout (deprecated) X X X -
2217timeout connect X - X X
2218timeout contimeout (deprecated) X - X X
2219timeout http-keep-alive X X X X
2220timeout http-request X X X X
2221timeout queue X - X X
2222timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02002223timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002224timeout srvtimeout (deprecated) X - X X
2225timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02002226timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002227transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01002228unique-id-format X X X -
2229unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002230use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02002231use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002232------------------------------------+----------+----------+---------+---------
2233 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02002234
Willy Tarreau0ba27502007-12-24 16:55:16 +01002235
Willy Tarreauc57f0e22009-05-10 13:12:33 +020022364.2. Alphabetically sorted keywords reference
2237---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002238
2239This section provides a description of each keyword and its usage.
2240
2241
2242acl <aclname> <criterion> [flags] [operator] <value> ...
2243 Declare or complete an access list.
2244 May be used in sections : defaults | frontend | listen | backend
2245 no | yes | yes | yes
2246 Example:
2247 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2248 acl invalid_src src_port 0:1023
2249 acl local_dst hdr(host) -i localhost
2250
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002251 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002252
2253
Cyril Bontéb21570a2009-11-29 20:04:48 +01002254appsession <cookie> len <length> timeout <holdtime>
2255 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002256 Define session stickiness on an existing application cookie.
2257 May be used in sections : defaults | frontend | listen | backend
2258 no | no | yes | yes
2259 Arguments :
2260 <cookie> this is the name of the cookie used by the application and which
2261 HAProxy will have to learn for each new session.
2262
Cyril Bontéb21570a2009-11-29 20:04:48 +01002263 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01002264 checked in each cookie value.
2265
2266 <holdtime> this is the time after which the cookie will be removed from
2267 memory if unused. If no unit is specified, this time is in
2268 milliseconds.
2269
Cyril Bontébf47aeb2009-10-15 00:15:40 +02002270 request-learn
2271 If this option is specified, then haproxy will be able to learn
2272 the cookie found in the request in case the server does not
2273 specify any in response. This is typically what happens with
2274 PHPSESSID cookies, or when haproxy's session expires before
2275 the application's session and the correct server is selected.
2276 It is recommended to specify this option to improve reliability.
2277
Cyril Bontéb21570a2009-11-29 20:04:48 +01002278 prefix When this option is specified, haproxy will match on the cookie
2279 prefix (or URL parameter prefix). The appsession value is the
2280 data following this prefix.
2281
2282 Example :
2283 appsession ASPSESSIONID len 64 timeout 3h prefix
2284
Davor Ocelice9ed2812017-12-25 17:49:28 +01002285 This will match the cookie ASPSESSIONIDXXX=XXXX,
2286 the appsession value will be XXX=XXXX.
Cyril Bontéb21570a2009-11-29 20:04:48 +01002287
2288 mode This option allows to change the URL parser mode.
2289 2 modes are currently supported :
2290 - path-parameters :
2291 The parser looks for the appsession in the path parameters
2292 part (each parameter is separated by a semi-colon), which is
2293 convenient for JSESSIONID for example.
2294 This is the default mode if the option is not set.
2295 - query-string :
2296 In this mode, the parser will look for the appsession in the
2297 query string.
2298
Willy Tarreau294d0f02015-08-10 19:40:12 +02002299 As of version 1.6, appsessions was removed. It is more flexible and more
2300 convenient to use stick-tables instead, and stick-tables support multi-master
2301 replication and data conservation across reloads, which appsessions did not.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002302
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01002303 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
2304 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002305
2306
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002307backlog <conns>
2308 Give hints to the system about the approximate listen backlog desired size
2309 May be used in sections : defaults | frontend | listen | backend
2310 yes | yes | yes | no
2311 Arguments :
2312 <conns> is the number of pending connections. Depending on the operating
2313 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02002314 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002315
2316 In order to protect against SYN flood attacks, one solution is to increase
2317 the system's SYN backlog size. Depending on the system, sometimes it is just
2318 tunable via a system parameter, sometimes it is not adjustable at all, and
2319 sometimes the system relies on hints given by the application at the time of
2320 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
2321 to the listen() syscall. On systems which can make use of this value, it can
2322 sometimes be useful to be able to specify a different value, hence this
2323 backlog parameter.
2324
2325 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
2326 used as a hint and the system accepts up to the smallest greater power of
2327 two, and never more than some limits (usually 32768).
2328
2329 See also : "maxconn" and the target operating system's tuning guide.
2330
2331
Willy Tarreau0ba27502007-12-24 16:55:16 +01002332balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02002333balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002334 Define the load balancing algorithm to be used in a backend.
2335 May be used in sections : defaults | frontend | listen | backend
2336 yes | no | yes | yes
2337 Arguments :
2338 <algorithm> is the algorithm used to select a server when doing load
2339 balancing. This only applies when no persistence information
2340 is available, or when a connection is redispatched to another
2341 server. <algorithm> may be one of the following :
2342
2343 roundrobin Each server is used in turns, according to their weights.
2344 This is the smoothest and fairest algorithm when the server's
2345 processing time remains equally distributed. This algorithm
2346 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02002347 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08002348 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02002349 large farms, when a server becomes up after having been down
2350 for a very short time, it may sometimes take a few hundreds
2351 requests for it to be re-integrated into the farm and start
2352 receiving traffic. This is normal, though very rare. It is
2353 indicated here in case you would have the chance to observe
2354 it, so that you don't worry.
2355
2356 static-rr Each server is used in turns, according to their weights.
2357 This algorithm is as similar to roundrobin except that it is
2358 static, which means that changing a server's weight on the
2359 fly will have no effect. On the other hand, it has no design
2360 limitation on the number of servers, and when a server goes
2361 up, it is always immediately reintroduced into the farm, once
2362 the full map is recomputed. It also uses slightly less CPU to
2363 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01002364
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01002365 leastconn The server with the lowest number of connections receives the
2366 connection. Round-robin is performed within groups of servers
2367 of the same load to ensure that all servers will be used. Use
2368 of this algorithm is recommended where very long sessions are
2369 expected, such as LDAP, SQL, TSE, etc... but is not very well
2370 suited for protocols using short sessions such as HTTP. This
2371 algorithm is dynamic, which means that server weights may be
2372 adjusted on the fly for slow starts for instance.
2373
Willy Tarreauf09c6602012-02-13 17:12:08 +01002374 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002375 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01002376 identifier to the highest (see server parameter "id"), which
2377 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02002378 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01002379 not make sense to use this algorithm without setting maxconn.
2380 The purpose of this algorithm is to always use the smallest
2381 number of servers so that extra servers can be powered off
2382 during non-intensive hours. This algorithm ignores the server
2383 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02002384 or IMAP than HTTP, though it can be useful there too. In
2385 order to use this algorithm efficiently, it is recommended
2386 that a cloud controller regularly checks server usage to turn
2387 them off when unused, and regularly checks backend queue to
2388 turn new servers on when the queue inflates. Alternatively,
2389 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01002390
Willy Tarreau0ba27502007-12-24 16:55:16 +01002391 source The source IP address is hashed and divided by the total
2392 weight of the running servers to designate which server will
2393 receive the request. This ensures that the same client IP
2394 address will always reach the same server as long as no
2395 server goes down or up. If the hash result changes due to the
2396 number of running servers changing, many clients will be
2397 directed to a different server. This algorithm is generally
2398 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002399 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01002400 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002401 static by default, which means that changing a server's
2402 weight on the fly will have no effect, but this can be
2403 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002404
Oskar Stolc8dc41842012-05-19 10:19:54 +01002405 uri This algorithm hashes either the left part of the URI (before
2406 the question mark) or the whole URI (if the "whole" parameter
2407 is present) and divides the hash value by the total weight of
2408 the running servers. The result designates which server will
2409 receive the request. This ensures that the same URI will
2410 always be directed to the same server as long as no server
2411 goes up or down. This is used with proxy caches and
2412 anti-virus proxies in order to maximize the cache hit rate.
2413 Note that this algorithm may only be used in an HTTP backend.
2414 This algorithm is static by default, which means that
2415 changing a server's weight on the fly will have no effect,
2416 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002417
Oskar Stolc8dc41842012-05-19 10:19:54 +01002418 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002419 "depth", both followed by a positive integer number. These
2420 options may be helpful when it is needed to balance servers
2421 based on the beginning of the URI only. The "len" parameter
2422 indicates that the algorithm should only consider that many
2423 characters at the beginning of the URI to compute the hash.
2424 Note that having "len" set to 1 rarely makes sense since most
2425 URIs start with a leading "/".
2426
2427 The "depth" parameter indicates the maximum directory depth
2428 to be used to compute the hash. One level is counted for each
2429 slash in the request. If both parameters are specified, the
2430 evaluation stops when either is reached.
2431
Willy Tarreau0ba27502007-12-24 16:55:16 +01002432 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002433 the query string of each HTTP GET request.
2434
2435 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02002436 request entity will be searched for the parameter argument,
2437 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02002438 ('?') in the URL. The message body will only start to be
2439 analyzed once either the advertised amount of data has been
2440 received or the request buffer is full. In the unlikely event
2441 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02002442 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02002443 be randomly balanced if at all. This keyword used to support
2444 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002445
2446 If the parameter is found followed by an equal sign ('=') and
2447 a value, then the value is hashed and divided by the total
2448 weight of the running servers. The result designates which
2449 server will receive the request.
2450
2451 This is used to track user identifiers in requests and ensure
2452 that a same user ID will always be sent to the same server as
2453 long as no server goes up or down. If no value is found or if
2454 the parameter is not found, then a round robin algorithm is
2455 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002456 backend. This algorithm is static by default, which means
2457 that changing a server's weight on the fly will have no
2458 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002459
Cyril Bontédc4d9032012-04-08 21:57:39 +02002460 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
2461 request. Just as with the equivalent ACL 'hdr()' function,
2462 the header name in parenthesis is not case sensitive. If the
2463 header is absent or if it does not contain any value, the
2464 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01002465
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002466 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01002467 reducing the hash algorithm to the main domain part with some
2468 specific headers such as 'Host'. For instance, in the Host
2469 value "haproxy.1wt.eu", only "1wt" will be considered.
2470
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002471 This algorithm is static by default, which means that
2472 changing a server's weight on the fly will have no effect,
2473 but this can be changed using "hash-type".
2474
Willy Tarreau760e81d2018-05-03 07:20:40 +02002475 random A random number will be used as the key for the consistent
2476 hashing function. This means that the servers' weights are
2477 respected, dynamic weight changes immediately take effect, as
2478 well as new server additions. Random load balancing can be
2479 useful with large farms or when servers are frequently added
2480 or removed. The hash-balance-factor directive can be used to
2481 further improve fairness of the load balancing, especially
2482 in situations where servers show highly variable response
2483 times.
2484
Emeric Brun736aa232009-06-30 17:56:00 +02002485 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02002486 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02002487 The RDP cookie <name> (or "mstshash" if omitted) will be
2488 looked up and hashed for each incoming TCP request. Just as
2489 with the equivalent ACL 'req_rdp_cookie()' function, the name
2490 is not case-sensitive. This mechanism is useful as a degraded
2491 persistence mode, as it makes it possible to always send the
2492 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002493 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02002494 used instead.
2495
2496 Note that for this to work, the frontend must ensure that an
2497 RDP cookie is already present in the request buffer. For this
2498 you must use 'tcp-request content accept' rule combined with
2499 a 'req_rdp_cookie_cnt' ACL.
2500
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002501 This algorithm is static by default, which means that
2502 changing a server's weight on the fly will have no effect,
2503 but this can be changed using "hash-type".
2504
Cyril Bontédc4d9032012-04-08 21:57:39 +02002505 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09002506
Willy Tarreau0ba27502007-12-24 16:55:16 +01002507 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002508 algorithms. Right now, only "url_param" and "uri" support an
2509 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002510
Willy Tarreau3cd9af22009-03-15 14:06:41 +01002511 The load balancing algorithm of a backend is set to roundrobin when no other
2512 algorithm, mode nor option have been set. The algorithm may only be set once
2513 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002514
Lukas Tribus80512b12018-10-27 20:07:40 +02002515 With authentication schemes that require the same connection like NTLM, URI
2516 based alghoritms must not be used, as they would cause subsequent requests
2517 to be routed to different backend servers, breaking the invalid assumptions
2518 NTLM relies on.
2519
Willy Tarreau0ba27502007-12-24 16:55:16 +01002520 Examples :
2521 balance roundrobin
2522 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002523 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01002524 balance hdr(User-Agent)
2525 balance hdr(host)
2526 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002527
2528 Note: the following caveats and limitations on using the "check_post"
2529 extension with "url_param" must be considered :
2530
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002531 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002532 to determine if the parameters will be found in the body or entity which
2533 may contain binary data. Therefore another method may be required to
2534 restrict consideration of POST requests that have no URL parameters in
2535 the body. (see acl reqideny http_end)
2536
2537 - using a <max_wait> value larger than the request buffer size does not
2538 make sense and is useless. The buffer size is set at build time, and
2539 defaults to 16 kB.
2540
2541 - Content-Encoding is not supported, the parameter search will probably
2542 fail; and load balancing will fall back to Round Robin.
2543
2544 - Expect: 100-continue is not supported, load balancing will fall back to
2545 Round Robin.
2546
Lukas Tribus23953682017-04-28 13:24:30 +00002547 - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002548 If the entire parameter value is not present in the first chunk, the
2549 selection of server is undefined (actually, defined by how little
2550 actually appeared in the first chunk).
2551
2552 - This feature does not support generation of a 100, 411 or 501 response.
2553
2554 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002555 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002556 white space or control characters are found, indicating the end of what
2557 might be a URL parameter list. This is probably not a concern with SGML
2558 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002559
Willy Tarreau294d0f02015-08-10 19:40:12 +02002560 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002561
2562
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002563bind [<address>]:<port_range> [, ...] [param*]
2564bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002565 Define one or several listening addresses and/or ports in a frontend.
2566 May be used in sections : defaults | frontend | listen | backend
2567 no | yes | yes | no
2568 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002569 <address> is optional and can be a host name, an IPv4 address, an IPv6
2570 address, or '*'. It designates the address the frontend will
2571 listen on. If unset, all IPv4 addresses of the system will be
2572 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01002573 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01002574 Optionally, an address family prefix may be used before the
2575 address to force the family regardless of the address format,
2576 which can be useful to specify a path to a unix socket with
2577 no slash ('/'). Currently supported prefixes are :
2578 - 'ipv4@' -> address is always IPv4
2579 - 'ipv6@' -> address is always IPv6
2580 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02002581 - 'abns@' -> address is in abstract namespace (Linux only).
2582 Note: since abstract sockets are not "rebindable", they
2583 do not cope well with multi-process mode during
2584 soft-restart, so it is better to avoid them if
2585 nbproc is greater than 1. The effect is that if the
2586 new process fails to start, only one of the old ones
2587 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01002588 - 'fd@<n>' -> use file descriptor <n> inherited from the
2589 parent. The fd must be bound and may or may not already
2590 be listening.
William Lallemand2fe7dd02018-09-11 16:51:29 +02002591 - 'sockpair@<n>'-> like fd@ but you must use the fd of a
2592 connected unix socket or of a socketpair. The bind waits
2593 to receive a FD over the unix socket and uses it as if it
2594 was the FD of an accept(). Should be used carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02002595 You may want to reference some environment variables in the
2596 address parameter, see section 2.3 about environment
2597 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002598
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002599 <port_range> is either a unique TCP port, or a port range for which the
2600 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002601 above. The port is mandatory for TCP listeners. Note that in
2602 the case of an IPv6 address, the port is always the number
2603 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002604 - a numerical port (ex: '80')
2605 - a dash-delimited ports range explicitly stating the lower
2606 and upper bounds (ex: '2000-2100') which are included in
2607 the range.
2608
2609 Particular care must be taken against port ranges, because
2610 every <address:port> couple consumes one socket (= a file
2611 descriptor), so it's easy to consume lots of descriptors
2612 with a simple range, and to run out of sockets. Also, each
2613 <address:port> couple must be used only once among all
2614 instances running on a same system. Please note that binding
2615 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002616 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002617 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002618
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002619 <path> is a UNIX socket path beginning with a slash ('/'). This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002620 alternative to the TCP listening port. HAProxy will then
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002621 receive UNIX connections on the socket located at this place.
2622 The path must begin with a slash and by default is absolute.
2623 It can be relative to the prefix defined by "unix-bind" in
2624 the global section. Note that the total length of the prefix
2625 followed by the socket path cannot exceed some system limits
2626 for UNIX sockets, which commonly are set to 107 characters.
2627
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002628 <param*> is a list of parameters common to all sockets declared on the
2629 same line. These numerous parameters depend on OS and build
2630 options and have a complete section dedicated to them. Please
2631 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002632
Willy Tarreau0ba27502007-12-24 16:55:16 +01002633 It is possible to specify a list of address:port combinations delimited by
2634 commas. The frontend will then listen on all of these addresses. There is no
2635 fixed limit to the number of addresses and ports which can be listened on in
2636 a frontend, as well as there is no limit to the number of "bind" statements
2637 in a frontend.
2638
2639 Example :
2640 listen http_proxy
2641 bind :80,:443
2642 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002643 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01002644
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002645 listen http_https_proxy
2646 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02002647 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002648
Willy Tarreau24709282013-03-10 21:32:12 +01002649 listen http_https_proxy_explicit
2650 bind ipv6@:80
2651 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
2652 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
2653
Willy Tarreaudad36a32013-03-11 01:20:04 +01002654 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02002655 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01002656
Willy Tarreau55dcaf62015-09-27 15:03:15 +02002657 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
2658 sun_path length is used for the address length. Some other programs
2659 such as socat use the string length only by default. Pass the option
2660 ",unix-tightsocklen=0" to any abstract socket definition in socat to
2661 make it compatible with HAProxy's.
2662
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002663 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002664 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002665
2666
Christopher Fauletff4121f2017-11-22 16:38:49 +01002667bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002668 Limit visibility of an instance to a certain set of processes numbers.
2669 May be used in sections : defaults | frontend | listen | backend
2670 yes | yes | yes | yes
2671 Arguments :
2672 all All process will see this instance. This is the default. It
2673 may be used to override a default value.
2674
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002675 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002676 option may be combined with other numbers.
2677
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002678 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002679 option may be combined with other numbers. Do not use it
2680 with less than 2 processes otherwise some instances might be
2681 missing from all processes.
2682
Christopher Fauletff4121f2017-11-22 16:38:49 +01002683 process_num The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002684 whose values must all be between 1 and 32 or 64 depending on
Christopher Fauletff4121f2017-11-22 16:38:49 +01002685 the machine's word size. Ranges can be partially defined. The
2686 higher bound can be omitted. In such case, it is replaced by
2687 the corresponding maximum value. If a proxy is bound to
2688 process numbers greater than the configured global.nbproc, it
2689 will either be forced to process #1 if a single process was
Willy Tarreau102df612014-05-07 23:56:38 +02002690 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002691
2692 This keyword limits binding of certain instances to certain processes. This
2693 is useful in order not to have too many processes listening to the same
2694 ports. For instance, on a dual-core machine, it might make sense to set
2695 'nbproc 2' in the global section, then distributes the listeners among 'odd'
2696 and 'even' instances.
2697
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002698 At the moment, it is not possible to reference more than 32 or 64 processes
2699 using this keyword, but this should be more than enough for most setups.
2700 Please note that 'all' really means all processes regardless of the machine's
2701 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002702
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02002703 Each "bind" line may further be limited to a subset of the proxy's processes,
2704 please consult the "process" bind keyword in section 5.1.
2705
Willy Tarreaub369a042014-09-16 13:21:03 +02002706 When a frontend has no explicit "bind-process" line, it tries to bind to all
2707 the processes referenced by its "bind" lines. That means that frontends can
2708 easily adapt to their listeners' processes.
2709
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002710 If some backends are referenced by frontends bound to other processes, the
2711 backend automatically inherits the frontend's processes.
2712
2713 Example :
2714 listen app_ip1
2715 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002716 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002717
2718 listen app_ip2
2719 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002720 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002721
2722 listen management
2723 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002724 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002725
Willy Tarreau110ecc12012-11-15 17:50:01 +01002726 listen management
2727 bind 10.0.0.4:80
2728 bind-process 1-4
2729
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02002730 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002731
2732
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002733block { if | unless } <condition> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002734 Block a layer 7 request if/unless a condition is matched
2735 May be used in sections : defaults | frontend | listen | backend
2736 no | yes | yes | yes
2737
2738 The HTTP request will be blocked very early in the layer 7 processing
2739 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002740 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02002741 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01002742 conditions are met or not met. There is no fixed limit to the number of
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03002743 "block" statements per instance. To block connections at layer 4 (without
2744 sending a 403 error) see "tcp-request connection reject" and
2745 "tcp-request content reject" rules.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002746
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002747 This form is deprecated, do not use it in any new configuration, use the new
2748 "http-request deny" instead.
2749
Willy Tarreau0ba27502007-12-24 16:55:16 +01002750 Example:
2751 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2752 acl invalid_src src_port 0:1023
2753 acl local_dst hdr(host) -i localhost
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +03002754 # block is deprecated. Use http-request deny instead:
2755 #block if invalid_src || local_dst
2756 http-request deny if invalid_src || local_dst
Willy Tarreau0ba27502007-12-24 16:55:16 +01002757
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03002758 See also : section 7 about ACL usage, "http-request deny",
2759 "http-response deny", "tcp-request connection reject" and
2760 "tcp-request content reject".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002761
2762capture cookie <name> len <length>
2763 Capture and log a cookie in the request and in the response.
2764 May be used in sections : defaults | frontend | listen | backend
2765 no | yes | yes | no
2766 Arguments :
2767 <name> is the beginning of the name of the cookie to capture. In order
2768 to match the exact name, simply suffix the name with an equal
2769 sign ('='). The full name will appear in the logs, which is
2770 useful with application servers which adjust both the cookie name
Davor Ocelice9ed2812017-12-25 17:49:28 +01002771 and value (e.g. ASPSESSIONXXX).
Willy Tarreau0ba27502007-12-24 16:55:16 +01002772
2773 <length> is the maximum number of characters to report in the logs, which
2774 include the cookie name, the equal sign and the value, all in the
2775 standard "name=value" form. The string will be truncated on the
2776 right if it exceeds <length>.
2777
2778 Only the first cookie is captured. Both the "cookie" request headers and the
2779 "set-cookie" response headers are monitored. This is particularly useful to
2780 check for application bugs causing session crossing or stealing between
2781 users, because generally the user's cookies can only change on a login page.
2782
2783 When the cookie was not presented by the client, the associated log column
2784 will report "-". When a request does not cause a cookie to be assigned by the
2785 server, a "-" is reported in the response column.
2786
2787 The capture is performed in the frontend only because it is necessary that
2788 the log format does not change for a given frontend depending on the
2789 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01002790 "capture cookie" statement in a frontend. The maximum capture length is set
2791 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
2792 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002793
2794 Example:
2795 capture cookie ASPSESSION len 32
2796
2797 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002798 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002799
2800
2801capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002802 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002803 May be used in sections : defaults | frontend | listen | backend
2804 no | yes | yes | no
2805 Arguments :
2806 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002807 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002808 appear in the requests, with the first letter of each word in
2809 upper case. The header name will not appear in the logs, only the
2810 value is reported, but the position in the logs is respected.
2811
2812 <length> is the maximum number of characters to extract from the value and
2813 report in the logs. The string will be truncated on the right if
2814 it exceeds <length>.
2815
Willy Tarreau4460d032012-11-21 23:37:37 +01002816 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002817 value will be added to the logs between braces ('{}'). If multiple headers
2818 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002819 in the same order they were declared in the configuration. Non-existent
2820 headers will be logged just as an empty string. Common uses for request
2821 header captures include the "Host" field in virtual hosting environments, the
2822 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002823 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002824 environments to find where the request came from.
2825
2826 Note that when capturing headers such as "User-agent", some spaces may be
2827 logged, making the log analysis more difficult. Thus be careful about what
2828 you log if you know your log parser is not smart enough to rely on the
2829 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002830
Willy Tarreau0900abb2012-11-22 00:21:46 +01002831 There is no limit to the number of captured request headers nor to their
2832 length, though it is wise to keep them low to limit memory usage per session.
2833 In order to keep log format consistent for a same frontend, header captures
2834 can only be declared in a frontend. It is not possible to specify a capture
2835 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002836
2837 Example:
2838 capture request header Host len 15
2839 capture request header X-Forwarded-For len 15
Cyril Bontéd1b0f7c2015-10-26 22:37:39 +01002840 capture request header Referer len 15
Willy Tarreau0ba27502007-12-24 16:55:16 +01002841
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002842 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002843 about logging.
2844
2845
2846capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002847 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002848 May be used in sections : defaults | frontend | listen | backend
2849 no | yes | yes | no
2850 Arguments :
2851 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002852 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002853 appear in the response, with the first letter of each word in
2854 upper case. The header name will not appear in the logs, only the
2855 value is reported, but the position in the logs is respected.
2856
2857 <length> is the maximum number of characters to extract from the value and
2858 report in the logs. The string will be truncated on the right if
2859 it exceeds <length>.
2860
Willy Tarreau4460d032012-11-21 23:37:37 +01002861 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002862 result will be added to the logs between braces ('{}') after the captured
2863 request headers. If multiple headers are captured, they will be delimited by
2864 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002865 the configuration. Non-existent headers will be logged just as an empty
2866 string. Common uses for response header captures include the "Content-length"
2867 header which indicates how many bytes are expected to be returned, the
2868 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002869
Willy Tarreau0900abb2012-11-22 00:21:46 +01002870 There is no limit to the number of captured response headers nor to their
2871 length, though it is wise to keep them low to limit memory usage per session.
2872 In order to keep log format consistent for a same frontend, header captures
2873 can only be declared in a frontend. It is not possible to specify a capture
2874 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002875
2876 Example:
2877 capture response header Content-length len 9
2878 capture response header Location len 15
2879
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002880 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002881 about logging.
2882
2883
Cyril Bontéf0c60612010-02-06 14:44:47 +01002884clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002885 Set the maximum inactivity time on the client side.
2886 May be used in sections : defaults | frontend | listen | backend
2887 yes | yes | yes | no
2888 Arguments :
2889 <timeout> is the timeout value is specified in milliseconds by default, but
2890 can be in any other unit if the number is suffixed by the unit,
2891 as explained at the top of this document.
2892
2893 The inactivity timeout applies when the client is expected to acknowledge or
2894 send data. In HTTP mode, this timeout is particularly important to consider
2895 during the first phase, when the client sends the request, and during the
2896 response while it is reading data sent by the server. The value is specified
2897 in milliseconds by default, but can be in any other unit if the number is
2898 suffixed by the unit, as specified at the top of this document. In TCP mode
2899 (and to a lesser extent, in HTTP mode), it is highly recommended that the
2900 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002901 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01002902 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +01002903 (e.g. 4 or 5 seconds).
Willy Tarreau0ba27502007-12-24 16:55:16 +01002904
2905 This parameter is specific to frontends, but can be specified once for all in
2906 "defaults" sections. This is in fact one of the easiest solutions not to
2907 forget about it. An unspecified timeout results in an infinite timeout, which
2908 is not recommended. Such a usage is accepted and works but reports a warning
2909 during startup because it may results in accumulation of expired sessions in
2910 the system if the system's timeouts are not configured either.
2911
2912 This parameter is provided for compatibility but is currently deprecated.
2913 Please use "timeout client" instead.
2914
Willy Tarreau036fae02008-01-06 13:24:40 +01002915 See also : "timeout client", "timeout http-request", "timeout server", and
2916 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002917
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002918compression algo <algorithm> ...
2919compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02002920compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02002921 Enable HTTP compression.
2922 May be used in sections : defaults | frontend | listen | backend
2923 yes | yes | yes | yes
2924 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002925 algo is followed by the list of supported compression algorithms.
2926 type is followed by the list of MIME types that will be compressed.
2927 offload makes haproxy work as a compression offloader only (see notes).
2928
2929 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01002930 identity this is mostly for debugging, and it was useful for developing
2931 the compression feature. Identity does not apply any change on
2932 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002933
Willy Tarreauc91840a2015-03-28 17:00:39 +01002934 gzip applies gzip compression. This setting is only available when
Baptiste Assmannf085d632015-12-21 17:57:32 +01002935 support for zlib or libslz was built in.
Willy Tarreauc91840a2015-03-28 17:00:39 +01002936
2937 deflate same as "gzip", but with deflate algorithm and zlib format.
2938 Note that this algorithm has ambiguous support on many
2939 browsers and no support at all from recent ones. It is
2940 strongly recommended not to use it for anything else than
2941 experimentation. This setting is only available when support
Baptiste Assmannf085d632015-12-21 17:57:32 +01002942 for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002943
Willy Tarreauc91840a2015-03-28 17:00:39 +01002944 raw-deflate same as "deflate" without the zlib wrapper, and used as an
2945 alternative when the browser wants "deflate". All major
2946 browsers understand it and despite violating the standards,
2947 it is known to work better than "deflate", at least on MSIE
2948 and some versions of Safari. Do not use it in conjunction
2949 with "deflate", use either one or the other since both react
2950 to the same Accept-Encoding token. This setting is only
Baptiste Assmannf085d632015-12-21 17:57:32 +01002951 available when support for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002952
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002953 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002954 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002955 If backend servers support HTTP compression, these directives
2956 will be no-op: haproxy will see the compressed response and will not
2957 compress again. If backend servers do not support HTTP compression and
2958 there is Accept-Encoding header in request, haproxy will compress the
2959 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02002960
2961 The "offload" setting makes haproxy remove the Accept-Encoding header to
2962 prevent backend servers from compressing responses. It is strongly
2963 recommended not to do this because this means that all the compression work
2964 will be done on the single point where haproxy is located. However in some
2965 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002966 with broken HTTP compression implementation which can't be turned off.
2967 In that case haproxy can be used to prevent that gateway from emitting
2968 invalid payloads. In this case, simply removing the header in the
2969 configuration does not work because it applies before the header is parsed,
2970 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02002971 then be used for such scenarios. Note: for now, the "offload" setting is
2972 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02002973
William Lallemand05097442012-11-20 12:14:28 +01002974 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002975 * the request does not advertise a supported compression algorithm in the
2976 "Accept-Encoding" header
2977 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01002978 * HTTP status code is not 200
William Lallemand8bb4e342013-12-10 17:28:48 +01002979 * response header "Transfer-Encoding" contains "chunked" (Temporary
2980 Workaround)
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002981 * response contain neither a "Content-Length" header nor a
2982 "Transfer-Encoding" whose last value is "chunked"
2983 * response contains a "Content-Type" header whose first value starts with
2984 "multipart"
2985 * the response contains the "no-transform" value in the "Cache-control"
2986 header
2987 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
2988 and later
2989 * The response contains a "Content-Encoding" header, indicating that the
2990 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01002991
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002992 Note: The compression does not rewrite Etag headers, and does not emit the
2993 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01002994
William Lallemand82fe75c2012-10-23 10:25:10 +02002995 Examples :
2996 compression algo gzip
2997 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002998
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002999
Cyril Bontéf0c60612010-02-06 14:44:47 +01003000contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01003001 Set the maximum time to wait for a connection attempt to a server to succeed.
3002 May be used in sections : defaults | frontend | listen | backend
3003 yes | no | yes | yes
3004 Arguments :
3005 <timeout> is the timeout value is specified in milliseconds by default, but
3006 can be in any other unit if the number is suffixed by the unit,
3007 as explained at the top of this document.
3008
3009 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003010 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01003011 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +01003012 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003013 connect timeout also presets the queue timeout to the same value if this one
3014 has not been specified. Historically, the contimeout was also used to set the
3015 tarpit timeout in a listen section, which is not possible in a pure frontend.
3016
3017 This parameter is specific to backends, but can be specified once for all in
3018 "defaults" sections. This is in fact one of the easiest solutions not to
3019 forget about it. An unspecified timeout results in an infinite timeout, which
3020 is not recommended. Such a usage is accepted and works but reports a warning
3021 during startup because it may results in accumulation of failed sessions in
3022 the system if the system's timeouts are not configured either.
3023
3024 This parameter is provided for backwards compatibility but is currently
3025 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
3026 instead.
3027
3028 See also : "timeout connect", "timeout queue", "timeout tarpit",
3029 "timeout server", "contimeout".
3030
3031
Willy Tarreau55165fe2009-05-10 12:02:55 +02003032cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02003033 [ postonly ] [ preserve ] [ httponly ] [ secure ]
3034 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Olivier Houchard4e694042017-03-14 20:01:29 +01003035 [ dynamic ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01003036 Enable cookie-based persistence in a backend.
3037 May be used in sections : defaults | frontend | listen | backend
3038 yes | no | yes | yes
3039 Arguments :
3040 <name> is the name of the cookie which will be monitored, modified or
3041 inserted in order to bring persistence. This cookie is sent to
3042 the client via a "Set-Cookie" header in the response, and is
3043 brought back by the client in a "Cookie" header in all requests.
3044 Special care should be taken to choose a name which does not
3045 conflict with any likely application cookie. Also, if the same
Davor Ocelice9ed2812017-12-25 17:49:28 +01003046 backends are subject to be used by the same clients (e.g.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003047 HTTP/HTTPS), care should be taken to use different cookie names
3048 between all backends if persistence between them is not desired.
3049
3050 rewrite This keyword indicates that the cookie will be provided by the
3051 server and that haproxy will have to modify its value to set the
3052 server's identifier in it. This mode is handy when the management
3053 of complex combinations of "Set-cookie" and "Cache-control"
3054 headers is left to the application. The application can then
3055 decide whether or not it is appropriate to emit a persistence
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003056 cookie. Since all responses should be monitored, this mode
3057 doesn't work in HTTP tunnel mode. Unless the application
Davor Ocelice9ed2812017-12-25 17:49:28 +01003058 behavior is very complex and/or broken, it is advised not to
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003059 start with this mode for new deployments. This keyword is
3060 incompatible with "insert" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003061
3062 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02003063 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003064
Willy Tarreaua79094d2010-08-31 22:54:15 +02003065 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003066 server. When used without the "preserve" option, if the server
3067 emits a cookie with the same name, it will be remove before
Davor Ocelice9ed2812017-12-25 17:49:28 +01003068 processing. For this reason, this mode can be used to upgrade
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003069 existing configurations running in the "rewrite" mode. The cookie
3070 will only be a session cookie and will not be stored on the
3071 client's disk. By default, unless the "indirect" option is added,
3072 the server will see the cookies emitted by the client. Due to
3073 caching effects, it is generally wise to add the "nocache" or
3074 "postonly" keywords (see below). The "insert" keyword is not
3075 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003076
3077 prefix This keyword indicates that instead of relying on a dedicated
3078 cookie for the persistence, an existing one will be completed.
3079 This may be needed in some specific environments where the client
3080 does not support more than one single cookie and the application
3081 already needs it. In this case, whenever the server sets a cookie
3082 named <name>, it will be prefixed with the server's identifier
3083 and a delimiter. The prefix will be removed from all client
3084 requests so that the server still finds the cookie it emitted.
3085 Since all requests and responses are subject to being modified,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003086 this mode doesn't work with tunnel mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02003087 not compatible with "rewrite" and "insert". Note: it is highly
3088 recommended not to use "indirect" with "prefix", otherwise server
3089 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003090
Willy Tarreaua79094d2010-08-31 22:54:15 +02003091 indirect When this option is specified, no cookie will be emitted to a
3092 client which already has a valid one for the server which has
3093 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003094 it will be removed, unless the "preserve" option is also set. In
3095 "insert" mode, this will additionally remove cookies from the
3096 requests transmitted to the server, making the persistence
3097 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02003098 Note: it is highly recommended not to use "indirect" with
3099 "prefix", otherwise server cookie updates would not be sent to
3100 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003101
3102 nocache This option is recommended in conjunction with the insert mode
3103 when there is a cache between the client and HAProxy, as it
3104 ensures that a cacheable response will be tagged non-cacheable if
3105 a cookie needs to be inserted. This is important because if all
3106 persistence cookies are added on a cacheable home page for
3107 instance, then all customers will then fetch the page from an
3108 outer cache and will all share the same persistence cookie,
3109 leading to one server receiving much more traffic than others.
3110 See also the "insert" and "postonly" options.
3111
3112 postonly This option ensures that cookie insertion will only be performed
3113 on responses to POST requests. It is an alternative to the
3114 "nocache" option, because POST responses are not cacheable, so
3115 this ensures that the persistence cookie will never get cached.
3116 Since most sites do not need any sort of persistence before the
3117 first POST which generally is a login request, this is a very
3118 efficient method to optimize caching without risking to find a
3119 persistence cookie in the cache.
3120 See also the "insert" and "nocache" options.
3121
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003122 preserve This option may only be used with "insert" and/or "indirect". It
3123 allows the server to emit the persistence cookie itself. In this
3124 case, if a cookie is found in the response, haproxy will leave it
3125 untouched. This is useful in order to end persistence after a
3126 logout request for instance. For this, the server just has to
Davor Ocelice9ed2812017-12-25 17:49:28 +01003127 emit a cookie with an invalid value (e.g. empty) or with a date in
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003128 the past. By combining this mechanism with the "disable-on-404"
3129 check option, it is possible to perform a completely graceful
3130 shutdown because users will definitely leave the server after
3131 they logout.
3132
Willy Tarreau4992dd22012-05-31 21:02:17 +02003133 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
3134 when a cookie is inserted. This attribute is used so that a
3135 user agent doesn't share the cookie with non-HTTP components.
3136 Please check RFC6265 for more information on this attribute.
3137
3138 secure This option tells haproxy to add a "Secure" cookie attribute when
3139 a cookie is inserted. This attribute is used so that a user agent
3140 never emits this cookie over non-secure channels, which means
3141 that a cookie learned with this flag will be presented only over
3142 SSL/TLS connections. Please check RFC6265 for more information on
3143 this attribute.
3144
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003145 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003146 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01003147 name. If the domain begins with a dot, the browser is allowed to
3148 use it for any host ending with that name. It is also possible to
3149 specify several domain names by invoking this option multiple
3150 times. Some browsers might have small limits on the number of
3151 domains, so be careful when doing that. For the record, sending
3152 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003153
Willy Tarreau996a92c2010-10-13 19:30:47 +02003154 maxidle This option allows inserted cookies to be ignored after some idle
3155 time. It only works with insert-mode cookies. When a cookie is
3156 sent to the client, the date this cookie was emitted is sent too.
3157 Upon further presentations of this cookie, if the date is older
3158 than the delay indicated by the parameter (in seconds), it will
3159 be ignored. Otherwise, it will be refreshed if needed when the
3160 response is sent to the client. This is particularly useful to
3161 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003162 too long on the same server (e.g. after a farm size change). When
Willy Tarreau996a92c2010-10-13 19:30:47 +02003163 this option is set and a cookie has no date, it is always
3164 accepted, but gets refreshed in the response. This maintains the
3165 ability for admins to access their sites. Cookies that have a
3166 date in the future further than 24 hours are ignored. Doing so
3167 lets admins fix timezone issues without risking kicking users off
3168 the site.
3169
3170 maxlife This option allows inserted cookies to be ignored after some life
3171 time, whether they're in use or not. It only works with insert
3172 mode cookies. When a cookie is first sent to the client, the date
3173 this cookie was emitted is sent too. Upon further presentations
3174 of this cookie, if the date is older than the delay indicated by
3175 the parameter (in seconds), it will be ignored. If the cookie in
3176 the request has no date, it is accepted and a date will be set.
3177 Cookies that have a date in the future further than 24 hours are
3178 ignored. Doing so lets admins fix timezone issues without risking
3179 kicking users off the site. Contrary to maxidle, this value is
3180 not refreshed, only the first visit date counts. Both maxidle and
3181 maxlife may be used at the time. This is particularly useful to
3182 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003183 too long on the same server (e.g. after a farm size change). This
Willy Tarreau996a92c2010-10-13 19:30:47 +02003184 is stronger than the maxidle method in that it forces a
3185 redispatch after some absolute delay.
3186
Olivier Houchard4e694042017-03-14 20:01:29 +01003187 dynamic Activate dynamic cookies. When used, a session cookie is
3188 dynamically created for each server, based on the IP and port
3189 of the server, and a secret key, specified in the
3190 "dynamic-cookie-key" backend directive.
3191 The cookie will be regenerated each time the IP address change,
3192 and is only generated for IPv4/IPv6.
3193
Willy Tarreau0ba27502007-12-24 16:55:16 +01003194 There can be only one persistence cookie per HTTP backend, and it can be
3195 declared in a defaults section. The value of the cookie will be the value
3196 indicated after the "cookie" keyword in a "server" statement. If no cookie
3197 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02003198
Willy Tarreau0ba27502007-12-24 16:55:16 +01003199 Examples :
3200 cookie JSESSIONID prefix
3201 cookie SRV insert indirect nocache
3202 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02003203 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01003204
Willy Tarreau294d0f02015-08-10 19:40:12 +02003205 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003206
Willy Tarreau983e01e2010-01-11 18:42:06 +01003207
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003208declare capture [ request | response ] len <length>
3209 Declares a capture slot.
3210 May be used in sections : defaults | frontend | listen | backend
3211 no | yes | yes | no
3212 Arguments:
3213 <length> is the length allowed for the capture.
3214
3215 This declaration is only available in the frontend or listen section, but the
3216 reserved slot can be used in the backends. The "request" keyword allocates a
3217 capture slot for use in the request, and "response" allocates a capture slot
3218 for use in the response.
3219
3220 See also: "capture-req", "capture-res" (sample converters),
Baptiste Assmann5ac425c2015-10-21 23:13:46 +02003221 "capture.req.hdr", "capture.res.hdr" (sample fetches),
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003222 "http-request capture" and "http-response capture".
3223
3224
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003225default-server [param*]
3226 Change default options for a server in a backend
3227 May be used in sections : defaults | frontend | listen | backend
3228 yes | no | yes | yes
3229 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01003230 <param*> is a list of parameters for this server. The "default-server"
3231 keyword accepts an important number of options and has a complete
3232 section dedicated to it. Please refer to section 5 for more
3233 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003234
Willy Tarreau983e01e2010-01-11 18:42:06 +01003235 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003236 default-server inter 1000 weight 13
3237
3238 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01003239
Willy Tarreau983e01e2010-01-11 18:42:06 +01003240
Willy Tarreau0ba27502007-12-24 16:55:16 +01003241default_backend <backend>
3242 Specify the backend to use when no "use_backend" rule has been matched.
3243 May be used in sections : defaults | frontend | listen | backend
3244 yes | yes | yes | no
3245 Arguments :
3246 <backend> is the name of the backend to use.
3247
3248 When doing content-switching between frontend and backends using the
3249 "use_backend" keyword, it is often useful to indicate which backend will be
3250 used when no rule has matched. It generally is the dynamic backend which
3251 will catch all undetermined requests.
3252
Willy Tarreau0ba27502007-12-24 16:55:16 +01003253 Example :
3254
3255 use_backend dynamic if url_dyn
3256 use_backend static if url_css url_img extension_img
3257 default_backend dynamic
3258
Willy Tarreau98d04852015-05-26 12:18:29 +02003259 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003260
Willy Tarreau0ba27502007-12-24 16:55:16 +01003261
Baptiste Assmann27f51342013-10-09 06:51:49 +02003262description <string>
3263 Describe a listen, frontend or backend.
3264 May be used in sections : defaults | frontend | listen | backend
3265 no | yes | yes | yes
3266 Arguments : string
3267
3268 Allows to add a sentence to describe the related object in the HAProxy HTML
3269 stats page. The description will be printed on the right of the object name
3270 it describes.
3271 No need to backslash spaces in the <string> arguments.
3272
3273
Willy Tarreau0ba27502007-12-24 16:55:16 +01003274disabled
3275 Disable a proxy, frontend or backend.
3276 May be used in sections : defaults | frontend | listen | backend
3277 yes | yes | yes | yes
3278 Arguments : none
3279
3280 The "disabled" keyword is used to disable an instance, mainly in order to
3281 liberate a listening port or to temporarily disable a service. The instance
3282 will still be created and its configuration will be checked, but it will be
3283 created in the "stopped" state and will appear as such in the statistics. It
3284 will not receive any traffic nor will it send any health-checks or logs. It
3285 is possible to disable many instances at once by adding the "disabled"
3286 keyword in a "defaults" section.
3287
3288 See also : "enabled"
3289
3290
Willy Tarreau5ce94572010-06-07 14:35:41 +02003291dispatch <address>:<port>
3292 Set a default server address
3293 May be used in sections : defaults | frontend | listen | backend
3294 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003295 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02003296
3297 <address> is the IPv4 address of the default server. Alternatively, a
3298 resolvable hostname is supported, but this name will be resolved
3299 during start-up.
3300
3301 <ports> is a mandatory port specification. All connections will be sent
3302 to this port, and it is not permitted to use port offsets as is
3303 possible with normal servers.
3304
Willy Tarreau787aed52011-04-15 06:45:37 +02003305 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02003306 server can take the connection. In the past it was used to forward non
3307 persistent connections to an auxiliary load balancer. Due to its simple
3308 syntax, it has also been used for simple TCP relays. It is recommended not to
3309 use it for more clarity, and to use the "server" directive instead.
3310
3311 See also : "server"
3312
Olivier Houchard4e694042017-03-14 20:01:29 +01003313
3314dynamic-cookie-key <string>
3315 Set the dynamic cookie secret key for a backend.
3316 May be used in sections : defaults | frontend | listen | backend
3317 yes | no | yes | yes
3318 Arguments : The secret key to be used.
3319
3320 When dynamic cookies are enabled (see the "dynamic" directive for cookie),
Davor Ocelice9ed2812017-12-25 17:49:28 +01003321 a dynamic cookie is created for each server (unless one is explicitly
Olivier Houchard4e694042017-03-14 20:01:29 +01003322 specified on the "server" line), using a hash of the IP address of the
3323 server, the TCP port, and the secret key.
Davor Ocelice9ed2812017-12-25 17:49:28 +01003324 That way, we can ensure session persistence across multiple load-balancers,
Olivier Houchard4e694042017-03-14 20:01:29 +01003325 even if servers are dynamically added or removed.
Willy Tarreau5ce94572010-06-07 14:35:41 +02003326
Willy Tarreau0ba27502007-12-24 16:55:16 +01003327enabled
3328 Enable a proxy, frontend or backend.
3329 May be used in sections : defaults | frontend | listen | backend
3330 yes | yes | yes | yes
3331 Arguments : none
3332
3333 The "enabled" keyword is used to explicitly enable an instance, when the
3334 defaults has been set to "disabled". This is very rarely used.
3335
3336 See also : "disabled"
3337
3338
3339errorfile <code> <file>
3340 Return a file contents instead of errors generated by HAProxy
3341 May be used in sections : defaults | frontend | listen | backend
3342 yes | yes | yes | yes
3343 Arguments :
3344 <code> is the HTTP status code. Currently, HAProxy is capable of
Olivier Houchard51a76d82017-10-02 16:12:07 +02003345 generating codes 200, 400, 403, 405, 408, 425, 429, 500, 502,
3346 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003347
3348 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003349 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01003350 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01003351 error pages, and to use absolute paths, since files are read
3352 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003353
3354 It is important to understand that this keyword is not meant to rewrite
3355 errors returned by the server, but errors detected and returned by HAProxy.
3356 This is why the list of supported errors is limited to a small set.
3357
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003358 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3359
Willy Tarreau0ba27502007-12-24 16:55:16 +01003360 The files are returned verbatim on the TCP socket. This allows any trick such
3361 as redirections to another URL or site, as well as tricks to clean cookies,
3362 force enable or disable caching, etc... The package provides default error
3363 files returning the same contents as default errors.
3364
Willy Tarreau59140a22009-02-22 12:02:30 +01003365 The files should not exceed the configured buffer size (BUFSIZE), which
3366 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
Davor Ocelice9ed2812017-12-25 17:49:28 +01003367 not to put any reference to local contents (e.g. images) in order to avoid
Willy Tarreau59140a22009-02-22 12:02:30 +01003368 loops between the client and HAProxy when all servers are down, causing an
3369 error to be returned instead of an image. For better HTTP compliance, it is
3370 recommended that all header lines end with CR-LF and not LF alone.
3371
Willy Tarreau0ba27502007-12-24 16:55:16 +01003372 The files are read at the same time as the configuration and kept in memory.
3373 For this reason, the errors continue to be returned even when the process is
3374 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01003375 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003376 403 status code and interrogating a blocked URL.
3377
3378 See also : "errorloc", "errorloc302", "errorloc303"
3379
Willy Tarreau59140a22009-02-22 12:02:30 +01003380 Example :
3381 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau989222a2016-01-15 10:26:26 +01003382 errorfile 408 /dev/null # work around Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01003383 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
3384 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
3385
Willy Tarreau2769aa02007-12-27 18:26:09 +01003386
3387errorloc <code> <url>
3388errorloc302 <code> <url>
3389 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3390 May be used in sections : defaults | frontend | listen | backend
3391 yes | yes | yes | yes
3392 Arguments :
3393 <code> is the HTTP status code. Currently, HAProxy is capable of
Olivier Houchard51a76d82017-10-02 16:12:07 +02003394 generating codes 200, 400, 403, 405, 408, 425, 429, 500, 502,
3395 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003396
3397 <url> it is the exact contents of the "Location" header. It may contain
3398 either a relative URI to an error page hosted on the same site,
3399 or an absolute URI designating an error page on another site.
3400 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01003401 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01003402
3403 It is important to understand that this keyword is not meant to rewrite
3404 errors returned by the server, but errors detected and returned by HAProxy.
3405 This is why the list of supported errors is limited to a small set.
3406
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003407 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3408
Willy Tarreau2769aa02007-12-27 18:26:09 +01003409 Note that both keyword return the HTTP 302 status code, which tells the
3410 client to fetch the designated URL using the same HTTP method. This can be
3411 quite problematic in case of non-GET methods such as POST, because the URL
3412 sent to the client might not be allowed for something other than GET. To
Willy Tarreau989222a2016-01-15 10:26:26 +01003413 work around this problem, please use "errorloc303" which send the HTTP 303
Willy Tarreau2769aa02007-12-27 18:26:09 +01003414 status code, indicating to the client that the URL must be fetched with a GET
3415 request.
3416
3417 See also : "errorfile", "errorloc303"
3418
3419
3420errorloc303 <code> <url>
3421 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3422 May be used in sections : defaults | frontend | listen | backend
3423 yes | yes | yes | yes
3424 Arguments :
3425 <code> is the HTTP status code. Currently, HAProxy is capable of
Olivier Houchard51a76d82017-10-02 16:12:07 +02003426 generating codes 200, 400, 403, 405, 408, 425, 429, 500, 502,
3427 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003428
3429 <url> it is the exact contents of the "Location" header. It may contain
3430 either a relative URI to an error page hosted on the same site,
3431 or an absolute URI designating an error page on another site.
3432 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01003433 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01003434
3435 It is important to understand that this keyword is not meant to rewrite
3436 errors returned by the server, but errors detected and returned by HAProxy.
3437 This is why the list of supported errors is limited to a small set.
3438
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003439 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3440
Willy Tarreau2769aa02007-12-27 18:26:09 +01003441 Note that both keyword return the HTTP 303 status code, which tells the
3442 client to fetch the designated URL using the same HTTP GET method. This
3443 solves the usual problems associated with "errorloc" and the 302 code. It is
3444 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003445 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003446
3447 See also : "errorfile", "errorloc", "errorloc302"
3448
3449
Simon Horman51a1cf62015-02-03 13:00:44 +09003450email-alert from <emailaddr>
3451 Declare the from email address to be used in both the envelope and header
Davor Ocelice9ed2812017-12-25 17:49:28 +01003452 of email alerts. This is the address that email alerts are sent from.
Simon Horman51a1cf62015-02-03 13:00:44 +09003453 May be used in sections: defaults | frontend | listen | backend
3454 yes | yes | yes | yes
3455
3456 Arguments :
3457
3458 <emailaddr> is the from email address to use when sending email alerts
3459
3460 Also requires "email-alert mailers" and "email-alert to" to be set
3461 and if so sending email alerts is enabled for the proxy.
3462
Simon Horman64e34162015-02-06 11:11:57 +09003463 See also : "email-alert level", "email-alert mailers",
Cyril Bonté307ee1e2015-09-28 23:16:06 +02003464 "email-alert myhostname", "email-alert to", section 3.6 about
3465 mailers.
Simon Horman64e34162015-02-06 11:11:57 +09003466
3467
3468email-alert level <level>
3469 Declare the maximum log level of messages for which email alerts will be
3470 sent. This acts as a filter on the sending of email alerts.
3471 May be used in sections: defaults | frontend | listen | backend
3472 yes | yes | yes | yes
3473
3474 Arguments :
3475
3476 <level> One of the 8 syslog levels:
3477 emerg alert crit err warning notice info debug
3478 The above syslog levels are ordered from lowest to highest.
3479
3480 By default level is alert
3481
3482 Also requires "email-alert from", "email-alert mailers" and
3483 "email-alert to" to be set and if so sending email alerts is enabled
3484 for the proxy.
3485
Simon Horman1421e212015-04-30 13:10:35 +09003486 Alerts are sent when :
3487
3488 * An un-paused server is marked as down and <level> is alert or lower
3489 * A paused server is marked as down and <level> is notice or lower
3490 * A server is marked as up or enters the drain state and <level>
3491 is notice or lower
3492 * "option log-health-checks" is enabled, <level> is info or lower,
3493 and a health check status update occurs
3494
Simon Horman64e34162015-02-06 11:11:57 +09003495 See also : "email-alert from", "email-alert mailers",
3496 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09003497 section 3.6 about mailers.
3498
3499
3500email-alert mailers <mailersect>
3501 Declare the mailers to be used when sending email alerts
3502 May be used in sections: defaults | frontend | listen | backend
3503 yes | yes | yes | yes
3504
3505 Arguments :
3506
3507 <mailersect> is the name of the mailers section to send email alerts.
3508
3509 Also requires "email-alert from" and "email-alert to" to be set
3510 and if so sending email alerts is enabled for the proxy.
3511
Simon Horman64e34162015-02-06 11:11:57 +09003512 See also : "email-alert from", "email-alert level", "email-alert myhostname",
3513 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003514
3515
3516email-alert myhostname <hostname>
3517 Declare the to hostname address to be used when communicating with
3518 mailers.
3519 May be used in sections: defaults | frontend | listen | backend
3520 yes | yes | yes | yes
3521
3522 Arguments :
3523
Baptiste Assmann738bad92015-12-21 15:27:53 +01003524 <hostname> is the hostname to use when communicating with mailers
Simon Horman51a1cf62015-02-03 13:00:44 +09003525
3526 By default the systems hostname is used.
3527
3528 Also requires "email-alert from", "email-alert mailers" and
3529 "email-alert to" to be set and if so sending email alerts is enabled
3530 for the proxy.
3531
Simon Horman64e34162015-02-06 11:11:57 +09003532 See also : "email-alert from", "email-alert level", "email-alert mailers",
3533 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003534
3535
3536email-alert to <emailaddr>
Davor Ocelice9ed2812017-12-25 17:49:28 +01003537 Declare both the recipient address in the envelope and to address in the
Simon Horman51a1cf62015-02-03 13:00:44 +09003538 header of email alerts. This is the address that email alerts are sent to.
3539 May be used in sections: defaults | frontend | listen | backend
3540 yes | yes | yes | yes
3541
3542 Arguments :
3543
3544 <emailaddr> is the to email address to use when sending email alerts
3545
3546 Also requires "email-alert mailers" and "email-alert to" to be set
3547 and if so sending email alerts is enabled for the proxy.
3548
Simon Horman64e34162015-02-06 11:11:57 +09003549 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09003550 "email-alert myhostname", section 3.6 about mailers.
3551
3552
Willy Tarreau4de91492010-01-22 19:10:05 +01003553force-persist { if | unless } <condition>
3554 Declare a condition to force persistence on down servers
3555 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01003556 no | no | yes | yes
Willy Tarreau4de91492010-01-22 19:10:05 +01003557
3558 By default, requests are not dispatched to down servers. It is possible to
3559 force this using "option persist", but it is unconditional and redispatches
3560 to a valid server if "option redispatch" is set. That leaves with very little
3561 possibilities to force some requests to reach a server which is artificially
3562 marked down for maintenance operations.
3563
3564 The "force-persist" statement allows one to declare various ACL-based
3565 conditions which, when met, will cause a request to ignore the down status of
3566 a server and still try to connect to it. That makes it possible to start a
3567 server, still replying an error to the health checks, and run a specially
3568 configured browser to test the service. Among the handy methods, one could
3569 use a specific source IP address, or a specific cookie. The cookie also has
3570 the advantage that it can easily be added/removed on the browser from a test
3571 page. Once the service is validated, it is then possible to open the service
3572 to the world by returning a valid response to health checks.
3573
3574 The forced persistence is enabled when an "if" condition is met, or unless an
3575 "unless" condition is met. The final redispatch is always disabled when this
3576 is used.
3577
Cyril Bonté0d4bf012010-04-25 23:21:46 +02003578 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02003579 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01003580
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003581
3582filter <name> [param*]
3583 Add the filter <name> in the filter list attached to the proxy.
3584 May be used in sections : defaults | frontend | listen | backend
3585 no | yes | yes | yes
3586 Arguments :
3587 <name> is the name of the filter. Officially supported filters are
3588 referenced in section 9.
3589
Tim Düsterhus4896c442016-11-29 02:15:19 +01003590 <param*> is a list of parameters accepted by the filter <name>. The
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003591 parsing of these parameters are the responsibility of the
Tim Düsterhus4896c442016-11-29 02:15:19 +01003592 filter. Please refer to the documentation of the corresponding
3593 filter (section 9) for all details on the supported parameters.
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003594
3595 Multiple occurrences of the filter line can be used for the same proxy. The
3596 same filter can be referenced many times if needed.
3597
3598 Example:
3599 listen
3600 bind *:80
3601
3602 filter trace name BEFORE-HTTP-COMP
3603 filter compression
3604 filter trace name AFTER-HTTP-COMP
3605
3606 compression algo gzip
3607 compression offload
3608
3609 server srv1 192.168.0.1:80
3610
3611 See also : section 9.
3612
Willy Tarreau4de91492010-01-22 19:10:05 +01003613
Willy Tarreau2769aa02007-12-27 18:26:09 +01003614fullconn <conns>
3615 Specify at what backend load the servers will reach their maxconn
3616 May be used in sections : defaults | frontend | listen | backend
3617 yes | no | yes | yes
3618 Arguments :
3619 <conns> is the number of connections on the backend which will make the
3620 servers use the maximal number of connections.
3621
Willy Tarreau198a7442008-01-17 12:05:32 +01003622 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01003623 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01003624 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01003625 load. The server will then always accept at least <minconn> connections,
3626 never more than <maxconn>, and the limit will be on the ramp between both
3627 values when the backend has less than <conns> concurrent connections. This
3628 makes it possible to limit the load on the servers during normal loads, but
3629 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003630 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003631
Willy Tarreaufbb78422011-06-05 15:38:35 +02003632 Since it's hard to get this value right, haproxy automatically sets it to
3633 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01003634 backend (based on "use_backend" and "default_backend" rules). That way it's
3635 safe to leave it unset. However, "use_backend" involving dynamic names are
3636 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02003637
Willy Tarreau2769aa02007-12-27 18:26:09 +01003638 Example :
3639 # The servers will accept between 100 and 1000 concurrent connections each
3640 # and the maximum of 1000 will be reached when the backend reaches 10000
3641 # connections.
3642 backend dynamic
3643 fullconn 10000
3644 server srv1 dyn1:80 minconn 100 maxconn 1000
3645 server srv2 dyn2:80 minconn 100 maxconn 1000
3646
3647 See also : "maxconn", "server"
3648
3649
3650grace <time>
3651 Maintain a proxy operational for some time after a soft stop
3652 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01003653 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01003654 Arguments :
3655 <time> is the time (by default in milliseconds) for which the instance
3656 will remain operational with the frontend sockets still listening
3657 when a soft-stop is received via the SIGUSR1 signal.
3658
3659 This may be used to ensure that the services disappear in a certain order.
3660 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003661 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01003662 needed by the equipment to detect the failure.
3663
3664 Note that currently, there is very little benefit in using this parameter,
3665 and it may in fact complicate the soft-reconfiguration process more than
3666 simplify it.
3667
Willy Tarreau0ba27502007-12-24 16:55:16 +01003668
Andrew Rodland17be45e2016-10-25 17:04:12 -04003669hash-balance-factor <factor>
3670 Specify the balancing factor for bounded-load consistent hashing
3671 May be used in sections : defaults | frontend | listen | backend
3672 yes | no | no | yes
3673 Arguments :
3674 <factor> is the control for the maximum number of concurrent requests to
3675 send to a server, expressed as a percentage of the average number
3676 of concurrent requests across all of the active servers.
3677
3678 Specifying a "hash-balance-factor" for a server with "hash-type consistent"
3679 enables an algorithm that prevents any one server from getting too many
3680 requests at once, even if some hash buckets receive many more requests than
3681 others. Setting <factor> to 0 (the default) disables the feature. Otherwise,
3682 <factor> is a percentage greater than 100. For example, if <factor> is 150,
3683 then no server will be allowed to have a load more than 1.5 times the average.
3684 If server weights are used, they will be respected.
3685
3686 If the first-choice server is disqualified, the algorithm will choose another
3687 server based on the request hash, until a server with additional capacity is
3688 found. A higher <factor> allows more imbalance between the servers, while a
3689 lower <factor> means that more servers will be checked on average, affecting
3690 performance. Reasonable values are from 125 to 200.
3691
Willy Tarreau760e81d2018-05-03 07:20:40 +02003692 This setting is also used by "balance random" which internally relies on the
3693 consistent hashing mechanism.
3694
Andrew Rodland17be45e2016-10-25 17:04:12 -04003695 See also : "balance" and "hash-type".
3696
3697
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003698hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003699 Specify a method to use for mapping hashes to servers
3700 May be used in sections : defaults | frontend | listen | backend
3701 yes | no | yes | yes
3702 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04003703 <method> is the method used to select a server from the hash computed by
3704 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003705
Bhaskar98634f02013-10-29 23:30:51 -04003706 map-based the hash table is a static array containing all alive servers.
3707 The hashes will be very smooth, will consider weights, but
3708 will be static in that weight changes while a server is up
3709 will be ignored. This means that there will be no slow start.
3710 Also, since a server is selected by its position in the array,
3711 most mappings are changed when the server count changes. This
3712 means that when a server goes up or down, or when a server is
3713 added to a farm, most connections will be redistributed to
3714 different servers. This can be inconvenient with caches for
3715 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01003716
Bhaskar98634f02013-10-29 23:30:51 -04003717 consistent the hash table is a tree filled with many occurrences of each
3718 server. The hash key is looked up in the tree and the closest
3719 server is chosen. This hash is dynamic, it supports changing
3720 weights while the servers are up, so it is compatible with the
3721 slow start feature. It has the advantage that when a server
3722 goes up or down, only its associations are moved. When a
3723 server is added to the farm, only a few part of the mappings
3724 are redistributed, making it an ideal method for caches.
3725 However, due to its principle, the distribution will never be
3726 very smooth and it may sometimes be necessary to adjust a
3727 server's weight or its ID to get a more balanced distribution.
3728 In order to get the same distribution on multiple load
3729 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003730 same IDs. Note: consistent hash uses sdbm and avalanche if no
3731 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04003732
3733 <function> is the hash function to be used :
3734
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003735 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04003736 reimplementation of ndbm) database library. It was found to do
3737 well in scrambling bits, causing better distribution of the keys
3738 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003739 function with good distribution, unless the total server weight
3740 is a multiple of 64, in which case applying the avalanche
3741 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04003742
3743 djb2 this function was first proposed by Dan Bernstein many years ago
3744 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003745 function provides a better distribution than sdbm. It generally
3746 works well with text-based inputs though it can perform extremely
3747 poorly with numeric-only input or when the total server weight is
3748 a multiple of 33, unless the avalanche modifier is also used.
3749
Willy Tarreaua0f42712013-11-14 14:30:35 +01003750 wt6 this function was designed for haproxy while testing other
3751 functions in the past. It is not as smooth as the other ones, but
3752 is much less sensible to the input data set or to the number of
3753 servers. It can make sense as an alternative to sdbm+avalanche or
3754 djb2+avalanche for consistent hashing or when hashing on numeric
3755 data such as a source IP address or a visitor identifier in a URL
3756 parameter.
3757
Willy Tarreau324f07f2015-01-20 19:44:50 +01003758 crc32 this is the most common CRC32 implementation as used in Ethernet,
3759 gzip, PNG, etc. It is slower than the other ones but may provide
3760 a better distribution or less predictable results especially when
3761 used on strings.
3762
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003763 <modifier> indicates an optional method applied after hashing the key :
3764
3765 avalanche This directive indicates that the result from the hash
3766 function above should not be used in its raw form but that
3767 a 4-byte full avalanche hash must be applied first. The
3768 purpose of this step is to mix the resulting bits from the
3769 previous hash in order to avoid any undesired effect when
3770 the input contains some limited values or when the number of
3771 servers is a multiple of one of the hash's components (64
3772 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
3773 result less predictable, but it's also not as smooth as when
3774 using the original function. Some testing might be needed
3775 with some workloads. This hash is one of the many proposed
3776 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003777
Bhaskar98634f02013-10-29 23:30:51 -04003778 The default hash type is "map-based" and is recommended for most usages. The
3779 default function is "sdbm", the selection of a function should be based on
3780 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003781
Andrew Rodland17be45e2016-10-25 17:04:12 -04003782 See also : "balance", "hash-balance-factor", "server"
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003783
3784
Willy Tarreau0ba27502007-12-24 16:55:16 +01003785http-check disable-on-404
3786 Enable a maintenance mode upon HTTP/404 response to health-checks
3787 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01003788 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01003789 Arguments : none
3790
3791 When this option is set, a server which returns an HTTP code 404 will be
3792 excluded from further load-balancing, but will still receive persistent
3793 connections. This provides a very convenient method for Web administrators
3794 to perform a graceful shutdown of their servers. It is also important to note
3795 that a server which is detected as failed while it was in this mode will not
3796 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
3797 will immediately be reinserted into the farm. The status on the stats page
3798 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01003799 option only works in conjunction with the "httpchk" option. If this option
3800 is used with "http-check expect", then it has precedence over it so that 404
3801 responses will still be considered as soft-stop.
3802
3803 See also : "option httpchk", "http-check expect"
3804
3805
3806http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003807 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01003808 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02003809 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01003810 Arguments :
3811 <match> is a keyword indicating how to look for a specific pattern in the
3812 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003813 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01003814 exclamation mark ("!") to negate the match. Spaces are allowed
3815 between the exclamation mark and the keyword. See below for more
3816 details on the supported keywords.
3817
3818 <pattern> is the pattern to look for. It may be a string or a regular
3819 expression. If the pattern contains spaces, they must be escaped
3820 with the usual backslash ('\').
3821
3822 By default, "option httpchk" considers that response statuses 2xx and 3xx
3823 are valid, and that others are invalid. When "http-check expect" is used,
3824 it defines what is considered valid or invalid. Only one "http-check"
3825 statement is supported in a backend. If a server fails to respond or times
3826 out, the check obviously fails. The available matches are :
3827
3828 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003829 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003830 response's status code is exactly this string. If the
3831 "status" keyword is prefixed with "!", then the response
3832 will be considered invalid if the status code matches.
3833
3834 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003835 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003836 response's status code matches the expression. If the
3837 "rstatus" keyword is prefixed with "!", then the response
3838 will be considered invalid if the status code matches.
3839 This is mostly used to check for multiple codes.
3840
3841 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003842 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003843 response's body contains this exact string. If the
3844 "string" keyword is prefixed with "!", then the response
3845 will be considered invalid if the body contains this
3846 string. This can be used to look for a mandatory word at
3847 the end of a dynamic page, or to detect a failure when a
Davor Ocelice9ed2812017-12-25 17:49:28 +01003848 specific error appears on the check page (e.g. a stack
Willy Tarreaubd741542010-03-16 18:46:54 +01003849 trace).
3850
3851 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003852 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003853 response's body matches this expression. If the "rstring"
3854 keyword is prefixed with "!", then the response will be
3855 considered invalid if the body matches the expression.
3856 This can be used to look for a mandatory word at the end
3857 of a dynamic page, or to detect a failure when a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01003858 error appears on the check page (e.g. a stack trace).
Willy Tarreaubd741542010-03-16 18:46:54 +01003859
3860 It is important to note that the responses will be limited to a certain size
3861 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
3862 Thus, too large responses may not contain the mandatory pattern when using
3863 "string" or "rstring". If a large response is absolutely required, it is
3864 possible to change the default max size by setting the global variable.
3865 However, it is worth keeping in mind that parsing very large responses can
3866 waste some CPU cycles, especially when regular expressions are used, and that
3867 it is always better to focus the checks on smaller resources.
3868
Cyril Bonté32602d22015-01-30 00:07:07 +01003869 Also "http-check expect" doesn't support HTTP keep-alive. Keep in mind that it
3870 will automatically append a "Connection: close" header, meaning that this
3871 header should not be present in the request provided by "option httpchk".
3872
Willy Tarreaubd741542010-03-16 18:46:54 +01003873 Last, if "http-check expect" is combined with "http-check disable-on-404",
3874 then this last one has precedence when the server responds with 404.
3875
3876 Examples :
3877 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003878 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01003879
3880 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003881 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01003882
3883 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003884 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01003885
3886 # check that we have a correct hexadecimal tag before /html
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03003887 http-check expect rstring <!--tag:[0-9a-f]*--></html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01003888
Willy Tarreaubd741542010-03-16 18:46:54 +01003889 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003890
3891
Willy Tarreauef781042010-01-27 11:53:01 +01003892http-check send-state
3893 Enable emission of a state header with HTTP health checks
3894 May be used in sections : defaults | frontend | listen | backend
3895 yes | no | yes | yes
3896 Arguments : none
3897
3898 When this option is set, haproxy will systematically send a special header
3899 "X-Haproxy-Server-State" with a list of parameters indicating to each server
3900 how they are seen by haproxy. This can be used for instance when a server is
3901 manipulated without access to haproxy and the operator needs to know whether
3902 haproxy still sees it up or not, or if the server is the last one in a farm.
3903
3904 The header is composed of fields delimited by semi-colons, the first of which
3905 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
3906 checks on the total number before transition, just as appears in the stats
3907 interface. Next headers are in the form "<variable>=<value>", indicating in
3908 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08003909 - a variable "address", containing the address of the backend server.
3910 This corresponds to the <address> field in the server declaration. For
3911 unix domain sockets, it will read "unix".
3912
3913 - a variable "port", containing the port of the backend server. This
3914 corresponds to the <port> field in the server declaration. For unix
3915 domain sockets, it will read "unix".
3916
Willy Tarreauef781042010-01-27 11:53:01 +01003917 - a variable "name", containing the name of the backend followed by a slash
3918 ("/") then the name of the server. This can be used when a server is
3919 checked in multiple backends.
3920
3921 - a variable "node" containing the name of the haproxy node, as set in the
3922 global "node" variable, otherwise the system's hostname if unspecified.
3923
3924 - a variable "weight" indicating the weight of the server, a slash ("/")
3925 and the total weight of the farm (just counting usable servers). This
3926 helps to know if other servers are available to handle the load when this
3927 one fails.
3928
3929 - a variable "scur" indicating the current number of concurrent connections
3930 on the server, followed by a slash ("/") then the total number of
3931 connections on all servers of the same backend.
3932
3933 - a variable "qcur" indicating the current number of requests in the
3934 server's queue.
3935
3936 Example of a header received by the application server :
3937 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
3938 scur=13/22; qcur=0
3939
3940 See also : "option httpchk", "http-check disable-on-404"
3941
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003942
3943http-request <action> [options...] [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003944 Access control for Layer 7 requests
3945
3946 May be used in sections: defaults | frontend | listen | backend
3947 no | yes | yes | yes
3948
Willy Tarreau20b0de52012-12-24 15:45:22 +01003949 The http-request statement defines a set of rules which apply to layer 7
3950 processing. The rules are evaluated in their declaration order when they are
3951 met in a frontend, listen or backend section. Any rule may optionally be
3952 followed by an ACL-based condition, in which case it will only be evaluated
3953 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003954
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003955 The first keyword is the rule's action. The supported actions are described
3956 below.
Willy Tarreau20b0de52012-12-24 15:45:22 +01003957
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003958 There is no limit to the number of http-request statements per instance.
Willy Tarreau20b0de52012-12-24 15:45:22 +01003959
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003960 It is important to know that http-request rules are processed very early in
3961 the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
3962 or "reqadd" rules. That way, headers added by "add-header"/"set-header" are
3963 visible by almost all further ACL rules.
Willy Tarreau53275e82017-11-24 07:52:01 +01003964
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003965 Using "reqadd"/"reqdel"/"reqrep" to manipulate request headers is discouraged
3966 in newer versions (>= 1.5). But if you need to use regular expression to
3967 delete headers, you can still use "reqdel". Also please use
3968 "http-request deny/allow/tarpit" instead of "reqdeny"/"reqpass"/"reqtarpit".
Willy Tarreauccbcc372012-12-27 12:37:57 +01003969
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003970 Example:
3971 acl nagios src 192.168.129.3
3972 acl local_net src 192.168.0.0/16
3973 acl auth_ok http_auth(L1)
Willy Tarreau20b0de52012-12-24 15:45:22 +01003974
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003975 http-request allow if nagios
3976 http-request allow if local_net auth_ok
3977 http-request auth realm Gimme if local_net auth_ok
3978 http-request deny
Willy Tarreau81499eb2012-12-27 12:19:02 +01003979
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003980 Example:
3981 acl key req.hdr(X-Add-Acl-Key) -m found
3982 acl add path /addacl
3983 acl del path /delacl
Willy Tarreau20b0de52012-12-24 15:45:22 +01003984
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003985 acl myhost hdr(Host) -f myhost.lst
Willy Tarreau20b0de52012-12-24 15:45:22 +01003986
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003987 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
3988 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003989
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003990 Example:
3991 acl value req.hdr(X-Value) -m found
3992 acl setmap path /setmap
3993 acl delmap path /delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06003994
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003995 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06003996
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02003997 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
3998 http-request del-map(map.lst) %[src] if delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06003999
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004000 See also : "stats http-request", section 3.4 about userlists and section 7
4001 about ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06004002
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004003http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004004
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004005 This is used to add a new entry into an ACL. The ACL must be loaded from a
4006 file (even a dummy empty file). The file name of the ACL to be updated is
4007 passed between parentheses. It takes one argument: <key fmt>, which follows
4008 log-format rules, to collect content of the new entry. It performs a lookup
4009 in the ACL before insertion, to avoid duplicated (or more) values. This
4010 lookup is done by a linear search and can be expensive with large lists!
4011 It is the equivalent of the "add acl" command from the stats socket, but can
4012 be triggered by an HTTP request.
Sasha Pachev218f0642014-06-16 12:05:59 -06004013
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004014http-request add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004015
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004016 This appends an HTTP header field whose name is specified in <name> and
4017 whose value is defined by <fmt> which follows the log-format rules (see
4018 Custom Log Format in section 8.2.4). This is particularly useful to pass
4019 connection-specific information to the server (e.g. the client's SSL
4020 certificate), or to combine several headers into one. This rule is not
4021 final, so it is possible to add other similar rules. Note that header
4022 addition is performed immediately, so one rule might reuse the resulting
4023 header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06004024
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004025http-request allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004026
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004027 This stops the evaluation of the rules and lets the request pass the check.
4028 No further "http-request" rules are evaluated.
Sasha Pachev218f0642014-06-16 12:05:59 -06004029
Sasha Pachev218f0642014-06-16 12:05:59 -06004030
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004031http-request auth [realm <realm>] [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004032
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004033 This stops the evaluation of the rules and immediately responds with an
4034 HTTP 401 or 407 error code to invite the user to present a valid user name
4035 and password. No further "http-request" rules are evaluated. An optional
4036 "realm" parameter is supported, it sets the authentication realm that is
4037 returned with the response (typically the application's name).
Sasha Pachev218f0642014-06-16 12:05:59 -06004038
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004039 Example:
4040 acl auth_ok http_auth_group(L1) G1
4041 http-request auth unless auth_ok
Sasha Pachev218f0642014-06-16 12:05:59 -06004042
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004043http-request cache-use [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004044
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004045 See section 10.2 about cache setup.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004046
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004047http-request capture <sample> [ len <length> | id <id> ]
4048 [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004049
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004050 This captures sample expression <sample> from the request buffer, and
4051 converts it to a string of at most <len> characters. The resulting string is
4052 stored into the next request "capture" slot, so it will possibly appear next
4053 to some captured HTTP headers. It will then automatically appear in the logs,
4054 and it will be possible to extract it using sample fetch rules to feed it
4055 into headers or anything. The length should be limited given that this size
4056 will be allocated for each capture during the whole session life.
4057 Please check section 7.3 (Fetching samples) and "capture request header" for
4058 more information.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004059
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004060 If the keyword "id" is used instead of "len", the action tries to store the
4061 captured string in a previously declared capture slot. This is useful to run
4062 captures in backends. The slot id can be declared by a previous directive
4063 "http-request capture" or with the "declare capture" keyword. If the slot
4064 <id> doesn't exist, then HAProxy fails parsing the configuration to prevent
4065 unexpected behavior at run time.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004066
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004067http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004068
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004069 This is used to delete an entry from an ACL. The ACL must be loaded from a
4070 file (even a dummy empty file). The file name of the ACL to be updated is
4071 passed between parentheses. It takes one argument: <key fmt>, which follows
4072 log-format rules, to collect content of the entry to delete.
4073 It is the equivalent of the "del acl" command from the stats socket, but can
4074 be triggered by an HTTP request.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004075
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004076http-request del-header <name> [ { if | unless } <condition> ]
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004077
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004078 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau9a355ec2013-06-11 17:45:46 +02004079
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004080http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau42cf39e2013-06-11 18:51:32 +02004081
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004082 This is used to delete an entry from a MAP. The MAP must be loaded from a
4083 file (even a dummy empty file). The file name of the MAP to be updated is
4084 passed between parentheses. It takes one argument: <key fmt>, which follows
4085 log-format rules, to collect content of the entry to delete.
4086 It takes one argument: "file name" It is the equivalent of the "del map"
4087 command from the stats socket, but can be triggered by an HTTP request.
Willy Tarreau51347ed2013-06-11 19:34:13 +02004088
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004089http-request deny [deny_status <status>] [ { if | unless } <condition> ]
Patrick Hemmer268a7072018-05-11 12:52:31 -04004090
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004091 This stops the evaluation of the rules and immediately rejects the request
4092 and emits an HTTP 403 error, or optionally the status code specified as an
4093 argument to "deny_status". The list of permitted status codes is limited to
4094 those that can be overridden by the "errorfile" directive.
4095 No further "http-request" rules are evaluated.
Patrick Hemmer268a7072018-05-11 12:52:31 -04004096
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004097http-request redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004098
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004099 This performs an HTTP redirection based on a redirect rule. This is exactly
4100 the same as the "redirect" statement except that it inserts a redirect rule
4101 which can be processed in the middle of other "http-request" rules and that
4102 these rules use the "log-format" strings. See the "redirect" keyword for the
4103 rule's syntax.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004104
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004105http-request reject [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004106
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004107 This stops the evaluation of the rules and immediately closes the connection
4108 without sending any response. It acts similarly to the
4109 "tcp-request content reject" rules. It can be useful to force an immediate
4110 connection closure on HTTP/2 connections.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004111
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004112http-request replace-header <name> <match-regex> <replace-fmt>
4113 [ { if | unless } <condition> ]
Willy Tarreaua9083d02015-05-08 15:27:59 +02004114
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004115 This matches the regular expression in all occurrences of header field
4116 <name> according to <match-regex>, and replaces them with the
4117 <replace-fmt> argument. Format characters are allowed in replace-fmt and
4118 work like in <fmt> arguments in "http-request add-header". The match is
4119 only case-sensitive. It is important to understand that this action only
4120 considers whole header lines, regardless of the number of values they may
4121 contain. This usage is suited to headers naturally containing commas in
4122 their value, such as If-Modified-Since and so on.
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02004123
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004124 Example:
4125 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
William Lallemand86d0df02017-11-24 21:36:45 +01004126
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004127 # applied to:
4128 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
Willy Tarreau09448f72014-06-25 18:12:15 +02004129
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004130 # outputs:
4131 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
Willy Tarreau09448f72014-06-25 18:12:15 +02004132
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004133 # assuming the backend IP is 192.168.1.20
Willy Tarreau09448f72014-06-25 18:12:15 +02004134
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004135http-request replace-value <name> <match-regex> <replace-fmt>
4136 [ { if | unless } <condition> ]
Willy Tarreau09448f72014-06-25 18:12:15 +02004137
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004138 This works like "replace-header" except that it matches the regex against
4139 every comma-delimited value of the header field <name> instead of the
4140 entire header. This is suited for all headers which are allowed to carry
4141 more than one value. An example could be the Accept header.
Willy Tarreau09448f72014-06-25 18:12:15 +02004142
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004143 Example:
4144 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004145
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004146 # applied to:
4147 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004148
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004149 # outputs:
4150 X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
Frédéric Lécaille6778b272018-01-29 15:22:53 +01004151
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004152http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
4153http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004154
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004155 This actions increments the GPC0 or GPC1 counter according with the sticky
4156 counter designated by <sc-id>. If an error occurs, this action silently fails
4157 and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004158
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004159http-request sc-set-gpt0(<sc-id>) <int> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004160
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004161 This action sets the GPT0 tag according to the sticky counter designated by
4162 <sc-id> and the value of <int>. The expected result is a boolean. If an error
4163 occurs, this action silently fails and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004164
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004165http-request set-dst <expr> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004166
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004167 This is used to set the destination IP address to the value of specified
4168 expression. Useful when a proxy in front of HAProxy rewrites destination IP,
4169 but provides the correct IP in a HTTP header; or you want to mask the IP for
4170 privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
4171 server address in the backend.
Christopher Faulet85d79c92016-11-09 16:54:56 +01004172
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004173 Arguments:
4174 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4175 by some converters.
Christopher Faulet85d79c92016-11-09 16:54:56 +01004176
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004177 Example:
4178 http-request set-dst hdr(x-dst)
4179 http-request set-dst dst,ipmask(24)
Christopher Faulet85d79c92016-11-09 16:54:56 +01004180
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004181 When possible, set-dst preserves the original destination port as long as the
4182 address family allows it, otherwise the destination port is set to 0.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004183
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004184http-request set-dst-port <expr> [ { if | unless } <condition> ]
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004185
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004186 This is used to set the destination port address to the value of specified
4187 expression. If you want to connect to the new address/port, use '0.0.0.0:0'
4188 as a server address in the backend.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004189
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004190 Arguments:
4191 <expr> Is a standard HAProxy expression formed by a sample-fetch
4192 followed by some converters.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004193
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004194 Example:
4195 http-request set-dst-port hdr(x-port)
4196 http-request set-dst-port int(4000)
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004197
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004198 When possible, set-dst-port preserves the original destination address as
4199 long as the address family supports a port, otherwise it forces the
4200 destination address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02004201
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004202http-request set-header <name> <fmt> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02004203
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004204 This does the same as "http-request add-header" except that the header name
4205 is first removed if it existed. This is useful when passing security
4206 information to the server, where the header must not be manipulated by
4207 external users. Note that the new value is computed before the removal so it
4208 is possible to concatenate a value to an existing header.
William Lallemand44be6402016-05-25 01:51:35 +02004209
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004210 Example:
4211 http-request set-header X-Haproxy-Current-Date %T
4212 http-request set-header X-SSL %[ssl_fc]
4213 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
4214 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
4215 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
4216 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
4217 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
4218 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
4219 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
William Lallemand44be6402016-05-25 01:51:35 +02004220
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004221http-request set-log-level <level> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02004222
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004223 This is used to change the log level of the current request when a certain
4224 condition is met. Valid levels are the 8 syslog levels (see the "log"
4225 keyword) plus the special level "silent" which disables logging for this
4226 request. This rule is not final so the last matching rule wins. This rule
4227 can be useful to disable health checks coming from another equipment.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004228
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004229http-request set-map(<file-name>) <key fmt> <value fmt>
4230 [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004231
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004232 This is used to add a new entry into a MAP. The MAP must be loaded from a
4233 file (even a dummy empty file). The file name of the MAP to be updated is
4234 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
4235 log-format rules, used to collect MAP key, and <value fmt>, which follows
4236 log-format rules, used to collect content for the new entry.
4237 It performs a lookup in the MAP before insertion, to avoid duplicated (or
4238 more) values. This lookup is done by a linear search and can be expensive
4239 with large lists! It is the equivalent of the "set map" command from the
4240 stats socket, but can be triggered by an HTTP request.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004241
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004242http-request set-mark <mark> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004243
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004244 This is used to set the Netfilter MARK on all packets sent to the client to
4245 the value passed in <mark> on platforms which support it. This value is an
4246 unsigned 32 bit value which can be matched by netfilter and by the routing
4247 table. It can be expressed both in decimal or hexadecimal format (prefixed by
4248 "0x"). This can be useful to force certain packets to take a different route
4249 (for example a cheaper network path for bulk downloads). This works on Linux
4250 kernels 2.6.32 and above and requires admin privileges.
Willy Tarreau00005ce2016-10-21 15:07:45 +02004251
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004252http-request set-method <fmt> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004253
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004254 This rewrites the request method with the result of the evaluation of format
4255 string <fmt>. There should be very few valid reasons for having to do so as
4256 this is more likely to break something than to fix it.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004257
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004258http-request set-nice <nice> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004259
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004260 This sets the "nice" factor of the current request being processed. It only
4261 has effect against the other requests being processed at the same time.
4262 The default value is 0, unless altered by the "nice" setting on the "bind"
4263 line. The accepted range is -1024..1024. The higher the value, the nicest
4264 the request will be. Lower values will make the request more important than
4265 other ones. This can be useful to improve the speed of some requests, or
4266 lower the priority of non-important requests. Using this setting without
4267 prior experimentation can cause some major slowdown.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004268
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004269http-request set-path <fmt> [ { if | unless } <condition> ]
Willy Tarreau00005ce2016-10-21 15:07:45 +02004270
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004271 This rewrites the request path with the result of the evaluation of format
4272 string <fmt>. The query string, if any, is left intact. If a scheme and
4273 authority is found before the path, they are left intact as well. If the
4274 request doesn't have a path ("*"), this one is replaced with the format.
4275 This can be used to prepend a directory component in front of a path for
4276 example. See also "http-request set-query" and "http-request set-uri".
Willy Tarreau2d392c22015-08-24 01:43:45 +02004277
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004278 Example :
4279 # prepend the host name before the path
4280 http-request set-path /%[hdr(host)]%[path]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004281
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004282http-request set-priority-class <expr> [ { if | unless } <condition> ]
Olivier Houchardccaa7de2017-10-02 11:51:03 +02004283
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004284 This is used to set the queue priority class of the current request.
4285 The value must be a sample expression which converts to an integer in the
4286 range -2047..2047. Results outside this range will be truncated.
4287 The priority class determines the order in which queued requests are
4288 processed. Lower values have higher priority.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004289
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004290http-request set-priority-offset <expr> [ { if | unless } <condition> ]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004291
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004292 This is used to set the queue priority timestamp offset of the current
4293 request. The value must be a sample expression which converts to an integer
4294 in the range -524287..524287. Results outside this range will be truncated.
4295 When a request is queued, it is ordered first by the priority class, then by
4296 the current timestamp adjusted by the given offset in milliseconds. Lower
4297 values have higher priority.
4298 Note that the resulting timestamp is is only tracked with enough precision
4299 for 524,287ms (8m44s287ms). If the request is queued long enough to where the
4300 adjusted timestamp exceeds this value, it will be misidentified as highest
4301 priority. Thus it is important to set "timeout queue" to a value, where when
4302 combined with the offset, does not exceed this limit.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004303
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004304http-request set-query <fmt> [ { if | unless } <condition> ]
Willy Tarreau20b0de52012-12-24 15:45:22 +01004305
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004306 This rewrites the request's query string which appears after the first
4307 question mark ("?") with the result of the evaluation of format string <fmt>.
4308 The part prior to the question mark is left intact. If the request doesn't
4309 contain a question mark and the new value is not empty, then one is added at
4310 the end of the URI, followed by the new value. If a question mark was
4311 present, it will never be removed even if the value is empty. This can be
4312 used to add or remove parameters from the query string.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004313
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004314 See also "http-request set-query" and "http-request set-uri".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004315
4316 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004317 # replace "%3D" with "=" in the query string
4318 http-request set-query %[query,regsub(%3D,=,g)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004319
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004320http-request set-src <expr> [ { if | unless } <condition> ]
4321 This is used to set the source IP address to the value of specified
4322 expression. Useful when a proxy in front of HAProxy rewrites source IP, but
4323 provides the correct IP in a HTTP header; or you want to mask source IP for
4324 privacy.
4325
4326 Arguments :
4327 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4328 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004329
Cyril Bonté78caf842010-03-10 22:41:43 +01004330 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004331 http-request set-src hdr(x-forwarded-for)
4332 http-request set-src src,ipmask(24)
4333
4334 When possible, set-src preserves the original source port as long as the
4335 address family allows it, otherwise the source port is set to 0.
4336
4337http-request set-src-port <expr> [ { if | unless } <condition> ]
4338
4339 This is used to set the source port address to the value of specified
4340 expression.
4341
4342 Arguments:
4343 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4344 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004345
Willy Tarreau20b0de52012-12-24 15:45:22 +01004346 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004347 http-request set-src-port hdr(x-port)
4348 http-request set-src-port int(4000)
4349
4350 When possible, set-src-port preserves the original source address as long as
4351 the address family supports a port, otherwise it forces the source address to
4352 IPv4 "0.0.0.0" before rewriting the port.
4353
4354http-request set-tos <tos> [ { if | unless } <condition> ]
4355
4356 This is used to set the TOS or DSCP field value of packets sent to the client
4357 to the value passed in <tos> on platforms which support this. This value
4358 represents the whole 8 bits of the IP TOS field, and can be expressed both in
4359 decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
4360 bits are used in DSCP or TOS, and the two lower bits are always 0. This can
4361 be used to adjust some routing behavior on border routers based on some
4362 information from the request.
4363
4364 See RFC 2474, 2597, 3260 and 4594 for more information.
4365
4366http-request set-uri <fmt> [ { if | unless } <condition> ]
4367
4368 This rewrites the request URI with the result of the evaluation of format
4369 string <fmt>. The scheme, authority, path and query string are all replaced
4370 at once. This can be used to rewrite hosts in front of proxies, or to
4371 perform complex modifications to the URI such as moving parts between the
4372 path and the query string.
4373 See also "http-request set-path" and "http-request set-query".
4374
4375http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ]
4376
4377 This is used to set the contents of a variable. The variable is declared
4378 inline.
4379
4380 Arguments:
4381 <var-name> The name of the variable starts with an indication about its
4382 scope. The scopes allowed are:
4383 "proc" : the variable is shared with the whole process
4384 "sess" : the variable is shared with the whole session
4385 "txn" : the variable is shared with the transaction
4386 (request and response)
4387 "req" : the variable is shared only during request
4388 processing
4389 "res" : the variable is shared only during response
4390 processing
4391 This prefix is followed by a name. The separator is a '.'.
4392 The name may only contain characters 'a-z', 'A-Z', '0-9'
4393 and '_'.
4394
4395 <expr> Is a standard HAProxy expression formed by a sample-fetch
4396 followed by some converters.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004397
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004398 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004399 http-request set-var(req.my_var) req.fhdr(user-agent),lower
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004400
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004401http-request send-spoe-group <engine-name> <group-name>
4402 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004403
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004404 This action is used to trigger sending of a group of SPOE messages. To do so,
4405 the SPOE engine used to send messages must be defined, as well as the SPOE
4406 group to send. Of course, the SPOE engine must refer to an existing SPOE
4407 filter. If not engine name is provided on the SPOE filter line, the SPOE
4408 agent name must be used.
4409
4410 Arguments:
4411 <engine-name> The SPOE engine name.
4412
4413 <group-name> The SPOE group name as specified in the engine
4414 configuration.
4415
4416http-request silent-drop [ { if | unless } <condition> ]
4417
4418 This stops the evaluation of the rules and makes the client-facing connection
4419 suddenly disappear using a system-dependent way that tries to prevent the
4420 client from being notified. The effect it then that the client still sees an
4421 established connection while there's none on HAProxy. The purpose is to
4422 achieve a comparable effect to "tarpit" except that it doesn't use any local
4423 resource at all on the machine running HAProxy. It can resist much higher
4424 loads than "tarpit", and slow down stronger attackers. It is important to
4425 understand the impact of using this mechanism. All stateful equipment placed
4426 between the client and HAProxy (firewalls, proxies, load balancers) will also
4427 keep the established connection for a long time and may suffer from this
4428 action.
4429 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
4430 option is used to block the emission of a TCP reset. On other systems, the
4431 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
4432 router, though it's still delivered to local networks. Do not use it unless
4433 you fully understand how it works.
4434
4435http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
4436
4437 This stops the evaluation of the rules and immediately blocks the request
4438 without responding for a delay specified by "timeout tarpit" or
4439 "timeout connect" if the former is not set. After that delay, if the client
4440 is still connected, an HTTP error 500 (or optionally the status code
4441 specified as an argument to "deny_status") is returned so that the client
4442 does not suspect it has been tarpitted. Logs will report the flags "PT".
4443 The goal of the tarpit rule is to slow down robots during an attack when
4444 they're limited on the number of concurrent requests. It can be very
4445 efficient against very dumb robots, and will significantly reduce the load
4446 on firewalls compared to a "deny" rule. But when facing "correctly"
4447 developed robots, it can make things worse by forcing haproxy and the front
4448 firewall to support insane number of concurrent connections.
4449 See also the "silent-drop" action.
4450
4451http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
4452http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
4453http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
4454
4455 This enables tracking of sticky counters from current request. These rules do
4456 not stop evaluation and do not change default action. The number of counters
4457 that may be simultaneously tracked by the same connection is set in
4458 MAX_SESS_STKCTR at build time (reported in haproxy -vv) which defaults to 3,
4459 so the track-sc number is between 0 and (MAX_SESS_STCKTR-1). The first
4460 "track-sc0" rule executed enables tracking of the counters of the specified
4461 table as the first set. The first "track-sc1" rule executed enables tracking
4462 of the counters of the specified table as the second set. The first
4463 "track-sc2" rule executed enables tracking of the counters of the specified
4464 table as the third set. It is a recommended practice to use the first set of
4465 counters for the per-frontend counters and the second set for the per-backend
4466 ones. But this is just a guideline, all may be used everywhere.
4467
4468 Arguments :
4469 <key> is mandatory, and is a sample expression rule as described in
4470 section 7.3. It describes what elements of the incoming request or
4471 connection will be analyzed, extracted, combined, and used to
4472 select which table entry to update the counters.
4473
4474 <table> is an optional table to be used instead of the default one, which
4475 is the stick-table declared in the current proxy. All the counters
4476 for the matches and updates for the key will then be performed in
4477 that table until the session ends.
4478
4479 Once a "track-sc*" rule is executed, the key is looked up in the table and if
4480 it is not found, an entry is allocated for it. Then a pointer to that entry
4481 is kept during all the session's life, and this entry's counters are updated
4482 as often as possible, every time the session's counters are updated, and also
4483 systematically when the session ends. Counters are only updated for events
4484 that happen after the tracking has been started. As an exception, connection
4485 counters and request counters are systematically updated so that they reflect
4486 useful information.
4487
4488 If the entry tracks concurrent connection counters, one connection is counted
4489 for as long as the entry is tracked, and the entry will not expire during
4490 that time. Tracking counters also provides a performance advantage over just
4491 checking the keys, because only one table lookup is performed for all ACL
4492 checks that make use of it.
4493
4494http-request unset-var(<var-name>) [ { if | unless } <condition> ]
4495
4496 This is used to unset a variable. See above for details about <var-name>.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004497
4498 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004499 http-request unset-var(req.my_var)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004500
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004501http-request wait-for-handshake [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004502
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004503 This will delay the processing of the request until the SSL handshake
4504 happened. This is mostly useful to delay processing early data until we're
4505 sure they are valid.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004506
Willy Tarreauef781042010-01-27 11:53:01 +01004507
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004508http-response <action> <options...> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004509 Access control for Layer 7 responses
4510
4511 May be used in sections: defaults | frontend | listen | backend
4512 no | yes | yes | yes
4513
4514 The http-response statement defines a set of rules which apply to layer 7
4515 processing. The rules are evaluated in their declaration order when they are
4516 met in a frontend, listen or backend section. Any rule may optionally be
4517 followed by an ACL-based condition, in which case it will only be evaluated
4518 if the condition is true. Since these rules apply on responses, the backend
4519 rules are applied first, followed by the frontend's rules.
4520
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004521 The first keyword is the rule's action. The supported actions are described
4522 below.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004523
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004524 There is no limit to the number of http-response statements per instance.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004525
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004526 It is important to know that http-response rules are processed very early in
4527 the HTTP processing, before "rspdel" or "rsprep" or "rspadd" rules. That way,
4528 headers added by "add-header"/"set-header" are visible by almost all further
4529 ACL rules.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004530
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004531 Using "rspadd"/"rspdel"/"rsprep" to manipulate request headers is discouraged
4532 in newer versions (>= 1.5). But if you need to use regular expression to
4533 delete headers, you can still use "rspdel". Also please use
4534 "http-response deny" instead of "rspdeny".
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004535
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004536 Example:
4537 acl key_acl res.hdr(X-Acl-Key) -m found
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02004538
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004539 acl myhost hdr(Host) -f myhost.lst
Sasha Pachev218f0642014-06-16 12:05:59 -06004540
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004541 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
4542 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
Sasha Pachev218f0642014-06-16 12:05:59 -06004543
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004544 Example:
4545 acl value res.hdr(X-Value) -m found
Sasha Pachev218f0642014-06-16 12:05:59 -06004546
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004547 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06004548
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004549 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
4550 http-response del-map(map.lst) %[src] if ! value
Sasha Pachev218f0642014-06-16 12:05:59 -06004551
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004552 See also : "http-request", section 3.4 about userlists and section 7 about
4553 ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06004554
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004555http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004556
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004557 This is used to add a new entry into an ACL. The ACL must be loaded from a
4558 file (even a dummy empty file). The file name of the ACL to be updated is
4559 passed between parentheses. It takes one argument: <key fmt>, which follows
4560 log-format rules, to collect content of the new entry. It performs a lookup
4561 in the ACL before insertion, to avoid duplicated (or more) values.
4562 This lookup is done by a linear search and can be expensive with large lists!
4563 It is the equivalent of the "add acl" command from the stats socket, but can
4564 be triggered by an HTTP response.
Sasha Pachev218f0642014-06-16 12:05:59 -06004565
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004566http-response add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004567
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004568 This appends an HTTP header field whose name is specified in <name> and whose
4569 value is defined by <fmt> which follows the log-format rules (see Custom Log
4570 Format in section 8.2.4). This may be used to send a cookie to a client for
4571 example, or to pass some internal information.
4572 This rule is not final, so it is possible to add other similar rules.
4573 Note that header addition is performed immediately, so one rule might reuse
4574 the resulting header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06004575
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004576http-response allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004577
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004578 This stops the evaluation of the rules and lets the response pass the check.
4579 No further "http-response" rules are evaluated for the current section.
Sasha Pachev218f0642014-06-16 12:05:59 -06004580
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004581http-response cache-store [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004582
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004583 See section 10.2 about cache setup.
Sasha Pachev218f0642014-06-16 12:05:59 -06004584
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004585http-response capture <sample> id <id> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004586
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004587 This captures sample expression <sample> from the response buffer, and
4588 converts it to a string. The resulting string is stored into the next request
4589 "capture" slot, so it will possibly appear next to some captured HTTP
4590 headers. It will then automatically appear in the logs, and it will be
4591 possible to extract it using sample fetch rules to feed it into headers or
4592 anything. Please check section 7.3 (Fetching samples) and
4593 "capture response header" for more information.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004594
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004595 The keyword "id" is the id of the capture slot which is used for storing the
4596 string. The capture slot must be defined in an associated frontend.
4597 This is useful to run captures in backends. The slot id can be declared by a
4598 previous directive "http-response capture" or with the "declare capture"
4599 keyword.
4600 If the slot <id> doesn't exist, then HAProxy fails parsing the configuration
4601 to prevent unexpected behavior at run time.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004602
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004603http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004604
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004605 This is used to delete an entry from an ACL. The ACL must be loaded from a
4606 file (even a dummy empty file). The file name of the ACL to be updated is
4607 passed between parentheses. It takes one argument: <key fmt>, which follows
4608 log-format rules, to collect content of the entry to delete.
4609 It is the equivalent of the "del acl" command from the stats socket, but can
4610 be triggered by an HTTP response.
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004611
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004612http-response del-header <name> [ { if | unless } <condition> ]
Willy Tarreau9a355ec2013-06-11 17:45:46 +02004613
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004614 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau42cf39e2013-06-11 18:51:32 +02004615
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004616http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau51347ed2013-06-11 19:34:13 +02004617
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004618 This is used to delete an entry from a MAP. The MAP must be loaded from a
4619 file (even a dummy empty file). The file name of the MAP to be updated is
4620 passed between parentheses. It takes one argument: <key fmt>, which follows
4621 log-format rules, to collect content of the entry to delete.
4622 It takes one argument: "file name" It is the equivalent of the "del map"
4623 command from the stats socket, but can be triggered by an HTTP response.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004624
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004625http-response deny [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004626
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004627 This stops the evaluation of the rules and immediately rejects the response
4628 and emits an HTTP 502 error. No further "http-response" rules are evaluated.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004629
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004630http-response redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004631
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004632 This performs an HTTP redirection based on a redirect rule.
4633 This supports a format string similarly to "http-request redirect" rules,
4634 with the exception that only the "location" type of redirect is possible on
4635 the response. See the "redirect" keyword for the rule's syntax. When a
4636 redirect rule is applied during a response, connections to the server are
4637 closed so that no data can be forwarded from the server to the client.
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02004638
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004639http-response replace-header <name> <regex-match> <replace-fmt>
4640 [ { if | unless } <condition> ]
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02004641
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004642 This matches the regular expression in all occurrences of header field <name>
4643 according to <match-regex>, and replaces them with the <replace-fmt> argument.
4644 Format characters are allowed in replace-fmt and work like in <fmt> arguments
4645 in "add-header". The match is only case-sensitive. It is important to
4646 understand that this action only considers whole header lines, regardless of
4647 the number of values they may contain. This usage is suited to headers
4648 naturally containing commas in their value, such as Set-Cookie, Expires and
4649 so on.
William Lallemand86d0df02017-11-24 21:36:45 +01004650
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004651 Example:
4652 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
Willy Tarreau51d861a2015-05-22 17:30:48 +02004653
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004654 # applied to:
4655 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004656
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004657 # outputs:
4658 Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004659
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004660 # assuming the backend IP is 192.168.1.20.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004661
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004662http-response replace-value <name> <regex-match> <replace-fmt>
4663 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004664
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004665 This works like "replace-header" except that it matches the regex against
4666 every comma-delimited value of the header field <name> instead of the entire
4667 header. This is suited for all headers which are allowed to carry more than
4668 one value. An example could be the Accept header.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004669
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004670 Example:
4671 http-response replace-value Cache-control ^public$ private
Christopher Faulet85d79c92016-11-09 16:54:56 +01004672
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004673 # applied to:
4674 Cache-Control: max-age=3600, public
Christopher Faulet85d79c92016-11-09 16:54:56 +01004675
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004676 # outputs:
4677 Cache-Control: max-age=3600, private
Christopher Faulet85d79c92016-11-09 16:54:56 +01004678
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004679http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
4680http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08004681
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004682 This action increments the GPC0 or GPC1 counter according with the sticky
4683 counter designated by <sc-id>. If an error occurs, this action silently fails
4684 and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004685
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004686http-response sc-set-gpt0(<sc-id>) <int> [ { if | unless } <condition> ]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004687
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004688 This action sets the GPT0 tag according to the sticky counter designated by
4689 <sc-id> and the value of <int>. The expected result is a boolean. If an error
4690 occurs, this action silently fails and the actions evaluation continues.
Frédéric Lécaille6778b272018-01-29 15:22:53 +01004691
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004692http-response send-spoe-group [ { if | unless } <condition> ]
Willy Tarreau2d392c22015-08-24 01:43:45 +02004693
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004694 This action is used to trigger sending of a group of SPOE messages. To do so,
4695 the SPOE engine used to send messages must be defined, as well as the SPOE
4696 group to send. Of course, the SPOE engine must refer to an existing SPOE
4697 filter. If not engine name is provided on the SPOE filter line, the SPOE
4698 agent name must be used.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004699
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004700 Arguments:
4701 <engine-name> The SPOE engine name.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004702
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004703 <group-name> The SPOE group name as specified in the engine
4704 configuration.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004705
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004706http-response set-header <name> <fmt> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004707
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004708 This does the same as "add-header" except that the header name is first
4709 removed if it existed. This is useful when passing security information to
4710 the server, where the header must not be manipulated by external users.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004711
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004712http-response set-log-level <level> [ { if | unless } <condition> ]
4713
4714 This is used to change the log level of the current request when a certain
4715 condition is met. Valid levels are the 8 syslog levels (see the "log"
4716 keyword) plus the special level "silent" which disables logging for this
4717 request. This rule is not final so the last matching rule wins. This rule can
4718 be useful to disable health checks coming from another equipment.
4719
4720http-response set-map(<file-name>) <key fmt> <value fmt>
4721
4722 This is used to add a new entry into a MAP. The MAP must be loaded from a
4723 file (even a dummy empty file). The file name of the MAP to be updated is
4724 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
4725 log-format rules, used to collect MAP key, and <value fmt>, which follows
4726 log-format rules, used to collect content for the new entry. It performs a
4727 lookup in the MAP before insertion, to avoid duplicated (or more) values.
4728 This lookup is done by a linear search and can be expensive with large lists!
4729 It is the equivalent of the "set map" command from the stats socket, but can
4730 be triggered by an HTTP response.
4731
4732http-response set-mark <mark> [ { if | unless } <condition> ]
4733
4734 This is used to set the Netfilter MARK on all packets sent to the client to
4735 the value passed in <mark> on platforms which support it. This value is an
4736 unsigned 32 bit value which can be matched by netfilter and by the routing
4737 table. It can be expressed both in decimal or hexadecimal format (prefixed
4738 by "0x"). This can be useful to force certain packets to take a different
4739 route (for example a cheaper network path for bulk downloads). This works on
4740 Linux kernels 2.6.32 and above and requires admin privileges.
4741
4742http-response set-nice <nice> [ { if | unless } <condition> ]
4743
4744 This sets the "nice" factor of the current request being processed.
4745 It only has effect against the other requests being processed at the same
4746 time. The default value is 0, unless altered by the "nice" setting on the
4747 "bind" line. The accepted range is -1024..1024. The higher the value, the
4748 nicest the request will be. Lower values will make the request more important
4749 than other ones. This can be useful to improve the speed of some requests, or
4750 lower the priority of non-important requests. Using this setting without
4751 prior experimentation can cause some major slowdown.
4752
4753http-response set-status <status> [reason <str>]
4754 [ { if | unless } <condition> ]
4755
4756 This replaces the response status code with <status> which must be an integer
4757 between 100 and 999. Optionally, a custom reason text can be provided defined
4758 by <str>, or the default reason for the specified code will be used as a
4759 fallback.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004760
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004761 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004762 # return "431 Request Header Fields Too Large"
4763 http-response set-status 431
4764 # return "503 Slow Down", custom reason
4765 http-response set-status 503 reason "Slow Down".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004766
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004767http-response set-tos <tos> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004768
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004769 This is used to set the TOS or DSCP field value of packets sent to the client
4770 to the value passed in <tos> on platforms which support this.
4771 This value represents the whole 8 bits of the IP TOS field, and can be
4772 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note that
4773 only the 6 higher bits are used in DSCP or TOS, and the two lower bits are
4774 always 0. This can be used to adjust some routing behavior on border routers
4775 based on some information from the request.
4776
4777 See RFC 2474, 2597, 3260 and 4594 for more information.
4778
4779http-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
4780
4781 This is used to set the contents of a variable. The variable is declared
4782 inline.
4783
4784 Arguments:
4785 <var-name> The name of the variable starts with an indication about its
4786 scope. The scopes allowed are:
4787 "proc" : the variable is shared with the whole process
4788 "sess" : the variable is shared with the whole session
4789 "txn" : the variable is shared with the transaction
4790 (request and response)
4791 "req" : the variable is shared only during request
4792 processing
4793 "res" : the variable is shared only during response
4794 processing
4795 This prefix is followed by a name. The separator is a '.'.
4796 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
4797 and '_'.
4798
4799 <expr> Is a standard HAProxy expression formed by a sample-fetch
4800 followed by some converters.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004801
4802 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004803 http-response set-var(sess.last_redir) res.hdr(location)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004804
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004805http-response silent-drop [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004806
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004807 This stops the evaluation of the rules and makes the client-facing connection
4808 suddenly disappear using a system-dependent way that tries to prevent the
4809 client from being notified. The effect it then that the client still sees an
4810 established connection while there's none on HAProxy. The purpose is to
4811 achieve a comparable effect to "tarpit" except that it doesn't use any local
4812 resource at all on the machine running HAProxy. It can resist much higher
4813 loads than "tarpit", and slow down stronger attackers. It is important to
4814 understand the impact of using this mechanism. All stateful equipment placed
4815 between the client and HAProxy (firewalls, proxies, load balancers) will also
4816 keep the established connection for a long time and may suffer from this
4817 action.
4818 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
4819 option is used to block the emission of a TCP reset. On other systems, the
4820 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
4821 router, though it's still delivered to local networks. Do not use it unless
4822 you fully understand how it works.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004823
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004824http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
4825http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
4826http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004827
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004828 This enables tracking of sticky counters from current response. Please refer
4829 to "http-request track-sc" for a complete description. The only difference
4830 from "http-request track-sc" is the <key> sample expression can only make use
4831 of samples in response (e.g. res.*, status etc.) and samples below Layer 6
4832 (e.g. SSL-related samples, see section 7.3.4). If the sample is not
4833 supported, haproxy will fail and warn while parsing the config.
4834
4835http-response unset-var(<var-name>) [ { if | unless } <condition> ]
4836
4837 This is used to unset a variable. See "http-response set-var" for details
4838 about <var-name>.
4839
4840 Example:
4841 http-response unset-var(sess.last_redir)
4842
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02004843
Willy Tarreau30631952015-08-06 15:05:24 +02004844http-reuse { never | safe | aggressive | always }
4845 Declare how idle HTTP connections may be shared between requests
4846
4847 May be used in sections: defaults | frontend | listen | backend
4848 yes | no | yes | yes
4849
4850 By default, a connection established between haproxy and the backend server
4851 belongs to the session that initiated it. The downside is that between the
4852 response and the next request, the connection remains idle and is not used.
4853 In many cases for performance reasons it is desirable to make it possible to
4854 reuse these idle connections to serve other requests from different sessions.
Davor Ocelice9ed2812017-12-25 17:49:28 +01004855 This directive allows to tune this behavior.
Willy Tarreau30631952015-08-06 15:05:24 +02004856
4857 The argument indicates the desired connection reuse strategy :
4858
4859 - "never" : idle connections are never shared between sessions. This is
4860 the default choice. It may be enforced to cancel a different
4861 strategy inherited from a defaults section or for
4862 troubleshooting. For example, if an old bogus application
4863 considers that multiple requests over the same connection come
4864 from the same client and it is not possible to fix the
4865 application, it may be desirable to disable connection sharing
4866 in a single backend. An example of such an application could
4867 be an old haproxy using cookie insertion in tunnel mode and
4868 not checking any request past the first one.
4869
4870 - "safe" : this is the recommended strategy. The first request of a
4871 session is always sent over its own connection, and only
4872 subsequent requests may be dispatched over other existing
4873 connections. This ensures that in case the server closes the
4874 connection when the request is being sent, the browser can
4875 decide to silently retry it. Since it is exactly equivalent to
4876 regular keep-alive, there should be no side effects.
4877
4878 - "aggressive" : this mode may be useful in webservices environments where
4879 all servers are not necessarily known and where it would be
4880 appreciable to deliver most first requests over existing
4881 connections. In this case, first requests are only delivered
4882 over existing connections that have been reused at least once,
4883 proving that the server correctly supports connection reuse.
4884 It should only be used when it's sure that the client can
4885 retry a failed request once in a while and where the benefit
4886 of aggressive connection reuse significantly outweights the
4887 downsides of rare connection failures.
4888
4889 - "always" : this mode is only recommended when the path to the server is
4890 known for never breaking existing connections quickly after
4891 releasing them. It allows the first request of a session to be
4892 sent to an existing connection. This can provide a significant
4893 performance increase over the "safe" strategy when the backend
4894 is a cache farm, since such components tend to show a
Davor Ocelice9ed2812017-12-25 17:49:28 +01004895 consistent behavior and will benefit from the connection
Willy Tarreau30631952015-08-06 15:05:24 +02004896 sharing. It is recommended that the "http-keep-alive" timeout
4897 remains low in this mode so that no dead connections remain
4898 usable. In most cases, this will lead to the same performance
4899 gains as "aggressive" but with more risks. It should only be
4900 used when it improves the situation over "aggressive".
4901
4902 When http connection sharing is enabled, a great care is taken to respect the
Davor Ocelice9ed2812017-12-25 17:49:28 +01004903 connection properties and compatibility. Specifically :
4904 - connections made with "usesrc" followed by a client-dependent value
4905 ("client", "clientip", "hdr_ip") are marked private and never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02004906
4907 - connections sent to a server with a TLS SNI extension are marked private
Davor Ocelice9ed2812017-12-25 17:49:28 +01004908 and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02004909
Lukas Tribusfd9b68c2018-10-27 20:06:59 +02004910 - connections with certain bogus authentication schemes (relying on the
4911 connection) like NTLM are detected, marked private and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02004912
4913 No connection pool is involved, once a session dies, the last idle connection
4914 it was attached to is deleted at the same time. This ensures that connections
4915 may not last after all sessions are closed.
4916
4917 Note: connection reuse improves the accuracy of the "server maxconn" setting,
4918 because almost no new connection will be established while idle connections
4919 remain available. This is particularly true with the "always" strategy.
4920
4921 See also : "option http-keep-alive", "server maxconn"
4922
4923
Mark Lamourinec2247f02012-01-04 13:02:01 -05004924http-send-name-header [<header>]
4925 Add the server name to a request. Use the header string given by <header>
4926
4927 May be used in sections: defaults | frontend | listen | backend
4928 yes | no | yes | yes
4929
4930 Arguments :
4931
4932 <header> The header string to use to send the server name
4933
4934 The "http-send-name-header" statement causes the name of the target
Davor Ocelice9ed2812017-12-25 17:49:28 +01004935 server to be added to the headers of an HTTP request. The name
Mark Lamourinec2247f02012-01-04 13:02:01 -05004936 is added with the header string proved.
4937
4938 See also : "server"
4939
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01004940id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02004941 Set a persistent ID to a proxy.
4942 May be used in sections : defaults | frontend | listen | backend
4943 no | yes | yes | yes
4944 Arguments : none
4945
4946 Set a persistent ID for the proxy. This ID must be unique and positive.
4947 An unused ID will automatically be assigned if unset. The first assigned
4948 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01004949
4950
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004951ignore-persist { if | unless } <condition>
4952 Declare a condition to ignore persistence
4953 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01004954 no | no | yes | yes
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004955
4956 By default, when cookie persistence is enabled, every requests containing
4957 the cookie are unconditionally persistent (assuming the target server is up
4958 and running).
4959
4960 The "ignore-persist" statement allows one to declare various ACL-based
4961 conditions which, when met, will cause a request to ignore persistence.
4962 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03004963 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004964 persistence for a specific User-Agent (for example, some web crawler bots).
4965
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004966 The persistence is ignored when an "if" condition is met, or unless an
4967 "unless" condition is met.
4968
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03004969 Example:
4970 acl url_static path_beg /static /images /img /css
4971 acl url_static path_end .gif .png .jpg .css .js
4972 ignore-persist if url_static
4973
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004974 See also : "force-persist", "cookie", and section 7 about ACL usage.
4975
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004976load-server-state-from-file { global | local | none }
4977 Allow seamless reload of HAProxy
4978 May be used in sections: defaults | frontend | listen | backend
4979 yes | no | yes | yes
4980
4981 This directive points HAProxy to a file where server state from previous
4982 running process has been saved. That way, when starting up, before handling
4983 traffic, the new process can apply old states to servers exactly has if no
Davor Ocelice9ed2812017-12-25 17:49:28 +01004984 reload occurred. The purpose of the "load-server-state-from-file" directive is
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004985 to tell haproxy which file to use. For now, only 2 arguments to either prevent
4986 loading state or load states from a file containing all backends and servers.
4987 The state file can be generated by running the command "show servers state"
4988 over the stats socket and redirect output.
4989
Davor Ocelice9ed2812017-12-25 17:49:28 +01004990 The format of the file is versioned and is very specific. To understand it,
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004991 please read the documentation of the "show servers state" command (chapter
Willy Tarreau1af20c72017-06-23 16:01:14 +02004992 9.3 of Management Guide).
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004993
4994 Arguments:
4995 global load the content of the file pointed by the global directive
4996 named "server-state-file".
4997
4998 local load the content of the file pointed by the directive
4999 "server-state-file-name" if set. If not set, then the backend
5000 name is used as a file name.
5001
5002 none don't load any stat for this backend
5003
5004 Notes:
Willy Tarreaue5a60682016-11-09 14:54:53 +01005005 - server's IP address is preserved across reloads by default, but the
5006 order can be changed thanks to the server's "init-addr" setting. This
5007 means that an IP address change performed on the CLI at run time will
Davor Ocelice9ed2812017-12-25 17:49:28 +01005008 be preserved, and that any change to the local resolver (e.g. /etc/hosts)
Willy Tarreaue5a60682016-11-09 14:54:53 +01005009 will possibly not have any effect if the state file is in use.
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005010
5011 - server's weight is applied from previous running process unless it has
5012 has changed between previous and new configuration files.
5013
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005014 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005015
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005016 global
5017 stats socket /tmp/socket
5018 server-state-file /tmp/server_state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005019
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005020 defaults
5021 load-server-state-from-file global
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005022
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005023 backend bk
5024 server s1 127.0.0.1:22 check weight 11
5025 server s2 127.0.0.1:22 check weight 12
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005026
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005027
5028 Then one can run :
5029
5030 socat /tmp/socket - <<< "show servers state" > /tmp/server_state
5031
5032 Content of the file /tmp/server_state would be like this:
5033
5034 1
5035 # <field names skipped for the doc example>
5036 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
5037 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
5038
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005039 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005040
5041 global
5042 stats socket /tmp/socket
5043 server-state-base /etc/haproxy/states
5044
5045 defaults
5046 load-server-state-from-file local
5047
5048 backend bk
5049 server s1 127.0.0.1:22 check weight 11
5050 server s2 127.0.0.1:22 check weight 12
5051
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005052
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005053 Then one can run :
5054
5055 socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
5056
5057 Content of the file /etc/haproxy/states/bk would be like this:
5058
5059 1
5060 # <field names skipped for the doc example>
5061 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
5062 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
5063
5064 See also: "server-state-file", "server-state-file-name", and
5065 "show servers state"
5066
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005067
Willy Tarreau2769aa02007-12-27 18:26:09 +01005068log global
Willy Tarreau18324f52014-06-27 18:10:07 +02005069log <address> [len <length>] <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02005070no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01005071 Enable per-instance logging of events and traffic.
5072 May be used in sections : defaults | frontend | listen | backend
5073 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02005074
5075 Prefix :
5076 no should be used when the logger list must be flushed. For example,
5077 if you don't want to inherit from the default logger list. This
5078 prefix does not allow arguments.
5079
Willy Tarreau2769aa02007-12-27 18:26:09 +01005080 Arguments :
5081 global should be used when the instance's logging parameters are the
5082 same as the global ones. This is the most common usage. "global"
5083 replaces <address>, <facility> and <level> with those of the log
5084 entries found in the "global" section. Only one "log global"
5085 statement may be used per instance, and this form takes no other
5086 parameter.
5087
5088 <address> indicates where to send the logs. It takes the same format as
5089 for the "global" section's logs, and can be one of :
5090
5091 - An IPv4 address optionally followed by a colon (':') and a UDP
5092 port. If no port is specified, 514 is used by default (the
5093 standard syslog port).
5094
David du Colombier24bb5f52011-03-17 10:40:23 +01005095 - An IPv6 address followed by a colon (':') and optionally a UDP
5096 port. If no port is specified, 514 is used by default (the
5097 standard syslog port).
5098
Willy Tarreau2769aa02007-12-27 18:26:09 +01005099 - A filesystem path to a UNIX domain socket, keeping in mind
5100 considerations for chroot (be sure the path is accessible
5101 inside the chroot) and uid/gid (be sure the path is
Davor Ocelice9ed2812017-12-25 17:49:28 +01005102 appropriately writable).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005103
William Lallemandb2f07452015-05-12 14:27:13 +02005104 You may want to reference some environment variables in the
5105 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01005106
Willy Tarreau18324f52014-06-27 18:10:07 +02005107 <length> is an optional maximum line length. Log lines larger than this
5108 value will be truncated before being sent. The reason is that
5109 syslog servers act differently on log line length. All servers
5110 support the default value of 1024, but some servers simply drop
5111 larger lines while others do log them. If a server supports long
5112 lines, it may make sense to set this value here in order to avoid
5113 truncating long lines. Similarly, if a server drops long lines,
5114 it is preferable to truncate them before sending them. Accepted
5115 values are 80 to 65535 inclusive. The default value of 1024 is
5116 generally fine for all standard usages. Some specific cases of
Davor Ocelice9ed2812017-12-25 17:49:28 +01005117 long captures or JSON-formatted logs may require larger values.
Willy Tarreau18324f52014-06-27 18:10:07 +02005118
Willy Tarreau2769aa02007-12-27 18:26:09 +01005119 <facility> must be one of the 24 standard syslog facilities :
5120
5121 kern user mail daemon auth syslog lpr news
5122 uucp cron auth2 ftp ntp audit alert cron2
5123 local0 local1 local2 local3 local4 local5 local6 local7
5124
5125 <level> is optional and can be specified to filter outgoing messages. By
5126 default, all messages are sent. If a level is specified, only
5127 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005128 will be sent. An optional minimum level can be specified. If it
5129 is set, logs emitted with a more severe level than this one will
5130 be capped to this level. This is used to avoid sending "emerg"
5131 messages on all terminals on some default syslog configurations.
5132 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005133
5134 emerg alert crit err warning notice info debug
5135
William Lallemand0f99e342011-10-12 17:50:54 +02005136 It is important to keep in mind that it is the frontend which decides what to
5137 log from a connection, and that in case of content switching, the log entries
5138 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005139
5140 However, backend log declaration define how and where servers status changes
5141 will be logged. Level "notice" will be used to indicate a server going up,
5142 "warning" will be used for termination signals and definitive service
5143 termination, and "alert" will be used for when a server goes down.
5144
5145 Note : According to RFC3164, messages are truncated to 1024 bytes before
5146 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005147
5148 Example :
5149 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005150 log 127.0.0.1:514 local0 notice # only send important events
5151 log 127.0.0.1:514 local0 notice notice # same but limit output level
William Lallemandb2f07452015-05-12 14:27:13 +02005152 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01005153
Willy Tarreau2769aa02007-12-27 18:26:09 +01005154
William Lallemand48940402012-01-30 16:47:22 +01005155log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005156 Specifies the log format string to use for traffic logs
5157 May be used in sections: defaults | frontend | listen | backend
5158 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01005159
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005160 This directive specifies the log format string that will be used for all logs
5161 resulting from traffic passing through the frontend using this line. If the
5162 directive is used in a defaults section, all subsequent frontends will use
5163 the same log format. Please see section 8.2.4 which covers the log format
5164 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01005165
Guillaume de Lafond29f45602017-03-31 19:52:15 +02005166 "log-format" directive overrides previous "option tcplog", "log-format" and
5167 "option httplog" directives.
5168
Dragan Dosen7ad31542015-09-28 17:16:47 +02005169log-format-sd <string>
5170 Specifies the RFC5424 structured-data log format string
5171 May be used in sections: defaults | frontend | listen | backend
5172 yes | yes | yes | no
5173
5174 This directive specifies the RFC5424 structured-data log format string that
5175 will be used for all logs resulting from traffic passing through the frontend
5176 using this line. If the directive is used in a defaults section, all
5177 subsequent frontends will use the same log format. Please see section 8.2.4
5178 which covers the log format string in depth.
5179
5180 See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
5181 about the RFC5424 structured-data part.
5182
5183 Note : This log format string will be used only for loggers that have set
5184 log format to "rfc5424".
5185
5186 Example :
5187 log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
5188
5189
Willy Tarreau094af4e2015-01-07 15:03:42 +01005190log-tag <string>
5191 Specifies the log tag to use for all outgoing logs
5192 May be used in sections: defaults | frontend | listen | backend
5193 yes | yes | yes | yes
5194
5195 Sets the tag field in the syslog header to this string. It defaults to the
5196 log-tag set in the global section, otherwise the program name as launched
5197 from the command line, which usually is "haproxy". Sometimes it can be useful
5198 to differentiate between multiple processes running on the same host, or to
5199 differentiate customer instances running in the same process. In the backend,
5200 logs about servers up/down will use this tag. As a hint, it can be convenient
5201 to set a log-tag related to a hosted customer in a defaults section then put
5202 all the frontends and backends for that customer, then start another customer
5203 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005204
Willy Tarreauc35362a2014-04-25 13:58:37 +02005205max-keep-alive-queue <value>
5206 Set the maximum server queue size for maintaining keep-alive connections
5207 May be used in sections: defaults | frontend | listen | backend
5208 yes | no | yes | yes
5209
5210 HTTP keep-alive tries to reuse the same server connection whenever possible,
5211 but sometimes it can be counter-productive, for example if a server has a lot
5212 of connections while other ones are idle. This is especially true for static
5213 servers.
5214
5215 The purpose of this setting is to set a threshold on the number of queued
5216 connections at which haproxy stops trying to reuse the same server and prefers
5217 to find another one. The default value, -1, means there is no limit. A value
5218 of zero means that keep-alive requests will never be queued. For very close
5219 servers which can be reached with a low latency and which are not sensible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01005220 breaking keep-alive, a low value is recommended (e.g. local static server can
Willy Tarreauc35362a2014-04-25 13:58:37 +02005221 use a value of 10 or less). For remote servers suffering from a high latency,
5222 higher values might be needed to cover for the latency and/or the cost of
5223 picking a different server.
5224
5225 Note that this has no impact on responses which are maintained to the same
5226 server consecutively to a 401 response. They will still go to the same server
5227 even if they have to be queued.
5228
5229 See also : "option http-server-close", "option prefer-last-server", server
5230 "maxconn" and cookie persistence.
5231
5232
Willy Tarreau2769aa02007-12-27 18:26:09 +01005233maxconn <conns>
5234 Fix the maximum number of concurrent connections on a frontend
5235 May be used in sections : defaults | frontend | listen | backend
5236 yes | yes | yes | no
5237 Arguments :
5238 <conns> is the maximum number of concurrent connections the frontend will
5239 accept to serve. Excess connections will be queued by the system
5240 in the socket's listen queue and will be served once a connection
5241 closes.
5242
5243 If the system supports it, it can be useful on big sites to raise this limit
5244 very high so that haproxy manages connection queues, instead of leaving the
5245 clients with unanswered connection attempts. This value should not exceed the
5246 global maxconn. Also, keep in mind that a connection contains two buffers
Baptiste Assmann79fb45d2016-03-06 23:34:31 +01005247 of tune.bufsize (16kB by default) each, as well as some other data resulting
5248 in about 33 kB of RAM being consumed per established connection. That means
5249 that a medium system equipped with 1GB of RAM can withstand around
5250 20000-25000 concurrent connections if properly tuned.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005251
5252 Also, when <conns> is set to large values, it is possible that the servers
5253 are not sized to accept such loads, and for this reason it is generally wise
5254 to assign them some reasonable connection limits.
5255
Vincent Bernat6341be52012-06-27 17:18:30 +02005256 By default, this value is set to 2000.
5257
Willy Tarreau2769aa02007-12-27 18:26:09 +01005258 See also : "server", global section's "maxconn", "fullconn"
5259
5260
5261mode { tcp|http|health }
5262 Set the running mode or protocol of the instance
5263 May be used in sections : defaults | frontend | listen | backend
5264 yes | yes | yes | yes
5265 Arguments :
5266 tcp The instance will work in pure TCP mode. A full-duplex connection
5267 will be established between clients and servers, and no layer 7
5268 examination will be performed. This is the default mode. It
5269 should be used for SSL, SSH, SMTP, ...
5270
5271 http The instance will work in HTTP mode. The client request will be
5272 analyzed in depth before connecting to any server. Any request
5273 which is not RFC-compliant will be rejected. Layer 7 filtering,
5274 processing and switching will be possible. This is the mode which
5275 brings HAProxy most of its value.
5276
5277 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02005278 to incoming connections and close the connection. Alternatively,
5279 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
5280 instead. Nothing will be logged in either case. This mode is used
5281 to reply to external components health checks. This mode is
5282 deprecated and should not be used anymore as it is possible to do
5283 the same and even better by combining TCP or HTTP modes with the
5284 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005285
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005286 When doing content switching, it is mandatory that the frontend and the
5287 backend are in the same mode (generally HTTP), otherwise the configuration
5288 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005289
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005290 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005291 defaults http_instances
5292 mode http
5293
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005294 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005295
Willy Tarreau0ba27502007-12-24 16:55:16 +01005296
Cyril Bontéf0c60612010-02-06 14:44:47 +01005297monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01005298 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005299 May be used in sections : defaults | frontend | listen | backend
5300 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01005301 Arguments :
5302 if <cond> the monitor request will fail if the condition is satisfied,
5303 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005304 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01005305 are met, for instance a low number of servers both in a
5306 backend and its backup.
5307
5308 unless <cond> the monitor request will succeed only if the condition is
5309 satisfied, and will fail otherwise. Such a condition may be
5310 based on a test on the presence of a minimum number of active
5311 servers in a list of backends.
5312
5313 This statement adds a condition which can force the response to a monitor
5314 request to report a failure. By default, when an external component queries
5315 the URI dedicated to monitoring, a 200 response is returned. When one of the
5316 conditions above is met, haproxy will return 503 instead of 200. This is
5317 very useful to report a site failure to an external component which may base
5318 routing advertisements between multiple sites on the availability reported by
5319 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005320 criterion. Note that "monitor fail" only works in HTTP mode. Both status
5321 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005322
5323 Example:
5324 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01005325 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01005326 acl site_dead nbsrv(dynamic) lt 2
5327 acl site_dead nbsrv(static) lt 2
5328 monitor-uri /site_alive
5329 monitor fail if site_dead
5330
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005331 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005332
5333
5334monitor-net <source>
5335 Declare a source network which is limited to monitor requests
5336 May be used in sections : defaults | frontend | listen | backend
5337 yes | yes | yes | no
5338 Arguments :
5339 <source> is the source IPv4 address or network which will only be able to
5340 get monitor responses to any request. It can be either an IPv4
5341 address, a host name, or an address followed by a slash ('/')
5342 followed by a mask.
5343
5344 In TCP mode, any connection coming from a source matching <source> will cause
5345 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005346 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01005347 forwarding the connection to a remote server.
5348
5349 In HTTP mode, a connection coming from a source matching <source> will be
5350 accepted, the following response will be sent without waiting for a request,
5351 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
5352 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02005353 running without forwarding the request to a backend server. Note that this
5354 response is sent in raw format, without any transformation. This is important
5355 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005356
Willy Tarreau82569f92012-09-27 23:48:56 +02005357 Monitor requests are processed very early, just after tcp-request connection
5358 ACLs which are the only ones able to block them. These connections are short
5359 lived and never wait for any data from the client. They cannot be logged, and
5360 it is the intended purpose. They are only used to report HAProxy's health to
5361 an upper component, nothing more. Please note that "monitor fail" rules do
5362 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01005363
Willy Tarreau95cd2832010-03-04 23:36:33 +01005364 Last, please note that only one "monitor-net" statement can be specified in
5365 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005366
Willy Tarreau2769aa02007-12-27 18:26:09 +01005367 Example :
5368 # addresses .252 and .253 are just probing us.
5369 frontend www
5370 monitor-net 192.168.0.252/31
5371
5372 See also : "monitor fail", "monitor-uri"
5373
5374
5375monitor-uri <uri>
5376 Intercept a URI used by external components' monitor requests
5377 May be used in sections : defaults | frontend | listen | backend
5378 yes | yes | yes | no
5379 Arguments :
5380 <uri> is the exact URI which we want to intercept to return HAProxy's
5381 health status instead of forwarding the request.
5382
5383 When an HTTP request referencing <uri> will be received on a frontend,
5384 HAProxy will not forward it nor log it, but instead will return either
5385 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
5386 conditions defined with "monitor fail". This is normally enough for any
5387 front-end HTTP probe to detect that the service is UP and running without
5388 forwarding the request to a backend server. Note that the HTTP method, the
5389 version and all headers are ignored, but the request must at least be valid
5390 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
5391
Willy Tarreau721d8e02017-12-01 18:25:08 +01005392 Monitor requests are processed very early, just after the request is parsed
5393 and even before any "http-request" or "block" rulesets. The only rulesets
5394 applied before are the tcp-request ones. They cannot be logged either, and it
5395 is the intended purpose. They are only used to report HAProxy's health to an
5396 upper component, nothing more. However, it is possible to add any number of
5397 conditions using "monitor fail" and ACLs so that the result can be adjusted
5398 to whatever check can be imagined (most often the number of available servers
5399 in a backend).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005400
5401 Example :
5402 # Use /haproxy_test to report haproxy's status
5403 frontend www
5404 mode http
5405 monitor-uri /haproxy_test
5406
5407 See also : "monitor fail", "monitor-net"
5408
Willy Tarreau0ba27502007-12-24 16:55:16 +01005409
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005410option abortonclose
5411no option abortonclose
5412 Enable or disable early dropping of aborted requests pending in queues.
5413 May be used in sections : defaults | frontend | listen | backend
5414 yes | no | yes | yes
5415 Arguments : none
5416
5417 In presence of very high loads, the servers will take some time to respond.
5418 The per-instance connection queue will inflate, and the response time will
5419 increase respective to the size of the queue times the average per-session
5420 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01005421 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005422 the queue, and slowing down other users, and the servers as well, because the
5423 request will eventually be served, then aborted at the first error
5424 encountered while delivering the response.
5425
5426 As there is no way to distinguish between a full STOP and a simple output
5427 close on the client side, HTTP agents should be conservative and consider
5428 that the client might only have closed its output channel while waiting for
5429 the response. However, this introduces risks of congestion when lots of users
5430 do the same, and is completely useless nowadays because probably no client at
5431 all will close the session while waiting for the response. Some HTTP agents
Davor Ocelice9ed2812017-12-25 17:49:28 +01005432 support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005433 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01005434 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005435 of being the single component to break rare but valid traffic is extremely
5436 low, which adds to the temptation to be able to abort a session early while
5437 still not served and not pollute the servers.
5438
Davor Ocelice9ed2812017-12-25 17:49:28 +01005439 In HAProxy, the user can choose the desired behavior using the option
5440 "abortonclose". By default (without the option) the behavior is HTTP
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005441 compliant and aborted requests will be served. But when the option is
5442 specified, a session with an incoming channel closed will be aborted while
5443 it is still possible, either pending in the queue for a connection slot, or
5444 during the connection establishment if the server has not yet acknowledged
5445 the connection request. This considerably reduces the queue size and the load
5446 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01005447 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005448
5449 If this option has been enabled in a "defaults" section, it can be disabled
5450 in a specific instance by prepending the "no" keyword before it.
5451
5452 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
5453
5454
Willy Tarreau4076a152009-04-02 15:18:36 +02005455option accept-invalid-http-request
5456no option accept-invalid-http-request
5457 Enable or disable relaxing of HTTP request parsing
5458 May be used in sections : defaults | frontend | listen | backend
5459 yes | yes | yes | no
5460 Arguments : none
5461
Willy Tarreau91852eb2015-05-01 13:26:00 +02005462 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02005463 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01005464 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02005465 forbidden characters are essentially used to build attacks exploiting server
5466 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
5467 server will emit invalid header names for whatever reason (configuration,
5468 implementation) and the issue will not be immediately fixed. In such a case,
5469 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01005470 even if that does not make sense, by specifying this option. Similarly, the
5471 list of characters allowed to appear in a URI is well defined by RFC3986, and
5472 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
5473 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
Davor Ocelice9ed2812017-12-25 17:49:28 +01005474 not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02005475 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02005476 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
5477 to pass through (no version specified) and multiple digits for both the major
5478 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02005479
5480 This option should never be enabled by default as it hides application bugs
5481 and open security breaches. It should only be deployed after a problem has
5482 been confirmed.
5483
5484 When this option is enabled, erroneous header names will still be accepted in
5485 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01005486 analysis using the "show errors" request on the UNIX stats socket. Similarly,
5487 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02005488 also helps confirming that the issue has been solved.
5489
5490 If this option has been enabled in a "defaults" section, it can be disabled
5491 in a specific instance by prepending the "no" keyword before it.
5492
5493 See also : "option accept-invalid-http-response" and "show errors" on the
5494 stats socket.
5495
5496
5497option accept-invalid-http-response
5498no option accept-invalid-http-response
5499 Enable or disable relaxing of HTTP response parsing
5500 May be used in sections : defaults | frontend | listen | backend
5501 yes | no | yes | yes
5502 Arguments : none
5503
Willy Tarreau91852eb2015-05-01 13:26:00 +02005504 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02005505 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01005506 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02005507 forbidden characters are essentially used to build attacks exploiting server
5508 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
5509 server will emit invalid header names for whatever reason (configuration,
5510 implementation) and the issue will not be immediately fixed. In such a case,
5511 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02005512 even if that does not make sense, by specifying this option. This option also
5513 relaxes the test on the HTTP version format, it allows multiple digits for
5514 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02005515
5516 This option should never be enabled by default as it hides application bugs
5517 and open security breaches. It should only be deployed after a problem has
5518 been confirmed.
5519
5520 When this option is enabled, erroneous header names will still be accepted in
5521 responses, but the complete response will be captured in order to permit
5522 later analysis using the "show errors" request on the UNIX stats socket.
5523 Doing this also helps confirming that the issue has been solved.
5524
5525 If this option has been enabled in a "defaults" section, it can be disabled
5526 in a specific instance by prepending the "no" keyword before it.
5527
5528 See also : "option accept-invalid-http-request" and "show errors" on the
5529 stats socket.
5530
5531
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005532option allbackups
5533no option allbackups
5534 Use either all backup servers at a time or only the first one
5535 May be used in sections : defaults | frontend | listen | backend
5536 yes | no | yes | yes
5537 Arguments : none
5538
5539 By default, the first operational backup server gets all traffic when normal
5540 servers are all down. Sometimes, it may be preferred to use multiple backups
5541 at once, because one will not be enough. When "option allbackups" is enabled,
5542 the load balancing will be performed among all backup servers when all normal
5543 ones are unavailable. The same load balancing algorithm will be used and the
5544 servers' weights will be respected. Thus, there will not be any priority
5545 order between the backup servers anymore.
5546
5547 This option is mostly used with static server farms dedicated to return a
5548 "sorry" page when an application is completely offline.
5549
5550 If this option has been enabled in a "defaults" section, it can be disabled
5551 in a specific instance by prepending the "no" keyword before it.
5552
5553
5554option checkcache
5555no option checkcache
Godbach7056a352013-12-11 20:01:07 +08005556 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005557 May be used in sections : defaults | frontend | listen | backend
5558 yes | no | yes | yes
5559 Arguments : none
5560
5561 Some high-level frameworks set application cookies everywhere and do not
5562 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005563 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005564 high risk of session crossing or stealing between users traversing the same
5565 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005566 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005567
5568 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005569 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01005570 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005571 response to check if there's a risk of caching a cookie on a client-side
5572 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01005573 to the client are :
Davor Ocelice9ed2812017-12-25 17:49:28 +01005574 - all those without "Set-Cookie" header;
Willy Tarreauc55ddce2017-12-21 11:41:38 +01005575 - all those with a return code other than 200, 203, 204, 206, 300, 301,
5576 404, 405, 410, 414, 501, provided that the server has not set a
Davor Ocelice9ed2812017-12-25 17:49:28 +01005577 "Cache-control: public" header field;
Willy Tarreau24ea0bc2017-12-21 11:32:55 +01005578 - all those that result from a request using a method other than GET, HEAD,
5579 OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
Davor Ocelice9ed2812017-12-25 17:49:28 +01005580 public' header field;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005581 - those with a 'Pragma: no-cache' header
5582 - those with a 'Cache-control: private' header
5583 - those with a 'Cache-control: no-store' header
5584 - those with a 'Cache-control: max-age=0' header
5585 - those with a 'Cache-control: s-maxage=0' header
5586 - those with a 'Cache-control: no-cache' header
5587 - those with a 'Cache-control: no-cache="set-cookie"' header
5588 - those with a 'Cache-control: no-cache="set-cookie,' header
5589 (allowing other fields after set-cookie)
5590
5591 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01005592 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005593 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005594 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005595 that admins are informed that there's something to be fixed.
5596
5597 Due to the high impact on the application, the application should be tested
5598 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005599 good practice to always activate it during tests, even if it is not used in
Davor Ocelice9ed2812017-12-25 17:49:28 +01005600 production, as it will report potentially dangerous application behaviors.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005601
5602 If this option has been enabled in a "defaults" section, it can be disabled
5603 in a specific instance by prepending the "no" keyword before it.
5604
5605
5606option clitcpka
5607no option clitcpka
5608 Enable or disable the sending of TCP keepalive packets on the client side
5609 May be used in sections : defaults | frontend | listen | backend
5610 yes | yes | yes | no
5611 Arguments : none
5612
5613 When there is a firewall or any session-aware component between a client and
5614 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01005615 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005616 components decides to expire a session which has remained idle for too long.
5617
5618 Enabling socket-level TCP keep-alives makes the system regularly send packets
5619 to the other end of the connection, leaving it active. The delay between
5620 keep-alive probes is controlled by the system only and depends both on the
5621 operating system and its tuning parameters.
5622
5623 It is important to understand that keep-alive packets are neither emitted nor
5624 received at the application level. It is only the network stacks which sees
5625 them. For this reason, even if one side of the proxy already uses keep-alives
5626 to maintain its connection alive, those keep-alive packets will not be
5627 forwarded to the other side of the proxy.
5628
5629 Please note that this has nothing to do with HTTP keep-alive.
5630
5631 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
5632 client side of a connection, which should help when session expirations are
5633 noticed between HAProxy and a client.
5634
5635 If this option has been enabled in a "defaults" section, it can be disabled
5636 in a specific instance by prepending the "no" keyword before it.
5637
5638 See also : "option srvtcpka", "option tcpka"
5639
5640
Willy Tarreau0ba27502007-12-24 16:55:16 +01005641option contstats
5642 Enable continuous traffic statistics updates
5643 May be used in sections : defaults | frontend | listen | backend
5644 yes | yes | yes | no
5645 Arguments : none
5646
5647 By default, counters used for statistics calculation are incremented
5648 only when a session finishes. It works quite well when serving small
5649 objects, but with big ones (for example large images or archives) or
5650 with A/V streaming, a graph generated from haproxy counters looks like
Willy Tarreaudef0d222016-11-08 22:03:00 +01005651 a hedgehog. With this option enabled counters get incremented frequently
5652 along the session, typically every 5 seconds, which is often enough to
5653 produce clean graphs. Recounting touches a hotpath directly so it is not
5654 not enabled by default, as it can cause a lot of wakeups for very large
5655 session counts and cause a small performance drop.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005656
5657
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005658option dontlog-normal
5659no option dontlog-normal
5660 Enable or disable logging of normal, successful connections
5661 May be used in sections : defaults | frontend | listen | backend
5662 yes | yes | yes | no
5663 Arguments : none
5664
5665 There are large sites dealing with several thousand connections per second
5666 and for which logging is a major pain. Some of them are even forced to turn
5667 logs off and cannot debug production issues. Setting this option ensures that
5668 normal connections, those which experience no error, no timeout, no retry nor
5669 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
5670 mode, the response status code is checked and return codes 5xx will still be
5671 logged.
5672
5673 It is strongly discouraged to use this option as most of the time, the key to
5674 complex issues is in the normal logs which will not be logged here. If you
5675 need to separate logs, see the "log-separate-errors" option instead.
5676
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005677 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005678 logging.
5679
5680
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005681option dontlognull
5682no option dontlognull
5683 Enable or disable logging of null connections
5684 May be used in sections : defaults | frontend | listen | backend
5685 yes | yes | yes | no
5686 Arguments : none
5687
5688 In certain environments, there are components which will regularly connect to
5689 various systems to ensure that they are still alive. It can be the case from
5690 another load balancer as well as from monitoring systems. By default, even a
5691 simple port probe or scan will produce a log. If those connections pollute
5692 the logs too much, it is possible to enable option "dontlognull" to indicate
5693 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02005694 which typically corresponds to those probes. Note that errors will still be
5695 returned to the client and accounted for in the stats. If this is not what is
5696 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005697
5698 It is generally recommended not to use this option in uncontrolled
Davor Ocelice9ed2812017-12-25 17:49:28 +01005699 environments (e.g. internet), otherwise scans and other malicious activities
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005700 would not be logged.
5701
5702 If this option has been enabled in a "defaults" section, it can be disabled
5703 in a specific instance by prepending the "no" keyword before it.
5704
Willy Tarreau0f228a02015-05-01 15:37:53 +02005705 See also : "log", "http-ignore-probes", "monitor-net", "monitor-uri", and
5706 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005707
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005708
Christopher Faulet315b39c2018-09-21 16:26:19 +02005709option forceclose (deprecated)
5710no option forceclose (deprecated)
5711 This is an alias for "option httpclose". Thus this option is deprecated.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005712
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005713 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005714
5715
Willy Tarreau87cf5142011-08-19 22:57:24 +02005716option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01005717 Enable insertion of the X-Forwarded-For header to requests sent to servers
5718 May be used in sections : defaults | frontend | listen | backend
5719 yes | yes | yes | yes
5720 Arguments :
5721 <network> is an optional argument used to disable this option for sources
5722 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02005723 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01005724 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005725
5726 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
5727 their client address. This is sometimes annoying when the client's IP address
5728 is expected in server logs. To solve this problem, the well-known HTTP header
5729 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
5730 This header contains a value representing the client's IP address. Since this
5731 header is always appended at the end of the existing header list, the server
5732 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02005733 the server's manual to find how to enable use of this standard header. Note
5734 that only the last occurrence of the header must be used, since it is really
5735 possible that the client has already brought one.
5736
Willy Tarreaud72758d2010-01-12 10:42:19 +01005737 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02005738 the default "X-Forwarded-For". This can be useful where you might already
Davor Ocelice9ed2812017-12-25 17:49:28 +01005739 have a "X-Forwarded-For" header from a different application (e.g. stunnel),
Willy Tarreaud72758d2010-01-12 10:42:19 +01005740 and you need preserve it. Also if your backend server doesn't use the
Davor Ocelice9ed2812017-12-25 17:49:28 +01005741 "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
Ross Westaf72a1d2008-08-03 10:51:45 +02005742 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01005743
5744 Sometimes, a same HAProxy instance may be shared between a direct client
5745 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
5746 used to decrypt HTTPS traffic). It is possible to disable the addition of the
5747 header for a known source address or network by adding the "except" keyword
5748 followed by the network address. In this case, any source IP matching the
5749 network will not cause an addition of this header. Most common uses are with
5750 private networks or 127.0.0.1.
5751
Willy Tarreau87cf5142011-08-19 22:57:24 +02005752 Alternatively, the keyword "if-none" states that the header will only be
5753 added if it is not present. This should only be used in perfectly trusted
5754 environment, as this might cause a security issue if headers reaching haproxy
5755 are under the control of the end-user.
5756
Willy Tarreauc27debf2008-01-06 08:57:02 +01005757 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02005758 least one of them uses it, the header will be added. Note that the backend's
5759 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02005760 both are defined. In the case of the "if-none" argument, if at least one of
5761 the frontend or the backend does not specify it, it wants the addition to be
5762 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005763
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005764 Example :
Willy Tarreauc27debf2008-01-06 08:57:02 +01005765 # Public HTTP address also used by stunnel on the same machine
5766 frontend www
5767 mode http
5768 option forwardfor except 127.0.0.1 # stunnel already adds the header
5769
Ross Westaf72a1d2008-08-03 10:51:45 +02005770 # Those servers want the IP Address in X-Client
5771 backend www
5772 mode http
5773 option forwardfor header X-Client
5774
Willy Tarreau87cf5142011-08-19 22:57:24 +02005775 See also : "option httpclose", "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02005776 "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01005777
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005778
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005779option http-buffer-request
5780no option http-buffer-request
5781 Enable or disable waiting for whole HTTP request body before proceeding
5782 May be used in sections : defaults | frontend | listen | backend
5783 yes | yes | yes | yes
5784 Arguments : none
5785
5786 It is sometimes desirable to wait for the body of an HTTP request before
5787 taking a decision. This is what is being done by "balance url_param" for
5788 example. The first use case is to buffer requests from slow clients before
5789 connecting to the server. Another use case consists in taking the routing
5790 decision based on the request body's contents. This option placed in a
5791 frontend or backend forces the HTTP processing to wait until either the whole
5792 body is received, or the request buffer is full, or the first chunk is
5793 complete in case of chunked encoding. It can have undesired side effects with
Tim Düsterhus4896c442016-11-29 02:15:19 +01005794 some applications abusing HTTP by expecting unbuffered transmissions between
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005795 the frontend and the backend, so this should definitely not be used by
5796 default.
5797
Baptiste Assmanneccdf432015-10-28 13:49:01 +01005798 See also : "option http-no-delay", "timeout http-request"
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005799
5800
Willy Tarreau0f228a02015-05-01 15:37:53 +02005801option http-ignore-probes
5802no option http-ignore-probes
5803 Enable or disable logging of null connections and request timeouts
5804 May be used in sections : defaults | frontend | listen | backend
5805 yes | yes | yes | no
5806 Arguments : none
5807
5808 Recently some browsers started to implement a "pre-connect" feature
5809 consisting in speculatively connecting to some recently visited web sites
5810 just in case the user would like to visit them. This results in many
5811 connections being established to web sites, which end up in 408 Request
5812 Timeout if the timeout strikes first, or 400 Bad Request when the browser
5813 decides to close them first. These ones pollute the log and feed the error
5814 counters. There was already "option dontlognull" but it's insufficient in
5815 this case. Instead, this option does the following things :
5816 - prevent any 400/408 message from being sent to the client if nothing
Davor Ocelice9ed2812017-12-25 17:49:28 +01005817 was received over a connection before it was closed;
5818 - prevent any log from being emitted in this situation;
Willy Tarreau0f228a02015-05-01 15:37:53 +02005819 - prevent any error counter from being incremented
5820
5821 That way the empty connection is silently ignored. Note that it is better
5822 not to use this unless it is clear that it is needed, because it will hide
5823 real problems. The most common reason for not receiving a request and seeing
5824 a 408 is due to an MTU inconsistency between the client and an intermediary
5825 element such as a VPN, which blocks too large packets. These issues are
5826 generally seen with POST requests as well as GET with large cookies. The logs
5827 are often the only way to detect them.
5828
5829 If this option has been enabled in a "defaults" section, it can be disabled
5830 in a specific instance by prepending the "no" keyword before it.
5831
5832 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
5833
5834
Willy Tarreau16bfb022010-01-16 19:48:41 +01005835option http-keep-alive
5836no option http-keep-alive
5837 Enable or disable HTTP keep-alive from client to server
5838 May be used in sections : defaults | frontend | listen | backend
5839 yes | yes | yes | yes
5840 Arguments : none
5841
Willy Tarreau70dffda2014-01-30 03:07:23 +01005842 By default HAProxy operates in keep-alive mode with regards to persistent
5843 connections: for each connection it processes each request and response, and
Christopher Faulet315b39c2018-09-21 16:26:19 +02005844 leaves the connection idle on both sides between the end of a response and
5845 the start of a new request. This mode may be changed by several options such
5846 as "option http-server-close", "option httpclose" or "option http-tunnel".
5847 This option allows to set back the keep-alive mode, which can be useful when
5848 another mode was used in a defaults section.
Willy Tarreau70dffda2014-01-30 03:07:23 +01005849
5850 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
5851 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01005852 network) and the fastest session reuse on the server side at the expense
5853 of maintaining idle connections to the servers. In general, it is possible
5854 with this option to achieve approximately twice the request rate that the
5855 "http-server-close" option achieves on small objects. There are mainly two
5856 situations where this option may be useful :
5857
5858 - when the server is non-HTTP compliant and authenticates the connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01005859 instead of requests (e.g. NTLM authentication)
Willy Tarreau16bfb022010-01-16 19:48:41 +01005860
5861 - when the cost of establishing the connection to the server is significant
5862 compared to the cost of retrieving the associated object from the server.
5863
5864 This last case can happen when the server is a fast static server of cache.
5865 In this case, the server will need to be properly tuned to support high enough
5866 connection counts because connections will last until the client sends another
5867 request.
5868
5869 If the client request has to go to another backend or another server due to
5870 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01005871 immediately be closed and a new one re-opened. Option "prefer-last-server" is
5872 available to try optimize server selection so that if the server currently
5873 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01005874
Willy Tarreau16bfb022010-01-16 19:48:41 +01005875 At the moment, logs will not indicate whether requests came from the same
5876 session or not. The accept date reported in the logs corresponds to the end
5877 of the previous request, and the request time corresponds to the time spent
5878 waiting for a new request. The keep-alive request time is still bound to the
5879 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
5880 not set.
5881
Cyril Bonté653dcd62014-02-20 00:13:15 +01005882 This option disables and replaces any previous "option httpclose", "option
Christopher Faulet315b39c2018-09-21 16:26:19 +02005883 http-server-close" or "option http-tunnel". When backend and frontend options
5884 differ, all of these 4 options have precedence over "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01005885
Christopher Faulet315b39c2018-09-21 16:26:19 +02005886 See also : "option httpclose",, "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01005887 "option prefer-last-server", "option http-pretend-keepalive",
Christopher Faulet315b39c2018-09-21 16:26:19 +02005888 and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01005889
5890
Willy Tarreau96e31212011-05-30 18:10:30 +02005891option http-no-delay
5892no option http-no-delay
5893 Instruct the system to favor low interactive delays over performance in HTTP
5894 May be used in sections : defaults | frontend | listen | backend
5895 yes | yes | yes | yes
5896 Arguments : none
5897
5898 In HTTP, each payload is unidirectional and has no notion of interactivity.
5899 Any agent is expected to queue data somewhat for a reasonably low delay.
5900 There are some very rare server-to-server applications that abuse the HTTP
5901 protocol and expect the payload phase to be highly interactive, with many
5902 interleaved data chunks in both directions within a single request. This is
5903 absolutely not supported by the HTTP specification and will not work across
5904 most proxies or servers. When such applications attempt to do this through
5905 haproxy, it works but they will experience high delays due to the network
5906 optimizations which favor performance by instructing the system to wait for
5907 enough data to be available in order to only send full packets. Typical
5908 delays are around 200 ms per round trip. Note that this only happens with
5909 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
5910 affected.
5911
5912 When "option http-no-delay" is present in either the frontend or the backend
5913 used by a connection, all such optimizations will be disabled in order to
5914 make the exchanges as fast as possible. Of course this offers no guarantee on
5915 the functionality, as it may break at any other place. But if it works via
5916 HAProxy, it will work as fast as possible. This option should never be used
5917 by default, and should never be used at all unless such a buggy application
5918 is discovered. The impact of using this option is an increase of bandwidth
5919 usage and CPU usage, which may significantly lower performance in high
5920 latency environments.
5921
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005922 See also : "option http-buffer-request"
5923
Willy Tarreau96e31212011-05-30 18:10:30 +02005924
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005925option http-pretend-keepalive
5926no option http-pretend-keepalive
5927 Define whether haproxy will announce keepalive to the server or not
5928 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet98db9762018-09-21 10:25:19 +02005929 yes | no | yes | yes
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005930 Arguments : none
5931
Christopher Faulet315b39c2018-09-21 16:26:19 +02005932 When running with "option http-server-close" or "option httpclose", haproxy
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005933 adds a "Connection: close" header to the request forwarded to the server.
5934 Unfortunately, when some servers see this header, they automatically refrain
5935 from using the chunked encoding for responses of unknown length, while this
5936 is totally unrelated. The immediate effect is that this prevents haproxy from
5937 maintaining the client connection alive. A second effect is that a client or
5938 a cache could receive an incomplete response without being aware of it, and
5939 consider the response complete.
5940
5941 By setting "option http-pretend-keepalive", haproxy will make the server
5942 believe it will keep the connection alive. The server will then not fall back
5943 to the abnormal undesired above. When haproxy gets the whole response, it
5944 will close the connection with the server just as it would do with the
Christopher Faulet315b39c2018-09-21 16:26:19 +02005945 "option httpclose". That way the client gets a normal response and the
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005946 connection is correctly closed on the server side.
5947
5948 It is recommended not to enable this option by default, because most servers
5949 will more efficiently close the connection themselves after the last packet,
5950 and release its buffers slightly earlier. Also, the added packet on the
5951 network could slightly reduce the overall peak performance. However it is
5952 worth noting that when this option is enabled, haproxy will have slightly
5953 less work to do. So if haproxy is the bottleneck on the whole architecture,
5954 enabling this option might save a few CPU cycles.
5955
Christopher Faulet98db9762018-09-21 10:25:19 +02005956 This option may be set in backend and listen sections. Using it in a frontend
5957 section will be ignored and a warning will be reported during startup. It is
5958 a backend related option, so there is no real reason to set it on a
5959 frontend. This option may be combined with "option httpclose", which will
5960 cause keepalive to be announced to the server and close to be announced to
5961 the client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005962
5963 If this option has been enabled in a "defaults" section, it can be disabled
5964 in a specific instance by prepending the "no" keyword before it.
5965
Christopher Faulet315b39c2018-09-21 16:26:19 +02005966 See also : "option httpclose", "option http-server-close", and
Willy Tarreau16bfb022010-01-16 19:48:41 +01005967 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005968
Willy Tarreauc27debf2008-01-06 08:57:02 +01005969
Willy Tarreaub608feb2010-01-02 22:47:18 +01005970option http-server-close
5971no option http-server-close
5972 Enable or disable HTTP connection closing on the server side
5973 May be used in sections : defaults | frontend | listen | backend
5974 yes | yes | yes | yes
5975 Arguments : none
5976
Willy Tarreau70dffda2014-01-30 03:07:23 +01005977 By default HAProxy operates in keep-alive mode with regards to persistent
5978 connections: for each connection it processes each request and response, and
5979 leaves the connection idle on both sides between the end of a response and
5980 the start of a new request. This mode may be changed by several options such
Christopher Faulet315b39c2018-09-21 16:26:19 +02005981 as "option http-server-close", "option httpclose" or "option http-tunnel".
5982 Setting "option http-server-close" enables HTTP connection-close mode on the
5983 server side while keeping the ability to support HTTP keep-alive and
5984 pipelining on the client side. This provides the lowest latency on the client
5985 side (slow network) and the fastest session reuse on the server side to save
5986 server resources, similarly to "option httpclose". It also permits
5987 non-keepalive capable servers to be served in keep-alive mode to the clients
5988 if they conform to the requirements of RFC7230. Please note that some servers
5989 do not always conform to those requirements when they see "Connection: close"
5990 in the request. The effect will be that keep-alive will never be used. A
5991 workaround consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01005992
5993 At the moment, logs will not indicate whether requests came from the same
5994 session or not. The accept date reported in the logs corresponds to the end
5995 of the previous request, and the request time corresponds to the time spent
5996 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01005997 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
5998 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01005999
6000 This option may be set both in a frontend and in a backend. It is enabled if
6001 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet315b39c2018-09-21 16:26:19 +02006002 It disables and replaces any previous "option httpclose", "option http-tunnel"
6003 or "option http-keep-alive". Please check section 4 ("Proxies") to see how
6004 this option combines with others when frontend and backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01006005
6006 If this option has been enabled in a "defaults" section, it can be disabled
6007 in a specific instance by prepending the "no" keyword before it.
6008
Christopher Faulet315b39c2018-09-21 16:26:19 +02006009 See also : "option httpclose", "option http-pretend-keepalive",
6010 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01006011
6012
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006013option http-tunnel
6014no option http-tunnel
6015 Disable or enable HTTP connection processing after first transaction
6016 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet4212a302018-09-21 10:42:19 +02006017 yes | yes | yes | no
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006018 Arguments : none
6019
Willy Tarreau70dffda2014-01-30 03:07:23 +01006020 By default HAProxy operates in keep-alive mode with regards to persistent
6021 connections: for each connection it processes each request and response, and
6022 leaves the connection idle on both sides between the end of a response and
6023 the start of a new request. This mode may be changed by several options such
Christopher Faulet315b39c2018-09-21 16:26:19 +02006024 as "option http-server-close", "option httpclose" or "option http-tunnel".
Willy Tarreau70dffda2014-01-30 03:07:23 +01006025
6026 Option "http-tunnel" disables any HTTP processing past the first request and
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006027 the first response. This is the mode which was used by default in versions
Willy Tarreau70dffda2014-01-30 03:07:23 +01006028 1.0 to 1.5-dev21. It is the mode with the lowest processing overhead, which
6029 is normally not needed anymore unless in very specific cases such as when
6030 using an in-house protocol that looks like HTTP but is not compatible, or
6031 just to log one request per client in order to reduce log size. Note that
6032 everything which works at the HTTP level, including header parsing/addition,
6033 cookie processing or content switching will only work for the first request
6034 and will be ignored after the first response.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006035
Christopher Faulet4212a302018-09-21 10:42:19 +02006036 This option may be set on frontend and listen sections. Using it on a backend
6037 section will be ignored and a warning will be reported during the startup. It
6038 is a frontend related option, so there is no real reason to set it on a
6039 backend.
6040
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006041 If this option has been enabled in a "defaults" section, it can be disabled
6042 in a specific instance by prepending the "no" keyword before it.
6043
Christopher Faulet315b39c2018-09-21 16:26:19 +02006044 See also : "option httpclose", "option http-server-close",
6045 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006046
6047
Willy Tarreau88d349d2010-01-25 12:15:43 +01006048option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01006049no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01006050 Make use of non-standard Proxy-Connection header instead of Connection
6051 May be used in sections : defaults | frontend | listen | backend
6052 yes | yes | yes | no
6053 Arguments : none
6054
Lukas Tribus23953682017-04-28 13:24:30 +00006055 While RFC7230 explicitly states that HTTP/1.1 agents must use the
Willy Tarreau88d349d2010-01-25 12:15:43 +01006056 Connection header to indicate their wish of persistent or non-persistent
6057 connections, both browsers and proxies ignore this header for proxied
6058 connections and make use of the undocumented, non-standard Proxy-Connection
6059 header instead. The issue begins when trying to put a load balancer between
6060 browsers and such proxies, because there will be a difference between what
6061 haproxy understands and what the client and the proxy agree on.
6062
6063 By setting this option in a frontend, haproxy can automatically switch to use
6064 that non-standard header if it sees proxied requests. A proxied request is
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006065 defined here as one where the URI begins with neither a '/' nor a '*'. This
6066 is incompatible with the HTTP tunnel mode. Note that this option can only be
6067 specified in a frontend and will affect the request along its whole life.
Willy Tarreau88d349d2010-01-25 12:15:43 +01006068
Willy Tarreau844a7e72010-01-31 21:46:18 +01006069 Also, when this option is set, a request which requires authentication will
6070 automatically switch to use proxy authentication headers if it is itself a
6071 proxied request. That makes it possible to check or enforce authentication in
6072 front of an existing proxy.
6073
Willy Tarreau88d349d2010-01-25 12:15:43 +01006074 This option should normally never be used, except in front of a proxy.
6075
Christopher Faulet315b39c2018-09-21 16:26:19 +02006076 See also : "option httpclose", and "option http-server-close".
Willy Tarreau88d349d2010-01-25 12:15:43 +01006077
6078
Willy Tarreau68ad3a42018-10-22 11:49:15 +02006079option http-use-htx
6080no option http-use-htx
6081 Switch to the new HTX internal representation for HTTP protocol elements
6082 May be used in sections : defaults | frontend | listen | backend
6083 yes | yes | yes | yes
6084 Arguments : none
6085
6086 By default, the HTTP protocol is processed as-is. Inserting, deleting, or
6087 modifying a header field requires to rewrite the affected part in the buffer
6088 and to move the buffer's tail accordingly. Since this principle has deep
6089 roots in haproxy, the HTTP/2 protocol is converted to HTTP/1.1 before being
6090 processed this way. It also results in the inability to establish HTTP/2
6091 connections to servers because of the loss of HTTP/2 semantics in the HTTP/1
6092 representation.
6093
6094 HTX is the name of a totally new native internal representation for the HTTP
6095 protocol, that is agnostic to the version and aims at preserving semantics
6096 all along the chain. It relies on a fast parsing, tokenizing and indexing of
6097 the protocol elements so that no more memory moves are necessary and that
6098 most elements are directly accessed. This mechanism is still limited to the
6099 most basic operations (no compression, filters, Lua, applets, cache, etc).
6100 But it supports using either HTTP/1 or HTTP/2 on any side regardless of the
6101 other side's version.
6102
6103 This option indicates that HTX needs to be used. It will cause errors to be
6104 emitted if incompatible features are used, but will allow H2 to be selected
6105 as a server protocol. It is recommended to use this option on new reasonably
6106 simple configurations, but since the feature still has incomplete functional
6107 coverage, it is not enabled by default.
6108
6109 See also : "mode http"
6110
6111
Willy Tarreaud63335a2010-02-26 12:56:52 +01006112option httpchk
6113option httpchk <uri>
6114option httpchk <method> <uri>
6115option httpchk <method> <uri> <version>
6116 Enable HTTP protocol to check on the servers health
6117 May be used in sections : defaults | frontend | listen | backend
6118 yes | no | yes | yes
6119 Arguments :
6120 <method> is the optional HTTP method used with the requests. When not set,
6121 the "OPTIONS" method is used, as it generally requires low server
6122 processing and is easy to filter out from the logs. Any method
6123 may be used, though it is not recommended to invent non-standard
6124 ones.
6125
6126 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
6127 which is accessible by default on almost any server, but may be
6128 changed to any other URI. Query strings are permitted.
6129
6130 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
6131 but some servers might behave incorrectly in HTTP 1.0, so turning
6132 it to HTTP/1.1 may sometimes help. Note that the Host field is
6133 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
6134 after "\r\n" following the version string.
6135
6136 By default, server health checks only consist in trying to establish a TCP
6137 connection. When "option httpchk" is specified, a complete HTTP request is
6138 sent once the TCP connection is established, and responses 2xx and 3xx are
6139 considered valid, while all other ones indicate a server failure, including
6140 the lack of any response.
6141
6142 The port and interval are specified in the server configuration.
6143
6144 This option does not necessarily require an HTTP backend, it also works with
6145 plain TCP backends. This is particularly useful to check simple scripts bound
6146 to some dedicated ports using the inetd daemon.
6147
6148 Examples :
6149 # Relay HTTPS traffic to Apache instance and check service availability
6150 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
6151 backend https_relay
6152 mode tcp
6153 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
6154 server apache1 192.168.1.1:443 check port 80
6155
Simon Hormanafc47ee2013-11-25 10:46:35 +09006156 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
6157 "option pgsql-check", "http-check" and the "check", "port" and
6158 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006159
6160
Willy Tarreauc27debf2008-01-06 08:57:02 +01006161option httpclose
6162no option httpclose
Christopher Faulet315b39c2018-09-21 16:26:19 +02006163 Enable or disable HTTP connection closing
Willy Tarreauc27debf2008-01-06 08:57:02 +01006164 May be used in sections : defaults | frontend | listen | backend
6165 yes | yes | yes | yes
6166 Arguments : none
6167
Willy Tarreau70dffda2014-01-30 03:07:23 +01006168 By default HAProxy operates in keep-alive mode with regards to persistent
6169 connections: for each connection it processes each request and response, and
6170 leaves the connection idle on both sides between the end of a response and
6171 the start of a new request. This mode may be changed by several options such
Christopher Faulet315b39c2018-09-21 16:26:19 +02006172 as "option http-server-close", "option httpclose" or "option http-tunnel".
Willy Tarreau70dffda2014-01-30 03:07:23 +01006173
Christopher Faulet315b39c2018-09-21 16:26:19 +02006174 If "option httpclose" is set, HAProxy will close connections with the server
6175 and the client as soon as the request and the response are received. It will
6176 alos check if a "Connection: close" header is already set in each direction,
6177 and will add one if missing. Any "Connection" header different from "close"
6178 will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006179
Christopher Faulet315b39c2018-09-21 16:26:19 +02006180 This option may also be combined with "option http-pretend-keepalive", which
6181 will disable sending of the "Connection: close" header, but will still cause
6182 the connection to be closed once the whole response is received.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006183
6184 This option may be set both in a frontend and in a backend. It is enabled if
6185 at least one of the frontend or backend holding a connection has it enabled.
Cyril Bonté653dcd62014-02-20 00:13:15 +01006186 It disables and replaces any previous "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02006187 "option http-keep-alive" or "option http-tunnel". Please check section 4
6188 ("Proxies") to see how this option combines with others when frontend and
6189 backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006190
6191 If this option has been enabled in a "defaults" section, it can be disabled
6192 in a specific instance by prepending the "no" keyword before it.
6193
Christopher Faulet315b39c2018-09-21 16:26:19 +02006194 See also : "option http-server-close" and "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01006195
6196
Emeric Brun3a058f32009-06-30 18:26:00 +02006197option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01006198 Enable logging of HTTP request, session state and timers
6199 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01006200 yes | yes | yes | no
Emeric Brun3a058f32009-06-30 18:26:00 +02006201 Arguments :
6202 clf if the "clf" argument is added, then the output format will be
6203 the CLF format instead of HAProxy's default HTTP format. You can
6204 use this when you need to feed HAProxy's logs through a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01006205 log analyzer which only support the CLF format and which is not
Emeric Brun3a058f32009-06-30 18:26:00 +02006206 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006207
6208 By default, the log output format is very poor, as it only contains the
6209 source and destination addresses, and the instance name. By specifying
6210 "option httplog", each log line turns into a much richer format including,
6211 but not limited to, the HTTP request, the connection timers, the session
6212 status, the connections numbers, the captured headers and cookies, the
6213 frontend, backend and server name, and of course the source address and
6214 ports.
6215
PiBa-NLbd556bf2014-12-11 21:31:54 +01006216 Specifying only "option httplog" will automatically clear the 'clf' mode
6217 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02006218
Guillaume de Lafond29f45602017-03-31 19:52:15 +02006219 "option httplog" overrides any previous "log-format" directive.
6220
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006221 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006222
Willy Tarreau55165fe2009-05-10 12:02:55 +02006223
6224option http_proxy
6225no option http_proxy
6226 Enable or disable plain HTTP proxy mode
6227 May be used in sections : defaults | frontend | listen | backend
6228 yes | yes | yes | yes
6229 Arguments : none
6230
6231 It sometimes happens that people need a pure HTTP proxy which understands
6232 basic proxy requests without caching nor any fancy feature. In this case,
6233 it may be worth setting up an HAProxy instance with the "option http_proxy"
6234 set. In this mode, no server is declared, and the connection is forwarded to
6235 the IP address and port found in the URL after the "http://" scheme.
6236
6237 No host address resolution is performed, so this only works when pure IP
6238 addresses are passed. Since this option's usage perimeter is rather limited,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006239 it will probably be used only by experts who know they need exactly it. This
6240 is incompatible with the HTTP tunnel mode.
Willy Tarreau55165fe2009-05-10 12:02:55 +02006241
6242 If this option has been enabled in a "defaults" section, it can be disabled
6243 in a specific instance by prepending the "no" keyword before it.
6244
6245 Example :
6246 # this backend understands HTTP proxy requests and forwards them directly.
6247 backend direct_forward
6248 option httpclose
6249 option http_proxy
6250
6251 See also : "option httpclose"
6252
Willy Tarreau211ad242009-10-03 21:45:07 +02006253
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006254option independent-streams
6255no option independent-streams
6256 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006257 May be used in sections : defaults | frontend | listen | backend
6258 yes | yes | yes | yes
6259 Arguments : none
6260
6261 By default, when data is sent over a socket, both the write timeout and the
6262 read timeout for that socket are refreshed, because we consider that there is
6263 activity on that socket, and we have no other means of guessing if we should
6264 receive data or not.
6265
Davor Ocelice9ed2812017-12-25 17:49:28 +01006266 While this default behavior is desirable for almost all applications, there
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006267 exists a situation where it is desirable to disable it, and only refresh the
6268 read timeout if there are incoming data. This happens on sessions with large
6269 timeouts and low amounts of exchanged data such as telnet session. If the
6270 server suddenly disappears, the output data accumulates in the system's
6271 socket buffers, both timeouts are correctly refreshed, and there is no way
6272 to know the server does not receive them, so we don't timeout. However, when
6273 the underlying protocol always echoes sent data, it would be enough by itself
6274 to detect the issue using the read timeout. Note that this problem does not
6275 happen with more verbose protocols because data won't accumulate long in the
6276 socket buffers.
6277
6278 When this option is set on the frontend, it will disable read timeout updates
6279 on data sent to the client. There probably is little use of this case. When
6280 the option is set on the backend, it will disable read timeout updates on
6281 data sent to the server. Doing so will typically break large HTTP posts from
6282 slow lines, so use it with caution.
6283
Lukas Tribus745f15e2018-11-08 12:41:42 +01006284 Note: older versions used to call this setting "option independant-streams"
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006285 with a spelling mistake. This spelling is still supported but
6286 deprecated.
6287
Willy Tarreauce887fd2012-05-12 12:50:00 +02006288 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006289
6290
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02006291option ldap-check
6292 Use LDAPv3 health checks for server testing
6293 May be used in sections : defaults | frontend | listen | backend
6294 yes | no | yes | yes
6295 Arguments : none
6296
6297 It is possible to test that the server correctly talks LDAPv3 instead of just
6298 testing that it accepts the TCP connection. When this option is set, an
6299 LDAPv3 anonymous simple bind message is sent to the server, and the response
6300 is analyzed to find an LDAPv3 bind response message.
6301
6302 The server is considered valid only when the LDAP response contains success
6303 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
6304
6305 Logging of bind requests is server dependent see your documentation how to
6306 configure it.
6307
6308 Example :
6309 option ldap-check
6310
6311 See also : "option httpchk"
6312
6313
Simon Horman98637e52014-06-20 12:30:16 +09006314option external-check
6315 Use external processes for server health checks
6316 May be used in sections : defaults | frontend | listen | backend
6317 yes | no | yes | yes
6318
6319 It is possible to test the health of a server using an external command.
6320 This is achieved by running the executable set using "external-check
6321 command".
6322
6323 Requires the "external-check" global to be set.
6324
6325 See also : "external-check", "external-check command", "external-check path"
6326
6327
Willy Tarreau211ad242009-10-03 21:45:07 +02006328option log-health-checks
6329no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02006330 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02006331 May be used in sections : defaults | frontend | listen | backend
6332 yes | no | yes | yes
6333 Arguments : none
6334
Willy Tarreaubef1b322014-05-13 21:01:39 +02006335 By default, failed health check are logged if server is UP and successful
6336 health checks are logged if server is DOWN, so the amount of additional
6337 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02006338
Willy Tarreaubef1b322014-05-13 21:01:39 +02006339 When this option is enabled, any change of the health check status or to
6340 the server's health will be logged, so that it becomes possible to know
6341 that a server was failing occasional checks before crashing, or exactly when
6342 it failed to respond a valid HTTP status, then when the port started to
6343 reject connections, then when the server stopped responding at all.
6344
Davor Ocelice9ed2812017-12-25 17:49:28 +01006345 Note that status changes not caused by health checks (e.g. enable/disable on
Willy Tarreaubef1b322014-05-13 21:01:39 +02006346 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02006347
Willy Tarreaubef1b322014-05-13 21:01:39 +02006348 See also: "option httpchk", "option ldap-check", "option mysql-check",
6349 "option pgsql-check", "option redis-check", "option smtpchk",
6350 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02006351
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006352
6353option log-separate-errors
6354no option log-separate-errors
6355 Change log level for non-completely successful connections
6356 May be used in sections : defaults | frontend | listen | backend
6357 yes | yes | yes | no
6358 Arguments : none
6359
6360 Sometimes looking for errors in logs is not easy. This option makes haproxy
6361 raise the level of logs containing potentially interesting information such
6362 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
6363 level changes from "info" to "err". This makes it possible to log them
6364 separately to a different file with most syslog daemons. Be careful not to
6365 remove them from the original file, otherwise you would lose ordering which
6366 provides very important information.
6367
6368 Using this option, large sites dealing with several thousand connections per
6369 second may log normal traffic to a rotating buffer and only archive smaller
6370 error logs.
6371
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006372 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006373 logging.
6374
Willy Tarreauc27debf2008-01-06 08:57:02 +01006375
6376option logasap
6377no option logasap
6378 Enable or disable early logging of HTTP requests
6379 May be used in sections : defaults | frontend | listen | backend
6380 yes | yes | yes | no
6381 Arguments : none
6382
6383 By default, HTTP requests are logged upon termination so that the total
6384 transfer time and the number of bytes appear in the logs. When large objects
6385 are being transferred, it may take a while before the request appears in the
6386 logs. Using "option logasap", the request gets logged as soon as the server
6387 sends the complete headers. The only missing information in the logs will be
6388 the total number of bytes which will indicate everything except the amount
6389 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006390 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01006391 "Content-Length" response header so that the logs at least indicate how many
6392 bytes are expected to be transferred.
6393
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006394 Examples :
6395 listen http_proxy 0.0.0.0:80
6396 mode http
6397 option httplog
6398 option logasap
6399 log 192.168.2.200 local3
6400
6401 >>> Feb 6 12:14:14 localhost \
6402 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
6403 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
6404 "GET /image.iso HTTP/1.0"
6405
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006406 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01006407 logging.
6408
6409
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02006410option mysql-check [ user <username> [ post-41 ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006411 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006412 May be used in sections : defaults | frontend | listen | backend
6413 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006414 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006415 <username> This is the username which will be used when connecting to MySQL
6416 server.
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02006417 post-41 Send post v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006418
6419 If you specify a username, the check consists of sending two MySQL packet,
6420 one Client Authentication packet, and one QUIT packet, to correctly close
Davor Ocelice9ed2812017-12-25 17:49:28 +01006421 MySQL session. We then parse the MySQL Handshake Initialization packet and/or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006422 Error packet. It is a basic but useful test which does not produce error nor
6423 aborted connect on the server. However, it requires adding an authorization
6424 in the MySQL table, like this :
6425
6426 USE mysql;
6427 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
6428 FLUSH PRIVILEGES;
6429
6430 If you don't specify a username (it is deprecated and not recommended), the
Davor Ocelice9ed2812017-12-25 17:49:28 +01006431 check only consists in parsing the Mysql Handshake Initialization packet or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006432 Error packet, we don't send anything in this mode. It was reported that it
6433 can generate lockout if check is too frequent and/or if there is not enough
6434 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
6435 value as if a connection is established successfully within fewer than MySQL
6436 "max_connect_errors" attempts after a previous connection was interrupted,
6437 the error count for the host is cleared to zero. If HAProxy's server get
6438 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
6439
6440 Remember that this does not check database presence nor database consistency.
6441 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006442
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02006443 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006444
6445 Most often, an incoming MySQL server needs to see the client's IP address for
6446 various purposes, including IP privilege matching and connection logging.
6447 When possible, it is often wise to masquerade the client's IP address when
6448 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02006449 which requires the transparent proxy feature to be compiled in, and the MySQL
6450 server to route the client via the machine hosting haproxy.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006451
6452 See also: "option httpchk"
6453
6454
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006455option nolinger
6456no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006457 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006458 May be used in sections: defaults | frontend | listen | backend
6459 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006460 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006461
Davor Ocelice9ed2812017-12-25 17:49:28 +01006462 When clients or servers abort connections in a dirty way (e.g. they are
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006463 physically disconnected), the session timeouts triggers and the session is
6464 closed. But it will remain in FIN_WAIT1 state for some time in the system,
6465 using some resources and possibly limiting the ability to establish newer
6466 connections.
6467
6468 When this happens, it is possible to activate "option nolinger" which forces
6469 the system to immediately remove any socket's pending data on close. Thus,
6470 the session is instantly purged from the system's tables. This usually has
6471 side effects such as increased number of TCP resets due to old retransmits
6472 getting immediately rejected. Some firewalls may sometimes complain about
6473 this too.
6474
6475 For this reason, it is not recommended to use this option when not absolutely
6476 needed. You know that you need it when you have thousands of FIN_WAIT1
6477 sessions on your system (TIME_WAIT ones do not count).
6478
6479 This option may be used both on frontends and backends, depending on the side
6480 where it is required. Use it on the frontend for clients, and on the backend
6481 for servers.
6482
6483 If this option has been enabled in a "defaults" section, it can be disabled
6484 in a specific instance by prepending the "no" keyword before it.
6485
6486
Willy Tarreau55165fe2009-05-10 12:02:55 +02006487option originalto [ except <network> ] [ header <name> ]
6488 Enable insertion of the X-Original-To header to requests sent to servers
6489 May be used in sections : defaults | frontend | listen | backend
6490 yes | yes | yes | yes
6491 Arguments :
6492 <network> is an optional argument used to disable this option for sources
6493 matching <network>
6494 <name> an optional argument to specify a different "X-Original-To"
6495 header name.
6496
6497 Since HAProxy can work in transparent mode, every request from a client can
6498 be redirected to the proxy and HAProxy itself can proxy every request to a
6499 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
6500 be lost. This is annoying when you want access rules based on destination ip
6501 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
6502 added by HAProxy to all requests sent to the server. This header contains a
6503 value representing the original destination IP address. Since this must be
6504 configured to always use the last occurrence of this header only. Note that
6505 only the last occurrence of the header must be used, since it is really
6506 possible that the client has already brought one.
6507
6508 The keyword "header" may be used to supply a different header name to replace
6509 the default "X-Original-To". This can be useful where you might already
6510 have a "X-Original-To" header from a different application, and you need
6511 preserve it. Also if your backend server doesn't use the "X-Original-To"
6512 header and requires different one.
6513
6514 Sometimes, a same HAProxy instance may be shared between a direct client
6515 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
6516 used to decrypt HTTPS traffic). It is possible to disable the addition of the
6517 header for a known source address or network by adding the "except" keyword
6518 followed by the network address. In this case, any source IP matching the
6519 network will not cause an addition of this header. Most common uses are with
6520 private networks or 127.0.0.1.
6521
6522 This option may be specified either in the frontend or in the backend. If at
6523 least one of them uses it, the header will be added. Note that the backend's
6524 setting of the header subargument takes precedence over the frontend's if
6525 both are defined.
6526
Willy Tarreau55165fe2009-05-10 12:02:55 +02006527 Examples :
6528 # Original Destination address
6529 frontend www
6530 mode http
6531 option originalto except 127.0.0.1
6532
6533 # Those servers want the IP Address in X-Client-Dst
6534 backend www
6535 mode http
6536 option originalto header X-Client-Dst
6537
Christopher Faulet315b39c2018-09-21 16:26:19 +02006538 See also : "option httpclose", "option http-server-close".
Willy Tarreau55165fe2009-05-10 12:02:55 +02006539
6540
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006541option persist
6542no option persist
6543 Enable or disable forced persistence on down servers
6544 May be used in sections: defaults | frontend | listen | backend
6545 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006546 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006547
6548 When an HTTP request reaches a backend with a cookie which references a dead
6549 server, by default it is redispatched to another server. It is possible to
6550 force the request to be sent to the dead server first using "option persist"
6551 if absolutely needed. A common use case is when servers are under extreme
6552 load and spend their time flapping. In this case, the users would still be
6553 directed to the server they opened the session on, in the hope they would be
6554 correctly served. It is recommended to use "option redispatch" in conjunction
6555 with this option so that in the event it would not be possible to connect to
6556 the server at all (server definitely dead), the client would finally be
6557 redirected to another valid server.
6558
6559 If this option has been enabled in a "defaults" section, it can be disabled
6560 in a specific instance by prepending the "no" keyword before it.
6561
Willy Tarreau4de91492010-01-22 19:10:05 +01006562 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006563
6564
Willy Tarreau0c122822013-12-15 18:49:01 +01006565option pgsql-check [ user <username> ]
6566 Use PostgreSQL health checks for server testing
6567 May be used in sections : defaults | frontend | listen | backend
6568 yes | no | yes | yes
6569 Arguments :
6570 <username> This is the username which will be used when connecting to
6571 PostgreSQL server.
6572
6573 The check sends a PostgreSQL StartupMessage and waits for either
6574 Authentication request or ErrorResponse message. It is a basic but useful
6575 test which does not produce error nor aborted connect on the server.
6576 This check is identical with the "mysql-check".
6577
6578 See also: "option httpchk"
6579
6580
Willy Tarreau9420b122013-12-15 18:58:25 +01006581option prefer-last-server
6582no option prefer-last-server
6583 Allow multiple load balanced requests to remain on the same server
6584 May be used in sections: defaults | frontend | listen | backend
6585 yes | no | yes | yes
6586 Arguments : none
6587
6588 When the load balancing algorithm in use is not deterministic, and a previous
6589 request was sent to a server to which haproxy still holds a connection, it is
6590 sometimes desirable that subsequent requests on a same session go to the same
6591 server as much as possible. Note that this is different from persistence, as
6592 we only indicate a preference which haproxy tries to apply without any form
6593 of warranty. The real use is for keep-alive connections sent to servers. When
6594 this option is used, haproxy will try to reuse the same connection that is
6595 attached to the server instead of rebalancing to another server, causing a
6596 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01006597 not make much sense to use this in combination with hashing algorithms. Note,
6598 haproxy already automatically tries to stick to a server which sends a 401 or
Lukas Tribus80512b12018-10-27 20:07:40 +02006599 to a proxy which sends a 407 (authentication required), when the load
6600 balancing algorithm is not deterministic. This is mandatory for use with the
6601 broken NTLM authentication challenge, and significantly helps in
Willy Tarreau068621e2013-12-23 15:11:25 +01006602 troubleshooting some faulty applications. Option prefer-last-server might be
6603 desirable in these environments as well, to avoid redistributing the traffic
6604 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01006605
6606 If this option has been enabled in a "defaults" section, it can be disabled
6607 in a specific instance by prepending the "no" keyword before it.
6608
6609 See also: "option http-keep-alive"
6610
6611
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006612option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07006613option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006614no option redispatch
6615 Enable or disable session redistribution in case of connection failure
6616 May be used in sections: defaults | frontend | listen | backend
6617 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07006618 Arguments :
6619 <interval> The optional integer value that controls how often redispatches
6620 occur when retrying connections. Positive value P indicates a
6621 redispatch is desired on every Pth retry, and negative value
Davor Ocelice9ed2812017-12-25 17:49:28 +01006622 N indicate a redispatch is desired on the Nth retry prior to the
Joseph Lynch726ab712015-05-11 23:25:34 -07006623 last retry. For example, the default of -1 preserves the
Davor Ocelice9ed2812017-12-25 17:49:28 +01006624 historical behavior of redispatching on the last retry, a
Joseph Lynch726ab712015-05-11 23:25:34 -07006625 positive value of 1 would indicate a redispatch on every retry,
6626 and a positive value of 3 would indicate a redispatch on every
6627 third retry. You can disable redispatches with a value of 0.
6628
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006629
6630 In HTTP mode, if a server designated by a cookie is down, clients may
6631 definitely stick to it because they cannot flush the cookie, so they will not
6632 be able to access the service anymore.
6633
6634 Specifying "option redispatch" will allow the proxy to break their
6635 persistence and redistribute them to a working server.
6636
Joseph Lynch726ab712015-05-11 23:25:34 -07006637 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006638 connection failures. Of course, it requires having "retries" set to a nonzero
6639 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006640
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006641 This form is the preferred form, which replaces both the "redispatch" and
6642 "redisp" keywords.
6643
6644 If this option has been enabled in a "defaults" section, it can be disabled
6645 in a specific instance by prepending the "no" keyword before it.
6646
Willy Tarreau4de91492010-01-22 19:10:05 +01006647 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006648
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006649
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02006650option redis-check
6651 Use redis health checks for server testing
6652 May be used in sections : defaults | frontend | listen | backend
6653 yes | no | yes | yes
6654 Arguments : none
6655
6656 It is possible to test that the server correctly talks REDIS protocol instead
6657 of just testing that it accepts the TCP connection. When this option is set,
6658 a PING redis command is sent to the server, and the response is analyzed to
6659 find the "+PONG" response message.
6660
6661 Example :
6662 option redis-check
6663
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03006664 See also : "option httpchk", "option tcp-check", "tcp-check expect"
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02006665
6666
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006667option smtpchk
6668option smtpchk <hello> <domain>
6669 Use SMTP health checks for server testing
6670 May be used in sections : defaults | frontend | listen | backend
6671 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01006672 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006673 <hello> is an optional argument. It is the "hello" command to use. It can
Lukas Tribus27935782018-10-01 02:00:16 +02006674 be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006675 values will be turned into the default command ("HELO").
6676
6677 <domain> is the domain name to present to the server. It may only be
6678 specified (and is mandatory) if the hello command has been
6679 specified. By default, "localhost" is used.
6680
6681 When "option smtpchk" is set, the health checks will consist in TCP
6682 connections followed by an SMTP command. By default, this command is
6683 "HELO localhost". The server's return code is analyzed and only return codes
6684 starting with a "2" will be considered as valid. All other responses,
6685 including a lack of response will constitute an error and will indicate a
6686 dead server.
6687
6688 This test is meant to be used with SMTP servers or relays. Depending on the
6689 request, it is possible that some servers do not log each connection attempt,
Davor Ocelice9ed2812017-12-25 17:49:28 +01006690 so you may want to experiment to improve the behavior. Using telnet on port
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006691 25 is often easier than adjusting the configuration.
6692
6693 Most often, an incoming SMTP server needs to see the client's IP address for
6694 various purposes, including spam filtering, anti-spoofing and logging. When
6695 possible, it is often wise to masquerade the client's IP address when
6696 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02006697 which requires the transparent proxy feature to be compiled in.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006698
6699 Example :
6700 option smtpchk HELO mydomain.org
6701
6702 See also : "option httpchk", "source"
6703
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006704
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02006705option socket-stats
6706no option socket-stats
6707
6708 Enable or disable collecting & providing separate statistics for each socket.
6709 May be used in sections : defaults | frontend | listen | backend
6710 yes | yes | yes | no
6711
6712 Arguments : none
6713
6714
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006715option splice-auto
6716no option splice-auto
6717 Enable or disable automatic kernel acceleration on sockets in both directions
6718 May be used in sections : defaults | frontend | listen | backend
6719 yes | yes | yes | yes
6720 Arguments : none
6721
6722 When this option is enabled either on a frontend or on a backend, haproxy
6723 will automatically evaluate the opportunity to use kernel tcp splicing to
Davor Ocelice9ed2812017-12-25 17:49:28 +01006724 forward data between the client and the server, in either direction. HAProxy
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006725 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006726 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006727 are not much aggressive in order to limit excessive use of splicing. This
6728 option requires splicing to be enabled at compile time, and may be globally
6729 disabled with the global option "nosplice". Since splice uses pipes, using it
6730 requires that there are enough spare pipes.
6731
6732 Important note: kernel-based TCP splicing is a Linux-specific feature which
6733 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
6734 transfer data between sockets without copying these data to user-space, thus
6735 providing noticeable performance gains and CPU cycles savings. Since many
6736 early implementations are buggy, corrupt data and/or are inefficient, this
6737 feature is not enabled by default, and it should be used with extreme care.
6738 While it is not possible to detect the correctness of an implementation,
6739 2.6.29 is the first version offering a properly working implementation. In
6740 case of doubt, splicing may be globally disabled using the global "nosplice"
6741 keyword.
6742
6743 Example :
6744 option splice-auto
6745
6746 If this option has been enabled in a "defaults" section, it can be disabled
6747 in a specific instance by prepending the "no" keyword before it.
6748
6749 See also : "option splice-request", "option splice-response", and global
6750 options "nosplice" and "maxpipes"
6751
6752
6753option splice-request
6754no option splice-request
6755 Enable or disable automatic kernel acceleration on sockets for requests
6756 May be used in sections : defaults | frontend | listen | backend
6757 yes | yes | yes | yes
6758 Arguments : none
6759
6760 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006761 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006762 the client to the server. It might still use the recv/send scheme if there
6763 are no spare pipes left. This option requires splicing to be enabled at
6764 compile time, and may be globally disabled with the global option "nosplice".
6765 Since splice uses pipes, using it requires that there are enough spare pipes.
6766
6767 Important note: see "option splice-auto" for usage limitations.
6768
6769 Example :
6770 option splice-request
6771
6772 If this option has been enabled in a "defaults" section, it can be disabled
6773 in a specific instance by prepending the "no" keyword before it.
6774
6775 See also : "option splice-auto", "option splice-response", and global options
6776 "nosplice" and "maxpipes"
6777
6778
6779option splice-response
6780no option splice-response
6781 Enable or disable automatic kernel acceleration on sockets for responses
6782 May be used in sections : defaults | frontend | listen | backend
6783 yes | yes | yes | yes
6784 Arguments : none
6785
6786 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006787 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006788 the server to the client. It might still use the recv/send scheme if there
6789 are no spare pipes left. This option requires splicing to be enabled at
6790 compile time, and may be globally disabled with the global option "nosplice".
6791 Since splice uses pipes, using it requires that there are enough spare pipes.
6792
6793 Important note: see "option splice-auto" for usage limitations.
6794
6795 Example :
6796 option splice-response
6797
6798 If this option has been enabled in a "defaults" section, it can be disabled
6799 in a specific instance by prepending the "no" keyword before it.
6800
6801 See also : "option splice-auto", "option splice-request", and global options
6802 "nosplice" and "maxpipes"
6803
6804
Christopher Fauletba7bc162016-11-07 21:07:38 +01006805option spop-check
6806 Use SPOP health checks for server testing
6807 May be used in sections : defaults | frontend | listen | backend
6808 no | no | no | yes
6809 Arguments : none
6810
6811 It is possible to test that the server correctly talks SPOP protocol instead
6812 of just testing that it accepts the TCP connection. When this option is set,
6813 a HELLO handshake is performed between HAProxy and the server, and the
6814 response is analyzed to check no error is reported.
6815
6816 Example :
6817 option spop-check
6818
6819 See also : "option httpchk"
6820
6821
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006822option srvtcpka
6823no option srvtcpka
6824 Enable or disable the sending of TCP keepalive packets on the server side
6825 May be used in sections : defaults | frontend | listen | backend
6826 yes | no | yes | yes
6827 Arguments : none
6828
6829 When there is a firewall or any session-aware component between a client and
6830 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01006831 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006832 components decides to expire a session which has remained idle for too long.
6833
6834 Enabling socket-level TCP keep-alives makes the system regularly send packets
6835 to the other end of the connection, leaving it active. The delay between
6836 keep-alive probes is controlled by the system only and depends both on the
6837 operating system and its tuning parameters.
6838
6839 It is important to understand that keep-alive packets are neither emitted nor
6840 received at the application level. It is only the network stacks which sees
6841 them. For this reason, even if one side of the proxy already uses keep-alives
6842 to maintain its connection alive, those keep-alive packets will not be
6843 forwarded to the other side of the proxy.
6844
6845 Please note that this has nothing to do with HTTP keep-alive.
6846
6847 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
6848 server side of a connection, which should help when session expirations are
6849 noticed between HAProxy and a server.
6850
6851 If this option has been enabled in a "defaults" section, it can be disabled
6852 in a specific instance by prepending the "no" keyword before it.
6853
6854 See also : "option clitcpka", "option tcpka"
6855
6856
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006857option ssl-hello-chk
6858 Use SSLv3 client hello health checks for server testing
6859 May be used in sections : defaults | frontend | listen | backend
6860 yes | no | yes | yes
6861 Arguments : none
6862
6863 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
6864 possible to test that the server correctly talks SSL instead of just testing
6865 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
6866 SSLv3 client hello messages are sent once the connection is established to
6867 the server, and the response is analyzed to find an SSL server hello message.
6868 The server is considered valid only when the response contains this server
6869 hello message.
6870
6871 All servers tested till there correctly reply to SSLv3 client hello messages,
6872 and most servers tested do not even log the requests containing only hello
6873 messages, which is appreciable.
6874
Willy Tarreau763a95b2012-10-04 23:15:39 +02006875 Note that this check works even when SSL support was not built into haproxy
6876 because it forges the SSL message. When SSL support is available, it is best
6877 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006878
Willy Tarreau763a95b2012-10-04 23:15:39 +02006879 See also: "option httpchk", "check-ssl"
6880
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006881
Willy Tarreaued179852013-12-16 01:07:00 +01006882option tcp-check
6883 Perform health checks using tcp-check send/expect sequences
6884 May be used in sections: defaults | frontend | listen | backend
6885 yes | no | yes | yes
6886
6887 This health check method is intended to be combined with "tcp-check" command
6888 lists in order to support send/expect types of health check sequences.
6889
6890 TCP checks currently support 4 modes of operations :
6891 - no "tcp-check" directive : the health check only consists in a connection
6892 attempt, which remains the default mode.
6893
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006894 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01006895 used to send a string along with a connection opening. With some
6896 protocols, it helps sending a "QUIT" message for example that prevents
6897 the server from logging a connection error for each health check. The
6898 check result will still be based on the ability to open the connection
6899 only.
6900
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006901 - "tcp-check expect" only is mentioned : this is used to test a banner.
Willy Tarreaued179852013-12-16 01:07:00 +01006902 The connection is opened and haproxy waits for the server to present some
6903 contents which must validate some rules. The check result will be based
6904 on the matching between the contents and the rules. This is suited for
6905 POP, IMAP, SMTP, FTP, SSH, TELNET.
6906
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006907 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Davor Ocelice9ed2812017-12-25 17:49:28 +01006908 used to test a hello-type protocol. HAProxy sends a message, the server
6909 responds and its response is analyzed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006910 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01006911 suited for protocols which require a binding or a request/response model.
6912 LDAP, MySQL, Redis and SSL are example of such protocols, though they
6913 already all have their dedicated checks with a deeper understanding of
6914 the respective protocols.
6915 In this mode, many questions may be sent and many answers may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01006916 analyzed.
Willy Tarreaued179852013-12-16 01:07:00 +01006917
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006918 A fifth mode can be used to insert comments in different steps of the
6919 script.
6920
6921 For each tcp-check rule you create, you can add a "comment" directive,
6922 followed by a string. This string will be reported in the log and stderr
6923 in debug mode. It is useful to make user-friendly error reporting.
6924 The "comment" is of course optional.
6925
6926
Willy Tarreaued179852013-12-16 01:07:00 +01006927 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01006928 # perform a POP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01006929 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006930 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01006931
Davor Ocelice9ed2812017-12-25 17:49:28 +01006932 # perform an IMAP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01006933 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006934 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01006935
6936 # look for the redis master server after ensuring it speaks well
6937 # redis protocol, then it exits properly.
Davor Ocelice9ed2812017-12-25 17:49:28 +01006938 # (send a command then analyze the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01006939 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006940 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01006941 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02006942 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006943 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01006944 tcp-check send info\ replication\r\n
6945 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006946 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01006947 tcp-check send QUIT\r\n
6948 tcp-check expect string +OK
6949
Davor Ocelice9ed2812017-12-25 17:49:28 +01006950 forge a HTTP request, then analyze the response
Willy Tarreaued179852013-12-16 01:07:00 +01006951 (send many headers before analyzing)
6952 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006953 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01006954 tcp-check send HEAD\ /\ HTTP/1.1\r\n
6955 tcp-check send Host:\ www.mydomain.com\r\n
6956 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
6957 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006958 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01006959
6960
6961 See also : "tcp-check expect", "tcp-check send"
6962
6963
Willy Tarreau9ea05a72009-06-14 12:07:01 +02006964option tcp-smart-accept
6965no option tcp-smart-accept
6966 Enable or disable the saving of one ACK packet during the accept sequence
6967 May be used in sections : defaults | frontend | listen | backend
6968 yes | yes | yes | no
6969 Arguments : none
6970
6971 When an HTTP connection request comes in, the system acknowledges it on
6972 behalf of HAProxy, then the client immediately sends its request, and the
6973 system acknowledges it too while it is notifying HAProxy about the new
6974 connection. HAProxy then reads the request and responds. This means that we
6975 have one TCP ACK sent by the system for nothing, because the request could
6976 very well be acknowledged by HAProxy when it sends its response.
6977
6978 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
6979 sending this useless ACK on platforms which support it (currently at least
6980 Linux). It must not cause any problem, because the system will send it anyway
6981 after 40 ms if the response takes more time than expected to come.
6982
6983 During complex network debugging sessions, it may be desirable to disable
6984 this optimization because delayed ACKs can make troubleshooting more complex
6985 when trying to identify where packets are delayed. It is then possible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01006986 fall back to normal behavior by specifying "no option tcp-smart-accept".
Willy Tarreau9ea05a72009-06-14 12:07:01 +02006987
6988 It is also possible to force it for non-HTTP proxies by simply specifying
6989 "option tcp-smart-accept". For instance, it can make sense with some services
6990 such as SMTP where the server speaks first.
6991
6992 It is recommended to avoid forcing this option in a defaults section. In case
6993 of doubt, consider setting it back to automatic values by prepending the
6994 "default" keyword before it, or disabling it using the "no" keyword.
6995
Willy Tarreaud88edf22009-06-14 15:48:17 +02006996 See also : "option tcp-smart-connect"
6997
6998
6999option tcp-smart-connect
7000no option tcp-smart-connect
7001 Enable or disable the saving of one ACK packet during the connect sequence
7002 May be used in sections : defaults | frontend | listen | backend
7003 yes | no | yes | yes
7004 Arguments : none
7005
7006 On certain systems (at least Linux), HAProxy can ask the kernel not to
7007 immediately send an empty ACK upon a connection request, but to directly
7008 send the buffer request instead. This saves one packet on the network and
7009 thus boosts performance. It can also be useful for some servers, because they
7010 immediately get the request along with the incoming connection.
7011
7012 This feature is enabled when "option tcp-smart-connect" is set in a backend.
7013 It is not enabled by default because it makes network troubleshooting more
7014 complex.
7015
7016 It only makes sense to enable it with protocols where the client speaks first
7017 such as HTTP. In other situations, if there is no data to send in place of
7018 the ACK, a normal ACK is sent.
7019
7020 If this option has been enabled in a "defaults" section, it can be disabled
7021 in a specific instance by prepending the "no" keyword before it.
7022
7023 See also : "option tcp-smart-accept"
7024
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007025
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007026option tcpka
7027 Enable or disable the sending of TCP keepalive packets on both sides
7028 May be used in sections : defaults | frontend | listen | backend
7029 yes | yes | yes | yes
7030 Arguments : none
7031
7032 When there is a firewall or any session-aware component between a client and
7033 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01007034 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007035 components decides to expire a session which has remained idle for too long.
7036
7037 Enabling socket-level TCP keep-alives makes the system regularly send packets
7038 to the other end of the connection, leaving it active. The delay between
7039 keep-alive probes is controlled by the system only and depends both on the
7040 operating system and its tuning parameters.
7041
7042 It is important to understand that keep-alive packets are neither emitted nor
7043 received at the application level. It is only the network stacks which sees
7044 them. For this reason, even if one side of the proxy already uses keep-alives
7045 to maintain its connection alive, those keep-alive packets will not be
7046 forwarded to the other side of the proxy.
7047
7048 Please note that this has nothing to do with HTTP keep-alive.
7049
7050 Using option "tcpka" enables the emission of TCP keep-alive probes on both
7051 the client and server sides of a connection. Note that this is meaningful
7052 only in "defaults" or "listen" sections. If this option is used in a
7053 frontend, only the client side will get keep-alives, and if this option is
7054 used in a backend, only the server side will get keep-alives. For this
7055 reason, it is strongly recommended to explicitly use "option clitcpka" and
7056 "option srvtcpka" when the configuration is split between frontends and
7057 backends.
7058
7059 See also : "option clitcpka", "option srvtcpka"
7060
Willy Tarreau844e3c52008-01-11 16:28:18 +01007061
7062option tcplog
7063 Enable advanced logging of TCP connections with session state and timers
7064 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01007065 yes | yes | yes | no
Willy Tarreau844e3c52008-01-11 16:28:18 +01007066 Arguments : none
7067
7068 By default, the log output format is very poor, as it only contains the
7069 source and destination addresses, and the instance name. By specifying
7070 "option tcplog", each log line turns into a much richer format including, but
7071 not limited to, the connection timers, the session status, the connections
7072 numbers, the frontend, backend and server name, and of course the source
7073 address and ports. This option is useful for pure TCP proxies in order to
7074 find which of the client or server disconnects or times out. For normal HTTP
7075 proxies, it's better to use "option httplog" which is even more complete.
7076
Guillaume de Lafond29f45602017-03-31 19:52:15 +02007077 "option tcplog" overrides any previous "log-format" directive.
7078
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007079 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007080
7081
Willy Tarreau844e3c52008-01-11 16:28:18 +01007082option transparent
7083no option transparent
7084 Enable client-side transparent proxying
7085 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01007086 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01007087 Arguments : none
7088
7089 This option was introduced in order to provide layer 7 persistence to layer 3
7090 load balancers. The idea is to use the OS's ability to redirect an incoming
7091 connection for a remote address to a local process (here HAProxy), and let
7092 this process know what address was initially requested. When this option is
7093 used, sessions without cookies will be forwarded to the original destination
7094 IP address of the incoming request (which should match that of another
7095 equipment), while requests with cookies will still be forwarded to the
7096 appropriate server.
7097
7098 Note that contrary to a common belief, this option does NOT make HAProxy
7099 present the client's IP to the server when establishing the connection.
7100
Willy Tarreaua1146052011-03-01 09:51:54 +01007101 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007102 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007103
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007104
Simon Horman98637e52014-06-20 12:30:16 +09007105external-check command <command>
7106 Executable to run when performing an external-check
7107 May be used in sections : defaults | frontend | listen | backend
7108 yes | no | yes | yes
7109
7110 Arguments :
7111 <command> is the external command to run
7112
Simon Horman98637e52014-06-20 12:30:16 +09007113 The arguments passed to the to the command are:
7114
Cyril Bonté777be862014-12-02 21:21:35 +01007115 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09007116
Cyril Bonté777be862014-12-02 21:21:35 +01007117 The <proxy_address> and <proxy_port> are derived from the first listener
7118 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
7119 listener the proxy_address will be the path of the socket and the
7120 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
7121 possible to determine a listener, and both <proxy_address> and <proxy_port>
7122 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09007123
Cyril Bonté72cda2a2014-12-27 22:28:39 +01007124 Some values are also provided through environment variables.
7125
7126 Environment variables :
7127 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
7128 applicable, for example in a "backend" section).
7129
7130 HAPROXY_PROXY_ID The backend id.
7131
7132 HAPROXY_PROXY_NAME The backend name.
7133
7134 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
7135 applicable, for example in a "backend" section or
7136 for a UNIX socket).
7137
7138 HAPROXY_SERVER_ADDR The server address.
7139
7140 HAPROXY_SERVER_CURCONN The current number of connections on the server.
7141
7142 HAPROXY_SERVER_ID The server id.
7143
7144 HAPROXY_SERVER_MAXCONN The server max connections.
7145
7146 HAPROXY_SERVER_NAME The server name.
7147
7148 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
7149 socket).
7150
7151 PATH The PATH environment variable used when executing
7152 the command may be set using "external-check path".
7153
Simon Horman98637e52014-06-20 12:30:16 +09007154 If the command executed and exits with a zero status then the check is
7155 considered to have passed, otherwise the check is considered to have
7156 failed.
7157
7158 Example :
7159 external-check command /bin/true
7160
7161 See also : "external-check", "option external-check", "external-check path"
7162
7163
7164external-check path <path>
7165 The value of the PATH environment variable used when running an external-check
7166 May be used in sections : defaults | frontend | listen | backend
7167 yes | no | yes | yes
7168
7169 Arguments :
7170 <path> is the path used when executing external command to run
7171
7172 The default path is "".
7173
7174 Example :
7175 external-check path "/usr/bin:/bin"
7176
7177 See also : "external-check", "option external-check",
7178 "external-check command"
7179
7180
Emeric Brun647caf12009-06-30 17:57:00 +02007181persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007182persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02007183 Enable RDP cookie-based persistence
7184 May be used in sections : defaults | frontend | listen | backend
7185 yes | no | yes | yes
7186 Arguments :
7187 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02007188 default cookie name "msts" will be used. There currently is no
7189 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02007190
7191 This statement enables persistence based on an RDP cookie. The RDP cookie
7192 contains all information required to find the server in the list of known
Davor Ocelice9ed2812017-12-25 17:49:28 +01007193 servers. So when this option is set in the backend, the request is analyzed
Emeric Brun647caf12009-06-30 17:57:00 +02007194 and if an RDP cookie is found, it is decoded. If it matches a known server
7195 which is still UP (or if "option persist" is set), then the connection is
7196 forwarded to this server.
7197
7198 Note that this only makes sense in a TCP backend, but for this to work, the
7199 frontend must have waited long enough to ensure that an RDP cookie is present
7200 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007201 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02007202 a single "listen" section.
7203
Willy Tarreau61e28f22010-05-16 22:31:05 +02007204 Also, it is important to understand that the terminal server will emit this
7205 RDP cookie only if it is configured for "token redirection mode", which means
7206 that the "IP address redirection" option is disabled.
7207
Emeric Brun647caf12009-06-30 17:57:00 +02007208 Example :
7209 listen tse-farm
7210 bind :3389
7211 # wait up to 5s for an RDP cookie in the request
7212 tcp-request inspect-delay 5s
7213 tcp-request content accept if RDP_COOKIE
7214 # apply RDP cookie persistence
7215 persist rdp-cookie
7216 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02007217 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02007218 balance rdp-cookie
7219 server srv1 1.1.1.1:3389
7220 server srv2 1.1.1.2:3389
7221
Simon Hormanab814e02011-06-24 14:50:20 +09007222 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
7223 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02007224
7225
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007226rate-limit sessions <rate>
7227 Set a limit on the number of new sessions accepted per second on a frontend
7228 May be used in sections : defaults | frontend | listen | backend
7229 yes | yes | yes | no
7230 Arguments :
7231 <rate> The <rate> parameter is an integer designating the maximum number
7232 of new sessions per second to accept on the frontend.
7233
7234 When the frontend reaches the specified number of new sessions per second, it
7235 stops accepting new connections until the rate drops below the limit again.
7236 During this time, the pending sessions will be kept in the socket's backlog
7237 (in system buffers) and haproxy will not even be aware that sessions are
7238 pending. When applying very low limit on a highly loaded service, it may make
7239 sense to increase the socket's backlog using the "backlog" keyword.
7240
7241 This feature is particularly efficient at blocking connection-based attacks
7242 or service abuse on fragile servers. Since the session rate is measured every
7243 millisecond, it is extremely accurate. Also, the limit applies immediately,
7244 no delay is needed at all to detect the threshold.
7245
7246 Example : limit the connection rate on SMTP to 10 per second max
7247 listen smtp
7248 mode tcp
7249 bind :25
7250 rate-limit sessions 10
Panagiotis Panagiotopoulos7282d8e2016-02-11 16:37:15 +02007251 server smtp1 127.0.0.1:1025
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007252
Willy Tarreaua17c2d92011-07-25 08:16:20 +02007253 Note : when the maximum rate is reached, the frontend's status is not changed
7254 but its sockets appear as "WAITING" in the statistics if the
7255 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007256
7257 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
7258
7259
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007260redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
7261redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
7262redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007263 Return an HTTP redirection if/unless a condition is matched
7264 May be used in sections : defaults | frontend | listen | backend
7265 no | yes | yes | yes
7266
7267 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01007268 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007269
Willy Tarreau0140f252008-11-19 21:07:09 +01007270 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007271 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007272 the HTTP "Location" header. When used in an "http-request" rule,
7273 <loc> value follows the log-format rules and can include some
7274 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007275
7276 <pfx> With "redirect prefix", the "Location" header is built from the
7277 concatenation of <pfx> and the complete URI path, including the
7278 query string, unless the "drop-query" option is specified (see
7279 below). As a special case, if <pfx> equals exactly "/", then
7280 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007281 redirect to the same URL (for instance, to insert a cookie). When
7282 used in an "http-request" rule, <pfx> value follows the log-format
7283 rules and can include some dynamic values (see Custom Log Format
7284 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007285
7286 <sch> With "redirect scheme", then the "Location" header is built by
7287 concatenating <sch> with "://" then the first occurrence of the
7288 "Host" header, and then the URI path, including the query string
7289 unless the "drop-query" option is specified (see below). If no
7290 path is found or if the path is "*", then "/" is used instead. If
7291 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007292 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007293 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007294 HTTPS. When used in an "http-request" rule, <sch> value follows
7295 the log-format rules and can include some dynamic values (see
7296 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01007297
7298 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007299 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
7300 with 302 used by default if no code is specified. 301 means
7301 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02007302 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007303 cache the redirection. 303 is equivalent to 302 except that the
7304 browser will fetch the location with a GET method. 307 is just
7305 like 302 but makes it clear that the same method must be reused.
7306 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01007307
7308 <option> There are several options which can be specified to adjust the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007309 expected behavior of a redirection :
Willy Tarreau0140f252008-11-19 21:07:09 +01007310
7311 - "drop-query"
7312 When this keyword is used in a prefix-based redirection, then the
7313 location will be set without any possible query-string, which is useful
7314 for directing users to a non-secure page for instance. It has no effect
7315 with a location-type redirect.
7316
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007317 - "append-slash"
7318 This keyword may be used in conjunction with "drop-query" to redirect
7319 users who use a URL not ending with a '/' to the same one with the '/'.
7320 It can be useful to ensure that search engines will only see one URL.
7321 For this, a return code 301 is preferred.
7322
Willy Tarreau0140f252008-11-19 21:07:09 +01007323 - "set-cookie NAME[=value]"
7324 A "Set-Cookie" header will be added with NAME (and optionally "=value")
7325 to the response. This is sometimes used to indicate that a user has
7326 been seen, for instance to protect against some types of DoS. No other
7327 cookie option is added, so the cookie will be a session cookie. Note
7328 that for a browser, a sole cookie name without an equal sign is
7329 different from a cookie with an equal sign.
7330
7331 - "clear-cookie NAME[=]"
7332 A "Set-Cookie" header will be added with NAME (and optionally "="), but
7333 with the "Max-Age" attribute set to zero. This will tell the browser to
7334 delete this cookie. It is useful for instance on logout pages. It is
7335 important to note that clearing the cookie "NAME" will not remove a
7336 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
7337 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007338
7339 Example: move the login URL only to HTTPS.
7340 acl clear dst_port 80
7341 acl secure dst_port 8080
7342 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01007343 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01007344 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01007345 acl cookie_set hdr_sub(cookie) SEEN=1
7346
7347 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01007348 redirect prefix https://mysite.com if login_page !secure
7349 redirect prefix http://mysite.com drop-query if login_page !uid_given
7350 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01007351 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007352
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007353 Example: send redirects for request for articles without a '/'.
7354 acl missing_slash path_reg ^/article/[^/]*$
7355 redirect code 301 prefix / drop-query append-slash if missing_slash
7356
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007357 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01007358 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007359
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007360 Example: append 'www.' prefix in front of all hosts not having it
Coen Rosdorff596659b2016-04-11 11:33:49 +02007361 http-request redirect code 301 location \
7362 http://www.%[hdr(host)]%[capture.req.uri] \
7363 unless { hdr_beg(host) -i www }
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007364
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007365 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007366
7367
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007368redisp (deprecated)
7369redispatch (deprecated)
7370 Enable or disable session redistribution in case of connection failure
7371 May be used in sections: defaults | frontend | listen | backend
7372 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007373 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007374
7375 In HTTP mode, if a server designated by a cookie is down, clients may
7376 definitely stick to it because they cannot flush the cookie, so they will not
7377 be able to access the service anymore.
7378
7379 Specifying "redispatch" will allow the proxy to break their persistence and
7380 redistribute them to a working server.
7381
7382 It also allows to retry last connection to another server in case of multiple
7383 connection failures. Of course, it requires having "retries" set to a nonzero
7384 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01007385
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007386 This form is deprecated, do not use it in any new configuration, use the new
7387 "option redispatch" instead.
7388
7389 See also : "option redispatch"
7390
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007391
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01007392reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01007393 Add a header at the end of the HTTP request
7394 May be used in sections : defaults | frontend | listen | backend
7395 no | yes | yes | yes
7396 Arguments :
7397 <string> is the complete line to be added. Any space or known delimiter
7398 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007399 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007400
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01007401 <cond> is an optional matching condition built from ACLs. It makes it
7402 possible to ignore this rule when other conditions are not met.
7403
Willy Tarreau303c0352008-01-17 19:01:39 +01007404 A new line consisting in <string> followed by a line feed will be added after
7405 the last header of an HTTP request.
7406
7407 Header transformations only apply to traffic which passes through HAProxy,
7408 and not to traffic generated by HAProxy, such as health-checks or error
7409 responses.
7410
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01007411 Example : add "X-Proto: SSL" to requests coming via port 81
7412 acl is-ssl dst_port 81
7413 reqadd X-Proto:\ SSL if is-ssl
7414
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007415 See also: "rspadd", "http-request", section 6 about HTTP header manipulation,
7416 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007417
7418
Willy Tarreau5321c422010-01-28 20:35:13 +01007419reqallow <search> [{if | unless} <cond>]
7420reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007421 Definitely allow an HTTP request if a line matches a regular expression
7422 May be used in sections : defaults | frontend | listen | backend
7423 no | yes | yes | yes
7424 Arguments :
7425 <search> is the regular expression applied to HTTP headers and to the
7426 request line. This is an extended regular expression. Parenthesis
7427 grouping is supported and no preliminary backslash is required.
7428 Any space or known delimiter must be escaped using a backslash
7429 ('\'). The pattern applies to a full line at a time. The
7430 "reqallow" keyword strictly matches case while "reqiallow"
7431 ignores case.
7432
Willy Tarreau5321c422010-01-28 20:35:13 +01007433 <cond> is an optional matching condition built from ACLs. It makes it
7434 possible to ignore this rule when other conditions are not met.
7435
Willy Tarreau303c0352008-01-17 19:01:39 +01007436 A request containing any line which matches extended regular expression
7437 <search> will mark the request as allowed, even if any later test would
7438 result in a deny. The test applies both to the request line and to request
7439 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01007440 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01007441
7442 It is easier, faster and more powerful to use ACLs to write access policies.
7443 Reqdeny, reqallow and reqpass should be avoided in new designs.
7444
7445 Example :
7446 # allow www.* but refuse *.local
7447 reqiallow ^Host:\ www\.
7448 reqideny ^Host:\ .*\.local
7449
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007450 See also: "reqdeny", "block", "http-request", section 6 about HTTP header
7451 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007452
7453
Willy Tarreau5321c422010-01-28 20:35:13 +01007454reqdel <search> [{if | unless} <cond>]
7455reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007456 Delete all headers matching a regular expression in an HTTP request
7457 May be used in sections : defaults | frontend | listen | backend
7458 no | yes | yes | yes
7459 Arguments :
7460 <search> is the regular expression applied to HTTP headers and to the
7461 request line. This is an extended regular expression. Parenthesis
7462 grouping is supported and no preliminary backslash is required.
7463 Any space or known delimiter must be escaped using a backslash
7464 ('\'). The pattern applies to a full line at a time. The "reqdel"
7465 keyword strictly matches case while "reqidel" ignores case.
7466
Willy Tarreau5321c422010-01-28 20:35:13 +01007467 <cond> is an optional matching condition built from ACLs. It makes it
7468 possible to ignore this rule when other conditions are not met.
7469
Willy Tarreau303c0352008-01-17 19:01:39 +01007470 Any header line matching extended regular expression <search> in the request
7471 will be completely deleted. Most common use of this is to remove unwanted
7472 and/or dangerous headers or cookies from a request before passing it to the
7473 next servers.
7474
7475 Header transformations only apply to traffic which passes through HAProxy,
7476 and not to traffic generated by HAProxy, such as health-checks or error
7477 responses. Keep in mind that header names are not case-sensitive.
7478
7479 Example :
7480 # remove X-Forwarded-For header and SERVER cookie
7481 reqidel ^X-Forwarded-For:.*
7482 reqidel ^Cookie:.*SERVER=
7483
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007484 See also: "reqadd", "reqrep", "rspdel", "http-request", section 6 about
7485 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007486
7487
Willy Tarreau5321c422010-01-28 20:35:13 +01007488reqdeny <search> [{if | unless} <cond>]
7489reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007490 Deny an HTTP request if a line matches a regular expression
7491 May be used in sections : defaults | frontend | listen | backend
7492 no | yes | yes | yes
7493 Arguments :
7494 <search> is the regular expression applied to HTTP headers and to the
7495 request line. This is an extended regular expression. Parenthesis
7496 grouping is supported and no preliminary backslash is required.
7497 Any space or known delimiter must be escaped using a backslash
7498 ('\'). The pattern applies to a full line at a time. The
7499 "reqdeny" keyword strictly matches case while "reqideny" ignores
7500 case.
7501
Willy Tarreau5321c422010-01-28 20:35:13 +01007502 <cond> is an optional matching condition built from ACLs. It makes it
7503 possible to ignore this rule when other conditions are not met.
7504
Willy Tarreau303c0352008-01-17 19:01:39 +01007505 A request containing any line which matches extended regular expression
7506 <search> will mark the request as denied, even if any later test would
7507 result in an allow. The test applies both to the request line and to request
7508 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01007509 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01007510
Willy Tarreauced27012008-01-17 20:35:34 +01007511 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007512 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01007513 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01007514
Willy Tarreau303c0352008-01-17 19:01:39 +01007515 It is easier, faster and more powerful to use ACLs to write access policies.
7516 Reqdeny, reqallow and reqpass should be avoided in new designs.
7517
7518 Example :
7519 # refuse *.local, then allow www.*
7520 reqideny ^Host:\ .*\.local
7521 reqiallow ^Host:\ www\.
7522
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007523 See also: "reqallow", "rspdeny", "block", "http-request", section 6 about
7524 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007525
7526
Willy Tarreau5321c422010-01-28 20:35:13 +01007527reqpass <search> [{if | unless} <cond>]
7528reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007529 Ignore any HTTP request line matching a regular expression in next rules
7530 May be used in sections : defaults | frontend | listen | backend
7531 no | yes | yes | yes
7532 Arguments :
7533 <search> is the regular expression applied to HTTP headers and to the
7534 request line. This is an extended regular expression. Parenthesis
7535 grouping is supported and no preliminary backslash is required.
7536 Any space or known delimiter must be escaped using a backslash
7537 ('\'). The pattern applies to a full line at a time. The
7538 "reqpass" keyword strictly matches case while "reqipass" ignores
7539 case.
7540
Willy Tarreau5321c422010-01-28 20:35:13 +01007541 <cond> is an optional matching condition built from ACLs. It makes it
7542 possible to ignore this rule when other conditions are not met.
7543
Willy Tarreau303c0352008-01-17 19:01:39 +01007544 A request containing any line which matches extended regular expression
7545 <search> will skip next rules, without assigning any deny or allow verdict.
7546 The test applies both to the request line and to request headers. Keep in
7547 mind that URLs in request line are case-sensitive while header names are not.
7548
7549 It is easier, faster and more powerful to use ACLs to write access policies.
7550 Reqdeny, reqallow and reqpass should be avoided in new designs.
7551
7552 Example :
7553 # refuse *.local, then allow www.*, but ignore "www.private.local"
7554 reqipass ^Host:\ www.private\.local
7555 reqideny ^Host:\ .*\.local
7556 reqiallow ^Host:\ www\.
7557
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007558 See also: "reqallow", "reqdeny", "block", "http-request", section 6 about
7559 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007560
7561
Willy Tarreau5321c422010-01-28 20:35:13 +01007562reqrep <search> <string> [{if | unless} <cond>]
7563reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007564 Replace a regular expression with a string in an HTTP request line
7565 May be used in sections : defaults | frontend | listen | backend
7566 no | yes | yes | yes
7567 Arguments :
7568 <search> is the regular expression applied to HTTP headers and to the
7569 request line. This is an extended regular expression. Parenthesis
7570 grouping is supported and no preliminary backslash is required.
7571 Any space or known delimiter must be escaped using a backslash
7572 ('\'). The pattern applies to a full line at a time. The "reqrep"
7573 keyword strictly matches case while "reqirep" ignores case.
7574
7575 <string> is the complete line to be added. Any space or known delimiter
7576 must be escaped using a backslash ('\'). References to matched
7577 pattern groups are possible using the common \N form, with N
7578 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007579 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007580
Willy Tarreau5321c422010-01-28 20:35:13 +01007581 <cond> is an optional matching condition built from ACLs. It makes it
7582 possible to ignore this rule when other conditions are not met.
7583
Willy Tarreau303c0352008-01-17 19:01:39 +01007584 Any line matching extended regular expression <search> in the request (both
7585 the request line and header lines) will be completely replaced with <string>.
7586 Most common use of this is to rewrite URLs or domain names in "Host" headers.
7587
7588 Header transformations only apply to traffic which passes through HAProxy,
7589 and not to traffic generated by HAProxy, such as health-checks or error
7590 responses. Note that for increased readability, it is suggested to add enough
7591 spaces between the request and the response. Keep in mind that URLs in
7592 request line are case-sensitive while header names are not.
7593
7594 Example :
7595 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04007596 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01007597 # replace "www.mydomain.com" with "www" in the host name.
7598 reqirep ^Host:\ www.mydomain.com Host:\ www
7599
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007600 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", "http-request",
7601 section 6 about HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007602
7603
Willy Tarreau5321c422010-01-28 20:35:13 +01007604reqtarpit <search> [{if | unless} <cond>]
7605reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007606 Tarpit an HTTP request containing a line matching a regular expression
7607 May be used in sections : defaults | frontend | listen | backend
7608 no | yes | yes | yes
7609 Arguments :
7610 <search> is the regular expression applied to HTTP headers and to the
7611 request line. This is an extended regular expression. Parenthesis
7612 grouping is supported and no preliminary backslash is required.
7613 Any space or known delimiter must be escaped using a backslash
7614 ('\'). The pattern applies to a full line at a time. The
7615 "reqtarpit" keyword strictly matches case while "reqitarpit"
7616 ignores case.
7617
Willy Tarreau5321c422010-01-28 20:35:13 +01007618 <cond> is an optional matching condition built from ACLs. It makes it
7619 possible to ignore this rule when other conditions are not met.
7620
Willy Tarreau303c0352008-01-17 19:01:39 +01007621 A request containing any line which matches extended regular expression
7622 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01007623 be kept open for a pre-defined time, then will return an HTTP error 500 so
7624 that the attacker does not suspect it has been tarpitted. The status 500 will
7625 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01007626 delay is defined by "timeout tarpit", or "timeout connect" if the former is
7627 not set.
7628
7629 The goal of the tarpit is to slow down robots attacking servers with
7630 identifiable requests. Many robots limit their outgoing number of connections
7631 and stay connected waiting for a reply which can take several minutes to
7632 come. Depending on the environment and attack, it may be particularly
7633 efficient at reducing the load on the network and firewalls.
7634
Willy Tarreau5321c422010-01-28 20:35:13 +01007635 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01007636 # ignore user-agents reporting any flavor of "Mozilla" or "MSIE", but
Willy Tarreau303c0352008-01-17 19:01:39 +01007637 # block all others.
7638 reqipass ^User-Agent:\.*(Mozilla|MSIE)
7639 reqitarpit ^User-Agent:
7640
Willy Tarreau5321c422010-01-28 20:35:13 +01007641 # block bad guys
7642 acl badguys src 10.1.0.3 172.16.13.20/28
7643 reqitarpit . if badguys
7644
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007645 See also: "reqallow", "reqdeny", "reqpass", "http-request", section 6
7646 about HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007647
7648
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02007649retries <value>
7650 Set the number of retries to perform on a server after a connection failure
7651 May be used in sections: defaults | frontend | listen | backend
7652 yes | no | yes | yes
7653 Arguments :
7654 <value> is the number of times a connection attempt should be retried on
7655 a server when a connection either is refused or times out. The
7656 default value is 3.
7657
7658 It is important to understand that this value applies to the number of
7659 connection attempts, not full requests. When a connection has effectively
7660 been established to a server, there will be no more retry.
7661
7662 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -07007663 a turn-around timer of min("timeout connect", one second) is applied before
7664 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02007665
7666 When "option redispatch" is set, the last retry may be performed on another
7667 server even if a cookie references a different server.
7668
7669 See also : "option redispatch"
7670
7671
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007672rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01007673 Add a header at the end of the HTTP response
7674 May be used in sections : defaults | frontend | listen | backend
7675 no | yes | yes | yes
7676 Arguments :
7677 <string> is the complete line to be added. Any space or known delimiter
7678 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007679 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007680
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007681 <cond> is an optional matching condition built from ACLs. It makes it
7682 possible to ignore this rule when other conditions are not met.
7683
Willy Tarreau303c0352008-01-17 19:01:39 +01007684 A new line consisting in <string> followed by a line feed will be added after
7685 the last header of an HTTP response.
7686
7687 Header transformations only apply to traffic which passes through HAProxy,
7688 and not to traffic generated by HAProxy, such as health-checks or error
7689 responses.
7690
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007691 See also: "rspdel" "reqadd", "http-response", section 6 about HTTP header
7692 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007693
7694
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007695rspdel <search> [{if | unless} <cond>]
7696rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007697 Delete all headers matching a regular expression in an HTTP response
7698 May be used in sections : defaults | frontend | listen | backend
7699 no | yes | yes | yes
7700 Arguments :
7701 <search> is the regular expression applied to HTTP headers and to the
7702 response line. This is an extended regular expression, so
7703 parenthesis grouping is supported and no preliminary backslash
7704 is required. Any space or known delimiter must be escaped using
7705 a backslash ('\'). The pattern applies to a full line at a time.
7706 The "rspdel" keyword strictly matches case while "rspidel"
7707 ignores case.
7708
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007709 <cond> is an optional matching condition built from ACLs. It makes it
7710 possible to ignore this rule when other conditions are not met.
7711
Willy Tarreau303c0352008-01-17 19:01:39 +01007712 Any header line matching extended regular expression <search> in the response
7713 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02007714 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01007715 client.
7716
7717 Header transformations only apply to traffic which passes through HAProxy,
7718 and not to traffic generated by HAProxy, such as health-checks or error
7719 responses. Keep in mind that header names are not case-sensitive.
7720
7721 Example :
7722 # remove the Server header from responses
Willy Tarreau5e80e022013-05-25 08:31:25 +02007723 rspidel ^Server:.*
Willy Tarreau303c0352008-01-17 19:01:39 +01007724
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007725 See also: "rspadd", "rsprep", "reqdel", "http-response", section 6 about
7726 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007727
7728
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007729rspdeny <search> [{if | unless} <cond>]
7730rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007731 Block an HTTP response if a line matches a regular expression
7732 May be used in sections : defaults | frontend | listen | backend
7733 no | yes | yes | yes
7734 Arguments :
7735 <search> is the regular expression applied to HTTP headers and to the
7736 response line. This is an extended regular expression, so
7737 parenthesis grouping is supported and no preliminary backslash
7738 is required. Any space or known delimiter must be escaped using
7739 a backslash ('\'). The pattern applies to a full line at a time.
7740 The "rspdeny" keyword strictly matches case while "rspideny"
7741 ignores case.
7742
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007743 <cond> is an optional matching condition built from ACLs. It makes it
7744 possible to ignore this rule when other conditions are not met.
7745
Willy Tarreau303c0352008-01-17 19:01:39 +01007746 A response containing any line which matches extended regular expression
7747 <search> will mark the request as denied. The test applies both to the
7748 response line and to response headers. Keep in mind that header names are not
7749 case-sensitive.
7750
7751 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01007752 block the response before it reaches the client. If a response is denied, it
7753 will be replaced with an HTTP 502 error so that the client never retrieves
7754 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01007755
7756 It is easier, faster and more powerful to use ACLs to write access policies.
7757 Rspdeny should be avoided in new designs.
7758
7759 Example :
7760 # Ensure that no content type matching ms-word will leak
7761 rspideny ^Content-type:\.*/ms-word
7762
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007763 See also: "reqdeny", "acl", "block", "http-response", section 6 about
7764 HTTP header manipulation and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007765
7766
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007767rsprep <search> <string> [{if | unless} <cond>]
7768rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007769 Replace a regular expression with a string in an HTTP response line
7770 May be used in sections : defaults | frontend | listen | backend
7771 no | yes | yes | yes
7772 Arguments :
7773 <search> is the regular expression applied to HTTP headers and to the
7774 response line. This is an extended regular expression, so
7775 parenthesis grouping is supported and no preliminary backslash
7776 is required. Any space or known delimiter must be escaped using
7777 a backslash ('\'). The pattern applies to a full line at a time.
7778 The "rsprep" keyword strictly matches case while "rspirep"
7779 ignores case.
7780
7781 <string> is the complete line to be added. Any space or known delimiter
7782 must be escaped using a backslash ('\'). References to matched
7783 pattern groups are possible using the common \N form, with N
7784 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007785 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007786
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007787 <cond> is an optional matching condition built from ACLs. It makes it
7788 possible to ignore this rule when other conditions are not met.
7789
Willy Tarreau303c0352008-01-17 19:01:39 +01007790 Any line matching extended regular expression <search> in the response (both
7791 the response line and header lines) will be completely replaced with
7792 <string>. Most common use of this is to rewrite Location headers.
7793
7794 Header transformations only apply to traffic which passes through HAProxy,
7795 and not to traffic generated by HAProxy, such as health-checks or error
7796 responses. Note that for increased readability, it is suggested to add enough
7797 spaces between the request and the response. Keep in mind that header names
7798 are not case-sensitive.
7799
7800 Example :
7801 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
7802 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
7803
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007804 See also: "rspadd", "rspdel", "reqrep", "http-response", section 6 about
7805 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007806
7807
David du Colombier486df472011-03-17 10:40:26 +01007808server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007809 Declare a server in a backend
7810 May be used in sections : defaults | frontend | listen | backend
7811 no | no | yes | yes
7812 Arguments :
7813 <name> is the internal name assigned to this server. This name will
Davor Ocelice9ed2812017-12-25 17:49:28 +01007814 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05007815 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007816
David du Colombier486df472011-03-17 10:40:26 +01007817 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
7818 resolvable hostname is supported, but this name will be resolved
7819 during start-up. Address "0.0.0.0" or "*" has a special meaning.
7820 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02007821 address as the one from the client connection. This is useful in
7822 transparent proxy architectures where the client's connection is
7823 intercepted and haproxy must forward to the original destination
7824 address. This is more or less what the "transparent" keyword does
7825 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01007826 to report statistics. Optionally, an address family prefix may be
7827 used before the address to force the family regardless of the
7828 address format, which can be useful to specify a path to a unix
7829 socket with no slash ('/'). Currently supported prefixes are :
7830 - 'ipv4@' -> address is always IPv4
7831 - 'ipv6@' -> address is always IPv6
7832 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02007833 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemand2fe7dd02018-09-11 16:51:29 +02007834 - 'sockpair@' -> address is the FD of a connected unix
7835 socket or of a socketpair. During a connection, the
7836 backend creates a pair of connected sockets, and passes
7837 one of them over the FD. The bind part will use the
7838 received socket as the client FD. Should be used
7839 carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02007840 You may want to reference some environment variables in the
7841 address parameter, see section 2.3 about environment
Willy Tarreau6a031d12016-11-07 19:42:35 +01007842 variables. The "init-addr" setting can be used to modify the way
7843 IP addresses should be resolved upon startup.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007844
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007845 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007846 be sent to this port. If unset, the same port the client
7847 connected to will be used. The port may also be prefixed by a "+"
7848 or a "-". In this case, the server's port will be determined by
7849 adding this value to the client's port.
7850
7851 <param*> is a list of parameters for this server. The "server" keywords
7852 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007853 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007854
7855 Examples :
7856 server first 10.1.1.1:1080 cookie first check inter 1000
7857 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01007858 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +02007859 server backup "${SRV_BACKUP}:1080" backup
7860 server www1_dc1 "${LAN_DC1}.101:80"
7861 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007862
Willy Tarreau55dcaf62015-09-27 15:03:15 +02007863 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
7864 sun_path length is used for the address length. Some other programs
7865 such as socat use the string length only by default. Pass the option
7866 ",unix-tightsocklen=0" to any abstract socket definition in socat to
7867 make it compatible with HAProxy's.
7868
Mark Lamourinec2247f02012-01-04 13:02:01 -05007869 See also: "default-server", "http-send-name-header" and section 5 about
7870 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007871
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007872server-state-file-name [<file>]
7873 Set the server state file to read, load and apply to servers available in
7874 this backend. It only applies when the directive "load-server-state-from-file"
7875 is set to "local". When <file> is not provided or if this directive is not
7876 set, then backend name is used. If <file> starts with a slash '/', then it is
7877 considered as an absolute path. Otherwise, <file> is concatenated to the
7878 global directive "server-state-file-base".
7879
7880 Example: the minimal configuration below would make HAProxy look for the
7881 state server file '/etc/haproxy/states/bk':
7882
7883 global
7884 server-state-file-base /etc/haproxy/states
7885
7886 backend bk
7887 load-server-state-from-file
7888
7889 See also: "server-state-file-base", "load-server-state-from-file", and
7890 "show servers state"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007891
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02007892server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
7893 Set a template to initialize servers with shared parameters.
7894 The names of these servers are built from <prefix> and <num | range> parameters.
7895 May be used in sections : defaults | frontend | listen | backend
7896 no | no | yes | yes
7897
7898 Arguments:
7899 <prefix> A prefix for the server names to be built.
7900
7901 <num | range>
7902 If <num> is provided, this template initializes <num> servers
7903 with 1 up to <num> as server name suffixes. A range of numbers
7904 <num_low>-<num_high> may also be used to use <num_low> up to
7905 <num_high> as server name suffixes.
7906
7907 <fqdn> A FQDN for all the servers this template initializes.
7908
7909 <port> Same meaning as "server" <port> argument (see "server" keyword).
7910
7911 <params*>
7912 Remaining server parameters among all those supported by "server"
7913 keyword.
7914
7915 Examples:
7916 # Initializes 3 servers with srv1, srv2 and srv3 as names,
7917 # google.com as FQDN, and health-check enabled.
7918 server-template srv 1-3 google.com:80 check
7919
7920 # or
7921 server-template srv 3 google.com:80 check
7922
7923 # would be equivalent to:
7924 server srv1 google.com:80 check
7925 server srv2 google.com:80 check
7926 server srv3 google.com:80 check
7927
7928
7929
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007930source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02007931source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01007932source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007933 Set the source address for outgoing connections
7934 May be used in sections : defaults | frontend | listen | backend
7935 yes | no | yes | yes
7936 Arguments :
7937 <addr> is the IPv4 address HAProxy will bind to before connecting to a
7938 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01007939
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007940 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01007941 the most appropriate address to reach its destination. Optionally
7942 an address family prefix may be used before the address to force
7943 the family regardless of the address format, which can be useful
7944 to specify a path to a unix socket with no slash ('/'). Currently
7945 supported prefixes are :
7946 - 'ipv4@' -> address is always IPv4
7947 - 'ipv6@' -> address is always IPv6
7948 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02007949 - 'abns@' -> address is in abstract namespace (Linux only)
Cyril Bonté307ee1e2015-09-28 23:16:06 +02007950 You may want to reference some environment variables in the
7951 address parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007952
7953 <port> is an optional port. It is normally not needed but may be useful
7954 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007955 the system will select a free port. Note that port ranges are not
7956 supported in the backend. If you want to force port ranges, you
7957 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007958
7959 <addr2> is the IP address to present to the server when connections are
7960 forwarded in full transparent proxy mode. This is currently only
7961 supported on some patched Linux kernels. When this address is
7962 specified, clients connecting to the server will be presented
7963 with this address, while health checks will still use the address
7964 <addr>.
7965
7966 <port2> is the optional port to present to the server when connections
7967 are forwarded in full transparent proxy mode (see <addr2> above).
7968 The default value of zero means the system will select a free
7969 port.
7970
Willy Tarreaubce70882009-09-07 11:51:47 +02007971 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
7972 This is the name of a comma-separated header list which can
7973 contain multiple IP addresses. By default, the last occurrence is
7974 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01007975 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02007976 by previous proxy, typically Stunnel. In order to use another
7977 occurrence from the last one, please see the <occ> parameter
7978 below. When the header (or occurrence) is not found, no binding
7979 is performed so that the proxy's default IP address is used. Also
7980 keep in mind that the header name is case insensitive, as for any
7981 HTTP header.
7982
7983 <occ> is the occurrence number of a value to be used in a multi-value
7984 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007985 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02007986 address. Positive values indicate a position from the first
7987 occurrence, 1 being the first one. Negative values indicate
7988 positions relative to the last one, -1 being the last one. This
7989 is helpful for situations where an X-Forwarded-For header is set
7990 at the entry point of an infrastructure and must be used several
7991 proxy layers away. When this value is not specified, -1 is
7992 assumed. Passing a zero here disables the feature.
7993
Willy Tarreaud53f96b2009-02-04 18:46:54 +01007994 <name> is an optional interface name to which to bind to for outgoing
7995 traffic. On systems supporting this features (currently, only
7996 Linux), this allows one to bind all traffic to the server to
7997 this interface even if it is not the one the system would select
7998 based on routing tables. This should be used with extreme care.
7999 Note that using this option requires root privileges.
8000
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008001 The "source" keyword is useful in complex environments where a specific
8002 address only is allowed to connect to the servers. It may be needed when a
8003 private address must be used through a public gateway for instance, and it is
8004 known that the system cannot determine the adequate source address by itself.
8005
8006 An extension which is available on certain patched Linux kernels may be used
8007 through the "usesrc" optional keyword. It makes it possible to connect to the
8008 servers with an IP address which does not belong to the system itself. This
8009 is called "full transparent proxy mode". For this to work, the destination
8010 servers have to route their traffic back to this address through the machine
8011 running HAProxy, and IP forwarding must generally be enabled on this machine.
8012
8013 In this "full transparent proxy" mode, it is possible to force a specific IP
8014 address to be presented to the servers. This is not much used in fact. A more
8015 common use is to tell HAProxy to present the client's IP address. For this,
8016 there are two methods :
8017
8018 - present the client's IP and port addresses. This is the most transparent
8019 mode, but it can cause problems when IP connection tracking is enabled on
8020 the machine, because a same connection may be seen twice with different
8021 states. However, this solution presents the huge advantage of not
8022 limiting the system to the 64k outgoing address+port couples, because all
8023 of the client ranges may be used.
8024
8025 - present only the client's IP address and select a spare port. This
8026 solution is still quite elegant but slightly less transparent (downstream
8027 firewalls logs will not match upstream's). It also presents the downside
8028 of limiting the number of concurrent connections to the usual 64k ports.
8029 However, since the upstream and downstream ports are different, local IP
8030 connection tracking on the machine will not be upset by the reuse of the
8031 same session.
8032
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008033 This option sets the default source for all servers in the backend. It may
8034 also be specified in a "defaults" section. Finer source address specification
8035 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008036 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008037
Baptiste Assmann91bd3372015-07-17 21:59:42 +02008038 In order to work, "usesrc" requires root privileges.
8039
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008040 Examples :
8041 backend private
8042 # Connect to the servers using our 192.168.1.200 source address
8043 source 192.168.1.200
8044
8045 backend transparent_ssl1
8046 # Connect to the SSL farm from the client's source address
8047 source 192.168.1.200 usesrc clientip
8048
8049 backend transparent_ssl2
8050 # Connect to the SSL farm from the client's source address and port
8051 # not recommended if IP conntrack is present on the local machine.
8052 source 192.168.1.200 usesrc client
8053
8054 backend transparent_ssl3
8055 # Connect to the SSL farm from the client's source address. It
8056 # is more conntrack-friendly.
8057 source 192.168.1.200 usesrc clientip
8058
8059 backend transparent_smtp
8060 # Connect to the SMTP farm from the client's source address/port
8061 # with Tproxy version 4.
8062 source 0.0.0.0 usesrc clientip
8063
Willy Tarreaubce70882009-09-07 11:51:47 +02008064 backend transparent_http
8065 # Connect to the servers using the client's IP as seen by previous
8066 # proxy.
8067 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
8068
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008069 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008070 the Linux kernel on www.balabit.com, the "bind" keyword.
8071
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008072
Willy Tarreau844e3c52008-01-11 16:28:18 +01008073srvtimeout <timeout> (deprecated)
8074 Set the maximum inactivity time on the server side.
8075 May be used in sections : defaults | frontend | listen | backend
8076 yes | no | yes | yes
8077 Arguments :
8078 <timeout> is the timeout value specified in milliseconds by default, but
8079 can be in any other unit if the number is suffixed by the unit,
8080 as explained at the top of this document.
8081
8082 The inactivity timeout applies when the server is expected to acknowledge or
8083 send data. In HTTP mode, this timeout is particularly important to consider
8084 during the first phase of the server's response, when it has to send the
8085 headers, as it directly represents the server's processing time for the
8086 request. To find out what value to put there, it's often good to start with
8087 what would be considered as unacceptable response times, then check the logs
8088 to observe the response time distribution, and adjust the value accordingly.
8089
8090 The value is specified in milliseconds by default, but can be in any other
8091 unit if the number is suffixed by the unit, as specified at the top of this
8092 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
8093 recommended that the client timeout remains equal to the server timeout in
8094 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008095 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01008096 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +01008097 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01008098
8099 This parameter is specific to backends, but can be specified once for all in
8100 "defaults" sections. This is in fact one of the easiest solutions not to
8101 forget about it. An unspecified timeout results in an infinite timeout, which
8102 is not recommended. Such a usage is accepted and works but reports a warning
8103 during startup because it may results in accumulation of expired sessions in
8104 the system if the system's timeouts are not configured either.
8105
8106 This parameter is provided for compatibility but is currently deprecated.
8107 Please use "timeout server" instead.
8108
Willy Tarreauce887fd2012-05-12 12:50:00 +02008109 See also : "timeout server", "timeout tunnel", "timeout client" and
8110 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01008111
8112
Cyril Bonté66c327d2010-10-12 00:14:37 +02008113stats admin { if | unless } <cond>
8114 Enable statistics admin level if/unless a condition is matched
8115 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008116 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +02008117
8118 This statement enables the statistics admin level if/unless a condition is
8119 matched.
8120
8121 The admin level allows to enable/disable servers from the web interface. By
8122 default, statistics page is read-only for security reasons.
8123
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008124 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8125 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008126 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008127
Cyril Bonté23b39d92011-02-10 22:54:44 +01008128 Currently, the POST request is limited to the buffer size minus the reserved
8129 buffer space, which means that if the list of servers is too long, the
8130 request won't be processed. It is recommended to alter few servers at a
8131 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008132
8133 Example :
8134 # statistics admin level only for localhost
8135 backend stats_localhost
8136 stats enable
8137 stats admin if LOCALHOST
8138
8139 Example :
8140 # statistics admin level always enabled because of the authentication
8141 backend stats_auth
8142 stats enable
8143 stats auth admin:AdMiN123
8144 stats admin if TRUE
8145
8146 Example :
8147 # statistics admin level depends on the authenticated user
8148 userlist stats-auth
8149 group admin users admin
8150 user admin insecure-password AdMiN123
8151 group readonly users haproxy
8152 user haproxy insecure-password haproxy
8153
8154 backend stats_auth
8155 stats enable
8156 acl AUTH http_auth(stats-auth)
8157 acl AUTH_ADMIN http_auth_group(stats-auth) admin
8158 stats http-request auth unless AUTH
8159 stats admin if AUTH_ADMIN
8160
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008161 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
8162 "bind-process", section 3.4 about userlists and section 7 about
8163 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008164
8165
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008166stats auth <user>:<passwd>
8167 Enable statistics with authentication and grant access to an account
8168 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008169 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008170 Arguments :
8171 <user> is a user name to grant access to
8172
8173 <passwd> is the cleartext password associated to this user
8174
8175 This statement enables statistics with default settings, and restricts access
8176 to declared users only. It may be repeated as many times as necessary to
8177 allow as many users as desired. When a user tries to access the statistics
8178 without a valid account, a "401 Forbidden" response will be returned so that
8179 the browser asks the user to provide a valid user and password. The real
8180 which will be returned to the browser is configurable using "stats realm".
8181
8182 Since the authentication method is HTTP Basic Authentication, the passwords
8183 circulate in cleartext on the network. Thus, it was decided that the
8184 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02008185 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008186
8187 It is also possible to reduce the scope of the proxies which appear in the
8188 report using "stats scope".
8189
8190 Though this statement alone is enough to enable statistics reporting, it is
8191 recommended to set all other settings in order to avoid relying on default
8192 unobvious parameters.
8193
8194 Example :
8195 # public access (limited to this backend only)
8196 backend public_www
8197 server srv1 192.168.0.1:80
8198 stats enable
8199 stats hide-version
8200 stats scope .
8201 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008202 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008203 stats auth admin1:AdMiN123
8204 stats auth admin2:AdMiN321
8205
8206 # internal monitoring access (unlimited)
8207 backend private_monitoring
8208 stats enable
8209 stats uri /admin?stats
8210 stats refresh 5s
8211
8212 See also : "stats enable", "stats realm", "stats scope", "stats uri"
8213
8214
8215stats enable
8216 Enable statistics reporting with default settings
8217 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008218 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008219 Arguments : none
8220
8221 This statement enables statistics reporting with default settings defined
8222 at build time. Unless stated otherwise, these settings are used :
8223 - stats uri : /haproxy?stats
8224 - stats realm : "HAProxy Statistics"
8225 - stats auth : no authentication
8226 - stats scope : no restriction
8227
8228 Though this statement alone is enough to enable statistics reporting, it is
8229 recommended to set all other settings in order to avoid relying on default
8230 unobvious parameters.
8231
8232 Example :
8233 # public access (limited to this backend only)
8234 backend public_www
8235 server srv1 192.168.0.1:80
8236 stats enable
8237 stats hide-version
8238 stats scope .
8239 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008240 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008241 stats auth admin1:AdMiN123
8242 stats auth admin2:AdMiN321
8243
8244 # internal monitoring access (unlimited)
8245 backend private_monitoring
8246 stats enable
8247 stats uri /admin?stats
8248 stats refresh 5s
8249
8250 See also : "stats auth", "stats realm", "stats uri"
8251
8252
Willy Tarreaud63335a2010-02-26 12:56:52 +01008253stats hide-version
8254 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008255 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008256 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008257 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008258
Willy Tarreaud63335a2010-02-26 12:56:52 +01008259 By default, the stats page reports some useful status information along with
8260 the statistics. Among them is HAProxy's version. However, it is generally
8261 considered dangerous to report precise version to anyone, as it can help them
8262 target known weaknesses with specific attacks. The "stats hide-version"
8263 statement removes the version from the statistics report. This is recommended
8264 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008265
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02008266 Though this statement alone is enough to enable statistics reporting, it is
8267 recommended to set all other settings in order to avoid relying on default
8268 unobvious parameters.
8269
Willy Tarreaud63335a2010-02-26 12:56:52 +01008270 Example :
8271 # public access (limited to this backend only)
8272 backend public_www
8273 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02008274 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01008275 stats hide-version
8276 stats scope .
8277 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008278 stats realm HAProxy\ Statistics
Willy Tarreaud63335a2010-02-26 12:56:52 +01008279 stats auth admin1:AdMiN123
8280 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008281
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008282 # internal monitoring access (unlimited)
8283 backend private_monitoring
8284 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01008285 stats uri /admin?stats
8286 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01008287
Willy Tarreaud63335a2010-02-26 12:56:52 +01008288 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008289
Willy Tarreau983e01e2010-01-11 18:42:06 +01008290
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02008291stats http-request { allow | deny | auth [realm <realm>] }
8292 [ { if | unless } <condition> ]
8293 Access control for statistics
8294
8295 May be used in sections: defaults | frontend | listen | backend
8296 no | no | yes | yes
8297
8298 As "http-request", these set of options allow to fine control access to
8299 statistics. Each option may be followed by if/unless and acl.
8300 First option with matched condition (or option without condition) is final.
8301 For "deny" a 403 error will be returned, for "allow" normal processing is
8302 performed, for "auth" a 401/407 error code is returned so the client
8303 should be asked to enter a username and password.
8304
8305 There is no fixed limit to the number of http-request statements per
8306 instance.
8307
8308 See also : "http-request", section 3.4 about userlists and section 7
8309 about ACL usage.
8310
8311
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008312stats realm <realm>
8313 Enable statistics and set authentication realm
8314 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008315 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008316 Arguments :
8317 <realm> is the name of the HTTP Basic Authentication realm reported to
8318 the browser. The browser uses it to display it in the pop-up
8319 inviting the user to enter a valid username and password.
8320
8321 The realm is read as a single word, so any spaces in it should be escaped
8322 using a backslash ('\').
8323
8324 This statement is useful only in conjunction with "stats auth" since it is
8325 only related to authentication.
8326
8327 Though this statement alone is enough to enable statistics reporting, it is
8328 recommended to set all other settings in order to avoid relying on default
8329 unobvious parameters.
8330
8331 Example :
8332 # public access (limited to this backend only)
8333 backend public_www
8334 server srv1 192.168.0.1:80
8335 stats enable
8336 stats hide-version
8337 stats scope .
8338 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008339 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008340 stats auth admin1:AdMiN123
8341 stats auth admin2:AdMiN321
8342
8343 # internal monitoring access (unlimited)
8344 backend private_monitoring
8345 stats enable
8346 stats uri /admin?stats
8347 stats refresh 5s
8348
8349 See also : "stats auth", "stats enable", "stats uri"
8350
8351
8352stats refresh <delay>
8353 Enable statistics with automatic refresh
8354 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008355 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008356 Arguments :
8357 <delay> is the suggested refresh delay, specified in seconds, which will
8358 be returned to the browser consulting the report page. While the
8359 browser is free to apply any delay, it will generally respect it
8360 and refresh the page this every seconds. The refresh interval may
8361 be specified in any other non-default time unit, by suffixing the
8362 unit after the value, as explained at the top of this document.
8363
8364 This statement is useful on monitoring displays with a permanent page
8365 reporting the load balancer's activity. When set, the HTML report page will
8366 include a link "refresh"/"stop refresh" so that the user can select whether
8367 he wants automatic refresh of the page or not.
8368
8369 Though this statement alone is enough to enable statistics reporting, it is
8370 recommended to set all other settings in order to avoid relying on default
8371 unobvious parameters.
8372
8373 Example :
8374 # public access (limited to this backend only)
8375 backend public_www
8376 server srv1 192.168.0.1:80
8377 stats enable
8378 stats hide-version
8379 stats scope .
8380 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008381 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008382 stats auth admin1:AdMiN123
8383 stats auth admin2:AdMiN321
8384
8385 # internal monitoring access (unlimited)
8386 backend private_monitoring
8387 stats enable
8388 stats uri /admin?stats
8389 stats refresh 5s
8390
8391 See also : "stats auth", "stats enable", "stats realm", "stats uri"
8392
8393
8394stats scope { <name> | "." }
8395 Enable statistics and limit access scope
8396 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008397 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008398 Arguments :
8399 <name> is the name of a listen, frontend or backend section to be
8400 reported. The special name "." (a single dot) designates the
8401 section in which the statement appears.
8402
8403 When this statement is specified, only the sections enumerated with this
8404 statement will appear in the report. All other ones will be hidden. This
8405 statement may appear as many times as needed if multiple sections need to be
8406 reported. Please note that the name checking is performed as simple string
8407 comparisons, and that it is never checked that a give section name really
8408 exists.
8409
8410 Though this statement alone is enough to enable statistics reporting, it is
8411 recommended to set all other settings in order to avoid relying on default
8412 unobvious parameters.
8413
8414 Example :
8415 # public access (limited to this backend only)
8416 backend public_www
8417 server srv1 192.168.0.1:80
8418 stats enable
8419 stats hide-version
8420 stats scope .
8421 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008422 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008423 stats auth admin1:AdMiN123
8424 stats auth admin2:AdMiN321
8425
8426 # internal monitoring access (unlimited)
8427 backend private_monitoring
8428 stats enable
8429 stats uri /admin?stats
8430 stats refresh 5s
8431
8432 See also : "stats auth", "stats enable", "stats realm", "stats uri"
8433
Willy Tarreaud63335a2010-02-26 12:56:52 +01008434
Willy Tarreauc9705a12010-07-27 20:05:50 +02008435stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01008436 Enable reporting of a description on the statistics page.
8437 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008438 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008439
Willy Tarreauc9705a12010-07-27 20:05:50 +02008440 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01008441 description from global section is automatically used instead.
8442
8443 This statement is useful for users that offer shared services to their
8444 customers, where node or description should be different for each customer.
8445
8446 Though this statement alone is enough to enable statistics reporting, it is
8447 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01008448 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008449
8450 Example :
8451 # internal monitoring access (unlimited)
8452 backend private_monitoring
8453 stats enable
8454 stats show-desc Master node for Europe, Asia, Africa
8455 stats uri /admin?stats
8456 stats refresh 5s
8457
8458 See also: "show-node", "stats enable", "stats uri" and "description" in
8459 global section.
8460
8461
8462stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +02008463 Enable reporting additional information on the statistics page
8464 May be used in sections : defaults | frontend | listen | backend
8465 yes | yes | yes | yes
8466 Arguments : none
8467
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008468 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +01008469 - cap: capabilities (proxy)
8470 - mode: one of tcp, http or health (proxy)
8471 - id: SNMP ID (proxy, socket, server)
8472 - IP (socket, server)
8473 - cookie (backend, server)
8474
8475 Though this statement alone is enough to enable statistics reporting, it is
8476 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01008477 unobvious parameters. Default behavior is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008478
8479 See also: "stats enable", "stats uri".
8480
8481
8482stats show-node [ <name> ]
8483 Enable reporting of a host name on the statistics page.
8484 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008485 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008486 Arguments:
8487 <name> is an optional name to be reported. If unspecified, the
8488 node name from global section is automatically used instead.
8489
8490 This statement is useful for users that offer shared services to their
8491 customers, where node or description might be different on a stats page
Davor Ocelice9ed2812017-12-25 17:49:28 +01008492 provided for each customer. Default behavior is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008493
8494 Though this statement alone is enough to enable statistics reporting, it is
8495 recommended to set all other settings in order to avoid relying on default
8496 unobvious parameters.
8497
8498 Example:
8499 # internal monitoring access (unlimited)
8500 backend private_monitoring
8501 stats enable
8502 stats show-node Europe-1
8503 stats uri /admin?stats
8504 stats refresh 5s
8505
8506 See also: "show-desc", "stats enable", "stats uri", and "node" in global
8507 section.
8508
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008509
8510stats uri <prefix>
8511 Enable statistics and define the URI prefix to access them
8512 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008513 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008514 Arguments :
8515 <prefix> is the prefix of any URI which will be redirected to stats. This
8516 prefix may contain a question mark ('?') to indicate part of a
8517 query string.
8518
8519 The statistics URI is intercepted on the relayed traffic, so it appears as a
8520 page within the normal application. It is strongly advised to ensure that the
8521 selected URI will never appear in the application, otherwise it will never be
8522 possible to reach it in the application.
8523
8524 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008525 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008526 It is generally a good idea to include a question mark in the URI so that
8527 intermediate proxies refrain from caching the results. Also, since any string
8528 beginning with the prefix will be accepted as a stats request, the question
8529 mark helps ensuring that no valid URI will begin with the same words.
8530
8531 It is sometimes very convenient to use "/" as the URI prefix, and put that
8532 statement in a "listen" instance of its own. That makes it easy to dedicate
8533 an address or a port to statistics only.
8534
8535 Though this statement alone is enough to enable statistics reporting, it is
8536 recommended to set all other settings in order to avoid relying on default
8537 unobvious parameters.
8538
8539 Example :
8540 # public access (limited to this backend only)
8541 backend public_www
8542 server srv1 192.168.0.1:80
8543 stats enable
8544 stats hide-version
8545 stats scope .
8546 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008547 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008548 stats auth admin1:AdMiN123
8549 stats auth admin2:AdMiN321
8550
8551 # internal monitoring access (unlimited)
8552 backend private_monitoring
8553 stats enable
8554 stats uri /admin?stats
8555 stats refresh 5s
8556
8557 See also : "stats auth", "stats enable", "stats realm"
8558
8559
Willy Tarreaud63335a2010-02-26 12:56:52 +01008560stick match <pattern> [table <table>] [{if | unless} <cond>]
8561 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008562 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01008563 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008564
8565 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008566 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008567 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01008568 will be analyzed in the hope to find a matching entry in a
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008569 stickiness table. This rule is mandatory.
8570
8571 <table> is an optional stickiness table name. If unspecified, the same
8572 backend's table is used. A stickiness table is declared using
8573 the "stick-table" statement.
8574
8575 <cond> is an optional matching condition. It makes it possible to match
8576 on a certain criterion only when other conditions are met (or
8577 not met). For instance, it could be used to match on a source IP
8578 address except when a request passes through a known proxy, in
8579 which case we'd match on a header containing that IP address.
8580
8581 Some protocols or applications require complex stickiness rules and cannot
8582 always simply rely on cookies nor hashing. The "stick match" statement
8583 describes a rule to extract the stickiness criterion from an incoming request
8584 or connection. See section 7 for a complete list of possible patterns and
8585 transformation rules.
8586
8587 The table has to be declared using the "stick-table" statement. It must be of
8588 a type compatible with the pattern. By default it is the one which is present
8589 in the same backend. It is possible to share a table with other backends by
8590 referencing it using the "table" keyword. If another table is referenced,
8591 the server's ID inside the backends are used. By default, all server IDs
8592 start at 1 in each backend, so the server ordering is enough. But in case of
8593 doubt, it is highly recommended to force server IDs using their "id" setting.
8594
8595 It is possible to restrict the conditions where a "stick match" statement
8596 will apply, using "if" or "unless" followed by a condition. See section 7 for
8597 ACL based conditions.
8598
8599 There is no limit on the number of "stick match" statements. The first that
8600 applies and matches will cause the request to be directed to the same server
8601 as was used for the request which created the entry. That way, multiple
8602 matches can be used as fallbacks.
8603
8604 The stick rules are checked after the persistence cookies, so they will not
8605 affect stickiness if a cookie has already been used to select a server. That
8606 way, it becomes very easy to insert cookies and match on IP addresses in
8607 order to maintain stickiness between HTTP and HTTPS.
8608
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008609 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8610 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008611 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008612
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008613 Example :
8614 # forward SMTP users to the same server they just used for POP in the
8615 # last 30 minutes
8616 backend pop
8617 mode tcp
8618 balance roundrobin
8619 stick store-request src
8620 stick-table type ip size 200k expire 30m
8621 server s1 192.168.1.1:110
8622 server s2 192.168.1.1:110
8623
8624 backend smtp
8625 mode tcp
8626 balance roundrobin
8627 stick match src table pop
8628 server s1 192.168.1.1:25
8629 server s2 192.168.1.1:25
8630
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008631 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02008632 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008633
8634
8635stick on <pattern> [table <table>] [{if | unless} <condition>]
8636 Define a request pattern to associate a user to a server
8637 May be used in sections : defaults | frontend | listen | backend
8638 no | no | yes | yes
8639
8640 Note : This form is exactly equivalent to "stick match" followed by
8641 "stick store-request", all with the same arguments. Please refer
8642 to both keywords for details. It is only provided as a convenience
8643 for writing more maintainable configurations.
8644
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008645 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8646 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008647 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008648
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008649 Examples :
8650 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01008651 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008652
8653 # ...is strictly equivalent to this one :
8654 stick match src table pop if !localhost
8655 stick store-request src table pop if !localhost
8656
8657
8658 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
8659 # well as HTTP without cookie. Share the same table between both accesses.
8660 backend http
8661 mode http
8662 balance roundrobin
8663 stick on src table https
8664 cookie SRV insert indirect nocache
8665 server s1 192.168.1.1:80 cookie s1
8666 server s2 192.168.1.1:80 cookie s2
8667
8668 backend https
8669 mode tcp
8670 balance roundrobin
8671 stick-table type ip size 200k expire 30m
8672 stick on src
8673 server s1 192.168.1.1:443
8674 server s2 192.168.1.1:443
8675
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008676 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008677
8678
8679stick store-request <pattern> [table <table>] [{if | unless} <condition>]
8680 Define a request pattern used to create an entry in a stickiness table
8681 May be used in sections : defaults | frontend | listen | backend
8682 no | no | yes | yes
8683
8684 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008685 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008686 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01008687 will be analyzed, extracted and stored in the table once a
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008688 server is selected.
8689
8690 <table> is an optional stickiness table name. If unspecified, the same
8691 backend's table is used. A stickiness table is declared using
8692 the "stick-table" statement.
8693
8694 <cond> is an optional storage condition. It makes it possible to store
8695 certain criteria only when some conditions are met (or not met).
8696 For instance, it could be used to store the source IP address
8697 except when the request passes through a known proxy, in which
8698 case we'd store a converted form of a header containing that IP
8699 address.
8700
8701 Some protocols or applications require complex stickiness rules and cannot
8702 always simply rely on cookies nor hashing. The "stick store-request" statement
8703 describes a rule to decide what to extract from the request and when to do
8704 it, in order to store it into a stickiness table for further requests to
8705 match it using the "stick match" statement. Obviously the extracted part must
8706 make sense and have a chance to be matched in a further request. Storing a
8707 client's IP address for instance often makes sense. Storing an ID found in a
8708 URL parameter also makes sense. Storing a source port will almost never make
8709 any sense because it will be randomly matched. See section 7 for a complete
8710 list of possible patterns and transformation rules.
8711
8712 The table has to be declared using the "stick-table" statement. It must be of
8713 a type compatible with the pattern. By default it is the one which is present
8714 in the same backend. It is possible to share a table with other backends by
8715 referencing it using the "table" keyword. If another table is referenced,
8716 the server's ID inside the backends are used. By default, all server IDs
8717 start at 1 in each backend, so the server ordering is enough. But in case of
8718 doubt, it is highly recommended to force server IDs using their "id" setting.
8719
8720 It is possible to restrict the conditions where a "stick store-request"
8721 statement will apply, using "if" or "unless" followed by a condition. This
8722 condition will be evaluated while parsing the request, so any criteria can be
8723 used. See section 7 for ACL based conditions.
8724
8725 There is no limit on the number of "stick store-request" statements, but
8726 there is a limit of 8 simultaneous stores per request or response. This
8727 makes it possible to store up to 8 criteria, all extracted from either the
8728 request or the response, regardless of the number of rules. Only the 8 first
8729 ones which match will be kept. Using this, it is possible to feed multiple
8730 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01008731 another protocol or access method. Using multiple store-request rules with
8732 the same table is possible and may be used to find the best criterion to rely
8733 on, by arranging the rules by decreasing preference order. Only the first
8734 extracted criterion for a given table will be stored. All subsequent store-
8735 request rules referencing the same table will be skipped and their ACLs will
8736 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008737
8738 The "store-request" rules are evaluated once the server connection has been
8739 established, so that the table will contain the real server that processed
8740 the request.
8741
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008742 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8743 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008744 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008745
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008746 Example :
8747 # forward SMTP users to the same server they just used for POP in the
8748 # last 30 minutes
8749 backend pop
8750 mode tcp
8751 balance roundrobin
8752 stick store-request src
8753 stick-table type ip size 200k expire 30m
8754 server s1 192.168.1.1:110
8755 server s2 192.168.1.1:110
8756
8757 backend smtp
8758 mode tcp
8759 balance roundrobin
8760 stick match src table pop
8761 server s1 192.168.1.1:25
8762 server s2 192.168.1.1:25
8763
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008764 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02008765 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008766
8767
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008768stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02008769 size <size> [expire <expire>] [nopurge] [peers <peersect>]
8770 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +08008771 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008772 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02008773 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008774
8775 Arguments :
8776 ip a table declared with "type ip" will only store IPv4 addresses.
8777 This form is very compact (about 50 bytes per entry) and allows
8778 very fast entry lookup and stores with almost no overhead. This
8779 is mainly used to store client source IP addresses.
8780
David du Colombier9a6d3c92011-03-17 10:40:24 +01008781 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
8782 This form is very compact (about 60 bytes per entry) and allows
8783 very fast entry lookup and stores with almost no overhead. This
8784 is mainly used to store client source IP addresses.
8785
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008786 integer a table declared with "type integer" will store 32bit integers
8787 which can represent a client identifier found in a request for
8788 instance.
8789
8790 string a table declared with "type string" will store substrings of up
8791 to <len> characters. If the string provided by the pattern
8792 extractor is larger than <len>, it will be truncated before
8793 being stored. During matching, at most <len> characters will be
8794 compared between the string in the table and the extracted
8795 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008796 to 32 characters.
8797
8798 binary a table declared with "type binary" will store binary blocks
8799 of <len> bytes. If the block provided by the pattern
8800 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +02008801 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008802 is shorter than <len>, it will be padded by 0. When not
8803 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008804
8805 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008806 "string" type table (See type "string" above). Or the number
8807 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008808 changing this parameter as memory usage will proportionally
8809 increase.
8810
8811 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01008812 value directly impacts memory usage. Count approximately
8813 50 bytes per entry, plus the size of a string if any. The size
8814 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008815
8816 [nopurge] indicates that we refuse to purge older entries when the table
8817 is full. When not specified and the table is full when haproxy
8818 wants to store an entry in it, it will flush a few of the oldest
8819 entries in order to release some space for the new ones. This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01008820 most often the desired behavior. In some specific cases, it
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008821 be desirable to refuse new entries instead of purging the older
8822 ones. That may be the case when the amount of data to store is
8823 far above the hardware limits and we prefer not to offer access
8824 to new clients than to reject the ones already connected. When
8825 using this parameter, be sure to properly set the "expire"
8826 parameter (see below).
8827
Emeric Brunf099e792010-09-27 12:05:28 +02008828 <peersect> is the name of the peers section to use for replication. Entries
8829 which associate keys to server IDs are kept synchronized with
8830 the remote peers declared in this section. All entries are also
8831 automatically learned from the local peer (old process) during a
8832 soft restart.
8833
Willy Tarreau1abc6732015-05-01 19:21:02 +02008834 NOTE : each peers section may be referenced only by tables
8835 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008836
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008837 <expire> defines the maximum duration of an entry in the table since it
8838 was last created, refreshed or matched. The expiration delay is
8839 defined using the standard time format, similarly as the various
8840 timeouts. The maximum duration is slightly above 24 days. See
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03008841 section 2.4 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02008842 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008843 be removed once full. Be sure not to use the "nopurge" parameter
8844 if not expiration delay is specified.
8845
Willy Tarreau08d5f982010-06-06 13:34:54 +02008846 <data_type> is used to store additional information in the stick-table. This
8847 may be used by ACLs in order to control various criteria related
8848 to the activity of the client matching the stick-table. For each
8849 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02008850 that the additional data can fit. Several data types may be
8851 stored with an entry. Multiple data types may be specified after
8852 the "store" keyword, as a comma-separated list. Alternatively,
8853 it is possible to repeat the "store" keyword followed by one or
8854 several data types. Except for the "server_id" type which is
8855 automatically detected and enabled, all data types must be
8856 explicitly declared to be stored. If an ACL references a data
8857 type which is not stored, the ACL will simply not match. Some
8858 data types require an argument which must be passed just after
8859 the type between parenthesis. See below for the supported data
8860 types and their arguments.
8861
8862 The data types that can be stored with an entry are the following :
8863 - server_id : this is an integer which holds the numeric ID of the server a
8864 request was assigned to. It is used by the "stick match", "stick store",
8865 and "stick on" rules. It is automatically enabled when referenced.
8866
8867 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
8868 integer which may be used for anything. Most of the time it will be used
8869 to put a special tag on some entries, for instance to note that a
Davor Ocelice9ed2812017-12-25 17:49:28 +01008870 specific behavior was detected and must be known for future matches.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008871
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008872 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
8873 over a period. It is a positive 32-bit integer integer which may be used
8874 for anything. Just like <gpc0>, it counts events, but instead of keeping
Davor Ocelice9ed2812017-12-25 17:49:28 +01008875 a cumulative number, it maintains the rate at which the counter is
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008876 incremented. Most of the time it will be used to measure the frequency of
Davor Ocelice9ed2812017-12-25 17:49:28 +01008877 occurrence of certain events (e.g. requests to a specific URL).
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008878
Frédéric Lécaille6778b272018-01-29 15:22:53 +01008879 - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
8880 integer which may be used for anything. Most of the time it will be used
8881 to put a special tag on some entries, for instance to note that a
8882 specific behavior was detected and must be known for future matches.
8883
8884 - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
8885 over a period. It is a positive 32-bit integer integer which may be used
8886 for anything. Just like <gpc1>, it counts events, but instead of keeping
8887 a cumulative number, it maintains the rate at which the counter is
8888 incremented. Most of the time it will be used to measure the frequency of
8889 occurrence of certain events (e.g. requests to a specific URL).
8890
Willy Tarreauc9705a12010-07-27 20:05:50 +02008891 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
8892 the absolute number of connections received from clients which matched
8893 this entry. It does not mean the connections were accepted, just that
8894 they were received.
8895
8896 - conn_cur : Current Connections. It is a positive 32-bit integer which
8897 stores the concurrent connection counts for the entry. It is incremented
8898 once an incoming connection matches the entry, and decremented once the
8899 connection leaves. That way it is possible to know at any time the exact
8900 number of concurrent connections for an entry.
8901
8902 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8903 integer parameter <period> which indicates in milliseconds the length
8904 of the period over which the average is measured. It reports the average
8905 incoming connection rate over that period, in connections per period. The
8906 result is an integer which can be matched using ACLs.
8907
8908 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
8909 the absolute number of sessions received from clients which matched this
8910 entry. A session is a connection that was accepted by the layer 4 rules.
8911
8912 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8913 integer parameter <period> which indicates in milliseconds the length
8914 of the period over which the average is measured. It reports the average
8915 incoming session rate over that period, in sessions per period. The
8916 result is an integer which can be matched using ACLs.
8917
8918 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
8919 counts the absolute number of HTTP requests received from clients which
8920 matched this entry. It does not matter whether they are valid requests or
8921 not. Note that this is different from sessions when keep-alive is used on
8922 the client side.
8923
8924 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8925 integer parameter <period> which indicates in milliseconds the length
8926 of the period over which the average is measured. It reports the average
8927 HTTP request rate over that period, in requests per period. The result is
8928 an integer which can be matched using ACLs. It does not matter whether
8929 they are valid requests or not. Note that this is different from sessions
8930 when keep-alive is used on the client side.
8931
8932 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
8933 counts the absolute number of HTTP requests errors induced by clients
8934 which matched this entry. Errors are counted on invalid and truncated
8935 requests, as well as on denied or tarpitted requests, and on failed
8936 authentications. If the server responds with 4xx, then the request is
8937 also counted as an error since it's an error triggered by the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01008938 (e.g. vulnerability scan).
Willy Tarreauc9705a12010-07-27 20:05:50 +02008939
8940 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8941 integer parameter <period> which indicates in milliseconds the length
8942 of the period over which the average is measured. It reports the average
8943 HTTP request error rate over that period, in requests per period (see
8944 http_err_cnt above for what is accounted as an error). The result is an
8945 integer which can be matched using ACLs.
8946
8947 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +01008948 integer which counts the cumulative number of bytes received from clients
Willy Tarreauc9705a12010-07-27 20:05:50 +02008949 which matched this entry. Headers are included in the count. This may be
8950 used to limit abuse of upload features on photo or video servers.
8951
8952 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8953 integer parameter <period> which indicates in milliseconds the length
8954 of the period over which the average is measured. It reports the average
8955 incoming bytes rate over that period, in bytes per period. It may be used
8956 to detect users which upload too much and too fast. Warning: with large
8957 uploads, it is possible that the amount of uploaded data will be counted
8958 once upon termination, thus causing spikes in the average transfer speed
8959 instead of having a smooth one. This may partially be smoothed with
8960 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
8961 recommended for better fairness.
8962
8963 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +01008964 integer which counts the cumulative number of bytes sent to clients which
Willy Tarreauc9705a12010-07-27 20:05:50 +02008965 matched this entry. Headers are included in the count. This may be used
8966 to limit abuse of bots sucking the whole site.
8967
8968 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
8969 an integer parameter <period> which indicates in milliseconds the length
8970 of the period over which the average is measured. It reports the average
8971 outgoing bytes rate over that period, in bytes per period. It may be used
8972 to detect users which download too much and too fast. Warning: with large
8973 transfers, it is possible that the amount of transferred data will be
8974 counted once upon termination, thus causing spikes in the average
8975 transfer speed instead of having a smooth one. This may partially be
8976 smoothed with "option contstats" though this is not perfect yet. Use of
8977 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02008978
Willy Tarreauc00cdc22010-06-06 16:48:26 +02008979 There is only one stick-table per proxy. At the moment of writing this doc,
8980 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008981 to be required, simply create a dummy backend with a stick-table in it and
8982 reference it.
8983
8984 It is important to understand that stickiness based on learning information
8985 has some limitations, including the fact that all learned associations are
Baptiste Assmann123ff042016-03-06 23:29:28 +01008986 lost upon restart unless peers are properly configured to transfer such
8987 information upon restart (recommended). In general it can be good as a
8988 complement but not always as an exclusive stickiness.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008989
Willy Tarreauc9705a12010-07-27 20:05:50 +02008990 Last, memory requirements may be important when storing many data types.
8991 Indeed, storing all indicators above at once in each entry requires 116 bytes
8992 per entry, or 116 MB for a 1-million entries table. This is definitely not
8993 something that can be ignored.
8994
8995 Example:
8996 # Keep track of counters of up to 1 million IP addresses over 5 minutes
8997 # and store a general purpose counter and the average connection rate
8998 # computed over a sliding window of 30 seconds.
8999 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
9000
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03009001 See also : "stick match", "stick on", "stick store-request", section 2.4
David du Colombiera13d1b92011-03-17 10:40:22 +01009002 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009003
9004
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009005stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Baptiste Assmann2f2d2ec2016-03-06 23:27:24 +01009006 Define a response pattern used to create an entry in a stickiness table
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009007 May be used in sections : defaults | frontend | listen | backend
9008 no | no | yes | yes
9009
9010 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009011 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009012 describes what elements of the response or connection will
Davor Ocelice9ed2812017-12-25 17:49:28 +01009013 be analyzed, extracted and stored in the table once a
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009014 server is selected.
9015
9016 <table> is an optional stickiness table name. If unspecified, the same
9017 backend's table is used. A stickiness table is declared using
9018 the "stick-table" statement.
9019
9020 <cond> is an optional storage condition. It makes it possible to store
9021 certain criteria only when some conditions are met (or not met).
9022 For instance, it could be used to store the SSL session ID only
9023 when the response is a SSL server hello.
9024
9025 Some protocols or applications require complex stickiness rules and cannot
9026 always simply rely on cookies nor hashing. The "stick store-response"
9027 statement describes a rule to decide what to extract from the response and
9028 when to do it, in order to store it into a stickiness table for further
9029 requests to match it using the "stick match" statement. Obviously the
9030 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009031 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009032 See section 7 for a complete list of possible patterns and transformation
9033 rules.
9034
9035 The table has to be declared using the "stick-table" statement. It must be of
9036 a type compatible with the pattern. By default it is the one which is present
9037 in the same backend. It is possible to share a table with other backends by
9038 referencing it using the "table" keyword. If another table is referenced,
9039 the server's ID inside the backends are used. By default, all server IDs
9040 start at 1 in each backend, so the server ordering is enough. But in case of
9041 doubt, it is highly recommended to force server IDs using their "id" setting.
9042
9043 It is possible to restrict the conditions where a "stick store-response"
9044 statement will apply, using "if" or "unless" followed by a condition. This
9045 condition will be evaluated while parsing the response, so any criteria can
9046 be used. See section 7 for ACL based conditions.
9047
9048 There is no limit on the number of "stick store-response" statements, but
9049 there is a limit of 8 simultaneous stores per request or response. This
9050 makes it possible to store up to 8 criteria, all extracted from either the
9051 request or the response, regardless of the number of rules. Only the 8 first
9052 ones which match will be kept. Using this, it is possible to feed multiple
9053 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01009054 another protocol or access method. Using multiple store-response rules with
9055 the same table is possible and may be used to find the best criterion to rely
9056 on, by arranging the rules by decreasing preference order. Only the first
9057 extracted criterion for a given table will be stored. All subsequent store-
9058 response rules referencing the same table will be skipped and their ACLs will
9059 not be evaluated. However, even if a store-request rule references a table, a
9060 store-response rule may also use the same table. This means that each table
9061 may learn exactly one element from the request and one element from the
9062 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009063
9064 The table will contain the real server that processed the request.
9065
9066 Example :
9067 # Learn SSL session ID from both request and response and create affinity.
9068 backend https
9069 mode tcp
9070 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02009071 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009072 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009073
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009074 acl clienthello req_ssl_hello_type 1
9075 acl serverhello rep_ssl_hello_type 2
9076
9077 # use tcp content accepts to detects ssl client and server hello.
9078 tcp-request inspect-delay 5s
9079 tcp-request content accept if clienthello
9080
9081 # no timeout on response inspect delay by default.
9082 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009083
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009084 # SSL session ID (SSLID) may be present on a client or server hello.
9085 # Its length is coded on 1 byte at offset 43 and its value starts
9086 # at offset 44.
9087
9088 # Match and learn on request if client hello.
9089 stick on payload_lv(43,1) if clienthello
9090
9091 # Learn on response if server hello.
9092 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02009093
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009094 server s1 192.168.1.1:443
9095 server s2 192.168.1.1:443
9096
9097 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
9098 extraction.
9099
9100
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009101tcp-check connect [params*]
9102 Opens a new connection
9103 May be used in sections: defaults | frontend | listen | backend
9104 no | no | yes | yes
9105
9106 When an application lies on more than a single TCP port or when HAProxy
9107 load-balance many services in a single backend, it makes sense to probe all
9108 the services individually before considering a server as operational.
9109
9110 When there are no TCP port configured on the server line neither server port
9111 directive, then the 'tcp-check connect port <port>' must be the first step
9112 of the sequence.
9113
9114 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
9115 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
9116 do.
9117
9118 Parameters :
9119 They are optional and can be used to describe how HAProxy should open and
9120 use the TCP connection.
9121
9122 port if not set, check port or server port is used.
9123 It tells HAProxy where to open the connection to.
9124 <port> must be a valid TCP port source integer, from 1 to 65535.
9125
9126 send-proxy send a PROXY protocol string
9127
9128 ssl opens a ciphered connection
9129
9130 Examples:
9131 # check HTTP and HTTPs services on a server.
9132 # first open port 80 thanks to server line port directive, then
9133 # tcp-check opens port 443, ciphered and run a request on it:
9134 option tcp-check
9135 tcp-check connect
9136 tcp-check send GET\ /\ HTTP/1.0\r\n
9137 tcp-check send Host:\ haproxy.1wt.eu\r\n
9138 tcp-check send \r\n
9139 tcp-check expect rstring (2..|3..)
9140 tcp-check connect port 443 ssl
9141 tcp-check send GET\ /\ HTTP/1.0\r\n
9142 tcp-check send Host:\ haproxy.1wt.eu\r\n
9143 tcp-check send \r\n
9144 tcp-check expect rstring (2..|3..)
9145 server www 10.0.0.1 check port 80
9146
9147 # check both POP and IMAP from a single server:
9148 option tcp-check
9149 tcp-check connect port 110
9150 tcp-check expect string +OK\ POP3\ ready
9151 tcp-check connect port 143
9152 tcp-check expect string *\ OK\ IMAP4\ ready
9153 server mail 10.0.0.1 check
9154
9155 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
9156
9157
9158tcp-check expect [!] <match> <pattern>
Davor Ocelice9ed2812017-12-25 17:49:28 +01009159 Specify data to be collected and analyzed during a generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009160 May be used in sections: defaults | frontend | listen | backend
9161 no | no | yes | yes
9162
9163 Arguments :
9164 <match> is a keyword indicating how to look for a specific pattern in the
9165 response. The keyword may be one of "string", "rstring" or
9166 binary.
9167 The keyword may be preceded by an exclamation mark ("!") to negate
9168 the match. Spaces are allowed between the exclamation mark and the
9169 keyword. See below for more details on the supported keywords.
9170
9171 <pattern> is the pattern to look for. It may be a string or a regular
9172 expression. If the pattern contains spaces, they must be escaped
9173 with the usual backslash ('\').
9174 If the match is set to binary, then the pattern must be passed as
Davor Ocelice9ed2812017-12-25 17:49:28 +01009175 a series of hexadecimal digits in an even number. Each sequence of
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009176 two digits will represent a byte. The hexadecimal digits may be
9177 used upper or lower case.
9178
9179
9180 The available matches are intentionally similar to their http-check cousins :
9181
9182 string <string> : test the exact string matches in the response buffer.
9183 A health check response will be considered valid if the
9184 response's buffer contains this exact string. If the
9185 "string" keyword is prefixed with "!", then the response
9186 will be considered invalid if the body contains this
9187 string. This can be used to look for a mandatory pattern
9188 in a protocol response, or to detect a failure when a
9189 specific error appears in a protocol banner.
9190
9191 rstring <regex> : test a regular expression on the response buffer.
9192 A health check response will be considered valid if the
9193 response's buffer matches this expression. If the
9194 "rstring" keyword is prefixed with "!", then the response
9195 will be considered invalid if the body matches the
9196 expression.
9197
9198 binary <hexstring> : test the exact string in its hexadecimal form matches
9199 in the response buffer. A health check response will
9200 be considered valid if the response's buffer contains
9201 this exact hexadecimal string.
9202 Purpose is to match data on binary protocols.
9203
9204 It is important to note that the responses will be limited to a certain size
9205 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
9206 Thus, too large responses may not contain the mandatory pattern when using
9207 "string", "rstring" or binary. If a large response is absolutely required, it
9208 is possible to change the default max size by setting the global variable.
9209 However, it is worth keeping in mind that parsing very large responses can
9210 waste some CPU cycles, especially when regular expressions are used, and that
9211 it is always better to focus the checks on smaller resources. Also, in its
9212 current state, the check will not find any string nor regex past a null
9213 character in the response. Similarly it is not possible to request matching
9214 the null character.
9215
9216 Examples :
9217 # perform a POP check
9218 option tcp-check
9219 tcp-check expect string +OK\ POP3\ ready
9220
9221 # perform an IMAP check
9222 option tcp-check
9223 tcp-check expect string *\ OK\ IMAP4\ ready
9224
9225 # look for the redis master server
9226 option tcp-check
9227 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02009228 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009229 tcp-check send info\ replication\r\n
9230 tcp-check expect string role:master
9231 tcp-check send QUIT\r\n
9232 tcp-check expect string +OK
9233
9234
9235 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
9236 "tcp-check send-binary", "http-check expect", tune.chksize
9237
9238
9239tcp-check send <data>
9240 Specify a string to be sent as a question during a generic health check
9241 May be used in sections: defaults | frontend | listen | backend
9242 no | no | yes | yes
9243
9244 <data> : the data to be sent as a question during a generic health check
9245 session. For now, <data> must be a string.
9246
9247 Examples :
9248 # look for the redis master server
9249 option tcp-check
9250 tcp-check send info\ replication\r\n
9251 tcp-check expect string role:master
9252
9253 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
9254 "tcp-check send-binary", tune.chksize
9255
9256
Davor Ocelice9ed2812017-12-25 17:49:28 +01009257tcp-check send-binary <hexstring>
9258 Specify a hex digits string to be sent as a binary question during a raw
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009259 tcp health check
9260 May be used in sections: defaults | frontend | listen | backend
9261 no | no | yes | yes
9262
9263 <data> : the data to be sent as a question during a generic health check
9264 session. For now, <data> must be a string.
Davor Ocelice9ed2812017-12-25 17:49:28 +01009265 <hexstring> : test the exact string in its hexadecimal form matches in the
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009266 response buffer. A health check response will be considered
9267 valid if the response's buffer contains this exact
9268 hexadecimal string.
9269 Purpose is to send binary data to ask on binary protocols.
9270
9271 Examples :
9272 # redis check in binary
9273 option tcp-check
9274 tcp-check send-binary 50494e470d0a # PING\r\n
9275 tcp-check expect binary 2b504F4e47 # +PONG
9276
9277
9278 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
9279 "tcp-check send", tune.chksize
9280
9281
Willy Tarreaue9656522010-08-17 15:40:09 +02009282tcp-request connection <action> [{if | unless} <condition>]
9283 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02009284 May be used in sections : defaults | frontend | listen | backend
9285 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02009286 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009287 <action> defines the action to perform if the condition applies. See
9288 below.
Willy Tarreau1a687942010-05-23 22:40:30 +02009289
Willy Tarreaue9656522010-08-17 15:40:09 +02009290 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009291
9292 Immediately after acceptance of a new incoming connection, it is possible to
9293 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02009294 or dropped or have its counters tracked. Those conditions cannot make use of
9295 any data contents because the connection has not been read from yet, and the
9296 buffers are not yet allocated. This is used to selectively and very quickly
9297 accept or drop connections from various sources with a very low overhead. If
9298 some contents need to be inspected in order to take the decision, the
9299 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009300
Willy Tarreaue9656522010-08-17 15:40:09 +02009301 The "tcp-request connection" rules are evaluated in their exact declaration
9302 order. If no rule matches or if there is no rule, the default action is to
9303 accept the incoming connection. There is no specific limit to the number of
9304 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009305
Willy Tarreaua9083d02015-05-08 15:27:59 +02009306 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +02009307 - accept :
9308 accepts the connection if the condition is true (when used with "if")
9309 or false (when used with "unless"). The first such rule executed ends
9310 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009311
Willy Tarreaue9656522010-08-17 15:40:09 +02009312 - reject :
9313 rejects the connection if the condition is true (when used with "if")
9314 or false (when used with "unless"). The first such rule executed ends
9315 the rules evaluation. Rejected connections do not even become a
9316 session, which is why they are accounted separately for in the stats,
9317 as "denied connections". They are not considered for the session
9318 rate-limit and are not logged either. The reason is that these rules
9319 should only be used to filter extremely high connection rates such as
9320 the ones encountered during a massive DDoS attack. Under these extreme
9321 conditions, the simple action of logging each event would make the
9322 system collapse and would considerably lower the filtering capacity. If
9323 logging is absolutely desired, then "tcp-request content" rules should
Willy Tarreau4f614292016-10-21 17:49:36 +02009324 be used instead, as "tcp-request session" rules will not log either.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009325
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009326 - expect-proxy layer4 :
9327 configures the client-facing connection to receive a PROXY protocol
9328 header before any byte is read from the socket. This is equivalent to
9329 having the "accept-proxy" keyword on the "bind" line, except that using
9330 the TCP rule allows the PROXY protocol to be accepted only for certain
9331 IP address ranges using an ACL. This is convenient when multiple layers
9332 of load balancers are passed through by traffic coming from public
9333 hosts.
9334
Bertrand Jacquin90759682016-06-06 15:35:39 +01009335 - expect-netscaler-cip layer4 :
9336 configures the client-facing connection to receive a NetScaler Client
9337 IP insertion protocol header before any byte is read from the socket.
9338 This is equivalent to having the "accept-netscaler-cip" keyword on the
9339 "bind" line, except that using the TCP rule allows the PROXY protocol
9340 to be accepted only for certain IP address ranges using an ACL. This
9341 is convenient when multiple layers of load balancers are passed
9342 through by traffic coming from public hosts.
9343
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009344 - capture <sample> len <length> :
9345 This only applies to "tcp-request content" rules. It captures sample
9346 expression <sample> from the request buffer, and converts it to a
9347 string of at most <len> characters. The resulting string is stored into
9348 the next request "capture" slot, so it will possibly appear next to
9349 some captured HTTP headers. It will then automatically appear in the
9350 logs, and it will be possible to extract it using sample fetch rules to
9351 feed it into headers or anything. The length should be limited given
9352 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +02009353 session life. Please check section 7.3 (Fetching samples) and "capture
9354 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009355
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009356 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +02009357 enables tracking of sticky counters from current connection. These
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +02009358 rules do not stop evaluation and do not change default action. The
9359 number of counters that may be simultaneously tracked by the same
9360 connection is set in MAX_SESS_STKCTR at build time (reported in
9361 haproxy -vv) whichs defaults to 3, so the track-sc number is between 0
9362 and (MAX_SESS_STCKTR-1). The first "track-sc0" rule executed enables
9363 tracking of the counters of the specified table as the first set. The
9364 first "track-sc1" rule executed enables tracking of the counters of the
9365 specified table as the second set. The first "track-sc2" rule executed
9366 enables tracking of the counters of the specified table as the third
9367 set. It is a recommended practice to use the first set of counters for
9368 the per-frontend counters and the second set for the per-backend ones.
9369 But this is just a guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009370
Willy Tarreaue9656522010-08-17 15:40:09 +02009371 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009372 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +02009373 in section 7.3. It describes what elements of the incoming
Davor Ocelice9ed2812017-12-25 17:49:28 +01009374 request or connection will be analyzed, extracted, combined,
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009375 and used to select which table entry to update the counters.
9376 Note that "tcp-request connection" cannot use content-based
9377 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009378
Willy Tarreaue9656522010-08-17 15:40:09 +02009379 <table> is an optional table to be used instead of the default one,
9380 which is the stick-table declared in the current proxy. All
9381 the counters for the matches and updates for the key will
9382 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009383
Willy Tarreaue9656522010-08-17 15:40:09 +02009384 Once a "track-sc*" rule is executed, the key is looked up in the table
9385 and if it is not found, an entry is allocated for it. Then a pointer to
9386 that entry is kept during all the session's life, and this entry's
9387 counters are updated as often as possible, every time the session's
9388 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009389 Counters are only updated for events that happen after the tracking has
9390 been started. For example, connection counters will not be updated when
9391 tracking layer 7 information, since the connection event happens before
9392 layer7 information is extracted.
9393
Willy Tarreaue9656522010-08-17 15:40:09 +02009394 If the entry tracks concurrent connection counters, one connection is
9395 counted for as long as the entry is tracked, and the entry will not
9396 expire during that time. Tracking counters also provides a performance
9397 advantage over just checking the keys, because only one table lookup is
9398 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009399
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009400 - sc-inc-gpc0(<sc-id>):
9401 The "sc-inc-gpc0" increments the GPC0 counter according to the sticky
9402 counter designated by <sc-id>. If an error occurs, this action silently
9403 fails and the actions evaluation continues.
9404
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009405 - sc-inc-gpc1(<sc-id>):
9406 The "sc-inc-gpc1" increments the GPC1 counter according to the sticky
9407 counter designated by <sc-id>. If an error occurs, this action silently
9408 fails and the actions evaluation continues.
9409
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009410 - sc-set-gpt0(<sc-id>) <int>:
9411 This action sets the GPT0 tag according to the sticky counter designated
9412 by <sc-id> and the value of <int>. The expected result is a boolean. If
9413 an error occurs, this action silently fails and the actions evaluation
9414 continues.
9415
William Lallemand2e785f22016-05-25 01:48:42 +02009416 - set-src <expr> :
9417 Is used to set the source IP address to the value of specified
9418 expression. Useful if you want to mask source IP for privacy.
9419 If you want to provide an IP from a HTTP header use "http-request
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02009420 set-src".
William Lallemand2e785f22016-05-25 01:48:42 +02009421
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02009422 Arguments:
9423 <expr> Is a standard HAProxy expression formed by a sample-fetch
9424 followed by some converters.
William Lallemand2e785f22016-05-25 01:48:42 +02009425
9426 Example:
William Lallemand2e785f22016-05-25 01:48:42 +02009427 tcp-request connection set-src src,ipmask(24)
9428
Willy Tarreau0c630532016-10-21 17:52:58 +02009429 When possible, set-src preserves the original source port as long as the
9430 address family allows it, otherwise the source port is set to 0.
William Lallemand2e785f22016-05-25 01:48:42 +02009431
William Lallemand44be6402016-05-25 01:51:35 +02009432 - set-src-port <expr> :
9433 Is used to set the source port address to the value of specified
9434 expression.
9435
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02009436 Arguments:
9437 <expr> Is a standard HAProxy expression formed by a sample-fetch
9438 followed by some converters.
William Lallemand44be6402016-05-25 01:51:35 +02009439
9440 Example:
William Lallemand44be6402016-05-25 01:51:35 +02009441 tcp-request connection set-src-port int(4000)
9442
Willy Tarreau0c630532016-10-21 17:52:58 +02009443 When possible, set-src-port preserves the original source address as long
9444 as the address family supports a port, otherwise it forces the source
9445 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02009446
William Lallemand13e9b0c2016-05-25 02:34:07 +02009447 - set-dst <expr> :
9448 Is used to set the destination IP address to the value of specified
9449 expression. Useful if you want to mask IP for privacy in log.
9450 If you want to provide an IP from a HTTP header use "http-request
9451 set-dst". If you want to connect to the new address/port, use
9452 '0.0.0.0:0' as a server address in the backend.
9453
9454 <expr> Is a standard HAProxy expression formed by a sample-fetch
9455 followed by some converters.
9456
9457 Example:
9458
9459 tcp-request connection set-dst dst,ipmask(24)
9460 tcp-request connection set-dst ipv4(10.0.0.1)
9461
Willy Tarreau0c630532016-10-21 17:52:58 +02009462 When possible, set-dst preserves the original destination port as long as
9463 the address family allows it, otherwise the destination port is set to 0.
9464
William Lallemand13e9b0c2016-05-25 02:34:07 +02009465 - set-dst-port <expr> :
9466 Is used to set the destination port address to the value of specified
9467 expression. If you want to connect to the new address/port, use
9468 '0.0.0.0:0' as a server address in the backend.
9469
9470
9471 <expr> Is a standard HAProxy expression formed by a sample-fetch
9472 followed by some converters.
9473
9474 Example:
9475
9476 tcp-request connection set-dst-port int(4000)
9477
Willy Tarreau0c630532016-10-21 17:52:58 +02009478 When possible, set-dst-port preserves the original destination address as
9479 long as the address family supports a port, otherwise it forces the
9480 destination address to IPv4 "0.0.0.0" before rewriting the port.
9481
Willy Tarreau2d392c22015-08-24 01:43:45 +02009482 - "silent-drop" :
9483 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +01009484 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +02009485 to prevent the client from being notified. The effect it then that the
9486 client still sees an established connection while there's none on
9487 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
9488 except that it doesn't use any local resource at all on the machine
9489 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +01009490 slow down stronger attackers. It is important to understand the impact
9491 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009492 client and HAProxy (firewalls, proxies, load balancers) will also keep
9493 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +01009494 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009495 TCP_REPAIR socket option is used to block the emission of a TCP
9496 reset. On other systems, the socket's TTL is reduced to 1 so that the
9497 TCP reset doesn't pass the first router, though it's still delivered to
9498 local networks. Do not use it unless you fully understand how it works.
9499
Willy Tarreaue9656522010-08-17 15:40:09 +02009500 Note that the "if/unless" condition is optional. If no condition is set on
9501 the action, it is simply performed unconditionally. That can be useful for
9502 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009503
Willy Tarreaue9656522010-08-17 15:40:09 +02009504 Example: accept all connections from white-listed hosts, reject too fast
9505 connection without counting them, and track accepted connections.
9506 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009507
Willy Tarreaue9656522010-08-17 15:40:09 +02009508 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009509 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009510 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009511
Willy Tarreaue9656522010-08-17 15:40:09 +02009512 Example: accept all connections from white-listed hosts, count all other
9513 connections and reject too fast ones. This results in abusive ones
9514 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009515
Willy Tarreaue9656522010-08-17 15:40:09 +02009516 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009517 tcp-request connection track-sc0 src
9518 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009519
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009520 Example: enable the PROXY protocol for traffic coming from all known proxies.
9521
9522 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
9523
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009524 See section 7 about ACL usage.
9525
Willy Tarreau4f614292016-10-21 17:49:36 +02009526 See also : "tcp-request session", "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009527
9528
Willy Tarreaue9656522010-08-17 15:40:09 +02009529tcp-request content <action> [{if | unless} <condition>]
9530 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02009531 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02009532 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02009533 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009534 <action> defines the action to perform if the condition applies. See
9535 below.
Willy Tarreau62644772008-07-16 18:36:06 +02009536
Willy Tarreaue9656522010-08-17 15:40:09 +02009537 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02009538
Davor Ocelice9ed2812017-12-25 17:49:28 +01009539 A request's contents can be analyzed at an early stage of request processing
Willy Tarreaue9656522010-08-17 15:40:09 +02009540 called "TCP content inspection". During this stage, ACL-based rules are
9541 evaluated every time the request contents are updated, until either an
9542 "accept" or a "reject" rule matches, or the TCP request inspection delay
9543 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02009544
Willy Tarreaue9656522010-08-17 15:40:09 +02009545 The first difference between these rules and "tcp-request connection" rules
9546 is that "tcp-request content" rules can make use of contents to take a
9547 decision. Most often, these decisions will consider a protocol recognition or
9548 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +01009549 both frontends and backends. In case of HTTP keep-alive with the client, all
9550 tcp-request content rules are evaluated again, so haproxy keeps a record of
9551 what sticky counters were assigned by a "tcp-request connection" versus a
9552 "tcp-request content" rule, and flushes all the content-related ones after
9553 processing an HTTP request, so that they may be evaluated again by the rules
9554 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009555 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +01009556 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +02009557
Willy Tarreaue9656522010-08-17 15:40:09 +02009558 Content-based rules are evaluated in their exact declaration order. If no
9559 rule matches or if there is no rule, the default action is to accept the
9560 contents. There is no specific limit to the number of rules which may be
9561 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02009562
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009563 Several types of actions are supported :
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009564 - accept : the request is accepted
9565 - reject : the request is rejected and the connection is closed
9566 - capture : the specified sample expression is captured
Patrick Hemmer268a7072018-05-11 12:52:31 -04009567 - set-priority-class <expr> | set-priority-offset <expr>
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009568 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009569 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009570 - sc-inc-gpc1(<sc-id>)
Thierry Fournierb9125672016-03-29 19:34:37 +02009571 - sc-set-gpt0(<sc-id>) <int>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009572 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +01009573 - unset-var(<var-name>)
Willy Tarreau2d392c22015-08-24 01:43:45 +02009574 - silent-drop
Davor Ocelice9ed2812017-12-25 17:49:28 +01009575 - send-spoe-group <engine-name> <group-name>
Willy Tarreau62644772008-07-16 18:36:06 +02009576
Willy Tarreaue9656522010-08-17 15:40:09 +02009577 They have the same meaning as their counter-parts in "tcp-request connection"
9578 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02009579
Willy Tarreauf3338342014-01-28 21:40:28 +01009580 While there is nothing mandatory about it, it is recommended to use the
9581 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
9582 content" rules in the frontend, and track-sc2 for "tcp-request content"
9583 rules in the backend, because that makes the configuration more readable
9584 and easier to troubleshoot, but this is just a guideline and all counters
9585 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +02009586
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009587 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02009588 the action, it is simply performed unconditionally. That can be useful for
9589 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02009590
Willy Tarreaue9656522010-08-17 15:40:09 +02009591 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02009592 rules, since HTTP-specific ACL matches are able to preliminarily parse the
9593 contents of a buffer before extracting the required data. If the buffered
9594 contents do not parse as a valid HTTP message, then the ACL does not match.
9595 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +01009596 processing, so there is no risk of parsing something differently. In an HTTP
9597 backend connected to from an HTTP frontend, it is guaranteed that HTTP
9598 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +02009599
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009600 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009601 are present when the rule is processed. The rule processing engine is able to
9602 wait until the inspect delay expires when the data to be tracked is not yet
9603 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009604
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009605 The "set-var" is used to set the content of a variable. The variable is
Willy Tarreau4f614292016-10-21 17:49:36 +02009606 declared inline. For "tcp-request session" rules, only session-level
9607 variables can be used, without any layer7 contents.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009608
Daniel Schneller0b547052016-03-21 20:46:57 +01009609 <var-name> The name of the variable starts with an indication about
9610 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01009611 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01009612 "sess" : the variable is shared with the whole session
9613 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009614 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01009615 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009616 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01009617 "res" : the variable is shared only during response
9618 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009619 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01009620 The name may only contain characters 'a-z', 'A-Z', '0-9',
9621 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009622
9623 <expr> Is a standard HAProxy expression formed by a sample-fetch
9624 followed by some converters.
9625
Christopher Faulet85d79c92016-11-09 16:54:56 +01009626 The "unset-var" is used to unset a variable. See above for details about
9627 <var-name>.
9628
Patrick Hemmer268a7072018-05-11 12:52:31 -04009629 The "set-priority-class" is used to set the queue priority class of the
9630 current request. The value must be a sample expression which converts to an
9631 integer in the range -2047..2047. Results outside this range will be
9632 truncated. The priority class determines the order in which queued requests
9633 are processed. Lower values have higher priority.
9634
9635 The "set-priority-offset" is used to set the queue priority timestamp offset
9636 of the current request. The value must be a sample expression which converts
9637 to an integer in the range -524287..524287. Results outside this range will be
9638 truncated. When a request is queued, it is ordered first by the priority
9639 class, then by the current timestamp adjusted by the given offset in
9640 milliseconds. Lower values have higher priority.
9641 Note that the resulting timestamp is is only tracked with enough precision for
9642 524,287ms (8m44s287ms). If the request is queued long enough to where the
9643 adjusted timestamp exceeds this value, it will be misidentified as highest
9644 priority. Thus it is important to set "timeout queue" to a value, where when
9645 combined with the offset, does not exceed this limit.
9646
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009647 The "send-spoe-group" is used to trigger sending of a group of SPOE
9648 messages. To do so, the SPOE engine used to send messages must be defined, as
9649 well as the SPOE group to send. Of course, the SPOE engine must refer to an
9650 existing SPOE filter. If not engine name is provided on the SPOE filter line,
9651 the SPOE agent name must be used.
9652
9653 <engine-name> The SPOE engine name.
9654
9655 <group-name> The SPOE group name as specified in the engine configuration.
9656
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009657 Example:
9658
9659 tcp-request content set-var(sess.my_var) src
Christopher Faulet85d79c92016-11-09 16:54:56 +01009660 tcp-request content unset-var(sess.my_var2)
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009661
Willy Tarreau62644772008-07-16 18:36:06 +02009662 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02009663 # Accept HTTP requests containing a Host header saying "example.com"
9664 # and reject everything else.
9665 acl is_host_com hdr(Host) -i example.com
9666 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02009667 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02009668 tcp-request content reject
9669
9670 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02009671 # reject SMTP connection if client speaks first
9672 tcp-request inspect-delay 30s
9673 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009674 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02009675
9676 # Forward HTTPS connection only if client speaks
9677 tcp-request inspect-delay 30s
9678 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009679 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02009680 tcp-request content reject
9681
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009682 Example:
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009683 # Track the last IP(stick-table type string) from X-Forwarded-For
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009684 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009685 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009686 # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
9687 tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009688
9689 Example:
9690 # track request counts per "base" (concatenation of Host+URL)
9691 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009692 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009693
Willy Tarreaue9656522010-08-17 15:40:09 +02009694 Example: track per-frontend and per-backend counters, block abusers at the
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009695 frontend when the backend detects abuse(and marks gpc0).
Willy Tarreaue9656522010-08-17 15:40:09 +02009696
9697 frontend http
Davor Ocelice9ed2812017-12-25 17:49:28 +01009698 # Use General Purpose Counter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +02009699 # protecting all our sites
9700 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009701 tcp-request connection track-sc0 src
9702 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +02009703 ...
9704 use_backend http_dynamic if { path_end .php }
9705
9706 backend http_dynamic
9707 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009708 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +02009709 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009710 acl click_too_fast sc1_http_req_rate gt 10
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009711 acl mark_as_abuser sc0_inc_gpc0(http) gt 0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009712 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +02009713 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02009714
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009715 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02009716
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03009717 See also : "tcp-request connection", "tcp-request session",
9718 "tcp-request inspect-delay", and "http-request".
Willy Tarreau62644772008-07-16 18:36:06 +02009719
9720
9721tcp-request inspect-delay <timeout>
9722 Set the maximum allowed time to wait for data during content inspection
9723 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02009724 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02009725 Arguments :
9726 <timeout> is the timeout value specified in milliseconds by default, but
9727 can be in any other unit if the number is suffixed by the unit,
9728 as explained at the top of this document.
9729
9730 People using haproxy primarily as a TCP relay are often worried about the
9731 risk of passing any type of protocol to a server without any analysis. In
9732 order to be able to analyze the request contents, we must first withhold
9733 the data then analyze them. This statement simply enables withholding of
9734 data for at most the specified amount of time.
9735
Willy Tarreaufb356202010-08-03 14:02:05 +02009736 TCP content inspection applies very early when a connection reaches a
9737 frontend, then very early when the connection is forwarded to a backend. This
9738 means that a connection may experience a first delay in the frontend and a
9739 second delay in the backend if both have tcp-request rules.
9740
Willy Tarreau62644772008-07-16 18:36:06 +02009741 Note that when performing content inspection, haproxy will evaluate the whole
9742 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009743 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02009744 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01009745 contents are definitive. If no delay is set, haproxy will not wait at all
9746 and will immediately apply a verdict based on the available information.
9747 Obviously this is unlikely to be very useful and might even be racy, so such
9748 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02009749
9750 As soon as a rule matches, the request is released and continues as usual. If
9751 the timeout is reached and no rule matches, the default policy will be to let
9752 it pass through unaffected.
9753
9754 For most protocols, it is enough to set it to a few seconds, as most clients
9755 send the full request immediately upon connection. Add 3 or more seconds to
9756 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01009757 to use large values, for instance to ensure that the client never talks
Davor Ocelice9ed2812017-12-25 17:49:28 +01009758 before the server (e.g. SMTP), or to wait for a client to talk before passing
9759 data to the server (e.g. SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02009760 least the inspection delay, otherwise it will expire first. If the client
9761 closes the connection or if the buffer is full, the delay immediately expires
9762 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02009763
Willy Tarreau55165fe2009-05-10 12:02:55 +02009764 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02009765 "timeout client".
9766
9767
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009768tcp-response content <action> [{if | unless} <condition>]
9769 Perform an action on a session response depending on a layer 4-7 condition
9770 May be used in sections : defaults | frontend | listen | backend
9771 no | no | yes | yes
9772 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009773 <action> defines the action to perform if the condition applies. See
9774 below.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009775
9776 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
9777
Davor Ocelice9ed2812017-12-25 17:49:28 +01009778 Response contents can be analyzed at an early stage of response processing
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009779 called "TCP content inspection". During this stage, ACL-based rules are
9780 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009781 "accept", "close" or a "reject" rule matches, or a TCP response inspection
9782 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009783
9784 Most often, these decisions will consider a protocol recognition or validity.
9785
9786 Content-based rules are evaluated in their exact declaration order. If no
9787 rule matches or if there is no rule, the default action is to accept the
9788 contents. There is no specific limit to the number of rules which may be
9789 inserted.
9790
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009791 Several types of actions are supported :
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009792 - accept :
9793 accepts the response if the condition is true (when used with "if")
9794 or false (when used with "unless"). The first such rule executed ends
9795 the rules evaluation.
9796
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009797 - close :
9798 immediately closes the connection with the server if the condition is
9799 true (when used with "if"), or false (when used with "unless"). The
9800 first such rule executed ends the rules evaluation. The main purpose of
9801 this action is to force a connection to be finished between a client
9802 and a server after an exchange when the application protocol expects
9803 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009804 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009805 protocols.
9806
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009807 - reject :
9808 rejects the response if the condition is true (when used with "if")
9809 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009810 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009811
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009812 - set-var(<var-name>) <expr>
9813 Sets a variable.
9814
Christopher Faulet85d79c92016-11-09 16:54:56 +01009815 - unset-var(<var-name>)
9816 Unsets a variable.
9817
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009818 - sc-inc-gpc0(<sc-id>):
9819 This action increments the GPC0 counter according to the sticky
9820 counter designated by <sc-id>. If an error occurs, this action fails
9821 silently and the actions evaluation continues.
9822
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009823 - sc-inc-gpc1(<sc-id>):
9824 This action increments the GPC1 counter according to the sticky
9825 counter designated by <sc-id>. If an error occurs, this action fails
9826 silently and the actions evaluation continues.
9827
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009828 - sc-set-gpt0(<sc-id>) <int> :
9829 This action sets the GPT0 tag according to the sticky counter designated
9830 by <sc-id> and the value of <int>. The expected result is a boolean. If
9831 an error occurs, this action silently fails and the actions evaluation
9832 continues.
9833
Willy Tarreau2d392c22015-08-24 01:43:45 +02009834 - "silent-drop" :
9835 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +01009836 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +02009837 to prevent the client from being notified. The effect it then that the
9838 client still sees an established connection while there's none on
9839 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
9840 except that it doesn't use any local resource at all on the machine
9841 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +01009842 slow down stronger attackers. It is important to understand the impact
9843 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009844 client and HAProxy (firewalls, proxies, load balancers) will also keep
9845 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +01009846 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009847 TCP_REPAIR socket option is used to block the emission of a TCP
9848 reset. On other systems, the socket's TTL is reduced to 1 so that the
9849 TCP reset doesn't pass the first router, though it's still delivered to
9850 local networks. Do not use it unless you fully understand how it works.
9851
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009852 - send-spoe-group <engine-name> <group-name>
9853 Send a group of SPOE messages.
9854
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009855 Note that the "if/unless" condition is optional. If no condition is set on
9856 the action, it is simply performed unconditionally. That can be useful for
9857 for changing the default action to a reject.
9858
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009859 It is perfectly possible to match layer 7 contents with "tcp-response
9860 content" rules, but then it is important to ensure that a full response has
9861 been buffered, otherwise no contents will match. In order to achieve this,
9862 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009863 period.
9864
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009865 The "set-var" is used to set the content of a variable. The variable is
9866 declared inline.
9867
Daniel Schneller0b547052016-03-21 20:46:57 +01009868 <var-name> The name of the variable starts with an indication about
9869 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01009870 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01009871 "sess" : the variable is shared with the whole session
9872 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009873 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01009874 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009875 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01009876 "res" : the variable is shared only during response
9877 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009878 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01009879 The name may only contain characters 'a-z', 'A-Z', '0-9',
9880 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009881
9882 <expr> Is a standard HAProxy expression formed by a sample-fetch
9883 followed by some converters.
9884
9885 Example:
9886
9887 tcp-request content set-var(sess.my_var) src
9888
Christopher Faulet85d79c92016-11-09 16:54:56 +01009889 The "unset-var" is used to unset a variable. See above for details about
9890 <var-name>.
9891
9892 Example:
9893
9894 tcp-request content unset-var(sess.my_var)
9895
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009896 The "send-spoe-group" is used to trigger sending of a group of SPOE
9897 messages. To do so, the SPOE engine used to send messages must be defined, as
9898 well as the SPOE group to send. Of course, the SPOE engine must refer to an
9899 existing SPOE filter. If not engine name is provided on the SPOE filter line,
9900 the SPOE agent name must be used.
9901
9902 <engine-name> The SPOE engine name.
9903
9904 <group-name> The SPOE group name as specified in the engine configuration.
9905
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009906 See section 7 about ACL usage.
9907
9908 See also : "tcp-request content", "tcp-response inspect-delay"
9909
9910
Willy Tarreau4f614292016-10-21 17:49:36 +02009911tcp-request session <action> [{if | unless} <condition>]
9912 Perform an action on a validated session depending on a layer 5 condition
9913 May be used in sections : defaults | frontend | listen | backend
9914 no | yes | yes | no
9915 Arguments :
9916 <action> defines the action to perform if the condition applies. See
9917 below.
9918
9919 <condition> is a standard layer5-only ACL-based condition (see section 7).
9920
Davor Ocelice9ed2812017-12-25 17:49:28 +01009921 Once a session is validated, (i.e. after all handshakes have been completed),
Willy Tarreau4f614292016-10-21 17:49:36 +02009922 it is possible to evaluate some conditions to decide whether this session
9923 must be accepted or dropped or have its counters tracked. Those conditions
9924 cannot make use of any data contents because no buffers are allocated yet and
9925 the processing cannot wait at this stage. The main use case it to copy some
9926 early information into variables (since variables are accessible in the
9927 session), or to keep track of some information collected after the handshake,
9928 such as SSL-level elements (SNI, ciphers, client cert's CN) or information
Davor Ocelice9ed2812017-12-25 17:49:28 +01009929 from the PROXY protocol header (e.g. track a source forwarded this way). The
Willy Tarreau4f614292016-10-21 17:49:36 +02009930 extracted information can thus be copied to a variable or tracked using
9931 "track-sc" rules. Of course it is also possible to decide to accept/reject as
9932 with other rulesets. Most operations performed here could also be performed
9933 in "tcp-request content" rules, except that in HTTP these rules are evaluated
9934 for each new request, and that might not always be acceptable. For example a
9935 rule might increment a counter on each evaluation. It would also be possible
9936 that a country is resolved by geolocation from the source IP address,
9937 assigned to a session-wide variable, then the source address rewritten from
9938 an HTTP header for all requests. If some contents need to be inspected in
9939 order to take the decision, the "tcp-request content" statements must be used
9940 instead.
9941
9942 The "tcp-request session" rules are evaluated in their exact declaration
9943 order. If no rule matches or if there is no rule, the default action is to
9944 accept the incoming session. There is no specific limit to the number of
9945 rules which may be inserted.
9946
9947 Several types of actions are supported :
9948 - accept : the request is accepted
9949 - reject : the request is rejected and the connection is closed
9950 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
9951 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009952 - sc-inc-gpc1(<sc-id>)
Willy Tarreau4f614292016-10-21 17:49:36 +02009953 - sc-set-gpt0(<sc-id>) <int>
9954 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +01009955 - unset-var(<var-name>)
Willy Tarreau4f614292016-10-21 17:49:36 +02009956 - silent-drop
9957
9958 These actions have the same meaning as their respective counter-parts in
9959 "tcp-request connection" and "tcp-request content", so please refer to these
9960 sections for a complete description.
9961
9962 Note that the "if/unless" condition is optional. If no condition is set on
9963 the action, it is simply performed unconditionally. That can be useful for
9964 "track-sc*" actions as well as for changing the default action to a reject.
9965
9966 Example: track the original source address by default, or the one advertised
9967 in the PROXY protocol header for connection coming from the local
9968 proxies. The first connection-level rule enables receipt of the
9969 PROXY protocol for these ones, the second rule tracks whatever
9970 address we decide to keep after optional decoding.
9971
9972 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
9973 tcp-request session track-sc0 src
9974
9975 Example: accept all sessions from white-listed hosts, reject too fast
9976 sessions without counting them, and track accepted sessions.
9977 This results in session rate being capped from abusive sources.
9978
9979 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
9980 tcp-request session reject if { src_sess_rate gt 10 }
9981 tcp-request session track-sc0 src
9982
9983 Example: accept all sessions from white-listed hosts, count all other
9984 sessions and reject too fast ones. This results in abusive ones
9985 being blocked as long as they don't slow down.
9986
9987 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
9988 tcp-request session track-sc0 src
9989 tcp-request session reject if { sc0_sess_rate gt 10 }
9990
9991 See section 7 about ACL usage.
9992
9993 See also : "tcp-request connection", "tcp-request content", "stick-table"
9994
9995
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009996tcp-response inspect-delay <timeout>
9997 Set the maximum allowed time to wait for a response during content inspection
9998 May be used in sections : defaults | frontend | listen | backend
9999 no | no | yes | yes
10000 Arguments :
10001 <timeout> is the timeout value specified in milliseconds by default, but
10002 can be in any other unit if the number is suffixed by the unit,
10003 as explained at the top of this document.
10004
10005 See also : "tcp-response content", "tcp-request inspect-delay".
10006
10007
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010008timeout check <timeout>
10009 Set additional check timeout, but only after a connection has been already
10010 established.
10011
10012 May be used in sections: defaults | frontend | listen | backend
10013 yes | no | yes | yes
10014 Arguments:
10015 <timeout> is the timeout value specified in milliseconds by default, but
10016 can be in any other unit if the number is suffixed by the unit,
10017 as explained at the top of this document.
10018
10019 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
10020 for check and "timeout check" as an additional read timeout. The "min" is
Davor Ocelice9ed2812017-12-25 17:49:28 +010010021 used so that people running with *very* long "timeout connect" (e.g. those
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010022 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +010010023 (Please also note that there is no valid reason to have such long connect
10024 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
10025 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010026
10027 If "timeout check" is not set haproxy uses "inter" for complete check
10028 timeout (connect + read) exactly like all <1.3.15 version.
10029
10030 In most cases check request is much simpler and faster to handle than normal
10031 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +010010032 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010033
10034 This parameter is specific to backends, but can be specified once for all in
10035 "defaults" sections. This is in fact one of the easiest solutions not to
10036 forget about it.
10037
Willy Tarreau41a340d2008-01-22 12:25:31 +010010038 See also: "timeout connect", "timeout queue", "timeout server",
10039 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010040
10041
Willy Tarreau0ba27502007-12-24 16:55:16 +010010042timeout client <timeout>
10043timeout clitimeout <timeout> (deprecated)
10044 Set the maximum inactivity time on the client side.
10045 May be used in sections : defaults | frontend | listen | backend
10046 yes | yes | yes | no
10047 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010048 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010010049 can be in any other unit if the number is suffixed by the unit,
10050 as explained at the top of this document.
10051
10052 The inactivity timeout applies when the client is expected to acknowledge or
10053 send data. In HTTP mode, this timeout is particularly important to consider
10054 during the first phase, when the client sends the request, and during the
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010010055 response while it is reading data sent by the server. That said, for the
10056 first phase, it is preferable to set the "timeout http-request" to better
10057 protect HAProxy from Slowloris like attacks. The value is specified in
10058 milliseconds by default, but can be in any other unit if the number is
Willy Tarreau0ba27502007-12-24 16:55:16 +010010059 suffixed by the unit, as specified at the top of this document. In TCP mode
10060 (and to a lesser extent, in HTTP mode), it is highly recommended that the
10061 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010062 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +010010063 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +010010064 (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
10065 sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +020010066 which overrides "timeout client" and "timeout server" for tunnels, as well as
10067 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010068
10069 This parameter is specific to frontends, but can be specified once for all in
10070 "defaults" sections. This is in fact one of the easiest solutions not to
10071 forget about it. An unspecified timeout results in an infinite timeout, which
10072 is not recommended. Such a usage is accepted and works but reports a warning
10073 during startup because it may results in accumulation of expired sessions in
10074 the system if the system's timeouts are not configured either.
10075
Willy Tarreau95c4e142017-11-26 12:18:55 +010010076 This also applies to HTTP/2 connections, which will be closed with GOAWAY.
Lukas Tribus75df9d72017-11-24 19:05:12 +010010077
Willy Tarreau0ba27502007-12-24 16:55:16 +010010078 This parameter replaces the old, deprecated "clitimeout". It is recommended
10079 to use it to write new configurations. The form "timeout clitimeout" is
10080 provided only by backwards compatibility but its use is strongly discouraged.
10081
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010010082 See also : "clitimeout", "timeout server", "timeout tunnel",
10083 "timeout http-request".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010084
10085
Willy Tarreau05cdd962014-05-10 14:30:07 +020010086timeout client-fin <timeout>
10087 Set the inactivity timeout on the client side for half-closed connections.
10088 May be used in sections : defaults | frontend | listen | backend
10089 yes | yes | yes | no
10090 Arguments :
10091 <timeout> is the timeout value specified in milliseconds by default, but
10092 can be in any other unit if the number is suffixed by the unit,
10093 as explained at the top of this document.
10094
10095 The inactivity timeout applies when the client is expected to acknowledge or
10096 send data while one direction is already shut down. This timeout is different
10097 from "timeout client" in that it only applies to connections which are closed
10098 in one direction. This is particularly useful to avoid keeping connections in
10099 FIN_WAIT state for too long when clients do not disconnect cleanly. This
10100 problem is particularly common long connections such as RDP or WebSocket.
10101 Note that this timeout can override "timeout tunnel" when a connection shuts
Willy Tarreau599391a2017-11-24 10:16:00 +010010102 down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
10103 frame was sent, often indicating an expectation that the connection quickly
10104 ends.
Willy Tarreau05cdd962014-05-10 14:30:07 +020010105
10106 This parameter is specific to frontends, but can be specified once for all in
10107 "defaults" sections. By default it is not set, so half-closed connections
10108 will use the other timeouts (timeout.client or timeout.tunnel).
10109
10110 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
10111
10112
Willy Tarreau0ba27502007-12-24 16:55:16 +010010113timeout connect <timeout>
10114timeout contimeout <timeout> (deprecated)
10115 Set the maximum time to wait for a connection attempt to a server to succeed.
10116 May be used in sections : defaults | frontend | listen | backend
10117 yes | no | yes | yes
10118 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010119 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010010120 can be in any other unit if the number is suffixed by the unit,
10121 as explained at the top of this document.
10122
10123 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010124 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +010010125 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +010010126 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010127 connect timeout also presets both queue and tarpit timeouts to the same value
10128 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010129
10130 This parameter is specific to backends, but can be specified once for all in
10131 "defaults" sections. This is in fact one of the easiest solutions not to
10132 forget about it. An unspecified timeout results in an infinite timeout, which
10133 is not recommended. Such a usage is accepted and works but reports a warning
10134 during startup because it may results in accumulation of failed sessions in
10135 the system if the system's timeouts are not configured either.
10136
10137 This parameter replaces the old, deprecated "contimeout". It is recommended
10138 to use it to write new configurations. The form "timeout contimeout" is
10139 provided only by backwards compatibility but its use is strongly discouraged.
10140
Willy Tarreau41a340d2008-01-22 12:25:31 +010010141 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
10142 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010143
10144
Willy Tarreaub16a5742010-01-10 14:46:16 +010010145timeout http-keep-alive <timeout>
10146 Set the maximum allowed time to wait for a new HTTP request to appear
10147 May be used in sections : defaults | frontend | listen | backend
10148 yes | yes | yes | yes
10149 Arguments :
10150 <timeout> is the timeout value specified in milliseconds by default, but
10151 can be in any other unit if the number is suffixed by the unit,
10152 as explained at the top of this document.
10153
10154 By default, the time to wait for a new request in case of keep-alive is set
10155 by "timeout http-request". However this is not always convenient because some
10156 people want very short keep-alive timeouts in order to release connections
10157 faster, and others prefer to have larger ones but still have short timeouts
10158 once the request has started to present itself.
10159
10160 The "http-keep-alive" timeout covers these needs. It will define how long to
10161 wait for a new HTTP request to start coming after a response was sent. Once
10162 the first byte of request has been seen, the "http-request" timeout is used
10163 to wait for the complete request to come. Note that empty lines prior to a
10164 new request do not refresh the timeout and are not counted as a new request.
10165
10166 There is also another difference between the two timeouts : when a connection
10167 expires during timeout http-keep-alive, no error is returned, the connection
10168 just closes. If the connection expires in "http-request" while waiting for a
10169 connection to complete, a HTTP 408 error is returned.
10170
10171 In general it is optimal to set this value to a few tens to hundreds of
10172 milliseconds, to allow users to fetch all objects of a page at once but
Davor Ocelice9ed2812017-12-25 17:49:28 +010010173 without waiting for further clicks. Also, if set to a very small value (e.g.
Willy Tarreaub16a5742010-01-10 14:46:16 +010010174 1 millisecond) it will probably only accept pipelined requests but not the
10175 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +020010176 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +010010177
10178 If this parameter is not set, the "http-request" timeout applies, and if both
10179 are not set, "timeout client" still applies at the lower level. It should be
10180 set in the frontend to take effect, unless the frontend is in TCP mode, in
10181 which case the HTTP backend's timeout will be used.
10182
Willy Tarreau95c4e142017-11-26 12:18:55 +010010183 When using HTTP/2 "timeout client" is applied instead. This is so we can keep
10184 using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2
Lukas Tribus75df9d72017-11-24 19:05:12 +010010185 (where we only have one connection per client and a connection setup).
10186
Willy Tarreaub16a5742010-01-10 14:46:16 +010010187 See also : "timeout http-request", "timeout client".
10188
10189
Willy Tarreau036fae02008-01-06 13:24:40 +010010190timeout http-request <timeout>
10191 Set the maximum allowed time to wait for a complete HTTP request
10192 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010193 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +010010194 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010195 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +010010196 can be in any other unit if the number is suffixed by the unit,
10197 as explained at the top of this document.
10198
10199 In order to offer DoS protection, it may be required to lower the maximum
10200 accepted time to receive a complete HTTP request without affecting the client
10201 timeout. This helps protecting against established connections on which
10202 nothing is sent. The client timeout cannot offer a good protection against
10203 this abuse because it is an inactivity timeout, which means that if the
10204 attacker sends one character every now and then, the timeout will not
10205 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +020010206 types, the request will be aborted if it does not complete in time. When the
10207 timeout expires, an HTTP 408 response is sent to the client to inform it
10208 about the problem, and the connection is closed. The logs will report
10209 termination codes "cR". Some recent browsers are having problems with this
Davor Ocelice9ed2812017-12-25 17:49:28 +010010210 standard, well-documented behavior, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +020010211 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
10212 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +010010213
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010214 By default, this timeout only applies to the header part of the request,
10215 and not to any data. As soon as the empty line is received, this timeout is
10216 not used anymore. When combined with "option http-buffer-request", this
10217 timeout also applies to the body of the request..
10218 It is used again on keep-alive connections to wait for a second
Willy Tarreaub16a5742010-01-10 14:46:16 +010010219 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +010010220
10221 Generally it is enough to set it to a few seconds, as most clients send the
10222 full request immediately upon connection. Add 3 or more seconds to cover TCP
Davor Ocelice9ed2812017-12-25 17:49:28 +010010223 retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
Willy Tarreau036fae02008-01-06 13:24:40 +010010224 generally work on local networks as long as there are no packet losses. This
10225 will prevent people from sending bare HTTP requests using telnet.
10226
10227 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010228 chunk of the incoming request. It should be set in the frontend to take
10229 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
10230 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +010010231
Willy Tarreau0f228a02015-05-01 15:37:53 +020010232 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010233 "timeout client", "option http-buffer-request".
Willy Tarreau036fae02008-01-06 13:24:40 +010010234
Willy Tarreau844e3c52008-01-11 16:28:18 +010010235
10236timeout queue <timeout>
10237 Set the maximum time to wait in the queue for a connection slot to be free
10238 May be used in sections : defaults | frontend | listen | backend
10239 yes | no | yes | yes
10240 Arguments :
10241 <timeout> is the timeout value specified in milliseconds by default, but
10242 can be in any other unit if the number is suffixed by the unit,
10243 as explained at the top of this document.
10244
10245 When a server's maxconn is reached, connections are left pending in a queue
10246 which may be server-specific or global to the backend. In order not to wait
10247 indefinitely, a timeout is applied to requests pending in the queue. If the
10248 timeout is reached, it is considered that the request will almost never be
10249 served, so it is dropped and a 503 error is returned to the client.
10250
10251 The "timeout queue" statement allows to fix the maximum time for a request to
10252 be left pending in a queue. If unspecified, the same value as the backend's
10253 connection timeout ("timeout connect") is used, for backwards compatibility
10254 with older versions with no "timeout queue" parameter.
10255
10256 See also : "timeout connect", "contimeout".
10257
10258
10259timeout server <timeout>
10260timeout srvtimeout <timeout> (deprecated)
10261 Set the maximum inactivity time on the server side.
10262 May be used in sections : defaults | frontend | listen | backend
10263 yes | no | yes | yes
10264 Arguments :
10265 <timeout> is the timeout value specified in milliseconds by default, but
10266 can be in any other unit if the number is suffixed by the unit,
10267 as explained at the top of this document.
10268
10269 The inactivity timeout applies when the server is expected to acknowledge or
10270 send data. In HTTP mode, this timeout is particularly important to consider
10271 during the first phase of the server's response, when it has to send the
10272 headers, as it directly represents the server's processing time for the
10273 request. To find out what value to put there, it's often good to start with
10274 what would be considered as unacceptable response times, then check the logs
10275 to observe the response time distribution, and adjust the value accordingly.
10276
10277 The value is specified in milliseconds by default, but can be in any other
10278 unit if the number is suffixed by the unit, as specified at the top of this
10279 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
10280 recommended that the client timeout remains equal to the server timeout in
10281 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010282 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +010010283 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +010010284 seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
10285 with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
Willy Tarreauce887fd2012-05-12 12:50:00 +020010286 "timeout tunnel", which overrides "timeout client" and "timeout server" for
10287 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010288
10289 This parameter is specific to backends, but can be specified once for all in
10290 "defaults" sections. This is in fact one of the easiest solutions not to
10291 forget about it. An unspecified timeout results in an infinite timeout, which
10292 is not recommended. Such a usage is accepted and works but reports a warning
10293 during startup because it may results in accumulation of expired sessions in
10294 the system if the system's timeouts are not configured either.
10295
10296 This parameter replaces the old, deprecated "srvtimeout". It is recommended
10297 to use it to write new configurations. The form "timeout srvtimeout" is
10298 provided only by backwards compatibility but its use is strongly discouraged.
10299
Willy Tarreauce887fd2012-05-12 12:50:00 +020010300 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +010010301
Willy Tarreau05cdd962014-05-10 14:30:07 +020010302
10303timeout server-fin <timeout>
10304 Set the inactivity timeout on the server side for half-closed connections.
10305 May be used in sections : defaults | frontend | listen | backend
10306 yes | no | yes | yes
10307 Arguments :
10308 <timeout> is the timeout value specified in milliseconds by default, but
10309 can be in any other unit if the number is suffixed by the unit,
10310 as explained at the top of this document.
10311
10312 The inactivity timeout applies when the server is expected to acknowledge or
10313 send data while one direction is already shut down. This timeout is different
10314 from "timeout server" in that it only applies to connections which are closed
10315 in one direction. This is particularly useful to avoid keeping connections in
10316 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
10317 This problem is particularly common long connections such as RDP or WebSocket.
10318 Note that this timeout can override "timeout tunnel" when a connection shuts
10319 down in one direction. This setting was provided for completeness, but in most
10320 situations, it should not be needed.
10321
10322 This parameter is specific to backends, but can be specified once for all in
10323 "defaults" sections. By default it is not set, so half-closed connections
10324 will use the other timeouts (timeout.server or timeout.tunnel).
10325
10326 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
10327
Willy Tarreau844e3c52008-01-11 16:28:18 +010010328
10329timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +010010330 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +010010331 May be used in sections : defaults | frontend | listen | backend
10332 yes | yes | yes | yes
10333 Arguments :
10334 <timeout> is the tarpit duration specified in milliseconds by default, but
10335 can be in any other unit if the number is suffixed by the unit,
10336 as explained at the top of this document.
10337
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030010338 When a connection is tarpitted using "http-request tarpit" or
10339 "reqtarpit", it is maintained open with no activity for a certain
10340 amount of time, then closed. "timeout tarpit" defines how long it will
10341 be maintained open.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010342
10343 The value is specified in milliseconds by default, but can be in any other
10344 unit if the number is suffixed by the unit, as specified at the top of this
10345 document. If unspecified, the same value as the backend's connection timeout
10346 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +010010347 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010348
10349 See also : "timeout connect", "contimeout".
10350
10351
Willy Tarreauce887fd2012-05-12 12:50:00 +020010352timeout tunnel <timeout>
10353 Set the maximum inactivity time on the client and server side for tunnels.
10354 May be used in sections : defaults | frontend | listen | backend
10355 yes | no | yes | yes
10356 Arguments :
10357 <timeout> is the timeout value specified in milliseconds by default, but
10358 can be in any other unit if the number is suffixed by the unit,
10359 as explained at the top of this document.
10360
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010361 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +020010362 between a client and a server, and the connection remains inactive in both
10363 directions. This timeout supersedes both the client and server timeouts once
10364 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
Davor Ocelice9ed2812017-12-25 17:49:28 +010010365 analyzer remains attached to either connection (e.g. tcp content rules are
10366 accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
Willy Tarreauce887fd2012-05-12 12:50:00 +020010367 when switching to the WebSocket protocol, or forwarding a CONNECT request
10368 to a proxy), or after the first response when no keepalive/close option is
10369 specified.
10370
Willy Tarreau05cdd962014-05-10 14:30:07 +020010371 Since this timeout is usually used in conjunction with long-lived connections,
10372 it usually is a good idea to also set "timeout client-fin" to handle the
10373 situation where a client suddenly disappears from the net and does not
10374 acknowledge a close, or sends a shutdown and does not acknowledge pending
10375 data anymore. This can happen in lossy networks where firewalls are present,
10376 and is detected by the presence of large amounts of sessions in a FIN_WAIT
10377 state.
10378
Willy Tarreauce887fd2012-05-12 12:50:00 +020010379 The value is specified in milliseconds by default, but can be in any other
10380 unit if the number is suffixed by the unit, as specified at the top of this
10381 document. Whatever the expected normal idle time, it is a good practice to
10382 cover at least one or several TCP packet losses by specifying timeouts that
Davor Ocelice9ed2812017-12-25 17:49:28 +010010383 are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreauce887fd2012-05-12 12:50:00 +020010384
10385 This parameter is specific to backends, but can be specified once for all in
10386 "defaults" sections. This is in fact one of the easiest solutions not to
10387 forget about it.
10388
10389 Example :
10390 defaults http
10391 option http-server-close
10392 timeout connect 5s
10393 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +020010394 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +020010395 timeout server 30s
10396 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
10397
Willy Tarreau05cdd962014-05-10 14:30:07 +020010398 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +020010399
10400
Willy Tarreau844e3c52008-01-11 16:28:18 +010010401transparent (deprecated)
10402 Enable client-side transparent proxying
10403 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +010010404 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +010010405 Arguments : none
10406
10407 This keyword was introduced in order to provide layer 7 persistence to layer
10408 3 load balancers. The idea is to use the OS's ability to redirect an incoming
10409 connection for a remote address to a local process (here HAProxy), and let
10410 this process know what address was initially requested. When this option is
10411 used, sessions without cookies will be forwarded to the original destination
10412 IP address of the incoming request (which should match that of another
10413 equipment), while requests with cookies will still be forwarded to the
10414 appropriate server.
10415
10416 The "transparent" keyword is deprecated, use "option transparent" instead.
10417
10418 Note that contrary to a common belief, this option does NOT make HAProxy
10419 present the client's IP to the server when establishing the connection.
10420
Willy Tarreau844e3c52008-01-11 16:28:18 +010010421 See also: "option transparent"
10422
William Lallemanda73203e2012-03-12 12:48:57 +010010423unique-id-format <string>
10424 Generate a unique ID for each request.
10425 May be used in sections : defaults | frontend | listen | backend
10426 yes | yes | yes | no
10427 Arguments :
10428 <string> is a log-format string.
10429
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010430 This keyword creates a ID for each request using the custom log format. A
10431 unique ID is useful to trace a request passing through many components of
10432 a complex infrastructure. The newly created ID may also be logged using the
10433 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +010010434
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010435 The format should be composed from elements that are guaranteed to be
10436 unique when combined together. For instance, if multiple haproxy instances
10437 are involved, it might be important to include the node name. It is often
10438 needed to log the incoming connection's source and destination addresses
10439 and ports. Note that since multiple requests may be performed over the same
10440 connection, including a request counter may help differentiate them.
10441 Similarly, a timestamp may protect against a rollover of the counter.
10442 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +010010443
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010444 It is recommended to use hexadecimal notation for many fields since it
10445 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +010010446
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010447 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010010448
Julien Vehentf21be322014-03-07 08:27:34 -050010449 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010010450
10451 will generate:
10452
10453 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
10454
10455 See also: "unique-id-header"
10456
10457unique-id-header <name>
10458 Add a unique ID header in the HTTP request.
10459 May be used in sections : defaults | frontend | listen | backend
10460 yes | yes | yes | no
10461 Arguments :
10462 <name> is the name of the header.
10463
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010464 Add a unique-id header in the HTTP request sent to the server, using the
10465 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +010010466
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010467 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010010468
Julien Vehentf21be322014-03-07 08:27:34 -050010469 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010010470 unique-id-header X-Unique-ID
10471
10472 will generate:
10473
10474 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
10475
10476 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +010010477
Willy Tarreauf51658d2014-04-23 01:21:56 +020010478use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010479 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010480 May be used in sections : defaults | frontend | listen | backend
10481 no | yes | yes | no
10482 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010483 <backend> is the name of a valid backend or "listen" section, or a
10484 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010485
Willy Tarreauf51658d2014-04-23 01:21:56 +020010486 <condition> is a condition composed of ACLs, as described in section 7. If
10487 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010488
10489 When doing content-switching, connections arrive on a frontend and are then
10490 dispatched to various backends depending on a number of conditions. The
10491 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010492 "use_backend" keyword. While it is normally used with HTTP processing, it can
Davor Ocelice9ed2812017-12-25 17:49:28 +010010493 also be used in pure TCP, either without content using stateless ACLs (e.g.
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010494 source address validation) or combined with a "tcp-request" rule to wait for
10495 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010496
10497 There may be as many "use_backend" rules as desired. All of these rules are
10498 evaluated in their declaration order, and the first one which matches will
10499 assign the backend.
10500
10501 In the first form, the backend will be used if the condition is met. In the
10502 second form, the backend will be used if the condition is not met. If no
10503 condition is valid, the backend defined with "default_backend" will be used.
10504 If no default backend is defined, either the servers in the same section are
10505 used (in case of a "listen" section) or, in case of a frontend, no server is
10506 used and a 503 service unavailable response is returned.
10507
Willy Tarreau51aecc72009-07-12 09:47:04 +020010508 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010509 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +020010510 and backend processing will immediately follow, or the backend will wait for
10511 a complete HTTP request to get in. This feature is useful when a frontend
10512 must decode several protocols on a unique port, one of them being HTTP.
10513
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010514 When <backend> is a simple name, it is resolved at configuration time, and an
10515 error is reported if the specified backend does not exist. If <backend> is
10516 a log-format string instead, no check may be done at configuration time, so
10517 the backend name is resolved dynamically at run time. If the resulting
10518 backend name does not correspond to any valid backend, no other rule is
10519 evaluated, and the default_backend directive is applied instead. Note that
10520 when using dynamic backend names, it is highly recommended to use a prefix
10521 that no other backend uses in order to ensure that an unauthorized backend
10522 cannot be forced from the request.
10523
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010524 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010525 used to detect the association between frontends and backends to compute the
10526 backend's "fullconn" setting. This cannot be done for dynamic names.
10527
10528 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
10529 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +010010530
Willy Tarreau036fae02008-01-06 13:24:40 +010010531
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010532use-server <server> if <condition>
10533use-server <server> unless <condition>
10534 Only use a specific server if/unless an ACL-based condition is matched.
10535 May be used in sections : defaults | frontend | listen | backend
10536 no | no | yes | yes
10537 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010538 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010539
10540 <condition> is a condition composed of ACLs, as described in section 7.
10541
10542 By default, connections which arrive to a backend are load-balanced across
10543 the available servers according to the configured algorithm, unless a
10544 persistence mechanism such as a cookie is used and found in the request.
10545
10546 Sometimes it is desirable to forward a particular request to a specific
10547 server without having to declare a dedicated backend for this server. This
10548 can be achieved using the "use-server" rules. These rules are evaluated after
10549 the "redirect" rules and before evaluating cookies, and they have precedence
10550 on them. There may be as many "use-server" rules as desired. All of these
10551 rules are evaluated in their declaration order, and the first one which
10552 matches will assign the server.
10553
10554 If a rule designates a server which is down, and "option persist" is not used
10555 and no force-persist rule was validated, it is ignored and evaluation goes on
10556 with the next rules until one matches.
10557
10558 In the first form, the server will be used if the condition is met. In the
10559 second form, the server will be used if the condition is not met. If no
10560 condition is valid, the processing continues and the server will be assigned
10561 according to other persistence mechanisms.
10562
10563 Note that even if a rule is matched, cookie processing is still performed but
10564 does not assign the server. This allows prefixed cookies to have their prefix
10565 stripped.
10566
10567 The "use-server" statement works both in HTTP and TCP mode. This makes it
10568 suitable for use with content-based inspection. For instance, a server could
10569 be selected in a farm according to the TLS SNI field. And if these servers
10570 have their weight set to zero, they will not be used for other traffic.
10571
10572 Example :
10573 # intercept incoming TLS requests based on the SNI field
10574 use-server www if { req_ssl_sni -i www.example.com }
10575 server www 192.168.0.1:443 weight 0
10576 use-server mail if { req_ssl_sni -i mail.example.com }
10577 server mail 192.168.0.1:587 weight 0
10578 use-server imap if { req_ssl_sni -i imap.example.com }
Lukas Tribus98a3e3f2017-03-26 12:55:35 +000010579 server imap 192.168.0.1:993 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010580 # all the rest is forwarded to this server
10581 server default 192.168.0.2:443 check
10582
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010583 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010584
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010585
Davor Ocelice9ed2812017-12-25 17:49:28 +0100105865. Bind and server options
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010587--------------------------
10588
10589The "bind", "server" and "default-server" keywords support a number of settings
10590depending on some build options and on the system HAProxy was built on. These
10591settings generally each consist in one word sometimes followed by a value,
10592written on the same line as the "bind" or "server" line. All these options are
10593described in this section.
10594
10595
105965.1. Bind options
10597-----------------
10598
10599The "bind" keyword supports a certain number of settings which are all passed
10600as arguments on the same line. The order in which those arguments appear makes
10601no importance, provided that they appear after the bind address. All of these
10602parameters are optional. Some of them consist in a single words (booleans),
10603while other ones expect a value after them. In this case, the value must be
10604provided immediately after the setting name.
10605
10606The currently supported settings are the following ones.
10607
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010010608accept-netscaler-cip <magic number>
10609 Enforces the use of the NetScaler Client IP insertion protocol over any
10610 connection accepted by any of the TCP sockets declared on the same line. The
10611 NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
10612 the incoming connection to be used everywhere an address is used, with the
10613 only exception of "tcp-request connection" rules which will only see the
10614 real connection address. Logs will reflect the addresses indicated in the
10615 protocol, unless it is violated, in which case the real address will still
10616 be used. This keyword combined with support from external components can be
10617 used as an efficient and reliable alternative to the X-Forwarded-For
Bertrand Jacquin90759682016-06-06 15:35:39 +010010618 mechanism which is not always reliable and not even always usable. See also
10619 "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
10620 which client is allowed to use the protocol.
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010010621
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010622accept-proxy
10623 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +020010624 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
10625 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010626 3/4 addresses of the incoming connection to be used everywhere an address is
10627 used, with the only exception of "tcp-request connection" rules which will
10628 only see the real connection address. Logs will reflect the addresses
10629 indicated in the protocol, unless it is violated, in which case the real
Davor Ocelice9ed2812017-12-25 17:49:28 +010010630 address will still be used. This keyword combined with support from external
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010631 components can be used as an efficient and reliable alternative to the
10632 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +020010633 usable. See also "tcp-request connection expect-proxy" for a finer-grained
10634 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010635
Olivier Houchardc2aae742017-09-22 18:26:28 +020010636allow-0rtt
Bertrand Jacquina25282b2018-08-14 00:56:13 +010010637 Allow receiving early data when using TLSv1.3. This is disabled by default,
Olivier Houchardc2aae742017-09-22 18:26:28 +020010638 due to security considerations.
10639
Willy Tarreauab861d32013-04-02 02:30:41 +020010640alpn <protocols>
10641 This enables the TLS ALPN extension and advertises the specified protocol
10642 list as supported on top of ALPN. The protocol list consists in a comma-
10643 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
10644 quotes). This requires that the SSL library is build with support for TLS
10645 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
Willy Tarreau95c4e142017-11-26 12:18:55 +010010646 initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
10647 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
10648 now obsolete NPN extension. At the time of writing this, most browsers still
10649 support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
10650 a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
10651 are expected to be supported, both versions can be advertised, in order of
10652 preference, like below :
10653
10654 bind :443 ssl crt pub.pem alpn h2,http/1.1
Willy Tarreauab861d32013-04-02 02:30:41 +020010655
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010656backlog <backlog>
10657 Sets the socket's backlog to this value. If unspecified, the frontend's
10658 backlog is used instead, which generally defaults to the maxconn value.
10659
Emmanuel Hocdete7f2b732017-01-09 16:15:54 +010010660curves <curves>
10661 This setting is only available when support for OpenSSL was built in. It sets
10662 the string describing the list of elliptic curves algorithms ("curve suite")
10663 that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
10664 string is a colon-delimited list of curve name.
10665 Example: "X25519:P-256" (without quote)
10666 When "curves" is set, "ecdhe" parameter is ignored.
10667
Emeric Brun7fb34422012-09-28 15:26:15 +020010668ecdhe <named curve>
10669 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +010010670 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
10671 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +020010672
Emeric Brunfd33a262012-10-11 16:28:27 +020010673ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +020010674 This setting is only available when support for OpenSSL was built in. It
10675 designates a PEM file from which to load CA certificates used to verify
10676 client's certificate.
10677
Emeric Brunb6dc9342012-09-28 17:55:37 +020010678ca-ignore-err [all|<errorID>,...]
10679 This setting is only available when support for OpenSSL was built in.
10680 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
10681 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
10682 error is ignored.
10683
Christopher Faulet31af49d2015-06-09 17:29:50 +020010684ca-sign-file <cafile>
10685 This setting is only available when support for OpenSSL was built in. It
10686 designates a PEM file containing both the CA certificate and the CA private
10687 key used to create and sign server's certificates. This is a mandatory
10688 setting when the dynamic generation of certificates is enabled. See
10689 'generate-certificates' for details.
10690
Bertrand Jacquind4d0a232016-11-13 16:37:12 +000010691ca-sign-pass <passphrase>
Christopher Faulet31af49d2015-06-09 17:29:50 +020010692 This setting is only available when support for OpenSSL was built in. It is
10693 the CA private key passphrase. This setting is optional and used only when
10694 the dynamic generation of certificates is enabled. See
10695 'generate-certificates' for details.
10696
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010697ciphers <ciphers>
10698 This setting is only available when support for OpenSSL was built in. It sets
10699 the string describing the list of cipher algorithms ("cipher suite") that are
Dirkjan Bussink415150f2018-09-14 11:14:21 +020010700 negotiated during the SSL/TLS handshake except for TLSv1.3. The format of the
10701 string is defined in "man 1 ciphers" from OpenSSL man pages, and can be for
10702 instance a string such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without
10703 quotes). Depending on the compatibility and security requirements, the list
10704 of suitable ciphers depends on a variety of variables. For background
10705 information and recommendations see e.g.
10706 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
10707 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
10708 cipher configuration, please check the "ciphersuites" keyword.
10709
10710ciphersuites <ciphersuites>
10711 This setting is only available when support for OpenSSL was built in and
10712 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
10713 the list of cipher algorithms ("cipher suite") that are negotiated during the
10714 TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
10715 OpenSSL man pages under the "ciphersuites" section, and can be for instance a
10716 string such as
10717 "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
10718 (without quotes). For cipher configuration for TLSv1.2 and earlier, please check
10719 the "ciphers" keyword.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010720
Emeric Brunfd33a262012-10-11 16:28:27 +020010721crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +020010722 This setting is only available when support for OpenSSL was built in. It
10723 designates a PEM file from which to load certificate revocation list used
10724 to verify client's certificate.
10725
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010726crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +000010727 This setting is only available when support for OpenSSL was built in. It
10728 designates a PEM file containing both the required certificates and any
10729 associated private keys. This file can be built by concatenating multiple
10730 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
10731 requires an intermediate certificate, this can also be concatenated into this
10732 file.
10733
10734 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
10735 are loaded.
10736
10737 If a directory name is used instead of a PEM file, then all files found in
Cyril Bonté3180f7b2015-01-25 00:16:08 +010010738 that directory will be loaded in alphabetic order unless their name ends with
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010739 '.issuer', '.ocsp' or '.sctl' (reserved extensions). This directive may be
10740 specified multiple times in order to load certificates from multiple files or
10741 directories. The certificates will be presented to clients who provide a
10742 valid TLS Server Name Indication field matching one of their CN or alt
Davor Ocelice9ed2812017-12-25 17:49:28 +010010743 subjects. Wildcards are supported, where a wildcard character '*' is used
10744 instead of the first hostname component (e.g. *.example.org matches
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010745 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +000010746
10747 If no SNI is provided by the client or if the SSL library does not support
10748 TLS extensions, or if the client provides an SNI hostname which does not
10749 match any certificate, then the first loaded certificate will be presented.
10750 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +010010751 recommended to load the default one first as a file or to ensure that it will
10752 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +000010753
Emeric Brune032bfa2012-09-28 13:01:45 +020010754 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010755
Davor Ocelice9ed2812017-12-25 17:49:28 +010010756 Some CAs (such as GoDaddy) offer a drop down list of server types that do not
Alex Davies0fbf0162013-03-02 16:04:50 +000010757 include HAProxy when obtaining a certificate. If this happens be sure to
Davor Ocelice9ed2812017-12-25 17:49:28 +010010758 choose a web server that the CA believes requires an intermediate CA (for
10759 GoDaddy, selection Apache Tomcat will get the correct bundle, but many
Alex Davies0fbf0162013-03-02 16:04:50 +000010760 others, e.g. nginx, result in a wrong bundle that will not work for some
10761 clients).
10762
Emeric Brun4147b2e2014-06-16 18:36:30 +020010763 For each PEM file, haproxy checks for the presence of file at the same path
10764 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
10765 Status Request extension (also known as "OCSP stapling") is automatically
10766 enabled. The content of this file is optional. If not empty, it must contain
10767 a valid OCSP Response in DER format. In order to be valid an OCSP Response
10768 must comply with the following rules: it has to indicate a good status,
10769 it has to be a single response for the certificate of the PEM file, and it
10770 has to be valid at the moment of addition. If these rules are not respected
10771 the OCSP Response is ignored and a warning is emitted. In order to identify
10772 which certificate an OCSP Response applies to, the issuer's certificate is
10773 necessary. If the issuer's certificate is not found in the PEM file, it will
10774 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
10775 if it exists otherwise it will fail with an error.
10776
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010777 For each PEM file, haproxy also checks for the presence of file at the same
10778 path suffixed by ".sctl". If such file is found, support for Certificate
10779 Transparency (RFC6962) TLS extension is enabled. The file must contain a
10780 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
10781 to check basic syntax, but no signatures are verified.
10782
yanbzhu6c25e9e2016-01-05 12:52:02 -050010783 There are cases where it is desirable to support multiple key types, e.g. RSA
10784 and ECDSA in the cipher suites offered to the clients. This allows clients
10785 that support EC certificates to be able to use EC ciphers, while
10786 simultaneously supporting older, RSA only clients.
yanbzhud19630c2015-12-14 15:10:25 -050010787
10788 In order to provide this functionality, multiple PEM files, each with a
10789 different key type, are required. To associate these PEM files into a
10790 "cert bundle" that is recognized by haproxy, they must be named in the
10791 following way: All PEM files that are to be bundled must have the same base
10792 name, with a suffix indicating the key type. Currently, three suffixes are
10793 supported: rsa, dsa and ecdsa. For example, if www.example.com has two PEM
10794 files, an RSA file and an ECDSA file, they must be named: "example.pem.rsa"
10795 and "example.pem.ecdsa". The first part of the filename is arbitrary; only the
10796 suffix matters. To load this bundle into haproxy, specify the base name only:
10797
10798 Example : bind :8443 ssl crt example.pem
10799
yanbzhu6c25e9e2016-01-05 12:52:02 -050010800 Note that the suffix is not given to haproxy; this tells haproxy to look for
yanbzhud19630c2015-12-14 15:10:25 -050010801 a cert bundle.
10802
Davor Ocelice9ed2812017-12-25 17:49:28 +010010803 HAProxy will load all PEM files in the bundle at the same time to try to
yanbzhud19630c2015-12-14 15:10:25 -050010804 support multiple key types. PEM files are combined based on Common Name
10805 (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means
10806 that even if you give haproxy a cert bundle, if there are no shared CN/SAN
10807 entries in the certificates in that bundle, haproxy will not be able to
10808 provide multi-cert support.
10809
10810 Assuming bundle in the example above contained the following:
10811
10812 Filename | CN | SAN
10813 -------------------+-----------------+-------------------
10814 example.pem.rsa | www.example.com | rsa.example.com
yanbzhu6c25e9e2016-01-05 12:52:02 -050010815 -------------------+-----------------+-------------------
yanbzhud19630c2015-12-14 15:10:25 -050010816 example.pem.ecdsa | www.example.com | ecdsa.example.com
10817 -------------------+-----------------+-------------------
10818
10819 Users connecting with an SNI of "www.example.com" will be able
10820 to use both RSA and ECDSA cipher suites. Users connecting with an SNI of
10821 "rsa.example.com" will only be able to use RSA cipher suites, and users
10822 connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010823 suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
10824 no need to bundle certificates. ECDSA certificate will be preferred if client
10825 support it.
yanbzhud19630c2015-12-14 15:10:25 -050010826
10827 If a directory name is given as the <cert> argument, haproxy will
10828 automatically search and load bundled files in that directory.
10829
10830 OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
10831 bundling. Each certificate can have its own .ocsp and .issuer file. At this
10832 time, sctl is not supported in multi-certificate bundling.
10833
Emeric Brunb6dc9342012-09-28 17:55:37 +020010834crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +000010835 This setting is only available when support for OpenSSL was built in. Sets a
Davor Ocelice9ed2812017-12-25 17:49:28 +010010836 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010837 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +000010838 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +020010839
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010840crt-list <file>
10841 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010842 designates a list of PEM file with an optional ssl configuration and a SNI
10843 filter per certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010844
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010845 <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
10846
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020010847 sslbindconf support "npn", "alpn", "verify", "ca-file", "no-ca-names",
10848 crl-file", "ecdhe", "curves", "ciphers" configuration. With BoringSSL
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010849 and Openssl >= 1.1.1 "ssl-min-ver" and "ssl-max-ver" are also supported.
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010850 It override the configuration set in bind line for the certificate.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010851
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020010852 Wildcards are supported in the SNI filter. Negative filter are also supported,
10853 only useful in combination with a wildcard filter to exclude a particular SNI.
10854 The certificates will be presented to clients who provide a valid TLS Server
10855 Name Indication field matching one of the SNI filters. If no SNI filter is
10856 specified, the CN and alt subjects are used. This directive may be specified
10857 multiple times. See the "crt" option for more information. The default
10858 certificate is still needed to meet OpenSSL expectations. If it is not used,
10859 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010860
yanbzhu6c25e9e2016-01-05 12:52:02 -050010861 Multi-cert bundling (see "crt") is supported with crt-list, as long as only
Emmanuel Hocdetd294aea2016-05-13 11:14:06 +020010862 the base name is given in the crt-list. SNI filter will do the same work on
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010863 all bundled certificates. With BoringSSL and Openssl >= 1.1.1 multi-cert is
10864 natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
10865 be declared in a row, and set different ssl and filter parameter.
yanbzhud19630c2015-12-14 15:10:25 -050010866
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010867 crt-list file example:
10868 cert1.pem
Emmanuel Hocdet05942112017-02-20 16:11:50 +010010869 cert2.pem [alpn h2,http/1.1]
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010870 certW.pem *.domain.tld !secure.domain.tld
Emmanuel Hocdet05942112017-02-20 16:11:50 +010010871 certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010872
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010873defer-accept
10874 Is an optional keyword which is supported only on certain Linux kernels. It
10875 states that a connection will only be accepted once some data arrive on it,
10876 or at worst after the first retransmit. This should be used only on protocols
Davor Ocelice9ed2812017-12-25 17:49:28 +010010877 for which the client talks first (e.g. HTTP). It can slightly improve
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010878 performance by ensuring that most of the request is already available when
10879 the connection is accepted. On the other hand, it will not be able to detect
10880 connections which don't talk. It is important to note that this option is
10881 broken in all kernels up to 2.6.31, as the connection is never accepted until
10882 the client talks. This can cause issues with front firewalls which would see
10883 an established connection while the proxy will only see it in SYN_RECV. This
10884 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
10885
William Lallemandf6975e92017-05-26 17:42:10 +020010886expose-fd listeners
10887 This option is only usable with the stats socket. It gives your stats socket
10888 the capability to pass listeners FD to another HAProxy process.
William Lallemande202b1e2017-06-01 17:38:56 +020010889 During a reload with the master-worker mode, the process is automatically
10890 reexecuted adding -x and one of the stats socket with this option.
Davor Ocelice9ed2812017-12-25 17:49:28 +010010891 See also "-x" in the management guide.
William Lallemandf6975e92017-05-26 17:42:10 +020010892
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010893force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010894 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010895 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010896 for high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010897 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010898
10899force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010900 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010901 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010902 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010903
10904force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010905 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010906 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010907 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010908
10909force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010910 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010911 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010912 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010913
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020010914force-tlsv13
10915 This option enforces use of TLSv1.3 only on SSL connections instantiated from
10916 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010917 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020010918
Christopher Faulet31af49d2015-06-09 17:29:50 +020010919generate-certificates
10920 This setting is only available when support for OpenSSL was built in. It
10921 enables the dynamic SSL certificates generation. A CA certificate and its
10922 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
10923 a transparent forward proxy, SSL requests generate errors because of a common
10924 name mismatch on the certificate presented to the client. With this option
10925 enabled, HAProxy will try to forge a certificate using the SNI hostname
10926 indicated by the client. This is done only if no certificate matches the SNI
10927 hostname (see 'crt-list'). If an error occurs, the default certificate is
10928 used, else the 'strict-sni' option is set.
10929 It can also be used when HAProxy is configured as a reverse proxy to ease the
10930 deployment of an architecture with many backends.
10931
10932 Creating a SSL certificate is an expensive operation, so a LRU cache is used
10933 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
Davor Ocelice9ed2812017-12-25 17:49:28 +010010934 increases the HAProxy's memory footprint to reduce latency when the same
Christopher Faulet31af49d2015-06-09 17:29:50 +020010935 certificate is used many times.
10936
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010937gid <gid>
10938 Sets the group of the UNIX sockets to the designated system gid. It can also
10939 be set by default in the global section's "unix-bind" statement. Note that
10940 some platforms simply ignore this. This setting is equivalent to the "group"
10941 setting except that the group ID is used instead of its name. This setting is
10942 ignored by non UNIX sockets.
10943
10944group <group>
10945 Sets the group of the UNIX sockets to the designated system group. It can
10946 also be set by default in the global section's "unix-bind" statement. Note
10947 that some platforms simply ignore this. This setting is equivalent to the
10948 "gid" setting except that the group name is used instead of its gid. This
10949 setting is ignored by non UNIX sockets.
10950
10951id <id>
10952 Fixes the socket ID. By default, socket IDs are automatically assigned, but
10953 sometimes it is more convenient to fix them to ease monitoring. This value
10954 must be strictly positive and unique within the listener/frontend. This
10955 option can only be used when defining only a single socket.
10956
10957interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +010010958 Restricts the socket to a specific interface. When specified, only packets
10959 received from that particular interface are processed by the socket. This is
10960 currently only supported on Linux. The interface must be a primary system
10961 interface, not an aliased interface. It is also possible to bind multiple
10962 frontends to the same address if they are bound to different interfaces. Note
10963 that binding to a network interface requires root privileges. This parameter
Jérôme Magnin61275192018-02-07 11:39:58 +010010964 is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic
10965 uses the same interface as inbound traffic, and its associated routing table,
10966 even if there are explicit routes through different interfaces configured.
10967 This can prove useful to address asymmetric routing issues when the same
10968 client IP addresses need to be able to reach frontends hosted on different
10969 interfaces.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010970
Willy Tarreauabb175f2012-09-24 12:43:26 +020010971level <level>
10972 This setting is used with the stats sockets only to restrict the nature of
10973 the commands that can be issued on the socket. It is ignored by other
10974 sockets. <level> can be one of :
Davor Ocelice9ed2812017-12-25 17:49:28 +010010975 - "user" is the least privileged level; only non-sensitive stats can be
Willy Tarreauabb175f2012-09-24 12:43:26 +020010976 read, and no change is allowed. It would make sense on systems where it
10977 is not easy to restrict access to the socket.
10978 - "operator" is the default level and fits most common uses. All data can
Davor Ocelice9ed2812017-12-25 17:49:28 +010010979 be read, and only non-sensitive changes are permitted (e.g. clear max
Willy Tarreauabb175f2012-09-24 12:43:26 +020010980 counters).
Davor Ocelice9ed2812017-12-25 17:49:28 +010010981 - "admin" should be used with care, as everything is permitted (e.g. clear
Willy Tarreauabb175f2012-09-24 12:43:26 +020010982 all counters).
10983
Andjelko Iharosc4df59e2017-07-20 11:59:48 +020010984severity-output <format>
10985 This setting is used with the stats sockets only to configure severity
10986 level output prepended to informational feedback messages. Severity
10987 level of messages can range between 0 and 7, conforming to syslog
10988 rfc5424. Valid and successful socket commands requesting data
10989 (i.e. "show map", "get acl foo" etc.) will never have a severity level
10990 prepended. It is ignored by other sockets. <format> can be one of :
10991 - "none" (default) no severity level is prepended to feedback messages.
10992 - "number" severity level is prepended as a number.
10993 - "string" severity level is prepended as a string following the
10994 rfc5424 convention.
10995
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010996maxconn <maxconn>
10997 Limits the sockets to this number of concurrent connections. Extraneous
10998 connections will remain in the system's backlog until a connection is
10999 released. If unspecified, the limit will be the same as the frontend's
11000 maxconn. Note that in case of port ranges or multiple addresses, the same
11001 value will be applied to each socket. This setting enables different
11002 limitations on expensive sockets, for instance SSL entries which may easily
11003 eat all memory.
11004
11005mode <mode>
11006 Sets the octal mode used to define access permissions on the UNIX socket. It
11007 can also be set by default in the global section's "unix-bind" statement.
11008 Note that some platforms simply ignore this. This setting is ignored by non
11009 UNIX sockets.
11010
11011mss <maxseg>
11012 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
11013 connections. This can be used to force a lower MSS for certain specific
11014 ports, for instance for connections passing through a VPN. Note that this
11015 relies on a kernel feature which is theoretically supported under Linux but
11016 was buggy in all versions prior to 2.6.28. It may or may not work on other
11017 operating systems. It may also not change the advertised value but change the
11018 effective size of outgoing segments. The commonly advertised value for TCPv4
11019 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
11020 positive, it will be used as the advertised MSS. If it is negative, it will
11021 indicate by how much to reduce the incoming connection's advertised MSS for
11022 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
11023
11024name <name>
11025 Sets an optional name for these sockets, which will be reported on the stats
11026 page.
11027
Willy Tarreaud72f0f32015-10-13 14:50:22 +020011028namespace <name>
11029 On Linux, it is possible to specify which network namespace a socket will
11030 belong to. This directive makes it possible to explicitly bind a listener to
11031 a namespace different from the default one. Please refer to your operating
11032 system's documentation to find more details about network namespaces.
11033
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011034nice <nice>
11035 Sets the 'niceness' of connections initiated from the socket. Value must be
11036 in the range -1024..1024 inclusive, and defaults to zero. Positive values
11037 means that such connections are more friendly to others and easily offer
11038 their place in the scheduler. On the opposite, negative values mean that
11039 connections want to run with a higher priority than others. The difference
11040 only happens under high loads when the system is close to saturation.
11041 Negative values are appropriate for low-latency or administration services,
11042 and high values are generally recommended for CPU intensive tasks such as SSL
11043 processing or bulk transfers which are less sensible to latency. For example,
11044 it may make sense to use a positive value for an SMTP socket and a negative
11045 one for an RDP socket.
11046
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020011047no-ca-names
11048 This setting is only available when support for OpenSSL was built in. It
11049 prevents from send CA names in server hello message when ca-file is used.
11050
Emeric Brun9b3009b2012-10-05 11:55:06 +020011051no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011052 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011053 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011054 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011055 be enabled using any configuration option. This option is also available on
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011056 global statement "ssl-default-bind-options". Use "ssl-min-ver" and
11057 "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011058
Emeric Brun90ad8722012-10-02 14:00:59 +020011059no-tls-tickets
11060 This setting is only available when support for OpenSSL was built in. It
11061 disables the stateless session resumption (RFC 5077 TLS Ticket
11062 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011063 session resumption is more expensive in CPU usage. This option is also
11064 available on global statement "ssl-default-bind-options".
Emeric Brun90ad8722012-10-02 14:00:59 +020011065
Emeric Brun9b3009b2012-10-05 11:55:06 +020011066no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011067 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011068 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011069 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011070 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011071 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11072 and "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011073
Emeric Brun9b3009b2012-10-05 11:55:06 +020011074no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +020011075 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011076 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011077 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011078 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011079 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11080 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020011081
Emeric Brun9b3009b2012-10-05 11:55:06 +020011082no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +020011083 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011084 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011085 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011086 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011087 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11088 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020011089
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011090no-tlsv13
11091 This setting is only available when support for OpenSSL was built in. It
11092 disables support for TLSv1.3 on any sockets instantiated from the listener
11093 when SSL is supported. Note that SSLv2 is forced disabled in the code and
11094 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011095 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11096 and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011097
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020011098npn <protocols>
11099 This enables the NPN TLS extension and advertises the specified protocol list
11100 as supported on top of NPN. The protocol list consists in a comma-delimited
11101 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
11102 This requires that the SSL library is build with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +020011103 enabled (check with haproxy -vv). Note that the NPN extension has been
Willy Tarreau95c4e142017-11-26 12:18:55 +010011104 replaced with the ALPN extension (see the "alpn" keyword), though this one is
11105 only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
11106 version of OpenSSL, NPN might still be used as most clients still support it
11107 at the time of writing this. It is possible to enable both NPN and ALPN
11108 though it probably doesn't make any sense out of testing.
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020011109
Lukas Tribus53ae85c2017-05-04 15:45:40 +000011110prefer-client-ciphers
11111 Use the client's preference when selecting the cipher suite, by default
11112 the server's preference is enforced. This option is also available on
11113 global statement "ssl-default-bind-options".
Lukas Tribus926594f2018-05-18 17:55:57 +020011114 Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
11115 (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
11116 the client cipher list.
Lukas Tribus53ae85c2017-05-04 15:45:40 +000011117
Christopher Fauletc644fa92017-11-23 22:44:11 +010011118process <process-set>[/<thread-set>]
11119 This restricts the list of processes and/or threads on which this listener is
11120 allowed to run. It does not enforce any process but eliminates those which do
Davor Ocelice9ed2812017-12-25 17:49:28 +010011121 not match. If the frontend uses a "bind-process" setting, the intersection
Christopher Fauletc644fa92017-11-23 22:44:11 +010011122 between the two is applied. If in the end the listener is not allowed to run
11123 on any remaining process, a warning is emitted, and the listener will either
11124 run on the first process of the listener if a single process was specified,
11125 or on all of its processes if multiple processes were specified. If a thread
Davor Ocelice9ed2812017-12-25 17:49:28 +010011126 set is specified, it limits the threads allowed to process incoming
Christopher Fauletc644fa92017-11-23 22:44:11 +010011127 connections for this listener, for the corresponding process set. For the
11128 unlikely case where several ranges are needed, this directive may be
11129 repeated. <process-set> and <thread-set> must use the format
11130
11131 all | odd | even | number[-[number]]
11132
11133 Ranges can be partially defined. The higher bound can be omitted. In such
11134 case, it is replaced by the corresponding maximum value. The main purpose of
11135 this directive is to be used with the stats sockets and have one different
11136 socket per process. The second purpose is to have multiple bind lines sharing
11137 the same IP:port but not the same process in a listener, so that the system
11138 can distribute the incoming connections into multiple queues and allow a
11139 smoother inter-process load balancing. Currently Linux 3.9 and above is known
11140 for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +020011141
Christopher Fauleta717b992018-04-10 14:43:00 +020011142proto <name>
11143 Forces the multiplexer's protocol to use for the incoming connections. It
11144 must be compatible with the mode of the frontend (TCP or HTTP). It must also
11145 be usable on the frontend side. The list of available protocols is reported
11146 in haproxy -vv.
11147 Idea behind this optipon is to bypass the selection of the best multiplexer's
11148 protocol for all connections instantiated from this listening socket. For
11149 instance, it is possible to force the http/2 on clear TCP by specifing "proto
11150 h2" on the bind line.
11151
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011152ssl
11153 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011154 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011155 certificate is necessary (see "crt" above). All contents in the buffers will
11156 appear in clear text, so that ACLs and HTTP processing will only have access
Emmanuel Hocdetbd695fe2017-05-15 15:53:41 +020011157 to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
11158 to enable it.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011159
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011160ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11161 This option enforces use of <version> or lower on SSL connections instantiated
11162 from this listener. This option is also available on global statement
11163 "ssl-default-bind-options". See also "ssl-min-ver".
11164
11165ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11166 This option enforces use of <version> or upper on SSL connections instantiated
11167 from this listener. This option is also available on global statement
11168 "ssl-default-bind-options". See also "ssl-max-ver".
11169
Emmanuel Hocdet65623372013-01-24 17:17:15 +010011170strict-sni
11171 This setting is only available when support for OpenSSL was built in. The
11172 SSL/TLS negotiation is allow only if the client provided an SNI which match
11173 a certificate. The default certificate is not used.
11174 See the "crt" option for more information.
11175
Willy Tarreau2af207a2015-02-04 00:45:58 +010011176tcp-ut <delay>
Tim Düsterhus4896c442016-11-29 02:15:19 +010011177 Sets the TCP User Timeout for all incoming connections instantiated from this
Willy Tarreau2af207a2015-02-04 00:45:58 +010011178 listening socket. This option is available on Linux since version 2.6.37. It
11179 allows haproxy to configure a timeout for sockets which contain data not
Davor Ocelice9ed2812017-12-25 17:49:28 +010011180 receiving an acknowledgment for the configured delay. This is especially
Willy Tarreau2af207a2015-02-04 00:45:58 +010011181 useful on long-lived connections experiencing long idle periods such as
11182 remote terminals or database connection pools, where the client and server
11183 timeouts must remain high to allow a long period of idle, but where it is
11184 important to detect that the client has disappeared in order to release all
11185 resources associated with its connection (and the server's session). The
11186 argument is a delay expressed in milliseconds by default. This only works
11187 for regular TCP connections, and is ignored for other protocols.
11188
Willy Tarreau1c862c52012-10-05 16:21:00 +020011189tfo
Lukas Tribus0defb902013-02-13 23:35:39 +010011190 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +020011191 enables TCP Fast Open on the listening socket, which means that clients which
11192 support this feature will be able to send a request and receive a response
11193 during the 3-way handshake starting from second connection, thus saving one
11194 round-trip after the first connection. This only makes sense with protocols
11195 that use high connection rates and where each round trip matters. This can
11196 possibly cause issues with many firewalls which do not accept data on SYN
11197 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +020011198 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
11199 need to build HAProxy with USE_TFO=1 if your libc doesn't define
11200 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +020011201
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010011202tls-ticket-keys <keyfile>
11203 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
11204 bytes long, encoded with base64 (ex. openssl rand -base64 48). Number of keys
11205 is specified by the TLS_TICKETS_NO build option (default 3) and at least as
11206 many keys need to be present in the file. Last TLS_TICKETS_NO keys will be
11207 used for decryption and the penultimate one for encryption. This enables easy
11208 key rotation by just appending new key to the file and reloading the process.
11209 Keys must be periodically rotated (ex. every 12h) or Perfect Forward Secrecy
11210 is compromised. It is also a good idea to keep the keys off any permanent
11211 storage such as hard drives (hint: use tmpfs and don't swap those files).
11212 Lifetime hint can be changed using tune.ssl.timeout.
11213
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011214transparent
11215 Is an optional keyword which is supported only on certain Linux kernels. It
11216 indicates that the addresses will be bound even if they do not belong to the
11217 local machine, and that packets targeting any of these addresses will be
11218 intercepted just as if the addresses were locally configured. This normally
11219 requires that IP forwarding is enabled. Caution! do not use this with the
11220 default address '*', as it would redirect any traffic for the specified port.
11221 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
11222 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
11223 kernel version. Some distribution kernels include backports of the feature,
11224 so check for support with your vendor.
11225
Willy Tarreau77e3af92012-11-24 15:07:23 +010011226v4v6
11227 Is an optional keyword which is supported only on most recent systems
11228 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
11229 and IPv6 when it uses the default address. Doing so is sometimes necessary
11230 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011231 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +010011232
Willy Tarreau9b6700f2012-11-24 11:55:28 +010011233v6only
11234 Is an optional keyword which is supported only on most recent systems
11235 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
11236 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +010011237 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
11238 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +010011239
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011240uid <uid>
11241 Sets the owner of the UNIX sockets to the designated system uid. It can also
11242 be set by default in the global section's "unix-bind" statement. Note that
11243 some platforms simply ignore this. This setting is equivalent to the "user"
11244 setting except that the user numeric ID is used instead of its name. This
11245 setting is ignored by non UNIX sockets.
11246
11247user <user>
11248 Sets the owner of the UNIX sockets to the designated system user. It can also
11249 be set by default in the global section's "unix-bind" statement. Note that
11250 some platforms simply ignore this. This setting is equivalent to the "uid"
11251 setting except that the user name is used instead of its uid. This setting is
11252 ignored by non UNIX sockets.
11253
Emeric Brun1a073b42012-09-28 17:07:34 +020011254verify [none|optional|required]
11255 This setting is only available when support for OpenSSL was built in. If set
11256 to 'none', client certificate is not requested. This is the default. In other
11257 cases, a client certificate is requested. If the client does not provide a
11258 certificate after the request and if 'verify' is set to 'required', then the
11259 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +020011260 certificate provided by the client is always verified using CAs from
11261 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
11262 is aborted, regardless of the 'verify' option, unless the error code exactly
11263 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011264
Willy Tarreaub6205fd2012-09-24 12:27:33 +0200112655.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +010011266------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020011267
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010011268The "server" and "default-server" keywords support a certain number of settings
11269which are all passed as arguments on the server line. The order in which those
11270arguments appear does not count, and they are all optional. Some of those
11271settings are single words (booleans) while others expect one or several values
11272after them. In this case, the values must immediately follow the setting name.
11273Except default-server, all those settings must be specified after the server's
11274address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +020011275
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011276 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010011277 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +020011278
Frédéric Lécailled2376272017-03-21 18:52:12 +010011279Note that all these settings are supported both by "server" and "default-server"
11280keywords, except "id" which is only supported by "server".
11281
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011282The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +010011283
Willy Tarreauceb4ac92012-04-28 00:41:46 +020011284addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011285 Using the "addr" parameter, it becomes possible to use a different IP address
Baptiste Assmann13f83532016-03-06 23:14:36 +010011286 to send health-checks or to probe the agent-check. On some servers, it may be
11287 desirable to dedicate an IP address to specific component able to perform
11288 complex tests which are more suitable to health-checks than the application.
11289 This parameter is ignored if the "check" parameter is not set. See also the
11290 "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +020011291
Simon Hormand60d6912013-11-25 10:46:36 +090011292agent-check
11293 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +010011294 health check. An agent health check is performed by making a TCP connection
11295 to the port set by the "agent-port" parameter and reading an ASCII string.
11296 The string is made of a series of words delimited by spaces, tabs or commas
11297 in any order, optionally terminated by '\r' and/or '\n', each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +090011298
Willy Tarreau81f5d942013-12-09 20:51:51 +010011299 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +090011300 Values in this format will set the weight proportional to the initial
Willy Tarreauc5af3a62014-10-07 15:27:33 +020011301 weight of a server as configured when haproxy starts. Note that a zero
11302 weight is reported on the stats page as "DRAIN" since it has the same
11303 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +090011304
Davor Ocelice9ed2812017-12-25 17:49:28 +010011305 - The string "maxconn:" followed by an integer (no space between). Values
11306 in this format will set the maxconn of a server. The maximum number of
11307 connections advertised needs to be multiplied by the number of load
11308 balancers and different backends that use this health check to get the
11309 total number of connections the server might receive. Example: maxconn:30
Nenad Merdanovic174dd372016-04-24 23:10:06 +020011310
Willy Tarreau81f5d942013-12-09 20:51:51 +010011311 - The word "ready". This will turn the server's administrative state to the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011312 READY mode, thus canceling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +090011313
Willy Tarreau81f5d942013-12-09 20:51:51 +010011314 - The word "drain". This will turn the server's administrative state to the
11315 DRAIN mode, thus it will not accept any new connections other than those
11316 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +090011317
Willy Tarreau81f5d942013-12-09 20:51:51 +010011318 - The word "maint". This will turn the server's administrative state to the
11319 MAINT mode, thus it will not accept any new connections at all, and health
11320 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +090011321
Willy Tarreau81f5d942013-12-09 20:51:51 +010011322 - The words "down", "failed", or "stopped", optionally followed by a
11323 description string after a sharp ('#'). All of these mark the server's
11324 operating state as DOWN, but since the word itself is reported on the stats
11325 page, the difference allows an administrator to know if the situation was
11326 expected or not : the service may intentionally be stopped, may appear up
Davor Ocelice9ed2812017-12-25 17:49:28 +010011327 but fail some validity tests, or may be seen as down (e.g. missing process,
Willy Tarreau81f5d942013-12-09 20:51:51 +010011328 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +090011329
Willy Tarreau81f5d942013-12-09 20:51:51 +010011330 - The word "up" sets back the server's operating state as UP if health checks
11331 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +090011332
Willy Tarreau81f5d942013-12-09 20:51:51 +010011333 Parameters which are not advertised by the agent are not changed. For
11334 example, an agent might be designed to monitor CPU usage and only report a
11335 relative weight and never interact with the operating status. Similarly, an
11336 agent could be designed as an end-user interface with 3 radio buttons
11337 allowing an administrator to change only the administrative state. However,
11338 it is important to consider that only the agent may revert its own actions,
11339 so if a server is set to DRAIN mode or to DOWN state using the agent, the
11340 agent must implement the other equivalent actions to bring the service into
11341 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +090011342
Simon Horman2f1f9552013-11-25 10:46:37 +090011343 Failure to connect to the agent is not considered an error as connectivity
11344 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +010011345 parameter. Warning though, it is not a good idea to stop an agent after it
11346 reports "down", since only an agent reporting "up" will be able to turn the
11347 server up again. Note that the CLI on the Unix stats socket is also able to
Willy Tarreau989222a2016-01-15 10:26:26 +010011348 force an agent's result in order to work around a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +090011349
Willy Tarreau81f5d942013-12-09 20:51:51 +010011350 Requires the "agent-port" parameter to be set. See also the "agent-inter"
Frédéric Lécailled2376272017-03-21 18:52:12 +010011351 and "no-agent-check" parameters.
Simon Hormand60d6912013-11-25 10:46:36 +090011352
James Brown55f9ff12015-10-21 18:19:05 -070011353agent-send <string>
11354 If this option is specified, haproxy will send the given string (verbatim)
11355 to the agent server upon connection. You could, for example, encode
11356 the backend name into this string, which would enable your agent to send
11357 different responses based on the backend. Make sure to include a '\n' if
11358 you want to terminate your request with a newline.
11359
Simon Hormand60d6912013-11-25 10:46:36 +090011360agent-inter <delay>
11361 The "agent-inter" parameter sets the interval between two agent checks
11362 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
11363
11364 Just as with every other time-based parameter, it may be entered in any
11365 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
11366 parameter also serves as a timeout for agent checks "timeout check" is
11367 not set. In order to reduce "resonance" effects when multiple servers are
11368 hosted on the same hardware, the agent and health checks of all servers
11369 are started with a small time offset between them. It is also possible to
11370 add some random noise in the agent and health checks interval using the
11371 global "spread-checks" keyword. This makes sense for instance when a lot
11372 of backends use the same servers.
11373
11374 See also the "agent-check" and "agent-port" parameters.
11375
Misiek768d8602017-01-09 09:52:43 +010011376agent-addr <addr>
11377 The "agent-addr" parameter sets address for agent check.
11378
11379 You can offload agent-check to another target, so you can make single place
11380 managing status and weights of servers defined in haproxy in case you can't
11381 make self-aware and self-managing services. You can specify both IP or
11382 hostname, it will be resolved.
11383
Simon Hormand60d6912013-11-25 10:46:36 +090011384agent-port <port>
11385 The "agent-port" parameter sets the TCP port used for agent checks.
11386
11387 See also the "agent-check" and "agent-inter" parameters.
11388
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011389backup
11390 When "backup" is present on a server line, the server is only used in load
11391 balancing when all other non-backup servers are unavailable. Requests coming
11392 with a persistence cookie referencing the server will always be served
11393 though. By default, only the first operational backup server is used, unless
Frédéric Lécailled2376272017-03-21 18:52:12 +010011394 the "allbackups" option is set in the backend. See also the "no-backup" and
11395 "allbackups" options.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011396
Emeric Brunef42d922012-10-11 16:11:36 +020011397ca-file <cafile>
11398 This setting is only available when support for OpenSSL was built in. It
11399 designates a PEM file from which to load CA certificates used to verify
11400 server's certificate.
11401
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011402check
11403 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +010011404 always considered available. If "check" is set, the server is available when
11405 accepting periodic TCP connections, to ensure that it is really able to serve
11406 requests. The default address and port to send the tests to are those of the
11407 server, and the default source is the same as the one defined in the
11408 backend. It is possible to change the address using the "addr" parameter, the
11409 port using the "port" parameter, the source address using the "source"
11410 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormanafc47ee2013-11-25 10:46:35 +090011411 parameters. The request method is define in the backend using the "httpchk",
11412 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
Frédéric Lécailled2376272017-03-21 18:52:12 +010011413 refer to those options and parameters for more information. See also
11414 "no-check" option.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011415
Willy Tarreau6c16adc2012-10-05 00:04:16 +020011416check-send-proxy
11417 This option forces emission of a PROXY protocol line with outgoing health
11418 checks, regardless of whether the server uses send-proxy or not for the
11419 normal traffic. By default, the PROXY protocol is enabled for health checks
11420 if it is already enabled for normal traffic and if no "port" nor "addr"
11421 directive is present. However, if such a directive is present, the
11422 "check-send-proxy" option needs to be used to force the use of the
11423 protocol. See also the "send-proxy" option for more information.
11424
Olivier Houchard9130a962017-10-17 17:33:43 +020011425check-sni
11426 This option allows you to specify the SNI to be used when doing health checks
11427 over SSL.
11428
Willy Tarreau763a95b2012-10-04 23:15:39 +020011429check-ssl
11430 This option forces encryption of all health checks over SSL, regardless of
11431 whether the server uses SSL or not for the normal traffic. This is generally
11432 used when an explicit "port" or "addr" directive is specified and SSL health
11433 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011434 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +020011435 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
11436 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
Davor Ocelice9ed2812017-12-25 17:49:28 +010011437 All SSL settings are common to health checks and traffic (e.g. ciphers).
Frédéric Lécailled2376272017-03-21 18:52:12 +010011438 See the "ssl" option for more information and "no-check-ssl" to disable
11439 this option.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011440
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011441ciphers <ciphers>
Dirkjan Bussink415150f2018-09-14 11:14:21 +020011442 This setting is only available when support for OpenSSL was built in. This
11443 option sets the string describing the list of cipher algorithms that is
11444 negotiated during the SSL/TLS handshake with the server. The format of the
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011445 string is defined in "man 1 ciphers". When SSL is used to communicate with
11446 servers on the local network, it is common to see a weaker set of algorithms
11447 than what is used over the internet. Doing so reduces CPU usage on both the
11448 server and haproxy while still keeping it compatible with deployed software.
11449 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
11450 is needed and just connectivity, using DES can be appropriate.
11451
Dirkjan Bussink415150f2018-09-14 11:14:21 +020011452ciphersuites <ciphersuites>
11453 This setting is only available when support for OpenSSL was built in and
11454 OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string
11455 describing the list of cipher algorithms that is negotiated during the TLS
11456 1.3 handshake with the server. The format of the string is defined in
11457 "man 1 ciphers" under the "ciphersuites" section.
11458
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011459cookie <value>
11460 The "cookie" parameter sets the cookie value assigned to the server to
11461 <value>. This value will be checked in incoming requests, and the first
11462 operational server possessing the same value will be selected. In return, in
11463 cookie insertion or rewrite modes, this value will be assigned to the cookie
11464 sent to the client. There is nothing wrong in having several servers sharing
11465 the same cookie value, and it is in fact somewhat common between normal and
11466 backup servers. See also the "cookie" keyword in backend section.
11467
Emeric Brunef42d922012-10-11 16:11:36 +020011468crl-file <crlfile>
11469 This setting is only available when support for OpenSSL was built in. It
11470 designates a PEM file from which to load certificate revocation list used
11471 to verify server's certificate.
11472
Emeric Bruna7aa3092012-10-26 12:58:00 +020011473crt <cert>
11474 This setting is only available when support for OpenSSL was built in.
11475 It designates a PEM file from which to load both a certificate and the
11476 associated private key. This file can be built by concatenating both PEM
11477 files into one. This certificate will be sent if the server send a client
11478 certificate request.
11479
Willy Tarreau96839092010-03-29 10:02:24 +020011480disabled
11481 The "disabled" keyword starts the server in the "disabled" state. That means
11482 that it is marked down in maintenance mode, and no connection other than the
11483 ones allowed by persist mode will reach it. It is very well suited to setup
11484 new servers, because normal traffic will never reach them, while it is still
11485 possible to test the service by making use of the force-persist mechanism.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011486 See also "enabled" setting.
Willy Tarreau96839092010-03-29 10:02:24 +020011487
Frédéric Lécailled2376272017-03-21 18:52:12 +010011488enabled
11489 This option may be used as 'server' setting to reset any 'disabled'
11490 setting which would have been inherited from 'default-server' directive as
11491 default value.
11492 It may also be used as 'default-server' setting to reset any previous
11493 'default-server' 'disabled' setting.
Willy Tarreau96839092010-03-29 10:02:24 +020011494
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011495error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +010011496 If health observing is enabled, the "error-limit" parameter specifies the
11497 number of consecutive errors that triggers event selected by the "on-error"
11498 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011499
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011500 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011501
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011502fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011503 The "fall" parameter states that a server will be considered as dead after
11504 <count> consecutive unsuccessful health checks. This value defaults to 3 if
11505 unspecified. See also the "check", "inter" and "rise" parameters.
11506
Emeric Brun8694b9a2012-10-05 14:39:07 +020011507force-sslv3
11508 This option enforces use of SSLv3 only when SSL is used to communicate with
11509 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011510 high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011511 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011512
11513force-tlsv10
11514 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011515 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011516 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011517
11518force-tlsv11
11519 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011520 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011521 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011522
11523force-tlsv12
11524 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011525 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011526 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011527
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011528force-tlsv13
11529 This option enforces use of TLSv1.3 only when SSL is used to communicate with
11530 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011531 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011532
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011533id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +020011534 Set a persistent ID for the server. This ID must be positive and unique for
11535 the proxy. An unused ID will automatically be assigned if unset. The first
11536 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011537
Willy Tarreau6a031d12016-11-07 19:42:35 +010011538init-addr {last | libc | none | <ip>},[...]*
11539 Indicate in what order the server's address should be resolved upon startup
11540 if it uses an FQDN. Attempts are made to resolve the address by applying in
Davor Ocelice9ed2812017-12-25 17:49:28 +010011541 turn each of the methods mentioned in the comma-delimited list. The first
Willy Tarreau6a031d12016-11-07 19:42:35 +010011542 method which succeeds is used. If the end of the list is reached without
11543 finding a working method, an error is thrown. Method "last" suggests to pick
11544 the address which appears in the state file (see "server-state-file"). Method
11545 "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
11546 depending on the operating system and build options). Method "none"
11547 specifically indicates that the server should start without any valid IP
11548 address in a down state. It can be useful to ignore some DNS issues upon
11549 startup, waiting for the situation to get fixed later. Finally, an IP address
11550 (IPv4 or IPv6) may be provided. It can be the currently known address of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011551 server (e.g. filled by a configuration generator), or the address of a dummy
Willy Tarreau6a031d12016-11-07 19:42:35 +010011552 server used to catch old sessions and present them with a decent error
11553 message for example. When the "first" load balancing algorithm is used, this
11554 IP address could point to a fake server used to trigger the creation of new
11555 instances on the fly. This option defaults to "last,libc" indicating that the
11556 previous address found in the state file (if any) is used first, otherwise
11557 the libc's resolver is used. This ensures continued compatibility with the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011558 historic behavior.
Willy Tarreau6a031d12016-11-07 19:42:35 +010011559
11560 Example:
11561 defaults
11562 # never fail on address resolution
11563 default-server init-addr last,libc,none
11564
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011565inter <delay>
11566fastinter <delay>
11567downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011568 The "inter" parameter sets the interval between two consecutive health checks
11569 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
11570 It is also possible to use "fastinter" and "downinter" to optimize delays
11571 between checks depending on the server state :
11572
Pieter Baauw44fc9df2015-09-17 21:30:46 +020011573 Server state | Interval used
11574 ----------------------------------------+----------------------------------
11575 UP 100% (non-transitional) | "inter"
11576 ----------------------------------------+----------------------------------
11577 Transitionally UP (going down "fall"), | "fastinter" if set,
11578 Transitionally DOWN (going up "rise"), | "inter" otherwise.
11579 or yet unchecked. |
11580 ----------------------------------------+----------------------------------
11581 DOWN 100% (non-transitional) | "downinter" if set,
11582 | "inter" otherwise.
11583 ----------------------------------------+----------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +010011584
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011585 Just as with every other time-based parameter, they can be entered in any
11586 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
11587 serves as a timeout for health checks sent to servers if "timeout check" is
11588 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +090011589 hosted on the same hardware, the agent and health checks of all servers
11590 are started with a small time offset between them. It is also possible to
11591 add some random noise in the agent and health checks interval using the
11592 global "spread-checks" keyword. This makes sense for instance when a lot
11593 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011594
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011595maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011596 The "maxconn" parameter specifies the maximal number of concurrent
11597 connections that will be sent to this server. If the number of incoming
11598 concurrent requests goes higher than this value, they will be queued, waiting
11599 for a connection to be released. This parameter is very important as it can
11600 save fragile servers from going down under extreme loads. If a "minconn"
11601 parameter is specified, the limit becomes dynamic. The default value is "0"
11602 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
11603 the backend's "fullconn" keyword.
11604
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011605maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011606 The "maxqueue" parameter specifies the maximal number of connections which
11607 will wait in the queue for this server. If this limit is reached, next
11608 requests will be redispatched to other servers instead of indefinitely
11609 waiting to be served. This will break persistence but may allow people to
11610 quickly re-log in when the server they try to connect to is dying. The
11611 default value is "0" which means the queue is unlimited. See also the
11612 "maxconn" and "minconn" parameters.
11613
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011614minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011615 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
11616 limit following the backend's load. The server will always accept at least
11617 <minconn> connections, never more than <maxconn>, and the limit will be on
11618 the ramp between both values when the backend has less than <fullconn>
11619 concurrent connections. This makes it possible to limit the load on the
11620 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011621 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011622 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011623
Willy Tarreaud72f0f32015-10-13 14:50:22 +020011624namespace <name>
11625 On Linux, it is possible to specify which network namespace a socket will
11626 belong to. This directive makes it possible to explicitly bind a server to
11627 a namespace different from the default one. Please refer to your operating
11628 system's documentation to find more details about network namespaces.
11629
Frédéric Lécailled2376272017-03-21 18:52:12 +010011630no-agent-check
11631 This option may be used as "server" setting to reset any "agent-check"
11632 setting which would have been inherited from "default-server" directive as
11633 default value.
11634 It may also be used as "default-server" setting to reset any previous
11635 "default-server" "agent-check" setting.
11636
11637no-backup
11638 This option may be used as "server" setting to reset any "backup"
11639 setting which would have been inherited from "default-server" directive as
11640 default value.
11641 It may also be used as "default-server" setting to reset any previous
11642 "default-server" "backup" setting.
11643
11644no-check
11645 This option may be used as "server" setting to reset any "check"
11646 setting which would have been inherited from "default-server" directive as
11647 default value.
11648 It may also be used as "default-server" setting to reset any previous
11649 "default-server" "check" setting.
11650
11651no-check-ssl
11652 This option may be used as "server" setting to reset any "check-ssl"
11653 setting which would have been inherited from "default-server" directive as
11654 default value.
11655 It may also be used as "default-server" setting to reset any previous
11656 "default-server" "check-ssl" setting.
11657
Frédéric Lécailled2376272017-03-21 18:52:12 +010011658no-send-proxy
11659 This option may be used as "server" setting to reset any "send-proxy"
11660 setting which would have been inherited from "default-server" directive as
11661 default value.
11662 It may also be used as "default-server" setting to reset any previous
11663 "default-server" "send-proxy" setting.
11664
11665no-send-proxy-v2
11666 This option may be used as "server" setting to reset any "send-proxy-v2"
11667 setting which would have been inherited from "default-server" directive as
11668 default value.
11669 It may also be used as "default-server" setting to reset any previous
11670 "default-server" "send-proxy-v2" setting.
11671
11672no-send-proxy-v2-ssl
11673 This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
11674 setting which would have been inherited from "default-server" directive as
11675 default value.
11676 It may also be used as "default-server" setting to reset any previous
11677 "default-server" "send-proxy-v2-ssl" setting.
11678
11679no-send-proxy-v2-ssl-cn
11680 This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
11681 setting which would have been inherited from "default-server" directive as
11682 default value.
11683 It may also be used as "default-server" setting to reset any previous
11684 "default-server" "send-proxy-v2-ssl-cn" setting.
11685
11686no-ssl
11687 This option may be used as "server" setting to reset any "ssl"
11688 setting which would have been inherited from "default-server" directive as
11689 default value.
11690 It may also be used as "default-server" setting to reset any previous
11691 "default-server" "ssl" setting.
11692
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010011693no-ssl-reuse
11694 This option disables SSL session reuse when SSL is used to communicate with
11695 the server. It will force the server to perform a full handshake for every
11696 new connection. It's probably only useful for benchmarking, troubleshooting,
11697 and for paranoid users.
11698
Emeric Brun9b3009b2012-10-05 11:55:06 +020011699no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011700 This option disables support for SSLv3 when SSL is used to communicate with
11701 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011702 using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011703
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011704 Supported in default-server: No
11705
Emeric Brunf9c5c472012-10-11 15:28:34 +020011706no-tls-tickets
11707 This setting is only available when support for OpenSSL was built in. It
11708 disables the stateless session resumption (RFC 5077 TLS Ticket
11709 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011710 session resumption is more expensive in CPU usage for servers. This option
11711 is also available on global statement "ssl-default-server-options".
Frédéric Lécailled2376272017-03-21 18:52:12 +010011712 See also "tls-tickets".
Emeric Brunf9c5c472012-10-11 15:28:34 +020011713
Emeric Brun9b3009b2012-10-05 11:55:06 +020011714no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020011715 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020011716 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11717 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011718 often makes sense to disable it when communicating with local servers. This
11719 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011720 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011721
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011722 Supported in default-server: No
11723
Emeric Brun9b3009b2012-10-05 11:55:06 +020011724no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020011725 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020011726 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11727 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011728 often makes sense to disable it when communicating with local servers. This
11729 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011730 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011731
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011732 Supported in default-server: No
11733
Emeric Brun9b3009b2012-10-05 11:55:06 +020011734no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020011735 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011736 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11737 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011738 often makes sense to disable it when communicating with local servers. This
11739 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011740 Use "ssl-min-ver" and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011741
11742 Supported in default-server: No
11743
11744no-tlsv13
11745 This option disables support for TLSv1.3 when SSL is used to communicate with
11746 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11747 using any configuration option. TLSv1 is more expensive than SSLv3 so it
11748 often makes sense to disable it when communicating with local servers. This
11749 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011750 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011751
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011752 Supported in default-server: No
11753
Frédéric Lécailled2376272017-03-21 18:52:12 +010011754no-verifyhost
11755 This option may be used as "server" setting to reset any "verifyhost"
11756 setting which would have been inherited from "default-server" directive as
11757 default value.
11758 It may also be used as "default-server" setting to reset any previous
11759 "default-server" "verifyhost" setting.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011760
Simon Hormanfa461682011-06-25 09:39:49 +090011761non-stick
11762 Never add connections allocated to this sever to a stick-table.
11763 This may be used in conjunction with backup to ensure that
11764 stick-table persistence is disabled for backup servers.
11765
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011766observe <mode>
11767 This option enables health adjusting based on observing communication with
11768 the server. By default this functionality is disabled and enabling it also
11769 requires to enable health checks. There are two supported modes: "layer4" and
11770 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
11771 significant. In layer7, which is only allowed for http proxies, responses
11772 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010011773 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011774
11775 See also the "check", "on-error" and "error-limit".
11776
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011777on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011778 Select what should happen when enough consecutive errors are detected.
11779 Currently, four modes are available:
11780 - fastinter: force fastinter
11781 - fail-check: simulate a failed check, also forces fastinter (default)
11782 - sudden-death: simulate a pre-fatal failed health check, one more failed
11783 check will mark a server down, forces fastinter
11784 - mark-down: mark the server immediately down and force fastinter
11785
11786 See also the "check", "observe" and "error-limit".
11787
Simon Hormane0d1bfb2011-06-21 14:34:58 +090011788on-marked-down <action>
11789 Modify what occurs when a server is marked down.
11790 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011791 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
11792 all connections to the server are immediately terminated when the server
11793 goes down. It might be used if the health check detects more complex cases
11794 than a simple connection status, and long timeouts would cause the service
11795 to remain unresponsive for too long a time. For instance, a health check
11796 might detect that a database is stuck and that there's no chance to reuse
11797 existing connections anymore. Connections killed this way are logged with
11798 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090011799
11800 Actions are disabled by default
11801
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011802on-marked-up <action>
11803 Modify what occurs when a server is marked up.
11804 Currently one action is available:
11805 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
11806 done only if the server is not in backup state and if it is not disabled
11807 (it must have an effective weight > 0). This can be used sometimes to force
11808 an active server to take all the traffic back after recovery when dealing
Davor Ocelice9ed2812017-12-25 17:49:28 +010011809 with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble
11810 than it tries to solve (e.g. incomplete transactions), so use this feature
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011811 with extreme care. Sessions killed because a server comes up are logged
11812 with an 'U' termination code (for "Up").
11813
11814 Actions are disabled by default
11815
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011816port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011817 Using the "port" parameter, it becomes possible to use a different port to
11818 send health-checks. On some servers, it may be desirable to dedicate a port
11819 to a specific component able to perform complex tests which are more suitable
11820 to health-checks than the application. It is common to run a simple script in
11821 inetd for instance. This parameter is ignored if the "check" parameter is not
11822 set. See also the "addr" parameter.
11823
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020011824proto <name>
11825
11826 Forces the multiplexer's protocol to use for the outgoing connections to this
11827 server. It must be compatible with the mode of the backend (TCP or HTTP). It
11828 must also be usable on the backend side. The list of available protocols is
11829 reported in haproxy -vv.
11830 Idea behind this optipon is to bypass the selection of the best multiplexer's
11831 protocol for all connections established to this server.
11832
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011833redir <prefix>
11834 The "redir" parameter enables the redirection mode for all GET and HEAD
11835 requests addressing this server. This means that instead of having HAProxy
11836 forward the request to the server, it will send an "HTTP 302" response with
11837 the "Location" header composed of this prefix immediately followed by the
11838 requested URI beginning at the leading '/' of the path component. That means
11839 that no trailing slash should be used after <prefix>. All invalid requests
11840 will be rejected, and all non-GET or HEAD requests will be normally served by
11841 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011842 mangling nor cookie insertion is possible in the response. However, cookies in
Davor Ocelice9ed2812017-12-25 17:49:28 +010011843 requests are still analyzed, making this solution completely usable to direct
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011844 users to a remote location in case of local disaster. Main use consists in
11845 increasing bandwidth for static servers by having the clients directly
11846 connect to them. Note: never use a relative location here, it would cause a
11847 loop between the client and HAProxy!
11848
11849 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
11850
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011851rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011852 The "rise" parameter states that a server will be considered as operational
11853 after <count> consecutive successful health checks. This value defaults to 2
11854 if unspecified. See also the "check", "inter" and "fall" parameters.
11855
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020011856resolve-opts <option>,<option>,...
11857 Comma separated list of options to apply to DNS resolution linked to this
11858 server.
11859
11860 Available options:
11861
11862 * allow-dup-ip
11863 By default, HAProxy prevents IP address duplication in a backend when DNS
11864 resolution at runtime is in operation.
11865 That said, for some cases, it makes sense that two servers (in the same
11866 backend, being resolved by the same FQDN) have the same IP address.
11867 For such case, simply enable this option.
11868 This is the opposite of prevent-dup-ip.
11869
11870 * prevent-dup-ip
11871 Ensure HAProxy's default behavior is enforced on a server: prevent re-using
11872 an IP address already set to a server in the same backend and sharing the
11873 same fqdn.
11874 This is the opposite of allow-dup-ip.
11875
11876 Example:
11877 backend b_myapp
11878 default-server init-addr none resolvers dns
11879 server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
11880 server s2 myapp.example.com:81 check resolve-opts allow-dup-ip
11881
11882 With the option allow-dup-ip set:
11883 * if the nameserver returns a single IP address, then both servers will use
11884 it
11885 * If the nameserver returns 2 IP addresses, then each server will pick up a
11886 different address
11887
11888 Default value: not set
11889
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011890resolve-prefer <family>
11891 When DNS resolution is enabled for a server and multiple IP addresses from
11892 different families are returned, HAProxy will prefer using an IP address
11893 from the family mentioned in the "resolve-prefer" parameter.
11894 Available families: "ipv4" and "ipv6"
11895
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020011896 Default value: ipv6
11897
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011898 Example:
11899
11900 server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011901
Thierry Fournierac88cfe2016-02-17 22:05:30 +010011902resolve-net <network>[,<network[,...]]
11903 This options prioritize th choice of an ip address matching a network. This is
11904 useful with clouds to prefer a local ip. In some cases, a cloud high
Tim Düsterhus4896c442016-11-29 02:15:19 +010011905 availability service can be announced with many ip addresses on many
Davor Ocelice9ed2812017-12-25 17:49:28 +010011906 different datacenters. The latency between datacenter is not negligible, so
11907 this patch permits to prefer a local datacenter. If no address matches the
Thierry Fournierac88cfe2016-02-17 22:05:30 +010011908 configured network, another address is selected.
11909
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011910 Example:
11911
11912 server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8
Thierry Fournierac88cfe2016-02-17 22:05:30 +010011913
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011914resolvers <id>
11915 Points to an existing "resolvers" section to resolve current server's
11916 hostname.
11917
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011918 Example:
11919
11920 server s1 app1.domain.com:80 check resolvers mydns
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011921
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011922 See also section 5.3
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011923
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010011924send-proxy
11925 The "send-proxy" parameter enforces use of the PROXY protocol over any
11926 connection established to this server. The PROXY protocol informs the other
11927 end about the layer 3/4 addresses of the incoming connection, so that it can
11928 know the client's address or the public address it accessed to, whatever the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010011929 upper layer protocol. For connections accepted by an "accept-proxy" or
11930 "accept-netscaler-cip" listener, the advertised address will be used. Only
11931 TCPv4 and TCPv6 address families are supported. Other families such as
11932 Unix sockets, will report an UNKNOWN family. Servers using this option can
11933 fully be chained to another instance of haproxy listening with an
11934 "accept-proxy" setting. This setting must not be used if the server isn't
11935 aware of the protocol. When health checks are sent to the server, the PROXY
11936 protocol is automatically used when this option is set, unless there is an
11937 explicit "port" or "addr" directive, in which case an explicit
11938 "check-send-proxy" directive would also be needed to use the PROXY protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011939 See also the "no-send-proxy" option of this section and "accept-proxy" and
11940 "accept-netscaler-cip" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010011941
David Safb76832014-05-08 23:42:08 -040011942send-proxy-v2
11943 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
11944 over any connection established to this server. The PROXY protocol informs
11945 the other end about the layer 3/4 addresses of the incoming connection, so
11946 that it can know the client's address or the public address it accessed to,
Emmanuel Hocdet404d9782017-10-24 10:55:14 +020011947 whatever the upper layer protocol. It also send ALPN information if an alpn
11948 have been negotiated. This setting must not be used if the server isn't aware
11949 of this version of the protocol. See also the "no-send-proxy-v2" option of
11950 this section and send-proxy" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040011951
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010011952proxy-v2-options <option>[,<option>]*
11953 The "proxy-v2-options" parameter add option to send in PROXY protocol version
11954 2 when "send-proxy-v2" is used. Options available are "ssl" (see also
Emmanuel Hocdetfa8d0f12018-02-01 15:53:52 +010011955 send-proxy-v2-ssl), "cert-cn" (see also "send-proxy-v2-ssl-cn"), "ssl-cipher":
11956 name of the used cipher, "cert-sig": signature algorithm of the used
Emmanuel Hocdet253c3b72018-02-01 18:29:59 +010011957 certificate, "cert-key": key algorithm of the used certificate), "authority":
11958 host name value passed by the client (only sni from a tls connection is
Emmanuel Hocdet4399c752018-02-05 15:26:43 +010011959 supported), "crc32c": checksum of the proxy protocol v2 header.
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010011960
David Safb76832014-05-08 23:42:08 -040011961send-proxy-v2-ssl
11962 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
11963 2 over any connection established to this server. The PROXY protocol informs
11964 the other end about the layer 3/4 addresses of the incoming connection, so
11965 that it can know the client's address or the public address it accessed to,
11966 whatever the upper layer protocol. In addition, the SSL information extension
11967 of the PROXY protocol is added to the PROXY protocol header. This setting
11968 must not be used if the server isn't aware of this version of the protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011969 See also the "no-send-proxy-v2-ssl" option of this section and the
11970 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040011971
11972send-proxy-v2-ssl-cn
11973 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
11974 2 over any connection established to this server. The PROXY protocol informs
11975 the other end about the layer 3/4 addresses of the incoming connection, so
11976 that it can know the client's address or the public address it accessed to,
11977 whatever the upper layer protocol. In addition, the SSL information extension
11978 of the PROXY protocol, along along with the Common Name from the subject of
11979 the client certificate (if any), is added to the PROXY protocol header. This
11980 setting must not be used if the server isn't aware of this version of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011981 protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and
11982 the "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040011983
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011984slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011985 The "slowstart" parameter for a server accepts a value in milliseconds which
11986 indicates after how long a server which has just come back up will run at
11987 full speed. Just as with every other time-based parameter, it can be entered
11988 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
11989 linearly from 0 to 100% during this time. The limitation applies to two
11990 parameters :
11991
11992 - maxconn: the number of connections accepted by the server will grow from 1
11993 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
11994
11995 - weight: when the backend uses a dynamic weighted algorithm, the weight
11996 grows linearly from 1 to 100%. In this case, the weight is updated at every
11997 health-check. For this reason, it is important that the "inter" parameter
11998 is smaller than the "slowstart", in order to maximize the number of steps.
11999
12000 The slowstart never applies when haproxy starts, otherwise it would cause
12001 trouble to running servers. It only applies when a server has been previously
12002 seen as failed.
12003
Willy Tarreau732eac42015-07-09 11:40:25 +020012004sni <expression>
12005 The "sni" parameter evaluates the sample fetch expression, converts it to a
12006 string and uses the result as the host name sent in the SNI TLS extension to
12007 the server. A typical use case is to send the SNI received from the client in
12008 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
Willy Tarreau2ab88672017-07-05 18:23:03 +020012009 expression, though alternatives such as req.hdr(host) can also make sense. If
12010 "verify required" is set (which is the recommended setting), the resulting
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012011 name will also be matched against the server certificate's names. See the
12012 "verify" directive for more details.
Willy Tarreau732eac42015-07-09 11:40:25 +020012013
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012014source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020012015source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012016source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012017 The "source" parameter sets the source address which will be used when
12018 connecting to the server. It follows the exact same parameters and principle
12019 as the backend "source" keyword, except that it only applies to the server
12020 referencing it. Please consult the "source" keyword for details.
12021
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012022 Additionally, the "source" statement on a server line allows one to specify a
12023 source port range by indicating the lower and higher bounds delimited by a
12024 dash ('-'). Some operating systems might require a valid IP address when a
12025 source port range is specified. It is permitted to have the same IP/range for
12026 several servers. Doing so makes it possible to bypass the maximum of 64k
12027 total concurrent connections. The limit will then reach 64k connections per
12028 server.
12029
Lukas Tribus7d56c6d2016-09-13 09:51:15 +000012030 Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
12031 specifying the source address without port(s).
12032
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012033ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020012034 This option enables SSL ciphering on outgoing connections to the server. It
12035 is critical to verify server certificates using "verify" when using SSL to
12036 connect to servers, otherwise the communication is prone to trivial man in
12037 the-middle attacks rendering SSL useless. When this option is used, health
12038 checks are automatically sent in SSL too unless there is a "port" or an
12039 "addr" directive indicating the check should be sent to a different location.
Frédéric Lécailled2376272017-03-21 18:52:12 +010012040 See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
12041 SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012042
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012043ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12044 This option enforces use of <version> or lower when SSL is used to communicate
12045 with the server. This option is also available on global statement
12046 "ssl-default-server-options". See also "ssl-min-ver".
12047
12048ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12049 This option enforces use of <version> or upper when SSL is used to communicate
12050 with the server. This option is also available on global statement
12051 "ssl-default-server-options". See also "ssl-max-ver".
12052
Frédéric Lécailled2376272017-03-21 18:52:12 +010012053ssl-reuse
12054 This option may be used as "server" setting to reset any "no-ssl-reuse"
12055 setting which would have been inherited from "default-server" directive as
12056 default value.
12057 It may also be used as "default-server" setting to reset any previous
12058 "default-server" "no-ssl-reuse" setting.
12059
12060stick
12061 This option may be used as "server" setting to reset any "non-stick"
12062 setting which would have been inherited from "default-server" directive as
12063 default value.
12064 It may also be used as "default-server" setting to reset any previous
12065 "default-server" "non-stick" setting.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012066
Willy Tarreau163d4622015-10-13 16:16:41 +020012067tcp-ut <delay>
12068 Sets the TCP User Timeout for all outgoing connections to this server. This
12069 option is available on Linux since version 2.6.37. It allows haproxy to
12070 configure a timeout for sockets which contain data not receiving an
Davor Ocelice9ed2812017-12-25 17:49:28 +010012071 acknowledgment for the configured delay. This is especially useful on
Willy Tarreau163d4622015-10-13 16:16:41 +020012072 long-lived connections experiencing long idle periods such as remote
12073 terminals or database connection pools, where the client and server timeouts
12074 must remain high to allow a long period of idle, but where it is important to
12075 detect that the server has disappeared in order to release all resources
12076 associated with its connection (and the client's session). One typical use
12077 case is also to force dead server connections to die when health checks are
12078 too slow or during a soft reload since health checks are then disabled. The
12079 argument is a delay expressed in milliseconds by default. This only works for
12080 regular TCP connections, and is ignored for other protocols.
12081
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012082track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020012083 This option enables ability to set the current state of the server by tracking
12084 another one. It is possible to track a server which itself tracks another
12085 server, provided that at the end of the chain, a server has health checks
12086 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012087 used, it has to be enabled on both proxies.
12088
Frédéric Lécailled2376272017-03-21 18:52:12 +010012089tls-tickets
12090 This option may be used as "server" setting to reset any "no-tls-tickets"
12091 setting which would have been inherited from "default-server" directive as
12092 default value.
12093 It may also be used as "default-server" setting to reset any previous
12094 "default-server" "no-tlsv-tickets" setting.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012095
Emeric Brunef42d922012-10-11 16:11:36 +020012096verify [none|required]
12097 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010012098 to 'none', server certificate is not verified. In the other case, The
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012099 certificate provided by the server is verified using CAs from 'ca-file' and
12100 optional CRLs from 'crl-file' after having checked that the names provided in
Davor Ocelice9ed2812017-12-25 17:49:28 +010012101 the certificate's subject and subjectAlternateNames attributes match either
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012102 the name passed using the "sni" directive, or if not provided, the static
12103 host name passed using the "verifyhost" directive. When no name is found, the
12104 certificate's names are ignored. For this reason, without SNI it's important
12105 to use "verifyhost". On verification failure the handshake is aborted. It is
12106 critically important to verify server certificates when using SSL to connect
12107 to servers, otherwise the communication is prone to trivial man-in-the-middle
12108 attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
12109 the global section, "verify" is set to "required" by default.
Emeric Brunef42d922012-10-11 16:11:36 +020012110
Evan Broderbe554312013-06-27 00:05:25 -070012111verifyhost <hostname>
12112 This setting is only available when support for OpenSSL was built in, and
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012113 only takes effect if 'verify required' is also specified. This directive sets
12114 a default static hostname to check the server's certificate against when no
12115 SNI was used to connect to the server. If SNI is not used, this is the only
12116 way to enable hostname verification. This static hostname, when set, will
12117 also be used for health checks (which cannot provide an SNI value). If none
12118 of the hostnames in the certificate match the specified hostname, the
12119 handshake is aborted. The hostnames in the server-provided certificate may
12120 include wildcards. See also "verify", "sni" and "no-verifyhost" options.
Evan Broderbe554312013-06-27 00:05:25 -070012121
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012122weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012123 The "weight" parameter is used to adjust the server's weight relative to
12124 other servers. All servers will receive a load proportional to their weight
12125 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020012126 load. The default weight is 1, and the maximal value is 256. A value of 0
12127 means the server will not participate in load-balancing but will still accept
12128 persistent connections. If this parameter is used to distribute the load
12129 according to server's capacity, it is recommended to start with values which
12130 can both grow and shrink, for instance between 10 and 100 to leave enough
12131 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012132
12133
Cyril Bonté46175dd2015-07-02 22:45:32 +0200121345.3. Server IP address resolution using DNS
12135-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012136
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012137HAProxy allows using a host name on the server line to retrieve its IP address
12138using name servers. By default, HAProxy resolves the name when parsing the
12139configuration file, at startup and cache the result for the process' life.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012140This is not sufficient in some cases, such as in Amazon where a server's IP
12141can change after a reboot or an ELB Virtual IP can change based on current
12142workload.
12143This chapter describes how HAProxy can be configured to process server's name
12144resolution at run time.
12145Whether run time server name resolution has been enable or not, HAProxy will
12146carry on doing the first resolution when parsing the configuration.
12147
12148
Cyril Bonté46175dd2015-07-02 22:45:32 +0200121495.3.1. Global overview
12150----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012151
12152As we've seen in introduction, name resolution in HAProxy occurs at two
12153different steps of the process life:
12154
12155 1. when starting up, HAProxy parses the server line definition and matches a
12156 host name. It uses libc functions to get the host name resolved. This
12157 resolution relies on /etc/resolv.conf file.
12158
Christopher Faulet67957bd2017-09-27 11:00:59 +020012159 2. at run time, HAProxy performs periodically name resolutions for servers
12160 requiring DNS resolutions.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012161
12162A few other events can trigger a name resolution at run time:
12163 - when a server's health check ends up in a connection timeout: this may be
12164 because the server has a new IP address. So we need to trigger a name
12165 resolution to know this new IP.
12166
Christopher Faulet67957bd2017-09-27 11:00:59 +020012167When using resolvers, the server name can either be a hostname, or a SRV label.
Davor Ocelice9ed2812017-12-25 17:49:28 +010012168HAProxy considers anything that starts with an underscore as a SRV label. If a
Christopher Faulet67957bd2017-09-27 11:00:59 +020012169SRV label is specified, then the corresponding SRV records will be retrieved
12170from the DNS server, and the provided hostnames will be used. The SRV label
12171will be checked periodically, and if any server are added or removed, haproxy
12172will automatically do the same.
Olivier Houchardecfa18d2017-08-07 17:30:03 +020012173
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012174A few things important to notice:
12175 - all the name servers are queried in the mean time. HAProxy will process the
12176 first valid response.
12177
12178 - a resolution is considered as invalid (NX, timeout, refused), when all the
12179 servers return an error.
12180
12181
Cyril Bonté46175dd2015-07-02 22:45:32 +0200121825.3.2. The resolvers section
12183----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012184
12185This section is dedicated to host information related to name resolution in
Christopher Faulet67957bd2017-09-27 11:00:59 +020012186HAProxy. There can be as many as resolvers section as needed. Each section can
12187contain many name servers.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012188
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012189When multiple name servers are configured in a resolvers section, then HAProxy
12190uses the first valid response. In case of invalid responses, only the last one
12191is treated. Purpose is to give the chance to a slow server to deliver a valid
12192answer after a fast faulty or outdated server.
12193
12194When each server returns a different error type, then only the last error is
Christopher Faulet67957bd2017-09-27 11:00:59 +020012195used by HAProxy. The following processing is applied on this error:
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012196
Christopher Faulet67957bd2017-09-27 11:00:59 +020012197 1. HAProxy retries the same DNS query with a new query type. The A queries are
12198 switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
12199 errors are also excluded.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012200
Christopher Faulet67957bd2017-09-27 11:00:59 +020012201 2. When the fallback on the query type was done (or not applicable), HAProxy
12202 retries the original DNS query, with the preferred query type.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012203
Christopher Faulet67957bd2017-09-27 11:00:59 +020012204 3. HAProxy retries previous steps <resolve_retires> times. If no valid
12205 response is received after that, it stops the DNS resolution and reports
12206 the error.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012207
Christopher Faulet67957bd2017-09-27 11:00:59 +020012208For example, with 2 name servers configured in a resolvers section, the
12209following scenarios are possible:
12210
12211 - First response is valid and is applied directly, second response is
12212 ignored
12213
12214 - First response is invalid and second one is valid, then second response is
12215 applied
12216
12217 - First response is a NX domain and second one a truncated response, then
12218 HAProxy retries the query with a new type
12219
12220 - First response is a NX domain and second one is a timeout, then HAProxy
12221 retries the query with a new type
12222
12223 - Query timed out for both name servers, then HAProxy retries it with the
12224 same query type
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012225
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012226As a DNS server may not answer all the IPs in one DNS request, haproxy keeps
12227a cache of previous answers, an answer will be considered obsolete after
Christopher Faulet67957bd2017-09-27 11:00:59 +020012228<hold obsolete> seconds without the IP returned.
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012229
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012230
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012231resolvers <resolvers id>
Davor Ocelice9ed2812017-12-25 17:49:28 +010012232 Creates a new name server list labeled <resolvers id>
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012233
12234A resolvers section accept the following parameters:
12235
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020012236accepted_payload_size <nb>
Davor Ocelice9ed2812017-12-25 17:49:28 +010012237 Defines the maximum payload size accepted by HAProxy and announced to all the
Christopher Faulet67957bd2017-09-27 11:00:59 +020012238 name servers configured in this resolvers section.
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020012239 <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
12240 by RFC 6891)
12241
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020012242 Note: the maximum allowed value is 8192.
12243
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012244nameserver <id> <ip>:<port>
12245 DNS server description:
12246 <id> : label of the server, should be unique
12247 <ip> : IP address of the server
12248 <port> : port where the DNS service actually runs
12249
Ben Draut44e609b2018-05-29 15:40:08 -060012250parse-resolv-conf
12251 Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers
12252 list. Ordered as if each nameserver in /etc/resolv.conf was individually
12253 placed in the resolvers section in place of this directive.
12254
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012255hold <status> <period>
12256 Defines <period> during which the last name resolution should be kept based
12257 on last resolution <status>
Baptiste Assmann987e16d2016-11-02 22:23:31 +010012258 <status> : last name resolution status. Acceptable values are "nx",
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012259 "other", "refused", "timeout", "valid", "obsolete".
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012260 <period> : interval between two successive name resolution when the last
12261 answer was in <status>. It follows the HAProxy time format.
12262 <period> is in milliseconds by default.
12263
Baptiste Assmann686408b2017-08-18 10:15:42 +020012264 Default value is 10s for "valid", 0s for "obsolete" and 30s for others.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012265
Christopher Faulet67957bd2017-09-27 11:00:59 +020012266resolution_pool_size <nb> (deprecated)
Baptiste Assmann201c07f2017-05-22 15:17:15 +020012267 Defines the number of resolutions available in the pool for this resolvers.
12268 If not defines, it defaults to 64. If your configuration requires more than
12269 <nb>, then HAProxy will return an error when parsing the configuration.
12270
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012271resolve_retries <nb>
12272 Defines the number <nb> of queries to send to resolve a server name before
12273 giving up.
12274 Default value: 3
12275
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012276 A retry occurs on name server timeout or when the full sequence of DNS query
12277 type failover is over and we need to start up from the default ANY query
12278 type.
12279
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012280timeout <event> <time>
12281 Defines timeouts related to name resolution
12282 <event> : the event on which the <time> timeout period applies to.
12283 events available are:
Christopher Faulet67957bd2017-09-27 11:00:59 +020012284 - resolve : default time to trigger name resolutions when no
12285 other time applied.
12286 Default value: 1s
12287 - retry : time between two DNS queries, when no valid response
12288 have been received.
12289 Default value: 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012290 <time> : time related to the event. It follows the HAProxy time format.
12291 <time> is expressed in milliseconds.
12292
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012293 Example:
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012294
12295 resolvers mydns
12296 nameserver dns1 10.0.0.1:53
12297 nameserver dns2 10.0.0.2:53
Ben Draut44e609b2018-05-29 15:40:08 -060012298 parse-resolv-conf
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012299 resolve_retries 3
Christopher Faulet67957bd2017-09-27 11:00:59 +020012300 timeout resolve 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012301 timeout retry 1s
Baptiste Assmann987e16d2016-11-02 22:23:31 +010012302 hold other 30s
12303 hold refused 30s
12304 hold nx 30s
12305 hold timeout 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012306 hold valid 10s
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012307 hold obsolete 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012308
12309
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200123106. HTTP header manipulation
12311---------------------------
12312
12313In HTTP mode, it is possible to rewrite, add or delete some of the request and
12314response headers based on regular expressions. It is also possible to block a
12315request or a response if a particular header matches a regular expression,
12316which is enough to stop most elementary protocol attacks, and to protect
Willy Tarreau70dffda2014-01-30 03:07:23 +010012317against information leak from the internal network.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012318
Willy Tarreau70dffda2014-01-30 03:07:23 +010012319If HAProxy encounters an "Informational Response" (status code 1xx), it is able
12320to process all rsp* rules which can allow, deny, rewrite or delete a header,
12321but it will refuse to add a header to any such messages as this is not
12322HTTP-compliant. The reason for still processing headers in such responses is to
12323stop and/or fix any possible information leak which may happen, for instance
12324because another downstream equipment would unconditionally add a header, or if
12325a server name appears there. When such messages are seen, normal processing
12326still occurs on the next non-informational messages.
Willy Tarreau816b9792009-09-15 21:25:21 +020012327
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012328This section covers common usage of the following keywords, described in detail
12329in section 4.2 :
12330
12331 - reqadd <string>
12332 - reqallow <search>
12333 - reqiallow <search>
12334 - reqdel <search>
12335 - reqidel <search>
12336 - reqdeny <search>
12337 - reqideny <search>
12338 - reqpass <search>
12339 - reqipass <search>
12340 - reqrep <search> <replace>
12341 - reqirep <search> <replace>
12342 - reqtarpit <search>
12343 - reqitarpit <search>
12344 - rspadd <string>
12345 - rspdel <search>
12346 - rspidel <search>
12347 - rspdeny <search>
12348 - rspideny <search>
12349 - rsprep <search> <replace>
12350 - rspirep <search> <replace>
12351
12352With all these keywords, the same conventions are used. The <search> parameter
12353is a POSIX extended regular expression (regex) which supports grouping through
12354parenthesis (without the backslash). Spaces and other delimiters must be
12355prefixed with a backslash ('\') to avoid confusion with a field delimiter.
12356Other characters may be prefixed with a backslash to change their meaning :
12357
12358 \t for a tab
12359 \r for a carriage return (CR)
12360 \n for a new line (LF)
12361 \ to mark a space and differentiate it from a delimiter
12362 \# to mark a sharp and differentiate it from a comment
12363 \\ to use a backslash in a regex
12364 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
12365 \xXX to write the ASCII hex code XX as in the C language
12366
12367The <replace> parameter contains the string to be used to replace the largest
12368portion of text matching the regex. It can make use of the special characters
12369above, and can reference a substring which is delimited by parenthesis in the
12370regex, by writing a backslash ('\') immediately followed by one digit from 0 to
123719 indicating the group position (0 designating the entire line). This practice
12372is very common to users of the "sed" program.
12373
12374The <string> parameter represents the string which will systematically be added
12375after the last header line. It can also use special character sequences above.
12376
12377Notes related to these keywords :
12378---------------------------------
12379 - these keywords are not always convenient to allow/deny based on header
12380 contents. It is strongly recommended to use ACLs with the "block" keyword
12381 instead, resulting in far more flexible and manageable rules.
12382
12383 - lines are always considered as a whole. It is not possible to reference
12384 a header name only or a value only. This is important because of the way
12385 headers are written (notably the number of spaces after the colon).
12386
12387 - the first line is always considered as a header, which makes it possible to
12388 rewrite or filter HTTP requests URIs or response codes, but in turn makes
12389 it harder to distinguish between headers and request line. The regex prefix
12390 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
12391 ^[^ \t:]*: matches any header name followed by a colon.
12392
12393 - for performances reasons, the number of characters added to a request or to
12394 a response is limited at build time to values between 1 and 4 kB. This
12395 should normally be far more than enough for most usages. If it is too short
12396 on occasional usages, it is possible to gain some space by removing some
12397 useless headers before adding new ones.
12398
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012399 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012400 without the 'i' letter except that they ignore case when matching patterns.
12401
12402 - when a request passes through a frontend then a backend, all req* rules
12403 from the frontend will be evaluated, then all req* rules from the backend
12404 will be evaluated. The reverse path is applied to responses.
12405
12406 - req* statements are applied after "block" statements, so that "block" is
12407 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +010012408 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012409
12410
Willy Tarreau74ca5042013-06-11 23:12:07 +0200124117. Using ACLs and fetching samples
12412----------------------------------
12413
Davor Ocelice9ed2812017-12-25 17:49:28 +010012414HAProxy is capable of extracting data from request or response streams, from
Willy Tarreau74ca5042013-06-11 23:12:07 +020012415client or server information, from tables, environmental information etc...
12416The action of extracting such data is called fetching a sample. Once retrieved,
12417these samples may be used for various purposes such as a key to a stick-table,
12418but most common usages consist in matching them against predefined constant
12419data called patterns.
12420
12421
124227.1. ACL basics
12423---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012424
12425The use of Access Control Lists (ACL) provides a flexible solution to perform
12426content switching and generally to take decisions based on content extracted
12427from the request, the response or any environmental status. The principle is
12428simple :
12429
Willy Tarreau74ca5042013-06-11 23:12:07 +020012430 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012431 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020012432 - apply one or multiple pattern matching methods on this sample
12433 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012434
Willy Tarreau74ca5042013-06-11 23:12:07 +020012435The actions generally consist in blocking a request, selecting a backend, or
12436adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012437
12438In order to define a test, the "acl" keyword is used. The syntax is :
12439
Willy Tarreau74ca5042013-06-11 23:12:07 +020012440 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012441
12442This creates a new ACL <aclname> or completes an existing one with new tests.
12443Those tests apply to the portion of request/response specified in <criterion>
12444and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012445an operator which may be specified before the set of values. Optionally some
12446conversion operators may be applied to the sample, and they will be specified
12447as a comma-delimited list of keywords just after the first keyword. The values
12448are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012449
12450ACL names must be formed from upper and lower case letters, digits, '-' (dash),
12451'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
12452which means that "my_acl" and "My_Acl" are two different ACLs.
12453
12454There is no enforced limit to the number of ACLs. The unused ones do not affect
12455performance, they just consume a small amount of memory.
12456
Willy Tarreau74ca5042013-06-11 23:12:07 +020012457The criterion generally is the name of a sample fetch method, or one of its ACL
12458specific declinations. The default test method is implied by the output type of
12459this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012460methods of a same sample fetch method. The sample fetch methods are the only
12461ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012462
12463Sample fetch methods return data which can be of the following types :
12464 - boolean
12465 - integer (signed or unsigned)
12466 - IPv4 or IPv6 address
12467 - string
12468 - data block
12469
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012470Converters transform any of these data into any of these. For example, some
12471converters might convert a string to a lower-case string while other ones
12472would turn a string to an IPv4 address, or apply a netmask to an IP address.
12473The resulting sample is of the type of the last converter applied to the list,
12474which defaults to the type of the sample fetch method.
12475
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012476Each sample or converter returns data of a specific type, specified with its
12477keyword in this documentation. When an ACL is declared using a standard sample
12478fetch method, certain types automatically involved a default matching method
12479which are summarized in the table below :
12480
12481 +---------------------+-----------------+
12482 | Sample or converter | Default |
12483 | output type | matching method |
12484 +---------------------+-----------------+
12485 | boolean | bool |
12486 +---------------------+-----------------+
12487 | integer | int |
12488 +---------------------+-----------------+
12489 | ip | ip |
12490 +---------------------+-----------------+
12491 | string | str |
12492 +---------------------+-----------------+
12493 | binary | none, use "-m" |
12494 +---------------------+-----------------+
12495
12496Note that in order to match a binary samples, it is mandatory to specify a
12497matching method, see below.
12498
Willy Tarreau74ca5042013-06-11 23:12:07 +020012499The ACL engine can match these types against patterns of the following types :
12500 - boolean
12501 - integer or integer range
12502 - IP address / network
12503 - string (exact, substring, suffix, prefix, subdir, domain)
12504 - regular expression
12505 - hex block
12506
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012507The following ACL flags are currently supported :
12508
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012509 -i : ignore case during matching of all subsequent patterns.
12510 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012511 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012512 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010012513 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010012514 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020012515 -- : force end of flags. Useful when a string looks like one of the flags.
12516
Willy Tarreau74ca5042013-06-11 23:12:07 +020012517The "-f" flag is followed by the name of a file from which all lines will be
12518read as individual values. It is even possible to pass multiple "-f" arguments
12519if the patterns are to be loaded from multiple files. Empty lines as well as
12520lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
12521will be stripped. If it is absolutely necessary to insert a valid pattern
12522beginning with a sharp, just prefix it with a space so that it is not taken for
12523a comment. Depending on the data type and match method, haproxy may load the
12524lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
12525exact string matching. In this case, duplicates will automatically be removed.
12526
Thierry FOURNIER9860c412014-01-29 14:23:29 +010012527The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
12528parsed as two column file. The first column contains the patterns used by the
12529ACL, and the second column contain the samples. The sample can be used later by
12530a map. This can be useful in some rare cases where an ACL would just be used to
12531check for the existence of a pattern in a map before a mapping is applied.
12532
Thierry FOURNIER3534d882014-01-20 17:01:44 +010012533The "-u" flag forces the unique id of the ACL. This unique id is used with the
12534socket interface to identify ACL and dynamically change its values. Note that a
12535file is always identified by its name even if an id is set.
12536
Willy Tarreau74ca5042013-06-11 23:12:07 +020012537Also, note that the "-i" flag applies to subsequent entries and not to entries
12538loaded from files preceding it. For instance :
12539
12540 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
12541
12542In this example, each line of "exact-ua.lst" will be exactly matched against
12543the "user-agent" header of the request. Then each line of "generic-ua" will be
12544case-insensitively matched. Then the word "test" will be insensitively matched
12545as well.
12546
12547The "-m" flag is used to select a specific pattern matching method on the input
12548sample. All ACL-specific criteria imply a pattern matching method and generally
12549do not need this flag. However, this flag is useful with generic sample fetch
12550methods to describe how they're going to be matched against the patterns. This
12551is required for sample fetches which return data type for which there is no
Davor Ocelice9ed2812017-12-25 17:49:28 +010012552obvious matching method (e.g. string or binary). When "-m" is specified and
Willy Tarreau74ca5042013-06-11 23:12:07 +020012553followed by a pattern matching method name, this method is used instead of the
12554default one for the criterion. This makes it possible to match contents in ways
12555that were not initially planned, or with sample fetch methods which return a
12556string. The matching method also affects the way the patterns are parsed.
12557
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012558The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
12559By default, if the parser cannot parse ip address it considers that the parsed
12560string is maybe a domain name and try dns resolution. The flag "-n" disable this
12561resolution. It is useful for detecting malformed ip lists. Note that if the DNS
12562server is not reachable, the haproxy configuration parsing may last many minutes
12563waiting fir the timeout. During this time no error messages are displayed. The
12564flag "-n" disable this behavior. Note also that during the runtime, this
12565function is disabled for the dynamic acl modifications.
12566
Willy Tarreau74ca5042013-06-11 23:12:07 +020012567There are some restrictions however. Not all methods can be used with all
12568sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
12569be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020012570
12571 - "found" : only check if the requested sample could be found in the stream,
12572 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020012573 to pass any pattern to avoid confusion. This matching method is
12574 particularly useful to detect presence of certain contents such
12575 as headers, cookies, etc... even if they are empty and without
12576 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012577
12578 - "bool" : check the value as a boolean. It can only be applied to fetches
12579 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012580 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012581
12582 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020012583 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012584
12585 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020012586 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012587
Davor Ocelice9ed2812017-12-25 17:49:28 +010012588 - "bin" : match the contents against a hexadecimal string representing a
Willy Tarreau5adeda12013-03-31 22:13:34 +020012589 binary sequence. This may be used with binary or string samples.
12590
12591 - "len" : match the sample's length as an integer. This may be used with
12592 binary or string samples.
12593
Willy Tarreau74ca5042013-06-11 23:12:07 +020012594 - "str" : exact match : match the contents against a string. This may be
12595 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012596
Willy Tarreau74ca5042013-06-11 23:12:07 +020012597 - "sub" : substring match : check that the contents contain at least one of
12598 the provided string patterns. This may be used with binary or
12599 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012600
Willy Tarreau74ca5042013-06-11 23:12:07 +020012601 - "reg" : regex match : match the contents against a list of regular
12602 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012603
Willy Tarreau74ca5042013-06-11 23:12:07 +020012604 - "beg" : prefix match : check that the contents begin like the provided
12605 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012606
Willy Tarreau74ca5042013-06-11 23:12:07 +020012607 - "end" : suffix match : check that the contents end like the provided
12608 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012609
Willy Tarreau74ca5042013-06-11 23:12:07 +020012610 - "dir" : subdir match : check that a slash-delimited portion of the
12611 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012612 This may be used with binary or string samples.
12613
Willy Tarreau74ca5042013-06-11 23:12:07 +020012614 - "dom" : domain match : check that a dot-delimited portion of the contents
12615 exactly match one of the provided string patterns. This may be
12616 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012617
12618For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
12619request, it is possible to do :
12620
12621 acl jsess_present cook(JSESSIONID) -m found
12622
12623In order to apply a regular expression on the 500 first bytes of data in the
12624buffer, one would use the following acl :
12625
12626 acl script_tag payload(0,500) -m reg -i <script>
12627
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012628On systems where the regex library is much slower when using "-i", it is
12629possible to convert the sample to lowercase before matching, like this :
12630
12631 acl script_tag payload(0,500),lower -m reg <script>
12632
Willy Tarreau74ca5042013-06-11 23:12:07 +020012633All ACL-specific criteria imply a default matching method. Most often, these
12634criteria are composed by concatenating the name of the original sample fetch
12635method and the matching method. For example, "hdr_beg" applies the "beg" match
12636to samples retrieved using the "hdr" fetch method. Since all ACL-specific
12637criteria rely on a sample fetch method, it is always possible instead to use
12638the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012639
Willy Tarreau74ca5042013-06-11 23:12:07 +020012640If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012641the matching method is simply applied to the underlying sample fetch method.
12642For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012643
Willy Tarreau74ca5042013-06-11 23:12:07 +020012644 acl short_form hdr_beg(host) www.
12645 acl alternate1 hdr_beg(host) -m beg www.
12646 acl alternate2 hdr_dom(host) -m beg www.
12647 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012648
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012649
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012650The table below summarizes the compatibility matrix between sample or converter
12651types and the pattern types to fetch against. It indicates for each compatible
12652combination the name of the matching method to be used, surrounded with angle
12653brackets ">" and "<" when the method is the default one and will work by
12654default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012655
Willy Tarreau74ca5042013-06-11 23:12:07 +020012656 +-------------------------------------------------+
12657 | Input sample type |
12658 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012659 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012660 +----------------------+---------+---------+---------+---------+---------+
12661 | none (presence only) | found | found | found | found | found |
12662 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012663 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012664 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012665 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012666 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012667 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012668 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012669 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012670 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012671 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012672 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012673 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012674 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012675 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012676 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012677 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012678 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012679 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012680 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012681 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012682 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012683 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012684 +----------------------+---------+---------+---------+---------+---------+
12685 | hex block | | | | bin | bin |
12686 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020012687
12688
Willy Tarreau74ca5042013-06-11 23:12:07 +0200126897.1.1. Matching booleans
12690------------------------
12691
12692In order to match a boolean, no value is needed and all values are ignored.
12693Boolean matching is used by default for all fetch methods of type "boolean".
12694When boolean matching is used, the fetched value is returned as-is, which means
12695that a boolean "true" will always match and a boolean "false" will never match.
12696
12697Boolean matching may also be enforced using "-m bool" on fetch methods which
12698return an integer value. Then, integer value 0 is converted to the boolean
12699"false" and all other values are converted to "true".
12700
Willy Tarreau6a06a402007-07-15 20:15:28 +020012701
Willy Tarreau74ca5042013-06-11 23:12:07 +0200127027.1.2. Matching integers
12703------------------------
12704
12705Integer matching applies by default to integer fetch methods. It can also be
12706enforced on boolean fetches using "-m int". In this case, "false" is converted
12707to the integer 0, and "true" is converted to the integer 1.
12708
12709Integer matching also supports integer ranges and operators. Note that integer
12710matching only applies to positive values. A range is a value expressed with a
12711lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012712
12713For instance, "1024:65535" is a valid range to represent a range of
12714unprivileged ports, and "1024:" would also work. "0:1023" is a valid
12715representation of privileged ports, and ":1023" would also work.
12716
Willy Tarreau62644772008-07-16 18:36:06 +020012717As a special case, some ACL functions support decimal numbers which are in fact
12718two integers separated by a dot. This is used with some version checks for
12719instance. All integer properties apply to those decimal numbers, including
12720ranges and operators.
12721
Willy Tarreau6a06a402007-07-15 20:15:28 +020012722For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010012723operators with ranges does not make much sense and is strongly discouraged.
12724Similarly, it does not make much sense to perform order comparisons with a set
12725of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012726
Willy Tarreau0ba27502007-12-24 16:55:16 +010012727Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020012728
12729 eq : true if the tested value equals at least one value
12730 ge : true if the tested value is greater than or equal to at least one value
12731 gt : true if the tested value is greater than at least one value
12732 le : true if the tested value is less than or equal to at least one value
12733 lt : true if the tested value is less than at least one value
12734
Willy Tarreau0ba27502007-12-24 16:55:16 +010012735For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020012736
12737 acl negative-length hdr_val(content-length) lt 0
12738
Willy Tarreau62644772008-07-16 18:36:06 +020012739This one matches SSL versions between 3.0 and 3.1 (inclusive) :
12740
12741 acl sslv3 req_ssl_ver 3:3.1
12742
Willy Tarreau6a06a402007-07-15 20:15:28 +020012743
Willy Tarreau74ca5042013-06-11 23:12:07 +0200127447.1.3. Matching strings
12745-----------------------
12746
12747String matching applies to string or binary fetch methods, and exists in 6
12748different forms :
12749
12750 - exact match (-m str) : the extracted string must exactly match the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012751 patterns;
Willy Tarreau74ca5042013-06-11 23:12:07 +020012752
12753 - substring match (-m sub) : the patterns are looked up inside the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012754 extracted string, and the ACL matches if any of them is found inside;
Willy Tarreau74ca5042013-06-11 23:12:07 +020012755
12756 - prefix match (-m beg) : the patterns are compared with the beginning of
12757 the extracted string, and the ACL matches if any of them matches.
12758
12759 - suffix match (-m end) : the patterns are compared with the end of the
12760 extracted string, and the ACL matches if any of them matches.
12761
Baptiste Assmann33db6002016-03-06 23:32:10 +010012762 - subdir match (-m dir) : the patterns are looked up inside the extracted
Willy Tarreau74ca5042013-06-11 23:12:07 +020012763 string, delimited with slashes ("/"), and the ACL matches if any of them
12764 matches.
12765
12766 - domain match (-m dom) : the patterns are looked up inside the extracted
12767 string, delimited with dots ("."), and the ACL matches if any of them
12768 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012769
12770String matching applies to verbatim strings as they are passed, with the
12771exception of the backslash ("\") which makes it possible to escape some
12772characters such as the space. If the "-i" flag is passed before the first
12773string, then the matching will be performed ignoring the case. In order
12774to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010012775before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020012776
12777
Willy Tarreau74ca5042013-06-11 23:12:07 +0200127787.1.4. Matching regular expressions (regexes)
12779---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020012780
12781Just like with string matching, regex matching applies to verbatim strings as
12782they are passed, with the exception of the backslash ("\") which makes it
12783possible to escape some characters such as the space. If the "-i" flag is
12784passed before the first regex, then the matching will be performed ignoring
12785the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010012786the "--" flag before the first string. Same principle applies of course to
12787match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020012788
12789
Willy Tarreau74ca5042013-06-11 23:12:07 +0200127907.1.5. Matching arbitrary data blocks
12791-------------------------------------
12792
12793It is possible to match some extracted samples against a binary block which may
12794not safely be represented as a string. For this, the patterns must be passed as
12795a series of hexadecimal digits in an even number, when the match method is set
12796to binary. Each sequence of two digits will represent a byte. The hexadecimal
12797digits may be used upper or lower case.
12798
12799Example :
12800 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
12801 acl hello payload(0,6) -m bin 48656c6c6f0a
12802
12803
128047.1.6. Matching IPv4 and IPv6 addresses
12805---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020012806
12807IPv4 addresses values can be specified either as plain addresses or with a
12808netmask appended, in which case the IPv4 address matches whenever it is
12809within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010012810host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010012811difficult to read and debug configurations. If hostnames are used, you should
12812at least ensure that they are present in /etc/hosts so that the configuration
12813does not depend on any random DNS match at the moment the configuration is
12814parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012815
Daniel Schnellereba56342016-04-13 00:26:52 +020012816The dotted IPv4 address notation is supported in both regular as well as the
12817abbreviated form with all-0-octets omitted:
12818
12819 +------------------+------------------+------------------+
12820 | Example 1 | Example 2 | Example 3 |
12821 +------------------+------------------+------------------+
12822 | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 |
12823 | 192.168.1 | 10.12 | 127.1 |
12824 | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 |
12825 | 192.168.1/22 | 10.12/8 | 127.1/8 |
12826 +------------------+------------------+------------------+
12827
12828Notice that this is different from RFC 4632 CIDR address notation in which
12829192.168.42/24 would be equivalent to 192.168.42.0/24.
12830
Willy Tarreauceb4ac92012-04-28 00:41:46 +020012831IPv6 may be entered in their usual form, with or without a netmask appended.
12832Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
12833trouble with randomly resolved IP addresses, host names are never allowed in
12834IPv6 patterns.
12835
12836HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
12837following situations :
12838 - tested address is IPv4, pattern address is IPv4, the match applies
12839 in IPv4 using the supplied mask if any.
12840 - tested address is IPv6, pattern address is IPv6, the match applies
12841 in IPv6 using the supplied mask if any.
12842 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
12843 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
12844 ::IPV4 or ::ffff:IPV4, otherwise it fails.
12845 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
12846 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
12847 applied in IPv6 using the supplied IPv6 mask.
12848
Willy Tarreau74ca5042013-06-11 23:12:07 +020012849
128507.2. Using ACLs to form conditions
12851----------------------------------
12852
12853Some actions are only performed upon a valid condition. A condition is a
12854combination of ACLs with operators. 3 operators are supported :
12855
12856 - AND (implicit)
12857 - OR (explicit with the "or" keyword or the "||" operator)
12858 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020012859
Willy Tarreau74ca5042013-06-11 23:12:07 +020012860A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020012861
Willy Tarreau74ca5042013-06-11 23:12:07 +020012862 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020012863
Willy Tarreau74ca5042013-06-11 23:12:07 +020012864Such conditions are generally used after an "if" or "unless" statement,
12865indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020012866
Willy Tarreau74ca5042013-06-11 23:12:07 +020012867For instance, to block HTTP requests to the "*" URL with methods other than
12868"OPTIONS", as well as POST requests without content-length, and GET or HEAD
12869requests with a content-length greater than 0, and finally every request which
12870is not either GET/HEAD/POST/OPTIONS !
12871
12872 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012873 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
12874 http-request deny if METH_GET HTTP_CONTENT
12875 http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreau74ca5042013-06-11 23:12:07 +020012876
12877To select a different backend for requests to static contents on the "www" site
12878and to every request on the "img", "video", "download" and "ftp" hosts :
12879
12880 acl url_static path_beg /static /images /img /css
12881 acl url_static path_end .gif .png .jpg .css .js
12882 acl host_www hdr_beg(host) -i www
12883 acl host_static hdr_beg(host) -i img. video. download. ftp.
12884
Davor Ocelice9ed2812017-12-25 17:49:28 +010012885 # now use backend "static" for all static-only hosts, and for static URLs
Willy Tarreau74ca5042013-06-11 23:12:07 +020012886 # of host "www". Use backend "www" for the rest.
12887 use_backend static if host_static or host_www url_static
12888 use_backend www if host_www
12889
12890It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
12891expressions that are built on the fly without needing to be declared. They must
12892be enclosed between braces, with a space before and after each brace (because
12893the braces must be seen as independent words). Example :
12894
12895 The following rule :
12896
12897 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012898 http-request deny if METH_POST missing_cl
Willy Tarreau74ca5042013-06-11 23:12:07 +020012899
12900 Can also be written that way :
12901
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012902 http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 }
Willy Tarreau74ca5042013-06-11 23:12:07 +020012903
12904It is generally not recommended to use this construct because it's a lot easier
12905to leave errors in the configuration when written that way. However, for very
12906simple rules matching only one source IP address for instance, it can make more
12907sense to use them than to declare ACLs with random names. Another example of
12908good use is the following :
12909
12910 With named ACLs :
12911
12912 acl site_dead nbsrv(dynamic) lt 2
12913 acl site_dead nbsrv(static) lt 2
12914 monitor fail if site_dead
12915
12916 With anonymous ACLs :
12917
12918 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
12919
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012920See section 4.2 for detailed help on the "http-request deny" and "use_backend"
12921keywords.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012922
12923
129247.3. Fetching samples
12925---------------------
12926
12927Historically, sample fetch methods were only used to retrieve data to match
12928against patterns using ACLs. With the arrival of stick-tables, a new class of
12929sample fetch methods was created, most often sharing the same syntax as their
12930ACL counterpart. These sample fetch methods are also known as "fetches". As
12931of now, ACLs and fetches have converged. All ACL fetch methods have been made
12932available as fetch methods, and ACLs may use any sample fetch method as well.
12933
12934This section details all available sample fetch methods and their output type.
12935Some sample fetch methods have deprecated aliases that are used to maintain
12936compatibility with existing configurations. They are then explicitly marked as
12937deprecated and should not be used in new setups.
12938
12939The ACL derivatives are also indicated when available, with their respective
12940matching methods. These ones all have a well defined default pattern matching
12941method, so it is never necessary (though allowed) to pass the "-m" option to
12942indicate how the sample will be matched using ACLs.
12943
12944As indicated in the sample type versus matching compatibility matrix above,
12945when using a generic sample fetch method in an ACL, the "-m" option is
12946mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
12947the same keyword exists as an ACL keyword and as a standard fetch method, the
12948ACL engine will automatically pick the ACL-only one by default.
12949
12950Some of these keywords support one or multiple mandatory arguments, and one or
12951multiple optional arguments. These arguments are strongly typed and are checked
12952when the configuration is parsed so that there is no risk of running with an
Davor Ocelice9ed2812017-12-25 17:49:28 +010012953incorrect argument (e.g. an unresolved backend name). Fetch function arguments
12954are passed between parenthesis and are delimited by commas. When an argument
Willy Tarreau74ca5042013-06-11 23:12:07 +020012955is optional, it will be indicated below between square brackets ('[ ]'). When
12956all arguments are optional, the parenthesis may be omitted.
12957
12958Thus, the syntax of a standard sample fetch method is one of the following :
12959 - name
12960 - name(arg1)
12961 - name(arg1,arg2)
12962
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012963
129647.3.1. Converters
12965-----------------
12966
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012967Sample fetch methods may be combined with transformations to be applied on top
12968of the fetched sample (also called "converters"). These combinations form what
12969is called "sample expressions" and the result is a "sample". Initially this
12970was only supported by "stick on" and "stick store-request" directives but this
Davor Ocelice9ed2812017-12-25 17:49:28 +010012971has now be extended to all places where samples may be used (ACLs, log-format,
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012972unique-id-format, add-header, ...).
12973
12974These transformations are enumerated as a series of specific keywords after the
12975sample fetch method. These keywords may equally be appended immediately after
12976the fetch keyword's argument, delimited by a comma. These keywords can also
Davor Ocelice9ed2812017-12-25 17:49:28 +010012977support some arguments (e.g. a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010012978
Willy Tarreau97707872015-01-27 15:12:13 +010012979A certain category of converters are bitwise and arithmetic operators which
12980support performing basic operations on integers. Some bitwise operations are
12981supported (and, or, xor, cpl) and some arithmetic operations are supported
12982(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
12983bool) which make it possible to report a match without having to write an ACL.
12984
Willy Tarreau74ca5042013-06-11 23:12:07 +020012985The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010012986
Ben Shillitof25e8e52016-12-02 14:25:37 +00001298751d.single(<prop>[,<prop>*])
12988 Returns values for the properties requested as a string, where values are
12989 separated by the delimiter specified with "51degrees-property-separator".
12990 The device is identified using the User-Agent header passed to the
12991 converter. The function can be passed up to five property names, and if a
12992 property name can't be found, the value "NoData" is returned.
12993
12994 Example :
Davor Ocelice9ed2812017-12-25 17:49:28 +010012995 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request,
12996 # containing values for the three properties requested by using the
Ben Shillitof25e8e52016-12-02 14:25:37 +000012997 # User-Agent passed to the converter.
12998 frontend http-in
12999 bind *:8081
13000 default_backend servers
13001 http-request set-header X-51D-DeviceTypeMobileTablet \
13002 %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
13003
Willy Tarreau97707872015-01-27 15:12:13 +010013004add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013005 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013006 result as a signed integer. <value> can be a numeric value or a variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013007 name. The name of the variable starts with an indication about its scope. The
13008 scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013009 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013010 "sess" : the variable is shared with the whole session
13011 "txn" : the variable is shared with the transaction (request and response)
13012 "req" : the variable is shared only during request processing
13013 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013014 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013015 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013016
13017and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013018 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013019 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010013020 numeric value or a variable name. The name of the variable starts with an
13021 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013022 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013023 "sess" : the variable is shared with the whole session
13024 "txn" : the variable is shared with the transaction (request and response)
13025 "req" : the variable is shared only during request processing
13026 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013027 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013028 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013029
Holger Just1bfc24b2017-05-06 00:56:53 +020013030b64dec
13031 Converts (decodes) a base64 encoded input string to its binary
13032 representation. It performs the inverse operation of base64().
13033
Emeric Brun53d1a982014-04-30 18:21:37 +020013034base64
13035 Converts a binary input sample to a base64 string. It is used to log or
Davor Ocelice9ed2812017-12-25 17:49:28 +010013036 transfer binary content in a way that can be reliably transferred (e.g.
Emeric Brun53d1a982014-04-30 18:21:37 +020013037 an SSL ID can be copied in a header).
13038
Willy Tarreau97707872015-01-27 15:12:13 +010013039bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013040 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010013041 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010013042 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010013043 presence of a flag).
13044
Emeric Brun54c4ac82014-11-03 15:32:43 +010013045bytes(<offset>[,<length>])
13046 Extracts some bytes from an input binary sample. The result is a binary
13047 sample starting at an offset (in bytes) of the original sample and
Tim Düsterhus4896c442016-11-29 02:15:19 +010013048 optionally truncated at the given length.
Emeric Brun54c4ac82014-11-03 15:32:43 +010013049
Willy Tarreau280f42b2018-02-19 15:34:12 +010013050concat([<start>],[<var>],[<end>])
13051 Concatenates up to 3 fields after the current sample which is then turned to
13052 a string. The first one, <start>, is a constant string, that will be appended
13053 immediately after the existing sample. It may be omitted if not used. The
13054 second one, <var>, is a variable name. The variable will be looked up, its
13055 contents converted to a string, and it will be appended immediately after the
13056 <first> part. If the variable is not found, nothing is appended. It may be
13057 omitted as well. The third field, <end> is a constant string that will be
13058 appended after the variable. It may also be omitted. Together, these elements
13059 allow to concatenate variables with delimiters to an existing set of
13060 variables. This can be used to build new variables made of a succession of
13061 other variables, such as colon-delimited varlues. Note that due to the config
13062 parser, it is not possible to use a comma nor a closing parenthesis as
13063 delimitors.
13064
13065 Example:
13066 tcp-request session set-var(sess.src) src
13067 tcp-request session set-var(sess.dn) ssl_c_s_dn
13068 tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>)
13069 http-request set-header x-hap-sig %[var(txn.sig)]
13070
Willy Tarreau97707872015-01-27 15:12:13 +010013071cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013072 Takes the input value of type signed integer, applies a ones-complement
13073 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010013074
Willy Tarreau80599772015-01-20 19:35:24 +010013075crc32([<avalanche>])
13076 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
13077 hash function. Optionally, it is possible to apply a full avalanche hash
13078 function to the output if the optional <avalanche> argument equals 1. This
13079 converter uses the same functions as used by the various hash-based load
13080 balancing algorithms, so it will provide exactly the same results. It is
13081 provided for compatibility with other software which want a CRC32 to be
13082 computed on some input keys, so it follows the most common implementation as
13083 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
13084 but may provide a better or at least less predictable distribution. It must
13085 not be used for security purposes as a 32-bit hash is trivial to break. See
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013086 also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive.
13087
13088crc32c([<avalanche>])
13089 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C
13090 hash function. Optionally, it is possible to apply a full avalanche hash
13091 function to the output if the optional <avalanche> argument equals 1. This
13092 converter uses the same functions as described in RFC4960, Appendix B [8].
13093 It is provided for compatibility with other software which want a CRC32C to be
13094 computed on some input keys. It is slower than the other algorithms and it must
13095 not be used for security purposes as a 32-bit hash is trivial to break. See
13096 also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive.
Willy Tarreau80599772015-01-20 19:35:24 +010013097
David Carlier29b3ca32015-09-25 14:09:21 +010013098da-csv-conv(<prop>[,<prop>*])
David Carlier4542b102015-06-01 13:54:29 +020013099 Asks the DeviceAtlas converter to identify the User Agent string passed on
13100 input, and to emit a string made of the concatenation of the properties
13101 enumerated in argument, delimited by the separator defined by the global
13102 keyword "deviceatlas-property-separator", or by default the pipe character
David Carlier840b0242016-03-16 10:09:55 +000013103 ('|'). There's a limit of 12 different properties imposed by the haproxy
David Carlier4542b102015-06-01 13:54:29 +020013104 configuration language.
13105
13106 Example:
13107 frontend www
Cyril Bonté307ee1e2015-09-28 23:16:06 +020013108 bind *:8881
13109 default_backend servers
David Carlier840b0242016-03-16 10:09:55 +000013110 http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
David Carlier4542b102015-06-01 13:54:29 +020013111
Thierry FOURNIER9687c772015-05-07 15:46:29 +020013112debug
13113 This converter is used as debug tool. It dumps on screen the content and the
13114 type of the input sample. The sample is returned as is on its output. This
13115 converter only exists when haproxy was built with debugging enabled.
13116
Willy Tarreau97707872015-01-27 15:12:13 +010013117div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013118 Divides the input value of type signed integer by <value>, and returns the
13119 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013120 integer is returned (typically 2^63-1). <value> can be a numeric value or a
Daniel Schneller0b547052016-03-21 20:46:57 +010013121 variable name. The name of the variable starts with an indication about its
13122 scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013123 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013124 "sess" : the variable is shared with the whole session
13125 "txn" : the variable is shared with the transaction (request and response)
13126 "req" : the variable is shared only during request processing
13127 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013128 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013129 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013130
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013131djb2([<avalanche>])
13132 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
13133 hash function. Optionally, it is possible to apply a full avalanche hash
13134 function to the output if the optional <avalanche> argument equals 1. This
13135 converter uses the same functions as used by the various hash-based load
13136 balancing algorithms, so it will provide exactly the same results. It is
13137 mostly intended for debugging, but can be used as a stick-table entry to
13138 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013139 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c",
13140 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013141
Willy Tarreau97707872015-01-27 15:12:13 +010013142even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013143 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010013144 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
13145
Marcin Deranek9631a282018-04-16 14:30:46 +020013146field(<index>,<delimiters>[,<count>])
13147 Extracts the substring at the given index counting from the beginning
13148 (positive index) or from the end (negative index) considering given delimiters
13149 from an input string. Indexes start at 1 or -1 and delimiters are a string
13150 formatted list of chars. Optionally you can specify <count> of fields to
13151 extract (default: 1). Value of 0 indicates extraction of all remaining
13152 fields.
13153
13154 Example :
13155 str(f1_f2_f3__f5),field(5,_) # f5
13156 str(f1_f2_f3__f5),field(2,_,0) # f2_f3__f5
13157 str(f1_f2_f3__f5),field(2,_,2) # f2_f3
13158 str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_
13159 str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3
Emeric Brunf399b0d2014-11-03 17:07:03 +010013160
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013161hex
Davor Ocelice9ed2812017-12-25 17:49:28 +010013162 Converts a binary input sample to a hex string containing two hex digits per
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013163 input byte. It is used to log or transfer hex dumps of some binary input data
Davor Ocelice9ed2812017-12-25 17:49:28 +010013164 in a way that can be reliably transferred (e.g. an SSL ID can be copied in a
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013165 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010013166
Dragan Dosen3f957b22017-10-24 09:27:34 +020013167hex2i
13168 Converts a hex string containing two hex digits per input byte to an
13169 integer. If the input value can not be converted, then zero is returned.
13170
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013171http_date([<offset>])
13172 Converts an integer supposed to contain a date since epoch to a string
13173 representing this date in a format suitable for use in HTTP header fields. If
13174 an offset value is specified, then it is a number of seconds that is added to
13175 the date before the conversion is operated. This is particularly useful to
13176 emit Date header fields, Expires values in responses when combined with a
13177 positive offset, or Last-Modified values when the offset is negative.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013178
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013179in_table(<table>)
13180 Uses the string representation of the input sample to perform a look up in
13181 the specified table. If the key is not found in the table, a boolean false
13182 is returned. Otherwise a boolean true is returned. This can be used to verify
Davor Ocelice9ed2812017-12-25 17:49:28 +010013183 the presence of a certain key in a table tracking some elements (e.g. whether
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013184 or not a source IP address or an Authorization header was already seen).
13185
Tim Duesterhus1478aa72018-01-25 16:24:51 +010013186ipmask(<mask4>, [<mask6>])
13187 Apply a mask to an IP address, and use the result for lookups and storage.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013188 This can be used to make all hosts within a certain mask to share the same
Tim Duesterhus1478aa72018-01-25 16:24:51 +010013189 table entries and as such use the same server. The mask4 can be passed in
13190 dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can
13191 be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64).
13192 If no mask6 is given IPv6 addresses will fail to convert for backwards
13193 compatibility reasons.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013194
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013195json([<input-code>])
Davor Ocelice9ed2812017-12-25 17:49:28 +010013196 Escapes the input string and produces an ASCII output string ready to use as a
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013197 JSON string. The converter tries to decode the input string according to the
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020013198 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013199 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
13200 of errors:
13201 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
13202 bytes, ...)
13203 - invalid range (the decoded value is within a UTF-8 prohibited range),
13204 - code overlong (the value is encoded with more bytes than necessary).
13205
13206 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
13207 character is greater than 0xffff because the JSON string escape specification
13208 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
13209 in 4 variants designated by a combination of two suffix letters : "p" for
13210 "permissive" and "s" for "silently ignore". The behaviors of the decoders
13211 are :
Davor Ocelice9ed2812017-12-25 17:49:28 +010013212 - "ascii" : never fails;
13213 - "utf8" : fails on any detected errors;
13214 - "utf8s" : never fails, but removes characters corresponding to errors;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013215 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
Davor Ocelice9ed2812017-12-25 17:49:28 +010013216 error;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013217 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
13218 characters corresponding to the other errors.
13219
13220 This converter is particularly useful for building properly escaped JSON for
Davor Ocelice9ed2812017-12-25 17:49:28 +010013221 logging to servers which consume JSON-formatted traffic logs.
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013222
13223 Example:
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013224 capture request header Host len 15
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020013225 capture request header user-agent len 150
13226 log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013227
13228 Input request from client 127.0.0.1:
13229 GET / HTTP/1.0
13230 User-Agent: Very "Ugly" UA 1/2
13231
13232 Output log:
13233 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
13234
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013235language(<value>[,<default>])
13236 Returns the value with the highest q-factor from a list as extracted from the
13237 "accept-language" header using "req.fhdr". Values with no q-factor have a
13238 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
13239 belong to the list of semi-colon delimited <values> will be considered. The
13240 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
13241 given list and a default value is provided, it is returned. Note that language
13242 names may have a variant after a dash ('-'). If this variant is present in the
13243 list, it will be matched, but if it is not, only the base language is checked.
13244 The match is case-sensitive, and the output string is always one of those
Davor Ocelice9ed2812017-12-25 17:49:28 +010013245 provided in arguments. The ordering of arguments is meaningless, only the
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013246 ordering of the values in the request counts, as the first value among
13247 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020013248
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013249 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020013250
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013251 # this configuration switches to the backend matching a
13252 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020013253
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013254 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
13255 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
13256 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
13257 use_backend spanish if es
13258 use_backend french if fr
13259 use_backend english if en
13260 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020013261
Willy Tarreau60a2ee72017-12-15 07:13:48 +010013262length
Etienne Carriereed0d24e2017-12-13 13:41:34 +010013263 Get the length of the string. This can only be placed after a string
13264 sample fetch function or after a transformation keyword returning a string
13265 type. The result is of type integer.
13266
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013267lower
13268 Convert a string sample to lower case. This can only be placed after a string
13269 sample fetch function or after a transformation keyword returning a string
13270 type. The result is of type string.
13271
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013272ltime(<format>[,<offset>])
13273 Converts an integer supposed to contain a date since epoch to a string
13274 representing this date in local time using a format defined by the <format>
13275 string using strftime(3). The purpose is to allow any date format to be used
13276 in logs. An optional <offset> in seconds may be applied to the input date
13277 (positive or negative). See the strftime() man page for the format supported
13278 by your operating system. See also the utime converter.
13279
13280 Example :
13281
13282 # Emit two colons, one with the local time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010013283 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013284 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
13285
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013286map(<map_file>[,<default_value>])
13287map_<match_type>(<map_file>[,<default_value>])
13288map_<match_type>_<output_type>(<map_file>[,<default_value>])
13289 Search the input value from <map_file> using the <match_type> matching method,
13290 and return the associated value converted to the type <output_type>. If the
13291 input value cannot be found in the <map_file>, the converter returns the
13292 <default_value>. If the <default_value> is not set, the converter fails and
13293 acts as if no input value could be fetched. If the <match_type> is not set, it
13294 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
13295 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
13296 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013297
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013298 It is important to avoid overlapping between the keys : IP addresses and
13299 strings are stored in trees, so the first of the finest match will be used.
13300 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013301
Tim Düsterhus4896c442016-11-29 02:15:19 +010013302 The following array contains the list of all map functions available sorted by
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013303 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013304
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013305 input type | match method | output type str | output type int | output type ip
13306 -----------+--------------+-----------------+-----------------+---------------
13307 str | str | map_str | map_str_int | map_str_ip
13308 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020013309 str | beg | map_beg | map_beg_int | map_end_ip
13310 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013311 str | sub | map_sub | map_sub_int | map_sub_ip
13312 -----------+--------------+-----------------+-----------------+---------------
13313 str | dir | map_dir | map_dir_int | map_dir_ip
13314 -----------+--------------+-----------------+-----------------+---------------
13315 str | dom | map_dom | map_dom_int | map_dom_ip
13316 -----------+--------------+-----------------+-----------------+---------------
13317 str | end | map_end | map_end_int | map_end_ip
13318 -----------+--------------+-----------------+-----------------+---------------
Ruoshan Huang3c5e3742016-12-02 16:25:31 +080013319 str | reg | map_reg | map_reg_int | map_reg_ip
13320 -----------+--------------+-----------------+-----------------+---------------
13321 str | reg | map_regm | map_reg_int | map_reg_ip
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013322 -----------+--------------+-----------------+-----------------+---------------
13323 int | int | map_int | map_int_int | map_int_ip
13324 -----------+--------------+-----------------+-----------------+---------------
13325 ip | ip | map_ip | map_ip_int | map_ip_ip
13326 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013327
Thierry Fournier8feaa662016-02-10 22:55:20 +010013328 The special map called "map_regm" expect matching zone in the regular
13329 expression and modify the output replacing back reference (like "\1") by
13330 the corresponding match text.
13331
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013332 The file contains one key + value per line. Lines which start with '#' are
13333 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
13334 is then the first "word" (series of non-space/tabs characters), and the value
13335 is what follows this series of space/tab till the end of the line excluding
13336 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013337
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013338 Example :
13339
13340 # this is a comment and is ignored
13341 2.22.246.0/23 United Kingdom \n
13342 <-><-----------><--><------------><---->
13343 | | | | `- trailing spaces ignored
13344 | | | `---------- value
13345 | | `-------------------- middle spaces ignored
13346 | `---------------------------- key
13347 `------------------------------------ leading spaces ignored
13348
Willy Tarreau97707872015-01-27 15:12:13 +010013349mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013350 Divides the input value of type signed integer by <value>, and returns the
13351 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013352 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013353 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013354 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013355 "sess" : the variable is shared with the whole session
13356 "txn" : the variable is shared with the transaction (request and response)
13357 "req" : the variable is shared only during request processing
13358 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013359 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013360 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013361
13362mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013363 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020013364 the product as an signed integer. In case of overflow, the largest possible
13365 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013366 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013367 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013368 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013369 "sess" : the variable is shared with the whole session
13370 "txn" : the variable is shared with the transaction (request and response)
13371 "req" : the variable is shared only during request processing
13372 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013373 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013374 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013375
Nenad Merdanovicb7e7c472017-03-12 21:56:55 +010013376nbsrv
13377 Takes an input value of type string, interprets it as a backend name and
13378 returns the number of usable servers in that backend. Can be used in places
13379 where we want to look up a backend from a dynamic name, like a result of a
13380 map lookup.
13381
Willy Tarreau97707872015-01-27 15:12:13 +010013382neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013383 Takes the input value of type signed integer, computes the opposite value,
13384 and returns the remainder as an signed integer. 0 is identity. This operator
13385 is provided for reversed subtracts : in order to subtract the input from a
13386 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010013387
13388not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013389 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010013390 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010013391 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010013392 absence of a flag).
13393
13394odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013395 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010013396 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
13397
13398or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013399 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013400 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010013401 numeric value or a variable name. The name of the variable starts with an
13402 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013403 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013404 "sess" : the variable is shared with the whole session
13405 "txn" : the variable is shared with the transaction (request and response)
13406 "req" : the variable is shared only during request processing
13407 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013408 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013409 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013410
Willy Tarreauc4dc3502015-01-23 20:39:28 +010013411regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010013412 Applies a regex-based substitution to the input string. It does the same
13413 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
13414 default it will replace in the input string the first occurrence of the
13415 largest part matching the regular expression <regex> with the substitution
13416 string <subst>. It is possible to replace all occurrences instead by adding
13417 the flag "g" in the third argument <flags>. It is also possible to make the
13418 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
13419 string, it is made up from the concatenation of all desired flags. Thus if
13420 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
13421 It is important to note that due to the current limitations of the
Baptiste Assmann66025d82016-03-06 23:36:48 +010013422 configuration parser, some characters such as closing parenthesis, closing
13423 square brackets or comma are not possible to use in the arguments. The first
13424 use of this converter is to replace certain characters or sequence of
13425 characters with other ones.
Willy Tarreau7eda8492015-01-20 19:47:06 +010013426
13427 Example :
13428
13429 # de-duplicate "/" in header "x-path".
13430 # input: x-path: /////a///b/c/xzxyz/
13431 # output: x-path: /a/b/c/xzxyz/
13432 http-request set-header x-path %[hdr(x-path),regsub(/+,/,g)]
13433
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013434capture-req(<id>)
13435 Capture the string entry in the request slot <id> and returns the entry as
13436 is. If the slot doesn't exist, the capture fails silently.
13437
13438 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020013439 "http-response capture", "capture.req.hdr" and
13440 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013441
13442capture-res(<id>)
13443 Capture the string entry in the response slot <id> and returns the entry as
13444 is. If the slot doesn't exist, the capture fails silently.
13445
13446 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020013447 "http-response capture", "capture.req.hdr" and
13448 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013449
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013450sdbm([<avalanche>])
13451 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
13452 hash function. Optionally, it is possible to apply a full avalanche hash
13453 function to the output if the optional <avalanche> argument equals 1. This
13454 converter uses the same functions as used by the various hash-based load
13455 balancing algorithms, so it will provide exactly the same results. It is
13456 mostly intended for debugging, but can be used as a stick-table entry to
13457 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013458 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c",
13459 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013460
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013461set-var(<var name>)
Davor Ocelice9ed2812017-12-25 17:49:28 +010013462 Sets a variable with the input content and returns the content on the output
13463 as-is. The variable keeps the value and the associated input type. The name of
13464 the variable starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013465 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013466 "sess" : the variable is shared with the whole session
13467 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013468 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013469 "req" : the variable is shared only during request processing,
13470 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013471 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013472 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013473
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020013474sha1
13475 Converts a binary input sample to a SHA1 digest. The result is a binary
13476 sample with length of 20 bytes.
13477
Tim Duesterhusca097c12018-04-27 21:18:45 +020013478strcmp(<var>)
13479 Compares the contents of <var> with the input value of type string. Returns
13480 the result as a signed integer compatible with strcmp(3): 0 if both strings
13481 are identical. A value less than 0 if the left string is lexicographically
13482 smaller than the right string or if the left string is shorter. A value greater
13483 than 0 otherwise (right string greater than left string or the right string is
13484 shorter).
13485
13486 Example :
13487
13488 http-request set-var(txn.host) hdr(host)
13489 # Check whether the client is attempting domain fronting.
13490 acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0
13491
13492
Willy Tarreau97707872015-01-27 15:12:13 +010013493sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013494 Subtracts <value> from the input value of type signed integer, and returns
13495 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013496 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
Daniel Schneller0b547052016-03-21 20:46:57 +010013497 or a variable name. The name of the variable starts with an indication about
13498 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013499 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013500 "sess" : the variable is shared with the whole session
13501 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013502 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013503 "req" : the variable is shared only during request processing,
13504 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013505 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013506 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013507
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013508table_bytes_in_rate(<table>)
13509 Uses the string representation of the input sample to perform a look up in
13510 the specified table. If the key is not found in the table, integer value zero
13511 is returned. Otherwise the converter returns the average client-to-server
13512 bytes rate associated with the input sample in the designated table, measured
13513 in amount of bytes over the period configured in the table. See also the
13514 sc_bytes_in_rate sample fetch keyword.
13515
13516
13517table_bytes_out_rate(<table>)
13518 Uses the string representation of the input sample to perform a look up in
13519 the specified table. If the key is not found in the table, integer value zero
13520 is returned. Otherwise the converter returns the average server-to-client
13521 bytes rate associated with the input sample in the designated table, measured
13522 in amount of bytes over the period configured in the table. See also the
13523 sc_bytes_out_rate sample fetch keyword.
13524
13525table_conn_cnt(<table>)
13526 Uses the string representation of the input sample to perform a look up in
13527 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013528 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013529 connections associated with the input sample in the designated table. See
13530 also the sc_conn_cnt sample fetch keyword.
13531
13532table_conn_cur(<table>)
13533 Uses the string representation of the input sample to perform a look up in
13534 the specified table. If the key is not found in the table, integer value zero
13535 is returned. Otherwise the converter returns the current amount of concurrent
13536 tracked connections associated with the input sample in the designated table.
13537 See also the sc_conn_cur sample fetch keyword.
13538
13539table_conn_rate(<table>)
13540 Uses the string representation of the input sample to perform a look up in
13541 the specified table. If the key is not found in the table, integer value zero
13542 is returned. Otherwise the converter returns the average incoming connection
13543 rate associated with the input sample in the designated table. See also the
13544 sc_conn_rate sample fetch keyword.
13545
Thierry FOURNIER236657b2015-08-19 08:25:14 +020013546table_gpt0(<table>)
13547 Uses the string representation of the input sample to perform a look up in
13548 the specified table. If the key is not found in the table, boolean value zero
13549 is returned. Otherwise the converter returns the current value of the first
13550 general purpose tag associated with the input sample in the designated table.
13551 See also the sc_get_gpt0 sample fetch keyword.
13552
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013553table_gpc0(<table>)
13554 Uses the string representation of the input sample to perform a look up in
13555 the specified table. If the key is not found in the table, integer value zero
13556 is returned. Otherwise the converter returns the current value of the first
13557 general purpose counter associated with the input sample in the designated
13558 table. See also the sc_get_gpc0 sample fetch keyword.
13559
13560table_gpc0_rate(<table>)
13561 Uses the string representation of the input sample to perform a look up in
13562 the specified table. If the key is not found in the table, integer value zero
13563 is returned. Otherwise the converter returns the frequency which the gpc0
13564 counter was incremented over the configured period in the table, associated
13565 with the input sample in the designated table. See also the sc_get_gpc0_rate
13566 sample fetch keyword.
13567
Frédéric Lécaille6778b272018-01-29 15:22:53 +010013568table_gpc1(<table>)
13569 Uses the string representation of the input sample to perform a look up in
13570 the specified table. If the key is not found in the table, integer value zero
13571 is returned. Otherwise the converter returns the current value of the second
13572 general purpose counter associated with the input sample in the designated
13573 table. See also the sc_get_gpc1 sample fetch keyword.
13574
13575table_gpc1_rate(<table>)
13576 Uses the string representation of the input sample to perform a look up in
13577 the specified table. If the key is not found in the table, integer value zero
13578 is returned. Otherwise the converter returns the frequency which the gpc1
13579 counter was incremented over the configured period in the table, associated
13580 with the input sample in the designated table. See also the sc_get_gpc1_rate
13581 sample fetch keyword.
13582
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013583table_http_err_cnt(<table>)
13584 Uses the string representation of the input sample to perform a look up in
13585 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013586 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013587 errors associated with the input sample in the designated table. See also the
13588 sc_http_err_cnt sample fetch keyword.
13589
13590table_http_err_rate(<table>)
13591 Uses the string representation of the input sample to perform a look up in
13592 the specified table. If the key is not found in the table, integer value zero
13593 is returned. Otherwise the average rate of HTTP errors associated with the
13594 input sample in the designated table, measured in amount of errors over the
13595 period configured in the table. See also the sc_http_err_rate sample fetch
13596 keyword.
13597
13598table_http_req_cnt(<table>)
13599 Uses the string representation of the input sample to perform a look up in
13600 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013601 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013602 requests associated with the input sample in the designated table. See also
13603 the sc_http_req_cnt sample fetch keyword.
13604
13605table_http_req_rate(<table>)
13606 Uses the string representation of the input sample to perform a look up in
13607 the specified table. If the key is not found in the table, integer value zero
13608 is returned. Otherwise the average rate of HTTP requests associated with the
13609 input sample in the designated table, measured in amount of requests over the
13610 period configured in the table. See also the sc_http_req_rate sample fetch
13611 keyword.
13612
13613table_kbytes_in(<table>)
13614 Uses the string representation of the input sample to perform a look up in
13615 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013616 is returned. Otherwise the converter returns the cumulative number of client-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013617 to-server data associated with the input sample in the designated table,
13618 measured in kilobytes. The test is currently performed on 32-bit integers,
13619 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
13620 keyword.
13621
13622table_kbytes_out(<table>)
13623 Uses the string representation of the input sample to perform a look up in
13624 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013625 is returned. Otherwise the converter returns the cumulative number of server-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013626 to-client data associated with the input sample in the designated table,
13627 measured in kilobytes. The test is currently performed on 32-bit integers,
13628 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
13629 keyword.
13630
13631table_server_id(<table>)
13632 Uses the string representation of the input sample to perform a look up in
13633 the specified table. If the key is not found in the table, integer value zero
13634 is returned. Otherwise the converter returns the server ID associated with
13635 the input sample in the designated table. A server ID is associated to a
13636 sample by a "stick" rule when a connection to a server succeeds. A server ID
13637 zero means that no server is associated with this key.
13638
13639table_sess_cnt(<table>)
13640 Uses the string representation of the input sample to perform a look up in
13641 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013642 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013643 sessions associated with the input sample in the designated table. Note that
13644 a session here refers to an incoming connection being accepted by the
13645 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
13646 keyword.
13647
13648table_sess_rate(<table>)
13649 Uses the string representation of the input sample to perform a look up in
13650 the specified table. If the key is not found in the table, integer value zero
13651 is returned. Otherwise the converter returns the average incoming session
13652 rate associated with the input sample in the designated table. Note that a
13653 session here refers to an incoming connection being accepted by the
13654 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
13655 keyword.
13656
13657table_trackers(<table>)
13658 Uses the string representation of the input sample to perform a look up in
13659 the specified table. If the key is not found in the table, integer value zero
13660 is returned. Otherwise the converter returns the current amount of concurrent
13661 connections tracking the same key as the input sample in the designated
13662 table. It differs from table_conn_cur in that it does not rely on any stored
13663 information but on the table's reference count (the "use" value which is
13664 returned by "show table" on the CLI). This may sometimes be more suited for
13665 layer7 tracking. It can be used to tell a server how many concurrent
13666 connections there are from a given address for example. See also the
13667 sc_trackers sample fetch keyword.
13668
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013669upper
13670 Convert a string sample to upper case. This can only be placed after a string
13671 sample fetch function or after a transformation keyword returning a string
13672 type. The result is of type string.
13673
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020013674url_dec
13675 Takes an url-encoded string provided as input and returns the decoded
13676 version as output. The input and the output are of type string.
13677
Christopher Faulet85d79c92016-11-09 16:54:56 +010013678unset-var(<var name>)
13679 Unsets a variable if the input content is defined. The name of the variable
13680 starts with an indication about its scope. The scopes allowed are:
13681 "proc" : the variable is shared with the whole process
13682 "sess" : the variable is shared with the whole session
13683 "txn" : the variable is shared with the transaction (request and
13684 response),
13685 "req" : the variable is shared only during request processing,
13686 "res" : the variable is shared only during response processing.
13687 This prefix is followed by a name. The separator is a '.'. The name may only
13688 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
13689
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013690utime(<format>[,<offset>])
13691 Converts an integer supposed to contain a date since epoch to a string
13692 representing this date in UTC time using a format defined by the <format>
13693 string using strftime(3). The purpose is to allow any date format to be used
13694 in logs. An optional <offset> in seconds may be applied to the input date
13695 (positive or negative). See the strftime() man page for the format supported
13696 by your operating system. See also the ltime converter.
13697
13698 Example :
13699
13700 # Emit two colons, one with the UTC time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010013701 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013702 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
13703
Marcin Deranek9631a282018-04-16 14:30:46 +020013704word(<index>,<delimiters>[,<count>])
13705 Extracts the nth word counting from the beginning (positive index) or from
13706 the end (negative index) considering given delimiters from an input string.
13707 Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
13708 Optionally you can specify <count> of words to extract (default: 1).
13709 Value of 0 indicates extraction of all remaining words.
13710
13711 Example :
13712 str(f1_f2_f3__f5),word(4,_) # f5
13713 str(f1_f2_f3__f5),word(2,_,0) # f2_f3__f5
13714 str(f1_f2_f3__f5),word(3,_,2) # f3__f5
13715 str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
13716 str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010013717
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013718wt6([<avalanche>])
13719 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
13720 hash function. Optionally, it is possible to apply a full avalanche hash
13721 function to the output if the optional <avalanche> argument equals 1. This
13722 converter uses the same functions as used by the various hash-based load
13723 balancing algorithms, so it will provide exactly the same results. It is
13724 mostly intended for debugging, but can be used as a stick-table entry to
13725 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013726 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c",
13727 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013728
Willy Tarreau97707872015-01-27 15:12:13 +010013729xor(<value>)
13730 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013731 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013732 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013733 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013734 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013735 "sess" : the variable is shared with the whole session
13736 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013737 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013738 "req" : the variable is shared only during request processing,
13739 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013740 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013741 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013742
Thierry FOURNIER01e09742016-12-26 11:46:11 +010013743xxh32([<seed>])
13744 Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
13745 variant of the XXHash hash function. This hash supports a seed which defaults
13746 to zero but a different value maybe passed as the <seed> argument. This hash
13747 is known to be very good and very fast so it can be used to hash URLs and/or
13748 URL parameters for use as stick-table keys to collect statistics with a low
13749 collision rate, though care must be taken as the algorithm is not considered
13750 as cryptographically secure.
13751
13752xxh64([<seed>])
13753 Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
13754 variant of the XXHash hash function. This hash supports a seed which defaults
13755 to zero but a different value maybe passed as the <seed> argument. This hash
13756 is known to be very good and very fast so it can be used to hash URLs and/or
13757 URL parameters for use as stick-table keys to collect statistics with a low
13758 collision rate, though care must be taken as the algorithm is not considered
13759 as cryptographically secure.
13760
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013761
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200137627.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020013763--------------------------------------------
13764
13765A first set of sample fetch methods applies to internal information which does
13766not even relate to any client information. These ones are sometimes used with
13767"monitor-fail" directives to report an internal status to external watchers.
13768The sample fetch methods described in this section are usable anywhere.
13769
13770always_false : boolean
13771 Always returns the boolean "false" value. It may be used with ACLs as a
13772 temporary replacement for another one when adjusting configurations.
13773
13774always_true : boolean
13775 Always returns the boolean "true" value. It may be used with ACLs as a
13776 temporary replacement for another one when adjusting configurations.
13777
13778avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010013779 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020013780 divided by the number of active servers. The current backend is used if no
13781 backend is specified. This is very similar to "queue" except that the size of
13782 the farm is considered, in order to give a more accurate measurement of the
13783 time it may take for a new connection to be processed. The main usage is with
13784 ACL to return a sorry page to new users when it becomes certain they will get
13785 a degraded service, or to pass to the backend servers in a header so that
13786 they decide to work in degraded mode or to disable some functions to speed up
13787 the processing a bit. Note that in the event there would not be any active
13788 server anymore, twice the number of queued connections would be considered as
13789 the measured value. This is a fair estimate, as we expect one server to get
13790 back soon anyway, but we still prefer to send new traffic to another backend
13791 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
13792 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010013793
Willy Tarreau74ca5042013-06-11 23:12:07 +020013794be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020013795 Applies to the number of currently established connections on the backend,
13796 possibly including the connection being evaluated. If no backend name is
13797 specified, the current one is used. But it is also possible to check another
13798 backend. It can be used to use a specific farm when the nominal one is full.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040013799 See also the "fe_conn", "queue", "be_conn_free", and "be_sess_rate" criteria.
13800
13801be_conn_free([<backend>]) : integer
13802 Returns an integer value corresponding to the number of available connections
13803 across available servers in the backend. Queue slots are not included. Backup
13804 servers are also not included, unless all other servers are down. If no
13805 backend name is specified, the current one is used. But it is also possible
13806 to check another backend. It can be used to use a specific farm when the
Patrick Hemmer155e93e2018-06-14 18:01:35 -040013807 nominal one is full. See also the "be_conn", "connslots", and "srv_conn_free"
13808 criteria.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040013809
13810 OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0
13811 (meaning unlimited), then this fetch clearly does not make sense, in which
13812 case the value returned will be -1.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013813
Willy Tarreau74ca5042013-06-11 23:12:07 +020013814be_sess_rate([<backend>]) : integer
13815 Returns an integer value corresponding to the sessions creation rate on the
13816 backend, in number of new sessions per second. This is used with ACLs to
13817 switch to an alternate backend when an expensive or fragile one reaches too
Davor Ocelice9ed2812017-12-25 17:49:28 +010013818 high a session rate, or to limit abuse of service (e.g. prevent sucking of an
Willy Tarreau74ca5042013-06-11 23:12:07 +020013819 online dictionary). It can also be useful to add this element to logs using a
13820 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013821
13822 Example :
13823 # Redirect to an error page if the dictionary is requested too often
13824 backend dynamic
13825 mode http
13826 acl being_scanned be_sess_rate gt 100
13827 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010013828
Davor Ocelice9ed2812017-12-25 17:49:28 +010013829bin(<hex>) : bin
Thierry FOURNIERcc103292015-06-06 19:30:17 +020013830 Returns a binary chain. The input is the hexadecimal representation
13831 of the string.
13832
13833bool(<bool>) : bool
13834 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
13835 'false' and '0' are the same. 'true' and '1' are the same.
13836
Willy Tarreau74ca5042013-06-11 23:12:07 +020013837connslots([<backend>]) : integer
13838 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013839 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020013840 connections on all servers and the maximum queue size. This is probably only
13841 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050013842
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013843 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020013844 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013845 usage; see "use_backend" keyword) can be redirected to a different backend.
13846
Willy Tarreau55165fe2009-05-10 12:02:55 +020013847 'connslots' = number of available server connection slots, + number of
13848 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013849
Willy Tarreaua36af912009-10-10 12:02:45 +020013850 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020013851 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020013852 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020013853 you want to be able to differentiate between different backends, and their
Davor Ocelice9ed2812017-12-25 17:49:28 +010013854 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020013855 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020013856 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013857
Willy Tarreau55165fe2009-05-10 12:02:55 +020013858 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
13859 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020013860 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020013861 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013862
Willy Tarreau6236d3a2013-07-25 14:28:25 +020013863date([<offset>]) : integer
13864 Returns the current date as the epoch (number of seconds since 01/01/1970).
13865 If an offset value is specified, then it is a number of seconds that is added
13866 to the current date before returning the value. This is particularly useful
13867 to compute relative dates, as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020013868 It is useful combined with the http_date converter.
13869
13870 Example :
13871
13872 # set an expires header to now+1 hour in every response
13873 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020013874
Etienne Carrierea792a0a2018-01-17 13:43:24 +010013875date_us : integer
13876 Return the microseconds part of the date (the "second" part is returned by
13877 date sample). This sample is coherent with the date sample as it is comes
13878 from the same timeval structure.
13879
Willy Tarreaud716f9b2017-10-13 11:03:15 +020013880distcc_body(<token>[,<occ>]) : binary
13881 Parses a distcc message and returns the body associated to occurrence #<occ>
13882 of the token <token>. Occurrences start at 1, and when unspecified, any may
13883 match though in practice only the first one is checked for now. This can be
13884 used to extract file names or arguments in files built using distcc through
13885 haproxy. Please refer to distcc's protocol documentation for the complete
13886 list of supported tokens.
13887
13888distcc_param(<token>[,<occ>]) : integer
13889 Parses a distcc message and returns the parameter associated to occurrence
13890 #<occ> of the token <token>. Occurrences start at 1, and when unspecified,
13891 any may match though in practice only the first one is checked for now. This
13892 can be used to extract certain information such as the protocol version, the
13893 file size or the argument in files built using distcc through haproxy.
13894 Another use case consists in waiting for the start of the preprocessed file
13895 contents before connecting to the server to avoid keeping idle connections.
13896 Please refer to distcc's protocol documentation for the complete list of
13897 supported tokens.
13898
13899 Example :
13900 # wait up to 20s for the pre-processed file to be uploaded
13901 tcp-request inspect-delay 20s
13902 tcp-request content accept if { distcc_param(DOTI) -m found }
13903 # send large files to the big farm
13904 use_backend big_farm if { distcc_param(DOTI) gt 1000000 }
13905
Willy Tarreau595ec542013-06-12 21:34:28 +020013906env(<name>) : string
13907 Returns a string containing the value of environment variable <name>. As a
13908 reminder, environment variables are per-process and are sampled when the
13909 process starts. This can be useful to pass some information to a next hop
13910 server, or with ACLs to take specific action when the process is started a
13911 certain way.
13912
13913 Examples :
13914 # Pass the Via header to next hop with the local hostname in it
13915 http-request add-header Via 1.1\ %[env(HOSTNAME)]
13916
13917 # reject cookie-less requests when the STOP environment variable is set
13918 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
13919
Willy Tarreau74ca5042013-06-11 23:12:07 +020013920fe_conn([<frontend>]) : integer
13921 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010013922 possibly including the connection being evaluated. If no frontend name is
13923 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020013924 frontend. It can be used to return a sorry page before hard-blocking, or to
13925 use a specific backend to drain new requests when the farm is considered
Davor Ocelice9ed2812017-12-25 17:49:28 +010013926 full. This is mostly used with ACLs but can also be used to pass some
Willy Tarreau74ca5042013-06-11 23:12:07 +020013927 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
13928 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020013929
Nenad Merdanovicad9a7e92016-10-03 04:57:37 +020013930fe_req_rate([<frontend>]) : integer
13931 Returns an integer value corresponding to the number of HTTP requests per
13932 second sent to a frontend. This number can differ from "fe_sess_rate" in
13933 situations where client-side keep-alive is enabled.
13934
Willy Tarreau74ca5042013-06-11 23:12:07 +020013935fe_sess_rate([<frontend>]) : integer
13936 Returns an integer value corresponding to the sessions creation rate on the
13937 frontend, in number of new sessions per second. This is used with ACLs to
13938 limit the incoming session rate to an acceptable range in order to prevent
13939 abuse of service at the earliest moment, for example when combined with other
13940 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
13941 down below the limit. It can also be useful to add this element to logs using
13942 a log-format directive. See also the "rate-limit sessions" directive for use
13943 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010013944
13945 Example :
13946 # This frontend limits incoming mails to 10/s with a max of 100
13947 # concurrent connections. We accept any connection below 10/s, and
13948 # force excess clients to wait for 100 ms. Since clients are limited to
13949 # 100 max, there cannot be more than 10 incoming mails per second.
13950 frontend mail
13951 bind :25
13952 mode tcp
13953 maxconn 100
13954 acl too_fast fe_sess_rate ge 10
13955 tcp-request inspect-delay 100ms
13956 tcp-request content accept if ! too_fast
13957 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010013958
Nenad Merdanovic807a6e72017-03-12 22:00:00 +010013959hostname : string
13960 Returns the system hostname.
13961
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013962int(<integer>) : signed integer
13963 Returns a signed integer.
13964
Thierry FOURNIERcc103292015-06-06 19:30:17 +020013965ipv4(<ipv4>) : ipv4
13966 Returns an ipv4.
13967
13968ipv6(<ipv6>) : ipv6
13969 Returns an ipv6.
13970
13971meth(<method>) : method
13972 Returns a method.
13973
Willy Tarreau0f30d262014-11-24 16:02:05 +010013974nbproc : integer
13975 Returns an integer value corresponding to the number of processes that were
13976 started (it equals the global "nbproc" setting). This is useful for logging
13977 and debugging purposes.
13978
Willy Tarreau74ca5042013-06-11 23:12:07 +020013979nbsrv([<backend>]) : integer
13980 Returns an integer value corresponding to the number of usable servers of
13981 either the current backend or the named backend. This is mostly used with
13982 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010013983 switch to an alternate backend when the number of servers is too low to
13984 to handle some load. It is useful to report a failure when combined with
13985 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010013986
Patrick Hemmerfabb24f2018-08-13 14:07:57 -040013987prio_class : integer
13988 Returns the priority class of the current session for http mode or connection
13989 for tcp mode. The value will be that set by the last call to "http-request
13990 set-priority-class" or "tcp-request content set-priority-class".
13991
13992prio_offset : integer
13993 Returns the priority offset of the current session for http mode or
13994 connection for tcp mode. The value will be that set by the last call to
13995 "http-request set-priority-offset" or "tcp-request content
13996 set-priority-offset".
13997
Willy Tarreau0f30d262014-11-24 16:02:05 +010013998proc : integer
13999 Returns an integer value corresponding to the position of the process calling
14000 the function, between 1 and global.nbproc. This is useful for logging and
14001 debugging purposes.
14002
Willy Tarreau74ca5042013-06-11 23:12:07 +020014003queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010014004 Returns the total number of queued connections of the designated backend,
14005 including all the connections in server queues. If no backend name is
14006 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020014007 one. This is useful with ACLs or to pass statistics to backend servers. This
14008 can be used to take actions when queuing goes above a known level, generally
14009 indicating a surge of traffic or a massive slowdown on the servers. One
14010 possible action could be to reject new users but still accept old ones. See
14011 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
14012
Willy Tarreau84310e22014-02-14 11:59:04 +010014013rand([<range>]) : integer
14014 Returns a random integer value within a range of <range> possible values,
14015 starting at zero. If the range is not specified, it defaults to 2^32, which
14016 gives numbers between 0 and 4294967295. It can be useful to pass some values
14017 needed to take some routing decisions for example, or just for debugging
14018 purposes. This random must not be used for security purposes.
14019
Willy Tarreau74ca5042013-06-11 23:12:07 +020014020srv_conn([<backend>/]<server>) : integer
14021 Returns an integer value corresponding to the number of currently established
14022 connections on the designated server, possibly including the connection being
14023 evaluated. If <backend> is omitted, then the server is looked up in the
14024 current backend. It can be used to use a specific farm when one server is
14025 full, or to inform the server about our view of the number of active
Patrick Hemmer155e93e2018-06-14 18:01:35 -040014026 connections with it. See also the "fe_conn", "be_conn", "queue", and
14027 "srv_conn_free" fetch methods.
14028
14029srv_conn_free([<backend>/]<server>) : integer
14030 Returns an integer value corresponding to the number of available connections
14031 on the designated server, possibly including the connection being evaluated.
14032 The value does not include queue slots. If <backend> is omitted, then the
14033 server is looked up in the current backend. It can be used to use a specific
14034 farm when one server is full, or to inform the server about our view of the
14035 number of active connections with it. See also the "be_conn_free" and
14036 "srv_conn" fetch methods.
14037
14038 OTHER CAVEATS AND NOTES: If the server maxconn is 0, then this fetch clearly
14039 does not make sense, in which case the value returned will be -1.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014040
14041srv_is_up([<backend>/]<server>) : boolean
14042 Returns true when the designated server is UP, and false when it is either
14043 DOWN or in maintenance mode. If <backend> is omitted, then the server is
14044 looked up in the current backend. It is mainly used to take action based on
Davor Ocelice9ed2812017-12-25 17:49:28 +010014045 an external status reported via a health check (e.g. a geographical site's
Willy Tarreau74ca5042013-06-11 23:12:07 +020014046 availability). Another possible use which is more of a hack consists in
14047 using dummy servers as boolean variables that can be enabled or disabled from
14048 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
14049
Willy Tarreauff2b7af2017-10-13 11:46:26 +020014050srv_queue([<backend>/]<server>) : integer
14051 Returns an integer value corresponding to the number of connections currently
14052 pending in the designated server's queue. If <backend> is omitted, then the
14053 server is looked up in the current backend. It can sometimes be used together
14054 with the "use-server" directive to force to use a known faster server when it
14055 is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample
14056 fetch methods.
14057
Willy Tarreau74ca5042013-06-11 23:12:07 +020014058srv_sess_rate([<backend>/]<server>) : integer
14059 Returns an integer corresponding to the sessions creation rate on the
14060 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014061 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020014062 used with ACLs but can make sense with logs too. This is used to switch to an
14063 alternate backend when an expensive or fragile one reaches too high a session
Davor Ocelice9ed2812017-12-25 17:49:28 +010014064 rate, or to limit abuse of service (e.g. prevent latent requests from
Willy Tarreau74ca5042013-06-11 23:12:07 +020014065 overloading servers).
14066
14067 Example :
14068 # Redirect to a separate back
14069 acl srv1_full srv_sess_rate(be1/srv1) gt 50
14070 acl srv2_full srv_sess_rate(be1/srv2) gt 50
14071 use_backend be2 if srv1_full or srv2_full
14072
Willy Tarreau0f30d262014-11-24 16:02:05 +010014073stopping : boolean
14074 Returns TRUE if the process calling the function is currently stopping. This
14075 can be useful for logging, or for relaxing certain checks or helping close
14076 certain connections upon graceful shutdown.
14077
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014078str(<string>) : string
14079 Returns a string.
14080
Willy Tarreau74ca5042013-06-11 23:12:07 +020014081table_avl([<table>]) : integer
14082 Returns the total number of available entries in the current proxy's
14083 stick-table or in the designated stick-table. See also table_cnt.
14084
14085table_cnt([<table>]) : integer
14086 Returns the total number of entries currently in use in the current proxy's
14087 stick-table or in the designated stick-table. See also src_conn_cnt and
14088 table_avl for other entry counting methods.
14089
Christopher Faulet34adb2a2017-11-21 21:45:38 +010014090thread : integer
14091 Returns an integer value corresponding to the position of the thread calling
14092 the function, between 0 and (global.nbthread-1). This is useful for logging
14093 and debugging purposes.
14094
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014095var(<var-name>) : undefined
14096 Returns a variable with the stored type. If the variable is not set, the
Daniel Schneller0b547052016-03-21 20:46:57 +010014097 sample fetch fails. The name of the variable starts with an indication
14098 about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014099 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014100 "sess" : the variable is shared with the whole session
14101 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014102 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010014103 "req" : the variable is shared only during request processing,
14104 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014105 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014106 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014107
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200141087.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020014109----------------------------------
14110
14111The layer 4 usually describes just the transport layer which in haproxy is
14112closest to the connection, where no content is yet made available. The fetch
14113methods described here are usable as low as the "tcp-request connection" rule
14114sets unless they require some future information. Those generally include
14115TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014116the incoming connection. For retrieving a value from a sticky counters, the
14117counter number can be explicitly set as 0, 1, or 2 using the pre-defined
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020014118"sc0_", "sc1_", or "sc2_" prefix. These three pre-defined prefixes can only be
14119used if MAX_SESS_STKCTR value does not exceed 3, otherwise the counter number
14120can be specified as the first integer argument when using the "sc_" prefix.
14121Starting from "sc_0" to "sc_N" where N is (MAX_SESS_STKCTR-1). An optional
14122table may be specified with the "sc*" form, in which case the currently
14123tracked key will be looked up into this alternate table instead of the table
14124currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014125
14126be_id : integer
14127 Returns an integer containing the current backend's id. It can be used in
14128 frontends with responses to check which backend processed the request.
14129
Marcin Deranekd2471c22016-12-12 14:08:05 +010014130be_name : string
14131 Returns a string containing the current backend's name. It can be used in
14132 frontends with responses to check which backend processed the request.
14133
Willy Tarreau74ca5042013-06-11 23:12:07 +020014134dst : ip
14135 This is the destination IPv4 address of the connection on the client side,
14136 which is the address the client connected to. It can be useful when running
14137 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
14138 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
14139 RFC 4291.
14140
14141dst_conn : integer
14142 Returns an integer value corresponding to the number of currently established
14143 connections on the same socket including the one being evaluated. It is
14144 normally used with ACLs but can as well be used to pass the information to
14145 servers in an HTTP header or in logs. It can be used to either return a sorry
14146 page before hard-blocking, or to use a specific backend to drain new requests
14147 when the socket is considered saturated. This offers the ability to assign
14148 different limits to different listening ports or addresses. See also the
14149 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014150
Willy Tarreau16e01562016-08-09 16:46:18 +020014151dst_is_local : boolean
14152 Returns true if the destination address of the incoming connection is local
14153 to the system, or false if the address doesn't exist on the system, meaning
14154 that it was intercepted in transparent mode. It can be useful to apply
14155 certain rules by default to forwarded traffic and other rules to the traffic
Davor Ocelice9ed2812017-12-25 17:49:28 +010014156 targeting the real address of the machine. For example the stats page could
Willy Tarreau16e01562016-08-09 16:46:18 +020014157 be delivered only on this address, or SSH access could be locally redirected.
14158 Please note that the check involves a few system calls, so it's better to do
14159 it only once per connection.
14160
Willy Tarreau74ca5042013-06-11 23:12:07 +020014161dst_port : integer
14162 Returns an integer value corresponding to the destination TCP port of the
14163 connection on the client side, which is the port the client connected to.
14164 This might be used when running in transparent mode, when assigning dynamic
14165 ports to some clients for a whole application session, to stick all users to
14166 a same server, or to pass the destination port information to a server using
14167 an HTTP header.
14168
Willy Tarreau60ca10a2017-08-18 15:26:54 +020014169fc_http_major : integer
14170 Reports the front connection's HTTP major version encoding, which may be 1
14171 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
14172 encoding and not on the version present in the request header.
14173
Emeric Brun4f603012017-01-05 15:11:44 +010014174fc_rcvd_proxy : boolean
14175 Returns true if the client initiated the connection with a PROXY protocol
14176 header.
14177
Thierry Fournier / OZON.IO6310bef2016-07-24 20:16:50 +020014178fc_rtt(<unit>) : integer
14179 Returns the Round Trip Time (RTT) measured by the kernel for the client
14180 connection. <unit> is facultative, by default the unit is milliseconds. <unit>
14181 can be set to "ms" for milliseconds or "us" for microseconds. If the server
14182 connection is not established, if the connection is not TCP or if the
14183 operating system does not support TCP_INFO, for example Linux kernels before
14184 2.4, the sample fetch fails.
14185
14186fc_rttvar(<unit>) : integer
14187 Returns the Round Trip Time (RTT) variance measured by the kernel for the
14188 client connection. <unit> is facultative, by default the unit is milliseconds.
14189 <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the
14190 server connection is not established, if the connection is not TCP or if the
14191 operating system does not support TCP_INFO, for example Linux kernels before
14192 2.4, the sample fetch fails.
14193
Joe Williams30fcd392016-08-10 07:06:44 -070014194fc_unacked(<unit>) : integer
14195 Returns the unacked counter measured by the kernel for the client connection.
14196 If the server connection is not established, if the connection is not TCP or
14197 if the operating system does not support TCP_INFO, for example Linux kernels
14198 before 2.4, the sample fetch fails.
14199
14200fc_sacked(<unit>) : integer
14201 Returns the sacked counter measured by the kernel for the client connection.
14202 If the server connection is not established, if the connection is not TCP or
14203 if the operating system does not support TCP_INFO, for example Linux kernels
14204 before 2.4, the sample fetch fails.
14205
14206fc_retrans(<unit>) : integer
14207 Returns the retransmits counter measured by the kernel for the client
14208 connection. If the server connection is not established, if the connection is
14209 not TCP or if the operating system does not support TCP_INFO, for example
14210 Linux kernels before 2.4, the sample fetch fails.
14211
14212fc_fackets(<unit>) : integer
14213 Returns the fack counter measured by the kernel for the client
14214 connection. If the server connection is not established, if the connection is
14215 not TCP or if the operating system does not support TCP_INFO, for example
14216 Linux kernels before 2.4, the sample fetch fails.
14217
14218fc_lost(<unit>) : integer
14219 Returns the lost counter measured by the kernel for the client
14220 connection. If the server connection is not established, if the connection is
14221 not TCP or if the operating system does not support TCP_INFO, for example
14222 Linux kernels before 2.4, the sample fetch fails.
14223
14224fc_reordering(<unit>) : integer
14225 Returns the reordering counter measured by the kernel for the client
14226 connection. If the server connection is not established, if the connection is
14227 not TCP or if the operating system does not support TCP_INFO, for example
14228 Linux kernels before 2.4, the sample fetch fails.
14229
Marcin Deranek9a66dfb2018-04-13 14:37:50 +020014230fe_defbe : string
14231 Returns a string containing the frontend's default backend name. It can be
14232 used in frontends to check which backend will handle requests by default.
14233
Willy Tarreau74ca5042013-06-11 23:12:07 +020014234fe_id : integer
14235 Returns an integer containing the current frontend's id. It can be used in
Marcin Deranek6e413ed2016-12-13 12:40:01 +010014236 backends to check from which frontend it was called, or to stick all users
Willy Tarreau74ca5042013-06-11 23:12:07 +020014237 coming via a same frontend to the same server.
14238
Marcin Deranekd2471c22016-12-12 14:08:05 +010014239fe_name : string
14240 Returns a string containing the current frontend's name. It can be used in
14241 backends to check from which frontend it was called, or to stick all users
14242 coming via a same frontend to the same server.
14243
Cyril Bonté62ba8702014-04-22 23:52:25 +020014244sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014245sc0_bytes_in_rate([<table>]) : integer
14246sc1_bytes_in_rate([<table>]) : integer
14247sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014248 Returns the average client-to-server bytes rate from the currently tracked
14249 counters, measured in amount of bytes over the period configured in the
14250 table. See also src_bytes_in_rate.
14251
Cyril Bonté62ba8702014-04-22 23:52:25 +020014252sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014253sc0_bytes_out_rate([<table>]) : integer
14254sc1_bytes_out_rate([<table>]) : integer
14255sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014256 Returns the average server-to-client bytes rate from the currently tracked
14257 counters, measured in amount of bytes over the period configured in the
14258 table. See also src_bytes_out_rate.
14259
Cyril Bonté62ba8702014-04-22 23:52:25 +020014260sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014261sc0_clr_gpc0([<table>]) : integer
14262sc1_clr_gpc0([<table>]) : integer
14263sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020014264 Clears the first General Purpose Counter associated to the currently tracked
14265 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010014266 stored value is zero, so first invocation will always return zero. This is
14267 typically used as a second ACL in an expression in order to mark a connection
14268 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020014269
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014270 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020014271 # block if 5 consecutive requests continue to come faster than 10 sess
14272 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014273 acl abuse sc0_http_req_rate gt 10
14274 acl kill sc0_inc_gpc0 gt 5
14275 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020014276 tcp-request connection accept if !abuse save
14277 tcp-request connection reject if abuse kill
14278
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014279sc_clr_gpc1(<ctr>[,<table>]) : integer
14280sc0_clr_gpc1([<table>]) : integer
14281sc1_clr_gpc1([<table>]) : integer
14282sc2_clr_gpc1([<table>]) : integer
14283 Clears the second General Purpose Counter associated to the currently tracked
14284 counters, and returns its previous value. Before the first invocation, the
14285 stored value is zero, so first invocation will always return zero. This is
14286 typically used as a second ACL in an expression in order to mark a connection
14287 when a first ACL was verified.
14288
Cyril Bonté62ba8702014-04-22 23:52:25 +020014289sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014290sc0_conn_cnt([<table>]) : integer
14291sc1_conn_cnt([<table>]) : integer
14292sc2_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014293 Returns the cumulative number of incoming connections from currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020014294 counters. See also src_conn_cnt.
14295
Cyril Bonté62ba8702014-04-22 23:52:25 +020014296sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014297sc0_conn_cur([<table>]) : integer
14298sc1_conn_cur([<table>]) : integer
14299sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014300 Returns the current amount of concurrent connections tracking the same
14301 tracked counters. This number is automatically incremented when tracking
14302 begins and decremented when tracking stops. See also src_conn_cur.
14303
Cyril Bonté62ba8702014-04-22 23:52:25 +020014304sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014305sc0_conn_rate([<table>]) : integer
14306sc1_conn_rate([<table>]) : integer
14307sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014308 Returns the average connection rate from the currently tracked counters,
14309 measured in amount of connections over the period configured in the table.
14310 See also src_conn_rate.
14311
Cyril Bonté62ba8702014-04-22 23:52:25 +020014312sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014313sc0_get_gpc0([<table>]) : integer
14314sc1_get_gpc0([<table>]) : integer
14315sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014316 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014317 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014318
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014319sc_get_gpc1(<ctr>[,<table>]) : integer
14320sc0_get_gpc1([<table>]) : integer
14321sc1_get_gpc1([<table>]) : integer
14322sc2_get_gpc1([<table>]) : integer
14323 Returns the value of the second General Purpose Counter associated to the
14324 currently tracked counters. See also src_get_gpc1 and sc/sc0/sc1/sc2_inc_gpc1.
14325
Thierry FOURNIER236657b2015-08-19 08:25:14 +020014326sc_get_gpt0(<ctr>[,<table>]) : integer
14327sc0_get_gpt0([<table>]) : integer
14328sc1_get_gpt0([<table>]) : integer
14329sc2_get_gpt0([<table>]) : integer
14330 Returns the value of the first General Purpose Tag associated to the
14331 currently tracked counters. See also src_get_gpt0.
14332
Cyril Bonté62ba8702014-04-22 23:52:25 +020014333sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014334sc0_gpc0_rate([<table>]) : integer
14335sc1_gpc0_rate([<table>]) : integer
14336sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014337 Returns the average increment rate of the first General Purpose Counter
14338 associated to the currently tracked counters. It reports the frequency
14339 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014340 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
14341 that the "gpc0_rate" counter must be stored in the stick-table for a value to
14342 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020014343
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014344sc_gpc1_rate(<ctr>[,<table>]) : integer
14345sc0_gpc1_rate([<table>]) : integer
14346sc1_gpc1_rate([<table>]) : integer
14347sc2_gpc1_rate([<table>]) : integer
14348 Returns the average increment rate of the second General Purpose Counter
14349 associated to the currently tracked counters. It reports the frequency
14350 which the gpc1 counter was incremented over the configured period. See also
14351 src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
14352 that the "gpc1_rate" counter must be stored in the stick-table for a value to
14353 be returned, as "gpc1" only holds the event count.
14354
Cyril Bonté62ba8702014-04-22 23:52:25 +020014355sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014356sc0_http_err_cnt([<table>]) : integer
14357sc1_http_err_cnt([<table>]) : integer
14358sc2_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014359 Returns the cumulative number of HTTP errors from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020014360 counters. This includes the both request errors and 4xx error responses.
14361 See also src_http_err_cnt.
14362
Cyril Bonté62ba8702014-04-22 23:52:25 +020014363sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014364sc0_http_err_rate([<table>]) : integer
14365sc1_http_err_rate([<table>]) : integer
14366sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014367 Returns the average rate of HTTP errors from the currently tracked counters,
14368 measured in amount of errors over the period configured in the table. This
14369 includes the both request errors and 4xx error responses. See also
14370 src_http_err_rate.
14371
Cyril Bonté62ba8702014-04-22 23:52:25 +020014372sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014373sc0_http_req_cnt([<table>]) : integer
14374sc1_http_req_cnt([<table>]) : integer
14375sc2_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014376 Returns the cumulative number of HTTP requests from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020014377 counters. This includes every started request, valid or not. See also
14378 src_http_req_cnt.
14379
Cyril Bonté62ba8702014-04-22 23:52:25 +020014380sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014381sc0_http_req_rate([<table>]) : integer
14382sc1_http_req_rate([<table>]) : integer
14383sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014384 Returns the average rate of HTTP requests from the currently tracked
14385 counters, measured in amount of requests over the period configured in
14386 the table. This includes every started request, valid or not. See also
14387 src_http_req_rate.
14388
Cyril Bonté62ba8702014-04-22 23:52:25 +020014389sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014390sc0_inc_gpc0([<table>]) : integer
14391sc1_inc_gpc0([<table>]) : integer
14392sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014393 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010014394 tracked counters, and returns its new value. Before the first invocation,
14395 the stored value is zero, so first invocation will increase it to 1 and will
14396 return 1. This is typically used as a second ACL in an expression in order
14397 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020014398
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014399 Example:
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014400 acl abuse sc0_http_req_rate gt 10
14401 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020014402 tcp-request connection reject if abuse kill
14403
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014404sc_inc_gpc1(<ctr>[,<table>]) : integer
14405sc0_inc_gpc1([<table>]) : integer
14406sc1_inc_gpc1([<table>]) : integer
14407sc2_inc_gpc1([<table>]) : integer
14408 Increments the second General Purpose Counter associated to the currently
14409 tracked counters, and returns its new value. Before the first invocation,
14410 the stored value is zero, so first invocation will increase it to 1 and will
14411 return 1. This is typically used as a second ACL in an expression in order
14412 to mark a connection when a first ACL was verified.
14413
Cyril Bonté62ba8702014-04-22 23:52:25 +020014414sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014415sc0_kbytes_in([<table>]) : integer
14416sc1_kbytes_in([<table>]) : integer
14417sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014418 Returns the total amount of client-to-server data from the currently tracked
14419 counters, measured in kilobytes. The test is currently performed on 32-bit
14420 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020014421
Cyril Bonté62ba8702014-04-22 23:52:25 +020014422sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014423sc0_kbytes_out([<table>]) : integer
14424sc1_kbytes_out([<table>]) : integer
14425sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014426 Returns the total amount of server-to-client data from the currently tracked
14427 counters, measured in kilobytes. The test is currently performed on 32-bit
14428 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020014429
Cyril Bonté62ba8702014-04-22 23:52:25 +020014430sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014431sc0_sess_cnt([<table>]) : integer
14432sc1_sess_cnt([<table>]) : integer
14433sc2_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014434 Returns the cumulative number of incoming connections that were transformed
Willy Tarreaue9656522010-08-17 15:40:09 +020014435 into sessions, which means that they were accepted by a "tcp-request
14436 connection" rule, from the currently tracked counters. A backend may count
14437 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014438 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020014439 with the client. See also src_sess_cnt.
14440
Cyril Bonté62ba8702014-04-22 23:52:25 +020014441sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014442sc0_sess_rate([<table>]) : integer
14443sc1_sess_rate([<table>]) : integer
14444sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014445 Returns the average session rate from the currently tracked counters,
14446 measured in amount of sessions over the period configured in the table. A
14447 session is a connection that got past the early "tcp-request connection"
14448 rules. A backend may count more sessions than connections because each
14449 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014450 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020014451
Cyril Bonté62ba8702014-04-22 23:52:25 +020014452sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020014453sc0_tracked([<table>]) : boolean
14454sc1_tracked([<table>]) : boolean
14455sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020014456 Returns true if the designated session counter is currently being tracked by
14457 the current session. This can be useful when deciding whether or not we want
14458 to set some values in a header passed to the server.
14459
Cyril Bonté62ba8702014-04-22 23:52:25 +020014460sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014461sc0_trackers([<table>]) : integer
14462sc1_trackers([<table>]) : integer
14463sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010014464 Returns the current amount of concurrent connections tracking the same
14465 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014466 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010014467 that it does not rely on any stored information but on the table's reference
14468 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020014469 may sometimes be more suited for layer7 tracking. It can be used to tell a
14470 server how many concurrent connections there are from a given address for
14471 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010014472
Willy Tarreau74ca5042013-06-11 23:12:07 +020014473so_id : integer
14474 Returns an integer containing the current listening socket's id. It is useful
14475 in frontends involving many "bind" lines, or to stick all users coming via a
14476 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014477
Willy Tarreau74ca5042013-06-11 23:12:07 +020014478src : ip
Davor Ocelice9ed2812017-12-25 17:49:28 +010014479 This is the source IPv4 address of the client of the session. It is of type
Willy Tarreau74ca5042013-06-11 23:12:07 +020014480 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
14481 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
14482 TCP-level source address which is used, and not the address of a client
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010014483 behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind
14484 directive is used, it can be the address of a client behind another
14485 PROXY-protocol compatible component for all rule sets except
14486 "tcp-request connection" which sees the real address.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014487
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014488 Example:
14489 # add an HTTP header in requests with the originating address' country
14490 http-request set-header X-Country %[src,map_ip(geoip.lst)]
14491
Willy Tarreau74ca5042013-06-11 23:12:07 +020014492src_bytes_in_rate([<table>]) : integer
14493 Returns the average bytes rate from the incoming connection's source address
14494 in the current proxy's stick-table or in the designated stick-table, measured
14495 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014496 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014497
Willy Tarreau74ca5042013-06-11 23:12:07 +020014498src_bytes_out_rate([<table>]) : integer
14499 Returns the average bytes rate to the incoming connection's source address in
14500 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014501 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014502 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014503
Willy Tarreau74ca5042013-06-11 23:12:07 +020014504src_clr_gpc0([<table>]) : integer
14505 Clears the first General Purpose Counter associated to the incoming
14506 connection's source address in the current proxy's stick-table or in the
14507 designated stick-table, and returns its previous value. If the address is not
14508 found, an entry is created and 0 is returned. This is typically used as a
14509 second ACL in an expression in order to mark a connection when a first ACL
14510 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020014511
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014512 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020014513 # block if 5 consecutive requests continue to come faster than 10 sess
14514 # per second, and reset the counter as soon as the traffic slows down.
14515 acl abuse src_http_req_rate gt 10
14516 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010014517 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020014518 tcp-request connection accept if !abuse save
14519 tcp-request connection reject if abuse kill
14520
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014521src_clr_gpc1([<table>]) : integer
14522 Clears the second General Purpose Counter associated to the incoming
14523 connection's source address in the current proxy's stick-table or in the
14524 designated stick-table, and returns its previous value. If the address is not
14525 found, an entry is created and 0 is returned. This is typically used as a
14526 second ACL in an expression in order to mark a connection when a first ACL
14527 was verified.
14528
Willy Tarreau74ca5042013-06-11 23:12:07 +020014529src_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014530 Returns the cumulative number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020014531 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014532 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014533 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014534
Willy Tarreau74ca5042013-06-11 23:12:07 +020014535src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014536 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020014537 current incoming connection's source address in the current proxy's
14538 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014539 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014540
Willy Tarreau74ca5042013-06-11 23:12:07 +020014541src_conn_rate([<table>]) : integer
14542 Returns the average connection rate from the incoming connection's source
14543 address in the current proxy's stick-table or in the designated stick-table,
14544 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014545 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014546
Willy Tarreau74ca5042013-06-11 23:12:07 +020014547src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014548 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020014549 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014550 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014551 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014552
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014553src_get_gpc1([<table>]) : integer
14554 Returns the value of the second General Purpose Counter associated to the
14555 incoming connection's source address in the current proxy's stick-table or in
14556 the designated stick-table. If the address is not found, zero is returned.
14557 See also sc/sc0/sc1/sc2_get_gpc1 and src_inc_gpc1.
14558
Thierry FOURNIER236657b2015-08-19 08:25:14 +020014559src_get_gpt0([<table>]) : integer
14560 Returns the value of the first General Purpose Tag associated to the
14561 incoming connection's source address in the current proxy's stick-table or in
14562 the designated stick-table. If the address is not found, zero is returned.
14563 See also sc/sc0/sc1/sc2_get_gpt0.
14564
Willy Tarreau74ca5042013-06-11 23:12:07 +020014565src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014566 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020014567 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014568 stick-table or in the designated stick-table. It reports the frequency
14569 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014570 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
14571 that the "gpc0_rate" counter must be stored in the stick-table for a value to
14572 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014573
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014574src_gpc1_rate([<table>]) : integer
14575 Returns the average increment rate of the second General Purpose Counter
14576 associated to the incoming connection's source address in the current proxy's
14577 stick-table or in the designated stick-table. It reports the frequency
14578 which the gpc1 counter was incremented over the configured period. See also
14579 sc/sc0/sc1/sc2_gpc1_rate, src_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
14580 that the "gpc1_rate" counter must be stored in the stick-table for a value to
14581 be returned, as "gpc1" only holds the event count.
14582
Willy Tarreau74ca5042013-06-11 23:12:07 +020014583src_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014584 Returns the cumulative number of HTTP errors from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020014585 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020014586 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014587 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020014588 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014589
Willy Tarreau74ca5042013-06-11 23:12:07 +020014590src_http_err_rate([<table>]) : integer
14591 Returns the average rate of HTTP errors from the incoming connection's source
14592 address in the current proxy's stick-table or in the designated stick-table,
14593 measured in amount of errors over the period configured in the table. This
14594 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014595 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014596
Willy Tarreau74ca5042013-06-11 23:12:07 +020014597src_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014598 Returns the cumulative number of HTTP requests from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020014599 source address in the current proxy's stick-table or in the designated stick-
14600 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014601 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014602
Willy Tarreau74ca5042013-06-11 23:12:07 +020014603src_http_req_rate([<table>]) : integer
14604 Returns the average rate of HTTP requests from the incoming connection's
14605 source address in the current proxy's stick-table or in the designated stick-
14606 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020014607 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014608 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014609
Willy Tarreau74ca5042013-06-11 23:12:07 +020014610src_inc_gpc0([<table>]) : integer
14611 Increments the first General Purpose Counter associated to the incoming
14612 connection's source address in the current proxy's stick-table or in the
14613 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014614 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014615 This is typically used as a second ACL in an expression in order to mark a
14616 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020014617
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014618 Example:
Willy Tarreauc9705a12010-07-27 20:05:50 +020014619 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010014620 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020014621 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020014622
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014623src_inc_gpc1([<table>]) : integer
14624 Increments the second General Purpose Counter associated to the incoming
14625 connection's source address in the current proxy's stick-table or in the
14626 designated stick-table, and returns its new value. If the address is not
14627 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc1.
14628 This is typically used as a second ACL in an expression in order to mark a
14629 connection when a first ACL was verified.
14630
Willy Tarreau16e01562016-08-09 16:46:18 +020014631src_is_local : boolean
14632 Returns true if the source address of the incoming connection is local to the
14633 system, or false if the address doesn't exist on the system, meaning that it
14634 comes from a remote machine. Note that UNIX addresses are considered local.
14635 It can be useful to apply certain access restrictions based on where the
Davor Ocelice9ed2812017-12-25 17:49:28 +010014636 client comes from (e.g. require auth or https for remote machines). Please
Willy Tarreau16e01562016-08-09 16:46:18 +020014637 note that the check involves a few system calls, so it's better to do it only
14638 once per connection.
14639
Willy Tarreau74ca5042013-06-11 23:12:07 +020014640src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014641 Returns the total amount of data received from the incoming connection's
14642 source address in the current proxy's stick-table or in the designated
14643 stick-table, measured in kilobytes. If the address is not found, zero is
14644 returned. The test is currently performed on 32-bit integers, which limits
14645 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014646
Willy Tarreau74ca5042013-06-11 23:12:07 +020014647src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014648 Returns the total amount of data sent to the incoming connection's source
14649 address in the current proxy's stick-table or in the designated stick-table,
14650 measured in kilobytes. If the address is not found, zero is returned. The
14651 test is currently performed on 32-bit integers, which limits values to 4
14652 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020014653
Willy Tarreau74ca5042013-06-11 23:12:07 +020014654src_port : integer
14655 Returns an integer value corresponding to the TCP source port of the
14656 connection on the client side, which is the port the client connected from.
14657 Usage of this function is very limited as modern protocols do not care much
14658 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010014659
Willy Tarreau74ca5042013-06-11 23:12:07 +020014660src_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014661 Returns the cumulative number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020014662 connection's source IPv4 address in the current proxy's stick-table or in the
14663 designated stick-table, that were transformed into sessions, which means that
14664 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014665 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014666
Willy Tarreau74ca5042013-06-11 23:12:07 +020014667src_sess_rate([<table>]) : integer
14668 Returns the average session rate from the incoming connection's source
14669 address in the current proxy's stick-table or in the designated stick-table,
14670 measured in amount of sessions over the period configured in the table. A
14671 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014672 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014673
Willy Tarreau74ca5042013-06-11 23:12:07 +020014674src_updt_conn_cnt([<table>]) : integer
14675 Creates or updates the entry associated to the incoming connection's source
14676 address in the current proxy's stick-table or in the designated stick-table.
14677 This table must be configured to store the "conn_cnt" data type, otherwise
14678 the match will be ignored. The current count is incremented by one, and the
14679 expiration timer refreshed. The updated count is returned, so this match
14680 can't return zero. This was used to reject service abusers based on their
14681 source address. Note: it is recommended to use the more complete "track-sc*"
14682 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020014683
14684 Example :
14685 # This frontend limits incoming SSH connections to 3 per 10 second for
14686 # each source address, and rejects excess connections until a 10 second
14687 # silence is observed. At most 20 addresses are tracked.
14688 listen ssh
14689 bind :22
14690 mode tcp
14691 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020014692 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020014693 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020014694 server local 127.0.0.1:22
14695
Willy Tarreau74ca5042013-06-11 23:12:07 +020014696srv_id : integer
14697 Returns an integer containing the server's id when processing the response.
14698 While it's almost only used with ACLs, it may be used for logging or
14699 debugging.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020014700
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200147017.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020014702----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020014703
Willy Tarreau74ca5042013-06-11 23:12:07 +020014704The layer 5 usually describes just the session layer which in haproxy is
14705closest to the session once all the connection handshakes are finished, but
14706when no content is yet made available. The fetch methods described here are
14707usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014708future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020014709
Ben Shillitof25e8e52016-12-02 14:25:37 +00001471051d.all(<prop>[,<prop>*]) : string
14711 Returns values for the properties requested as a string, where values are
14712 separated by the delimiter specified with "51degrees-property-separator".
14713 The device is identified using all the important HTTP headers from the
14714 request. The function can be passed up to five property names, and if a
14715 property name can't be found, the value "NoData" is returned.
14716
14717 Example :
14718 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
14719 # containing the three properties requested using all relevant headers from
14720 # the request.
14721 frontend http-in
14722 bind *:8081
14723 default_backend servers
14724 http-request set-header X-51D-DeviceTypeMobileTablet \
14725 %[51d.all(DeviceType,IsMobile,IsTablet)]
14726
Emeric Brun645ae792014-04-30 14:21:06 +020014727ssl_bc : boolean
14728 Returns true when the back connection was made via an SSL/TLS transport
14729 layer and is locally deciphered. This means the outgoing connection was made
14730 other a server with the "ssl" option.
14731
14732ssl_bc_alg_keysize : integer
14733 Returns the symmetric cipher key size supported in bits when the outgoing
14734 connection was made over an SSL/TLS transport layer.
14735
14736ssl_bc_cipher : string
14737 Returns the name of the used cipher when the outgoing connection was made
14738 over an SSL/TLS transport layer.
14739
Emeric Brun74f7ffa2018-02-19 16:14:12 +010014740ssl_bc_is_resumed : boolean
14741 Returns true when the back connection was made over an SSL/TLS transport
14742 layer and the newly created SSL session was resumed using a cached
14743 session or a TLS ticket.
14744
Emeric Brun645ae792014-04-30 14:21:06 +020014745ssl_bc_protocol : string
14746 Returns the name of the used protocol when the outgoing connection was made
14747 over an SSL/TLS transport layer.
14748
Emeric Brunb73a9b02014-04-30 18:49:19 +020014749ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020014750 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020014751 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
14752 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
Emeric Brun645ae792014-04-30 14:21:06 +020014753
14754ssl_bc_session_id : binary
14755 Returns the SSL ID of the back connection when the outgoing connection was
14756 made over an SSL/TLS transport layer. It is useful to log if we want to know
14757 if session was reused or not.
14758
Patrick Hemmere0275472018-04-28 19:15:51 -040014759ssl_bc_session_key : binary
14760 Returns the SSL session master key of the back connection when the outgoing
14761 connection was made over an SSL/TLS transport layer. It is useful to decrypt
14762 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
14763 BoringSSL.
14764
Emeric Brun645ae792014-04-30 14:21:06 +020014765ssl_bc_use_keysize : integer
14766 Returns the symmetric cipher key size used in bits when the outgoing
14767 connection was made over an SSL/TLS transport layer.
14768
Willy Tarreau74ca5042013-06-11 23:12:07 +020014769ssl_c_ca_err : integer
14770 When the incoming connection was made over an SSL/TLS transport layer,
14771 returns the ID of the first error detected during verification of the client
14772 certificate at depth > 0, or 0 if no error was encountered during this
14773 verification process. Please refer to your SSL library's documentation to
14774 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020014775
Willy Tarreau74ca5042013-06-11 23:12:07 +020014776ssl_c_ca_err_depth : integer
14777 When the incoming connection was made over an SSL/TLS transport layer,
14778 returns the depth in the CA chain of the first error detected during the
14779 verification of the client certificate. If no error is encountered, 0 is
14780 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010014781
Emeric Brun43e79582014-10-29 19:03:26 +010014782ssl_c_der : binary
14783 Returns the DER formatted certificate presented by the client when the
14784 incoming connection was made over an SSL/TLS transport layer. When used for
14785 an ACL, the value(s) to match against can be passed in hexadecimal form.
14786
Willy Tarreau74ca5042013-06-11 23:12:07 +020014787ssl_c_err : integer
14788 When the incoming connection was made over an SSL/TLS transport layer,
14789 returns the ID of the first error detected during verification at depth 0, or
14790 0 if no error was encountered during this verification process. Please refer
14791 to your SSL library's documentation to find the exhaustive list of error
14792 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020014793
Willy Tarreau74ca5042013-06-11 23:12:07 +020014794ssl_c_i_dn([<entry>[,<occ>]]) : string
14795 When the incoming connection was made over an SSL/TLS transport layer,
14796 returns the full distinguished name of the issuer of the certificate
14797 presented by the client when no <entry> is specified, or the value of the
14798 first given entry found from the beginning of the DN. If a positive/negative
14799 occurrence number is specified as the optional second argument, it returns
14800 the value of the nth given entry value from the beginning/end of the DN.
14801 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
14802 "ssl_c_i_dn(CN)" retrieves the common name.
Willy Tarreau62644772008-07-16 18:36:06 +020014803
Willy Tarreau74ca5042013-06-11 23:12:07 +020014804ssl_c_key_alg : string
14805 Returns the name of the algorithm used to generate the key of the certificate
14806 presented by the client when the incoming connection was made over an SSL/TLS
14807 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020014808
Willy Tarreau74ca5042013-06-11 23:12:07 +020014809ssl_c_notafter : string
14810 Returns the end date presented by the client as a formatted string
14811 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14812 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020014813
Willy Tarreau74ca5042013-06-11 23:12:07 +020014814ssl_c_notbefore : string
14815 Returns the start date presented by the client as a formatted string
14816 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14817 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010014818
Willy Tarreau74ca5042013-06-11 23:12:07 +020014819ssl_c_s_dn([<entry>[,<occ>]]) : string
14820 When the incoming connection was made over an SSL/TLS transport layer,
14821 returns the full distinguished name of the subject of the certificate
14822 presented by the client when no <entry> is specified, or the value of the
14823 first given entry found from the beginning of the DN. If a positive/negative
14824 occurrence number is specified as the optional second argument, it returns
14825 the value of the nth given entry value from the beginning/end of the DN.
14826 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
14827 "ssl_c_s_dn(CN)" retrieves the common name.
Willy Tarreaub6672b52011-12-12 17:23:41 +010014828
Willy Tarreau74ca5042013-06-11 23:12:07 +020014829ssl_c_serial : binary
14830 Returns the serial of the certificate presented by the client when the
14831 incoming connection was made over an SSL/TLS transport layer. When used for
14832 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020014833
Willy Tarreau74ca5042013-06-11 23:12:07 +020014834ssl_c_sha1 : binary
14835 Returns the SHA-1 fingerprint of the certificate presented by the client when
14836 the incoming connection was made over an SSL/TLS transport layer. This can be
14837 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020014838 Note that the output is binary, so if you want to pass that signature to the
14839 server, you need to encode it in hex or base64, such as in the example below:
14840
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014841 Example:
Willy Tarreau2d0caa32014-07-02 19:01:22 +020014842 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020014843
Willy Tarreau74ca5042013-06-11 23:12:07 +020014844ssl_c_sig_alg : string
14845 Returns the name of the algorithm used to sign the certificate presented by
14846 the client when the incoming connection was made over an SSL/TLS transport
14847 layer.
Emeric Brun87855892012-10-17 17:39:35 +020014848
Willy Tarreau74ca5042013-06-11 23:12:07 +020014849ssl_c_used : boolean
14850 Returns true if current SSL session uses a client certificate even if current
14851 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020014852
Willy Tarreau74ca5042013-06-11 23:12:07 +020014853ssl_c_verify : integer
14854 Returns the verify result error ID when the incoming connection was made over
14855 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
14856 refer to your SSL library's documentation for an exhaustive list of error
14857 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020014858
Willy Tarreau74ca5042013-06-11 23:12:07 +020014859ssl_c_version : integer
14860 Returns the version of the certificate presented by the client when the
14861 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020014862
Emeric Brun43e79582014-10-29 19:03:26 +010014863ssl_f_der : binary
14864 Returns the DER formatted certificate presented by the frontend when the
14865 incoming connection was made over an SSL/TLS transport layer. When used for
14866 an ACL, the value(s) to match against can be passed in hexadecimal form.
14867
Willy Tarreau74ca5042013-06-11 23:12:07 +020014868ssl_f_i_dn([<entry>[,<occ>]]) : string
14869 When the incoming connection was made over an SSL/TLS transport layer,
14870 returns the full distinguished name of the issuer of the certificate
14871 presented by the frontend when no <entry> is specified, or the value of the
14872 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020014873 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020014874 the value of the nth given entry value from the beginning/end of the DN.
14875 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
14876 "ssl_f_i_dn(CN)" retrieves the common name.
Emeric Brun87855892012-10-17 17:39:35 +020014877
Willy Tarreau74ca5042013-06-11 23:12:07 +020014878ssl_f_key_alg : string
14879 Returns the name of the algorithm used to generate the key of the certificate
14880 presented by the frontend when the incoming connection was made over an
14881 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020014882
Willy Tarreau74ca5042013-06-11 23:12:07 +020014883ssl_f_notafter : string
14884 Returns the end date presented by the frontend as a formatted string
14885 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14886 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020014887
Willy Tarreau74ca5042013-06-11 23:12:07 +020014888ssl_f_notbefore : string
14889 Returns the start date presented by the frontend as a formatted string
14890 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14891 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020014892
Willy Tarreau74ca5042013-06-11 23:12:07 +020014893ssl_f_s_dn([<entry>[,<occ>]]) : string
14894 When the incoming connection was made over an SSL/TLS transport layer,
14895 returns the full distinguished name of the subject of the certificate
14896 presented by the frontend when no <entry> is specified, or the value of the
14897 first given entry found from the beginning of the DN. If a positive/negative
14898 occurrence number is specified as the optional second argument, it returns
14899 the value of the nth given entry value from the beginning/end of the DN.
14900 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
14901 "ssl_f_s_dn(CN)" retrieves the common name.
Emeric Brunce5ad802012-10-22 14:11:22 +020014902
Willy Tarreau74ca5042013-06-11 23:12:07 +020014903ssl_f_serial : binary
14904 Returns the serial of the certificate presented by the frontend when the
14905 incoming connection was made over an SSL/TLS transport layer. When used for
14906 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020014907
Emeric Brun55f4fa82014-04-30 17:11:25 +020014908ssl_f_sha1 : binary
14909 Returns the SHA-1 fingerprint of the certificate presented by the frontend
14910 when the incoming connection was made over an SSL/TLS transport layer. This
14911 can be used to know which certificate was chosen using SNI.
14912
Willy Tarreau74ca5042013-06-11 23:12:07 +020014913ssl_f_sig_alg : string
14914 Returns the name of the algorithm used to sign the certificate presented by
14915 the frontend when the incoming connection was made over an SSL/TLS transport
14916 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020014917
Willy Tarreau74ca5042013-06-11 23:12:07 +020014918ssl_f_version : integer
14919 Returns the version of the certificate presented by the frontend when the
14920 incoming connection was made over an SSL/TLS transport layer.
14921
14922ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020014923 Returns true when the front connection was made via an SSL/TLS transport
14924 layer and is locally deciphered. This means it has matched a socket declared
14925 with a "bind" line having the "ssl" option.
14926
Willy Tarreau74ca5042013-06-11 23:12:07 +020014927 Example :
14928 # This passes "X-Proto: https" to servers when client connects over SSL
14929 listen http-https
14930 bind :80
14931 bind :443 ssl crt /etc/haproxy.pem
14932 http-request add-header X-Proto https if { ssl_fc }
14933
14934ssl_fc_alg_keysize : integer
14935 Returns the symmetric cipher key size supported in bits when the incoming
14936 connection was made over an SSL/TLS transport layer.
14937
14938ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014939 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020014940 incoming connection made via a TLS transport layer and locally deciphered by
14941 haproxy. The result is a string containing the protocol name advertised by
14942 the client. The SSL library must have been built with support for TLS
14943 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
14944 not advertised unless the "alpn" keyword on the "bind" line specifies a
14945 protocol list. Also, nothing forces the client to pick a protocol from this
14946 list, any other one may be requested. The TLS ALPN extension is meant to
14947 replace the TLS NPN extension. See also "ssl_fc_npn".
14948
Willy Tarreau74ca5042013-06-11 23:12:07 +020014949ssl_fc_cipher : string
14950 Returns the name of the used cipher when the incoming connection was made
14951 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020014952
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014953ssl_fc_cipherlist_bin : binary
14954 Returns the binary form of the client hello cipher list. The maximum returned
14955 value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010014956 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014957
14958ssl_fc_cipherlist_hex : string
14959 Returns the binary form of the client hello cipher list encoded as
14960 hexadecimal. The maximum returned value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010014961 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014962
14963ssl_fc_cipherlist_str : string
14964 Returns the decoded text form of the client hello cipher list. The maximum
14965 number of ciphers returned is according with the value of
14966 "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only
Davor Ocelice9ed2812017-12-25 17:49:28 +010014967 available with OpenSSL >= 1.0.2. If the function is not enabled, this
Emmanuel Hocdetddcde192017-09-01 17:32:08 +020014968 sample-fetch returns the hash like "ssl_fc_cipherlist_xxh".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014969
14970ssl_fc_cipherlist_xxh : integer
14971 Returns a xxh64 of the cipher list. This hash can be return only is the value
14972 "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010014973 take in account all the data of the cipher list.
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014974
Willy Tarreau74ca5042013-06-11 23:12:07 +020014975ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020014976 Returns true if a client certificate is present in an incoming connection over
14977 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010014978 Note: on SSL session resumption with Session ID or TLS ticket, client
14979 certificate is not present in the current connection but may be retrieved
14980 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
14981 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020014982
Olivier Houchardccaa7de2017-10-02 11:51:03 +020014983ssl_fc_has_early : boolean
14984 Returns true if early data were sent, and the handshake didn't happen yet. As
14985 it has security implications, it is useful to be able to refuse those, or
14986 wait until the handshake happened.
14987
Willy Tarreau74ca5042013-06-11 23:12:07 +020014988ssl_fc_has_sni : boolean
14989 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020014990 in an incoming connection was made over an SSL/TLS transport layer. Returns
14991 true when the incoming connection presents a TLS SNI field. This requires
14992 that the SSL library is build with support for TLS extensions enabled (check
14993 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020014994
Nenad Merdanovic1516fe32016-05-17 03:31:21 +020014995ssl_fc_is_resumed : boolean
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020014996 Returns true if the SSL/TLS session has been resumed through the use of
Jérôme Magnin4a326cb2018-01-15 14:01:17 +010014997 SSL session cache or TLS tickets on an incoming connection over an SSL/TLS
14998 transport layer.
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020014999
Willy Tarreau74ca5042013-06-11 23:12:07 +020015000ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015001 This extracts the Next Protocol Negotiation field from an incoming connection
Willy Tarreau74ca5042013-06-11 23:12:07 +020015002 made via a TLS transport layer and locally deciphered by haproxy. The result
15003 is a string containing the protocol name advertised by the client. The SSL
15004 library must have been built with support for TLS extensions enabled (check
15005 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
15006 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
15007 forces the client to pick a protocol from this list, any other one may be
15008 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020015009
Willy Tarreau74ca5042013-06-11 23:12:07 +020015010ssl_fc_protocol : string
15011 Returns the name of the used protocol when the incoming connection was made
15012 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020015013
Emeric Brunb73a9b02014-04-30 18:49:19 +020015014ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040015015 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020015016 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
15017 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040015018
Willy Tarreau74ca5042013-06-11 23:12:07 +020015019ssl_fc_session_id : binary
15020 Returns the SSL ID of the front connection when the incoming connection was
15021 made over an SSL/TLS transport layer. It is useful to stick a given client to
15022 a server. It is important to note that some browsers refresh their session ID
15023 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020015024
Patrick Hemmere0275472018-04-28 19:15:51 -040015025ssl_fc_session_key : binary
15026 Returns the SSL session master key of the front connection when the incoming
15027 connection was made over an SSL/TLS transport layer. It is useful to decrypt
15028 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
15029 BoringSSL.
15030
15031
Willy Tarreau74ca5042013-06-11 23:12:07 +020015032ssl_fc_sni : string
15033 This extracts the Server Name Indication TLS extension (SNI) field from an
15034 incoming connection made via an SSL/TLS transport layer and locally
15035 deciphered by haproxy. The result (when present) typically is a string
15036 matching the HTTPS host name (253 chars or less). The SSL library must have
15037 been built with support for TLS extensions enabled (check haproxy -vv).
15038
15039 This fetch is different from "req_ssl_sni" above in that it applies to the
15040 connection being deciphered by haproxy and not to SSL contents being blindly
15041 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020015042 requires that the SSL library is build with support for TLS extensions
15043 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020015044
Willy Tarreau74ca5042013-06-11 23:12:07 +020015045 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020015046 ssl_fc_sni_end : suffix match
15047 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020015048
Willy Tarreau74ca5042013-06-11 23:12:07 +020015049ssl_fc_use_keysize : integer
15050 Returns the symmetric cipher key size used in bits when the incoming
15051 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020015052
Willy Tarreaub6fb4202008-07-20 11:18:28 +020015053
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200150547.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020015055------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020015056
Willy Tarreau74ca5042013-06-11 23:12:07 +020015057Fetching samples from buffer contents is a bit different from the previous
15058sample fetches above because the sampled data are ephemeral. These data can
15059only be used when they're available and will be lost when they're forwarded.
15060For this reason, samples fetched from buffer contents during a request cannot
15061be used in a response for example. Even while the data are being fetched, they
15062can change. Sometimes it is necessary to set some delays or combine multiple
15063sample fetch methods to ensure that the expected data are complete and usable,
15064for example through TCP request content inspection. Please see the "tcp-request
15065content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020015066
Willy Tarreau74ca5042013-06-11 23:12:07 +020015067payload(<offset>,<length>) : binary (deprecated)
Davor Ocelice9ed2812017-12-25 17:49:28 +010015068 This is an alias for "req.payload" when used in the context of a request (e.g.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015069 "stick on", "stick match"), and for "res.payload" when used in the context of
15070 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010015071
Willy Tarreau74ca5042013-06-11 23:12:07 +020015072payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
15073 This is an alias for "req.payload_lv" when used in the context of a request
Davor Ocelice9ed2812017-12-25 17:49:28 +010015074 (e.g. "stick on", "stick match"), and for "res.payload_lv" when used in the
Willy Tarreau74ca5042013-06-11 23:12:07 +020015075 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010015076
Thierry FOURNIERd7d88812017-04-19 15:15:14 +020015077req.hdrs : string
15078 Returns the current request headers as string including the last empty line
15079 separating headers from the request body. The last empty line can be used to
15080 detect a truncated header block. This sample fetch is useful for some SPOE
15081 headers analyzers and for advanced logging.
15082
Thierry FOURNIER5617dce2017-04-09 05:38:19 +020015083req.hdrs_bin : binary
15084 Returns the current request headers contained in preparsed binary form. This
15085 is useful for offloading some processing with SPOE. Each string is described
15086 by a length followed by the number of bytes indicated in the length. The
15087 length is represented using the variable integer encoding detailed in the
15088 SPOE documentation. The end of the list is marked by a couple of empty header
15089 names and values (length of 0 for both).
15090
15091 *(<str:header-name><str:header-value>)<empty string><empty string>
15092
15093 int: refer to the SPOE documentation for the encoding
15094 str: <int:length><bytes>
15095
Willy Tarreau74ca5042013-06-11 23:12:07 +020015096req.len : integer
15097req_len : integer (deprecated)
15098 Returns an integer value corresponding to the number of bytes present in the
15099 request buffer. This is mostly used in ACL. It is important to understand
15100 that this test does not return false as long as the buffer is changing. This
15101 means that a check with equality to zero will almost always immediately match
15102 at the beginning of the session, while a test for more data will wait for
15103 that data to come in and return false only when haproxy is certain that no
15104 more data will come in. This test was designed to be used with TCP request
15105 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015106
Willy Tarreau74ca5042013-06-11 23:12:07 +020015107req.payload(<offset>,<length>) : binary
15108 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020015109 in the request buffer. As a special case, if the <length> argument is zero,
15110 the the whole buffer from <offset> to the end is extracted. This can be used
15111 with ACLs in order to check for the presence of some content in a buffer at
15112 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015113
Willy Tarreau74ca5042013-06-11 23:12:07 +020015114 ACL alternatives :
15115 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015116
Willy Tarreau74ca5042013-06-11 23:12:07 +020015117req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
15118 This extracts a binary block whose size is specified at <offset1> for <length>
15119 bytes, and which starts at <offset2> if specified or just after the length in
15120 the request buffer. The <offset2> parameter also supports relative offsets if
15121 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015122
Willy Tarreau74ca5042013-06-11 23:12:07 +020015123 ACL alternatives :
15124 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015125
Willy Tarreau74ca5042013-06-11 23:12:07 +020015126 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015127
Willy Tarreau74ca5042013-06-11 23:12:07 +020015128req.proto_http : boolean
15129req_proto_http : boolean (deprecated)
15130 Returns true when data in the request buffer look like HTTP and correctly
15131 parses as such. It is the same parser as the common HTTP request parser which
15132 is used so there should be no surprises. The test does not match until the
15133 request is complete, failed or timed out. This test may be used to report the
15134 protocol in TCP logs, but the biggest use is to block TCP request analysis
15135 until a complete HTTP request is present in the buffer, for example to track
15136 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015137
Willy Tarreau74ca5042013-06-11 23:12:07 +020015138 Example:
15139 # track request counts per "base" (concatenation of Host+URL)
15140 tcp-request inspect-delay 10s
15141 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015142 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015143
Willy Tarreau74ca5042013-06-11 23:12:07 +020015144req.rdp_cookie([<name>]) : string
15145rdp_cookie([<name>]) : string (deprecated)
15146 When the request buffer looks like the RDP protocol, extracts the RDP cookie
15147 <name>, or any cookie if unspecified. The parser only checks for the first
15148 cookie, as illustrated in the RDP protocol specification. The cookie name is
15149 case insensitive. Generally the "MSTS" cookie name will be used, as it can
15150 contain the user name of the client connecting to the server if properly
15151 configured on the client. The "MSTSHASH" cookie is often used as well for
15152 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015153
Willy Tarreau74ca5042013-06-11 23:12:07 +020015154 This differs from "balance rdp-cookie" in that any balancing algorithm may be
15155 used and thus the distribution of clients to backend servers is not linked to
15156 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
15157 such as "balance roundrobin" or "balance leastconn" will lead to a more even
15158 distribution of clients to backend servers than the hash used by "balance
15159 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015160
Willy Tarreau74ca5042013-06-11 23:12:07 +020015161 ACL derivatives :
15162 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015163
Willy Tarreau74ca5042013-06-11 23:12:07 +020015164 Example :
15165 listen tse-farm
15166 bind 0.0.0.0:3389
15167 # wait up to 5s for an RDP cookie in the request
15168 tcp-request inspect-delay 5s
15169 tcp-request content accept if RDP_COOKIE
15170 # apply RDP cookie persistence
15171 persist rdp-cookie
15172 # Persist based on the mstshash cookie
15173 # This is only useful makes sense if
15174 # balance rdp-cookie is not used
15175 stick-table type string size 204800
15176 stick on req.rdp_cookie(mstshash)
15177 server srv1 1.1.1.1:3389
15178 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015179
Willy Tarreau74ca5042013-06-11 23:12:07 +020015180 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
15181 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015182
Willy Tarreau74ca5042013-06-11 23:12:07 +020015183req.rdp_cookie_cnt([name]) : integer
15184rdp_cookie_cnt([name]) : integer (deprecated)
15185 Tries to parse the request buffer as RDP protocol, then returns an integer
15186 corresponding to the number of RDP cookies found. If an optional cookie name
15187 is passed, only cookies matching this name are considered. This is mostly
15188 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015189
Willy Tarreau74ca5042013-06-11 23:12:07 +020015190 ACL derivatives :
15191 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015192
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020015193req.ssl_ec_ext : boolean
15194 Returns a boolean identifying if client sent the Supported Elliptic Curves
15195 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
Cyril Bonté307ee1e2015-09-28 23:16:06 +020015196 message. This can be used to present ECC compatible clients with EC
15197 certificate and to use RSA for all others, on the same IP address. Note that
15198 this only applies to raw contents found in the request buffer and not to
15199 contents deciphered via an SSL data layer, so this will not work with "bind"
15200 lines having the "ssl" option.
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020015201
Willy Tarreau74ca5042013-06-11 23:12:07 +020015202req.ssl_hello_type : integer
15203req_ssl_hello_type : integer (deprecated)
15204 Returns an integer value containing the type of the SSL hello message found
15205 in the request buffer if the buffer contains data that parse as a complete
15206 SSL (v3 or superior) client hello message. Note that this only applies to raw
15207 contents found in the request buffer and not to contents deciphered via an
15208 SSL data layer, so this will not work with "bind" lines having the "ssl"
15209 option. This is mostly used in ACL to detect presence of an SSL hello message
15210 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015211
Willy Tarreau74ca5042013-06-11 23:12:07 +020015212req.ssl_sni : string
15213req_ssl_sni : string (deprecated)
15214 Returns a string containing the value of the Server Name TLS extension sent
15215 by a client in a TLS stream passing through the request buffer if the buffer
15216 contains data that parse as a complete SSL (v3 or superior) client hello
15217 message. Note that this only applies to raw contents found in the request
15218 buffer and not to contents deciphered via an SSL data layer, so this will not
15219 work with "bind" lines having the "ssl" option. SNI normally contains the
15220 name of the host the client tries to connect to (for recent browsers). SNI is
15221 useful for allowing or denying access to certain hosts when SSL/TLS is used
15222 by the client. This test was designed to be used with TCP request content
15223 inspection. If content switching is needed, it is recommended to first wait
15224 for a complete client hello (type 1), like in the example below. See also
15225 "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015226
Willy Tarreau74ca5042013-06-11 23:12:07 +020015227 ACL derivatives :
15228 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015229
Willy Tarreau74ca5042013-06-11 23:12:07 +020015230 Examples :
15231 # Wait for a client hello for at most 5 seconds
15232 tcp-request inspect-delay 5s
15233 tcp-request content accept if { req_ssl_hello_type 1 }
15234 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
15235 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015236
Pradeep Jindalbb2acf52015-09-29 10:12:57 +053015237req.ssl_st_ext : integer
15238 Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077)
15239 Returns 1 if the client sent SessionTicket TLS Extension
15240 Returns 2 if the client also sent non-zero length TLS SessionTicket
15241 Note that this only applies to raw contents found in the request buffer and
15242 not to contents deciphered via an SSL data layer, so this will not work with
15243 "bind" lines having the "ssl" option. This can for example be used to detect
15244 whether the client sent a SessionTicket or not and stick it accordingly, if
15245 no SessionTicket then stick on SessionID or don't stick as there's no server
15246 side state is there when SessionTickets are in use.
15247
Willy Tarreau74ca5042013-06-11 23:12:07 +020015248req.ssl_ver : integer
15249req_ssl_ver : integer (deprecated)
15250 Returns an integer value containing the version of the SSL/TLS protocol of a
15251 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
15252 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
15253 composed of the major version multiplied by 65536, added to the minor
15254 version. Note that this only applies to raw contents found in the request
15255 buffer and not to contents deciphered via an SSL data layer, so this will not
15256 work with "bind" lines having the "ssl" option. The ACL version of the test
Davor Ocelice9ed2812017-12-25 17:49:28 +010015257 matches against a decimal notation in the form MAJOR.MINOR (e.g. 3.1). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020015258 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015259
Willy Tarreau74ca5042013-06-11 23:12:07 +020015260 ACL derivatives :
15261 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010015262
Willy Tarreau47e8eba2013-09-11 23:28:46 +020015263res.len : integer
15264 Returns an integer value corresponding to the number of bytes present in the
15265 response buffer. This is mostly used in ACL. It is important to understand
15266 that this test does not return false as long as the buffer is changing. This
15267 means that a check with equality to zero will almost always immediately match
15268 at the beginning of the session, while a test for more data will wait for
15269 that data to come in and return false only when haproxy is certain that no
15270 more data will come in. This test was designed to be used with TCP response
15271 content inspection.
15272
Willy Tarreau74ca5042013-06-11 23:12:07 +020015273res.payload(<offset>,<length>) : binary
15274 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020015275 in the response buffer. As a special case, if the <length> argument is zero,
15276 the the whole buffer from <offset> to the end is extracted. This can be used
15277 with ACLs in order to check for the presence of some content in a buffer at
15278 any location.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015279
Willy Tarreau74ca5042013-06-11 23:12:07 +020015280res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
15281 This extracts a binary block whose size is specified at <offset1> for <length>
15282 bytes, and which starts at <offset2> if specified or just after the length in
15283 the response buffer. The <offset2> parameter also supports relative offsets
15284 if prepended with a '+' or '-' sign.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015285
Willy Tarreau74ca5042013-06-11 23:12:07 +020015286 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015287
Willy Tarreau971f7b62015-09-29 14:06:59 +020015288res.ssl_hello_type : integer
15289rep_ssl_hello_type : integer (deprecated)
15290 Returns an integer value containing the type of the SSL hello message found
15291 in the response buffer if the buffer contains data that parses as a complete
15292 SSL (v3 or superior) hello message. Note that this only applies to raw
15293 contents found in the response buffer and not to contents deciphered via an
15294 SSL data layer, so this will not work with "server" lines having the "ssl"
15295 option. This is mostly used in ACL to detect presence of an SSL hello message
15296 that is supposed to contain an SSL session ID usable for stickiness.
15297
Willy Tarreau74ca5042013-06-11 23:12:07 +020015298wait_end : boolean
15299 This fetch either returns true when the inspection period is over, or does
15300 not fetch. It is only used in ACLs, in conjunction with content analysis to
Davor Ocelice9ed2812017-12-25 17:49:28 +010015301 avoid returning a wrong verdict early. It may also be used to delay some
Willy Tarreau74ca5042013-06-11 23:12:07 +020015302 actions, such as a delayed reject for some special addresses. Since it either
15303 stops the rules evaluation or immediately returns true, it is recommended to
Davor Ocelice9ed2812017-12-25 17:49:28 +010015304 use this acl as the last one in a rule. Please note that the default ACL
Willy Tarreau74ca5042013-06-11 23:12:07 +020015305 "WAIT_END" is always usable without prior declaration. This test was designed
15306 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015307
Willy Tarreau74ca5042013-06-11 23:12:07 +020015308 Examples :
15309 # delay every incoming request by 2 seconds
15310 tcp-request inspect-delay 2s
15311 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010015312
Willy Tarreau74ca5042013-06-11 23:12:07 +020015313 # don't immediately tell bad guys they are rejected
15314 tcp-request inspect-delay 10s
15315 acl goodguys src 10.0.0.0/24
15316 acl badguys src 10.0.1.0/24
15317 tcp-request content accept if goodguys
15318 tcp-request content reject if badguys WAIT_END
15319 tcp-request content reject
15320
15321
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200153227.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020015323--------------------------------------
15324
15325It is possible to fetch samples from HTTP contents, requests and responses.
15326This application layer is also called layer 7. It is only possible to fetch the
15327data in this section when a full HTTP request or response has been parsed from
15328its respective request or response buffer. This is always the case with all
15329HTTP specific rules and for sections running with "mode http". When using TCP
15330content inspection, it may be necessary to support an inspection delay in order
15331to let the request or response come in first. These fetches may require a bit
15332more CPU resources than the layer 4 ones, but not much since the request and
15333response are indexed.
15334
15335base : string
15336 This returns the concatenation of the first Host header and the path part of
15337 the request, which starts at the first slash and ends before the question
15338 mark. It can be useful in virtual hosted environments to detect URL abuses as
15339 well as to improve shared caches efficiency. Using this with a limited size
15340 stick table also allows one to collect statistics about most commonly
15341 requested objects by host/path. With ACLs it can allow simple content
15342 switching rules involving the host and the path at the same time, such as
15343 "www.example.com/favicon.ico". See also "path" and "uri".
15344
15345 ACL derivatives :
15346 base : exact string match
15347 base_beg : prefix match
15348 base_dir : subdir match
15349 base_dom : domain match
15350 base_end : suffix match
15351 base_len : length match
15352 base_reg : regex match
15353 base_sub : substring match
15354
15355base32 : integer
15356 This returns a 32-bit hash of the value returned by the "base" fetch method
15357 above. This is useful to track per-URL activity on high traffic sites without
15358 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015359 memory. The output type is an unsigned integer. The hash function used is
15360 SDBM with full avalanche on the output. Technically, base32 is exactly equal
15361 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020015362
15363base32+src : binary
15364 This returns the concatenation of the base32 fetch above and the src fetch
15365 below. The resulting type is of type binary, with a size of 8 or 20 bytes
15366 depending on the source address family. This can be used to track per-IP,
15367 per-URL counters.
15368
William Lallemand65ad6e12014-01-31 15:08:02 +010015369capture.req.hdr(<idx>) : string
15370 This extracts the content of the header captured by the "capture request
15371 header", idx is the position of the capture keyword in the configuration.
15372 The first entry is an index of 0. See also: "capture request header".
15373
15374capture.req.method : string
15375 This extracts the METHOD of an HTTP request. It can be used in both request
15376 and response. Unlike "method", it can be used in both request and response
15377 because it's allocated.
15378
15379capture.req.uri : string
15380 This extracts the request's URI, which starts at the first slash and ends
15381 before the first space in the request (without the host part). Unlike "path"
15382 and "url", it can be used in both request and response because it's
15383 allocated.
15384
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020015385capture.req.ver : string
15386 This extracts the request's HTTP version and returns either "HTTP/1.0" or
15387 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
15388 logs because it relies on a persistent flag.
15389
William Lallemand65ad6e12014-01-31 15:08:02 +010015390capture.res.hdr(<idx>) : string
15391 This extracts the content of the header captured by the "capture response
15392 header", idx is the position of the capture keyword in the configuration.
15393 The first entry is an index of 0.
15394 See also: "capture response header"
15395
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020015396capture.res.ver : string
15397 This extracts the response's HTTP version and returns either "HTTP/1.0" or
15398 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
15399 persistent flag.
15400
Willy Tarreaua5910cc2015-05-02 00:46:08 +020015401req.body : binary
15402 This returns the HTTP request's available body as a block of data. It
15403 requires that the request body has been buffered made available using
15404 "option http-buffer-request". In case of chunked-encoded body, currently only
15405 the first chunk is analyzed.
15406
Thierry FOURNIER9826c772015-05-20 15:50:54 +020015407req.body_param([<name>) : string
15408 This fetch assumes that the body of the POST request is url-encoded. The user
15409 can check if the "content-type" contains the value
15410 "application/x-www-form-urlencoded". This extracts the first occurrence of the
15411 parameter <name> in the body, which ends before '&'. The parameter name is
15412 case-sensitive. If no name is given, any parameter will match, and the first
15413 one will be returned. The result is a string corresponding to the value of the
15414 parameter <name> as presented in the request body (no URL decoding is
15415 performed). Note that the ACL version of this fetch iterates over multiple
15416 parameters and will iteratively report all parameters values if no name is
15417 given.
15418
Willy Tarreaua5910cc2015-05-02 00:46:08 +020015419req.body_len : integer
15420 This returns the length of the HTTP request's available body in bytes. It may
15421 be lower than the advertised length if the body is larger than the buffer. It
15422 requires that the request body has been buffered made available using
15423 "option http-buffer-request".
15424
15425req.body_size : integer
15426 This returns the advertised length of the HTTP request's body in bytes. It
15427 will represent the advertised Content-Length header, or the size of the first
15428 chunk in case of chunked encoding. In order to parse the chunks, it requires
15429 that the request body has been buffered made available using
15430 "option http-buffer-request".
15431
Willy Tarreau74ca5042013-06-11 23:12:07 +020015432req.cook([<name>]) : string
15433cook([<name>]) : string (deprecated)
15434 This extracts the last occurrence of the cookie name <name> on a "Cookie"
15435 header line from the request, and returns its value as string. If no name is
15436 specified, the first cookie value is returned. When used with ACLs, all
15437 matching cookies are evaluated. Spaces around the name and the value are
15438 ignored as requested by the Cookie header specification (RFC6265). The cookie
15439 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
15440 well return an empty value if it is present. Use the "found" match to detect
15441 presence. Use the res.cook() variant for response cookies sent by the server.
15442
15443 ACL derivatives :
15444 cook([<name>]) : exact string match
15445 cook_beg([<name>]) : prefix match
15446 cook_dir([<name>]) : subdir match
15447 cook_dom([<name>]) : domain match
15448 cook_end([<name>]) : suffix match
15449 cook_len([<name>]) : length match
15450 cook_reg([<name>]) : regex match
15451 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010015452
Willy Tarreau74ca5042013-06-11 23:12:07 +020015453req.cook_cnt([<name>]) : integer
15454cook_cnt([<name>]) : integer (deprecated)
15455 Returns an integer value representing the number of occurrences of the cookie
15456 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015457
Willy Tarreau74ca5042013-06-11 23:12:07 +020015458req.cook_val([<name>]) : integer
15459cook_val([<name>]) : integer (deprecated)
15460 This extracts the last occurrence of the cookie name <name> on a "Cookie"
15461 header line from the request, and converts its value to an integer which is
15462 returned. If no name is specified, the first cookie value is returned. When
15463 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020015464
Willy Tarreau74ca5042013-06-11 23:12:07 +020015465cookie([<name>]) : string (deprecated)
15466 This extracts the last occurrence of the cookie name <name> on a "Cookie"
15467 header line from the request, or a "Set-Cookie" header from the response, and
15468 returns its value as a string. A typical use is to get multiple clients
15469 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020015470 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020015471 multi-peer synchronization and state keeping across restarts. If no name is
15472 specified, the first cookie value is returned. This fetch should not be used
15473 anymore and should be replaced by req.cook() or res.cook() instead as it
15474 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015475
Willy Tarreau74ca5042013-06-11 23:12:07 +020015476hdr([<name>[,<occ>]]) : string
15477 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
15478 used on responses. Please refer to these respective fetches for more details.
15479 In case of doubt about the fetch direction, please use the explicit ones.
15480 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015481 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015482
Willy Tarreau74ca5042013-06-11 23:12:07 +020015483req.fhdr(<name>[,<occ>]) : string
15484 This extracts the last occurrence of header <name> in an HTTP request. When
15485 used from an ACL, all occurrences are iterated over until a match is found.
15486 Optionally, a specific occurrence might be specified as a position number.
15487 Positive values indicate a position from the first occurrence, with 1 being
15488 the first one. Negative values indicate positions relative to the last one,
15489 with -1 being the last one. It differs from req.hdr() in that any commas
15490 present in the value are returned and are not used as delimiters. This is
15491 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015492
Willy Tarreau74ca5042013-06-11 23:12:07 +020015493req.fhdr_cnt([<name>]) : integer
15494 Returns an integer value representing the number of occurrences of request
15495 header field name <name>, or the total number of header fields if <name> is
15496 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
15497 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015498
Willy Tarreau74ca5042013-06-11 23:12:07 +020015499req.hdr([<name>[,<occ>]]) : string
15500 This extracts the last occurrence of header <name> in an HTTP request. When
15501 used from an ACL, all occurrences are iterated over until a match is found.
15502 Optionally, a specific occurrence might be specified as a position number.
15503 Positive values indicate a position from the first occurrence, with 1 being
15504 the first one. Negative values indicate positions relative to the last one,
15505 with -1 being the last one. A typical use is with the X-Forwarded-For header
15506 once converted to IP, associated with an IP stick-table. The function
15507 considers any comma as a delimiter for distinct values. If full-line headers
Lukas Tribus23953682017-04-28 13:24:30 +000015508 are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
Willy Tarreau74ca5042013-06-11 23:12:07 +020015509 how certain headers are supposed to be parsed. Also, some of them are case
Davor Ocelice9ed2812017-12-25 17:49:28 +010015510 insensitive (e.g. Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010015511
Willy Tarreau74ca5042013-06-11 23:12:07 +020015512 ACL derivatives :
15513 hdr([<name>[,<occ>]]) : exact string match
15514 hdr_beg([<name>[,<occ>]]) : prefix match
15515 hdr_dir([<name>[,<occ>]]) : subdir match
15516 hdr_dom([<name>[,<occ>]]) : domain match
15517 hdr_end([<name>[,<occ>]]) : suffix match
15518 hdr_len([<name>[,<occ>]]) : length match
15519 hdr_reg([<name>[,<occ>]]) : regex match
15520 hdr_sub([<name>[,<occ>]]) : substring match
15521
15522req.hdr_cnt([<name>]) : integer
15523hdr_cnt([<header>]) : integer (deprecated)
15524 Returns an integer value representing the number of occurrences of request
15525 header field name <name>, or the total number of header field values if
15526 <name> is not specified. It is important to remember that one header line may
15527 count as several headers if it has several values. The function considers any
15528 comma as a delimiter for distinct values. If full-line headers are desired
15529 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
15530 detect presence, absence or abuse of a specific header, as well as to block
15531 request smuggling attacks by rejecting requests which contain more than one
15532 of certain headers. See "req.hdr" for more information on header matching.
15533
15534req.hdr_ip([<name>[,<occ>]]) : ip
15535hdr_ip([<name>[,<occ>]]) : ip (deprecated)
15536 This extracts the last occurrence of header <name> in an HTTP request,
15537 converts it to an IPv4 or IPv6 address and returns this address. When used
15538 with ACLs, all occurrences are checked, and if <name> is omitted, every value
15539 of every header is checked. Optionally, a specific occurrence might be
15540 specified as a position number. Positive values indicate a position from the
Davor Ocelice9ed2812017-12-25 17:49:28 +010015541 first occurrence, with 1 being the first one. Negative values indicate
Willy Tarreau74ca5042013-06-11 23:12:07 +020015542 positions relative to the last one, with -1 being the last one. A typical use
15543 is with the X-Forwarded-For and X-Client-IP headers.
15544
15545req.hdr_val([<name>[,<occ>]]) : integer
15546hdr_val([<name>[,<occ>]]) : integer (deprecated)
15547 This extracts the last occurrence of header <name> in an HTTP request, and
15548 converts it to an integer value. When used with ACLs, all occurrences are
15549 checked, and if <name> is omitted, every value of every header is checked.
15550 Optionally, a specific occurrence might be specified as a position number.
15551 Positive values indicate a position from the first occurrence, with 1 being
15552 the first one. Negative values indicate positions relative to the last one,
15553 with -1 being the last one. A typical use is with the X-Forwarded-For header.
15554
15555http_auth(<userlist>) : boolean
15556 Returns a boolean indicating whether the authentication data received from
15557 the client match a username & password stored in the specified userlist. This
15558 fetch function is not really useful outside of ACLs. Currently only http
15559 basic auth is supported.
15560
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010015561http_auth_group(<userlist>) : string
15562 Returns a string corresponding to the user name found in the authentication
15563 data received from the client if both the user name and password are valid
15564 according to the specified userlist. The main purpose is to use it in ACLs
15565 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015566 This fetch function is not really useful outside of ACLs. Currently only http
15567 basic auth is supported.
15568
15569 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010015570 http_auth_group(<userlist>) : group ...
15571 Returns true when the user extracted from the request and whose password is
15572 valid according to the specified userlist belongs to at least one of the
15573 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015574
15575http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020015576 Returns true when the request being processed is the first one of the
15577 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020015578 from some requests when a request is not the first one, or to help grouping
15579 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020015580
Willy Tarreau74ca5042013-06-11 23:12:07 +020015581method : integer + string
15582 Returns an integer value corresponding to the method in the HTTP request. For
15583 example, "GET" equals 1 (check sources to establish the matching). Value 9
15584 means "other method" and may be converted to a string extracted from the
15585 stream. This should not be used directly as a sample, this is only meant to
15586 be used from ACLs, which transparently convert methods from patterns to these
15587 integer + string values. Some predefined ACL already check for most common
15588 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015589
Willy Tarreau74ca5042013-06-11 23:12:07 +020015590 ACL derivatives :
15591 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020015592
Willy Tarreau74ca5042013-06-11 23:12:07 +020015593 Example :
15594 # only accept GET and HEAD requests
15595 acl valid_method method GET HEAD
15596 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020015597
Willy Tarreau74ca5042013-06-11 23:12:07 +020015598path : string
15599 This extracts the request's URL path, which starts at the first slash and
15600 ends before the question mark (without the host part). A typical use is with
15601 prefetch-capable caches, and with portals which need to aggregate multiple
15602 information from databases and keep them in caches. Note that with outgoing
15603 caches, it would be wiser to use "url" instead. With ACLs, it's typically
Davor Ocelice9ed2812017-12-25 17:49:28 +010015604 used to match exact file names (e.g. "/login.php"), or directory parts using
Willy Tarreau74ca5042013-06-11 23:12:07 +020015605 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015606
Willy Tarreau74ca5042013-06-11 23:12:07 +020015607 ACL derivatives :
15608 path : exact string match
15609 path_beg : prefix match
15610 path_dir : subdir match
15611 path_dom : domain match
15612 path_end : suffix match
15613 path_len : length match
15614 path_reg : regex match
15615 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020015616
Willy Tarreau49ad95c2015-01-19 15:06:26 +010015617query : string
15618 This extracts the request's query string, which starts after the first
15619 question mark. If no question mark is present, this fetch returns nothing. If
15620 a question mark is present but nothing follows, it returns an empty string.
15621 This means it's possible to easily know whether a query string is present
Tim Düsterhus4896c442016-11-29 02:15:19 +010015622 using the "found" matching method. This fetch is the complement of "path"
Willy Tarreau49ad95c2015-01-19 15:06:26 +010015623 which stops before the question mark.
15624
Willy Tarreaueb27ec72015-02-20 13:55:29 +010015625req.hdr_names([<delim>]) : string
15626 This builds a string made from the concatenation of all header names as they
15627 appear in the request when the rule is evaluated. The default delimiter is
15628 the comma (',') but it may be overridden as an optional argument <delim>. In
15629 this case, only the first character of <delim> is considered.
15630
Willy Tarreau74ca5042013-06-11 23:12:07 +020015631req.ver : string
15632req_ver : string (deprecated)
15633 Returns the version string from the HTTP request, for example "1.1". This can
15634 be useful for logs, but is mostly there for ACL. Some predefined ACL already
15635 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015636
Willy Tarreau74ca5042013-06-11 23:12:07 +020015637 ACL derivatives :
15638 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020015639
Willy Tarreau74ca5042013-06-11 23:12:07 +020015640res.comp : boolean
15641 Returns the boolean "true" value if the response has been compressed by
15642 HAProxy, otherwise returns boolean "false". This may be used to add
15643 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015644
Willy Tarreau74ca5042013-06-11 23:12:07 +020015645res.comp_algo : string
15646 Returns a string containing the name of the algorithm used if the response
15647 was compressed by HAProxy, for example : "deflate". This may be used to add
15648 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015649
Willy Tarreau74ca5042013-06-11 23:12:07 +020015650res.cook([<name>]) : string
15651scook([<name>]) : string (deprecated)
15652 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
15653 header line from the response, and returns its value as string. If no name is
15654 specified, the first cookie value is returned.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020015655
Willy Tarreau74ca5042013-06-11 23:12:07 +020015656 ACL derivatives :
15657 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020015658
Willy Tarreau74ca5042013-06-11 23:12:07 +020015659res.cook_cnt([<name>]) : integer
15660scook_cnt([<name>]) : integer (deprecated)
15661 Returns an integer value representing the number of occurrences of the cookie
15662 <name> in the response, or all cookies if <name> is not specified. This is
15663 mostly useful when combined with ACLs to detect suspicious responses.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015664
Willy Tarreau74ca5042013-06-11 23:12:07 +020015665res.cook_val([<name>]) : integer
15666scook_val([<name>]) : integer (deprecated)
15667 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
15668 header line from the response, and converts its value to an integer which is
15669 returned. If no name is specified, the first cookie value is returned.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015670
Willy Tarreau74ca5042013-06-11 23:12:07 +020015671res.fhdr([<name>[,<occ>]]) : string
15672 This extracts the last occurrence of header <name> in an HTTP response, or of
15673 the last header if no <name> is specified. Optionally, a specific occurrence
15674 might be specified as a position number. Positive values indicate a position
15675 from the first occurrence, with 1 being the first one. Negative values
15676 indicate positions relative to the last one, with -1 being the last one. It
15677 differs from res.hdr() in that any commas present in the value are returned
15678 and are not used as delimiters. If this is not desired, the res.hdr() fetch
15679 should be used instead. This is sometimes useful with headers such as Date or
15680 Expires.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015681
Willy Tarreau74ca5042013-06-11 23:12:07 +020015682res.fhdr_cnt([<name>]) : integer
15683 Returns an integer value representing the number of occurrences of response
15684 header field name <name>, or the total number of header fields if <name> is
15685 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
15686 the number of full line headers and does not stop on commas. If this is not
15687 desired, the res.hdr_cnt() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015688
Willy Tarreau74ca5042013-06-11 23:12:07 +020015689res.hdr([<name>[,<occ>]]) : string
15690shdr([<name>[,<occ>]]) : string (deprecated)
15691 This extracts the last occurrence of header <name> in an HTTP response, or of
15692 the last header if no <name> is specified. Optionally, a specific occurrence
15693 might be specified as a position number. Positive values indicate a position
15694 from the first occurrence, with 1 being the first one. Negative values
15695 indicate positions relative to the last one, with -1 being the last one. This
15696 can be useful to learn some data into a stick-table. The function considers
15697 any comma as a delimiter for distinct values. If this is not desired, the
15698 res.fhdr() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015699
Willy Tarreau74ca5042013-06-11 23:12:07 +020015700 ACL derivatives :
15701 shdr([<name>[,<occ>]]) : exact string match
15702 shdr_beg([<name>[,<occ>]]) : prefix match
15703 shdr_dir([<name>[,<occ>]]) : subdir match
15704 shdr_dom([<name>[,<occ>]]) : domain match
15705 shdr_end([<name>[,<occ>]]) : suffix match
15706 shdr_len([<name>[,<occ>]]) : length match
15707 shdr_reg([<name>[,<occ>]]) : regex match
15708 shdr_sub([<name>[,<occ>]]) : substring match
15709
15710res.hdr_cnt([<name>]) : integer
15711shdr_cnt([<name>]) : integer (deprecated)
15712 Returns an integer value representing the number of occurrences of response
15713 header field name <name>, or the total number of header fields if <name> is
15714 not specified. The function considers any comma as a delimiter for distinct
15715 values. If this is not desired, the res.fhdr_cnt() fetch should be used
15716 instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015717
Willy Tarreau74ca5042013-06-11 23:12:07 +020015718res.hdr_ip([<name>[,<occ>]]) : ip
15719shdr_ip([<name>[,<occ>]]) : ip (deprecated)
15720 This extracts the last occurrence of header <name> in an HTTP response,
15721 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
15722 specific occurrence might be specified as a position number. Positive values
15723 indicate a position from the first occurrence, with 1 being the first one.
15724 Negative values indicate positions relative to the last one, with -1 being
15725 the last one. This can be useful to learn some data into a stick table.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015726
Willy Tarreaueb27ec72015-02-20 13:55:29 +010015727res.hdr_names([<delim>]) : string
15728 This builds a string made from the concatenation of all header names as they
15729 appear in the response when the rule is evaluated. The default delimiter is
15730 the comma (',') but it may be overridden as an optional argument <delim>. In
15731 this case, only the first character of <delim> is considered.
15732
Willy Tarreau74ca5042013-06-11 23:12:07 +020015733res.hdr_val([<name>[,<occ>]]) : integer
15734shdr_val([<name>[,<occ>]]) : integer (deprecated)
15735 This extracts the last occurrence of header <name> in an HTTP response, and
15736 converts it to an integer value. Optionally, a specific occurrence might be
15737 specified as a position number. Positive values indicate a position from the
15738 first occurrence, with 1 being the first one. Negative values indicate
15739 positions relative to the last one, with -1 being the last one. This can be
15740 useful to learn some data into a stick table.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010015741
Willy Tarreau74ca5042013-06-11 23:12:07 +020015742res.ver : string
15743resp_ver : string (deprecated)
15744 Returns the version string from the HTTP response, for example "1.1". This
15745 can be useful for logs, but is mostly there for ACL.
Willy Tarreau0e698542011-09-16 08:32:32 +020015746
Willy Tarreau74ca5042013-06-11 23:12:07 +020015747 ACL derivatives :
15748 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010015749
Willy Tarreau74ca5042013-06-11 23:12:07 +020015750set-cookie([<name>]) : string (deprecated)
15751 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
15752 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020015753 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020015754 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010015755
Willy Tarreau74ca5042013-06-11 23:12:07 +020015756 This fetch function is deprecated and has been superseded by the "res.cook"
15757 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010015758
Willy Tarreau74ca5042013-06-11 23:12:07 +020015759status : integer
15760 Returns an integer containing the HTTP status code in the HTTP response, for
15761 example, 302. It is mostly used within ACLs and integer ranges, for example,
15762 to remove any Location header if the response is not a 3xx.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015763
Thierry Fournier0e00dca2016-04-07 15:47:40 +020015764unique-id : string
15765 Returns the unique-id attached to the request. The directive
15766 "unique-id-format" must be set. If it is not set, the unique-id sample fetch
15767 fails. Note that the unique-id is usually used with HTTP requests, however this
15768 sample fetch can be used with other protocols. Obviously, if it is used with
15769 other protocols than HTTP, the unique-id-format directive must not contain
15770 HTTP parts. See: unique-id-format and unique-id-header
15771
Willy Tarreau74ca5042013-06-11 23:12:07 +020015772url : string
15773 This extracts the request's URL as presented in the request. A typical use is
15774 with prefetch-capable caches, and with portals which need to aggregate
15775 multiple information from databases and keep them in caches. With ACLs, using
15776 "path" is preferred over using "url", because clients may send a full URL as
15777 is normally done with proxies. The only real use is to match "*" which does
15778 not match in "path", and for which there is already a predefined ACL. See
15779 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015780
Willy Tarreau74ca5042013-06-11 23:12:07 +020015781 ACL derivatives :
15782 url : exact string match
15783 url_beg : prefix match
15784 url_dir : subdir match
15785 url_dom : domain match
15786 url_end : suffix match
15787 url_len : length match
15788 url_reg : regex match
15789 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015790
Willy Tarreau74ca5042013-06-11 23:12:07 +020015791url_ip : ip
15792 This extracts the IP address from the request's URL when the host part is
15793 presented as an IP address. Its use is very limited. For instance, a
15794 monitoring system might use this field as an alternative for the source IP in
15795 order to test what path a given source address would follow, or to force an
15796 entry in a table for a given source address. With ACLs it can be used to
15797 restrict access to certain systems through a proxy, for example when combined
15798 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015799
Willy Tarreau74ca5042013-06-11 23:12:07 +020015800url_port : integer
15801 This extracts the port part from the request's URL. Note that if the port is
15802 not specified in the request, port 80 is assumed. With ACLs it can be used to
15803 restrict access to certain systems through a proxy, for example when combined
15804 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015805
Willy Tarreau1ede1da2015-05-07 16:06:18 +020015806urlp([<name>[,<delim>]]) : string
15807url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020015808 This extracts the first occurrence of the parameter <name> in the query
15809 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020015810 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
15811 any parameter will match, and the first one will be returned. The result is
15812 a string corresponding to the value of the parameter <name> as presented in
15813 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020015814 stickiness based on a client ID, to extract an application cookie passed as a
15815 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020015816 this fetch iterates over multiple parameters and will iteratively report all
15817 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015818
Willy Tarreau74ca5042013-06-11 23:12:07 +020015819 ACL derivatives :
15820 urlp(<name>[,<delim>]) : exact string match
15821 urlp_beg(<name>[,<delim>]) : prefix match
15822 urlp_dir(<name>[,<delim>]) : subdir match
15823 urlp_dom(<name>[,<delim>]) : domain match
15824 urlp_end(<name>[,<delim>]) : suffix match
15825 urlp_len(<name>[,<delim>]) : length match
15826 urlp_reg(<name>[,<delim>]) : regex match
15827 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015828
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015829
Willy Tarreau74ca5042013-06-11 23:12:07 +020015830 Example :
15831 # match http://example.com/foo?PHPSESSIONID=some_id
15832 stick on urlp(PHPSESSIONID)
15833 # match http://example.com/foo;JSESSIONID=some_id
15834 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015835
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015836urlp_val([<name>[,<delim>]]) : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020015837 See "urlp" above. This one extracts the URL parameter <name> in the request
15838 and converts it to an integer value. This can be used for session stickiness
15839 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020015840
Dragan Dosen0070cd52016-06-16 12:19:49 +020015841url32 : integer
15842 This returns a 32-bit hash of the value obtained by concatenating the first
15843 Host header and the whole URL including parameters (not only the path part of
15844 the request, as in the "base32" fetch above). This is useful to track per-URL
15845 activity. A shorter hash is stored, saving a lot of memory. The output type
15846 is an unsigned integer.
15847
15848url32+src : binary
15849 This returns the concatenation of the "url32" fetch and the "src" fetch. The
15850 resulting type is of type binary, with a size of 8 or 20 bytes depending on
15851 the source address family. This can be used to track per-IP, per-URL counters.
15852
Willy Tarreau198a7442008-01-17 12:05:32 +010015853
Willy Tarreau74ca5042013-06-11 23:12:07 +0200158547.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015855---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010015856
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015857Some predefined ACLs are hard-coded so that they do not have to be declared in
15858every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020015859order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010015860
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015861ACL name Equivalent to Usage
15862---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015863FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020015864HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015865HTTP_1.0 req_ver 1.0 match HTTP version 1.0
15866HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010015867HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
15868HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
15869HTTP_URL_SLASH url_beg / match URL beginning with "/"
15870HTTP_URL_STAR url * match URL equal to "*"
15871LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015872METH_CONNECT method CONNECT match HTTP CONNECT method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020015873METH_DELETE method DELETE match HTTP DELETE method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015874METH_GET method GET HEAD match HTTP GET or HEAD method
15875METH_HEAD method HEAD match HTTP HEAD method
15876METH_OPTIONS method OPTIONS match HTTP OPTIONS method
15877METH_POST method POST match HTTP POST method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020015878METH_PUT method PUT match HTTP PUT method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015879METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020015880RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015881REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010015882TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015883WAIT_END wait_end wait for end of content analysis
15884---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010015885
Willy Tarreaub937b7e2010-01-12 15:27:54 +010015886
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200158878. Logging
15888----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010015889
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015890One of HAProxy's strong points certainly lies is its precise logs. It probably
15891provides the finest level of information available for such a product, which is
15892very important for troubleshooting complex environments. Standard information
15893provided in logs include client ports, TCP/HTTP state timers, precise session
15894state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010015895to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015896headers.
15897
15898In order to improve administrators reactivity, it offers a great transparency
15899about encountered problems, both internal and external, and it is possible to
15900send logs to different sources at the same time with different level filters :
15901
15902 - global process-level logs (system errors, start/stop, etc..)
15903 - per-instance system and internal errors (lack of resource, bugs, ...)
15904 - per-instance external troubles (servers up/down, max connections)
15905 - per-instance activity (client connections), either at the establishment or
15906 at the termination.
Davor Ocelice9ed2812017-12-25 17:49:28 +010015907 - per-request control of log-level, e.g.
Jim Freeman9e8714b2015-05-26 09:16:34 -060015908 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015909
15910The ability to distribute different levels of logs to different log servers
15911allow several production teams to interact and to fix their problems as soon
15912as possible. For example, the system team might monitor system-wide errors,
15913while the application team might be monitoring the up/down for their servers in
15914real time, and the security team might analyze the activity logs with one hour
15915delay.
15916
15917
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200159188.1. Log levels
15919---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015920
Simon Hormandf791f52011-05-29 15:01:10 +090015921TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015922source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090015923HTTP request, HTTP return code, number of bytes transmitted, conditions
15924in which the session ended, and even exchanged cookies values. For example
15925track a particular user's problems. All messages may be sent to up to two
15926syslog servers. Check the "log" keyword in section 4.2 for more information
15927about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015928
15929
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200159308.2. Log formats
15931----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015932
William Lallemand48940402012-01-30 16:47:22 +010015933HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090015934and will be detailed in the following sections. A few of them may vary
15935slightly with the configuration, due to indicators specific to certain
15936options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015937
15938 - the default format, which is very basic and very rarely used. It only
15939 provides very basic information about the incoming connection at the moment
15940 it is accepted : source IP:port, destination IP:port, and frontend-name.
15941 This mode will eventually disappear so it will not be described to great
15942 extents.
15943
15944 - the TCP format, which is more advanced. This format is enabled when "option
15945 tcplog" is set on the frontend. HAProxy will then usually wait for the
15946 connection to terminate before logging. This format provides much richer
15947 information, such as timers, connection counts, queue size, etc... This
15948 format is recommended for pure TCP proxies.
15949
15950 - the HTTP format, which is the most advanced for HTTP proxying. This format
15951 is enabled when "option httplog" is set on the frontend. It provides the
15952 same information as the TCP format with some HTTP-specific fields such as
15953 the request, the status code, and captures of headers and cookies. This
15954 format is recommended for HTTP proxies.
15955
Emeric Brun3a058f32009-06-30 18:26:00 +020015956 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
15957 fields arranged in the same order as the CLF format. In this mode, all
15958 timers, captures, flags, etc... appear one per field after the end of the
15959 common fields, in the same order they appear in the standard HTTP format.
15960
William Lallemand48940402012-01-30 16:47:22 +010015961 - the custom log format, allows you to make your own log line.
15962
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015963Next sections will go deeper into details for each of these formats. Format
15964specification will be performed on a "field" basis. Unless stated otherwise, a
15965field is a portion of text delimited by any number of spaces. Since syslog
15966servers are susceptible of inserting fields at the beginning of a line, it is
15967always assumed that the first field is the one containing the process name and
15968identifier.
15969
15970Note : Since log lines may be quite long, the log examples in sections below
15971 might be broken into multiple lines. The example log lines will be
15972 prefixed with 3 closing angle brackets ('>>>') and each time a log is
15973 broken into multiple lines, each non-final line will end with a
15974 backslash ('\') and the next line will start indented by two characters.
15975
15976
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200159778.2.1. Default log format
15978-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015979
15980This format is used when no specific option is set. The log is emitted as soon
15981as the connection is accepted. One should note that this currently is the only
15982format which logs the request's destination IP and ports.
15983
15984 Example :
15985 listen www
15986 mode http
15987 log global
15988 server srv1 127.0.0.1:8000
15989
15990 >>> Feb 6 12:12:09 localhost \
15991 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
15992 (www/HTTP)
15993
15994 Field Format Extract from the example above
15995 1 process_name '[' pid ']:' haproxy[14385]:
15996 2 'Connect from' Connect from
15997 3 source_ip ':' source_port 10.0.1.2:33312
15998 4 'to' to
15999 5 destination_ip ':' destination_port 10.0.3.31:8012
16000 6 '(' frontend_name '/' mode ')' (www/HTTP)
16001
16002Detailed fields description :
16003 - "source_ip" is the IP address of the client which initiated the connection.
16004 - "source_port" is the TCP port of the client which initiated the connection.
16005 - "destination_ip" is the IP address the client connected to.
16006 - "destination_port" is the TCP port the client connected to.
16007 - "frontend_name" is the name of the frontend (or listener) which received
16008 and processed the connection.
16009 - "mode is the mode the frontend is operating (TCP or HTTP).
16010
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016011In case of a UNIX socket, the source and destination addresses are marked as
16012"unix:" and the ports reflect the internal ID of the socket which accepted the
16013connection (the same ID as reported in the stats).
16014
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016015It is advised not to use this deprecated format for newer installations as it
16016will eventually disappear.
16017
16018
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200160198.2.2. TCP log format
16020---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016021
16022The TCP format is used when "option tcplog" is specified in the frontend, and
16023is the recommended format for pure TCP proxies. It provides a lot of precious
16024information for troubleshooting. Since this format includes timers and byte
16025counts, the log is normally emitted at the end of the session. It can be
16026emitted earlier if "option logasap" is specified, which makes sense in most
16027environments with long sessions such as remote terminals. Sessions which match
16028the "monitor" rules are never logged. It is also possible not to emit logs for
16029sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016030specifying "option dontlognull" in the frontend. Successful connections will
16031not be logged if "option dontlog-normal" is specified in the frontend. A few
16032fields may slightly vary depending on some configuration options, those are
16033marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016034
16035 Example :
16036 frontend fnt
16037 mode tcp
16038 option tcplog
16039 log global
16040 default_backend bck
16041
16042 backend bck
16043 server srv1 127.0.0.1:8000
16044
16045 >>> Feb 6 12:12:56 localhost \
16046 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
16047 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
16048
16049 Field Format Extract from the example above
16050 1 process_name '[' pid ']:' haproxy[14387]:
16051 2 client_ip ':' client_port 10.0.1.2:33313
16052 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
16053 4 frontend_name fnt
16054 5 backend_name '/' server_name bck/srv1
16055 6 Tw '/' Tc '/' Tt* 0/0/5007
16056 7 bytes_read* 212
16057 8 termination_state --
16058 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
16059 10 srv_queue '/' backend_queue 0/0
16060
16061Detailed fields description :
16062 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016063 connection to haproxy. If the connection was accepted on a UNIX socket
16064 instead, the IP address would be replaced with the word "unix". Note that
16065 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016066 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010016067 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016068 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016069
16070 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016071 If the connection was accepted on a UNIX socket instead, the port would be
16072 replaced with the ID of the accepting socket, which is also reported in the
16073 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016074
16075 - "accept_date" is the exact date when the connection was received by haproxy
16076 (which might be very slightly different from the date observed on the
16077 network if there was some queuing in the system's backlog). This is usually
Willy Tarreau590a0512018-09-05 11:56:48 +020016078 the same date which may appear in any upstream firewall's log. When used in
16079 HTTP mode, the accept_date field will be reset to the first moment the
16080 connection is ready to receive a new request (end of previous response for
16081 HTTP/1, immediately after previous request for HTTP/2).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016082
16083 - "frontend_name" is the name of the frontend (or listener) which received
16084 and processed the connection.
16085
16086 - "backend_name" is the name of the backend (or listener) which was selected
16087 to manage the connection to the server. This will be the same as the
16088 frontend if no switching rule has been applied, which is common for TCP
16089 applications.
16090
16091 - "server_name" is the name of the last server to which the connection was
16092 sent, which might differ from the first one if there were connection errors
16093 and a redispatch occurred. Note that this server belongs to the backend
16094 which processed the request. If the connection was aborted before reaching
16095 a server, "<NOSRV>" is indicated instead of a server name.
16096
16097 - "Tw" is the total time in milliseconds spent waiting in the various queues.
16098 It can be "-1" if the connection was aborted before reaching the queue.
16099 See "Timers" below for more details.
16100
16101 - "Tc" is the total time in milliseconds spent waiting for the connection to
16102 establish to the final server, including retries. It can be "-1" if the
16103 connection was aborted before a connection could be established. See
16104 "Timers" below for more details.
16105
16106 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016107 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016108 "option logasap" was specified, then the time counting stops at the moment
16109 the log is emitted. In this case, a '+' sign is prepended before the value,
16110 indicating that the final one will be larger. See "Timers" below for more
16111 details.
16112
16113 - "bytes_read" is the total number of bytes transmitted from the server to
16114 the client when the log is emitted. If "option logasap" is specified, the
16115 this value will be prefixed with a '+' sign indicating that the final one
16116 may be larger. Please note that this value is a 64-bit counter, so log
16117 analysis tools must be able to handle it without overflowing.
16118
16119 - "termination_state" is the condition the session was in when the session
16120 ended. This indicates the session state, which side caused the end of
16121 session to happen, and for what reason (timeout, error, ...). The normal
16122 flags should be "--", indicating the session was closed by either end with
16123 no data remaining in buffers. See below "Session state at disconnection"
16124 for more details.
16125
16126 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016127 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016128 limits have been reached. For instance, if actconn is close to 512 when
16129 multiple connection errors occur, chances are high that the system limits
16130 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016131 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016132
16133 - "feconn" is the total number of concurrent connections on the frontend when
16134 the session was logged. It is useful to estimate the amount of resource
16135 required to sustain high loads, and to detect when the frontend's "maxconn"
16136 has been reached. Most often when this value increases by huge jumps, it is
16137 because there is congestion on the backend servers, but sometimes it can be
16138 caused by a denial of service attack.
16139
16140 - "beconn" is the total number of concurrent connections handled by the
16141 backend when the session was logged. It includes the total number of
16142 concurrent connections active on servers as well as the number of
16143 connections pending in queues. It is useful to estimate the amount of
16144 additional servers needed to support high loads for a given application.
16145 Most often when this value increases by huge jumps, it is because there is
16146 congestion on the backend servers, but sometimes it can be caused by a
16147 denial of service attack.
16148
16149 - "srv_conn" is the total number of concurrent connections still active on
16150 the server when the session was logged. It can never exceed the server's
16151 configured "maxconn" parameter. If this value is very often close or equal
16152 to the server's "maxconn", it means that traffic regulation is involved a
16153 lot, meaning that either the server's maxconn value is too low, or that
16154 there aren't enough servers to process the load with an optimal response
16155 time. When only one of the server's "srv_conn" is high, it usually means
16156 that this server has some trouble causing the connections to take longer to
16157 be processed than on other servers.
16158
16159 - "retries" is the number of connection retries experienced by this session
16160 when trying to connect to the server. It must normally be zero, unless a
16161 server is being stopped at the same moment the connection was attempted.
16162 Frequent retries generally indicate either a network problem between
16163 haproxy and the server, or a misconfigured system backlog on the server
16164 preventing new connections from being queued. This field may optionally be
16165 prefixed with a '+' sign, indicating that the session has experienced a
16166 redispatch after the maximal retry count has been reached on the initial
16167 server. In this case, the server name appearing in the log is the one the
16168 connection was redispatched to, and not the first one, though both may
16169 sometimes be the same in case of hashing for instance. So as a general rule
16170 of thumb, when a '+' is present in front of the retry count, this count
16171 should not be attributed to the logged server.
16172
16173 - "srv_queue" is the total number of requests which were processed before
16174 this one in the server queue. It is zero when the request has not gone
16175 through the server queue. It makes it possible to estimate the approximate
16176 server's response time by dividing the time spent in queue by the number of
16177 requests in the queue. It is worth noting that if a session experiences a
16178 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010016179 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016180 backend queue unless a redispatch occurs.
16181
16182 - "backend_queue" is the total number of requests which were processed before
16183 this one in the backend's global queue. It is zero when the request has not
16184 gone through the global queue. It makes it possible to estimate the average
16185 queue length, which easily translates into a number of missing servers when
16186 divided by a server's "maxconn" parameter. It is worth noting that if a
16187 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010016188 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016189 through both the server queue and the backend queue unless a redispatch
16190 occurs.
16191
16192
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161938.2.3. HTTP log format
16194----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016195
16196The HTTP format is the most complete and the best suited for HTTP proxies. It
16197is enabled by when "option httplog" is specified in the frontend. It provides
16198the same level of information as the TCP format with additional features which
16199are specific to the HTTP protocol. Just like the TCP format, the log is usually
16200emitted at the end of the session, unless "option logasap" is specified, which
16201generally only makes sense for download sites. A session which matches the
16202"monitor" rules will never logged. It is also possible not to log sessions for
16203which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016204frontend. Successful connections will not be logged if "option dontlog-normal"
16205is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016206
16207Most fields are shared with the TCP log, some being different. A few fields may
16208slightly vary depending on some configuration options. Those ones are marked
16209with a star ('*') after the field name below.
16210
16211 Example :
16212 frontend http-in
16213 mode http
16214 option httplog
16215 log global
16216 default_backend bck
16217
16218 backend static
16219 server srv1 127.0.0.1:8000
16220
16221 >>> Feb 6 12:14:14 localhost \
16222 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
16223 static/srv1 10/0/30/69/109 200 2750 - - ---- 1/1/1/1/0 0/0 {1wt.eu} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010016224 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016225
16226 Field Format Extract from the example above
16227 1 process_name '[' pid ']:' haproxy[14389]:
16228 2 client_ip ':' client_port 10.0.1.2:33317
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016229 3 '[' request_date ']' [06/Feb/2009:12:14:14.655]
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016230 4 frontend_name http-in
16231 5 backend_name '/' server_name static/srv1
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016232 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016233 7 status_code 200
16234 8 bytes_read* 2750
16235 9 captured_request_cookie -
16236 10 captured_response_cookie -
16237 11 termination_state ----
16238 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
16239 13 srv_queue '/' backend_queue 0/0
16240 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
16241 15 '{' captured_response_headers* '}' {}
16242 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010016243
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016244Detailed fields description :
16245 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016246 connection to haproxy. If the connection was accepted on a UNIX socket
16247 instead, the IP address would be replaced with the word "unix". Note that
16248 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016249 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010016250 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016251 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016252
16253 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016254 If the connection was accepted on a UNIX socket instead, the port would be
16255 replaced with the ID of the accepting socket, which is also reported in the
16256 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016257
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016258 - "request_date" is the exact date when the first byte of the HTTP request
16259 was received by haproxy (log field %tr).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016260
16261 - "frontend_name" is the name of the frontend (or listener) which received
16262 and processed the connection.
16263
16264 - "backend_name" is the name of the backend (or listener) which was selected
16265 to manage the connection to the server. This will be the same as the
16266 frontend if no switching rule has been applied.
16267
16268 - "server_name" is the name of the last server to which the connection was
16269 sent, which might differ from the first one if there were connection errors
16270 and a redispatch occurred. Note that this server belongs to the backend
16271 which processed the request. If the request was aborted before reaching a
16272 server, "<NOSRV>" is indicated instead of a server name. If the request was
16273 intercepted by the stats subsystem, "<STATS>" is indicated instead.
16274
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016275 - "TR" is the total time in milliseconds spent waiting for a full HTTP
16276 request from the client (not counting body) after the first byte was
16277 received. It can be "-1" if the connection was aborted before a complete
16278 request could be received or the a bad request was received. It should
16279 always be very small because a request generally fits in one single packet.
16280 Large times here generally indicate network issues between the client and
Willy Tarreau590a0512018-09-05 11:56:48 +020016281 haproxy or requests being typed by hand. See section 8.4 "Timing Events"
16282 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016283
16284 - "Tw" is the total time in milliseconds spent waiting in the various queues.
16285 It can be "-1" if the connection was aborted before reaching the queue.
Willy Tarreau590a0512018-09-05 11:56:48 +020016286 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016287
16288 - "Tc" is the total time in milliseconds spent waiting for the connection to
16289 establish to the final server, including retries. It can be "-1" if the
Willy Tarreau590a0512018-09-05 11:56:48 +020016290 request was aborted before a connection could be established. See section
16291 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016292
16293 - "Tr" is the total time in milliseconds spent waiting for the server to send
16294 a full HTTP response, not counting data. It can be "-1" if the request was
16295 aborted before a complete response could be received. It generally matches
16296 the server's processing time for the request, though it may be altered by
16297 the amount of data sent by the client to the server. Large times here on
Willy Tarreau590a0512018-09-05 11:56:48 +020016298 "GET" requests generally indicate an overloaded server. See section 8.4
16299 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016300
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016301 - "Ta" is the time the request remained active in haproxy, which is the total
16302 time in milliseconds elapsed between the first byte of the request was
16303 received and the last byte of response was sent. It covers all possible
16304 processing except the handshake (see Th) and idle time (see Ti). There is
16305 one exception, if "option logasap" was specified, then the time counting
16306 stops at the moment the log is emitted. In this case, a '+' sign is
16307 prepended before the value, indicating that the final one will be larger.
Willy Tarreau590a0512018-09-05 11:56:48 +020016308 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016309
16310 - "status_code" is the HTTP status code returned to the client. This status
16311 is generally set by the server, but it might also be set by haproxy when
16312 the server cannot be reached or when its response is blocked by haproxy.
16313
16314 - "bytes_read" is the total number of bytes transmitted to the client when
16315 the log is emitted. This does include HTTP headers. If "option logasap" is
16316 specified, the this value will be prefixed with a '+' sign indicating that
16317 the final one may be larger. Please note that this value is a 64-bit
16318 counter, so log analysis tools must be able to handle it without
16319 overflowing.
16320
16321 - "captured_request_cookie" is an optional "name=value" entry indicating that
16322 the client had this cookie in the request. The cookie name and its maximum
16323 length are defined by the "capture cookie" statement in the frontend
16324 configuration. The field is a single dash ('-') when the option is not
16325 set. Only one cookie may be captured, it is generally used to track session
16326 ID exchanges between a client and a server to detect session crossing
16327 between clients due to application bugs. For more details, please consult
16328 the section "Capturing HTTP headers and cookies" below.
16329
16330 - "captured_response_cookie" is an optional "name=value" entry indicating
16331 that the server has returned a cookie with its response. The cookie name
16332 and its maximum length are defined by the "capture cookie" statement in the
16333 frontend configuration. The field is a single dash ('-') when the option is
16334 not set. Only one cookie may be captured, it is generally used to track
16335 session ID exchanges between a client and a server to detect session
16336 crossing between clients due to application bugs. For more details, please
16337 consult the section "Capturing HTTP headers and cookies" below.
16338
16339 - "termination_state" is the condition the session was in when the session
16340 ended. This indicates the session state, which side caused the end of
16341 session to happen, for what reason (timeout, error, ...), just like in TCP
16342 logs, and information about persistence operations on cookies in the last
16343 two characters. The normal flags should begin with "--", indicating the
16344 session was closed by either end with no data remaining in buffers. See
16345 below "Session state at disconnection" for more details.
16346
16347 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016348 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016349 limits have been reached. For instance, if actconn is close to 512 or 1024
16350 when multiple connection errors occur, chances are high that the system
16351 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016352 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016353 system.
16354
16355 - "feconn" is the total number of concurrent connections on the frontend when
16356 the session was logged. It is useful to estimate the amount of resource
16357 required to sustain high loads, and to detect when the frontend's "maxconn"
16358 has been reached. Most often when this value increases by huge jumps, it is
16359 because there is congestion on the backend servers, but sometimes it can be
16360 caused by a denial of service attack.
16361
16362 - "beconn" is the total number of concurrent connections handled by the
16363 backend when the session was logged. It includes the total number of
16364 concurrent connections active on servers as well as the number of
16365 connections pending in queues. It is useful to estimate the amount of
16366 additional servers needed to support high loads for a given application.
16367 Most often when this value increases by huge jumps, it is because there is
16368 congestion on the backend servers, but sometimes it can be caused by a
16369 denial of service attack.
16370
16371 - "srv_conn" is the total number of concurrent connections still active on
16372 the server when the session was logged. It can never exceed the server's
16373 configured "maxconn" parameter. If this value is very often close or equal
16374 to the server's "maxconn", it means that traffic regulation is involved a
16375 lot, meaning that either the server's maxconn value is too low, or that
16376 there aren't enough servers to process the load with an optimal response
16377 time. When only one of the server's "srv_conn" is high, it usually means
16378 that this server has some trouble causing the requests to take longer to be
16379 processed than on other servers.
16380
16381 - "retries" is the number of connection retries experienced by this session
16382 when trying to connect to the server. It must normally be zero, unless a
16383 server is being stopped at the same moment the connection was attempted.
16384 Frequent retries generally indicate either a network problem between
16385 haproxy and the server, or a misconfigured system backlog on the server
16386 preventing new connections from being queued. This field may optionally be
16387 prefixed with a '+' sign, indicating that the session has experienced a
16388 redispatch after the maximal retry count has been reached on the initial
16389 server. In this case, the server name appearing in the log is the one the
16390 connection was redispatched to, and not the first one, though both may
16391 sometimes be the same in case of hashing for instance. So as a general rule
16392 of thumb, when a '+' is present in front of the retry count, this count
16393 should not be attributed to the logged server.
16394
16395 - "srv_queue" is the total number of requests which were processed before
16396 this one in the server queue. It is zero when the request has not gone
16397 through the server queue. It makes it possible to estimate the approximate
16398 server's response time by dividing the time spent in queue by the number of
16399 requests in the queue. It is worth noting that if a session experiences a
16400 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010016401 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016402 backend queue unless a redispatch occurs.
16403
16404 - "backend_queue" is the total number of requests which were processed before
16405 this one in the backend's global queue. It is zero when the request has not
16406 gone through the global queue. It makes it possible to estimate the average
16407 queue length, which easily translates into a number of missing servers when
16408 divided by a server's "maxconn" parameter. It is worth noting that if a
16409 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010016410 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016411 through both the server queue and the backend queue unless a redispatch
16412 occurs.
16413
16414 - "captured_request_headers" is a list of headers captured in the request due
16415 to the presence of the "capture request header" statement in the frontend.
16416 Multiple headers can be captured, they will be delimited by a vertical bar
16417 ('|'). When no capture is enabled, the braces do not appear, causing a
16418 shift of remaining fields. It is important to note that this field may
16419 contain spaces, and that using it requires a smarter log parser than when
16420 it's not used. Please consult the section "Capturing HTTP headers and
16421 cookies" below for more details.
16422
16423 - "captured_response_headers" is a list of headers captured in the response
16424 due to the presence of the "capture response header" statement in the
16425 frontend. Multiple headers can be captured, they will be delimited by a
16426 vertical bar ('|'). When no capture is enabled, the braces do not appear,
16427 causing a shift of remaining fields. It is important to note that this
16428 field may contain spaces, and that using it requires a smarter log parser
16429 than when it's not used. Please consult the section "Capturing HTTP headers
16430 and cookies" below for more details.
16431
16432 - "http_request" is the complete HTTP request line, including the method,
16433 request and HTTP version string. Non-printable characters are encoded (see
16434 below the section "Non-printable characters"). This is always the last
16435 field, and it is always delimited by quotes and is the only one which can
16436 contain quotes. If new fields are added to the log format, they will be
16437 added before this field. This field might be truncated if the request is
16438 huge and does not fit in the standard syslog buffer (1024 characters). This
16439 is the reason why this field must always remain the last one.
16440
16441
Cyril Bontédc4d9032012-04-08 21:57:39 +0200164428.2.4. Custom log format
16443------------------------
William Lallemand48940402012-01-30 16:47:22 +010016444
Willy Tarreau2beef582012-12-20 17:22:52 +010016445The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010016446mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010016447
Davor Ocelice9ed2812017-12-25 17:49:28 +010016448HAProxy understands some log format variables. % precedes log format variables.
William Lallemand48940402012-01-30 16:47:22 +010016449Variables can take arguments using braces ('{}'), and multiple arguments are
16450separated by commas within the braces. Flags may be added or removed by
16451prefixing them with a '+' or '-' sign.
16452
16453Special variable "%o" may be used to propagate its flags to all other
16454variables on the same format string. This is particularly handy with quoted
Dragan Dosen835b9212016-02-12 13:23:03 +010016455("Q") and escaped ("E") string formats.
William Lallemand48940402012-01-30 16:47:22 +010016456
Willy Tarreauc8368452012-12-21 00:09:23 +010016457If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020016458as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010016459less common information such as the client's SSL certificate's DN, or to log
16460the key that would be used to store an entry into a stick table.
16461
William Lallemand48940402012-01-30 16:47:22 +010016462Note: spaces must be escaped. A space character is considered as a separator.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016463In order to emit a verbatim '%', it must be preceded by another '%' resulting
Willy Tarreau06d97f92013-12-02 17:45:48 +010016464in '%%'. HAProxy will automatically merge consecutive separators.
William Lallemand48940402012-01-30 16:47:22 +010016465
Dragan Dosen835b9212016-02-12 13:23:03 +010016466Note: when using the RFC5424 syslog message format, the characters '"',
16467'\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see
16468https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In
16469such cases, the use of the flag "E" should be considered.
16470
William Lallemand48940402012-01-30 16:47:22 +010016471Flags are :
16472 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016473 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
Dragan Dosen835b9212016-02-12 13:23:03 +010016474 * E: escape characters '"', '\' and ']' in a string with '\' as prefix
16475 (intended purpose is for the RFC5424 structured-data log formats)
William Lallemand48940402012-01-30 16:47:22 +010016476
16477 Example:
16478
16479 log-format %T\ %t\ Some\ Text
16480 log-format %{+Q}o\ %t\ %s\ %{-Q}r
16481
Dragan Dosen835b9212016-02-12 13:23:03 +010016482 log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]
16483
William Lallemand48940402012-01-30 16:47:22 +010016484At the moment, the default HTTP format is defined this way :
16485
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016486 log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \
16487 %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"
William Lallemand48940402012-01-30 16:47:22 +010016488
William Lallemandbddd4fd2012-02-27 11:23:10 +010016489the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010016490
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016491 log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \
16492 %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \
16493 %bc %sc %rc %sq %bq %CC %CS %hrl %hsl"
William Lallemand48940402012-01-30 16:47:22 +010016494
William Lallemandbddd4fd2012-02-27 11:23:10 +010016495and the default TCP format is defined this way :
16496
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016497 log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \
16498 %ac/%fc/%bc/%sc/%rc %sq/%bq"
William Lallemandbddd4fd2012-02-27 11:23:10 +010016499
William Lallemand48940402012-01-30 16:47:22 +010016500Please refer to the table below for currently defined variables :
16501
William Lallemandbddd4fd2012-02-27 11:23:10 +010016502 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016503 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016504 +---+------+-----------------------------------------------+-------------+
16505 | | %o | special variable, apply flags on all next var | |
16506 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010016507 | | %B | bytes_read (from server to client) | numeric |
16508 | H | %CC | captured_request_cookie | string |
16509 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020016510 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000016511 | H | %HM | HTTP method (ex: POST) | string |
16512 | H | %HP | HTTP request URI without query string (path) | string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000016513 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000016514 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
16515 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010016516 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020016517 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020016518 | | %T | gmt_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016519 | | %Ta | Active time of the request (from TR to end) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016520 | | %Tc | Tc | numeric |
Willy Tarreau27b639d2016-05-17 17:55:27 +020016521 | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080016522 | | %Tl | local_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016523 | | %Th | connection handshake time (SSL, PROXY proto) | numeric |
16524 | H | %Ti | idle time before the HTTP request | numeric |
16525 | H | %Tq | Th + Ti + TR | numeric |
16526 | H | %TR | time to receive the full request from 1st byte| numeric |
16527 | H | %Tr | Tr (response time) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020016528 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016529 | | %Tt | Tt | numeric |
16530 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010016531 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016532 | | %ac | actconn | numeric |
16533 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016534 | | %bc | beconn (backend concurrent connections) | numeric |
16535 | | %bi | backend_source_ip (connecting address) | IP |
16536 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016537 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010016538 | | %ci | client_ip (accepted address) | IP |
16539 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016540 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016541 | | %fc | feconn (frontend concurrent connections) | numeric |
16542 | | %fi | frontend_ip (accepting address) | IP |
16543 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020016544 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020016545 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020016546 | | %hr | captured_request_headers default style | string |
16547 | | %hrl | captured_request_headers CLF style | string list |
16548 | | %hs | captured_response_headers default style | string |
16549 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020016550 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020016551 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016552 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016553 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010016554 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016555 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016556 | | %sc | srv_conn (server concurrent connections) | numeric |
16557 | | %si | server_IP (target address) | IP |
16558 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016559 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016560 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
16561 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016562 | | %t | date_time (with millisecond resolution) | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016563 | H | %tr | date_time of HTTP request | date |
16564 | H | %trg | gmt_date_time of start of HTTP request | date |
Jens Bissinger15c64ff2018-08-23 14:11:27 +020016565 | H | %trl | local_date_time of start of HTTP request | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016566 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016567 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016568 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010016569
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016570 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010016571
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010016572
165738.2.5. Error log format
16574-----------------------
16575
16576When an incoming connection fails due to an SSL handshake or an invalid PROXY
16577protocol header, haproxy will log the event using a shorter, fixed line format.
16578By default, logs are emitted at the LOG_INFO level, unless the option
16579"log-separate-errors" is set in the backend, in which case the LOG_ERR level
Davor Ocelice9ed2812017-12-25 17:49:28 +010016580will be used. Connections on which no data are exchanged (e.g. probes) are not
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010016581logged if the "dontlognull" option is set.
16582
16583The format looks like this :
16584
16585 >>> Dec 3 18:27:14 localhost \
16586 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
16587 Connection error during SSL handshake
16588
16589 Field Format Extract from the example above
16590 1 process_name '[' pid ']:' haproxy[6103]:
16591 2 client_ip ':' client_port 127.0.0.1:56059
16592 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
16593 4 frontend_name "/" bind_name ":" frt/f1:
16594 5 message Connection error during SSL handshake
16595
16596These fields just provide minimal information to help debugging connection
16597failures.
16598
16599
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166008.3. Advanced logging options
16601-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016602
16603Some advanced logging options are often looked for but are not easy to find out
16604just by looking at the various options. Here is an entry point for the few
16605options which can enable better logging. Please refer to the keywords reference
16606for more information about their usage.
16607
16608
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166098.3.1. Disabling logging of external tests
16610------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016611
16612It is quite common to have some monitoring tools perform health checks on
16613haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
16614commercial load-balancer, and sometimes it will simply be a more complete
16615monitoring system such as Nagios. When the tests are very frequent, users often
16616ask how to disable logging for those checks. There are three possibilities :
16617
16618 - if connections come from everywhere and are just TCP probes, it is often
16619 desired to simply disable logging of connections without data exchange, by
16620 setting "option dontlognull" in the frontend. It also disables logging of
16621 port scans, which may or may not be desired.
16622
16623 - if the connection come from a known source network, use "monitor-net" to
16624 declare this network as monitoring only. Any host in this network will then
16625 only be able to perform health checks, and their requests will not be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016626 logged. This is generally appropriate to designate a list of equipment
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016627 such as other load-balancers.
16628
16629 - if the tests are performed on a known URI, use "monitor-uri" to declare
16630 this URI as dedicated to monitoring. Any host sending this request will
16631 only get the result of a health-check, and the request will not be logged.
16632
16633
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166348.3.2. Logging before waiting for the session to terminate
16635----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016636
16637The problem with logging at end of connection is that you have no clue about
16638what is happening during very long sessions, such as remote terminal sessions
16639or large file downloads. This problem can be worked around by specifying
Davor Ocelice9ed2812017-12-25 17:49:28 +010016640"option logasap" in the frontend. HAProxy will then log as soon as possible,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016641just before data transfer begins. This means that in case of TCP, it will still
16642log the connection status to the server, and in case of HTTP, it will log just
16643after processing the server headers. In this case, the number of bytes reported
16644is the number of header bytes sent to the client. In order to avoid confusion
16645with normal logs, the total time field and the number of bytes are prefixed
16646with a '+' sign which means that real numbers are certainly larger.
16647
16648
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166498.3.3. Raising log level upon errors
16650------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016651
16652Sometimes it is more convenient to separate normal traffic from errors logs,
16653for instance in order to ease error monitoring from log files. When the option
16654"log-separate-errors" is used, connections which experience errors, timeouts,
16655retries, redispatches or HTTP status codes 5xx will see their syslog level
16656raised from "info" to "err". This will help a syslog daemon store the log in
16657a separate file. It is very important to keep the errors in the normal traffic
16658file too, so that log ordering is not altered. You should also be careful if
16659you already have configured your syslog daemon to store all logs higher than
16660"notice" in an "admin" file, because the "err" level is higher than "notice".
16661
16662
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166638.3.4. Disabling logging of successful connections
16664--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016665
16666Although this may sound strange at first, some large sites have to deal with
16667multiple thousands of logs per second and are experiencing difficulties keeping
16668them intact for a long time or detecting errors within them. If the option
16669"dontlog-normal" is set on the frontend, all normal connections will not be
16670logged. In this regard, a normal connection is defined as one without any
16671error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
16672and a response with a status 5xx is not considered normal and will be logged
16673too. Of course, doing is is really discouraged as it will remove most of the
16674useful information from the logs. Do this only if you have no other
16675alternative.
16676
16677
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166788.4. Timing events
16679------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016680
16681Timers provide a great help in troubleshooting network problems. All values are
16682reported in milliseconds (ms). These timers should be used in conjunction with
16683the session termination flags. In TCP mode with "option tcplog" set on the
16684frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016685mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In
16686addition, three other measures are provided, "Th", "Ti", and "Tq".
16687
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010016688Timings events in HTTP mode:
16689
16690 first request 2nd request
16691 |<-------------------------------->|<-------------- ...
16692 t tr t tr ...
16693 ---|----|----|----|----|----|----|----|----|--
16694 : Th Ti TR Tw Tc Tr Td : Ti ...
16695 :<---- Tq ---->: :
16696 :<-------------- Tt -------------->:
16697 :<--------- Ta --------->:
16698
16699Timings events in TCP mode:
16700
16701 TCP session
16702 |<----------------->|
16703 t t
16704 ---|----|----|----|----|---
16705 | Th Tw Tc Td |
16706 |<------ Tt ------->|
16707
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016708 - Th: total time to accept tcp connection and execute handshakes for low level
Davor Ocelice9ed2812017-12-25 17:49:28 +010016709 protocols. Currently, these protocols are proxy-protocol and SSL. This may
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016710 only happen once during the whole connection's lifetime. A large time here
16711 may indicate that the client only pre-established the connection without
16712 speaking, that it is experiencing network issues preventing it from
Davor Ocelice9ed2812017-12-25 17:49:28 +010016713 completing a handshake in a reasonable time (e.g. MTU issues), or that an
Willy Tarreau590a0512018-09-05 11:56:48 +020016714 SSL handshake was very expensive to compute. Please note that this time is
16715 reported only before the first request, so it is safe to average it over
16716 all request to calculate the amortized value. The second and subsequent
16717 request will always report zero here.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016718
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016719 - Ti: is the idle time before the HTTP request (HTTP mode only). This timer
16720 counts between the end of the handshakes and the first byte of the HTTP
16721 request. When dealing with a second request in keep-alive mode, it starts
Willy Tarreau590a0512018-09-05 11:56:48 +020016722 to count after the end of the transmission the previous response. When a
16723 multiplexed protocol such as HTTP/2 is used, it starts to count immediately
16724 after the previous request. Some browsers pre-establish connections to a
16725 server in order to reduce the latency of a future request, and keep them
16726 pending until they need it. This delay will be reported as the idle time. A
16727 value of -1 indicates that nothing was received on the connection.
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016728
16729 - TR: total time to get the client request (HTTP mode only). It's the time
16730 elapsed between the first bytes received and the moment the proxy received
16731 the empty line marking the end of the HTTP headers. The value "-1"
16732 indicates that the end of headers has never been seen. This happens when
16733 the client closes prematurely or times out. This time is usually very short
16734 since most requests fit in a single packet. A large time may indicate a
16735 request typed by hand during a test.
16736
16737 - Tq: total time to get the client request from the accept date or since the
16738 emission of the last byte of the previous response (HTTP mode only). It's
Davor Ocelice9ed2812017-12-25 17:49:28 +010016739 exactly equal to Th + Ti + TR unless any of them is -1, in which case it
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016740 returns -1 as well. This timer used to be very useful before the arrival of
16741 HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop
16742 it in favor of TR nowadays, as the idle time adds a lot of noise to the
16743 reports.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016744
16745 - Tw: total time spent in the queues waiting for a connection slot. It
16746 accounts for backend queue as well as the server queues, and depends on the
16747 queue size, and the time needed for the server to complete previous
16748 requests. The value "-1" means that the request was killed before reaching
16749 the queue, which is generally what happens with invalid or denied requests.
16750
16751 - Tc: total time to establish the TCP connection to the server. It's the time
16752 elapsed between the moment the proxy sent the connection request, and the
16753 moment it was acknowledged by the server, or between the TCP SYN packet and
16754 the matching SYN/ACK packet in return. The value "-1" means that the
16755 connection never established.
16756
16757 - Tr: server response time (HTTP mode only). It's the time elapsed between
16758 the moment the TCP connection was established to the server and the moment
16759 the server sent its complete response headers. It purely shows its request
16760 processing time, without the network overhead due to the data transmission.
16761 It is worth noting that when the client has data to send to the server, for
16762 instance during a POST request, the time already runs, and this can distort
16763 apparent response time. For this reason, it's generally wise not to trust
16764 too much this field for POST requests initiated from clients behind an
16765 untrusted network. A value of "-1" here means that the last the response
16766 header (empty line) was never seen, most likely because the server timeout
16767 stroke before the server managed to process the request.
16768
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016769 - Ta: total active time for the HTTP request, between the moment the proxy
16770 received the first byte of the request header and the emission of the last
16771 byte of the response body. The exception is when the "logasap" option is
16772 specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with
16773 a '+' sign. From this field, we can deduce "Td", the data transmission time,
16774 by subtracting other timers when valid :
16775
16776 Td = Ta - (TR + Tw + Tc + Tr)
16777
16778 Timers with "-1" values have to be excluded from this equation. Note that
16779 "Ta" can never be negative.
16780
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016781 - Tt: total session duration time, between the moment the proxy accepted it
16782 and the moment both ends were closed. The exception is when the "logasap"
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016783 option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and
16784 is prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016785 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016786
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016787 Td = Tt - (Th + Ti + TR + Tw + Tc + Tr)
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016788
16789 Timers with "-1" values have to be excluded from this equation. In TCP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016790 mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never
16791 be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016792
16793These timers provide precious indications on trouble causes. Since the TCP
16794protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
16795that timers close to multiples of 3s are nearly always related to lost packets
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016796due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or
16797"Tt" is close to a timeout value specified in the configuration, it often means
16798that a session has been aborted on timeout.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016799
16800Most common cases :
16801
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016802 - If "Th" or "Ti" are close to 3000, a packet has probably been lost between
16803 the client and the proxy. This is very rare on local networks but might
16804 happen when clients are on far remote networks and send large requests. It
16805 may happen that values larger than usual appear here without any network
16806 cause. Sometimes, during an attack or just after a resource starvation has
16807 ended, haproxy may accept thousands of connections in a few milliseconds.
16808 The time spent accepting these connections will inevitably slightly delay
16809 processing of other connections, and it can happen that request times in the
16810 order of a few tens of milliseconds are measured after a few thousands of
16811 new connections have been accepted at once. Using one of the keep-alive
16812 modes may display larger idle times since "Ti" measures the time spent
Patrick Mezard105faca2010-06-12 17:02:46 +020016813 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016814
16815 - If "Tc" is close to 3000, a packet has probably been lost between the
16816 server and the proxy during the server connection phase. This value should
16817 always be very low, such as 1 ms on local networks and less than a few tens
16818 of ms on remote networks.
16819
Willy Tarreau55165fe2009-05-10 12:02:55 +020016820 - If "Tr" is nearly always lower than 3000 except some rare values which seem
16821 to be the average majored by 3000, there are probably some packets lost
16822 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016823
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016824 - If "Ta" is large even for small byte counts, it generally is because
16825 neither the client nor the server decides to close the connection while
16826 haproxy is running in tunnel mode and both have agreed on a keep-alive
16827 connection mode. In order to solve this issue, it will be needed to specify
16828 one of the HTTP options to manipulate keep-alive or close options on either
16829 the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is
16830 important when connection regulation is used with the "maxconn" option on
16831 the servers, since no new connection will be sent to the server until
16832 another one is released.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016833
16834Other noticeable HTTP log cases ('xx' means any value to be ignored) :
16835
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016836 TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016837 was emitted before the data phase. All the timers are valid
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016838 except "Ta" which is shorter than reality.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016839
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016840 -1/xx/xx/xx/Ta The client was not able to send a complete request in time
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016841 or it aborted too early. Check the session termination flags
16842 then "timeout http-request" and "timeout client" settings.
16843
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016844 TR/-1/xx/xx/Ta It was not possible to process the request, maybe because
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016845 servers were out of order, because the request was invalid
16846 or forbidden by ACL rules. Check the session termination
16847 flags.
16848
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016849 TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it
16850 actively refused it or it timed out after Ta-(TR+Tw) ms.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016851 Check the session termination flags, then check the
16852 "timeout connect" setting. Note that the tarpit action might
16853 return similar-looking patterns, with "Tw" equal to the time
16854 the client connection was maintained open.
16855
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016856 TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016857 a complete response in time, or it closed its connection
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016858 unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016859 termination flags, then check the "timeout server" setting.
16860
16861
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200168628.5. Session state at disconnection
16863-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016864
16865TCP and HTTP logs provide a session termination indicator in the
16866"termination_state" field, just before the number of active connections. It is
168672-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
16868each of which has a special meaning :
16869
16870 - On the first character, a code reporting the first event which caused the
16871 session to terminate :
16872
16873 C : the TCP session was unexpectedly aborted by the client.
16874
16875 S : the TCP session was unexpectedly aborted by the server, or the
16876 server explicitly refused it.
16877
16878 P : the session was prematurely aborted by the proxy, because of a
16879 connection limit enforcement, because a DENY filter was matched,
16880 because of a security check which detected and blocked a dangerous
16881 error in server response which might have caused information leak
Davor Ocelice9ed2812017-12-25 17:49:28 +010016882 (e.g. cacheable cookie).
Willy Tarreau570f2212013-06-10 16:42:09 +020016883
16884 L : the session was locally processed by haproxy and was not passed to
16885 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016886
16887 R : a resource on the proxy has been exhausted (memory, sockets, source
16888 ports, ...). Usually, this appears during the connection phase, and
16889 system logs should contain a copy of the precise error. If this
16890 happens, it must be considered as a very serious anomaly which
16891 should be fixed as soon as possible by any means.
16892
16893 I : an internal error was identified by the proxy during a self-check.
16894 This should NEVER happen, and you are encouraged to report any log
16895 containing this, because this would almost certainly be a bug. It
16896 would be wise to preventively restart the process after such an
16897 event too, in case it would be caused by memory corruption.
16898
Simon Horman752dc4a2011-06-21 14:34:59 +090016899 D : the session was killed by haproxy because the server was detected
16900 as down and was configured to kill all connections when going down.
16901
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070016902 U : the session was killed by haproxy on this backup server because an
16903 active server was detected as up and was configured to kill all
16904 backup connections when going up.
16905
Willy Tarreaua2a64e92011-09-07 23:01:56 +020016906 K : the session was actively killed by an admin operating on haproxy.
16907
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016908 c : the client-side timeout expired while waiting for the client to
16909 send or receive data.
16910
16911 s : the server-side timeout expired while waiting for the server to
16912 send or receive data.
16913
16914 - : normal session completion, both the client and the server closed
16915 with nothing left in the buffers.
16916
16917 - on the second character, the TCP or HTTP session state when it was closed :
16918
Willy Tarreauf7b30a92010-12-06 22:59:17 +010016919 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016920 (HTTP mode only). Nothing was sent to any server.
16921
16922 Q : the proxy was waiting in the QUEUE for a connection slot. This can
16923 only happen when servers have a 'maxconn' parameter set. It can
16924 also happen in the global queue after a redispatch consecutive to
16925 a failed attempt to connect to a dying server. If no redispatch is
16926 reported, then no connection attempt was made to any server.
16927
16928 C : the proxy was waiting for the CONNECTION to establish on the
16929 server. The server might at most have noticed a connection attempt.
16930
16931 H : the proxy was waiting for complete, valid response HEADERS from the
16932 server (HTTP only).
16933
16934 D : the session was in the DATA phase.
16935
16936 L : the proxy was still transmitting LAST data to the client while the
16937 server had already finished. This one is very rare as it can only
16938 happen when the client dies while receiving the last packets.
16939
16940 T : the request was tarpitted. It has been held open with the client
16941 during the whole "timeout tarpit" duration or until the client
16942 closed, both of which will be reported in the "Tw" timer.
16943
16944 - : normal session completion after end of data transfer.
16945
16946 - the third character tells whether the persistence cookie was provided by
16947 the client (only in HTTP mode) :
16948
16949 N : the client provided NO cookie. This is usually the case for new
16950 visitors, so counting the number of occurrences of this flag in the
16951 logs generally indicate a valid trend for the site frequentation.
16952
16953 I : the client provided an INVALID cookie matching no known server.
16954 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020016955 cookies between HTTP/HTTPS sites, persistence conditionally
16956 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016957
16958 D : the client provided a cookie designating a server which was DOWN,
16959 so either "option persist" was used and the client was sent to
16960 this server, or it was not set and the client was redispatched to
16961 another server.
16962
Willy Tarreau996a92c2010-10-13 19:30:47 +020016963 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016964 server.
16965
Willy Tarreau996a92c2010-10-13 19:30:47 +020016966 E : the client provided a valid cookie, but with a last date which was
16967 older than what is allowed by the "maxidle" cookie parameter, so
16968 the cookie is consider EXPIRED and is ignored. The request will be
16969 redispatched just as if there was no cookie.
16970
16971 O : the client provided a valid cookie, but with a first date which was
16972 older than what is allowed by the "maxlife" cookie parameter, so
16973 the cookie is consider too OLD and is ignored. The request will be
16974 redispatched just as if there was no cookie.
16975
Willy Tarreauc89ccb62012-04-05 21:18:22 +020016976 U : a cookie was present but was not used to select the server because
16977 some other server selection mechanism was used instead (typically a
16978 "use-server" rule).
16979
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016980 - : does not apply (no cookie set in configuration).
16981
16982 - the last character reports what operations were performed on the persistence
16983 cookie returned by the server (only in HTTP mode) :
16984
16985 N : NO cookie was provided by the server, and none was inserted either.
16986
16987 I : no cookie was provided by the server, and the proxy INSERTED one.
16988 Note that in "cookie insert" mode, if the server provides a cookie,
16989 it will still be overwritten and reported as "I" here.
16990
Willy Tarreau996a92c2010-10-13 19:30:47 +020016991 U : the proxy UPDATED the last date in the cookie that was presented by
16992 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016993 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020016994 date indicated in the cookie. If any other change happens, such as
16995 a redispatch, then the cookie will be marked as inserted instead.
16996
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016997 P : a cookie was PROVIDED by the server and transmitted as-is.
16998
16999 R : the cookie provided by the server was REWRITTEN by the proxy, which
17000 happens in "cookie rewrite" or "cookie prefix" modes.
17001
17002 D : the cookie provided by the server was DELETED by the proxy.
17003
17004 - : does not apply (no cookie set in configuration).
17005
Willy Tarreau996a92c2010-10-13 19:30:47 +020017006The combination of the two first flags gives a lot of information about what
17007was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017008helpful to detect server saturation, network troubles, local system resource
17009starvation, attacks, etc...
17010
17011The most common termination flags combinations are indicated below. They are
17012alphabetically sorted, with the lowercase set just after the upper case for
17013easier finding and understanding.
17014
17015 Flags Reason
17016
17017 -- Normal termination.
17018
17019 CC The client aborted before the connection could be established to the
17020 server. This can happen when haproxy tries to connect to a recently
17021 dead (or unchecked) server, and the client aborts while haproxy is
17022 waiting for the server to respond or for "timeout connect" to expire.
17023
17024 CD The client unexpectedly aborted during data transfer. This can be
17025 caused by a browser crash, by an intermediate equipment between the
17026 client and haproxy which decided to actively break the connection,
17027 by network routing issues between the client and haproxy, or by a
17028 keep-alive session between the server and the client terminated first
17029 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010017030
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017031 cD The client did not send nor acknowledge any data for as long as the
17032 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020017033 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017034
17035 CH The client aborted while waiting for the server to start responding.
17036 It might be the server taking too long to respond or the client
17037 clicking the 'Stop' button too fast.
17038
17039 cH The "timeout client" stroke while waiting for client data during a
17040 POST request. This is sometimes caused by too large TCP MSS values
17041 for PPPoE networks which cannot transport full-sized packets. It can
17042 also happen when client timeout is smaller than server timeout and
17043 the server takes too long to respond.
17044
17045 CQ The client aborted while its session was queued, waiting for a server
17046 with enough empty slots to accept it. It might be that either all the
17047 servers were saturated or that the assigned server was taking too
17048 long a time to respond.
17049
17050 CR The client aborted before sending a full HTTP request. Most likely
17051 the request was typed by hand using a telnet client, and aborted
17052 too early. The HTTP status code is likely a 400 here. Sometimes this
17053 might also be caused by an IDS killing the connection between haproxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020017054 and the client. "option http-ignore-probes" can be used to ignore
17055 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017056
17057 cR The "timeout http-request" stroke before the client sent a full HTTP
17058 request. This is sometimes caused by too large TCP MSS values on the
17059 client side for PPPoE networks which cannot transport full-sized
17060 packets, or by clients sending requests by hand and not typing fast
17061 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020017062 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020017063 some browsers started to implement a "pre-connect" feature consisting
17064 in speculatively connecting to some recently visited web sites just
17065 in case the user would like to visit them. This results in many
17066 connections being established to web sites, which end up in 408
17067 Request Timeout if the timeout strikes first, or 400 Bad Request when
17068 the browser decides to close them first. These ones pollute the log
17069 and feed the error counters. Some versions of some browsers have even
17070 been reported to display the error code. It is possible to work
Davor Ocelice9ed2812017-12-25 17:49:28 +010017071 around the undesirable effects of this behavior by adding "option
Willy Tarreau0f228a02015-05-01 15:37:53 +020017072 http-ignore-probes" in the frontend, resulting in connections with
17073 zero data transfer to be totally ignored. This will definitely hide
17074 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017075
17076 CT The client aborted while its session was tarpitted. It is important to
17077 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020017078 wrong tarpit rules have been written. If a lot of them happen, it
17079 might make sense to lower the "timeout tarpit" value to something
17080 closer to the average reported "Tw" timer, in order not to consume
17081 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017082
Willy Tarreau570f2212013-06-10 16:42:09 +020017083 LR The request was intercepted and locally handled by haproxy. Generally
17084 it means that this was a redirect or a stats request.
17085
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017086 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017087 the TCP connection (the proxy received a TCP RST or an ICMP message
17088 in return). Under some circumstances, it can also be the network
Davor Ocelice9ed2812017-12-25 17:49:28 +010017089 stack telling the proxy that the server is unreachable (e.g. no route,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017090 or no ARP response on local network). When this happens in HTTP mode,
17091 the status code is likely a 502 or 503 here.
17092
17093 sC The "timeout connect" stroke before a connection to the server could
17094 complete. When this happens in HTTP mode, the status code is likely a
17095 503 or 504 here.
17096
17097 SD The connection to the server died with an error during the data
17098 transfer. This usually means that haproxy has received an RST from
17099 the server or an ICMP message from an intermediate equipment while
17100 exchanging data with the server. This can be caused by a server crash
17101 or by a network issue on an intermediate equipment.
17102
17103 sD The server did not send nor acknowledge any data for as long as the
17104 "timeout server" setting during the data phase. This is often caused
Davor Ocelice9ed2812017-12-25 17:49:28 +010017105 by too short timeouts on L4 equipment before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017106 load-balancers, ...), as well as keep-alive sessions maintained
17107 between the client and the server expiring first on haproxy.
17108
17109 SH The server aborted before sending its full HTTP response headers, or
17110 it crashed while processing the request. Since a server aborting at
17111 this moment is very rare, it would be wise to inspect its logs to
17112 control whether it crashed and why. The logged request may indicate a
17113 small set of faulty requests, demonstrating bugs in the application.
17114 Sometimes this might also be caused by an IDS killing the connection
17115 between haproxy and the server.
17116
17117 sH The "timeout server" stroke before the server could return its
17118 response headers. This is the most common anomaly, indicating too
17119 long transactions, probably caused by server or database saturation.
17120 The immediate workaround consists in increasing the "timeout server"
17121 setting, but it is important to keep in mind that the user experience
17122 will suffer from these long response times. The only long term
17123 solution is to fix the application.
17124
17125 sQ The session spent too much time in queue and has been expired. See
17126 the "timeout queue" and "timeout connect" settings to find out how to
17127 fix this if it happens too often. If it often happens massively in
17128 short periods, it may indicate general problems on the affected
17129 servers due to I/O or database congestion, or saturation caused by
17130 external attacks.
17131
17132 PC The proxy refused to establish a connection to the server because the
17133 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020017134 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017135 so that it does not happen anymore. This status is very rare and
17136 might happen when the global "ulimit-n" parameter is forced by hand.
17137
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010017138 PD The proxy blocked an incorrectly formatted chunked encoded message in
17139 a request or a response, after the server has emitted its headers. In
17140 most cases, this will indicate an invalid message from the server to
Davor Ocelice9ed2812017-12-25 17:49:28 +010017141 the client. HAProxy supports chunk sizes of up to 2GB - 1 (2147483647
Willy Tarreauf3a3e132013-08-31 08:16:26 +020017142 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010017143
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017144 PH The proxy blocked the server's response, because it was invalid,
17145 incomplete, dangerous (cache control), or matched a security filter.
17146 In any case, an HTTP 502 error is sent to the client. One possible
17147 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010017148 containing unauthorized characters. It is also possible but quite
17149 rare, that the proxy blocked a chunked-encoding request from the
17150 client due to an invalid syntax, before the server responded. In this
17151 case, an HTTP 400 error is sent to the client and reported in the
17152 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017153
17154 PR The proxy blocked the client's HTTP request, either because of an
17155 invalid HTTP syntax, in which case it returned an HTTP 400 error to
17156 the client, or because a deny filter matched, in which case it
17157 returned an HTTP 403 error.
17158
17159 PT The proxy blocked the client's request and has tarpitted its
17160 connection before returning it a 500 server error. Nothing was sent
17161 to the server. The connection was maintained open for as long as
17162 reported by the "Tw" timer field.
17163
17164 RC A local resource has been exhausted (memory, sockets, source ports)
17165 preventing the connection to the server from establishing. The error
17166 logs will tell precisely what was missing. This is very rare and can
17167 only be solved by proper system tuning.
17168
Willy Tarreau996a92c2010-10-13 19:30:47 +020017169The combination of the two last flags gives a lot of information about how
17170persistence was handled by the client, the server and by haproxy. This is very
17171important to troubleshoot disconnections, when users complain they have to
17172re-authenticate. The commonly encountered flags are :
17173
17174 -- Persistence cookie is not enabled.
17175
17176 NN No cookie was provided by the client, none was inserted in the
17177 response. For instance, this can be in insert mode with "postonly"
17178 set on a GET request.
17179
17180 II A cookie designating an invalid server was provided by the client,
17181 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017182 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020017183 value can be presented by a client when no other server knows it.
17184
17185 NI No cookie was provided by the client, one was inserted in the
17186 response. This typically happens for first requests from every user
17187 in "insert" mode, which makes it an easy way to count real users.
17188
17189 VN A cookie was provided by the client, none was inserted in the
17190 response. This happens for most responses for which the client has
17191 already got a cookie.
17192
17193 VU A cookie was provided by the client, with a last visit date which is
17194 not completely up-to-date, so an updated cookie was provided in
17195 response. This can also happen if there was no date at all, or if
17196 there was a date but the "maxidle" parameter was not set, so that the
17197 cookie can be switched to unlimited time.
17198
17199 EI A cookie was provided by the client, with a last visit date which is
17200 too old for the "maxidle" parameter, so the cookie was ignored and a
17201 new cookie was inserted in the response.
17202
17203 OI A cookie was provided by the client, with a first visit date which is
17204 too old for the "maxlife" parameter, so the cookie was ignored and a
17205 new cookie was inserted in the response.
17206
17207 DI The server designated by the cookie was down, a new server was
17208 selected and a new cookie was emitted in the response.
17209
17210 VI The server designated by the cookie was not marked dead but could not
17211 be reached. A redispatch happened and selected another one, which was
17212 then advertised in the response.
17213
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017214
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172158.6. Non-printable characters
17216-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017217
17218In order not to cause trouble to log analysis tools or terminals during log
17219consulting, non-printable characters are not sent as-is into log files, but are
17220converted to the two-digits hexadecimal representation of their ASCII code,
17221prefixed by the character '#'. The only characters that can be logged without
17222being escaped are comprised between 32 and 126 (inclusive). Obviously, the
17223escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
17224is the same for the character '"' which becomes "#22", as well as '{', '|' and
17225'}' when logging headers.
17226
17227Note that the space character (' ') is not encoded in headers, which can cause
17228issues for tools relying on space count to locate fields. A typical header
17229containing spaces is "User-Agent".
17230
17231Last, it has been observed that some syslog daemons such as syslog-ng escape
17232the quote ('"') with a backslash ('\'). The reverse operation can safely be
17233performed since no quote may appear anywhere else in the logs.
17234
17235
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172368.7. Capturing HTTP cookies
17237---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017238
17239Cookie capture simplifies the tracking a complete user session. This can be
17240achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017241section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017242cookie will simultaneously be checked in the request ("Cookie:" header) and in
17243the response ("Set-Cookie:" header). The respective values will be reported in
17244the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017245locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017246not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
17247user switches to a new session for example, because the server will reassign it
17248a new cookie. It is also possible to detect if a server unexpectedly sets a
17249wrong cookie to a client, leading to session crossing.
17250
17251 Examples :
17252 # capture the first cookie whose name starts with "ASPSESSION"
17253 capture cookie ASPSESSION len 32
17254
17255 # capture the first cookie whose name is exactly "vgnvisitor"
17256 capture cookie vgnvisitor= len 32
17257
17258
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172598.8. Capturing HTTP headers
17260---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017261
17262Header captures are useful to track unique request identifiers set by an upper
17263proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
17264the response, one can search for information about the response length, how the
17265server asked the cache to behave, or an object location during a redirection.
17266
17267Header captures are performed using the "capture request header" and "capture
17268response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017269section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017270
17271It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017272time. Non-existent headers are logged as empty strings, and if one header
17273appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017274are grouped within braces '{' and '}' in the same order as they were declared,
17275and delimited with a vertical bar '|' without any space. Response headers
17276follow the same representation, but are displayed after a space following the
17277request headers block. These blocks are displayed just before the HTTP request
17278in the logs.
17279
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020017280As a special case, it is possible to specify an HTTP header capture in a TCP
17281frontend. The purpose is to enable logging of headers which will be parsed in
17282an HTTP backend if the request is then switched to this HTTP backend.
17283
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017284 Example :
17285 # This instance chains to the outgoing proxy
17286 listen proxy-out
17287 mode http
17288 option httplog
17289 option logasap
17290 log global
17291 server cache1 192.168.1.1:3128
17292
17293 # log the name of the virtual server
17294 capture request header Host len 20
17295
17296 # log the amount of data uploaded during a POST
17297 capture request header Content-Length len 10
17298
17299 # log the beginning of the referrer
17300 capture request header Referer len 20
17301
17302 # server name (useful for outgoing proxies only)
17303 capture response header Server len 20
17304
17305 # logging the content-length is useful with "option logasap"
17306 capture response header Content-Length len 10
17307
Davor Ocelice9ed2812017-12-25 17:49:28 +010017308 # log the expected cache behavior on the response
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017309 capture response header Cache-Control len 8
17310
17311 # the Via header will report the next proxy's name
17312 capture response header Via len 20
17313
17314 # log the URL location during a redirection
17315 capture response header Location len 20
17316
17317 >>> Aug 9 20:26:09 localhost \
17318 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
17319 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
17320 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
17321 "GET http://fr.adserver.yahoo.com/"
17322
17323 >>> Aug 9 20:30:46 localhost \
17324 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
17325 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
17326 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017327 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017328
17329 >>> Aug 9 20:30:46 localhost \
17330 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
17331 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
17332 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
17333 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017334 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017335
17336
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200173378.9. Examples of logs
17338---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017339
17340These are real-world examples of logs accompanied with an explanation. Some of
17341them have been made up by hand. The syslog part has been removed for better
17342reading. Their sole purpose is to explain how to decipher them.
17343
17344 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
17345 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
17346 "HEAD / HTTP/1.0"
17347
17348 => long request (6.5s) entered by hand through 'telnet'. The server replied
17349 in 147 ms, and the session ended normally ('----')
17350
17351 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
17352 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
17353 0/9 "HEAD / HTTP/1.0"
17354
17355 => Idem, but the request was queued in the global queue behind 9 other
17356 requests, and waited there for 1230 ms.
17357
17358 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
17359 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
17360 "GET /image.iso HTTP/1.0"
17361
17362 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017363 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017364 14 ms, 243 bytes of headers were sent to the client, and total time from
17365 accept to first data byte is 30 ms.
17366
17367 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
17368 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
17369 "GET /cgi-bin/bug.cgi? HTTP/1.0"
17370
17371 => the proxy blocked a server response either because of an "rspdeny" or
17372 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020017373 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017374 risked being cached. In this case, the response is replaced with a "502
17375 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
17376 to return the 502 and not the server.
17377
17378 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017379 px-http/<NOSRV> -1/-1/-1/-1/8490 -1 0 - - CR-- 2/2/2/0/0 0/0 ""
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017380
17381 => the client never completed its request and aborted itself ("C---") after
17382 8.5s, while the proxy was waiting for the request headers ("-R--").
17383 Nothing was sent to any server.
17384
17385 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
17386 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
17387
17388 => The client never completed its request, which was aborted by the
17389 time-out ("c---") after 50s, while the proxy was waiting for the request
Davor Ocelice9ed2812017-12-25 17:49:28 +010017390 headers ("-R--"). Nothing was sent to any server, but the proxy could
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017391 send a 408 return code to the client.
17392
17393 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
17394 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
17395
17396 => This log was produced with "option tcplog". The client timed out after
17397 5 seconds ("c----").
17398
17399 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
17400 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017401 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017402
17403 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017404 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017405 (config says 'retries 3'), and no redispatch (otherwise we would have
17406 seen "/+3"). Status code 503 was returned to the client. There were 115
17407 connections on this server, 202 connections on this proxy, and 205 on
17408 the global process. It is possible that the server refused the
17409 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010017410
Willy Tarreau52b2d222011-09-07 23:48:48 +020017411
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200174129. Supported filters
17413--------------------
17414
17415Here are listed officially supported filters with the list of parameters they
17416accept. Depending on compile options, some of these filters might be
17417unavailable. The list of available filters is reported in haproxy -vv.
17418
17419See also : "filter"
17420
174219.1. Trace
17422----------
17423
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010017424filter trace [name <name>] [random-parsing] [random-forwarding] [hexdump]
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017425
17426 Arguments:
17427 <name> is an arbitrary name that will be reported in
17428 messages. If no name is provided, "TRACE" is used.
17429
17430 <random-parsing> enables the random parsing of data exchanged between
17431 the client and the server. By default, this filter
17432 parses all available data. With this parameter, it
17433 only parses a random amount of the available data.
17434
Davor Ocelice9ed2812017-12-25 17:49:28 +010017435 <random-forwarding> enables the random forwarding of parsed data. By
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017436 default, this filter forwards all previously parsed
17437 data. With this parameter, it only forwards a random
17438 amount of the parsed data.
17439
Davor Ocelice9ed2812017-12-25 17:49:28 +010017440 <hexdump> dumps all forwarded data to the server and the client.
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010017441
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017442This filter can be used as a base to develop new filters. It defines all
17443callbacks and print a message on the standard error stream (stderr) with useful
17444information for all of them. It may be useful to debug the activity of other
17445filters or, quite simply, HAProxy's activity.
17446
17447Using <random-parsing> and/or <random-forwarding> parameters is a good way to
17448tests the behavior of a filter that parses data exchanged between a client and
17449a server by adding some latencies in the processing.
17450
17451
174529.2. HTTP compression
17453---------------------
17454
17455filter compression
17456
17457The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
17458keyword must still be used to enable and configure the HTTP compression. And
17459when no other filter is used, it is enough. But it is mandatory to explicitly
17460use a filter line to enable the HTTP compression when two or more filters are
17461used for the same listener/frontend/backend. This is important to know the
17462filters evaluation order.
17463
17464See also : "compression"
17465
17466
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200174679.3. Stream Processing Offload Engine (SPOE)
17468--------------------------------------------
17469
17470filter spoe [engine <name>] config <file>
17471
17472 Arguments :
17473
17474 <name> is the engine name that will be used to find the right scope in
17475 the configuration file. If not provided, all the file will be
17476 parsed.
17477
17478 <file> is the path of the engine configuration file. This file can
17479 contain configuration of several engines. In this case, each
17480 part must be placed in its own scope.
17481
17482The Stream Processing Offload Engine (SPOE) is a filter communicating with
17483external components. It allows the offload of some specifics processing on the
Davor Ocelice9ed2812017-12-25 17:49:28 +010017484streams in tiered applications. These external components and information
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020017485exchanged with them are configured in dedicated files, for the main part. It
17486also requires dedicated backends, defined in HAProxy configuration.
17487
17488SPOE communicates with external components using an in-house binary protocol,
17489the Stream Processing Offload Protocol (SPOP).
17490
Tim Düsterhus4896c442016-11-29 02:15:19 +010017491For all information about the SPOE configuration and the SPOP specification, see
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020017492"doc/SPOE.txt".
17493
17494Important note:
17495 The SPOE filter is highly experimental for now and was not heavily
17496 tested. It is really not production ready. So use it carefully.
17497
William Lallemand86d0df02017-11-24 21:36:45 +01001749810. Cache
17499---------
17500
17501HAProxy provides a cache, which was designed to perform cache on small objects
17502(favicon, css...). This is a minimalist low-maintenance cache which runs in
17503RAM.
17504
17505The cache is based on a memory which is shared between processes and threads,
Cyril Bonté7b888f12017-11-26 22:24:31 +010017506this memory is split in blocks of 1k.
William Lallemand86d0df02017-11-24 21:36:45 +010017507
17508If an object is not used anymore, it can be deleted to store a new object
17509independently of its expiration date. The oldest objects are deleted first
17510when we try to allocate a new one.
17511
Cyril Bonté7b888f12017-11-26 22:24:31 +010017512The cache uses a hash of the host header and the URI as the key.
William Lallemand86d0df02017-11-24 21:36:45 +010017513
17514It's possible to view the status of a cache using the Unix socket command
17515"show cache" consult section 9.3 "Unix Socket commands" of Management Guide
17516for more details.
17517
17518When an object is delivered from the cache, the server name in the log is
17519replaced by "<CACHE>".
17520
Cyril Bonté7b888f12017-11-26 22:24:31 +01001752110.1. Limitation
17522----------------
William Lallemand86d0df02017-11-24 21:36:45 +010017523
17524The cache won't store and won't deliver objects in these cases:
17525
17526- If the response is not a 200
17527- If the response contains a Vary header
Frédéric Lécaille5f8bea62018-10-23 10:09:19 +020017528- If the Content-Length + the headers size is greater than "max-object-size"
William Lallemand86d0df02017-11-24 21:36:45 +010017529- If the response is not cacheable
17530
17531- If the request is not a GET
17532- If the HTTP version of the request is smaller than 1.1
William Lallemand8a16fe02018-05-22 11:04:33 +020017533- If the request contains an Authorization header
William Lallemand86d0df02017-11-24 21:36:45 +010017534
17535Caution!: Due to the current limitation of the filters, it is not recommended
17536to use the cache with other filters. Using them can cause undefined behavior
Cyril Bonté7b888f12017-11-26 22:24:31 +010017537if they modify the response (compression for example).
William Lallemand86d0df02017-11-24 21:36:45 +010017538
Cyril Bonté7b888f12017-11-26 22:24:31 +01001753910.2. Setup
17540-----------
William Lallemand86d0df02017-11-24 21:36:45 +010017541
17542To setup a cache, you must define a cache section and use it in a proxy with
17543the corresponding http-request and response actions.
17544
Cyril Bonté7b888f12017-11-26 22:24:31 +01001754510.2.1. Cache section
17546---------------------
William Lallemand86d0df02017-11-24 21:36:45 +010017547
17548cache <name>
17549 Declare a cache section, allocate a shared cache memory named <name>, the
17550 size of cache is mandatory.
17551
17552total-max-size <megabytes>
Davor Ocelice9ed2812017-12-25 17:49:28 +010017553 Define the size in RAM of the cache in megabytes. This size is split in
Frédéric Lécaillee3c83d82018-10-25 10:46:40 +020017554 blocks of 1kB which are used by the cache entries. Its maximum value is 4095.
William Lallemand86d0df02017-11-24 21:36:45 +010017555
Frédéric Lécaille5f8bea62018-10-23 10:09:19 +020017556max-object-size <bytes>
Frédéric Lécaillee3c83d82018-10-25 10:46:40 +020017557 Define the maximum size of the objects to be cached. Must not be greater than
17558 an half of "total-max-size". If not set, it equals to a 256th of the cache size.
17559 All objects with sizes larger than "max-object-size" will not be cached.
Frédéric Lécaille5f8bea62018-10-23 10:09:19 +020017560
William Lallemand86d0df02017-11-24 21:36:45 +010017561max-age <seconds>
17562 Define the maximum expiration duration. The expiration is set has the lowest
17563 value between the s-maxage or max-age (in this order) directive in the
17564 Cache-Control response header and this value. The default value is 60
17565 seconds, which means that you can't cache an object more than 60 seconds by
17566 default.
17567
Cyril Bonté7b888f12017-11-26 22:24:31 +01001756810.2.2. Proxy section
17569---------------------
William Lallemand86d0df02017-11-24 21:36:45 +010017570
17571http-request cache-use <name>
17572 Try to deliver a cached object from the cache <name>. This directive is also
17573 mandatory to store the cache as it calculates the cache hash. If you want to
17574 use a condition for both storage and delivering that's a good idea to put it
17575 after this one.
17576
17577http-response cache-store <name>
17578 Store an http-response within the cache. The storage of the response headers
17579 is done at this step, which means you can use others http-response actions
17580 to modify headers before or after the storage of the response. This action
17581 is responsible for the setup of the cache storage filter.
17582
17583
17584Example:
17585
17586 backend bck1
17587 mode http
17588
17589 http-request cache-use foobar
17590 http-response cache-store foobar
17591 server srv1 127.0.0.1:80
17592
17593 cache foobar
17594 total-max-size 4
17595 max-age 240
17596
Willy Tarreau0ba27502007-12-24 16:55:16 +010017597/*
17598 * Local variables:
17599 * fill-column: 79
17600 * End:
17601 */