blob: a716c34813174b251d765d30dd4345b699aefc34 [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 Tarreau1db55792020-11-05 17:20:35 +01005 version 2.4
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreau46b93af2021-05-10 07:50:26 +02007 2021/05/10
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
Willy Tarreau4b103022021-02-12 17:59:10 +0100442.4. Conditional blocks
452.5. Time format
462.6. Examples
Willy Tarreauc57f0e22009-05-10 13:12:33 +020047
483. Global parameters
493.1. Process management and security
503.2. Performance tuning
513.3. Debugging
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100523.4. Userlists
Cyril Bontédc4d9032012-04-08 21:57:39 +0200533.5. Peers
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200543.6. Mailers
William Lallemandc9515522019-06-12 16:32:11 +0200553.7. Programs
Christopher Faulet76edc0f2020-01-13 15:52:01 +0100563.8. HTTP-errors
Emeric Brun99c453d2020-05-25 15:01:04 +0200573.9. Rings
William Lallemand0217b7b2020-11-18 10:41:24 +0100583.10. Log forwarding
Willy Tarreauc57f0e22009-05-10 13:12:33 +020059
604. Proxies
614.1. Proxy keywords matrix
624.2. Alphabetically sorted keywords reference
63
Davor Ocelice9ed2812017-12-25 17:49:28 +0100645. Bind and server options
Willy Tarreau086fbf52012-09-24 20:34:51 +0200655.1. Bind options
665.2. Server and default-server options
Baptiste Assmann1fa66662015-04-14 00:28:47 +0200675.3. Server DNS resolution
685.3.1. Global overview
695.3.2. The resolvers section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020070
Julien Pivotto6ccee412019-11-27 15:49:54 +0100716. Cache
726.1. Limitation
736.2. Setup
746.2.1. Cache section
756.2.2. Proxy section
76
Willy Tarreau74ca5042013-06-11 23:12:07 +0200777. Using ACLs and fetching samples
787.1. ACL basics
797.1.1. Matching booleans
807.1.2. Matching integers
817.1.3. Matching strings
827.1.4. Matching regular expressions (regexes)
837.1.5. Matching arbitrary data blocks
847.1.6. Matching IPv4 and IPv6 addresses
857.2. Using ACLs to form conditions
867.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200877.3.1. Converters
887.3.2. Fetching samples from internal states
897.3.3. Fetching samples at Layer 4
907.3.4. Fetching samples at Layer 5
917.3.5. Fetching samples from buffer contents (Layer 6)
927.3.6. Fetching HTTP samples (Layer 7)
Christopher Faulete596d182020-05-05 17:46:34 +0200937.3.7. Fetching samples for developers
Willy Tarreau74ca5042013-06-11 23:12:07 +0200947.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020095
968. Logging
978.1. Log levels
988.2. Log formats
998.2.1. Default log format
1008.2.2. TCP log format
1018.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +01001028.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +01001038.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001048.3. Advanced logging options
1058.3.1. Disabling logging of external tests
1068.3.2. Logging before waiting for the session to terminate
1078.3.3. Raising log level upon errors
1088.3.4. Disabling logging of successful connections
1098.4. Timing events
1108.5. Session state at disconnection
1118.6. Non-printable characters
1128.7. Capturing HTTP cookies
1138.8. Capturing HTTP headers
1148.9. Examples of logs
115
Christopher Fauletc3fe5332016-04-07 15:30:10 +02001169. Supported filters
1179.1. Trace
1189.2. HTTP compression
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001199.3. Stream Processing Offload Engine (SPOE)
Christopher Faulet99a17a22018-12-11 09:18:27 +01001209.4. Cache
Christopher Fauletb30b3102019-09-12 23:03:09 +02001219.5. fcgi-app
Miroslav Zagoracdc32cd92020-12-13 18:32:57 +01001229.6. OpenTracing
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200123
Christopher Fauletb30b3102019-09-12 23:03:09 +020012410. FastCGI applications
12510.1. Setup
12610.1.1. Fcgi-app section
12710.1.2. Proxy section
12810.1.3. Example
12910.2. Default parameters
13010.3. Limitations
131
Emeric Brunce325c42021-04-02 17:05:09 +020013211. Address formats
13311.1. Address family prefixes
13411.2. Socket type prefixes
13511.3. Protocol prefixes
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200136
1371. Quick reminder about HTTP
138----------------------------
139
Davor Ocelice9ed2812017-12-25 17:49:28 +0100140When HAProxy is running in HTTP mode, both the request and the response are
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200141fully analyzed and indexed, thus it becomes possible to build matching criteria
142on almost anything found in the contents.
143
144However, it is important to understand how HTTP requests and responses are
145formed, and how HAProxy decomposes them. It will then become easier to write
146correct rules and to debug existing configurations.
147
148
1491.1. The HTTP transaction model
150-------------------------------
151
152The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100153to one and only one response. Traditionally, a TCP connection is established
Davor Ocelice9ed2812017-12-25 17:49:28 +0100154from the client to the server, a request is sent by the client through the
155connection, the server responds, and the connection is closed. A new request
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200156will involve a new connection :
157
158 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
159
160In this mode, called the "HTTP close" mode, there are as many connection
161establishments as there are HTTP transactions. Since the connection is closed
162by the server after the response, the client does not need to know the content
163length.
164
165Due to the transactional nature of the protocol, it was possible to improve it
166to avoid closing a connection between two subsequent transactions. In this mode
167however, it is mandatory that the server indicates the content length for each
168response so that the client does not wait indefinitely. For this, a special
169header is used: "Content-length". This mode is called the "keep-alive" mode :
170
171 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
172
173Its advantages are a reduced latency between transactions, and less processing
174power required on the server side. It is generally better than the close mode,
175but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200176a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177
Willy Tarreau95c4e142017-11-26 12:18:55 +0100178Another improvement in the communications is the pipelining mode. It still uses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200179keep-alive, but the client does not wait for the first response to send the
180second request. This is useful for fetching large number of images composing a
181page :
182
183 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
184
185This can obviously have a tremendous benefit on performance because the network
186latency is eliminated between subsequent requests. Many HTTP agents do not
187correctly support pipelining since there is no way to associate a response with
188the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100189server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200190
Willy Tarreau95c4e142017-11-26 12:18:55 +0100191The next improvement is the multiplexed mode, as implemented in HTTP/2. This
192time, each transaction is assigned a single stream identifier, and all streams
193are multiplexed over an existing connection. Many requests can be sent in
194parallel by the client, and responses can arrive in any order since they also
195carry the stream identifier.
196
Willy Tarreau70dffda2014-01-30 03:07:23 +0100197By default HAProxy operates in keep-alive mode with regards to persistent
198connections: for each connection it processes each request and response, and
199leaves the connection idle on both sides between the end of a response and the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100200start of a new request. When it receives HTTP/2 connections from a client, it
201processes all the requests in parallel and leaves the connection idling,
202waiting for new requests, just as if it was a keep-alive HTTP connection.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200203
Christopher Faulet315b39c2018-09-21 16:26:19 +0200204HAProxy supports 4 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +0100205 - keep alive : all requests and responses are processed (default)
206 - tunnel : only the first request and response are processed,
Christopher Faulet6c9bbb22019-03-26 21:37:23 +0100207 everything else is forwarded with no analysis (deprecated).
Willy Tarreau70dffda2014-01-30 03:07:23 +0100208 - server close : the server-facing connection is closed after the response.
Christopher Faulet315b39c2018-09-21 16:26:19 +0200209 - close : the connection is actively closed after end of response.
Willy Tarreau70dffda2014-01-30 03:07:23 +0100210
Willy Tarreau95c4e142017-11-26 12:18:55 +0100211
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200212
2131.2. HTTP request
214-----------------
215
216First, let's consider this HTTP request :
217
218 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100219 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200220 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
221 2 Host: www.mydomain.com
222 3 User-agent: my small browser
223 4 Accept: image/jpeg, image/gif
224 5 Accept: image/png
225
226
2271.2.1. The Request line
228-----------------------
229
230Line 1 is the "request line". It is always composed of 3 fields :
231
232 - a METHOD : GET
233 - a URI : /serv/login.php?lang=en&profile=2
234 - a version tag : HTTP/1.1
235
236All of them are delimited by what the standard calls LWS (linear white spaces),
237which are commonly spaces, but can also be tabs or line feeds/carriage returns
238followed by spaces/tabs. The method itself cannot contain any colon (':') and
239is limited to alphabetic letters. All those various combinations make it
240desirable that HAProxy performs the splitting itself rather than leaving it to
241the user to write a complex or inaccurate regular expression.
242
243The URI itself can have several forms :
244
245 - A "relative URI" :
246
247 /serv/login.php?lang=en&profile=2
248
249 It is a complete URL without the host part. This is generally what is
250 received by servers, reverse proxies and transparent proxies.
251
252 - An "absolute URI", also called a "URL" :
253
254 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
255
256 It is composed of a "scheme" (the protocol name followed by '://'), a host
257 name or address, optionally a colon (':') followed by a port number, then
258 a relative URI beginning at the first slash ('/') after the address part.
259 This is generally what proxies receive, but a server supporting HTTP/1.1
260 must accept this form too.
261
262 - a star ('*') : this form is only accepted in association with the OPTIONS
263 method and is not relayable. It is used to inquiry a next hop's
264 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100265
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200266 - an address:port combination : 192.168.0.12:80
267 This is used with the CONNECT method, which is used to establish TCP
268 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
269 other protocols too.
270
271In a relative URI, two sub-parts are identified. The part before the question
272mark is called the "path". It is typically the relative path to static objects
273on the server. The part after the question mark is called the "query string".
274It is mostly used with GET requests sent to dynamic scripts and is very
275specific to the language, framework or application in use.
276
Willy Tarreau95c4e142017-11-26 12:18:55 +0100277HTTP/2 doesn't convey a version information with the request, so the version is
Davor Ocelice9ed2812017-12-25 17:49:28 +0100278assumed to be the same as the one of the underlying protocol (i.e. "HTTP/2").
Willy Tarreau95c4e142017-11-26 12:18:55 +0100279
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200280
2811.2.2. The request headers
282--------------------------
283
284The headers start at the second line. They are composed of a name at the
285beginning of the line, immediately followed by a colon (':'). Traditionally,
286an LWS is added after the colon but that's not required. Then come the values.
287Multiple identical headers may be folded into one single line, delimiting the
288values with commas, provided that their order is respected. This is commonly
289encountered in the "Cookie:" field. A header may span over multiple lines if
290the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
291define a total of 3 values for the "Accept:" header.
292
Davor Ocelice9ed2812017-12-25 17:49:28 +0100293Contrary to a common misconception, header names are not case-sensitive, and
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200294their values are not either if they refer to other header names (such as the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100295"Connection:" header). In HTTP/2, header names are always sent in lower case,
Willy Tarreau253c2512020-07-07 15:55:23 +0200296as can be seen when running in debug mode. Internally, all header names are
297normalized to lower case so that HTTP/1.x and HTTP/2 use the exact same
298representation, and they are sent as-is on the other side. This explains why an
299HTTP/1.x request typed with camel case is delivered in lower case.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200300
301The end of the headers is indicated by the first empty line. People often say
302that it's a double line feed, which is not exact, even if a double line feed
303is one valid form of empty line.
304
305Fortunately, HAProxy takes care of all these complex combinations when indexing
306headers, checking values and counting them, so there is no reason to worry
307about the way they could be written, but it is important not to accuse an
308application of being buggy if it does unusual, valid things.
309
310Important note:
Lukas Tribus23953682017-04-28 13:24:30 +0000311 As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200312 in the middle of headers by LWS in order to join multi-line headers. This
313 is necessary for proper analysis and helps less capable HTTP parsers to work
314 correctly and not to be fooled by such complex constructs.
315
316
3171.3. HTTP response
318------------------
319
320An HTTP response looks very much like an HTTP request. Both are called HTTP
321messages. Let's consider this HTTP response :
322
323 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100324 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200325 1 HTTP/1.1 200 OK
326 2 Content-length: 350
327 3 Content-Type: text/html
328
Willy Tarreau816b9792009-09-15 21:25:21 +0200329As a special case, HTTP supports so called "Informational responses" as status
330codes 1xx. These messages are special in that they don't convey any part of the
331response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100332continue to post its request for instance. In the case of a status 100 response
333the requested information will be carried by the next non-100 response message
334following the informational one. This implies that multiple responses may be
335sent to a single request, and that this only works when keep-alive is enabled
336(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
337correctly forward and skip them, and only process the next non-100 response. As
338such, these messages are neither logged nor transformed, unless explicitly
339state otherwise. Status 101 messages indicate that the protocol is changing
Daniel Corbett9f0843f2021-05-08 10:50:37 -0400340over the same connection and that HAProxy must switch to tunnel mode, just as
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100341if a CONNECT had occurred. Then the Upgrade header would contain additional
342information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200343
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200344
Davor Ocelice9ed2812017-12-25 17:49:28 +01003451.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200346------------------------
347
348Line 1 is the "response line". It is always composed of 3 fields :
349
350 - a version tag : HTTP/1.1
351 - a status code : 200
352 - a reason : OK
353
354The status code is always 3-digit. The first digit indicates a general status :
Davor Ocelice9ed2812017-12-25 17:49:28 +0100355 - 1xx = informational message to be skipped (e.g. 100, 101)
356 - 2xx = OK, content is following (e.g. 200, 206)
357 - 3xx = OK, no content following (e.g. 302, 304)
358 - 4xx = error caused by the client (e.g. 401, 403, 404)
359 - 5xx = error caused by the server (e.g. 500, 502, 503)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200360
Lukas Tribus23953682017-04-28 13:24:30 +0000361Please refer to RFC7231 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100362"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200363found there, but it's a common practice to respect the well-established
364messages. It can be composed of one or multiple words, such as "OK", "Found",
365or "Authentication Required".
366
Davor Ocelice9ed2812017-12-25 17:49:28 +0100367HAProxy may emit the following status codes by itself :
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200368
369 Code When / reason
370 200 access to stats page, and when replying to monitoring requests
371 301 when performing a redirection, depending on the configured code
372 302 when performing a redirection, depending on the configured code
373 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100374 307 when performing a redirection, depending on the configured code
375 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200376 400 for an invalid or too large request
377 401 when an authentication is required to perform the action (when
378 accessing the stats page)
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200379 403 when a request is forbidden by a "http-request deny" rule
Florian Tham9205fea2020-01-08 13:35:30 +0100380 404 when the requested resource could not be found
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200381 408 when the request timeout strikes before the request is complete
Florian Tham272e29b2020-01-08 10:19:05 +0100382 410 when the requested resource is no longer available and will not
383 be available again
Daniel Corbett9f0843f2021-05-08 10:50:37 -0400384 500 when HAProxy encounters an unrecoverable internal error, such as a
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200385 memory allocation failure, which should never happen
Daniel Corbett9f0843f2021-05-08 10:50:37 -0400386 501 when HAProxy is unable to satisfy a client request because of an
Christopher Faulete095f312020-12-07 11:22:24 +0100387 unsupported feature
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200388 502 when the server returns an empty, invalid or incomplete response, or
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200389 when an "http-response deny" rule blocks the response.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200390 503 when no server was available to handle the request, or in response to
391 monitoring requests which match the "monitor fail" condition
392 504 when the response timeout strikes before the server responds
393
394The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3954.2).
396
397
3981.3.2. The response headers
399---------------------------
400
401Response headers work exactly like request headers, and as such, HAProxy uses
402the same parsing function for both. Please refer to paragraph 1.2.2 for more
403details.
404
405
4062. Configuring HAProxy
407----------------------
408
4092.1. Configuration file format
410------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200411
412HAProxy's configuration process involves 3 major sources of parameters :
413
414 - the arguments from the command-line, which always take precedence
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100415 - the configuration file(s), whose format is described here
Thayne McCombscdbcca92021-01-07 21:24:41 -0700416 - the running process's environment, in case some environment variables are
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100417 explicitly referenced
Willy Tarreau6a06a402007-07-15 20:15:28 +0200418
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100419The configuration file follows a fairly simple hierarchical format which obey
420a few basic rules:
Willy Tarreau0ba27502007-12-24 16:55:16 +0100421
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100422 1. a configuration file is an ordered sequence of statements
423
424 2. a statement is a single non-empty line before any unprotected "#" (hash)
425
426 3. a line is a series of tokens or "words" delimited by unprotected spaces or
427 tab characters
428
429 4. the first word or sequence of words of a line is one of the keywords or
430 keyword sequences listed in this document
431
432 5. all other words are all arguments of the first one, some being well-known
433 keywords listed in this document, others being values, references to other
434 parts of the configuration, or expressions
435
436 6. certain keywords delimit a section inside which only a subset of keywords
437 are supported
438
439 7. a section ends at the end of a file or on a special keyword starting a new
440 section
441
442This is all that is needed to know to write a simple but reliable configuration
443generator, but this is not enough to reliably parse any configuration nor to
444figure how to deal with certain corner cases.
445
446First, there are a few consequences of the rules above. Rule 6 and 7 imply that
447the keywords used to define a new section are valid everywhere and cannot have
448a different meaning in a specific section. These keywords are always a single
449word (as opposed to a sequence of words), and traditionally the section that
450follows them is designated using the same name. For example when speaking about
451the "global section", it designates the section of configuration that follows
452the "global" keyword. This usage is used a lot in error messages to help locate
453the parts that need to be addressed.
454
455A number of sections create an internal object or configuration space, which
456requires to be distinguished from other ones. In this case they will take an
457extra word which will set the name of this particular section. For some of them
458the section name is mandatory. For example "frontend foo" will create a new
459section of type "frontend" named "foo". Usually a name is specific to its
460section and two sections of different types may use the same name, but this is
461not recommended as it tends to complexify configuration management.
462
463A direct consequence of rule 7 is that when multiple files are read at once,
464each of them must start with a new section, and the end of each file will end
465a section. A file cannot contain sub-sections nor end an existing section and
466start a new one.
467
468Rule 1 mentioned that ordering matters. Indeed, some keywords create directives
469that can be repeated multiple times to create ordered sequences of rules to be
470applied in a certain order. For example "tcp-request" can be used to alternate
471"accept" and "reject" rules on varying criteria. As such, a configuration file
472processor must always preserve a section's ordering when editing a file. The
473ordering of sections usually does not matter except for the global section
474which must be placed before other sections, but it may be repeated if needed.
475In addition, some automatic identifiers may automatically be assigned to some
476of the created objects (e.g. proxies), and by reordering sections, their
477identifiers will change. These ones appear in the statistics for example. As
478such, the configuration below will assign "foo" ID number 1 and "bar" ID number
4792, which will be swapped if the two sections are reversed:
480
481 listen foo
482 bind :80
483
484 listen bar
485 bind :81
486
487Another important point is that according to rules 2 and 3 above, empty lines,
488spaces, tabs, and comments following and unprotected "#" character are not part
489of the configuration as they are just used as delimiters. This implies that the
490following configurations are strictly equivalent:
491
492 global#this is the global section
493 daemon#daemonize
494 frontend foo
495 mode http # or tcp
496
497and:
498
499 global
500 daemon
501
502 # this is the public web frontend
503 frontend foo
504 mode http
505
506The common practice is to align to the left only the keyword that initiates a
507new section, and indent (i.e. prepend a tab character or a few spaces) all
508other keywords so that it's instantly visible that they belong to the same
509section (as done in the second example above). Placing comments before a new
510section helps the reader decide if it's the desired one. Leaving a blank line
511at the end of a section also visually helps spotting the end when editing it.
512
513Tabs are very convenient for indent but they do not copy-paste well. If spaces
514are used instead, it is recommended to avoid placing too many (2 to 4) so that
515editing in field doesn't become a burden with limited editors that do not
516support automatic indent.
517
518In the early days it used to be common to see arguments split at fixed tab
519positions because most keywords would not take more than two arguments. With
520modern versions featuring complex expressions this practice does not stand
521anymore, and is not recommended.
522
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200523
William Lallemandf9873ba2015-05-05 17:37:14 +02005242.2. Quoting and escaping
525-------------------------
526
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100527In modern configurations, some arguments require the use of some characters
528that were previously considered as pure delimiters. In order to make this
529possible, HAProxy supports character escaping by prepending a backslash ('\')
530in front of the character to be escaped, weak quoting within double quotes
531('"') and strong quoting within single quotes ("'").
William Lallemandf9873ba2015-05-05 17:37:14 +0200532
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100533This is pretty similar to what is done in a number of programming languages and
534very close to what is commonly encountered in Bourne shell. The principle is
535the following: while the configuration parser cuts the lines into words, it
536also takes care of quotes and backslashes to decide whether a character is a
537delimiter or is the raw representation of this character within the current
538word. The escape character is then removed, the quotes are removed, and the
539remaining word is used as-is as a keyword or argument for example.
William Lallemandf9873ba2015-05-05 17:37:14 +0200540
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100541If a backslash is needed in a word, it must either be escaped using itself
542(i.e. double backslash) or be strongly quoted.
543
544Escaping outside quotes is achieved by preceding a special character by a
545backslash ('\'):
William Lallemandf9873ba2015-05-05 17:37:14 +0200546
547 \ to mark a space and differentiate it from a delimiter
548 \# to mark a hash and differentiate it from a comment
549 \\ to use a backslash
550 \' to use a single quote and differentiate it from strong quoting
551 \" to use a double quote and differentiate it from weak quoting
552
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100553In addition, a few non-printable characters may be emitted using their usual
554C-language representation:
555
556 \n to insert a line feed (LF, character \x0a or ASCII 10 decimal)
557 \r to insert a carriage return (CR, character \x0d or ASCII 13 decimal)
558 \t to insert a tab (character \x09 or ASCII 9 decimal)
559 \xNN to insert character having ASCII code hex NN (e.g \x0a for LF).
560
561Weak quoting is achieved by surrounding double quotes ("") around the character
562or sequence of characters to protect. Weak quoting prevents the interpretation
563of:
William Lallemandf9873ba2015-05-05 17:37:14 +0200564
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100565 space or tab as a word separator
William Lallemandf9873ba2015-05-05 17:37:14 +0200566 ' single quote as a strong quoting delimiter
567 # hash as a comment start
568
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100569Weak quoting permits the interpretation of environment variables (which are not
570evaluated outside of quotes) by preceding them with a dollar sign ('$'). If a
571dollar character is needed inside double quotes, it must be escaped using a
572backslash.
William Lallemandb2f07452015-05-12 14:27:13 +0200573
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100574Strong quoting is achieved by surrounding single quotes ('') around the
575character or sequence of characters to protect. Inside single quotes, nothing
576is interpreted, it's the efficient way to quote regular expressions.
William Lallemandf9873ba2015-05-05 17:37:14 +0200577
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100578As a result, here is the matrix indicating how special characters can be
579entered in different contexts (unprintable characters are replaced with their
580name within angle brackets). Note that some characters that may only be
581represented escaped have no possible representation inside single quotes,
582hence the '-' there:
William Lallemandf9873ba2015-05-05 17:37:14 +0200583
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100584 Character | Unquoted | Weakly quoted | Strongly quoted
585 -----------+---------------+-----------------------------+-----------------
586 <TAB> | \<TAB>, \x09 | "<TAB>", "\<TAB>", "\x09" | '<TAB>'
587 <LF> | \n, \x0a | "\n", "\x0a" | -
588 <CR> | \r, \x0d | "\r", "\x0d" | -
589 <SPC> | \<SPC>, \x20 | "<SPC>", "\<SPC>", "\x20" | '<SPC>'
590 " | \", \x22 | "\"", "\x22" | '"'
591 # | \#, \x23 | "#", "\#", "\x23" | '#'
592 $ | $, \$, \x24 | "\$", "\x24" | '$'
593 ' | \', \x27 | "'", "\'", "\x27" | -
594 \ | \\, \x5c | "\\", "\x5c" | '\'
William Lallemandf9873ba2015-05-05 17:37:14 +0200595
596 Example:
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100597 # those are all strictly equivalent:
William Lallemandf9873ba2015-05-05 17:37:14 +0200598 log-format %{+Q}o\ %t\ %s\ %{-Q}r
599 log-format "%{+Q}o %t %s %{-Q}r"
600 log-format '%{+Q}o %t %s %{-Q}r'
601 log-format "%{+Q}o %t"' %s %{-Q}r'
602 log-format "%{+Q}o %t"' %s'\ %{-Q}r
603
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100604There is one particular case where a second level of quoting or escaping may be
605necessary. Some keywords take arguments within parenthesis, sometimes delimited
606by commas. These arguments are commonly integers or predefined words, but when
607they are arbitrary strings, it may be required to perform a separate level of
608escaping to disambiguate the characters that belong to the argument from the
609characters that are used to delimit the arguments themselves. A pretty common
610case is the "regsub" converter. It takes a regular expression in argument, and
611if a closing parenthesis is needed inside, this one will require to have its
612own quotes.
613
614The keyword argument parser is exactly the same as the top-level one regarding
615quotes, except that is will not make special cases of backslashes. But what is
Ilya Shipitsin2272d8a2020-12-21 01:22:40 +0500616not always obvious is that the delimiters used inside must first be escaped or
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100617quoted so that they are not resolved at the top level.
618
619Let's take this example making use of the "regsub" converter which takes 3
620arguments, one regular expression, one replacement string and one set of flags:
621
622 # replace all occurrences of "foo" with "blah" in the path:
623 http-request set-path %[path,regsub(foo,blah,g)]
624
625Here no special quoting was necessary. But if now we want to replace either
626"foo" or "bar" with "blah", we'll need the regular expression "(foo|bar)". We
627cannot write:
628
629 http-request set-path %[path,regsub((foo|bar),blah,g)]
630
631because we would like the string to cut like this:
632
633 http-request set-path %[path,regsub((foo|bar),blah,g)]
634 |---------|----|-|
635 arg1 _/ / /
636 arg2 __________/ /
637 arg3 ______________/
638
639but actually what is passed is a string between the opening and closing
640parenthesis then garbage:
641
642 http-request set-path %[path,regsub((foo|bar),blah,g)]
643 |--------|--------|
644 arg1=(foo|bar _/ /
645 trailing garbage _________/
646
647The obvious solution here seems to be that the closing parenthesis needs to be
648quoted, but alone this will not work, because as mentioned above, quotes are
649processed by the top-level parser which will resolve them before processing
650this word:
651
652 http-request set-path %[path,regsub("(foo|bar)",blah,g)]
653 ------------ -------- ----------------------------------
654 word1 word2 word3=%[path,regsub((foo|bar),blah,g)]
655
656So we didn't change anything for the argument parser at the second level which
657still sees a truncated regular expression as the only argument, and garbage at
658the end of the string. By escaping the quotes they will be passed unmodified to
659the second level:
660
661 http-request set-path %[path,regsub(\"(foo|bar)\",blah,g)]
662 ------------ -------- ------------------------------------
663 word1 word2 word3=%[path,regsub("(foo|bar)",blah,g)]
664 |---------||----|-|
665 arg1=(foo|bar) _/ / /
666 arg2=blah ___________/ /
667 arg3=g _______________/
668
Ilya Shipitsin2272d8a2020-12-21 01:22:40 +0500669Another approach consists in using single quotes outside the whole string and
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100670double quotes inside (so that the double quotes are not stripped again):
671
672 http-request set-path '%[path,regsub("(foo|bar)",blah,g)]'
673 ------------ -------- ----------------------------------
674 word1 word2 word3=%[path,regsub("(foo|bar)",blah,g)]
675 |---------||----|-|
676 arg1=(foo|bar) _/ / /
677 arg2 ___________/ /
678 arg3 _______________/
679
680When using regular expressions, it can happen that the dollar ('$') character
681appears in the expression or that a backslash ('\') is used in the replacement
682string. In this case these ones will also be processed inside the double quotes
683thus single quotes are preferred (or double escaping). Example:
684
685 http-request set-path '%[path,regsub("^/(here)(/|$)","my/\1",g)]'
686 ------------ -------- -----------------------------------------
687 word1 word2 word3=%[path,regsub("^/(here)(/|$)","my/\1",g)]
688 |-------------| |-----||-|
689 arg1=(here)(/|$) _/ / /
690 arg2=my/\1 ________________/ /
691 arg3 ______________________/
692
Daniel Corbett9f0843f2021-05-08 10:50:37 -0400693Remember that backslashes are not escape characters within single quotes and
Willy Tarreau6f1129d2020-11-25 19:58:20 +0100694that the whole word3 above is already protected against them using the single
695quotes. Conversely, if double quotes had been used around the whole expression,
696single the dollar character and the backslashes would have been resolved at top
697level, breaking the argument contents at the second level.
698
699When in doubt, simply do not use quotes anywhere, and start to place single or
700double quotes around arguments that require a comma or a closing parenthesis,
701and think about escaping these quotes using a backslash of the string contains
702a dollar or a backslash. Again, this is pretty similar to what is used under
703a Bourne shell when double-escaping a command passed to "eval". For API writers
704the best is probably to place escaped quotes around each and every argument,
705regardless of their contents. Users will probably find that using single quotes
706around the whole expression and double quotes around each argument provides
707more readable configurations.
William Lallemandf9873ba2015-05-05 17:37:14 +0200708
709
William Lallemandb2f07452015-05-12 14:27:13 +02007102.3. Environment variables
711--------------------------
712
713HAProxy's configuration supports environment variables. Those variables are
714interpreted only within double quotes. Variables are expanded during the
715configuration parsing. Variable names must be preceded by a dollar ("$") and
716optionally enclosed with braces ("{}") similarly to what is done in Bourne
717shell. Variable names can contain alphanumerical characters or the character
Amaury Denoyellefa41cb62020-10-01 14:32:35 +0200718underscore ("_") but should not start with a digit. If the variable contains a
719list of several values separated by spaces, it can be expanded as individual
720arguments by enclosing the variable with braces and appending the suffix '[*]'
721before the closing brace.
William Lallemandb2f07452015-05-12 14:27:13 +0200722
723 Example:
724
725 bind "fd@${FD_APP1}"
726
727 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
728
729 user "$HAPROXY_USER"
730
William Lallemand4d03e432019-06-14 15:35:37 +0200731Some variables are defined by HAProxy, they can be used in the configuration
732file, or could be inherited by a program (See 3.7. Programs):
William Lallemanddaf4cd22018-04-17 16:46:13 +0200733
William Lallemand4d03e432019-06-14 15:35:37 +0200734* HAPROXY_LOCALPEER: defined at the startup of the process which contains the
735 name of the local peer. (See "-L" in the management guide.)
736
737* HAPROXY_CFGFILES: list of the configuration files loaded by HAProxy,
738 separated by semicolons. Can be useful in the case you specified a
739 directory.
740
741* HAPROXY_MWORKER: In master-worker mode, this variable is set to 1.
742
John Roeslerfb2fce12019-07-10 15:45:51 -0500743* HAPROXY_CLI: configured listeners addresses of the stats socket for every
William Lallemand4d03e432019-06-14 15:35:37 +0200744 processes, separated by semicolons.
745
John Roeslerfb2fce12019-07-10 15:45:51 -0500746* HAPROXY_MASTER_CLI: In master-worker mode, listeners addresses of the master
William Lallemand4d03e432019-06-14 15:35:37 +0200747 CLI, separated by semicolons.
748
Willy Tarreaua46f1af2021-05-06 10:25:11 +0200749In addition, some pseudo-variables are internally resolved and may be used as
750regular variables. Pseudo-variables always start with a dot ('.'), and are the
751only ones where the dot is permitted. The current list of pseudo-variables is:
752
753* .FILE: the name of the configuration file currently being parsed.
754
755* .LINE: the line number of the configuration file currently being parsed,
756 starting at one.
757
758* .SECTION: the name of the section currently being parsed, or its type if the
759 section doesn't have a name (e.g. "global"), or an empty string before the
760 first section.
761
762These variables are resolved at the location where they are parsed. For example
763if a ".LINE" variable is used in a "log-format" directive located in a defaults
764section, its line number will be resolved before parsing and compiling the
765"log-format" directive, so this same line number will be reused by subsequent
766proxies.
767
768This way it is possible to emit information to help locate a rule in variables,
769logs, error statuses, health checks, header values, or even to use line numbers
770to name some config objects like servers for example.
771
William Lallemand4d03e432019-06-14 15:35:37 +0200772See also "external-check command" for other variables.
William Lallemandb2f07452015-05-12 14:27:13 +0200773
Willy Tarreau4b103022021-02-12 17:59:10 +0100774
7752.4. Conditional blocks
776-----------------------
777
778It may sometimes be convenient to be able to conditionally enable or disable
779some arbitrary parts of the configuration, for example to enable/disable SSL or
780ciphers, enable or disable some pre-production listeners without modifying the
781configuration, or adjust the configuration's syntax to support two distinct
782versions of HAProxy during a migration.. HAProxy brings a set of nestable
783preprocessor-like directives which allow to integrate or ignore some blocks of
784text. These directives must be placed on their own line and they act on the
785lines that follow them. Two of them support an expression, the other ones only
786switch to an alternate block or end a current level. The 4 following directives
787are defined to form conditional blocks:
788
789 - .if <condition>
790 - .elif <condition>
791 - .else
792 - .endif
793
794The ".if" directive nests a new level, ".elif" stays at the same level, ".else"
795as well, and ".endif" closes a level. Each ".if" must be terminated by a
796matching ".endif". The ".elif" may only be placed after ".if" or ".elif", and
797there is no limit to the number of ".elif" that may be chained. There may be
798only one ".else" per ".if" and it must always be after the ".if" or the last
799".elif" of a block.
800
801Comments may be placed on the same line if needed after a '#', they will be
802ignored. The directives are tokenized like other configuration directives, and
803as such it is possible to use environment variables in conditions.
804
805The conditions are currently limited to:
806
807 - an empty string, always returns "false"
808 - the integer zero ('0'), always returns "false"
809 - a non-nul integer (e.g. '1'), always returns "true".
Willy Tarreau42ed14b2021-05-06 15:55:14 +0200810 - a predicate optionally followed by argument(s) in parenthesis.
811
812The list of currently supported predicates is the following:
813
814 - defined(<name>) : returns true if an environment variable <name>
815 exists, regardless of its contents
816
Willy Tarreau58ca7062021-05-06 16:34:23 +0200817 - feature(<name>) : returns true if feature <name> is listed as present
818 in the features list reported by "haproxy -vv"
819 (which means a <name> appears after a '+')
820
Willy Tarreau6492e872021-05-06 16:10:09 +0200821 - streq(<str1>,<str2>) : returns true only if the two strings are equal
822 - strneq(<str1>,<str2>) : returns true only if the two strings differ
823
Willy Tarreau0b7c78a2021-05-06 16:53:26 +0200824 - version_atleast(<ver>): returns true if the current haproxy version is
825 at least as recent as <ver> otherwise false. The
826 version syntax is the same as shown by "haproxy -v"
827 and missing components are assumed as being zero.
828
829 - version_before(<ver>) : returns true if the current haproxy version is
830 strictly older than <ver> otherwise false. The
831 version syntax is the same as shown by "haproxy -v"
832 and missing components are assumed as being zero.
833
Willy Tarreau42ed14b2021-05-06 15:55:14 +0200834Example:
Willy Tarreau4b103022021-02-12 17:59:10 +0100835
Willy Tarreau42ed14b2021-05-06 15:55:14 +0200836 .if defined(HAPROXY_MWORKER)
837 listen mwcli_px
838 bind :1111
839 ...
840 .endif
Willy Tarreau4b103022021-02-12 17:59:10 +0100841
Willy Tarreau6492e872021-05-06 16:10:09 +0200842 .if strneq("$SSL_ONLY",yes)
843 bind :80
844 .endif
845
846 .if streq("$WITH_SSL",yes)
Willy Tarreau58ca7062021-05-06 16:34:23 +0200847 .if feature(OPENSSL)
Willy Tarreau6492e872021-05-06 16:10:09 +0200848 bind :443 ssl crt ...
Willy Tarreau58ca7062021-05-06 16:34:23 +0200849 .endif
Willy Tarreau6492e872021-05-06 16:10:09 +0200850 .endif
851
Willy Tarreau0b7c78a2021-05-06 16:53:26 +0200852 .if version_atleast(2.4-dev19)
853 profiling.memory on
854 .endif
855
Willy Tarreau7190b982021-05-07 08:59:50 +0200856Four other directives are provided to report some status:
Willy Tarreau4b103022021-02-12 17:59:10 +0100857
Willy Tarreau7190b982021-05-07 08:59:50 +0200858 - .diag "message" : emit this message only when in diagnostic mode (-dD)
Willy Tarreau4b103022021-02-12 17:59:10 +0100859 - .notice "message" : emit this message at level NOTICE
860 - .warning "message" : emit this message at level WARNING
861 - .alert "message" : emit this message at level ALERT
862
863Messages emitted at level WARNING may cause the process to fail to start if the
864"strict-mode" is enabled. Messages emitted at level ALERT will always cause a
865fatal error. These can be used to detect some inappropriate conditions and
866provide advice to the user.
867
868Example:
869
870 .if "${A}"
871 .if "${B}"
872 .notice "A=1, B=1"
873 .elif "${C}"
874 .notice "A=1, B=0, C=1"
875 .elif "${D}"
876 .warning "A=1, B=0, C=0, D=1"
877 .else
878 .alert "A=1, B=0, C=0, D=0"
879 .endif
880 .else
881 .notice "A=0"
882 .endif
883
Willy Tarreau7190b982021-05-07 08:59:50 +0200884 .diag "WTA/2021-05-07: replace 'redirect' with 'return' after switch to 2.4"
885 http-request redirect location /goaway if ABUSE
886
Willy Tarreau4b103022021-02-12 17:59:10 +0100887
8882.5. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200889----------------
890
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100891Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100892values are generally expressed in milliseconds (unless explicitly stated
893otherwise) but may be expressed in any other unit by suffixing the unit to the
894numeric value. It is important to consider this because it will not be repeated
895for every keyword. Supported units are :
896
897 - us : microseconds. 1 microsecond = 1/1000000 second
898 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
899 - s : seconds. 1s = 1000ms
900 - m : minutes. 1m = 60s = 60000ms
901 - h : hours. 1h = 60m = 3600s = 3600000ms
902 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
903
904
Willy Tarreau4b103022021-02-12 17:59:10 +01009052.6. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200906-------------
907
908 # Simple configuration for an HTTP proxy listening on port 80 on all
909 # interfaces and forwarding requests to a single backend "servers" with a
910 # single server "server1" listening on 127.0.0.1:8000
911 global
912 daemon
913 maxconn 256
914
915 defaults
916 mode http
917 timeout connect 5000ms
918 timeout client 50000ms
919 timeout server 50000ms
920
921 frontend http-in
922 bind *:80
923 default_backend servers
924
925 backend servers
926 server server1 127.0.0.1:8000 maxconn 32
927
928
929 # The same configuration defined with a single listen block. Shorter but
930 # less expressive, especially in HTTP mode.
931 global
932 daemon
933 maxconn 256
934
935 defaults
936 mode http
937 timeout connect 5000ms
938 timeout client 50000ms
939 timeout server 50000ms
940
941 listen http-in
942 bind *:80
943 server server1 127.0.0.1:8000 maxconn 32
944
945
946Assuming haproxy is in $PATH, test these configurations in a shell with:
947
Willy Tarreauccb289d2010-12-11 20:19:38 +0100948 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200949
950
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009513. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200952--------------------
953
954Parameters in the "global" section are process-wide and often OS-specific. They
955are generally set once for all and do not need being changed once correct. Some
956of them have command-line equivalents.
957
958The following keywords are supported in the "global" section :
959
960 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200961 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200962 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200963 - crt-base
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200964 - cpu-map
Willy Tarreau6a06a402007-07-15 20:15:28 +0200965 - daemon
Willy Tarreau8a022d52021-04-27 20:29:11 +0200966 - default-path
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200967 - description
968 - deviceatlas-json-file
969 - deviceatlas-log-level
970 - deviceatlas-separator
971 - deviceatlas-properties-cookie
Amaury Denoyelled2e53cd2021-05-06 16:21:39 +0200972 - expose-experimental-directives
Simon Horman98637e52014-06-20 12:30:16 +0900973 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200974 - gid
975 - group
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100976 - hard-stop-after
Christopher Faulet98fbe952019-07-22 16:18:24 +0200977 - h1-case-adjust
978 - h1-case-adjust-file
Willy Tarreaud96f1122019-12-03 07:07:36 +0100979 - insecure-fork-wanted
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100980 - insecure-setuid-wanted
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +0100981 - issuers-chain-path
Dragan Dosen13cd54c2020-06-18 18:24:05 +0200982 - localpeer
Willy Tarreau6a06a402007-07-15 20:15:28 +0200983 - log
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200984 - log-tag
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100985 - log-send-hostname
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200986 - lua-load
Thierry Fournier59f11be2020-11-29 00:37:41 +0100987 - lua-load-per-thread
Tim Duesterhusdd74b5f2020-01-12 13:55:40 +0100988 - lua-prepend-path
William Lallemand27edc4b2019-05-07 17:49:33 +0200989 - mworker-max-reloads
Willy Tarreau6a06a402007-07-15 20:15:28 +0200990 - nbproc
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200991 - nbthread
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200992 - node
Amaury Denoyelle0f50cb92021-03-26 18:50:33 +0100993 - numa-cpu-mapping
Willy Tarreau6a06a402007-07-15 20:15:28 +0200994 - pidfile
Willy Tarreau119e50e2020-05-22 13:53:29 +0200995 - pp2-never-send-local
Willy Tarreau1d549722016-02-16 12:41:57 +0100996 - presetenv
997 - resetenv
Willy Tarreau6a06a402007-07-15 20:15:28 +0200998 - uid
999 - ulimit-n
1000 - user
Willy Tarreau636848a2019-04-15 19:38:50 +02001001 - set-dumpable
Willy Tarreau13d2ba22021-03-26 11:38:08 +01001002 - set-var
Willy Tarreau1d549722016-02-16 12:41:57 +01001003 - setenv
Willy Tarreaufbee7132007-10-18 13:53:22 +02001004 - stats
Baptiste Assmann3493d0f2015-10-12 20:21:23 +02001005 - ssl-default-bind-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001006 - ssl-default-bind-ciphersuites
Jerome Magninb203ff62020-04-03 15:28:22 +02001007 - ssl-default-bind-curves
Baptiste Assmann3493d0f2015-10-12 20:21:23 +02001008 - ssl-default-bind-options
1009 - ssl-default-server-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001010 - ssl-default-server-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +02001011 - ssl-default-server-options
1012 - ssl-dh-param-file
Emeric Brun850efd52014-01-29 12:24:34 +01001013 - ssl-server-verify
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001014 - ssl-skip-self-issued-ca
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001015 - unix-bind
Willy Tarreau1d549722016-02-16 12:41:57 +01001016 - unsetenv
Thomas Holmesdb04f192015-05-18 13:21:39 +01001017 - 51degrees-data-file
1018 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +02001019 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001020 - 51degrees-cache-size
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001021 - wurfl-data-file
1022 - wurfl-information-list
1023 - wurfl-information-list-separator
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001024 - wurfl-cache-size
William Dauchy0fec3ab2019-10-27 20:08:11 +01001025 - strict-limits
Willy Tarreaud72758d2010-01-12 10:42:19 +01001026
Willy Tarreau6a06a402007-07-15 20:15:28 +02001027 * Performance tuning
William Dauchy0a8824f2019-10-27 20:08:09 +01001028 - busy-polling
Willy Tarreau1746eec2014-04-25 10:46:47 +02001029 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +02001030 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +02001031 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +01001032 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +01001033 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001034 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +02001035 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +02001036 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +02001037 - maxsslrate
Baptiste Assmann3493d0f2015-10-12 20:21:23 +02001038 - maxzlibmem
Willy Tarreau6a06a402007-07-15 20:15:28 +02001039 - noepoll
1040 - nokqueue
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001041 - noevports
Willy Tarreau6a06a402007-07-15 20:15:28 +02001042 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001043 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001044 - nogetaddrinfo
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00001045 - noreuseport
Willy Tarreau75c62c22018-11-22 11:02:09 +01001046 - profiling.tasks
Willy Tarreaufe255b72007-10-14 23:09:26 +02001047 - spread-checks
Baptiste Assmann5626f482015-08-23 10:00:10 +02001048 - server-state-base
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +02001049 - server-state-file
Grant Zhang872f9c22017-01-21 01:10:18 +00001050 - ssl-engine
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001051 - ssl-mode-async
Baptiste Assmann3493d0f2015-10-12 20:21:23 +02001052 - tune.buffers.limit
1053 - tune.buffers.reserve
Willy Tarreau27a674e2009-08-17 07:23:33 +02001054 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +02001055 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +01001056 - tune.comp.maxlevel
Willy Tarreaubc52bec2020-06-18 08:58:47 +02001057 - tune.fd.edge-triggered
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02001058 - tune.h2.header-table-size
Willy Tarreaue6baec02017-07-27 11:45:11 +02001059 - tune.h2.initial-window-size
Willy Tarreau5242ef82017-07-27 11:47:28 +02001060 - tune.h2.max-concurrent-streams
Willy Tarreau193b8c62012-11-22 00:17:38 +01001061 - tune.http.cookielen
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001062 - tune.http.logurilen
Willy Tarreauac1932d2011-10-24 19:14:41 +02001063 - tune.http.maxhdr
Willy Tarreau76cc6992020-07-01 18:49:24 +02001064 - tune.idle-pool.shared
Willy Tarreau7e312732014-02-12 16:35:14 +01001065 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001066 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +01001067 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001068 - tune.lua.session-timeout
1069 - tune.lua.task-timeout
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001070 - tune.lua.service-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001071 - tune.maxaccept
1072 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +02001073 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +02001074 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02001075 - tune.pipesize
Willy Tarreaua8e2d972020-07-01 18:27:16 +02001076 - tune.pool-high-fd-ratio
1077 - tune.pool-low-fd-ratio
Willy Tarreaue803de22010-01-21 17:43:04 +01001078 - tune.rcvbuf.client
1079 - tune.rcvbuf.server
Willy Tarreaub22fc302015-12-14 12:04:35 +01001080 - tune.recv_enough
Olivier Houchard1599b802018-05-24 18:59:04 +02001081 - tune.runqueue-depth
Willy Tarreaue7723bd2020-06-24 11:11:02 +02001082 - tune.sched.low-latency
Willy Tarreaue803de22010-01-21 17:43:04 +01001083 - tune.sndbuf.client
1084 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001085 - tune.ssl.cachesize
William Lallemand7d42ef52020-07-06 11:41:30 +02001086 - tune.ssl.keylog
Willy Tarreaubfd59462013-02-21 07:46:09 +01001087 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +02001088 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +01001089 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001090 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +02001091 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01001092 - tune.ssl.capture-cipherlist-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001093 - tune.vars.global-max-size
Christopher Fauletff2613e2016-11-09 11:36:17 +01001094 - tune.vars.proc-max-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001095 - tune.vars.reqres-max-size
1096 - tune.vars.sess-max-size
1097 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +01001098 - tune.zlib.memlevel
1099 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +01001100
Willy Tarreau6a06a402007-07-15 20:15:28 +02001101 * Debugging
Willy Tarreau6a06a402007-07-15 20:15:28 +02001102 - quiet
Willy Tarreau3eb10b82020-04-15 16:42:39 +02001103 - zero-warning
Willy Tarreau6a06a402007-07-15 20:15:28 +02001104
1105
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011063.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +02001107------------------------------------
1108
Emeric Brunc8e8d122012-10-02 18:42:10 +02001109ca-base <dir>
1110 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emmanuel Hocdet842e94e2019-12-16 16:39:17 +01001111 relative path is used with "ca-file", "ca-verify-file" or "crl-file"
1112 directives. Absolute locations specified in "ca-file", "ca-verify-file" and
1113 "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +02001114
Willy Tarreau6a06a402007-07-15 20:15:28 +02001115chroot <jail dir>
1116 Changes current directory to <jail dir> and performs a chroot() there before
1117 dropping privileges. This increases the security level in case an unknown
1118 vulnerability would be exploited, since it would make it very hard for the
1119 attacker to exploit the system. This only works when the process is started
1120 with superuser privileges. It is important to ensure that <jail_dir> is both
Davor Ocelice9ed2812017-12-25 17:49:28 +01001121 empty and non-writable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +01001122
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001123cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>...
1124 On Linux 2.6 and above, it is possible to bind a process or a thread to a
1125 specific CPU set. This means that the process or the thread will never run on
1126 other CPUs. The "cpu-map" directive specifies CPU sets for process or thread
1127 sets. The first argument is a process set, eventually followed by a thread
1128 set. These sets have the format
1129
1130 all | odd | even | number[-[number]]
1131
1132 <number>> must be a number between 1 and 32 or 64, depending on the machine's
Davor Ocelice9ed2812017-12-25 17:49:28 +01001133 word size. Any process IDs above nbproc and any thread IDs above nbthread are
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001134 ignored. It is possible to specify a range with two such number delimited by
1135 a dash ('-'). It also is possible to specify all processes at once using
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +01001136 "all", only odd numbers using "odd" or even numbers using "even", just like
1137 with the "bind-process" directive. The second and forthcoming arguments are
Amaury Denoyelle982fb532021-04-21 18:39:58 +02001138 CPU sets. Each CPU set is either a unique number starting at 0 for the first
1139 CPU or a range with two such numbers delimited by a dash ('-'). Outside of
1140 Linux and BSDs, there may be a limitation on the maximum CPU index to either
1141 31 or 63. Multiple CPU numbers or ranges may be specified, and the processes
1142 or threads will be allowed to bind to all of them. Obviously, multiple
1143 "cpu-map" directives may be specified. Each "cpu-map" directive will replace
1144 the previous ones when they overlap. A thread will be bound on the
1145 intersection of its mapping and the one of the process on which it is
1146 attached. If the intersection is null, no specific binding will be set for
1147 the thread.
Willy Tarreaufc6c0322012-11-16 16:12:27 +01001148
Christopher Fauletff4121f2017-11-22 16:38:49 +01001149 Ranges can be partially defined. The higher bound can be omitted. In such
1150 case, it is replaced by the corresponding maximum value, 32 or 64 depending
1151 on the machine's word size.
1152
Christopher Faulet26028f62017-11-22 15:01:51 +01001153 The prefix "auto:" can be added before the process set to let HAProxy
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001154 automatically bind a process or a thread to a CPU by incrementing
1155 process/thread and CPU sets. To be valid, both sets must have the same
1156 size. No matter the declaration order of the CPU sets, it will be bound from
1157 the lowest to the highest bound. Having a process and a thread range with the
1158 "auto:" prefix is not supported. Only one range is supported, the other one
1159 must be a fixed number.
Christopher Faulet26028f62017-11-22 15:01:51 +01001160
1161 Examples:
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001162 cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs
1163
1164 cpu-map 1/all 0-3 # bind all threads of the first process on the
1165 # first 4 CPUs
1166
1167 cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63"
1168 # or "cpu-map 1-32 0-31" depending on the machine's
1169 # word size.
1170
Christopher Faulet26028f62017-11-22 15:01:51 +01001171 # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001172 # and so on.
Christopher Faulet26028f62017-11-22 15:01:51 +01001173 cpu-map auto:1-4 0-3
1174 cpu-map auto:1-4 0-1 2-3
1175 cpu-map auto:1-4 3 2 1 0
1176
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001177 # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
1178 # and so on.
1179 cpu-map auto:1/1-4 0-3
1180 cpu-map auto:1/1-4 0-1 2-3
1181 cpu-map auto:1/1-4 3 2 1 0
1182
Davor Ocelice9ed2812017-12-25 17:49:28 +01001183 # bind each process to exactly one CPU using all/odd/even keyword
Christopher Faulet26028f62017-11-22 15:01:51 +01001184 cpu-map auto:all 0-63
1185 cpu-map auto:even 0-31
1186 cpu-map auto:odd 32-63
1187
1188 # invalid cpu-map because process and CPU sets have different sizes.
1189 cpu-map auto:1-4 0 # invalid
1190 cpu-map auto:1 0-3 # invalid
1191
Christopher Fauletcb6a9452017-11-22 16:50:41 +01001192 # invalid cpu-map because automatic binding is used with a process range
1193 # and a thread range.
1194 cpu-map auto:all/all 0 # invalid
1195 cpu-map auto:all/1-4 0 # invalid
1196 cpu-map auto:1-4/all 0 # invalid
1197
Emeric Brunc8e8d122012-10-02 18:42:10 +02001198crt-base <dir>
1199 Assigns a default directory to fetch SSL certificates from when a relative
William Dauchy238ea3b2020-01-11 13:09:12 +01001200 path is used with "crtfile" or "crt" directives. Absolute locations specified
1201 prevail and ignore "crt-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +02001202
Willy Tarreau6a06a402007-07-15 20:15:28 +02001203daemon
1204 Makes the process fork into background. This is the recommended mode of
1205 operation. It is equivalent to the command line "-D" argument. It can be
Lukas Tribusf46bf952017-11-21 12:39:34 +01001206 disabled by the command line "-db" argument. This option is ignored in
1207 systemd mode.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001208
Willy Tarreau8a022d52021-04-27 20:29:11 +02001209default-path { current | config | parent | origin <path> }
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001210 By default HAProxy loads all files designated by a relative path from the
Willy Tarreau8a022d52021-04-27 20:29:11 +02001211 location the process is started in. In some circumstances it might be
1212 desirable to force all relative paths to start from a different location
1213 just as if the process was started from such locations. This is what this
1214 directive is made for. Technically it will perform a temporary chdir() to
1215 the designated location while processing each configuration file, and will
1216 return to the original directory after processing each file. It takes an
1217 argument indicating the policy to use when loading files whose path does
1218 not start with a slash ('/'):
1219 - "current" indicates that all relative files are to be loaded from the
1220 directory the process is started in ; this is the default.
1221
1222 - "config" indicates that all relative files should be loaded from the
1223 directory containing the configuration file. More specifically, if the
1224 configuration file contains a slash ('/'), the longest part up to the
1225 last slash is used as the directory to change to, otherwise the current
1226 directory is used. This mode is convenient to bundle maps, errorfiles,
1227 certificates and Lua scripts together as relocatable packages. When
1228 multiple configuration files are loaded, the directory is updated for
1229 each of them.
1230
1231 - "parent" indicates that all relative files should be loaded from the
1232 parent of the directory containing the configuration file. More
1233 specifically, if the configuration file contains a slash ('/'), ".."
1234 is appended to the longest part up to the last slash is used as the
1235 directory to change to, otherwise the directory is "..". This mode is
1236 convenient to bundle maps, errorfiles, certificates and Lua scripts
1237 together as relocatable packages, but where each part is located in a
1238 different subdirectory (e.g. "config/", "certs/", "maps/", ...).
1239
1240 - "origin" indicates that all relative files should be loaded from the
1241 designated (mandatory) path. This may be used to ease management of
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001242 different HAProxy instances running in parallel on a system, where each
Willy Tarreau8a022d52021-04-27 20:29:11 +02001243 instance uses a different prefix but where the rest of the sections are
1244 made easily relocatable.
1245
1246 Each "default-path" directive instantly replaces any previous one and will
1247 possibly result in switching to a different directory. While this should
1248 always result in the desired behavior, it is really not a good practice to
1249 use multiple default-path directives, and if used, the policy ought to remain
1250 consistent across all configuration files.
1251
1252 Warning: some configuration elements such as maps or certificates are
1253 uniquely identified by their configured path. By using a relocatable layout,
1254 it becomes possible for several of them to end up with the same unique name,
1255 making it difficult to update them at run time, especially when multiple
1256 configuration files are loaded from different directories. It is essential to
1257 observe a strict collision-free file naming scheme before adopting relative
1258 paths. A robust approach could consist in prefixing all files names with
1259 their respective site name, or in doing so at the directory level.
1260
David Carlier8167f302015-06-01 13:50:06 +02001261deviceatlas-json-file <path>
1262 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001263 The path must be a valid JSON data file and accessible by HAProxy process.
David Carlier8167f302015-06-01 13:50:06 +02001264
1265deviceatlas-log-level <value>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001266 Sets the level of information returned by the API. This directive is
David Carlier8167f302015-06-01 13:50:06 +02001267 optional and set to 0 by default if not set.
1268
1269deviceatlas-separator <char>
1270 Sets the character separator for the API properties results. This directive
1271 is optional and set to | by default if not set.
1272
Cyril Bonté0306c4a2015-10-26 22:37:38 +01001273deviceatlas-properties-cookie <name>
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001274 Sets the client cookie's name used for the detection if the DeviceAtlas
1275 Client-side component was used during the request. This directive is optional
1276 and set to DAPROPS by default if not set.
David Carlier29b3ca32015-09-25 14:09:21 +01001277
Amaury Denoyelled2e53cd2021-05-06 16:21:39 +02001278expose-experimental-directives
1279 This statement must appear before using directives tagged as experimental or
1280 the config file will be rejected.
1281
Simon Horman98637e52014-06-20 12:30:16 +09001282external-check
Willy Tarreaud96f1122019-12-03 07:07:36 +01001283 Allows the use of an external agent to perform health checks. This is
1284 disabled by default as a security precaution, and even when enabled, checks
Willy Tarreaua45a8b52019-12-06 16:31:45 +01001285 may still fail unless "insecure-fork-wanted" is enabled as well. If the
1286 program launched makes use of a setuid executable (it should really not),
1287 you may also need to set "insecure-setuid-wanted" in the global section.
1288 See "option external-check", and "insecure-fork-wanted", and
1289 "insecure-setuid-wanted".
Simon Horman98637e52014-06-20 12:30:16 +09001290
Willy Tarreau6a06a402007-07-15 20:15:28 +02001291gid <number>
Thayne McCombscdbcca92021-01-07 21:24:41 -07001292 Changes the process's group ID to <number>. It is recommended that the group
Willy Tarreau6a06a402007-07-15 20:15:28 +02001293 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
1294 be started with a user belonging to this group, or with superuser privileges.
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001295 Note that if HAProxy is started from a user having supplementary groups, it
Michael Schererab012dd2013-01-12 18:35:19 +01001296 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001297 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +01001298
Willy Tarreau11770ce2019-12-03 08:29:22 +01001299group <group name>
1300 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
1301 See also "gid" and "user".
1302
Cyril Bonté203ec5a2017-03-23 22:44:13 +01001303hard-stop-after <time>
1304 Defines the maximum time allowed to perform a clean soft-stop.
1305
1306 Arguments :
1307 <time> is the maximum time (by default in milliseconds) for which the
1308 instance will remain alive when a soft-stop is received via the
1309 SIGUSR1 signal.
1310
1311 This may be used to ensure that the instance will quit even if connections
1312 remain opened during a soft-stop (for example with long timeouts for a proxy
1313 in tcp mode). It applies both in TCP and HTTP mode.
1314
1315 Example:
1316 global
1317 hard-stop-after 30s
1318
Christopher Faulet98fbe952019-07-22 16:18:24 +02001319h1-case-adjust <from> <to>
1320 Defines the case adjustment to apply, when enabled, to the header name
1321 <from>, to change it to <to> before sending it to HTTP/1 clients or
1322 servers. <from> must be in lower case, and <from> and <to> must not differ
1323 except for their case. It may be repeated if several header names need to be
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05001324 adjusted. Duplicate entries are not allowed. If a lot of header names have to
Christopher Faulet98fbe952019-07-22 16:18:24 +02001325 be adjusted, it might be more convenient to use "h1-case-adjust-file".
1326 Please note that no transformation will be applied unless "option
1327 h1-case-adjust-bogus-client" or "option h1-case-adjust-bogus-server" is
1328 specified in a proxy.
1329
1330 There is no standard case for header names because, as stated in RFC7230,
1331 they are case-insensitive. So applications must handle them in a case-
1332 insensitive manner. But some bogus applications violate the standards and
1333 erroneously rely on the cases most commonly used by browsers. This problem
1334 becomes critical with HTTP/2 because all header names must be exchanged in
1335 lower case, and HAProxy follows the same convention. All header names are
1336 sent in lower case to clients and servers, regardless of the HTTP version.
1337
1338 Applications which fail to properly process requests or responses may require
1339 to temporarily use such workarounds to adjust header names sent to them for
1340 the time it takes the application to be fixed. Please note that an
1341 application which requires such workarounds might be vulnerable to content
1342 smuggling attacks and must absolutely be fixed.
1343
1344 Example:
1345 global
1346 h1-case-adjust content-length Content-Length
1347
1348 See "h1-case-adjust-file", "option h1-case-adjust-bogus-client" and
1349 "option h1-case-adjust-bogus-server".
1350
1351h1-case-adjust-file <hdrs-file>
1352 Defines a file containing a list of key/value pairs used to adjust the case
1353 of some header names before sending them to HTTP/1 clients or servers. The
1354 file <hdrs-file> must contain 2 header names per line. The first one must be
1355 in lower case and both must not differ except for their case. Lines which
1356 start with '#' are ignored, just like empty lines. Leading and trailing tabs
1357 and spaces are stripped. Duplicate entries are not allowed. Please note that
1358 no transformation will be applied unless "option h1-case-adjust-bogus-client"
1359 or "option h1-case-adjust-bogus-server" is specified in a proxy.
1360
1361 If this directive is repeated, only the last one will be processed. It is an
1362 alternative to the directive "h1-case-adjust" if a lot of header names need
1363 to be adjusted. Please read the risks associated with using this.
1364
1365 See "h1-case-adjust", "option h1-case-adjust-bogus-client" and
1366 "option h1-case-adjust-bogus-server".
1367
Willy Tarreaud96f1122019-12-03 07:07:36 +01001368insecure-fork-wanted
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001369 By default HAProxy tries hard to prevent any thread and process creation
Willy Tarreaud96f1122019-12-03 07:07:36 +01001370 after it starts. Doing so is particularly important when using Lua files of
1371 uncertain origin, and when experimenting with development versions which may
1372 still contain bugs whose exploitability is uncertain. And generally speaking
1373 it's good hygiene to make sure that no unexpected background activity can be
1374 triggered by traffic. But this prevents external checks from working, and may
1375 break some very specific Lua scripts which actively rely on the ability to
1376 fork. This option is there to disable this protection. Note that it is a bad
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001377 idea to disable it, as a vulnerability in a library or within HAProxy itself
Willy Tarreaud96f1122019-12-03 07:07:36 +01001378 will be easier to exploit once disabled. In addition, forking from Lua or
1379 anywhere else is not reliable as the forked process may randomly embed a lock
1380 set by another thread and never manage to finish an operation. As such it is
1381 highly recommended that this option is never used and that any workload
1382 requiring such a fork be reconsidered and moved to a safer solution (such as
1383 agents instead of external checks). This option supports the "no" prefix to
1384 disable it.
1385
Willy Tarreaua45a8b52019-12-06 16:31:45 +01001386insecure-setuid-wanted
1387 HAProxy doesn't need to call executables at run time (except when using
1388 external checks which are strongly recommended against), and is even expected
1389 to isolate itself into an empty chroot. As such, there basically is no valid
1390 reason to allow a setuid executable to be called without the user being fully
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001391 aware of the risks. In a situation where HAProxy would need to call external
Willy Tarreaua45a8b52019-12-06 16:31:45 +01001392 checks and/or disable chroot, exploiting a vulnerability in a library or in
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001393 HAProxy itself could lead to the execution of an external program. On Linux
Willy Tarreaua45a8b52019-12-06 16:31:45 +01001394 it is possible to lock the process so that any setuid bit present on such an
1395 executable is ignored. This significantly reduces the risk of privilege
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001396 escalation in such a situation. This is what HAProxy does by default. In case
Willy Tarreaua45a8b52019-12-06 16:31:45 +01001397 this causes a problem to an external check (for example one which would need
1398 the "ping" command), then it is possible to disable this protection by
1399 explicitly adding this directive in the global section. If enabled, it is
1400 possible to turn it back off by prefixing it with the "no" keyword.
1401
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +01001402issuers-chain-path <dir>
1403 Assigns a directory to load certificate chain for issuer completion. All
1404 files must be in PEM format. For certificates loaded with "crt" or "crt-list",
1405 if certificate chain is not included in PEM (also commonly known as
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001406 intermediate certificate), HAProxy will complete chain if the issuer of the
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +01001407 certificate corresponds to the first certificate of the chain loaded with
1408 "issuers-chain-path".
1409 A "crt" file with PrivateKey+Certificate+IntermediateCA2+IntermediateCA1
1410 could be replaced with PrivateKey+Certificate. HAProxy will complete the
1411 chain if a file with IntermediateCA2+IntermediateCA1 is present in
1412 "issuers-chain-path" directory. All other certificates with the same issuer
1413 will share the chain in memory.
1414
Dragan Dosen13cd54c2020-06-18 18:24:05 +02001415localpeer <name>
1416 Sets the local instance's peer name. It will be ignored if the "-L"
1417 command line argument is specified or if used after "peers" section
1418 definitions. In such cases, a warning message will be emitted during
1419 the configuration parsing.
1420
1421 This option will also set the HAPROXY_LOCALPEER environment variable.
1422 See also "-L" in the management guide and "peers" section below.
1423
Jan Wagner3e678602020-12-17 22:22:32 +01001424log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02001425 <facility> [max level [min level]]
Cyril Bonté3e954872018-03-20 23:30:27 +01001426 Adds a global syslog server. Several global servers can be defined. They
Davor Ocelice9ed2812017-12-25 17:49:28 +01001427 will receive logs for starts and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +01001428 configured with "log global".
1429
1430 <address> can be one of:
1431
Willy Tarreau2769aa02007-12-27 18:26:09 +01001432 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +01001433 no port is specified, 514 is used by default (the standard syslog
1434 port).
1435
David du Colombier24bb5f52011-03-17 10:40:23 +01001436 - An IPv6 address followed by a colon and optionally a UDP port. If
1437 no port is specified, 514 is used by default (the standard syslog
1438 port).
1439
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01001440 - A filesystem path to a datagram UNIX domain socket, keeping in mind
Robert Tsai81ae1952007-12-05 10:47:29 +01001441 considerations for chroot (be sure the path is accessible inside
1442 the chroot) and uid/gid (be sure the path is appropriately
Davor Ocelice9ed2812017-12-25 17:49:28 +01001443 writable).
Robert Tsai81ae1952007-12-05 10:47:29 +01001444
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01001445 - A file descriptor number in the form "fd@<number>", which may point
1446 to a pipe, terminal, or socket. In this case unbuffered logs are used
1447 and one writev() call per log is performed. This is a bit expensive
1448 but acceptable for most workloads. Messages sent this way will not be
1449 truncated but may be dropped, in which case the DroppedLogs counter
1450 will be incremented. The writev() call is atomic even on pipes for
1451 messages up to PIPE_BUF size, which POSIX recommends to be at least
1452 512 and which is 4096 bytes on most modern operating systems. Any
1453 larger message may be interleaved with messages from other processes.
1454 Exceptionally for debugging purposes the file descriptor may also be
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001455 directed to a file, but doing so will significantly slow HAProxy down
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01001456 as non-blocking calls will be ignored. Also there will be no way to
1457 purge nor rotate this file without restarting the process. Note that
1458 the configured syslog format is preserved, so the output is suitable
Willy Tarreauc1b06452018-11-12 11:57:56 +01001459 for use with a TCP syslog server. See also the "short" and "raw"
1460 format below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01001461
1462 - "stdout" / "stderr", which are respectively aliases for "fd@1" and
1463 "fd@2", see above.
1464
Willy Tarreauc046d162019-08-30 15:24:59 +02001465 - A ring buffer in the form "ring@<name>", which will correspond to an
1466 in-memory ring buffer accessible over the CLI using the "show events"
1467 command, which will also list existing rings and their sizes. Such
1468 buffers are lost on reload or restart but when used as a complement
1469 this can help troubleshooting by having the logs instantly available.
1470
William Lallemandb2f07452015-05-12 14:27:13 +02001471 You may want to reference some environment variables in the address
1472 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001473
Willy Tarreau18324f52014-06-27 18:10:07 +02001474 <length> is an optional maximum line length. Log lines larger than this value
1475 will be truncated before being sent. The reason is that syslog
1476 servers act differently on log line length. All servers support the
1477 default value of 1024, but some servers simply drop larger lines
1478 while others do log them. If a server supports long lines, it may
1479 make sense to set this value here in order to avoid truncating long
1480 lines. Similarly, if a server drops long lines, it is preferable to
1481 truncate them before sending them. Accepted values are 80 to 65535
1482 inclusive. The default value of 1024 is generally fine for all
1483 standard usages. Some specific cases of long captures or
Davor Ocelice9ed2812017-12-25 17:49:28 +01001484 JSON-formatted logs may require larger values. You may also need to
1485 increase "tune.http.logurilen" if your request URIs are truncated.
Willy Tarreau18324f52014-06-27 18:10:07 +02001486
Dragan Dosen7ad31542015-09-28 17:16:47 +02001487 <format> is the log format used when generating syslog messages. It may be
1488 one of the following :
1489
Emeric Brun0237c4e2020-11-27 16:24:34 +01001490 local Analog to rfc3164 syslog message format except that hostname
1491 field is stripped. This is the default.
1492 Note: option "log-send-hostname" switches the default to
1493 rfc3164.
1494
1495 rfc3164 The RFC3164 syslog message format.
Dragan Dosen7ad31542015-09-28 17:16:47 +02001496 (https://tools.ietf.org/html/rfc3164)
1497
1498 rfc5424 The RFC5424 syslog message format.
1499 (https://tools.ietf.org/html/rfc5424)
1500
Emeric Brun54648852020-07-06 15:54:06 +02001501 priority A message containing only a level plus syslog facility between
1502 angle brackets such as '<63>', followed by the text. The PID,
1503 date, time, process name and system name are omitted. This is
1504 designed to be used with a local log server.
1505
Willy Tarreaue8746a02018-11-12 08:45:00 +01001506 short A message containing only a level between angle brackets such as
1507 '<3>', followed by the text. The PID, date, time, process name
1508 and system name are omitted. This is designed to be used with a
1509 local log server. This format is compatible with what the systemd
1510 logger consumes.
1511
Emeric Brun54648852020-07-06 15:54:06 +02001512 timed A message containing only a level between angle brackets such as
1513 '<3>', followed by ISO date and by the text. The PID, process
1514 name and system name are omitted. This is designed to be
1515 used with a local log server.
1516
1517 iso A message containing only the ISO date, followed by the text.
1518 The PID, process name and system name are omitted. This is
1519 designed to be used with a local log server.
1520
Willy Tarreauc1b06452018-11-12 11:57:56 +01001521 raw A message containing only the text. The level, PID, date, time,
1522 process name and system name are omitted. This is designed to be
1523 used in containers or during development, where the severity only
1524 depends on the file descriptor used (stdout/stderr).
1525
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02001526 <ranges> A list of comma-separated ranges to identify the logs to sample.
1527 This is used to balance the load of the logs to send to the log
1528 server. The limits of the ranges cannot be null. They are numbered
1529 from 1. The size or period (in number of logs) of the sample must be
1530 set with <sample_size> parameter.
1531
1532 <sample_size>
1533 The size of the sample in number of logs to consider when balancing
1534 their logging loads. It is used to balance the load of the logs to
1535 send to the syslog server. This size must be greater or equal to the
1536 maximum of the high limits of the ranges.
1537 (see also <ranges> parameter).
1538
Robert Tsai81ae1952007-12-05 10:47:29 +01001539 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001540
Willy Tarreaue8746a02018-11-12 08:45:00 +01001541 kern user mail daemon auth syslog lpr news
1542 uucp cron auth2 ftp ntp audit alert cron2
1543 local0 local1 local2 local3 local4 local5 local6 local7
1544
Willy Tarreauc1b06452018-11-12 11:57:56 +01001545 Note that the facility is ignored for the "short" and "raw"
1546 formats, but still required as a positional field. It is
1547 recommended to use "daemon" in this case to make it clear that
1548 it's only supposed to be used locally.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001549
1550 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001551 all messages are sent. If a maximum level is specified, only messages with a
1552 severity at least as important as this level will be sent. An optional minimum
1553 level can be specified. If it is set, logs emitted with a more severe level
1554 than this one will be capped to this level. This is used to avoid sending
1555 "emerg" messages on all terminals on some default syslog configurations.
1556 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001557
Cyril Bontédc4d9032012-04-08 21:57:39 +02001558 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +02001559
Joe Williamsdf5b38f2010-12-29 17:05:48 +01001560log-send-hostname [<string>]
1561 Sets the hostname field in the syslog header. If optional "string" parameter
1562 is set the header is set to the string contents, otherwise uses the hostname
1563 of the system. Generally used if one is not relaying logs through an
1564 intermediate syslog server or for simply customizing the hostname printed in
1565 the logs.
1566
Kevinm48936af2010-12-22 16:08:21 +00001567log-tag <string>
1568 Sets the tag field in the syslog header to this string. It defaults to the
1569 program name as launched from the command line, which usually is "haproxy".
1570 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +01001571 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +00001572
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001573lua-load <file>
Thierry Fournier59f11be2020-11-29 00:37:41 +01001574 This global directive loads and executes a Lua file in the shared context
1575 that is visible to all threads. Any variable set in such a context is visible
1576 from any thread. This is the easiest and recommended way to load Lua programs
1577 but it will not scale well if a lot of Lua calls are performed, as only one
1578 thread may be running on the global state at a time. A program loaded this
1579 way will always see 0 in the "core.thread" variable. This directive can be
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001580 used multiple times.
1581
Thierry Fournier59f11be2020-11-29 00:37:41 +01001582lua-load-per-thread <file>
1583 This global directive loads and executes a Lua file into each started thread.
1584 Any global variable has a thread-local visibility so that each thread could
1585 see a different value. As such it is strongly recommended not to use global
1586 variables in programs loaded this way. An independent copy is loaded and
1587 initialized for each thread, everything is done sequentially and in the
1588 thread's numeric order from 1 to nbthread. If some operations need to be
1589 performed only once, the program should check the "core.thread" variable to
1590 figure what thread is being initialized. Programs loaded this way will run
1591 concurrently on all threads and will be highly scalable. This is the
1592 recommended way to load simple functions that register sample-fetches,
1593 converters, actions or services once it is certain the program doesn't depend
1594 on global variables. For the sake of simplicity, the directive is available
1595 even if only one thread is used and even if threads are disabled (in which
1596 case it will be equivalent to lua-load). This directive can be used multiple
1597 times.
1598
Tim Duesterhusdd74b5f2020-01-12 13:55:40 +01001599lua-prepend-path <string> [<type>]
1600 Prepends the given string followed by a semicolon to Lua's package.<type>
1601 variable.
1602 <type> must either be "path" or "cpath". If <type> is not given it defaults
1603 to "path".
1604
1605 Lua's paths are semicolon delimited lists of patterns that specify how the
1606 `require` function attempts to find the source file of a library. Question
1607 marks (?) within a pattern will be replaced by module name. The path is
1608 evaluated left to right. This implies that paths that are prepended later
1609 will be checked earlier.
1610
1611 As an example by specifying the following path:
1612
1613 lua-prepend-path /usr/share/haproxy-lua/?/init.lua
1614 lua-prepend-path /usr/share/haproxy-lua/?.lua
1615
1616 When `require "example"` is being called Lua will first attempt to load the
1617 /usr/share/haproxy-lua/example.lua script, if that does not exist the
1618 /usr/share/haproxy-lua/example/init.lua will be attempted and the default
1619 paths if that does not exist either.
1620
1621 See https://www.lua.org/pil/8.1.html for the details within the Lua
1622 documentation.
1623
William Lallemand4cfede82017-11-24 22:02:34 +01001624master-worker [no-exit-on-failure]
William Lallemande202b1e2017-06-01 17:38:56 +02001625 Master-worker mode. It is equivalent to the command line "-W" argument.
1626 This mode will launch a "master" which will monitor the "workers". Using
1627 this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001628 the master. The master-worker mode is compatible either with the foreground
William Lallemande202b1e2017-06-01 17:38:56 +02001629 or daemon mode. It is recommended to use this mode with multiprocess and
1630 systemd.
William Lallemand4cfede82017-11-24 22:02:34 +01001631 By default, if a worker exits with a bad return code, in the case of a
1632 segfault for example, all workers will be killed, and the master will leave.
1633 It is convenient to combine this behavior with Restart=on-failure in a
1634 systemd unit file in order to relaunch the whole process. If you don't want
1635 this behavior, you must use the keyword "no-exit-on-failure".
William Lallemande202b1e2017-06-01 17:38:56 +02001636
William Lallemand4cfede82017-11-24 22:02:34 +01001637 See also "-W" in the management guide.
William Lallemande202b1e2017-06-01 17:38:56 +02001638
William Lallemand27edc4b2019-05-07 17:49:33 +02001639mworker-max-reloads <number>
1640 In master-worker mode, this option limits the number of time a worker can
John Roeslerfb2fce12019-07-10 15:45:51 -05001641 survive to a reload. If the worker did not leave after a reload, once its
William Lallemand27edc4b2019-05-07 17:49:33 +02001642 number of reloads is greater than this number, the worker will receive a
1643 SIGTERM. This option helps to keep under control the number of workers.
1644 See also "show proc" in the Management Guide.
1645
Willy Tarreauf42d7942020-10-20 11:54:49 +02001646nbproc <number> (deprecated)
Willy Tarreau6a06a402007-07-15 20:15:28 +02001647 Creates <number> processes when going daemon. This requires the "daemon"
1648 mode. By default, only one process is created, which is the recommended mode
1649 of operation. For systems limited to small sets of file descriptors per
Willy Tarreau149ab772019-01-26 14:27:06 +01001650 process, it may be needed to fork multiple daemons. When set to a value
1651 larger than 1, threads are automatically disabled. USING MULTIPLE PROCESSES
Willy Tarreauf42d7942020-10-20 11:54:49 +02001652 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. This directive is deprecated
1653 and scheduled for removal in 2.5. Please use "nbthread" instead. See also
1654 "daemon" and "nbthread".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001655
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001656nbthread <number>
1657 This setting is only available when support for threads was built in. It
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001658 makes HAProxy run on <number> threads. This is exclusive with "nbproc". While
Willy Tarreau26f6ae12019-02-02 12:56:15 +01001659 "nbproc" historically used to be the only way to use multiple processors, it
1660 also involved a number of shortcomings related to the lack of synchronization
1661 between processes (health-checks, peers, stick-tables, stats, ...) which do
1662 not affect threads. As such, any modern configuration is strongly encouraged
Willy Tarreau149ab772019-01-26 14:27:06 +01001663 to migrate away from "nbproc" to "nbthread". "nbthread" also works when
1664 HAProxy is started in foreground. On some platforms supporting CPU affinity,
1665 when nbproc is not used, the default "nbthread" value is automatically set to
1666 the number of CPUs the process is bound to upon startup. This means that the
1667 thread count can easily be adjusted from the calling process using commands
1668 like "taskset" or "cpuset". Otherwise, this value defaults to 1. The default
1669 value is reported in the output of "haproxy -vv". See also "nbproc".
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001670
Amaury Denoyelle0f50cb92021-03-26 18:50:33 +01001671numa-cpu-mapping
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001672 By default, if running on Linux, HAProxy inspects on startup the CPU topology
Amaury Denoyelle0f50cb92021-03-26 18:50:33 +01001673 of the machine. If a multi-socket machine is detected, the affinity is
1674 automatically calculated to run on the CPUs of a single node. This is done in
1675 order to not suffer from the performance penalties caused by the inter-socket
1676 bus latency. However, if the applied binding is non optimal on a particular
1677 architecture, it can be disabled with the statement 'no numa-cpu-mapping'.
1678 This automatic binding is also not applied if a nbthread statement is present
1679 in the configuration, or the affinity of the process is already specified,
1680 for example via the 'cpu-map' directive or the taskset utility.
1681
Willy Tarreau6a06a402007-07-15 20:15:28 +02001682pidfile <pidfile>
MIZUTA Takeshic32f3942020-08-26 13:46:19 +09001683 Writes PIDs of all daemons into file <pidfile> when daemon mode or writes PID
1684 of master process into file <pidfile> when master-worker mode. This option is
1685 equivalent to the "-p" command line argument. The file must be accessible to
1686 the user starting the process. See also "daemon" and "master-worker".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001687
Willy Tarreau119e50e2020-05-22 13:53:29 +02001688pp2-never-send-local
1689 A bug in the PROXY protocol v2 implementation was present in HAProxy up to
1690 version 2.1, causing it to emit a PROXY command instead of a LOCAL command
1691 for health checks. This is particularly minor but confuses some servers'
1692 logs. Sadly, the bug was discovered very late and revealed that some servers
1693 which possibly only tested their PROXY protocol implementation against
1694 HAProxy fail to properly handle the LOCAL command, and permanently remain in
1695 the "down" state when HAProxy checks them. When this happens, it is possible
1696 to enable this global option to revert to the older (bogus) behavior for the
1697 time it takes to contact the affected components' vendors and get them fixed.
1698 This option is disabled by default and acts on all servers having the
1699 "send-proxy-v2" statement.
1700
Willy Tarreau1d549722016-02-16 12:41:57 +01001701presetenv <name> <value>
1702 Sets environment variable <name> to value <value>. If the variable exists, it
1703 is NOT overwritten. The changes immediately take effect so that the next line
1704 in the configuration file sees the new value. See also "setenv", "resetenv",
1705 and "unsetenv".
1706
1707resetenv [<name> ...]
1708 Removes all environment variables except the ones specified in argument. It
1709 allows to use a clean controlled environment before setting new values with
1710 setenv or unsetenv. Please note that some internal functions may make use of
1711 some environment variables, such as time manipulation functions, but also
1712 OpenSSL or even external checks. This must be used with extreme care and only
1713 after complete validation. The changes immediately take effect so that the
1714 next line in the configuration file sees the new environment. See also
1715 "setenv", "presetenv", and "unsetenv".
1716
Christopher Fauletff4121f2017-11-22 16:38:49 +01001717stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +02001718 Limits the stats socket to a certain set of processes numbers. By default the
1719 stats socket is bound to all processes, causing a warning to be emitted when
1720 nbproc is greater than 1 because there is no way to select the target process
1721 when connecting. However, by using this setting, it becomes possible to pin
1722 the stats socket to a specific set of processes, typically the first one. The
1723 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001724 the number of processes used. The maximum process ID depends on the machine's
Christopher Fauletff4121f2017-11-22 16:38:49 +01001725 word size (32 or 64). Ranges can be partially defined. The higher bound can
1726 be omitted. In such case, it is replaced by the corresponding maximum
1727 value. A better option consists in using the "process" setting of the "stats
1728 socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +02001729
Baptiste Assmann5626f482015-08-23 10:00:10 +02001730server-state-base <directory>
1731 Specifies the directory prefix to be prepended in front of all servers state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001732 file names which do not start with a '/'. See also "server-state-file",
1733 "load-server-state-from-file" and "server-state-file-name".
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +02001734
1735server-state-file <file>
1736 Specifies the path to the file containing state of servers. If the path starts
1737 with a slash ('/'), it is considered absolute, otherwise it is considered
1738 relative to the directory specified using "server-state-base" (if set) or to
1739 the current directory. Before reloading HAProxy, it is possible to save the
1740 servers' current state using the stats command "show servers state". The
1741 output of this command must be written in the file pointed by <file>. When
1742 starting up, before handling traffic, HAProxy will read, load and apply state
1743 for each server found in the file and available in its current running
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001744 configuration. See also "server-state-base" and "show servers state",
1745 "load-server-state-from-file" and "server-state-file-name"
Baptiste Assmann5626f482015-08-23 10:00:10 +02001746
Willy Tarreau13d2ba22021-03-26 11:38:08 +01001747set-var <var-name> <expr>
1748 Sets the process-wide variable '<var-name>' to the result of the evaluation
1749 of the sample expression <expr>. The variable '<var-name>' may only be a
1750 process-wide variable (using the 'proc.' prefix). It works exactly like the
1751 'set-var' action in TCP or HTTP rules except that the expression is evaluated
1752 at configuration parsing time and that the variable is instantly set. The
1753 sample fetch functions and converters permitted in the expression are only
1754 those using internal data, typically 'int(value)' or 'str(value)'. It's is
1755 possible to reference previously allocated variables as well. These variables
1756 will then be readable (and modifiable) from the regular rule sets.
1757
1758 Example:
1759 global
1760 set-var proc.current_state str(primary)
1761 set-var proc.prio int(100)
1762 set-var proc.threshold int(200),sub(proc.prio)
1763
Willy Tarreau1d549722016-02-16 12:41:57 +01001764setenv <name> <value>
1765 Sets environment variable <name> to value <value>. If the variable exists, it
1766 is overwritten. The changes immediately take effect so that the next line in
1767 the configuration file sees the new value. See also "presetenv", "resetenv",
1768 and "unsetenv".
1769
Willy Tarreau636848a2019-04-15 19:38:50 +02001770set-dumpable
1771 This option is better left disabled by default and enabled only upon a
William Dauchyec730982019-10-27 20:08:10 +01001772 developer's request. If it has been enabled, it may still be forcibly
1773 disabled by prefixing it with the "no" keyword. It has no impact on
1774 performance nor stability but will try hard to re-enable core dumps that were
1775 possibly disabled by file size limitations (ulimit -f), core size limitations
1776 (ulimit -c), or "dumpability" of a process after changing its UID/GID (such
1777 as /proc/sys/fs/suid_dumpable on Linux). Core dumps might still be limited by
1778 the current directory's permissions (check what directory the file is started
1779 from), the chroot directory's permission (it may be needed to temporarily
1780 disable the chroot directive or to move it to a dedicated writable location),
1781 or any other system-specific constraint. For example, some Linux flavours are
1782 notorious for replacing the default core file with a path to an executable
1783 not even installed on the system (check /proc/sys/kernel/core_pattern). Often,
1784 simply writing "core", "core.%p" or "/var/log/core/core.%p" addresses the
1785 issue. When trying to enable this option waiting for a rare issue to
1786 re-appear, it's often a good idea to first try to obtain such a dump by
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001787 issuing, for example, "kill -11" to the "haproxy" process and verify that it
William Dauchyec730982019-10-27 20:08:10 +01001788 leaves a core where expected when dying.
Willy Tarreau636848a2019-04-15 19:38:50 +02001789
Willy Tarreau610f04b2014-02-13 11:36:41 +01001790ssl-default-bind-ciphers <ciphers>
1791 This setting is only available when support for OpenSSL was built in. It sets
1792 the default string describing the list of cipher algorithms ("cipher suite")
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001793 that are negotiated during the SSL/TLS handshake up to TLSv1.2 for all
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001794 "bind" lines which do not explicitly define theirs. The format of the string
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001795 is defined in "man 1 ciphers" from OpenSSL man pages. For background
1796 information and recommendations see e.g.
1797 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1798 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
1799 cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword.
1800 Please check the "bind" keyword for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001801
1802ssl-default-bind-ciphersuites <ciphersuites>
1803 This setting is only available when support for OpenSSL was built in and
1804 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
1805 describing the list of cipher algorithms ("cipher suite") that are negotiated
1806 during the TLSv1.3 handshake for all "bind" lines which do not explicitly define
1807 theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001808 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1809 cipher configuration for TLSv1.2 and earlier, please check the
1810 "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001811 information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001812
Jerome Magninb203ff62020-04-03 15:28:22 +02001813ssl-default-bind-curves <curves>
1814 This setting is only available when support for OpenSSL was built in. It sets
1815 the default string describing the list of elliptic curves algorithms ("curve
1816 suite") that are negotiated during the SSL/TLS handshake with ECDHE. The format
1817 of the string is a colon-delimited list of curve name.
1818 Please check the "bind" keyword for more information.
1819
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001820ssl-default-bind-options [<option>]...
1821 This setting is only available when support for OpenSSL was built in. It sets
1822 default ssl-options to force on all "bind" lines. Please check the "bind"
1823 keyword to see available options.
1824
1825 Example:
1826 global
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +02001827 ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001828
Willy Tarreau610f04b2014-02-13 11:36:41 +01001829ssl-default-server-ciphers <ciphers>
1830 This setting is only available when support for OpenSSL was built in. It
1831 sets the default string describing the list of cipher algorithms that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001832 negotiated during the SSL/TLS handshake up to TLSv1.2 with the server,
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001833 for all "server" lines which do not explicitly define theirs. The format of
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001834 the string is defined in "man 1 ciphers" from OpenSSL man pages. For background
1835 information and recommendations see e.g.
1836 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1837 (https://mozilla.github.io/server-side-tls/ssl-config-generator/).
1838 For TLSv1.3 cipher configuration, please check the
1839 "ssl-default-server-ciphersuites" keyword. Please check the "server" keyword
1840 for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001841
1842ssl-default-server-ciphersuites <ciphersuites>
1843 This setting is only available when support for OpenSSL was built in and
1844 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
1845 string describing the list of cipher algorithms that are negotiated during
1846 the TLSv1.3 handshake with the server, for all "server" lines which do not
1847 explicitly define theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001848 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1849 cipher configuration for TLSv1.2 and earlier, please check the
1850 "ssl-default-server-ciphers" keyword. Please check the "server" keyword for
1851 more information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001852
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001853ssl-default-server-options [<option>]...
1854 This setting is only available when support for OpenSSL was built in. It sets
1855 default ssl-options to force on all "server" lines. Please check the "server"
1856 keyword to see available options.
1857
Remi Gacogne47783ef2015-05-29 15:53:22 +02001858ssl-dh-param-file <file>
1859 This setting is only available when support for OpenSSL was built in. It sets
1860 the default DH parameters that are used during the SSL/TLS handshake when
1861 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
Davor Ocelice9ed2812017-12-25 17:49:28 +01001862 which do not explicitly define theirs. It will be overridden by custom DH
Remi Gacogne47783ef2015-05-29 15:53:22 +02001863 parameters found in a bind certificate file if any. If custom DH parameters
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001864 are not specified either by using ssl-dh-param-file or by setting them
1865 directly in the certificate file, pre-generated DH parameters of the size
1866 specified by tune.ssl.default-dh-param will be used. Custom parameters are
1867 known to be more secure and therefore their use is recommended.
Remi Gacogne47783ef2015-05-29 15:53:22 +02001868 Custom DH parameters may be generated by using the OpenSSL command
1869 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
1870 parameters should not be considered secure anymore.
1871
William Lallemand8e8581e2020-10-20 17:36:46 +02001872ssl-load-extra-del-ext
1873 This setting allows to configure the way HAProxy does the lookup for the
1874 extra SSL files. By default HAProxy adds a new extension to the filename.
William Lallemand089c1382020-10-23 17:35:12 +02001875 (ex: with "foobar.crt" load "foobar.crt.key"). With this option enabled,
William Lallemand8e8581e2020-10-20 17:36:46 +02001876 HAProxy removes the extension before adding the new one (ex: with
William Lallemand089c1382020-10-23 17:35:12 +02001877 "foobar.crt" load "foobar.key").
1878
1879 Your crt file must have a ".crt" extension for this option to work.
William Lallemand8e8581e2020-10-20 17:36:46 +02001880
1881 This option is not compatible with bundle extensions (.ecdsa, .rsa. .dsa)
1882 and won't try to remove them.
1883
1884 This option is disabled by default. See also "ssl-load-extra-files".
1885
William Lallemand4c5adbf2020-02-24 14:23:22 +01001886ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*
William Lallemand3af48e72020-02-03 17:15:52 +01001887 This setting alters the way HAProxy will look for unspecified files during
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001888 the loading of the SSL certificates. This option applies to certificates
1889 associated to "bind" lines as well as "server" lines but some of the extra
1890 files will not have any functional impact for "server" line certificates.
William Lallemand3af48e72020-02-03 17:15:52 +01001891
1892 By default, HAProxy discovers automatically a lot of files not specified in
1893 the configuration, and you may want to disable this behavior if you want to
1894 optimize the startup time.
1895
1896 "none": Only load the files specified in the configuration. Don't try to load
1897 a certificate bundle if the file does not exist. In the case of a directory,
1898 it won't try to bundle the certificates if they have the same basename.
1899
1900 "all": This is the default behavior, it will try to load everything,
William Lallemand4c5adbf2020-02-24 14:23:22 +01001901 bundles, sctl, ocsp, issuer, key.
William Lallemand3af48e72020-02-03 17:15:52 +01001902
1903 "bundle": When a file specified in the configuration does not exist, HAProxy
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001904 will try to load a "cert bundle". Certificate bundles are only managed on the
1905 frontend side and will not work for backend certificates.
William Lallemandf9ff3ec2020-10-02 17:57:44 +02001906
1907 Starting from HAProxy 2.3, the bundles are not loaded in the same OpenSSL
1908 certificate store, instead it will loads each certificate in a separate
1909 store which is equivalent to declaring multiple "crt". OpenSSL 1.1.1 is
1910 required to achieve this. Which means that bundles are now used only for
1911 backward compatibility and are not mandatory anymore to do an hybrid RSA/ECC
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001912 bind configuration.
William Lallemandf9ff3ec2020-10-02 17:57:44 +02001913
1914 To associate these PEM files into a "cert bundle" that is recognized by
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001915 HAProxy, they must be named in the following way: All PEM files that are to
William Lallemandf9ff3ec2020-10-02 17:57:44 +02001916 be bundled must have the same base name, with a suffix indicating the key
1917 type. Currently, three suffixes are supported: rsa, dsa and ecdsa. For
1918 example, if www.example.com has two PEM files, an RSA file and an ECDSA
1919 file, they must be named: "example.pem.rsa" and "example.pem.ecdsa". The
1920 first part of the filename is arbitrary; only the suffix matters. To load
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001921 this bundle into HAProxy, specify the base name only:
William Lallemandf9ff3ec2020-10-02 17:57:44 +02001922
1923 Example : bind :8443 ssl crt example.pem
1924
Daniel Corbett9f0843f2021-05-08 10:50:37 -04001925 Note that the suffix is not given to HAProxy; this tells HAProxy to look for
William Lallemandf9ff3ec2020-10-02 17:57:44 +02001926 a cert bundle.
1927
1928 HAProxy will load all PEM files in the bundle as if they were configured
1929 separately in several "crt".
1930
1931 The bundle loading does not have an impact anymore on the directory loading
1932 since files are loading separately.
1933
1934 On the CLI, bundles are seen as separate files, and the bundle extension is
1935 required to commit them.
1936
William Dauchy57dd6f12020-10-06 15:22:37 +02001937 OCSP files (.ocsp), issuer files (.issuer), Certificate Transparency (.sctl)
William Lallemandf9ff3ec2020-10-02 17:57:44 +02001938 as well as private keys (.key) are supported with multi-cert bundling.
William Lallemand3af48e72020-02-03 17:15:52 +01001939
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001940 "sctl": Try to load "<basename>.sctl" for each crt keyword. If provided for
1941 a backend certificate, it will be loaded but will not have any functional
1942 impact.
William Lallemand3af48e72020-02-03 17:15:52 +01001943
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001944 "ocsp": Try to load "<basename>.ocsp" for each crt keyword. If provided for
1945 a backend certificate, it will be loaded but will not have any functional
1946 impact.
William Lallemand3af48e72020-02-03 17:15:52 +01001947
1948 "issuer": Try to load "<basename>.issuer" if the issuer of the OCSP file is
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001949 not provided in the PEM file. If provided for a backend certificate, it will
1950 be loaded but will not have any functional impact.
William Lallemand3af48e72020-02-03 17:15:52 +01001951
William Lallemand4c5adbf2020-02-24 14:23:22 +01001952 "key": If the private key was not provided by the PEM file, try to load a
1953 file "<basename>.key" containing a private key.
1954
William Lallemand3af48e72020-02-03 17:15:52 +01001955 The default behavior is "all".
1956
1957 Example:
1958 ssl-load-extra-files bundle sctl
1959 ssl-load-extra-files sctl ocsp issuer
1960 ssl-load-extra-files none
1961
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +02001962 See also: "crt", section 5.1 about bind options and section 5.2 about server
1963 options.
William Lallemand3af48e72020-02-03 17:15:52 +01001964
Emeric Brun850efd52014-01-29 12:24:34 +01001965ssl-server-verify [none|required]
1966 The default behavior for SSL verify on servers side. If specified to 'none',
1967 servers certificates are not verified. The default is 'required' except if
1968 forced using cmdline option '-dV'.
1969
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001970ssl-skip-self-issued-ca
Daniel Corbett67a82712020-07-06 23:01:19 -04001971 Self issued CA, aka x509 root CA, is the anchor for chain validation: as a
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001972 server is useless to send it, client must have it. Standard configuration
1973 need to not include such CA in PEM file. This option allows you to keep such
1974 CA in PEM file without sending it to the client. Use case is to provide
1975 issuer for ocsp without the need for '.issuer' file and be able to share it
1976 with 'issuers-chain-path'. This concerns all certificates without intermediate
1977 certificates. It's useless for BoringSSL, .issuer is ignored because ocsp
William Lallemand9a1d8392020-08-10 17:28:23 +02001978 bits does not need it. Requires at least OpenSSL 1.0.2.
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001979
Willy Tarreauabb175f2012-09-24 12:43:26 +02001980stats socket [<address:port>|<path>] [param*]
1981 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
1982 Connections to this socket will return various statistics outputs and even
1983 allow some commands to be issued to change some runtime settings. Please
Willy Tarreau1af20c72017-06-23 16:01:14 +02001984 consult section 9.3 "Unix Socket commands" of Management Guide for more
Kevin Decherf949c7202015-10-13 23:26:44 +02001985 details.
Willy Tarreau6162db22009-10-10 17:13:00 +02001986
Willy Tarreauabb175f2012-09-24 12:43:26 +02001987 All parameters supported by "bind" lines are supported, for instance to
1988 restrict access to some users or their access rights. Please consult
1989 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001990
1991stats timeout <timeout, in milliseconds>
1992 The default timeout on the stats socket is set to 10 seconds. It is possible
1993 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +01001994 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001995
1996stats maxconn <connections>
1997 By default, the stats socket is limited to 10 concurrent connections. It is
1998 possible to change this value with "stats maxconn".
1999
Willy Tarreau6a06a402007-07-15 20:15:28 +02002000uid <number>
Thayne McCombscdbcca92021-01-07 21:24:41 -07002001 Changes the process's user ID to <number>. It is recommended that the user ID
Willy Tarreau6a06a402007-07-15 20:15:28 +02002002 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
2003 be started with superuser privileges in order to be able to switch to another
2004 one. See also "gid" and "user".
2005
2006ulimit-n <number>
2007 Sets the maximum number of per-process file-descriptors to <number>. By
2008 default, it is automatically computed, so it is recommended not to use this
2009 option.
2010
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002011unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
2012 [ group <group> ] [ gid <gid> ]
2013
2014 Fixes common settings to UNIX listening sockets declared in "bind" statements.
2015 This is mainly used to simplify declaration of those UNIX sockets and reduce
2016 the risk of errors, since those settings are most commonly required but are
2017 also process-specific. The <prefix> setting can be used to force all socket
2018 path to be relative to that directory. This might be needed to access another
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002019 component's chroot. Note that those paths are resolved before HAProxy chroots
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002020 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
2021 all have the same meaning as their homonyms used by the "bind" statement. If
2022 both are specified, the "bind" statement has priority, meaning that the
2023 "unix-bind" settings may be seen as process-wide default settings.
2024
Willy Tarreau1d549722016-02-16 12:41:57 +01002025unsetenv [<name> ...]
2026 Removes environment variables specified in arguments. This can be useful to
2027 hide some sensitive information that are occasionally inherited from the
2028 user's environment during some operations. Variables which did not exist are
2029 silently ignored so that after the operation, it is certain that none of
2030 these variables remain. The changes immediately take effect so that the next
2031 line in the configuration file will not see these variables. See also
2032 "setenv", "presetenv", and "resetenv".
2033
Willy Tarreau6a06a402007-07-15 20:15:28 +02002034user <user name>
2035 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
2036 See also "uid" and "group".
2037
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02002038node <name>
2039 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
2040
2041 This statement is useful in HA configurations where two or more processes or
2042 servers share the same IP address. By setting a different node-name on all
2043 nodes, it becomes easy to immediately spot what server is handling the
2044 traffic.
2045
2046description <text>
2047 Add a text that describes the instance.
2048
2049 Please note that it is required to escape certain characters (# for example)
2050 and this text is inserted into a html page so you should avoid using
2051 "<" and ">" characters.
2052
Thomas Holmesdb04f192015-05-18 13:21:39 +0100205351degrees-data-file <file path>
2054 The path of the 51Degrees data file to provide device detection services. The
Davor Ocelice9ed2812017-12-25 17:49:28 +01002055 file should be unzipped and accessible by HAProxy with relevant permissions.
Thomas Holmesdb04f192015-05-18 13:21:39 +01002056
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002057 Please note that this option is only available when HAProxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01002058 compiled with USE_51DEGREES.
2059
Ben Shillitof25e8e52016-12-02 14:25:37 +0000206051degrees-property-name-list [<string> ...]
Thomas Holmesdb04f192015-05-18 13:21:39 +01002061 A list of 51Degrees property names to be load from the dataset. A full list
2062 of names is available on the 51Degrees website:
2063 https://51degrees.com/resources/property-dictionary
2064
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002065 Please note that this option is only available when HAProxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01002066 compiled with USE_51DEGREES.
2067
Dragan Dosen93b38d92015-06-29 16:43:25 +0200206851degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +01002069 A char that will be appended to every property value in a response header
2070 containing 51Degrees results. If not set that will be set as ','.
2071
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002072 Please note that this option is only available when HAProxy has been
Dragan Dosenae6d39a2015-06-29 16:43:27 +02002073 compiled with USE_51DEGREES.
2074
207551degrees-cache-size <number>
2076 Sets the size of the 51Degrees converter cache to <number> entries. This
2077 is an LRU cache which reminds previous device detections and their results.
2078 By default, this cache is disabled.
2079
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002080 Please note that this option is only available when HAProxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01002081 compiled with USE_51DEGREES.
2082
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002083wurfl-data-file <file path>
2084 The path of the WURFL data file to provide device detection services. The
2085 file should be accessible by HAProxy with relevant permissions.
2086
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002087 Please note that this option is only available when HAProxy has been compiled
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002088 with USE_WURFL=1.
2089
2090wurfl-information-list [<capability>]*
2091 A space-delimited list of WURFL capabilities, virtual capabilities, property
2092 names we plan to use in injected headers. A full list of capability and
2093 virtual capability names is available on the Scientiamobile website :
2094
2095 https://www.scientiamobile.com/wurflCapability
2096
2097 Valid WURFL properties are:
2098 - wurfl_id Contains the device ID of the matched device.
2099
2100 - wurfl_root_id Contains the device root ID of the matched
2101 device.
2102
2103 - wurfl_isdevroot Tells if the matched device is a root device.
2104 Possible values are "TRUE" or "FALSE".
2105
2106 - wurfl_useragent The original useragent coming with this
2107 particular web request.
2108
2109 - wurfl_api_version Contains a string representing the currently
2110 used Libwurfl API version.
2111
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002112 - wurfl_info A string containing information on the parsed
2113 wurfl.xml and its full path.
2114
2115 - wurfl_last_load_time Contains the UNIX timestamp of the last time
2116 WURFL has been loaded successfully.
2117
2118 - wurfl_normalized_useragent The normalized useragent.
2119
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002120 Please note that this option is only available when HAProxy has been compiled
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002121 with USE_WURFL=1.
2122
2123wurfl-information-list-separator <char>
2124 A char that will be used to separate values in a response header containing
2125 WURFL results. If not set that a comma (',') will be used by default.
2126
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002127 Please note that this option is only available when HAProxy has been compiled
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002128 with USE_WURFL=1.
2129
2130wurfl-patch-file [<file path>]
2131 A list of WURFL patch file paths. Note that patches are loaded during startup
2132 thus before the chroot.
2133
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002134 Please note that this option is only available when HAProxy has been compiled
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002135 with USE_WURFL=1.
2136
paulborilebad132c2019-04-18 11:57:04 +02002137wurfl-cache-size <size>
2138 Sets the WURFL Useragent cache size. For faster lookups, already processed user
2139 agents are kept in a LRU cache :
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002140 - "0" : no cache is used.
paulborilebad132c2019-04-18 11:57:04 +02002141 - <size> : size of lru cache in elements.
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002142
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002143 Please note that this option is only available when HAProxy has been compiled
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02002144 with USE_WURFL=1.
2145
William Dauchy0fec3ab2019-10-27 20:08:11 +01002146strict-limits
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002147 Makes process fail at startup when a setrlimit fails. HAProxy tries to set the
William Dauchya5194602020-03-28 19:29:58 +01002148 best setrlimit according to what has been calculated. If it fails, it will
2149 emit a warning. This option is here to guarantee an explicit failure of
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002150 HAProxy when those limits fail. It is enabled by default. It may still be
William Dauchya5194602020-03-28 19:29:58 +01002151 forcibly disabled by prefixing it with the "no" keyword.
William Dauchy0fec3ab2019-10-27 20:08:11 +01002152
Willy Tarreauc57f0e22009-05-10 13:12:33 +020021533.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +02002154-----------------------
2155
Willy Tarreaubeb859a2018-11-22 18:07:59 +01002156busy-polling
2157 In some situations, especially when dealing with low latency on processors
2158 supporting a variable frequency or when running inside virtual machines, each
2159 time the process waits for an I/O using the poller, the processor goes back
2160 to sleep or is offered to another VM for a long time, and it causes
2161 excessively high latencies. This option provides a solution preventing the
2162 processor from sleeping by always using a null timeout on the pollers. This
2163 results in a significant latency reduction (30 to 100 microseconds observed)
2164 at the expense of a risk to overheat the processor. It may even be used with
2165 threads, in which case improperly bound threads may heavily conflict,
2166 resulting in a worse performance and high values for the CPU stolen fields
2167 in "show info" output, indicating which threads are misconfigured. It is
2168 important not to let the process run on the same processor as the network
2169 interrupts when this option is used. It is also better to avoid using it on
2170 multiple CPU threads sharing the same core. This option is disabled by
2171 default. If it has been enabled, it may still be forcibly disabled by
2172 prefixing it with the "no" keyword. It is ignored by the "select" and
2173 "poll" pollers.
2174
William Dauchy3894d972019-12-28 15:36:02 +01002175 This option is automatically disabled on old processes in the context of
2176 seamless reload; it avoids too much cpu conflicts when multiple processes
2177 stay around for some time waiting for the end of their current connections.
2178
Willy Tarreau1746eec2014-04-25 10:46:47 +02002179max-spread-checks <delay in milliseconds>
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002180 By default, HAProxy tries to spread the start of health checks across the
Willy Tarreau1746eec2014-04-25 10:46:47 +02002181 smallest health check interval of all the servers in a farm. The principle is
2182 to avoid hammering services running on the same server. But when using large
2183 check intervals (10 seconds or more), the last servers in the farm take some
2184 time before starting to be tested, which can be a problem. This parameter is
2185 used to enforce an upper bound on delay between the first and the last check,
2186 even if the servers' check intervals are larger. When servers run with
2187 shorter intervals, their intervals will be respected though.
2188
Willy Tarreau6a06a402007-07-15 20:15:28 +02002189maxconn <number>
2190 Sets the maximum per-process number of concurrent connections to <number>. It
2191 is equivalent to the command-line argument "-n". Proxies will stop accepting
2192 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +02002193 automatically adjusted according to this value. See also "ulimit-n". Note:
2194 the "select" poller cannot reliably use more than 1024 file descriptors on
2195 some platforms. If your platform only supports select and reports "select
2196 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaub28f3442019-03-04 08:13:43 +01002197 below 500 in general). If this value is not set, it will automatically be
2198 calculated based on the current file descriptors limit reported by the
2199 "ulimit -n" command, possibly reduced to a lower value if a memory limit
2200 is enforced, based on the buffer size, memory allocated to compression, SSL
2201 cache size, and use or not of SSL and the associated maxsslconn (which can
2202 also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +02002203
Willy Tarreau81c25d02011-09-07 15:17:21 +02002204maxconnrate <number>
2205 Sets the maximum per-process number of connections per second to <number>.
2206 Proxies will stop accepting connections when this limit is reached. It can be
2207 used to limit the global capacity regardless of each frontend capacity. It is
2208 important to note that this can only be used as a service protection measure,
2209 as there will not necessarily be a fair share between frontends when the
2210 limit is reached, so it's a good idea to also limit each frontend to some
2211 value close to its expected share. Also, lowering tune.maxaccept can improve
2212 fairness.
2213
William Lallemandd85f9172012-11-09 17:05:39 +01002214maxcomprate <number>
2215 Sets the maximum per-process input compression rate to <number> kilobytes
Davor Ocelice9ed2812017-12-25 17:49:28 +01002216 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +01002217 level will be decreased during the session. If the maximum is reached at the
2218 beginning of a session, the session will not compress at all. If the maximum
2219 is not reached, the compression level will be increased up to
Davor Ocelice9ed2812017-12-25 17:49:28 +01002220 tune.comp.maxlevel. A value of zero means there is no limit, this is the
William Lallemandd85f9172012-11-09 17:05:39 +01002221 default value.
2222
William Lallemand072a2bf2012-11-20 17:01:01 +01002223maxcompcpuusage <number>
2224 Sets the maximum CPU usage HAProxy can reach before stopping the compression
2225 for new requests or decreasing the compression level of current requests.
2226 It works like 'maxcomprate' but measures CPU usage instead of incoming data
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002227 bandwidth. The value is expressed in percent of the CPU used by HAProxy. In
William Lallemand072a2bf2012-11-20 17:01:01 +01002228 case of multiple processes (nbproc > 1), each process manages its individual
2229 usage. A value of 100 disable the limit. The default value is 100. Setting
2230 a lower value will prevent the compression work from slowing the whole
2231 process down and from introducing high latencies.
2232
Willy Tarreauff4f82d2009-02-06 11:28:13 +01002233maxpipes <number>
2234 Sets the maximum per-process number of pipes to <number>. Currently, pipes
2235 are only used by kernel-based tcp splicing. Since a pipe contains two file
2236 descriptors, the "ulimit-n" value will be increased accordingly. The default
2237 value is maxconn/4, which seems to be more than enough for most heavy usages.
2238 The splice code dynamically allocates and releases pipes, and can fall back
2239 to standard copy, so setting this value too low may only impact performance.
2240
Willy Tarreau93e7c002013-10-07 18:51:07 +02002241maxsessrate <number>
2242 Sets the maximum per-process number of sessions per second to <number>.
2243 Proxies will stop accepting connections when this limit is reached. It can be
2244 used to limit the global capacity regardless of each frontend capacity. It is
2245 important to note that this can only be used as a service protection measure,
2246 as there will not necessarily be a fair share between frontends when the
2247 limit is reached, so it's a good idea to also limit each frontend to some
2248 value close to its expected share. Also, lowering tune.maxaccept can improve
2249 fairness.
2250
Willy Tarreau403edff2012-09-06 11:58:37 +02002251maxsslconn <number>
2252 Sets the maximum per-process number of concurrent SSL connections to
2253 <number>. By default there is no SSL-specific limit, which means that the
2254 global maxconn setting will apply to all connections. Setting this limit
2255 avoids having openssl use too much memory and crash when malloc returns NULL
2256 (since it unfortunately does not reliably check for such conditions). Note
2257 that the limit applies both to incoming and outgoing connections, so one
2258 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +01002259 If this value is not set, but a memory limit is enforced, this value will be
2260 automatically computed based on the memory limit, maxconn, the buffer size,
2261 memory allocated to compression, SSL cache size, and use of SSL in either
2262 frontends, backends or both. If neither maxconn nor maxsslconn are specified
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002263 when there is a memory limit, HAProxy will automatically adjust these values
Willy Tarreaud0256482015-01-15 21:45:22 +01002264 so that 100% of the connections can be made over SSL with no risk, and will
2265 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +02002266
Willy Tarreaue43d5322013-10-07 20:01:52 +02002267maxsslrate <number>
2268 Sets the maximum per-process number of SSL sessions per second to <number>.
2269 SSL listeners will stop accepting connections when this limit is reached. It
2270 can be used to limit the global SSL CPU usage regardless of each frontend
2271 capacity. It is important to note that this can only be used as a service
2272 protection measure, as there will not necessarily be a fair share between
2273 frontends when the limit is reached, so it's a good idea to also limit each
2274 frontend to some value close to its expected share. It is also important to
2275 note that the sessions are accounted before they enter the SSL stack and not
2276 after, which also protects the stack against bad handshakes. Also, lowering
2277 tune.maxaccept can improve fairness.
2278
William Lallemand9d5f5482012-11-07 16:12:57 +01002279maxzlibmem <number>
2280 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
2281 When the maximum amount is reached, future sessions will not compress as long
2282 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01002283 The default value is 0. The value is available in bytes on the UNIX socket
2284 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
2285 "ZlibMemUsage" in bytes.
2286
Willy Tarreau6a06a402007-07-15 20:15:28 +02002287noepoll
2288 Disables the use of the "epoll" event polling system on Linux. It is
2289 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01002290 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02002291
2292nokqueue
2293 Disables the use of the "kqueue" event polling system on BSD. It is
2294 equivalent to the command-line argument "-dk". The next polling system
2295 used will generally be "poll". See also "nopoll".
2296
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00002297noevports
2298 Disables the use of the event ports event polling system on SunOS systems
2299 derived from Solaris 10 and later. It is equivalent to the command-line
2300 argument "-dv". The next polling system used will generally be "poll". See
2301 also "nopoll".
2302
Willy Tarreau6a06a402007-07-15 20:15:28 +02002303nopoll
2304 Disables the use of the "poll" event polling system. It is equivalent to the
2305 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002306 It should never be needed to disable "poll" since it's available on all
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00002307 platforms supported by HAProxy. See also "nokqueue", "noepoll" and
2308 "noevports".
Willy Tarreau6a06a402007-07-15 20:15:28 +02002309
Willy Tarreauff4f82d2009-02-06 11:28:13 +01002310nosplice
2311 Disables the use of kernel tcp splicing between sockets on Linux. It is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002312 equivalent to the command line argument "-dS". Data will then be copied
Willy Tarreauff4f82d2009-02-06 11:28:13 +01002313 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002314 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01002315 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
2316 be used. This option makes it easier to globally disable kernel splicing in
2317 case of doubt. See also "option splice-auto", "option splice-request" and
2318 "option splice-response".
2319
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002320nogetaddrinfo
2321 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
2322 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
2323
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00002324noreuseport
2325 Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the
2326 command line argument "-dR".
2327
Willy Tarreauca3afc22021-05-05 18:33:19 +02002328profiling.memory { on | off }
2329 Enables ('on') or disables ('off') per-function memory profiling. This will
2330 keep usage statistics of malloc/calloc/realloc/free calls anywhere in the
2331 process (including libraries) which will be reported on the CLI using the
2332 "show profiling" command. This is essentially meant to be used when an
2333 abnormal memory usage is observed that cannot be explained by the pools and
2334 other info are required. The performance hit will typically be around 1%,
2335 maybe a bit more on highly threaded machines, so it is normally suitable for
2336 use in production. The same may be achieved at run time on the CLI using the
2337 "set profiling memory" command, please consult the management manual.
2338
Willy Tarreaud2d33482019-04-25 17:09:07 +02002339profiling.tasks { auto | on | off }
2340 Enables ('on') or disables ('off') per-task CPU profiling. When set to 'auto'
2341 the profiling automatically turns on a thread when it starts to suffer from
2342 an average latency of 1000 microseconds or higher as reported in the
2343 "avg_loop_us" activity field, and automatically turns off when the latency
John Roeslerfb2fce12019-07-10 15:45:51 -05002344 returns below 990 microseconds (this value is an average over the last 1024
Willy Tarreaud2d33482019-04-25 17:09:07 +02002345 loops so it does not vary quickly and tends to significantly smooth short
2346 spikes). It may also spontaneously trigger from time to time on overloaded
2347 systems, containers, or virtual machines, or when the system swaps (which
2348 must absolutely never happen on a load balancer).
2349
2350 CPU profiling per task can be very convenient to report where the time is
2351 spent and which requests have what effect on which other request. Enabling
2352 it will typically affect the overall's performance by less than 1%, thus it
2353 is recommended to leave it to the default 'auto' value so that it only
2354 operates when a problem is identified. This feature requires a system
Willy Tarreau75c62c22018-11-22 11:02:09 +01002355 supporting the clock_gettime(2) syscall with clock identifiers
2356 CLOCK_MONOTONIC and CLOCK_THREAD_CPUTIME_ID, otherwise the reported time will
2357 be zero. This option may be changed at run time using "set profiling" on the
2358 CLI.
2359
Willy Tarreaufe255b72007-10-14 23:09:26 +02002360spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09002361 Sometimes it is desirable to avoid sending agent and health checks to
2362 servers at exact intervals, for instance when many logical servers are
2363 located on the same physical server. With the help of this parameter, it
2364 becomes possible to add some randomness in the check interval between 0
2365 and +/- 50%. A value between 2 and 5 seems to show good results. The
2366 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02002367
Davor Ocelice9ed2812017-12-25 17:49:28 +01002368ssl-engine <name> [algo <comma-separated list of algorithms>]
Grant Zhang872f9c22017-01-21 01:10:18 +00002369 Sets the OpenSSL engine to <name>. List of valid values for <name> may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01002370 obtained using the command "openssl engine". This statement may be used
Grant Zhang872f9c22017-01-21 01:10:18 +00002371 multiple times, it will simply enable multiple crypto engines. Referencing an
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002372 unsupported engine will prevent HAProxy from starting. Note that many engines
Grant Zhang872f9c22017-01-21 01:10:18 +00002373 will lead to lower HTTPS performance than pure software with recent
2374 processors. The optional command "algo" sets the default algorithms an ENGINE
2375 will supply using the OPENSSL function ENGINE_set_default_string(). A value
Davor Ocelice9ed2812017-12-25 17:49:28 +01002376 of "ALL" uses the engine for all cryptographic operations. If no list of
2377 algo is specified then the value of "ALL" is used. A comma-separated list
Grant Zhang872f9c22017-01-21 01:10:18 +00002378 of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND,
2379 CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that
2380 openssl configuration file uses:
2381 https://www.openssl.org/docs/man1.0.2/apps/config.html
2382
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00002383ssl-mode-async
2384 Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS
Emeric Brun3854e012017-05-17 20:42:48 +02002385 I/O operations if asynchronous capable SSL engines are used. The current
Emeric Brunb5e42a82017-06-06 12:35:14 +00002386 implementation supports a maximum of 32 engines. The Openssl ASYNC API
2387 doesn't support moving read/write buffers and is not compliant with
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002388 HAProxy's buffer management. So the asynchronous mode is disabled on
John Roeslerfb2fce12019-07-10 15:45:51 -05002389 read/write operations (it is only enabled during initial and renegotiation
Emeric Brunb5e42a82017-06-06 12:35:14 +00002390 handshakes).
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00002391
Willy Tarreau33cb0652014-12-23 22:52:37 +01002392tune.buffers.limit <number>
2393 Sets a hard limit on the number of buffers which may be allocated per process.
2394 The default value is zero which means unlimited. The minimum non-zero value
2395 will always be greater than "tune.buffers.reserve" and should ideally always
2396 be about twice as large. Forcing this value can be particularly useful to
2397 limit the amount of memory a process may take, while retaining a sane
Davor Ocelice9ed2812017-12-25 17:49:28 +01002398 behavior. When this limit is reached, sessions which need a buffer wait for
Willy Tarreau33cb0652014-12-23 22:52:37 +01002399 another one to be released by another session. Since buffers are dynamically
2400 allocated and released, the waiting time is very short and not perceptible
2401 provided that limits remain reasonable. In fact sometimes reducing the limit
2402 may even increase performance by increasing the CPU cache's efficiency. Tests
2403 have shown good results on average HTTP traffic with a limit to 1/10 of the
2404 expected global maxconn setting, which also significantly reduces memory
2405 usage. The memory savings come from the fact that a number of connections
2406 will not allocate 2*tune.bufsize. It is best not to touch this value unless
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002407 advised to do so by an HAProxy core developer.
Willy Tarreau33cb0652014-12-23 22:52:37 +01002408
Willy Tarreau1058ae72014-12-23 22:40:40 +01002409tune.buffers.reserve <number>
2410 Sets the number of buffers which are pre-allocated and reserved for use only
2411 during memory shortage conditions resulting in failed memory allocations. The
2412 minimum value is 2 and is also the default. There is no reason a user would
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002413 want to change this value, it's mostly aimed at HAProxy core developers.
Willy Tarreau1058ae72014-12-23 22:40:40 +01002414
Willy Tarreau27a674e2009-08-17 07:23:33 +02002415tune.bufsize <number>
2416 Sets the buffer size to this size (in bytes). Lower values allow more
2417 sessions to coexist in the same amount of RAM, and higher values allow some
2418 applications with very large cookies to work. The default value is 16384 and
2419 can be changed at build time. It is strongly recommended not to change this
2420 from the default value, as very low values will break some services such as
2421 statistics, and values larger than default size will increase memory usage,
2422 possibly causing the system to run out of memory. At least the global maxconn
Willy Tarreau45a66cc2017-11-24 11:28:00 +01002423 parameter should be decreased by the same factor as this one is increased. In
2424 addition, use of HTTP/2 mandates that this value must be 16384 or more. If an
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002425 HTTP request is larger than (tune.bufsize - tune.maxrewrite), HAProxy will
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04002426 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002427 than this size, HAProxy will return HTTP 502 (Bad Gateway). Note that the
Willy Tarreauc77d3642018-12-12 06:19:42 +01002428 value set using this parameter will automatically be rounded up to the next
2429 multiple of 8 on 32-bit machines and 16 on 64-bit machines.
Willy Tarreau27a674e2009-08-17 07:23:33 +02002430
Christopher Fauletbb9fb8b2020-11-25 17:20:57 +01002431tune.chksize <number> (deprecated)
2432 This option is deprecated and ignored.
Willy Tarreau43961d52010-10-04 20:39:20 +02002433
William Lallemandf3747832012-11-09 12:33:10 +01002434tune.comp.maxlevel <number>
2435 Sets the maximum compression level. The compression level affects CPU
2436 usage during compression. This value affects CPU usage during compression.
2437 Each session using compression initializes the compression algorithm with
2438 this value. The default value is 1.
2439
Willy Tarreauc299e1e2019-02-27 11:35:12 +01002440tune.fail-alloc
2441 If compiled with DEBUG_FAIL_ALLOC, gives the percentage of chances an
2442 allocation attempt fails. Must be between 0 (no failure) and 100 (no
2443 success). This is useful to debug and make sure memory failures are handled
2444 gracefully.
2445
Willy Tarreaubc52bec2020-06-18 08:58:47 +02002446tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ]
2447 Enables ('on') or disables ('off') the edge-triggered polling mode for FDs
2448 that support it. This is currently only support with epoll. It may noticeably
2449 reduce the number of epoll_ctl() calls and slightly improve performance in
2450 certain scenarios. This is still experimental, it may result in frozen
2451 connections if bugs are still present, and is disabled by default.
2452
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02002453tune.h2.header-table-size <number>
2454 Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and
2455 cannot be larger than 65536 bytes. A larger value may help certain clients
2456 send more compact requests, depending on their capabilities. This amount of
2457 memory is consumed for each HTTP/2 connection. It is recommended not to
2458 change it.
2459
Willy Tarreaue6baec02017-07-27 11:45:11 +02002460tune.h2.initial-window-size <number>
2461 Sets the HTTP/2 initial window size, which is the number of bytes the client
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002462 can upload before waiting for an acknowledgment from HAProxy. This setting
Davor Ocelice9ed2812017-12-25 17:49:28 +01002463 only affects payload contents (i.e. the body of POST requests), not headers.
Willy Tarreaue6baec02017-07-27 11:45:11 +02002464 The default value is 65535, which roughly allows up to 5 Mbps of upload
2465 bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps
2466 over a 1-ms local network. It can make sense to increase this value to allow
2467 faster uploads, or to reduce it to increase fairness when dealing with many
2468 clients. It doesn't affect resource usage.
2469
Willy Tarreau5242ef82017-07-27 11:47:28 +02002470tune.h2.max-concurrent-streams <number>
2471 Sets the HTTP/2 maximum number of concurrent streams per connection (ie the
2472 number of outstanding requests on a single connection). The default value is
2473 100. A larger one may slightly improve page load time for complex sites when
2474 visited over high latency networks, but increases the amount of resources a
2475 single client may allocate. A value of zero disables the limit so a single
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002476 client may create as many streams as allocatable by HAProxy. It is highly
Willy Tarreau5242ef82017-07-27 11:47:28 +02002477 recommended not to change this value.
2478
Willy Tarreaua24b35c2019-02-21 13:24:36 +01002479tune.h2.max-frame-size <number>
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002480 Sets the HTTP/2 maximum frame size that HAProxy announces it is willing to
Willy Tarreaua24b35c2019-02-21 13:24:36 +01002481 receive to its peers. The default value is the largest between 16384 and the
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002482 buffer size (tune.bufsize). In any case, HAProxy will not announce support
Willy Tarreaua24b35c2019-02-21 13:24:36 +01002483 for frame sizes larger than buffers. The main purpose of this setting is to
2484 allow to limit the maximum frame size setting when using large buffers. Too
2485 large frame sizes might have performance impact or cause some peers to
2486 misbehave. It is highly recommended not to change this value.
2487
Willy Tarreau193b8c62012-11-22 00:17:38 +01002488tune.http.cookielen <number>
2489 Sets the maximum length of captured cookies. This is the maximum value that
2490 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
2491 will automatically be truncated to this one. It is important not to set too
2492 high a value because all cookie captures still allocate this size whatever
2493 their configured value (they share a same pool). This value is per request
2494 per response, so the memory allocated is twice this value per connection.
2495 When not specified, the limit is set to 63 characters. It is recommended not
2496 to change this value.
2497
Stéphane Cottin23e9e932017-05-18 08:58:41 +02002498tune.http.logurilen <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01002499 Sets the maximum length of request URI in logs. This prevents truncating long
2500 request URIs with valuable query strings in log lines. This is not related
Stéphane Cottin23e9e932017-05-18 08:58:41 +02002501 to syslog limits. If you increase this limit, you may also increase the
Davor Ocelice9ed2812017-12-25 17:49:28 +01002502 'log ... len yyy' parameter. Your syslog daemon may also need specific
Stéphane Cottin23e9e932017-05-18 08:58:41 +02002503 configuration directives too.
2504 The default value is 1024.
2505
Willy Tarreauac1932d2011-10-24 19:14:41 +02002506tune.http.maxhdr <number>
2507 Sets the maximum number of headers in a request. When a request comes with a
2508 number of headers greater than this value (including the first line), it is
2509 rejected with a "400 Bad Request" status code. Similarly, too large responses
2510 are blocked with "502 Bad Gateway". The default value is 101, which is enough
2511 for all usages, considering that the widely deployed Apache server uses the
2512 same limit. It can be useful to push this limit further to temporarily allow
Christopher Faulet50174f32017-06-21 16:31:35 +02002513 a buggy application to work by the time it gets fixed. The accepted range is
2514 1..32767. Keep in mind that each new header consumes 32bits of memory for
2515 each session, so don't push this limit too high.
Willy Tarreauac1932d2011-10-24 19:14:41 +02002516
Willy Tarreau76cc6992020-07-01 18:49:24 +02002517tune.idle-pool.shared { on | off }
2518 Enables ('on') or disables ('off') sharing of idle connection pools between
2519 threads for a same server. The default is to share them between threads in
2520 order to minimize the number of persistent connections to a server, and to
2521 optimize the connection reuse rate. But to help with debugging or when
2522 suspecting a bug in HAProxy around connection reuse, it can be convenient to
2523 forcefully disable this idle pool sharing between multiple threads, and force
Willy Tarreau0784db82021-02-19 11:45:22 +01002524 this option to "off". The default is on. It is strongly recommended against
2525 disabling this option without setting a conservative value on "pool-low-conn"
2526 for all servers relying on connection reuse to achieve a high performance
2527 level, otherwise connections might be closed very often as the thread count
2528 increases.
Willy Tarreau76cc6992020-07-01 18:49:24 +02002529
Willy Tarreau7e312732014-02-12 16:35:14 +01002530tune.idletimer <timeout>
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002531 Sets the duration after which HAProxy will consider that an empty buffer is
Willy Tarreau7e312732014-02-12 16:35:14 +01002532 probably associated with an idle stream. This is used to optimally adjust
2533 some packet sizes while forwarding large and small data alternatively. The
2534 decision to use splice() or to send large buffers in SSL is modulated by this
2535 parameter. The value is in milliseconds between 0 and 65535. A value of zero
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002536 means that HAProxy will not try to detect idle streams. The default is 1000,
Davor Ocelice9ed2812017-12-25 17:49:28 +01002537 which seems to correctly detect end user pauses (e.g. read a page before
John Roeslerfb2fce12019-07-10 15:45:51 -05002538 clicking). There should be no reason for changing this value. Please check
Willy Tarreau7e312732014-02-12 16:35:14 +01002539 tune.ssl.maxrecord below.
2540
Willy Tarreau7ac908b2019-02-27 12:02:18 +01002541tune.listener.multi-queue { on | off }
2542 Enables ('on') or disables ('off') the listener's multi-queue accept which
2543 spreads the incoming traffic to all threads a "bind" line is allowed to run
2544 on instead of taking them for itself. This provides a smoother traffic
2545 distribution and scales much better, especially in environments where threads
2546 may be unevenly loaded due to external activity (network interrupts colliding
2547 with one thread for example). This option is enabled by default, but it may
2548 be forcefully disabled for troubleshooting or for situations where it is
2549 estimated that the operating system already provides a good enough
2550 distribution and connections are extremely short-lived.
2551
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002552tune.lua.forced-yield <number>
2553 This directive forces the Lua engine to execute a yield each <number> of
Tim Düsterhus4896c442016-11-29 02:15:19 +01002554 instructions executed. This permits interrupting a long script and allows the
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002555 HAProxy scheduler to process other tasks like accepting connections or
2556 forwarding traffic. The default value is 10000 instructions. If HAProxy often
Davor Ocelice9ed2812017-12-25 17:49:28 +01002557 executes some Lua code but more responsiveness is required, this value can be
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002558 lowered. If the Lua code is quite long and its result is absolutely required
2559 to process the data, the <number> can be increased.
2560
Willy Tarreau32f61e22015-03-18 17:54:59 +01002561tune.lua.maxmem
2562 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
2563 default it is zero which means unlimited. It is important to set a limit to
2564 ensure that a bug in a script will not result in the system running out of
2565 memory.
2566
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002567tune.lua.session-timeout <timeout>
2568 This is the execution timeout for the Lua sessions. This is useful for
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02002569 preventing infinite loops or spending too much time in Lua. This timeout
2570 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002571 not taken in account. The default timeout is 4s.
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002572
2573tune.lua.task-timeout <timeout>
2574 Purpose is the same as "tune.lua.session-timeout", but this timeout is
2575 dedicated to the tasks. By default, this timeout isn't set because a task may
2576 remain alive during of the lifetime of HAProxy. For example, a task used to
2577 check servers.
2578
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02002579tune.lua.service-timeout <timeout>
2580 This is the execution timeout for the Lua services. This is useful for
2581 preventing infinite loops or spending too much time in Lua. This timeout
2582 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002583 not taken in account. The default timeout is 4s.
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02002584
Willy Tarreaua0250ba2008-01-06 11:22:57 +01002585tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01002586 Sets the maximum number of consecutive connections a process may accept in a
2587 row before switching to other work. In single process mode, higher numbers
Willy Tarreau66161322021-02-19 15:50:27 +01002588 used to give better performance at high connection rates, though this is not
2589 the case anymore with the multi-queue. This value applies individually to
2590 each listener, so that the number of processes a listener is bound to is
2591 taken into account. This value defaults to 4 which showed best results. If a
2592 significantly higher value was inherited from an ancient config, it might be
2593 worth removing it as it will both increase performance and lower response
2594 time. In multi-process mode, it is divided by twice the number of processes
2595 the listener is bound to. Setting this value to -1 completely disables the
2596 limitation. It should normally not be needed to tweak this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01002597
2598tune.maxpollevents <number>
2599 Sets the maximum amount of events that can be processed at once in a call to
2600 the polling system. The default value is adapted to the operating system. It
2601 has been noticed that reducing it below 200 tends to slightly decrease
2602 latency at the expense of network bandwidth, and increasing it above 200
2603 tends to trade latency for slightly increased bandwidth.
2604
Willy Tarreau27a674e2009-08-17 07:23:33 +02002605tune.maxrewrite <number>
2606 Sets the reserved buffer space to this size in bytes. The reserved space is
2607 used for header rewriting or appending. The first reads on sockets will never
2608 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
2609 bufsize, though that does not make much sense since there are rarely large
2610 numbers of headers to add. Setting it too high prevents processing of large
2611 requests or responses. Setting it too low prevents addition of new headers
2612 to already large requests or to POST requests. It is generally wise to set it
2613 to about 1024. It is automatically readjusted to half of bufsize if it is
2614 larger than that. This means you don't have to worry about it when changing
2615 bufsize.
2616
Willy Tarreauf3045d22015-04-29 16:24:50 +02002617tune.pattern.cache-size <number>
2618 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
2619 cache which reminds previous lookups and their results. It is used by ACLs
2620 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
2621 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
2622 strings. It applies to pattern expressions which means that it will be able
2623 to memorize the result of a lookup among all the patterns specified on a
2624 configuration line (including all those loaded from files). It automatically
2625 invalidates entries which are updated using HTTP actions or on the CLI. The
2626 default cache size is set to 10000 entries, which limits its footprint to
Willy Tarreau403bfbb2019-10-23 06:59:31 +02002627 about 5 MB per process/thread on 32-bit systems and 8 MB per process/thread
2628 on 64-bit systems, as caches are thread/process local. There is a very low
Willy Tarreauf3045d22015-04-29 16:24:50 +02002629 risk of collision in this cache, which is in the order of the size of the
2630 cache divided by 2^64. Typically, at 10000 requests per second with the
2631 default cache size of 10000 entries, there's 1% chance that a brute force
2632 attack could cause a single collision after 60 years, or 0.1% after 6 years.
2633 This is considered much lower than the risk of a memory corruption caused by
2634 aging components. If this is not acceptable, the cache can be disabled by
2635 setting this parameter to 0.
2636
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02002637tune.pipesize <number>
2638 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
2639 are the default size for the system. But sometimes when using TCP splicing,
2640 it can improve performance to increase pipe sizes, especially if it is
2641 suspected that pipes are not filled and that many calls to splice() are
2642 performed. This has an impact on the kernel's memory footprint, so this must
2643 not be changed if impacts are not understood.
2644
Olivier Houchard88698d92019-04-16 19:07:22 +02002645tune.pool-high-fd-ratio <number>
2646 This setting sets the max number of file descriptors (in percentage) used by
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002647 HAProxy globally against the maximum number of file descriptors HAProxy can
Olivier Houchard88698d92019-04-16 19:07:22 +02002648 use before we start killing idle connections when we can't reuse a connection
2649 and we have to create a new one. The default is 25 (one quarter of the file
2650 descriptor will mean that roughly half of the maximum front connections can
2651 keep an idle connection behind, anything beyond this probably doesn't make
John Roeslerfb2fce12019-07-10 15:45:51 -05002652 much sense in the general case when targeting connection reuse).
Olivier Houchard88698d92019-04-16 19:07:22 +02002653
Willy Tarreau83ca3052020-07-01 18:30:16 +02002654tune.pool-low-fd-ratio <number>
2655 This setting sets the max number of file descriptors (in percentage) used by
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002656 HAProxy globally against the maximum number of file descriptors HAProxy can
Willy Tarreau83ca3052020-07-01 18:30:16 +02002657 use before we stop putting connection into the idle pool for reuse. The
2658 default is 20.
2659
Willy Tarreaue803de22010-01-21 17:43:04 +01002660tune.rcvbuf.client <number>
2661tune.rcvbuf.server <number>
2662 Forces the kernel socket receive buffer size on the client or the server side
2663 to the specified value in bytes. This value applies to all TCP/HTTP frontends
2664 and backends. It should normally never be set, and the default size (0) lets
John Roeslerfb2fce12019-07-10 15:45:51 -05002665 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01002666 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01002667 order to save kernel memory by preventing it from buffering too large amounts
2668 of received data. Lower values will significantly increase CPU usage though.
2669
Willy Tarreaub22fc302015-12-14 12:04:35 +01002670tune.recv_enough <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01002671 HAProxy uses some hints to detect that a short read indicates the end of the
Willy Tarreaub22fc302015-12-14 12:04:35 +01002672 socket buffers. One of them is that a read returns more than <recv_enough>
2673 bytes, which defaults to 10136 (7 segments of 1448 each). This default value
2674 may be changed by this setting to better deal with workloads involving lots
2675 of short messages such as telnet or SSH sessions.
2676
Olivier Houchard1599b802018-05-24 18:59:04 +02002677tune.runqueue-depth <number>
John Roeslerfb2fce12019-07-10 15:45:51 -05002678 Sets the maximum amount of task that can be processed at once when running
Willy Tarreau060a7612021-03-10 11:06:26 +01002679 tasks. The default value depends on the number of threads but sits between 35
2680 and 280, which tend to show the highest request rates and lowest latencies.
2681 Increasing it may incur latency when dealing with I/Os, making it too small
2682 can incur extra overhead. Higher thread counts benefit from lower values.
2683 When experimenting with much larger values, it may be useful to also enable
2684 tune.sched.low-latency and possibly tune.fd.edge-triggered to limit the
2685 maximum latency to the lowest possible.
Willy Tarreaue7723bd2020-06-24 11:11:02 +02002686
2687tune.sched.low-latency { on | off }
2688 Enables ('on') or disables ('off') the low-latency task scheduler. By default
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002689 HAProxy processes tasks from several classes one class at a time as this is
Willy Tarreaue7723bd2020-06-24 11:11:02 +02002690 the most efficient. But when running with large values of tune.runqueue-depth
2691 this can have a measurable effect on request or connection latency. When this
2692 low-latency setting is enabled, tasks of lower priority classes will always
2693 be executed before other ones if they exist. This will permit to lower the
2694 maximum latency experienced by new requests or connections in the middle of
2695 massive traffic, at the expense of a higher impact on this large traffic.
2696 For regular usage it is better to leave this off. The default value is off.
Olivier Houchard1599b802018-05-24 18:59:04 +02002697
Willy Tarreaue803de22010-01-21 17:43:04 +01002698tune.sndbuf.client <number>
2699tune.sndbuf.server <number>
2700 Forces the kernel socket send buffer size on the client or the server side to
2701 the specified value in bytes. This value applies to all TCP/HTTP frontends
2702 and backends. It should normally never be set, and the default size (0) lets
John Roeslerfb2fce12019-07-10 15:45:51 -05002703 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01002704 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01002705 order to save kernel memory by preventing it from buffering too large amounts
2706 of received data. Lower values will significantly increase CPU usage though.
2707 Another use case is to prevent write timeouts with extremely slow clients due
2708 to the kernel waiting for a large part of the buffer to be read before
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002709 notifying HAProxy again.
Willy Tarreaue803de22010-01-21 17:43:04 +01002710
Willy Tarreau6ec58db2012-11-16 16:32:15 +01002711tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01002712 Sets the size of the global SSL session cache, in a number of blocks. A block
William Dauchy9a4bbfe2021-02-12 15:58:46 +01002713 is large enough to contain an encoded session without peer certificate. An
2714 encoded session with peer certificate is stored in multiple blocks depending
2715 on the size of the peer certificate. A block uses approximately 200 bytes of
2716 memory (based on `sizeof(struct sh_ssl_sess_hdr) + SHSESS_BLOCK_MIN_SIZE`
2717 calculation used for `shctx_init` function). The default value may be forced
2718 at build time, otherwise defaults to 20000. When the cache is full, the most
2719 idle entries are purged and reassigned. Higher values reduce the occurrence
2720 of such a purge, hence the number of CPU-intensive SSL handshakes by ensuring
2721 that all users keep their session as long as possible. All entries are
2722 pre-allocated upon startup and are shared between all processes if "nbproc"
2723 is greater than 1. Setting this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01002724
Emeric Brun8dc60392014-05-09 13:52:00 +02002725tune.ssl.force-private-cache
Lukas Tribus27935782018-10-01 02:00:16 +02002726 This option disables SSL session cache sharing between all processes. It
Emeric Brun8dc60392014-05-09 13:52:00 +02002727 should normally not be used since it will force many renegotiations due to
2728 clients hitting a random process. But it may be required on some operating
2729 systems where none of the SSL cache synchronization method may be used. In
2730 this case, adding a first layer of hash-based load balancing before the SSL
2731 layer might limit the impact of the lack of session sharing.
2732
William Lallemand7d42ef52020-07-06 11:41:30 +02002733tune.ssl.keylog { on | off }
2734 This option activates the logging of the TLS keys. It should be used with
2735 care as it will consume more memory per SSL session and could decrease
2736 performances. This is disabled by default.
2737
2738 These sample fetches should be used to generate the SSLKEYLOGFILE that is
2739 required to decipher traffic with wireshark.
2740
2741 https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
2742
2743 The SSLKEYLOG is a series of lines which are formatted this way:
2744
2745 <Label> <space> <ClientRandom> <space> <Secret>
2746
2747 The ClientRandom is provided by the %[ssl_fc_client_random,hex] sample
2748 fetch, the secret and the Label could be find in the array below. You need
2749 to generate a SSLKEYLOGFILE with all the labels in this array.
2750
2751 The following sample fetches are hexadecimal strings and does not need to be
2752 converted.
2753
2754 SSLKEYLOGFILE Label | Sample fetches for the Secrets
2755 --------------------------------|-----------------------------------------
2756 CLIENT_EARLY_TRAFFIC_SECRET | %[ssl_fc_client_early_traffic_secret]
2757 CLIENT_HANDSHAKE_TRAFFIC_SECRET | %[ssl_fc_client_handshake_traffic_secret]
2758 SERVER_HANDSHAKE_TRAFFIC_SECRET | %[ssl_fc_server_handshake_traffic_secret]
2759 CLIENT_TRAFFIC_SECRET_0 | %[ssl_fc_client_traffic_secret_0]
2760 SERVER_TRAFFIC_SECRET_0 | %[ssl_fc_server_traffic_secret_0]
William Lallemandd742b6c2020-07-07 10:14:56 +02002761 EXPORTER_SECRET | %[ssl_fc_exporter_secret]
2762 EARLY_EXPORTER_SECRET | %[ssl_fc_early_exporter_secret]
William Lallemand7d42ef52020-07-06 11:41:30 +02002763
2764 This is only available with OpenSSL 1.1.1, and useful with TLS1.3 session.
2765
2766 If you want to generate the content of a SSLKEYLOGFILE with TLS < 1.3, you
2767 only need this line:
2768
2769 "CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]"
2770
Emeric Brun4f65bff2012-11-16 15:11:00 +01002771tune.ssl.lifetime <timeout>
2772 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002773 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01002774 does not guarantee that sessions will last that long, because if the cache is
2775 full, the longest idle sessions will be purged despite their configured
2776 lifetime. The real usefulness of this setting is to prevent sessions from
2777 being used for too long.
2778
Willy Tarreaubfd59462013-02-21 07:46:09 +01002779tune.ssl.maxrecord <number>
2780 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
2781 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
2782 data only once it has received a full record. With large records, it means
2783 that clients might have to download up to 16kB of data before starting to
2784 process them. Limiting the value can improve page load times on browsers
2785 located over high latency or low bandwidth networks. It is suggested to find
2786 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
2787 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
2788 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
2789 2859 gave good results during tests. Use "strace -e trace=write" to find the
Davor Ocelice9ed2812017-12-25 17:49:28 +01002790 best value. HAProxy will automatically switch to this setting after an idle
Willy Tarreau7e312732014-02-12 16:35:14 +01002791 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01002792
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002793tune.ssl.default-dh-param <number>
2794 Sets the maximum size of the Diffie-Hellman parameters used for generating
2795 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
2796 final size will try to match the size of the server's RSA (or DSA) key (e.g,
2797 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
Willy Tarreau3ba77d22020-05-08 09:31:18 +02002798 this maximum value. Default value if 2048. Only 1024 or higher values are
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002799 allowed. Higher values will increase the CPU load, and values greater than
2800 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02002801 used if static Diffie-Hellman parameters are supplied either directly
2802 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002803
Christopher Faulet31af49d2015-06-09 17:29:50 +02002804tune.ssl.ssl-ctx-cache-size <number>
2805 Sets the size of the cache used to store generated certificates to <number>
2806 entries. This is a LRU cache. Because generating a SSL certificate
2807 dynamically is expensive, they are cached. The default cache size is set to
2808 1000 entries.
2809
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01002810tune.ssl.capture-cipherlist-size <number>
2811 Sets the maximum size of the buffer used for capturing client-hello cipher
2812 list. If the value is 0 (default value) the capture is disabled, otherwise
2813 a buffer is allocated for each SSL/TLS connection.
2814
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002815tune.vars.global-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01002816tune.vars.proc-max-size <size>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002817tune.vars.reqres-max-size <size>
2818tune.vars.sess-max-size <size>
2819tune.vars.txn-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01002820 These five tunes help to manage the maximum amount of memory used by the
2821 variables system. "global" limits the overall amount of memory available for
2822 all scopes. "proc" limits the memory for the process scope, "sess" limits the
2823 memory for the session scope, "txn" for the transaction scope, and "reqres"
2824 limits the memory for each request or response processing.
2825 Memory accounting is hierarchical, meaning more coarse grained limits include
2826 the finer grained ones: "proc" includes "sess", "sess" includes "txn", and
2827 "txn" includes "reqres".
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002828
Daniel Schneller0b547052016-03-21 20:46:57 +01002829 For example, when "tune.vars.sess-max-size" is limited to 100,
2830 "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed
2831 100 either. If we create a variable "txn.var" that contains 100 bytes,
2832 all available space is consumed.
2833 Notice that exceeding the limits at runtime will not result in an error
2834 message, but values might be cut off or corrupted. So make sure to accurately
2835 plan for the amount of space needed to store all your variables.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002836
William Lallemanda509e4c2012-11-07 16:54:34 +01002837tune.zlib.memlevel <number>
2838 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002839 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01002840 state. A value of 1 uses minimum memory but is slow and reduces compression
Davor Ocelice9ed2812017-12-25 17:49:28 +01002841 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
William Lallemanda509e4c2012-11-07 16:54:34 +01002842 between 1 and 9. The default value is 8.
2843
2844tune.zlib.windowsize <number>
2845 Sets the window size (the size of the history buffer) as a parameter of the
2846 zlib initialization for each session. Larger values of this parameter result
Davor Ocelice9ed2812017-12-25 17:49:28 +01002847 in better compression at the expense of memory usage. Can be a value between
2848 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002849
Willy Tarreauc57f0e22009-05-10 13:12:33 +020028503.3. Debugging
2851--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02002852
Willy Tarreau6a06a402007-07-15 20:15:28 +02002853quiet
2854 Do not display any message during startup. It is equivalent to the command-
2855 line argument "-q".
2856
Willy Tarreau3eb10b82020-04-15 16:42:39 +02002857zero-warning
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002858 When this option is set, HAProxy will refuse to start if any warning was
Willy Tarreau3eb10b82020-04-15 16:42:39 +02002859 emitted while processing the configuration. It is highly recommended to set
2860 this option on configurations that are not changed often, as it helps detect
2861 subtle mistakes and keep the configuration clean and forward-compatible. Note
2862 that "haproxy -c" will also report errors in such a case. This option is
2863 equivalent to command line argument "-dW".
2864
Emeric Brunf099e792010-09-27 12:05:28 +02002865
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010028663.4. Userlists
2867--------------
2868It is possible to control access to frontend/backend/listen sections or to
2869http stats by allowing only authenticated and authorized users. To do this,
2870it is required to create at least one userlist and to define users.
2871
2872userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01002873 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002874 used to store authentication & authorization data for independent customers.
2875
2876group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01002877 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002878 attach users to this group by using a comma separated list of names
2879 proceeded by "users" keyword.
2880
Cyril Bontéf0c60612010-02-06 14:44:47 +01002881user <username> [password|insecure-password <password>]
2882 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002883 Adds user <username> to the current userlist. Both secure (encrypted) and
2884 insecure (unencrypted) passwords can be used. Encrypted passwords are
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002885 evaluated using the crypt(3) function, so depending on the system's
2886 capabilities, different algorithms are supported. For example, modern Glibc
2887 based Linux systems support MD5, SHA-256, SHA-512, and, of course, the
2888 classic DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002889
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002890 Attention: Be aware that using encrypted passwords might cause significantly
2891 increased CPU usage, depending on the number of requests, and the algorithm
2892 used. For any of the hashed variants, the password for each request must
2893 be processed through the chosen algorithm, before it can be compared to the
2894 value specified in the config file. Most current algorithms are deliberately
2895 designed to be expensive to compute to achieve resistance against brute
2896 force attacks. They do not simply salt/hash the clear text password once,
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002897 but thousands of times. This can quickly become a major factor in HAProxy's
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002898 overall CPU consumption!
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002899
2900 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01002901 userlist L1
2902 group G1 users tiger,scott
2903 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002904
Cyril Bontéf0c60612010-02-06 14:44:47 +01002905 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
2906 user scott insecure-password elgato
2907 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002908
Cyril Bontéf0c60612010-02-06 14:44:47 +01002909 userlist L2
2910 group G1
2911 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002912
Cyril Bontéf0c60612010-02-06 14:44:47 +01002913 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
2914 user scott insecure-password elgato groups G1,G2
2915 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002916
2917 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002918
Emeric Brunf099e792010-09-27 12:05:28 +02002919
29203.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02002921----------
Emeric Brun94900952015-06-11 18:25:54 +02002922It is possible to propagate entries of any data-types in stick-tables between
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002923several HAProxy instances over TCP connections in a multi-master fashion. Each
Emeric Brun94900952015-06-11 18:25:54 +02002924instance pushes its local updates and insertions to remote peers. The pushed
2925values overwrite remote ones without aggregation. Interrupted exchanges are
2926automatically detected and recovered from the last known point.
2927In addition, during a soft restart, the old process connects to the new one
2928using such a TCP connection to push all its entries before the new process
2929tries to connect to other peers. That ensures very fast replication during a
2930reload, it typically takes a fraction of a second even for large tables.
2931Note that Server IDs are used to identify servers remotely, so it is important
2932that configurations look similar or at least that the same IDs are forced on
2933each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02002934
2935peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002936 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02002937 which is referenced by one or more stick-tables.
2938
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002939bind [<address>]:<port_range> [, ...] [param*]
2940 Defines the binding parameters of the local peer of this "peers" section.
2941 Such lines are not supported with "peer" line in the same "peers" section.
2942
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002943disabled
2944 Disables a peers section. It disables both listening and any synchronization
2945 related to this section. This is provided to disable synchronization of stick
2946 tables without having to comment out all "peers" references.
2947
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002948default-bind [param*]
2949 Defines the binding parameters for the local peer, excepted its address.
2950
2951default-server [param*]
2952 Change default options for a server in a "peers" section.
2953
2954 Arguments:
2955 <param*> is a list of parameters for this server. The "default-server"
2956 keyword accepts an important number of options and has a complete
2957 section dedicated to it. Please refer to section 5 for more
2958 details.
2959
2960
2961 See also: "server" and section 5 about server options
2962
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002963enable
2964 This re-enables a disabled peers section which was previously disabled.
2965
Jan Wagner3e678602020-12-17 22:22:32 +01002966log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
Frédéric Lécailleb6f759b2019-11-05 09:57:45 +01002967 <facility> [<level> [<minlevel>]]
2968 "peers" sections support the same "log" keyword as for the proxies to
2969 log information about the "peers" listener. See "log" option for proxies for
2970 more details.
2971
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002972peer <peername> <ip>:<port> [param*]
Emeric Brunf099e792010-09-27 12:05:28 +02002973 Defines a peer inside a peers section.
2974 If <peername> is set to the local peer name (by default hostname, or forced
Dragan Dosen13cd54c2020-06-18 18:24:05 +02002975 using "-L" command line option or "localpeer" global configuration setting),
Daniel Corbett9f0843f2021-05-08 10:50:37 -04002976 HAProxy will listen for incoming remote peer connection on <ip>:<port>.
Dragan Dosen13cd54c2020-06-18 18:24:05 +02002977 Otherwise, <ip>:<port> defines where to connect to in order to join the
2978 remote peer, and <peername> is used at the protocol level to identify and
2979 validate the remote peer on the server side.
Emeric Brunf099e792010-09-27 12:05:28 +02002980
2981 During a soft restart, local peer <ip>:<port> is used by the old instance to
2982 connect the new one and initiate a complete replication (teaching process).
2983
2984 It is strongly recommended to have the exact same peers declaration on all
Dragan Dosen13cd54c2020-06-18 18:24:05 +02002985 peers and to only rely on the "-L" command line argument or the "localpeer"
2986 global configuration setting to change the local peer name. This makes it
2987 easier to maintain coherent configuration files across all peers.
Emeric Brunf099e792010-09-27 12:05:28 +02002988
William Lallemandb2f07452015-05-12 14:27:13 +02002989 You may want to reference some environment variables in the address
2990 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01002991
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002992 Note: "peer" keyword may transparently be replaced by "server" keyword (see
2993 "server" keyword explanation below).
2994
2995server <peername> [<ip>:<port>] [param*]
Michael Prokop4438c602019-05-24 10:25:45 +02002996 As previously mentioned, "peer" keyword may be replaced by "server" keyword
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002997 with a support for all "server" parameters found in 5.2 paragraph.
2998 If the underlying peer is local, <ip>:<port> parameters must not be present.
2999 These parameters must be provided on a "bind" line (see "bind" keyword
3000 of this "peers" section).
3001 Some of these parameters are irrelevant for "peers" sections.
3002
3003
Cyril Bontédc4d9032012-04-08 21:57:39 +02003004 Example:
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01003005 # The old way.
Emeric Brunf099e792010-09-27 12:05:28 +02003006 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01003007 peer haproxy1 192.168.0.1:1024
3008 peer haproxy2 192.168.0.2:1024
3009 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02003010
3011 backend mybackend
3012 mode tcp
3013 balance roundrobin
3014 stick-table type ip size 20k peers mypeers
3015 stick on src
3016
Willy Tarreauf7b30a92010-12-06 22:59:17 +01003017 server srv1 192.168.0.30:80
3018 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02003019
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01003020 Example:
3021 peers mypeers
3022 bind 127.0.0.11:10001 ssl crt mycerts/pem
3023 default-server ssl verify none
3024 server hostA 127.0.0.10:10000
3025 server hostB #local peer
Emeric Brunf099e792010-09-27 12:05:28 +02003026
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01003027
3028table <tablename> type {ip | integer | string [len <length>] | binary [len <length>]}
3029 size <size> [expire <expire>] [nopurge] [store <data_type>]*
3030
3031 Configure a stickiness table for the current section. This line is parsed
3032 exactly the same way as the "stick-table" keyword in others section, except
John Roeslerfb2fce12019-07-10 15:45:51 -05003033 for the "peers" argument which is not required here and with an additional
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01003034 mandatory first parameter to designate the stick-table. Contrary to others
3035 sections, there may be several "table" lines in "peers" sections (see also
3036 "stick-table" keyword).
3037
3038 Also be aware of the fact that "peers" sections have their own stick-table
3039 namespaces to avoid collisions between stick-table names identical in
3040 different "peers" section. This is internally handled prepending the "peers"
3041 sections names to the name of the stick-tables followed by a '/' character.
3042 If somewhere else in the configuration file you have to refer to such
3043 stick-tables declared in "peers" sections you must use the prefixed version
3044 of the stick-table name as follows:
3045
3046 peers mypeers
3047 peer A ...
3048 peer B ...
3049 table t1 ...
3050
3051 frontend fe1
3052 tcp-request content track-sc0 src table mypeers/t1
3053
3054 This is also this prefixed version of the stick-table names which must be
3055 used to refer to stick-tables through the CLI.
3056
3057 About "peers" protocol, as only "peers" belonging to the same section may
3058 communicate with each others, there is no need to do such a distinction.
3059 Several "peers" sections may declare stick-tables with the same name.
3060 This is shorter version of the stick-table name which is sent over the network.
3061 There is only a '/' character as prefix to avoid stick-table name collisions between
3062 stick-tables declared as backends and stick-table declared in "peers" sections
3063 as follows in this weird but supported configuration:
3064
3065 peers mypeers
3066 peer A ...
3067 peer B ...
3068 table t1 type string size 10m store gpc0
3069
3070 backend t1
3071 stick-table type string size 10m store gpc0 peers mypeers
3072
Daniel Corbett67a82712020-07-06 23:01:19 -04003073 Here "t1" table declared in "mypeers" section has "mypeers/t1" as global name.
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01003074 "t1" table declared as a backend as "t1" as global name. But at peer protocol
3075 level the former table is named "/t1", the latter is again named "t1".
3076
Simon Horman51a1cf62015-02-03 13:00:44 +090030773.6. Mailers
3078------------
3079It is possible to send email alerts when the state of servers changes.
3080If configured email alerts are sent to each mailer that is configured
3081in a mailers section. Email is sent to mailers using SMTP.
3082
Pieter Baauw386a1272015-08-16 15:26:24 +02003083mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09003084 Creates a new mailer list with the name <mailersect>. It is an
3085 independent section which is referenced by one or more proxies.
3086
3087mailer <mailername> <ip>:<port>
3088 Defines a mailer inside a mailers section.
3089
3090 Example:
3091 mailers mymailers
3092 mailer smtp1 192.168.0.1:587
3093 mailer smtp2 192.168.0.2:587
3094
3095 backend mybackend
3096 mode tcp
3097 balance roundrobin
3098
3099 email-alert mailers mymailers
3100 email-alert from test1@horms.org
3101 email-alert to test2@horms.org
3102
3103 server srv1 192.168.0.30:80
3104 server srv2 192.168.0.31:80
3105
Pieter Baauw235fcfc2016-02-13 15:33:40 +01003106timeout mail <time>
3107 Defines the time available for a mail/connection to be made and send to
3108 the mail-server. If not defined the default value is 10 seconds. To allow
3109 for at least two SYN-ACK packets to be send during initial TCP handshake it
3110 is advised to keep this value above 4 seconds.
3111
3112 Example:
3113 mailers mymailers
3114 timeout mail 20s
3115 mailer smtp1 192.168.0.1:587
Simon Horman51a1cf62015-02-03 13:00:44 +09003116
William Lallemandc9515522019-06-12 16:32:11 +020031173.7. Programs
3118-------------
3119In master-worker mode, it is possible to launch external binaries with the
3120master, these processes are called programs. These programs are launched and
3121managed the same way as the workers.
3122
3123During a reload of HAProxy, those processes are dealing with the same
3124sequence as a worker:
3125
3126 - the master is re-executed
3127 - the master sends a SIGUSR1 signal to the program
3128 - if "option start-on-reload" is not disabled, the master launches a new
3129 instance of the program
3130
3131During a stop, or restart, a SIGTERM is sent to the programs.
3132
3133program <name>
3134 This is a new program section, this section will create an instance <name>
3135 which is visible in "show proc" on the master CLI. (See "9.4. Master CLI" in
3136 the management guide).
3137
3138command <command> [arguments*]
3139 Define the command to start with optional arguments. The command is looked
3140 up in the current PATH if it does not include an absolute path. This is a
3141 mandatory option of the program section. Arguments containing spaces must
3142 be enclosed in quotes or double quotes or be prefixed by a backslash.
3143
Andrew Heberle97236962019-07-12 11:50:26 +08003144user <user name>
3145 Changes the executed command user ID to the <user name> from /etc/passwd.
3146 See also "group".
3147
3148group <group name>
3149 Changes the executed command group ID to the <group name> from /etc/group.
3150 See also "user".
3151
William Lallemandc9515522019-06-12 16:32:11 +02003152option start-on-reload
3153no option start-on-reload
3154 Start (or not) a new instance of the program upon a reload of the master.
3155 The default is to start a new instance. This option may only be used in a
3156 program section.
3157
3158
Christopher Faulet76edc0f2020-01-13 15:52:01 +010031593.8. HTTP-errors
3160----------------
3161
3162It is possible to globally declare several groups of HTTP errors, to be
3163imported afterwards in any proxy section. Same group may be referenced at
3164several places and can be fully or partially imported.
3165
3166http-errors <name>
3167 Create a new http-errors group with the name <name>. It is an independent
3168 section that may be referenced by one or more proxies using its name.
3169
3170errorfile <code> <file>
3171 Associate a file contents to an HTTP error code
3172
3173 Arguments :
3174 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02003175 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Christopher Faulete095f312020-12-07 11:22:24 +01003176 425, 429, 500, 501, 502, 503, and 504.
Christopher Faulet76edc0f2020-01-13 15:52:01 +01003177
3178 <file> designates a file containing the full HTTP response. It is
3179 recommended to follow the common practice of appending ".http" to
3180 the filename so that people do not confuse the response with HTML
3181 error pages, and to use absolute paths, since files are read
3182 before any chroot is performed.
3183
3184 Please referrers to "errorfile" keyword in section 4 for details.
3185
3186 Example:
3187 http-errors website-1
3188 errorfile 400 /etc/haproxy/errorfiles/site1/400.http
3189 errorfile 404 /etc/haproxy/errorfiles/site1/404.http
3190 errorfile 408 /dev/null # work around Chrome pre-connect bug
3191
3192 http-errors website-2
3193 errorfile 400 /etc/haproxy/errorfiles/site2/400.http
3194 errorfile 404 /etc/haproxy/errorfiles/site2/404.http
3195 errorfile 408 /dev/null # work around Chrome pre-connect bug
3196
Emeric Brun99c453d2020-05-25 15:01:04 +020031973.9. Rings
3198----------
3199
3200It is possible to globally declare ring-buffers, to be used as target for log
3201servers or traces.
3202
3203ring <ringname>
3204 Creates a new ring-buffer with name <ringname>.
3205
3206description <text>
Daniel Corbett67a82712020-07-06 23:01:19 -04003207 The description is an optional description string of the ring. It will
Emeric Brun99c453d2020-05-25 15:01:04 +02003208 appear on CLI. By default, <name> is reused to fill this field.
3209
3210format <format>
3211 Format used to store events into the ring buffer.
3212
3213 Arguments:
3214 <format> is the log format used when generating syslog messages. It may be
3215 one of the following :
3216
3217 iso A message containing only the ISO date, followed by the text.
3218 The PID, process name and system name are omitted. This is
3219 designed to be used with a local log server.
3220
Emeric Brun0237c4e2020-11-27 16:24:34 +01003221 local Analog to rfc3164 syslog message format except that hostname
3222 field is stripped. This is the default.
3223 Note: option "log-send-hostname" switches the default to
3224 rfc3164.
3225
Emeric Brun99c453d2020-05-25 15:01:04 +02003226 raw A message containing only the text. The level, PID, date, time,
3227 process name and system name are omitted. This is designed to be
3228 used in containers or during development, where the severity
3229 only depends on the file descriptor used (stdout/stderr). This
3230 is the default.
3231
Emeric Brun0237c4e2020-11-27 16:24:34 +01003232 rfc3164 The RFC3164 syslog message format.
Emeric Brun99c453d2020-05-25 15:01:04 +02003233 (https://tools.ietf.org/html/rfc3164)
3234
3235 rfc5424 The RFC5424 syslog message format.
3236 (https://tools.ietf.org/html/rfc5424)
3237
3238 short A message containing only a level between angle brackets such as
3239 '<3>', followed by the text. The PID, date, time, process name
3240 and system name are omitted. This is designed to be used with a
3241 local log server. This format is compatible with what the systemd
3242 logger consumes.
3243
Emeric Brun54648852020-07-06 15:54:06 +02003244 priority A message containing only a level plus syslog facility between angle
3245 brackets such as '<63>', followed by the text. The PID, date, time,
3246 process name and system name are omitted. This is designed to be used
3247 with a local log server.
3248
Emeric Brun99c453d2020-05-25 15:01:04 +02003249 timed A message containing only a level between angle brackets such as
3250 '<3>', followed by ISO date and by the text. The PID, process
3251 name and system name are omitted. This is designed to be
3252 used with a local log server.
3253
3254maxlen <length>
3255 The maximum length of an event message stored into the ring,
3256 including formatted header. If an event message is longer than
3257 <length>, it will be truncated to this length.
3258
Emeric Brun494c5052020-05-28 11:13:15 +02003259server <name> <address> [param*]
3260 Used to configure a syslog tcp server to forward messages from ring buffer.
3261 This supports for all "server" parameters found in 5.2 paragraph. Some of
3262 these parameters are irrelevant for "ring" sections. Important point: there
3263 is little reason to add more than one server to a ring, because all servers
3264 will receive the exact same copy of the ring contents, and as such the ring
3265 will progress at the speed of the slowest server. If one server does not
3266 respond, it will prevent old messages from being purged and may block new
3267 messages from being inserted into the ring. The proper way to send messages
3268 to multiple servers is to use one distinct ring per log server, not to
Emeric Brun97556472020-05-30 01:42:45 +02003269 attach multiple servers to the same ring. Note that specific server directive
3270 "log-proto" is used to set the protocol used to send messages.
Emeric Brun494c5052020-05-28 11:13:15 +02003271
Emeric Brun99c453d2020-05-25 15:01:04 +02003272size <size>
3273 This is the optional size in bytes for the ring-buffer. Default value is
3274 set to BUFSIZE.
3275
Emeric Brun494c5052020-05-28 11:13:15 +02003276timeout connect <timeout>
3277 Set the maximum time to wait for a connection attempt to a server to succeed.
3278
3279 Arguments :
3280 <timeout> is the timeout value specified in milliseconds by default, but
3281 can be in any other unit if the number is suffixed by the unit,
3282 as explained at the top of this document.
3283
3284timeout server <timeout>
3285 Set the maximum time for pending data staying into output buffer.
3286
3287 Arguments :
3288 <timeout> is the timeout value specified in milliseconds by default, but
3289 can be in any other unit if the number is suffixed by the unit,
3290 as explained at the top of this document.
3291
Emeric Brun99c453d2020-05-25 15:01:04 +02003292 Example:
3293 global
3294 log ring@myring local7
3295
3296 ring myring
3297 description "My local buffer"
3298 format rfc3164
3299 maxlen 1200
3300 size 32764
Emeric Brun494c5052020-05-28 11:13:15 +02003301 timeout connect 5s
3302 timeout server 10s
Emeric Brun97556472020-05-30 01:42:45 +02003303 server mysyslogsrv 127.0.0.1:6514 log-proto octet-count
Emeric Brun99c453d2020-05-25 15:01:04 +02003304
Emeric Brun12941c82020-07-07 14:19:42 +020033053.10. Log forwarding
3306-------------------
3307
3308It is possible to declare one or multiple log forwarding section,
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003309HAProxy will forward all received log messages to a log servers list.
Emeric Brun12941c82020-07-07 14:19:42 +02003310
3311log-forward <name>
3312 Creates a new log forwarder proxy identified as <name>.
3313
Emeric Bruncbb7bf72020-10-05 14:39:35 +02003314backlog <conns>
3315 Give hints to the system about the approximate listen backlog desired size
3316 on connections accept.
3317
3318bind <addr> [param*]
3319 Used to configure a stream log listener to receive messages to forward.
Emeric Brunda46c1c2020-10-08 08:39:02 +02003320 This supports the "bind" parameters found in 5.1 paragraph including
3321 those about ssl but some statements such as "alpn" may be irrelevant for
3322 syslog protocol over TCP.
3323 Those listeners support both "Octet Counting" and "Non-Transparent-Framing"
Emeric Bruncbb7bf72020-10-05 14:39:35 +02003324 modes as defined in rfc-6587.
3325
Willy Tarreau76aaa7f2020-09-16 15:07:22 +02003326dgram-bind <addr> [param*]
Emeric Bruncbb7bf72020-10-05 14:39:35 +02003327 Used to configure a datagram log listener to receive messages to forward.
3328 Addresses must be in IPv4 or IPv6 form,followed by a port. This supports
3329 for some of the "bind" parameters found in 5.1 paragraph among which
3330 "interface", "namespace" or "transparent", the other ones being
Willy Tarreau26ff5da2020-09-16 15:22:19 +02003331 silently ignored as irrelevant for UDP/syslog case.
Emeric Brun12941c82020-07-07 14:19:42 +02003332
3333log global
Jan Wagner3e678602020-12-17 22:22:32 +01003334log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
Emeric Brun12941c82020-07-07 14:19:42 +02003335 <facility> [<level> [<minlevel>]]
3336 Used to configure target log servers. See more details on proxies
3337 documentation.
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003338 If no format specified, HAProxy tries to keep the incoming log format.
Emeric Brun12941c82020-07-07 14:19:42 +02003339 Configured facility is ignored, except if incoming message does not
3340 present a facility but one is mandatory on the outgoing format.
3341 If there is no timestamp available in the input format, but the field
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003342 exists in output format, HAProxy will use the local date.
Emeric Brun12941c82020-07-07 14:19:42 +02003343
3344 Example:
3345 global
3346 log stderr format iso local7
3347
3348 ring myring
3349 description "My local buffer"
3350 format rfc5424
3351 maxlen 1200
3352 size 32764
3353 timeout connect 5s
3354 timeout server 10s
3355 # syslog tcp server
3356 server mysyslogsrv 127.0.0.1:514 log-proto octet-count
3357
3358 log-forward sylog-loadb
Emeric Bruncbb7bf72020-10-05 14:39:35 +02003359 dgram-bind 127.0.0.1:1514
3360 bind 127.0.0.1:1514
Emeric Brun12941c82020-07-07 14:19:42 +02003361 # all messages on stderr
3362 log global
3363 # all messages on local tcp syslog server
3364 log ring@myring local0
3365 # load balance messages on 4 udp syslog servers
3366 log 127.0.0.1:10001 sample 1:4 local0
3367 log 127.0.0.1:10002 sample 2:4 local0
3368 log 127.0.0.1:10003 sample 3:4 local0
3369 log 127.0.0.1:10004 sample 4:4 local0
Christopher Faulet76edc0f2020-01-13 15:52:01 +01003370
Emeric Bruncbb7bf72020-10-05 14:39:35 +02003371maxconn <conns>
3372 Fix the maximum number of concurrent connections on a log forwarder.
3373 10 is the default.
3374
3375timeout client <timeout>
3376 Set the maximum inactivity time on the client side.
3377
Willy Tarreauc57f0e22009-05-10 13:12:33 +020033784. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02003379----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01003380
Willy Tarreau6a06a402007-07-15 20:15:28 +02003381Proxy configuration can be located in a set of sections :
Willy Tarreau7c0b4d82021-02-12 14:58:08 +01003382 - defaults [<name>] [ from <defaults_name> ]
3383 - frontend <name> [ from <defaults_name> ]
3384 - backend <name> [ from <defaults_name> ]
3385 - listen <name> [ from <defaults_name> ]
Willy Tarreau6a06a402007-07-15 20:15:28 +02003386
3387A "frontend" section describes a set of listening sockets accepting client
3388connections.
3389
3390A "backend" section describes a set of servers to which the proxy will connect
3391to forward incoming connections.
3392
3393A "listen" section defines a complete proxy with its frontend and backend
3394parts combined in one section. It is generally useful for TCP-only traffic.
3395
Willy Tarreau7c0b4d82021-02-12 14:58:08 +01003396A "defaults" section resets all settings to the documented ones and presets new
3397ones for use by subsequent sections. All of "frontend", "backend" and "listen"
3398sections always take their initial settings from a defaults section, by default
3399the latest one that appears before the newly created section. It is possible to
3400explicitly designate a specific "defaults" section to load the initial settings
3401from by indicating its name on the section line after the optional keyword
3402"from". While "defaults" section do not impose a name, this use is encouraged
3403for better readability. It is also the only way to designate a specific section
3404to use instead of the default previous one. Since "defaults" section names are
3405optional, by default a very permissive check is applied on their name and these
3406are even permitted to overlap. However if a "defaults" section is referenced by
3407any other section, its name must comply with the syntax imposed on all proxy
3408names, and this name must be unique among the defaults sections. Please note
3409that regardless of what is currently permitted, it is recommended to avoid
3410duplicate section names in general and to respect the same syntax as for proxy
3411names. This rule might be enforced in a future version.
3412
3413Note that it is even possible for a defaults section to take its initial
3414settings from another one, and as such, inherit settings across multiple levels
3415of defaults sections. This can be convenient to establish certain configuration
3416profiles to carry groups of default settings (e.g. TCP vs HTTP or short vs long
3417timeouts) but can quickly become confusing to follow.
3418
Willy Tarreau0ba27502007-12-24 16:55:16 +01003419All proxy names must be formed from upper and lower case letters, digits,
3420'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
3421case-sensitive, which means that "www" and "WWW" are two different proxies.
3422
3423Historically, all proxy names could overlap, it just caused troubles in the
3424logs. Since the introduction of content switching, it is mandatory that two
3425proxies with overlapping capabilities (frontend/backend) have different names.
3426However, it is still permitted that a frontend and a backend share the same
3427name, as this configuration seems to be commonly encountered.
3428
3429Right now, two major proxy modes are supported : "tcp", also known as layer 4,
3430and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003431bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003432protocol, and can interact with it by allowing, blocking, switching, adding,
3433modifying, or removing arbitrary contents in requests or responses, based on
3434arbitrary criteria.
3435
Willy Tarreau70dffda2014-01-30 03:07:23 +01003436In HTTP mode, the processing applied to requests and responses flowing over
3437a connection depends in the combination of the frontend's HTTP options and
Julien Pivotto21ad3152019-12-10 13:11:17 +01003438the backend's. HAProxy supports 3 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +01003439
3440 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
3441 requests and responses are processed, and connections remain open but idle
3442 between responses and new requests.
3443
Willy Tarreau70dffda2014-01-30 03:07:23 +01003444 - SCL: server close ("option http-server-close") : the server-facing
3445 connection is closed after the end of the response is received, but the
3446 client-facing connection remains open.
3447
Christopher Faulet315b39c2018-09-21 16:26:19 +02003448 - CLO: close ("option httpclose"): the connection is closed after the end of
3449 the response and "Connection: close" appended in both directions.
Willy Tarreau70dffda2014-01-30 03:07:23 +01003450
3451The effective mode that will be applied to a connection passing through a
3452frontend and a backend can be determined by both proxy modes according to the
3453following matrix, but in short, the modes are symmetric, keep-alive is the
Christopher Faulet315b39c2018-09-21 16:26:19 +02003454weakest option and close is the strongest.
Willy Tarreau70dffda2014-01-30 03:07:23 +01003455
Christopher Faulet315b39c2018-09-21 16:26:19 +02003456 Backend mode
Willy Tarreau70dffda2014-01-30 03:07:23 +01003457
Christopher Faulet315b39c2018-09-21 16:26:19 +02003458 | KAL | SCL | CLO
3459 ----+-----+-----+----
3460 KAL | KAL | SCL | CLO
3461 ----+-----+-----+----
Christopher Faulet315b39c2018-09-21 16:26:19 +02003462 mode SCL | SCL | SCL | CLO
3463 ----+-----+-----+----
3464 CLO | CLO | CLO | CLO
Willy Tarreau70dffda2014-01-30 03:07:23 +01003465
Christopher Faulet4d37e532021-03-26 14:44:00 +01003466It is possible to chain a TCP frontend to an HTTP backend. It is pointless if
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003467only HTTP traffic is handled. But it may be used to handle several protocols
3468within the same frontend. In this case, the client's connection is first handled
Christopher Faulet4d37e532021-03-26 14:44:00 +01003469as a raw tcp connection before being upgraded to HTTP. Before the upgrade, the
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003470content processings are performend on raw data. Once upgraded, data is parsed
Christopher Faulet4d37e532021-03-26 14:44:00 +01003471and stored using an internal representation called HTX and it is no longer
3472possible to rely on raw representation. There is no way to go back.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003473
Christopher Faulet4d37e532021-03-26 14:44:00 +01003474There are two kind of upgrades, in-place upgrades and destructive upgrades. The
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003475first ones involves a TCP to HTTP/1 upgrade. In HTTP/1, the request
Christopher Faulet4d37e532021-03-26 14:44:00 +01003476processings are serialized, thus the applicative stream can be preserved. The
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003477second one involves a TCP to HTTP/2 upgrade. Because it is a multiplexed
Christopher Faulet4d37e532021-03-26 14:44:00 +01003478protocol, the applicative stream cannot be associated to any HTTP/2 stream and
3479is destroyed. New applicative streams are then created when HAProxy receives
3480new HTTP/2 streams at the lower level, in the H2 multiplexer. It is important
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003481to understand this difference because that drastically changes the way to
Christopher Faulet4d37e532021-03-26 14:44:00 +01003482process data. When an HTTP/1 upgrade is performed, the content processings
3483already performed on raw data are neither lost nor reexecuted while for an
3484HTTP/2 upgrade, applicative streams are distinct and all frontend rules are
3485evaluated systematically on each one. And as said, the first stream, the TCP
3486one, is destroyed, but only after the frontend rules were evaluated.
3487
3488There is another importnat point to understand when HTTP processings are
3489performed from a TCP proxy. While HAProxy is able to parse HTTP/1 in-fly from
3490tcp-request content rules, it is not possible for HTTP/2. Only the HTTP/2
3491preface can be parsed. This is a huge limitation regarding the HTTP content
3492analysis in TCP. Concretely it is only possible to know if received data are
3493HTTP. For instance, it is not possible to choose a backend based on the Host
3494header value while it is trivial in HTTP/1. Hopefully, there is a solution to
3495mitigate this drawback.
3496
Daniel Corbett9f0843f2021-05-08 10:50:37 -04003497There are two ways to perform an HTTP upgrade. The first one, the historical
Christopher Faulet4d37e532021-03-26 14:44:00 +01003498method, is to select an HTTP backend. The upgrade happens when the backend is
3499set. Thus, for in-place upgrades, only the backend configuration is considered
3500in the HTTP data processing. For destructive upgrades, the applicative stream
3501is destroyed, thus its processing is stopped. With this method, possibilities
3502to choose a backend with an HTTP/2 connection are really limited, as mentioned
3503above, and a bit useless because the stream is destroyed. The second method is
3504to upgrade during the tcp-request content rules evaluation, thanks to the
3505"switch-mode http" action. In this case, the upgrade is performed in the
3506frontend context and it is possible to define HTTP directives in this
3507frontend. For in-place upgrades, it offers all the power of the HTTP analysis
3508as soon as possible. It is not that far from an HTTP frontend. For destructive
3509upgrades, it does not change anything except it is useless to choose a backend
3510on limited information. It is of course the recommended method. Thus, testing
3511the request protocol from the tcp-request content rules to perform an HTTP
3512upgrade is enough. All the remaining HTTP manipulation may be moved to the
3513frontend http-request ruleset. But keep in mind that tcp-request content rules
3514remains evaluated on each streams, that can't be changed.
Willy Tarreau70dffda2014-01-30 03:07:23 +01003515
Willy Tarreauc57f0e22009-05-10 13:12:33 +020035164.1. Proxy keywords matrix
3517--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01003518
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003519The following list of keywords is supported. Most of them may only be used in a
3520limited set of section types. Some of them are marked as "deprecated" because
3521they are inherited from an old syntax which may be confusing or functionally
3522limited, and there are new recommended keywords to replace them. Keywords
Davor Ocelice9ed2812017-12-25 17:49:28 +01003523marked with "(*)" can be optionally inverted using the "no" prefix, e.g. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003524option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02003525and must be disabled for a specific instance. Such options may also be prefixed
3526with "default" in order to restore default settings regardless of what has been
3527specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003528
Willy Tarreau6a06a402007-07-15 20:15:28 +02003529
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003530 keyword defaults frontend listen backend
3531------------------------------------+----------+----------+---------+---------
3532acl - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003533backlog X X X -
3534balance X - X X
3535bind - X X -
3536bind-process X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003537capture cookie - X X -
3538capture request header - X X -
3539capture response header - X X -
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003540clitcpka-cnt X X X -
3541clitcpka-idle X X X -
3542clitcpka-intvl X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02003543compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003544cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003545declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003546default-server X - X X
3547default_backend X X X -
3548description - X X X
3549disabled X X X X
3550dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09003551email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09003552email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09003553email-alert mailers X X X X
3554email-alert myhostname X X X X
3555email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003556enabled X X X X
3557errorfile X X X X
Christopher Faulet76edc0f2020-01-13 15:52:01 +01003558errorfiles X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003559errorloc X X X X
3560errorloc302 X X X X
3561-- keyword -------------------------- defaults - frontend - listen -- backend -
3562errorloc303 X X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01003563force-persist - - X X
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003564filter - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003565fullconn X - X X
3566grace X X X X
3567hash-type X - X X
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01003568http-after-response - X X X
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02003569http-check comment X - X X
Christopher Faulete5870d82020-04-15 11:32:03 +02003570http-check connect X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003571http-check disable-on-404 X - X X
Christopher Faulete5870d82020-04-15 11:32:03 +02003572http-check expect X - X X
Peter Gervai8912ae62020-06-11 18:26:36 +02003573http-check send X - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02003574http-check send-state X - X X
Christopher Faulete5870d82020-04-15 11:32:03 +02003575http-check set-var X - X X
3576http-check unset-var X - X X
Christopher Faulet3b967c12020-05-15 15:47:44 +02003577http-error X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003578http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003579http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02003580http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02003581http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003582id - X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01003583ignore-persist - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02003584load-server-state-from-file X - X X
William Lallemand0f99e342011-10-12 17:50:54 +02003585log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01003586log-format X X X -
Dragan Dosen7ad31542015-09-28 17:16:47 +02003587log-format-sd X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01003588log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02003589max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003590maxconn X X X -
3591mode X X X X
3592monitor fail - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003593monitor-uri X X X -
3594option abortonclose (*) X - X X
3595option accept-invalid-http-request (*) X X X -
3596option accept-invalid-http-response (*) X - X X
3597option allbackups (*) X - X X
3598option checkcache (*) X - X X
3599option clitcpka (*) X X X -
3600option contstats (*) X X X -
Christopher Faulet89aed322020-06-02 17:33:56 +02003601option disable-h2-upgrade (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003602option dontlog-normal (*) X X X -
3603option dontlognull (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003604-- keyword -------------------------- defaults - frontend - listen -- backend -
3605option forwardfor X X X X
Christopher Faulet98fbe952019-07-22 16:18:24 +02003606option h1-case-adjust-bogus-client (*) X X X -
3607option h1-case-adjust-bogus-server (*) X - X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02003608option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02003609option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01003610option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02003611option http-no-delay (*) X X X X
Christopher Faulet98db9762018-09-21 10:25:19 +02003612option http-pretend-keepalive (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003613option http-server-close (*) X X X X
3614option http-use-proxy-header (*) X X X -
3615option httpchk X - X X
3616option httpclose (*) X X X X
Freddy Spierenburge88b7732019-03-25 14:35:17 +01003617option httplog X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003618option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003619option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003620option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09003621option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003622option log-health-checks (*) X - X X
3623option log-separate-errors (*) X X X -
3624option logasap (*) X X X -
3625option mysql-check X - X X
3626option nolinger (*) X X X X
3627option originalto X X X X
3628option persist (*) X - X X
Baptiste Assmann809e22a2015-10-12 20:22:55 +02003629option pgsql-check X - X X
3630option prefer-last-server (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003631option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02003632option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003633option smtpchk X - X X
3634option socket-stats (*) X X X -
3635option splice-auto (*) X X X X
3636option splice-request (*) X X X X
3637option splice-response (*) X X X X
Christopher Fauletba7bc162016-11-07 21:07:38 +01003638option spop-check - - - X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003639option srvtcpka (*) X - X X
3640option ssl-hello-chk X - X X
3641-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01003642option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003643option tcp-smart-accept (*) X X X -
3644option tcp-smart-connect (*) X - X X
3645option tcpka X X X X
3646option tcplog X X X X
3647option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09003648external-check command X - X X
3649external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003650persist rdp-cookie X - X X
3651rate-limit sessions X X X -
3652redirect - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003653-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003654retries X - X X
Olivier Houcharda254a372019-04-05 15:30:12 +02003655retry-on X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003656server - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02003657server-state-file-name X - X X
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02003658server-template - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003659source X - X X
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003660srvtcpka-cnt X - X X
3661srvtcpka-idle X - X X
3662srvtcpka-intvl X - X X
Baptiste Assmann5a549212015-10-12 20:30:24 +02003663stats admin - X X X
3664stats auth X X X X
3665stats enable X X X X
3666stats hide-version X X X X
3667stats http-request - X X X
3668stats realm X X X X
3669stats refresh X X X X
3670stats scope X X X X
3671stats show-desc X X X X
3672stats show-legends X X X X
3673stats show-node X X X X
3674stats uri X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003675-- keyword -------------------------- defaults - frontend - listen -- backend -
3676stick match - - X X
3677stick on - - X X
3678stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02003679stick store-response - - X X
Adam Spiers68af3c12017-04-06 16:31:39 +01003680stick-table - X X X
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02003681tcp-check comment X - X X
Christopher Faulet404f9192020-04-09 23:13:54 +02003682tcp-check connect X - X X
3683tcp-check expect X - X X
3684tcp-check send X - X X
Christopher Fauletb50b3e62020-05-05 18:43:43 +02003685tcp-check send-lf X - X X
Christopher Faulet404f9192020-04-09 23:13:54 +02003686tcp-check send-binary X - X X
Christopher Fauletb50b3e62020-05-05 18:43:43 +02003687tcp-check send-binary-lf X - X X
Christopher Faulet404f9192020-04-09 23:13:54 +02003688tcp-check set-var X - X X
3689tcp-check unset-var X - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02003690tcp-request connection - X X -
3691tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02003692tcp-request inspect-delay - X X X
Willy Tarreau4f614292016-10-21 17:49:36 +02003693tcp-request session - X X -
Emeric Brun0a3b67f2010-09-24 15:34:53 +02003694tcp-response content - - X X
3695tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003696timeout check X - X X
3697timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02003698timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003699timeout connect X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003700timeout http-keep-alive X X X X
3701timeout http-request X X X X
3702timeout queue X - X X
3703timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02003704timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003705timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02003706timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003707transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01003708unique-id-format X X X -
3709unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003710use_backend - X X -
Christopher Fauletb30b3102019-09-12 23:03:09 +02003711use-fcgi-app - - X X
Willy Tarreau4a5cade2012-04-05 21:09:48 +02003712use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003713------------------------------------+----------+----------+---------+---------
3714 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02003715
Willy Tarreau0ba27502007-12-24 16:55:16 +01003716
Willy Tarreauc57f0e22009-05-10 13:12:33 +020037174.2. Alphabetically sorted keywords reference
3718---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01003719
3720This section provides a description of each keyword and its usage.
3721
3722
3723acl <aclname> <criterion> [flags] [operator] <value> ...
3724 Declare or complete an access list.
3725 May be used in sections : defaults | frontend | listen | backend
3726 no | yes | yes | yes
3727 Example:
3728 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
3729 acl invalid_src src_port 0:1023
3730 acl local_dst hdr(host) -i localhost
3731
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003732 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003733
3734
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01003735backlog <conns>
3736 Give hints to the system about the approximate listen backlog desired size
3737 May be used in sections : defaults | frontend | listen | backend
3738 yes | yes | yes | no
3739 Arguments :
3740 <conns> is the number of pending connections. Depending on the operating
3741 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02003742 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01003743
3744 In order to protect against SYN flood attacks, one solution is to increase
3745 the system's SYN backlog size. Depending on the system, sometimes it is just
3746 tunable via a system parameter, sometimes it is not adjustable at all, and
3747 sometimes the system relies on hints given by the application at the time of
3748 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
3749 to the listen() syscall. On systems which can make use of this value, it can
3750 sometimes be useful to be able to specify a different value, hence this
3751 backlog parameter.
3752
3753 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
3754 used as a hint and the system accepts up to the smallest greater power of
3755 two, and never more than some limits (usually 32768).
3756
3757 See also : "maxconn" and the target operating system's tuning guide.
3758
3759
Willy Tarreau0ba27502007-12-24 16:55:16 +01003760balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02003761balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01003762 Define the load balancing algorithm to be used in a backend.
3763 May be used in sections : defaults | frontend | listen | backend
3764 yes | no | yes | yes
3765 Arguments :
3766 <algorithm> is the algorithm used to select a server when doing load
3767 balancing. This only applies when no persistence information
3768 is available, or when a connection is redispatched to another
3769 server. <algorithm> may be one of the following :
3770
3771 roundrobin Each server is used in turns, according to their weights.
3772 This is the smoothest and fairest algorithm when the server's
3773 processing time remains equally distributed. This algorithm
3774 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02003775 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08003776 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02003777 large farms, when a server becomes up after having been down
3778 for a very short time, it may sometimes take a few hundreds
3779 requests for it to be re-integrated into the farm and start
3780 receiving traffic. This is normal, though very rare. It is
3781 indicated here in case you would have the chance to observe
3782 it, so that you don't worry.
3783
3784 static-rr Each server is used in turns, according to their weights.
3785 This algorithm is as similar to roundrobin except that it is
3786 static, which means that changing a server's weight on the
3787 fly will have no effect. On the other hand, it has no design
3788 limitation on the number of servers, and when a server goes
3789 up, it is always immediately reintroduced into the farm, once
3790 the full map is recomputed. It also uses slightly less CPU to
3791 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01003792
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01003793 leastconn The server with the lowest number of connections receives the
3794 connection. Round-robin is performed within groups of servers
3795 of the same load to ensure that all servers will be used. Use
3796 of this algorithm is recommended where very long sessions are
3797 expected, such as LDAP, SQL, TSE, etc... but is not very well
3798 suited for protocols using short sessions such as HTTP. This
3799 algorithm is dynamic, which means that server weights may be
Willy Tarreau8c855f62020-10-22 17:41:45 +02003800 adjusted on the fly for slow starts for instance. It will
3801 also consider the number of queued connections in addition to
3802 the established ones in order to minimize queuing.
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01003803
Willy Tarreauf09c6602012-02-13 17:12:08 +01003804 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003805 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01003806 identifier to the highest (see server parameter "id"), which
3807 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02003808 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01003809 not make sense to use this algorithm without setting maxconn.
3810 The purpose of this algorithm is to always use the smallest
3811 number of servers so that extra servers can be powered off
3812 during non-intensive hours. This algorithm ignores the server
3813 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02003814 or IMAP than HTTP, though it can be useful there too. In
3815 order to use this algorithm efficiently, it is recommended
3816 that a cloud controller regularly checks server usage to turn
3817 them off when unused, and regularly checks backend queue to
3818 turn new servers on when the queue inflates. Alternatively,
3819 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01003820
Willy Tarreau0ba27502007-12-24 16:55:16 +01003821 source The source IP address is hashed and divided by the total
3822 weight of the running servers to designate which server will
3823 receive the request. This ensures that the same client IP
3824 address will always reach the same server as long as no
3825 server goes down or up. If the hash result changes due to the
3826 number of running servers changing, many clients will be
3827 directed to a different server. This algorithm is generally
3828 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003829 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01003830 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003831 static by default, which means that changing a server's
3832 weight on the fly will have no effect, but this can be
3833 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003834
Oskar Stolc8dc41842012-05-19 10:19:54 +01003835 uri This algorithm hashes either the left part of the URI (before
3836 the question mark) or the whole URI (if the "whole" parameter
3837 is present) and divides the hash value by the total weight of
3838 the running servers. The result designates which server will
3839 receive the request. This ensures that the same URI will
3840 always be directed to the same server as long as no server
3841 goes up or down. This is used with proxy caches and
3842 anti-virus proxies in order to maximize the cache hit rate.
3843 Note that this algorithm may only be used in an HTTP backend.
3844 This algorithm is static by default, which means that
3845 changing a server's weight on the fly will have no effect,
3846 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003847
Oskar Stolc8dc41842012-05-19 10:19:54 +01003848 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02003849 "depth", both followed by a positive integer number. These
3850 options may be helpful when it is needed to balance servers
3851 based on the beginning of the URI only. The "len" parameter
3852 indicates that the algorithm should only consider that many
3853 characters at the beginning of the URI to compute the hash.
3854 Note that having "len" set to 1 rarely makes sense since most
3855 URIs start with a leading "/".
3856
3857 The "depth" parameter indicates the maximum directory depth
3858 to be used to compute the hash. One level is counted for each
3859 slash in the request. If both parameters are specified, the
3860 evaluation stops when either is reached.
3861
Willy Tarreau57a37412020-09-23 08:56:29 +02003862 A "path-only" parameter indicates that the hashing key starts
3863 at the first '/' of the path. This can be used to ignore the
3864 authority part of absolute URIs, and to make sure that HTTP/1
3865 and HTTP/2 URIs will provide the same hash.
3866
Willy Tarreau0ba27502007-12-24 16:55:16 +01003867 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003868 the query string of each HTTP GET request.
3869
3870 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02003871 request entity will be searched for the parameter argument,
3872 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02003873 ('?') in the URL. The message body will only start to be
3874 analyzed once either the advertised amount of data has been
3875 received or the request buffer is full. In the unlikely event
3876 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02003877 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02003878 be randomly balanced if at all. This keyword used to support
3879 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003880
3881 If the parameter is found followed by an equal sign ('=') and
3882 a value, then the value is hashed and divided by the total
3883 weight of the running servers. The result designates which
3884 server will receive the request.
3885
3886 This is used to track user identifiers in requests and ensure
3887 that a same user ID will always be sent to the same server as
3888 long as no server goes up or down. If no value is found or if
3889 the parameter is not found, then a round robin algorithm is
3890 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003891 backend. This algorithm is static by default, which means
3892 that changing a server's weight on the fly will have no
3893 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003894
Cyril Bontédc4d9032012-04-08 21:57:39 +02003895 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
3896 request. Just as with the equivalent ACL 'hdr()' function,
3897 the header name in parenthesis is not case sensitive. If the
3898 header is absent or if it does not contain any value, the
3899 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01003900
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003901 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01003902 reducing the hash algorithm to the main domain part with some
3903 specific headers such as 'Host'. For instance, in the Host
3904 value "haproxy.1wt.eu", only "1wt" will be considered.
3905
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003906 This algorithm is static by default, which means that
3907 changing a server's weight on the fly will have no effect,
3908 but this can be changed using "hash-type".
3909
Willy Tarreau21c741a2019-01-14 18:14:27 +01003910 random
3911 random(<draws>)
3912 A random number will be used as the key for the consistent
Willy Tarreau760e81d2018-05-03 07:20:40 +02003913 hashing function. This means that the servers' weights are
3914 respected, dynamic weight changes immediately take effect, as
3915 well as new server additions. Random load balancing can be
3916 useful with large farms or when servers are frequently added
Willy Tarreau21c741a2019-01-14 18:14:27 +01003917 or removed as it may avoid the hammering effect that could
3918 result from roundrobin or leastconn in this situation. The
3919 hash-balance-factor directive can be used to further improve
3920 fairness of the load balancing, especially in situations
3921 where servers show highly variable response times. When an
3922 argument <draws> is present, it must be an integer value one
3923 or greater, indicating the number of draws before selecting
3924 the least loaded of these servers. It was indeed demonstrated
3925 that picking the least loaded of two servers is enough to
3926 significantly improve the fairness of the algorithm, by
3927 always avoiding to pick the most loaded server within a farm
3928 and getting rid of any bias that could be induced by the
3929 unfair distribution of the consistent list. Higher values N
3930 will take away N-1 of the highest loaded servers at the
3931 expense of performance. With very high values, the algorithm
3932 will converge towards the leastconn's result but much slower.
3933 The default value is 2, which generally shows very good
3934 distribution and performance. This algorithm is also known as
3935 the Power of Two Random Choices and is described here :
3936 http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
Willy Tarreau760e81d2018-05-03 07:20:40 +02003937
Emeric Brun736aa232009-06-30 17:56:00 +02003938 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02003939 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02003940 The RDP cookie <name> (or "mstshash" if omitted) will be
3941 looked up and hashed for each incoming TCP request. Just as
3942 with the equivalent ACL 'req_rdp_cookie()' function, the name
3943 is not case-sensitive. This mechanism is useful as a degraded
3944 persistence mode, as it makes it possible to always send the
3945 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003946 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02003947 used instead.
3948
3949 Note that for this to work, the frontend must ensure that an
3950 RDP cookie is already present in the request buffer. For this
3951 you must use 'tcp-request content accept' rule combined with
3952 a 'req_rdp_cookie_cnt' ACL.
3953
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003954 This algorithm is static by default, which means that
3955 changing a server's weight on the fly will have no effect,
3956 but this can be changed using "hash-type".
3957
Cyril Bontédc4d9032012-04-08 21:57:39 +02003958 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09003959
Willy Tarreau0ba27502007-12-24 16:55:16 +01003960 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02003961 algorithms. Right now, only "url_param" and "uri" support an
3962 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003963
Willy Tarreau3cd9af22009-03-15 14:06:41 +01003964 The load balancing algorithm of a backend is set to roundrobin when no other
3965 algorithm, mode nor option have been set. The algorithm may only be set once
3966 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003967
Lukas Tribus80512b12018-10-27 20:07:40 +02003968 With authentication schemes that require the same connection like NTLM, URI
John Roeslerfb2fce12019-07-10 15:45:51 -05003969 based algorithms must not be used, as they would cause subsequent requests
Lukas Tribus80512b12018-10-27 20:07:40 +02003970 to be routed to different backend servers, breaking the invalid assumptions
3971 NTLM relies on.
3972
Willy Tarreau0ba27502007-12-24 16:55:16 +01003973 Examples :
3974 balance roundrobin
3975 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003976 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01003977 balance hdr(User-Agent)
3978 balance hdr(host)
3979 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003980
3981 Note: the following caveats and limitations on using the "check_post"
3982 extension with "url_param" must be considered :
3983
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003984 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003985 to determine if the parameters will be found in the body or entity which
3986 may contain binary data. Therefore another method may be required to
3987 restrict consideration of POST requests that have no URL parameters in
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02003988 the body. (see acl http_end)
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003989
3990 - using a <max_wait> value larger than the request buffer size does not
3991 make sense and is useless. The buffer size is set at build time, and
3992 defaults to 16 kB.
3993
3994 - Content-Encoding is not supported, the parameter search will probably
3995 fail; and load balancing will fall back to Round Robin.
3996
3997 - Expect: 100-continue is not supported, load balancing will fall back to
3998 Round Robin.
3999
Lukas Tribus23953682017-04-28 13:24:30 +00004000 - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02004001 If the entire parameter value is not present in the first chunk, the
4002 selection of server is undefined (actually, defined by how little
4003 actually appeared in the first chunk).
4004
4005 - This feature does not support generation of a 100, 411 or 501 response.
4006
4007 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004008 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02004009 white space or control characters are found, indicating the end of what
4010 might be a URL parameter list. This is probably not a concern with SGML
4011 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004012
Willy Tarreau294d0f02015-08-10 19:40:12 +02004013 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01004014
4015
Willy Tarreaub6205fd2012-09-24 12:27:33 +02004016bind [<address>]:<port_range> [, ...] [param*]
4017bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01004018 Define one or several listening addresses and/or ports in a frontend.
4019 May be used in sections : defaults | frontend | listen | backend
4020 no | yes | yes | no
4021 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01004022 <address> is optional and can be a host name, an IPv4 address, an IPv6
4023 address, or '*'. It designates the address the frontend will
4024 listen on. If unset, all IPv4 addresses of the system will be
4025 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01004026 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01004027 Optionally, an address family prefix may be used before the
4028 address to force the family regardless of the address format,
4029 which can be useful to specify a path to a unix socket with
4030 no slash ('/'). Currently supported prefixes are :
4031 - 'ipv4@' -> address is always IPv4
4032 - 'ipv6@' -> address is always IPv6
Emeric Brun3835c0d2020-07-07 09:46:09 +02004033 - 'udp@' -> address is resolved as IPv4 or IPv6 and
Emeric Brun12941c82020-07-07 14:19:42 +02004034 protocol UDP is used. Currently those listeners are
4035 supported only in log-forward sections.
Emeric Brun3835c0d2020-07-07 09:46:09 +02004036 - 'udp4@' -> address is always IPv4 and protocol UDP
Emeric Brun12941c82020-07-07 14:19:42 +02004037 is used. Currently those listeners are supported
4038 only in log-forward sections.
Emeric Brun3835c0d2020-07-07 09:46:09 +02004039 - 'udp6@' -> address is always IPv6 and protocol UDP
Emeric Brun12941c82020-07-07 14:19:42 +02004040 is used. Currently those listeners are supported
4041 only in log-forward sections.
Willy Tarreau24709282013-03-10 21:32:12 +01004042 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02004043 - 'abns@' -> address is in abstract namespace (Linux only).
4044 Note: since abstract sockets are not "rebindable", they
4045 do not cope well with multi-process mode during
4046 soft-restart, so it is better to avoid them if
4047 nbproc is greater than 1. The effect is that if the
4048 new process fails to start, only one of the old ones
4049 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01004050 - 'fd@<n>' -> use file descriptor <n> inherited from the
4051 parent. The fd must be bound and may or may not already
4052 be listening.
William Lallemand2fe7dd02018-09-11 16:51:29 +02004053 - 'sockpair@<n>'-> like fd@ but you must use the fd of a
4054 connected unix socket or of a socketpair. The bind waits
4055 to receive a FD over the unix socket and uses it as if it
4056 was the FD of an accept(). Should be used carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02004057 You may want to reference some environment variables in the
4058 address parameter, see section 2.3 about environment
4059 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01004060
Willy Tarreauc5011ca2010-03-22 11:53:56 +01004061 <port_range> is either a unique TCP port, or a port range for which the
4062 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01004063 above. The port is mandatory for TCP listeners. Note that in
4064 the case of an IPv6 address, the port is always the number
4065 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01004066 - a numerical port (ex: '80')
4067 - a dash-delimited ports range explicitly stating the lower
4068 and upper bounds (ex: '2000-2100') which are included in
4069 the range.
4070
4071 Particular care must be taken against port ranges, because
4072 every <address:port> couple consumes one socket (= a file
4073 descriptor), so it's easy to consume lots of descriptors
4074 with a simple range, and to run out of sockets. Also, each
4075 <address:port> couple must be used only once among all
4076 instances running on a same system. Please note that binding
4077 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04004078 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01004079 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004080
Willy Tarreauceb24bc2010-11-09 12:46:41 +01004081 <path> is a UNIX socket path beginning with a slash ('/'). This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01004082 alternative to the TCP listening port. HAProxy will then
Willy Tarreauceb24bc2010-11-09 12:46:41 +01004083 receive UNIX connections on the socket located at this place.
4084 The path must begin with a slash and by default is absolute.
4085 It can be relative to the prefix defined by "unix-bind" in
4086 the global section. Note that the total length of the prefix
4087 followed by the socket path cannot exceed some system limits
4088 for UNIX sockets, which commonly are set to 107 characters.
4089
Willy Tarreaub6205fd2012-09-24 12:27:33 +02004090 <param*> is a list of parameters common to all sockets declared on the
4091 same line. These numerous parameters depend on OS and build
4092 options and have a complete section dedicated to them. Please
4093 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02004094
Willy Tarreau0ba27502007-12-24 16:55:16 +01004095 It is possible to specify a list of address:port combinations delimited by
4096 commas. The frontend will then listen on all of these addresses. There is no
4097 fixed limit to the number of addresses and ports which can be listened on in
4098 a frontend, as well as there is no limit to the number of "bind" statements
4099 in a frontend.
4100
4101 Example :
4102 listen http_proxy
4103 bind :80,:443
4104 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01004105 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01004106
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02004107 listen http_https_proxy
4108 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02004109 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02004110
Willy Tarreau24709282013-03-10 21:32:12 +01004111 listen http_https_proxy_explicit
4112 bind ipv6@:80
4113 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
4114 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
4115
Willy Tarreaudad36a32013-03-11 01:20:04 +01004116 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02004117 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01004118
Willy Tarreau55dcaf62015-09-27 15:03:15 +02004119 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
4120 sun_path length is used for the address length. Some other programs
4121 such as socat use the string length only by default. Pass the option
4122 ",unix-tightsocklen=0" to any abstract socket definition in socat to
4123 make it compatible with HAProxy's.
4124
Willy Tarreauceb24bc2010-11-09 12:46:41 +01004125 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02004126 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004127
4128
Christopher Fauletff4121f2017-11-22 16:38:49 +01004129bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004130 Limit visibility of an instance to a certain set of processes numbers.
4131 May be used in sections : defaults | frontend | listen | backend
4132 yes | yes | yes | yes
4133 Arguments :
4134 all All process will see this instance. This is the default. It
4135 may be used to override a default value.
4136
Willy Tarreaua9db57e2013-01-18 11:29:29 +01004137 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004138 option may be combined with other numbers.
4139
Willy Tarreaua9db57e2013-01-18 11:29:29 +01004140 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004141 option may be combined with other numbers. Do not use it
4142 with less than 2 processes otherwise some instances might be
4143 missing from all processes.
4144
Christopher Fauletff4121f2017-11-22 16:38:49 +01004145 process_num The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01004146 whose values must all be between 1 and 32 or 64 depending on
Christopher Fauletff4121f2017-11-22 16:38:49 +01004147 the machine's word size. Ranges can be partially defined. The
4148 higher bound can be omitted. In such case, it is replaced by
4149 the corresponding maximum value. If a proxy is bound to
4150 process numbers greater than the configured global.nbproc, it
4151 will either be forced to process #1 if a single process was
Willy Tarreau102df612014-05-07 23:56:38 +02004152 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004153
4154 This keyword limits binding of certain instances to certain processes. This
4155 is useful in order not to have too many processes listening to the same
4156 ports. For instance, on a dual-core machine, it might make sense to set
4157 'nbproc 2' in the global section, then distributes the listeners among 'odd'
4158 and 'even' instances.
4159
Willy Tarreaua9db57e2013-01-18 11:29:29 +01004160 At the moment, it is not possible to reference more than 32 or 64 processes
4161 using this keyword, but this should be more than enough for most setups.
4162 Please note that 'all' really means all processes regardless of the machine's
4163 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004164
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02004165 Each "bind" line may further be limited to a subset of the proxy's processes,
4166 please consult the "process" bind keyword in section 5.1.
4167
Willy Tarreaub369a042014-09-16 13:21:03 +02004168 When a frontend has no explicit "bind-process" line, it tries to bind to all
4169 the processes referenced by its "bind" lines. That means that frontends can
4170 easily adapt to their listeners' processes.
4171
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004172 If some backends are referenced by frontends bound to other processes, the
4173 backend automatically inherits the frontend's processes.
4174
4175 Example :
4176 listen app_ip1
4177 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02004178 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004179
4180 listen app_ip2
4181 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02004182 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004183
4184 listen management
4185 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02004186 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004187
Willy Tarreau110ecc12012-11-15 17:50:01 +01004188 listen management
4189 bind 10.0.0.4:80
4190 bind-process 1-4
4191
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02004192 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01004193
4194
Willy Tarreau0ba27502007-12-24 16:55:16 +01004195capture cookie <name> len <length>
4196 Capture and log a cookie in the request and in the response.
4197 May be used in sections : defaults | frontend | listen | backend
4198 no | yes | yes | no
4199 Arguments :
4200 <name> is the beginning of the name of the cookie to capture. In order
4201 to match the exact name, simply suffix the name with an equal
4202 sign ('='). The full name will appear in the logs, which is
4203 useful with application servers which adjust both the cookie name
Davor Ocelice9ed2812017-12-25 17:49:28 +01004204 and value (e.g. ASPSESSIONXXX).
Willy Tarreau0ba27502007-12-24 16:55:16 +01004205
4206 <length> is the maximum number of characters to report in the logs, which
4207 include the cookie name, the equal sign and the value, all in the
4208 standard "name=value" form. The string will be truncated on the
4209 right if it exceeds <length>.
4210
4211 Only the first cookie is captured. Both the "cookie" request headers and the
4212 "set-cookie" response headers are monitored. This is particularly useful to
4213 check for application bugs causing session crossing or stealing between
4214 users, because generally the user's cookies can only change on a login page.
4215
4216 When the cookie was not presented by the client, the associated log column
4217 will report "-". When a request does not cause a cookie to be assigned by the
4218 server, a "-" is reported in the response column.
4219
4220 The capture is performed in the frontend only because it is necessary that
4221 the log format does not change for a given frontend depending on the
4222 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01004223 "capture cookie" statement in a frontend. The maximum capture length is set
4224 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
4225 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004226
4227 Example:
4228 capture cookie ASPSESSION len 32
4229
4230 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004231 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004232
4233
4234capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01004235 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004236 May be used in sections : defaults | frontend | listen | backend
4237 no | yes | yes | no
4238 Arguments :
4239 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004240 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01004241 appear in the requests, with the first letter of each word in
4242 upper case. The header name will not appear in the logs, only the
4243 value is reported, but the position in the logs is respected.
4244
4245 <length> is the maximum number of characters to extract from the value and
4246 report in the logs. The string will be truncated on the right if
4247 it exceeds <length>.
4248
Willy Tarreau4460d032012-11-21 23:37:37 +01004249 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01004250 value will be added to the logs between braces ('{}'). If multiple headers
4251 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01004252 in the same order they were declared in the configuration. Non-existent
4253 headers will be logged just as an empty string. Common uses for request
4254 header captures include the "Host" field in virtual hosting environments, the
4255 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004256 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01004257 environments to find where the request came from.
4258
4259 Note that when capturing headers such as "User-agent", some spaces may be
4260 logged, making the log analysis more difficult. Thus be careful about what
4261 you log if you know your log parser is not smart enough to rely on the
4262 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004263
Willy Tarreau0900abb2012-11-22 00:21:46 +01004264 There is no limit to the number of captured request headers nor to their
4265 length, though it is wise to keep them low to limit memory usage per session.
4266 In order to keep log format consistent for a same frontend, header captures
4267 can only be declared in a frontend. It is not possible to specify a capture
4268 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004269
4270 Example:
4271 capture request header Host len 15
4272 capture request header X-Forwarded-For len 15
Cyril Bontéd1b0f7c2015-10-26 22:37:39 +01004273 capture request header Referer len 15
Willy Tarreau0ba27502007-12-24 16:55:16 +01004274
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004275 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01004276 about logging.
4277
4278
4279capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01004280 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004281 May be used in sections : defaults | frontend | listen | backend
4282 no | yes | yes | no
4283 Arguments :
4284 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004285 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01004286 appear in the response, with the first letter of each word in
4287 upper case. The header name will not appear in the logs, only the
4288 value is reported, but the position in the logs is respected.
4289
4290 <length> is the maximum number of characters to extract from the value and
4291 report in the logs. The string will be truncated on the right if
4292 it exceeds <length>.
4293
Willy Tarreau4460d032012-11-21 23:37:37 +01004294 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01004295 result will be added to the logs between braces ('{}') after the captured
4296 request headers. If multiple headers are captured, they will be delimited by
4297 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01004298 the configuration. Non-existent headers will be logged just as an empty
4299 string. Common uses for response header captures include the "Content-length"
4300 header which indicates how many bytes are expected to be returned, the
4301 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004302
Willy Tarreau0900abb2012-11-22 00:21:46 +01004303 There is no limit to the number of captured response headers nor to their
4304 length, though it is wise to keep them low to limit memory usage per session.
4305 In order to keep log format consistent for a same frontend, header captures
4306 can only be declared in a frontend. It is not possible to specify a capture
4307 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004308
4309 Example:
4310 capture response header Content-length len 9
4311 capture response header Location len 15
4312
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004313 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01004314 about logging.
4315
4316
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09004317clitcpka-cnt <count>
4318 Sets the maximum number of keepalive probes TCP should send before dropping
4319 the connection on the client side.
4320 May be used in sections : defaults | frontend | listen | backend
4321 yes | yes | yes | no
4322 Arguments :
4323 <count> is the maximum number of keepalive probes.
4324
4325 This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword
4326 is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02004327 The availability of this setting depends on the operating system. It is
4328 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09004329
4330 See also : "option clitcpka", "clitcpka-idle", "clitcpka-intvl".
4331
4332
4333clitcpka-idle <timeout>
4334 Sets the time the connection needs to remain idle before TCP starts sending
4335 keepalive probes, if enabled the sending of TCP keepalive packets on the
4336 client side.
4337 May be used in sections : defaults | frontend | listen | backend
4338 yes | yes | yes | no
4339 Arguments :
4340 <timeout> is the time the connection needs to remain idle before TCP starts
4341 sending keepalive probes. It is specified in seconds by default,
4342 but can be in any other unit if the number is suffixed by the
4343 unit, as explained at the top of this document.
4344
4345 This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword
4346 is not specified, system-wide TCP parameter (tcp_keepalive_time) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02004347 The availability of this setting depends on the operating system. It is
4348 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09004349
4350 See also : "option clitcpka", "clitcpka-cnt", "clitcpka-intvl".
4351
4352
4353clitcpka-intvl <timeout>
4354 Sets the time between individual keepalive probes on the client side.
4355 May be used in sections : defaults | frontend | listen | backend
4356 yes | yes | yes | no
4357 Arguments :
4358 <timeout> is the time between individual keepalive probes. It is specified
4359 in seconds by default, but can be in any other unit if the number
4360 is suffixed by the unit, as explained at the top of this
4361 document.
4362
4363 This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword
4364 is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02004365 The availability of this setting depends on the operating system. It is
4366 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09004367
4368 See also : "option clitcpka", "clitcpka-cnt", "clitcpka-idle".
4369
4370
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004371compression algo <algorithm> ...
4372compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02004373compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02004374 Enable HTTP compression.
4375 May be used in sections : defaults | frontend | listen | backend
4376 yes | yes | yes | yes
4377 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004378 algo is followed by the list of supported compression algorithms.
4379 type is followed by the list of MIME types that will be compressed.
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004380 offload makes HAProxy work as a compression offloader only (see notes).
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004381
4382 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01004383 identity this is mostly for debugging, and it was useful for developing
4384 the compression feature. Identity does not apply any change on
4385 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004386
Willy Tarreauc91840a2015-03-28 17:00:39 +01004387 gzip applies gzip compression. This setting is only available when
Baptiste Assmannf085d632015-12-21 17:57:32 +01004388 support for zlib or libslz was built in.
Willy Tarreauc91840a2015-03-28 17:00:39 +01004389
4390 deflate same as "gzip", but with deflate algorithm and zlib format.
4391 Note that this algorithm has ambiguous support on many
4392 browsers and no support at all from recent ones. It is
4393 strongly recommended not to use it for anything else than
4394 experimentation. This setting is only available when support
Baptiste Assmannf085d632015-12-21 17:57:32 +01004395 for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004396
Willy Tarreauc91840a2015-03-28 17:00:39 +01004397 raw-deflate same as "deflate" without the zlib wrapper, and used as an
4398 alternative when the browser wants "deflate". All major
4399 browsers understand it and despite violating the standards,
4400 it is known to work better than "deflate", at least on MSIE
4401 and some versions of Safari. Do not use it in conjunction
4402 with "deflate", use either one or the other since both react
4403 to the same Accept-Encoding token. This setting is only
Baptiste Assmannf085d632015-12-21 17:57:32 +01004404 available when support for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004405
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04004406 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01004407 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04004408 If backend servers support HTTP compression, these directives
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004409 will be no-op: HAProxy will see the compressed response and will not
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04004410 compress again. If backend servers do not support HTTP compression and
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004411 there is Accept-Encoding header in request, HAProxy will compress the
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04004412 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02004413
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004414 The "offload" setting makes HAProxy remove the Accept-Encoding header to
Willy Tarreau70737d12012-10-27 00:34:28 +02004415 prevent backend servers from compressing responses. It is strongly
4416 recommended not to do this because this means that all the compression work
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004417 will be done on the single point where HAProxy is located. However in some
4418 deployment scenarios, HAProxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04004419 with broken HTTP compression implementation which can't be turned off.
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004420 In that case HAProxy can be used to prevent that gateway from emitting
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04004421 invalid payloads. In this case, simply removing the header in the
4422 configuration does not work because it applies before the header is parsed,
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004423 so that prevents HAProxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02004424 then be used for such scenarios. Note: for now, the "offload" setting is
4425 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02004426
William Lallemand05097442012-11-20 12:14:28 +01004427 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01004428 * the request does not advertise a supported compression algorithm in the
4429 "Accept-Encoding" header
Julien Pivottoff80c822021-03-29 12:41:40 +02004430 * the response message is not HTTP/1.1 or above
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01004431 * HTTP status code is not one of 200, 201, 202, or 203
Baptiste Assmann650d53d2013-01-05 15:44:44 +01004432 * response contain neither a "Content-Length" header nor a
4433 "Transfer-Encoding" whose last value is "chunked"
4434 * response contains a "Content-Type" header whose first value starts with
4435 "multipart"
4436 * the response contains the "no-transform" value in the "Cache-control"
4437 header
4438 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
4439 and later
4440 * The response contains a "Content-Encoding" header, indicating that the
4441 response is already compressed (see compression offload)
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01004442 * The response contains an invalid "ETag" header or multiple ETag headers
William Lallemand05097442012-11-20 12:14:28 +01004443
Tim Duesterhusb229f012019-01-29 16:38:56 +01004444 Note: The compression does not emit the Warning header.
William Lallemand05097442012-11-20 12:14:28 +01004445
William Lallemand82fe75c2012-10-23 10:25:10 +02004446 Examples :
4447 compression algo gzip
4448 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01004449
Christopher Fauletc3fe5332016-04-07 15:30:10 +02004450
Willy Tarreau55165fe2009-05-10 12:02:55 +02004451cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02004452 [ postonly ] [ preserve ] [ httponly ] [ secure ]
4453 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Christopher Faulet2f533902020-01-21 11:06:48 +01004454 [ dynamic ] [ attr <value> ]*
Willy Tarreau0ba27502007-12-24 16:55:16 +01004455 Enable cookie-based persistence in a backend.
4456 May be used in sections : defaults | frontend | listen | backend
4457 yes | no | yes | yes
4458 Arguments :
4459 <name> is the name of the cookie which will be monitored, modified or
4460 inserted in order to bring persistence. This cookie is sent to
4461 the client via a "Set-Cookie" header in the response, and is
4462 brought back by the client in a "Cookie" header in all requests.
4463 Special care should be taken to choose a name which does not
4464 conflict with any likely application cookie. Also, if the same
Davor Ocelice9ed2812017-12-25 17:49:28 +01004465 backends are subject to be used by the same clients (e.g.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004466 HTTP/HTTPS), care should be taken to use different cookie names
4467 between all backends if persistence between them is not desired.
4468
4469 rewrite This keyword indicates that the cookie will be provided by the
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004470 server and that HAProxy will have to modify its value to set the
Willy Tarreau0ba27502007-12-24 16:55:16 +01004471 server's identifier in it. This mode is handy when the management
4472 of complex combinations of "Set-cookie" and "Cache-control"
4473 headers is left to the application. The application can then
4474 decide whether or not it is appropriate to emit a persistence
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01004475 cookie. Since all responses should be monitored, this mode
4476 doesn't work in HTTP tunnel mode. Unless the application
Davor Ocelice9ed2812017-12-25 17:49:28 +01004477 behavior is very complex and/or broken, it is advised not to
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01004478 start with this mode for new deployments. This keyword is
4479 incompatible with "insert" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01004480
4481 insert This keyword indicates that the persistence cookie will have to
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004482 be inserted by HAProxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004483
Willy Tarreaua79094d2010-08-31 22:54:15 +02004484 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004485 server. When used without the "preserve" option, if the server
Michael Prokop4438c602019-05-24 10:25:45 +02004486 emits a cookie with the same name, it will be removed before
Davor Ocelice9ed2812017-12-25 17:49:28 +01004487 processing. For this reason, this mode can be used to upgrade
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004488 existing configurations running in the "rewrite" mode. The cookie
4489 will only be a session cookie and will not be stored on the
4490 client's disk. By default, unless the "indirect" option is added,
4491 the server will see the cookies emitted by the client. Due to
4492 caching effects, it is generally wise to add the "nocache" or
4493 "postonly" keywords (see below). The "insert" keyword is not
4494 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01004495
4496 prefix This keyword indicates that instead of relying on a dedicated
4497 cookie for the persistence, an existing one will be completed.
4498 This may be needed in some specific environments where the client
4499 does not support more than one single cookie and the application
4500 already needs it. In this case, whenever the server sets a cookie
4501 named <name>, it will be prefixed with the server's identifier
4502 and a delimiter. The prefix will be removed from all client
4503 requests so that the server still finds the cookie it emitted.
4504 Since all requests and responses are subject to being modified,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01004505 this mode doesn't work with tunnel mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02004506 not compatible with "rewrite" and "insert". Note: it is highly
4507 recommended not to use "indirect" with "prefix", otherwise server
4508 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004509
Willy Tarreaua79094d2010-08-31 22:54:15 +02004510 indirect When this option is specified, no cookie will be emitted to a
4511 client which already has a valid one for the server which has
4512 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004513 it will be removed, unless the "preserve" option is also set. In
4514 "insert" mode, this will additionally remove cookies from the
4515 requests transmitted to the server, making the persistence
4516 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02004517 Note: it is highly recommended not to use "indirect" with
4518 "prefix", otherwise server cookie updates would not be sent to
4519 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004520
4521 nocache This option is recommended in conjunction with the insert mode
4522 when there is a cache between the client and HAProxy, as it
4523 ensures that a cacheable response will be tagged non-cacheable if
4524 a cookie needs to be inserted. This is important because if all
4525 persistence cookies are added on a cacheable home page for
4526 instance, then all customers will then fetch the page from an
4527 outer cache and will all share the same persistence cookie,
4528 leading to one server receiving much more traffic than others.
4529 See also the "insert" and "postonly" options.
4530
4531 postonly This option ensures that cookie insertion will only be performed
4532 on responses to POST requests. It is an alternative to the
4533 "nocache" option, because POST responses are not cacheable, so
4534 this ensures that the persistence cookie will never get cached.
4535 Since most sites do not need any sort of persistence before the
4536 first POST which generally is a login request, this is a very
4537 efficient method to optimize caching without risking to find a
4538 persistence cookie in the cache.
4539 See also the "insert" and "nocache" options.
4540
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004541 preserve This option may only be used with "insert" and/or "indirect". It
4542 allows the server to emit the persistence cookie itself. In this
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004543 case, if a cookie is found in the response, HAProxy will leave it
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004544 untouched. This is useful in order to end persistence after a
4545 logout request for instance. For this, the server just has to
Davor Ocelice9ed2812017-12-25 17:49:28 +01004546 emit a cookie with an invalid value (e.g. empty) or with a date in
Willy Tarreauba4c5be2010-10-23 12:46:42 +02004547 the past. By combining this mechanism with the "disable-on-404"
4548 check option, it is possible to perform a completely graceful
4549 shutdown because users will definitely leave the server after
4550 they logout.
4551
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004552 httponly This option tells HAProxy to add an "HttpOnly" cookie attribute
Willy Tarreau4992dd22012-05-31 21:02:17 +02004553 when a cookie is inserted. This attribute is used so that a
4554 user agent doesn't share the cookie with non-HTTP components.
4555 Please check RFC6265 for more information on this attribute.
4556
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004557 secure This option tells HAProxy to add a "Secure" cookie attribute when
Willy Tarreau4992dd22012-05-31 21:02:17 +02004558 a cookie is inserted. This attribute is used so that a user agent
4559 never emits this cookie over non-secure channels, which means
4560 that a cookie learned with this flag will be presented only over
4561 SSL/TLS connections. Please check RFC6265 for more information on
4562 this attribute.
4563
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02004564 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004565 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01004566 name. If the domain begins with a dot, the browser is allowed to
4567 use it for any host ending with that name. It is also possible to
4568 specify several domain names by invoking this option multiple
4569 times. Some browsers might have small limits on the number of
4570 domains, so be careful when doing that. For the record, sending
4571 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02004572
Willy Tarreau996a92c2010-10-13 19:30:47 +02004573 maxidle This option allows inserted cookies to be ignored after some idle
4574 time. It only works with insert-mode cookies. When a cookie is
4575 sent to the client, the date this cookie was emitted is sent too.
4576 Upon further presentations of this cookie, if the date is older
4577 than the delay indicated by the parameter (in seconds), it will
4578 be ignored. Otherwise, it will be refreshed if needed when the
4579 response is sent to the client. This is particularly useful to
4580 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01004581 too long on the same server (e.g. after a farm size change). When
Willy Tarreau996a92c2010-10-13 19:30:47 +02004582 this option is set and a cookie has no date, it is always
4583 accepted, but gets refreshed in the response. This maintains the
4584 ability for admins to access their sites. Cookies that have a
4585 date in the future further than 24 hours are ignored. Doing so
4586 lets admins fix timezone issues without risking kicking users off
4587 the site.
4588
4589 maxlife This option allows inserted cookies to be ignored after some life
4590 time, whether they're in use or not. It only works with insert
4591 mode cookies. When a cookie is first sent to the client, the date
4592 this cookie was emitted is sent too. Upon further presentations
4593 of this cookie, if the date is older than the delay indicated by
4594 the parameter (in seconds), it will be ignored. If the cookie in
4595 the request has no date, it is accepted and a date will be set.
4596 Cookies that have a date in the future further than 24 hours are
4597 ignored. Doing so lets admins fix timezone issues without risking
4598 kicking users off the site. Contrary to maxidle, this value is
4599 not refreshed, only the first visit date counts. Both maxidle and
4600 maxlife may be used at the time. This is particularly useful to
4601 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01004602 too long on the same server (e.g. after a farm size change). This
Willy Tarreau996a92c2010-10-13 19:30:47 +02004603 is stronger than the maxidle method in that it forces a
4604 redispatch after some absolute delay.
4605
Olivier Houchard4e694042017-03-14 20:01:29 +01004606 dynamic Activate dynamic cookies. When used, a session cookie is
4607 dynamically created for each server, based on the IP and port
4608 of the server, and a secret key, specified in the
4609 "dynamic-cookie-key" backend directive.
4610 The cookie will be regenerated each time the IP address change,
4611 and is only generated for IPv4/IPv6.
4612
Daniel Corbett9f0843f2021-05-08 10:50:37 -04004613 attr This option tells HAProxy to add an extra attribute when a
Christopher Faulet2f533902020-01-21 11:06:48 +01004614 cookie is inserted. The attribute value can contain any
4615 characters except control ones or ";". This option may be
4616 repeated.
4617
Willy Tarreau0ba27502007-12-24 16:55:16 +01004618 There can be only one persistence cookie per HTTP backend, and it can be
4619 declared in a defaults section. The value of the cookie will be the value
4620 indicated after the "cookie" keyword in a "server" statement. If no cookie
4621 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02004622
Willy Tarreau0ba27502007-12-24 16:55:16 +01004623 Examples :
4624 cookie JSESSIONID prefix
4625 cookie SRV insert indirect nocache
4626 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02004627 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01004628
Willy Tarreau294d0f02015-08-10 19:40:12 +02004629 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01004630
Willy Tarreau983e01e2010-01-11 18:42:06 +01004631
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02004632declare capture [ request | response ] len <length>
4633 Declares a capture slot.
4634 May be used in sections : defaults | frontend | listen | backend
4635 no | yes | yes | no
4636 Arguments:
4637 <length> is the length allowed for the capture.
4638
4639 This declaration is only available in the frontend or listen section, but the
4640 reserved slot can be used in the backends. The "request" keyword allocates a
4641 capture slot for use in the request, and "response" allocates a capture slot
4642 for use in the response.
4643
4644 See also: "capture-req", "capture-res" (sample converters),
Baptiste Assmann5ac425c2015-10-21 23:13:46 +02004645 "capture.req.hdr", "capture.res.hdr" (sample fetches),
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02004646 "http-request capture" and "http-response capture".
4647
4648
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004649default-server [param*]
4650 Change default options for a server in a backend
4651 May be used in sections : defaults | frontend | listen | backend
4652 yes | no | yes | yes
4653 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01004654 <param*> is a list of parameters for this server. The "default-server"
4655 keyword accepts an important number of options and has a complete
4656 section dedicated to it. Please refer to section 5 for more
4657 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004658
Willy Tarreau983e01e2010-01-11 18:42:06 +01004659 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004660 default-server inter 1000 weight 13
4661
4662 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01004663
Willy Tarreau983e01e2010-01-11 18:42:06 +01004664
Willy Tarreau0ba27502007-12-24 16:55:16 +01004665default_backend <backend>
4666 Specify the backend to use when no "use_backend" rule has been matched.
4667 May be used in sections : defaults | frontend | listen | backend
4668 yes | yes | yes | no
4669 Arguments :
4670 <backend> is the name of the backend to use.
4671
4672 When doing content-switching between frontend and backends using the
4673 "use_backend" keyword, it is often useful to indicate which backend will be
4674 used when no rule has matched. It generally is the dynamic backend which
4675 will catch all undetermined requests.
4676
Willy Tarreau0ba27502007-12-24 16:55:16 +01004677 Example :
4678
4679 use_backend dynamic if url_dyn
4680 use_backend static if url_css url_img extension_img
4681 default_backend dynamic
4682
Willy Tarreau98d04852015-05-26 12:18:29 +02004683 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004684
Willy Tarreau0ba27502007-12-24 16:55:16 +01004685
Baptiste Assmann27f51342013-10-09 06:51:49 +02004686description <string>
4687 Describe a listen, frontend or backend.
4688 May be used in sections : defaults | frontend | listen | backend
4689 no | yes | yes | yes
4690 Arguments : string
4691
4692 Allows to add a sentence to describe the related object in the HAProxy HTML
4693 stats page. The description will be printed on the right of the object name
4694 it describes.
4695 No need to backslash spaces in the <string> arguments.
4696
4697
Willy Tarreau0ba27502007-12-24 16:55:16 +01004698disabled
4699 Disable a proxy, frontend or backend.
4700 May be used in sections : defaults | frontend | listen | backend
4701 yes | yes | yes | yes
4702 Arguments : none
4703
4704 The "disabled" keyword is used to disable an instance, mainly in order to
4705 liberate a listening port or to temporarily disable a service. The instance
4706 will still be created and its configuration will be checked, but it will be
4707 created in the "stopped" state and will appear as such in the statistics. It
4708 will not receive any traffic nor will it send any health-checks or logs. It
4709 is possible to disable many instances at once by adding the "disabled"
4710 keyword in a "defaults" section.
4711
4712 See also : "enabled"
4713
4714
Willy Tarreau5ce94572010-06-07 14:35:41 +02004715dispatch <address>:<port>
4716 Set a default server address
4717 May be used in sections : defaults | frontend | listen | backend
4718 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004719 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02004720
4721 <address> is the IPv4 address of the default server. Alternatively, a
4722 resolvable hostname is supported, but this name will be resolved
4723 during start-up.
4724
4725 <ports> is a mandatory port specification. All connections will be sent
4726 to this port, and it is not permitted to use port offsets as is
4727 possible with normal servers.
4728
Willy Tarreau787aed52011-04-15 06:45:37 +02004729 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02004730 server can take the connection. In the past it was used to forward non
4731 persistent connections to an auxiliary load balancer. Due to its simple
4732 syntax, it has also been used for simple TCP relays. It is recommended not to
4733 use it for more clarity, and to use the "server" directive instead.
4734
4735 See also : "server"
4736
Olivier Houchard4e694042017-03-14 20:01:29 +01004737
4738dynamic-cookie-key <string>
4739 Set the dynamic cookie secret key for a backend.
4740 May be used in sections : defaults | frontend | listen | backend
4741 yes | no | yes | yes
4742 Arguments : The secret key to be used.
4743
4744 When dynamic cookies are enabled (see the "dynamic" directive for cookie),
Davor Ocelice9ed2812017-12-25 17:49:28 +01004745 a dynamic cookie is created for each server (unless one is explicitly
Olivier Houchard4e694042017-03-14 20:01:29 +01004746 specified on the "server" line), using a hash of the IP address of the
4747 server, the TCP port, and the secret key.
Davor Ocelice9ed2812017-12-25 17:49:28 +01004748 That way, we can ensure session persistence across multiple load-balancers,
Olivier Houchard4e694042017-03-14 20:01:29 +01004749 even if servers are dynamically added or removed.
Willy Tarreau5ce94572010-06-07 14:35:41 +02004750
Willy Tarreau0ba27502007-12-24 16:55:16 +01004751enabled
4752 Enable a proxy, frontend or backend.
4753 May be used in sections : defaults | frontend | listen | backend
4754 yes | yes | yes | yes
4755 Arguments : none
4756
4757 The "enabled" keyword is used to explicitly enable an instance, when the
4758 defaults has been set to "disabled". This is very rarely used.
4759
4760 See also : "disabled"
4761
4762
4763errorfile <code> <file>
4764 Return a file contents instead of errors generated by HAProxy
4765 May be used in sections : defaults | frontend | listen | backend
4766 yes | yes | yes | yes
4767 Arguments :
4768 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004769 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Christopher Faulete095f312020-12-07 11:22:24 +01004770 413, 425, 429, 500, 501, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004771
4772 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004773 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01004774 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01004775 error pages, and to use absolute paths, since files are read
4776 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004777
4778 It is important to understand that this keyword is not meant to rewrite
4779 errors returned by the server, but errors detected and returned by HAProxy.
4780 This is why the list of supported errors is limited to a small set.
4781
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004782 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
4783
Christopher Faulet70170672020-05-18 17:42:48 +02004784 The files are parsed when HAProxy starts and must be valid according to the
4785 HTTP specification. They should not exceed the configured buffer size
4786 (BUFSIZE), which generally is 16 kB, otherwise an internal error will be
4787 returned. It is also wise not to put any reference to local contents
4788 (e.g. images) in order to avoid loops between the client and HAProxy when all
4789 servers are down, causing an error to be returned instead of an
4790 image. Finally, The response cannot exceed (tune.bufsize - tune.maxrewrite)
4791 so that "http-after-response" rules still have room to operate (see
4792 "tune.maxrewrite").
Willy Tarreau59140a22009-02-22 12:02:30 +01004793
Willy Tarreau0ba27502007-12-24 16:55:16 +01004794 The files are read at the same time as the configuration and kept in memory.
4795 For this reason, the errors continue to be returned even when the process is
4796 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01004797 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01004798 403 status code and interrogating a blocked URL.
4799
Christopher Faulet3b967c12020-05-15 15:47:44 +02004800 See also : "http-error", "errorloc", "errorloc302", "errorloc303"
Willy Tarreau0ba27502007-12-24 16:55:16 +01004801
Willy Tarreau59140a22009-02-22 12:02:30 +01004802 Example :
4803 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau989222a2016-01-15 10:26:26 +01004804 errorfile 408 /dev/null # work around Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01004805 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
4806 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
4807
Willy Tarreau2769aa02007-12-27 18:26:09 +01004808
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004809errorfiles <name> [<code> ...]
4810 Import, fully or partially, the error files defined in the <name> http-errors
4811 section.
4812 May be used in sections : defaults | frontend | listen | backend
4813 yes | yes | yes | yes
4814 Arguments :
4815 <name> is the name of an existing http-errors section.
4816
4817 <code> is a HTTP status code. Several status code may be listed.
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004818 Currently, HAProxy is capable of generating codes 200, 400, 401,
Christopher Faulete095f312020-12-07 11:22:24 +01004819 403, 404, 405, 407, 408, 410, 413, 425, 429, 500, 501, 502, 503,
4820 and 504.
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004821
4822 Errors defined in the http-errors section with the name <name> are imported
4823 in the current proxy. If no status code is specified, all error files of the
4824 http-errors section are imported. Otherwise, only error files associated to
4825 the listed status code are imported. Those error files override the already
4826 defined custom errors for the proxy. And they may be overridden by following
Daniel Corbett67a82712020-07-06 23:01:19 -04004827 ones. Functionally, it is exactly the same as declaring all error files by
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004828 hand using "errorfile" directives.
4829
Christopher Faulet3b967c12020-05-15 15:47:44 +02004830 See also : "http-error", "errorfile", "errorloc", "errorloc302" ,
4831 "errorloc303" and section 3.8 about http-errors.
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004832
4833 Example :
4834 errorfiles generic
4835 errorfiles site-1 403 404
4836
4837
Willy Tarreau2769aa02007-12-27 18:26:09 +01004838errorloc <code> <url>
4839errorloc302 <code> <url>
4840 Return an HTTP redirection to a URL instead of errors generated by HAProxy
4841 May be used in sections : defaults | frontend | listen | backend
4842 yes | yes | yes | yes
4843 Arguments :
4844 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004845 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Christopher Faulete095f312020-12-07 11:22:24 +01004846 413, 425, 429, 500, 501, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004847
4848 <url> it is the exact contents of the "Location" header. It may contain
4849 either a relative URI to an error page hosted on the same site,
4850 or an absolute URI designating an error page on another site.
4851 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01004852 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01004853
4854 It is important to understand that this keyword is not meant to rewrite
4855 errors returned by the server, but errors detected and returned by HAProxy.
4856 This is why the list of supported errors is limited to a small set.
4857
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004858 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
4859
Willy Tarreau2769aa02007-12-27 18:26:09 +01004860 Note that both keyword return the HTTP 302 status code, which tells the
4861 client to fetch the designated URL using the same HTTP method. This can be
4862 quite problematic in case of non-GET methods such as POST, because the URL
4863 sent to the client might not be allowed for something other than GET. To
Willy Tarreau989222a2016-01-15 10:26:26 +01004864 work around this problem, please use "errorloc303" which send the HTTP 303
Willy Tarreau2769aa02007-12-27 18:26:09 +01004865 status code, indicating to the client that the URL must be fetched with a GET
4866 request.
4867
Christopher Faulet3b967c12020-05-15 15:47:44 +02004868 See also : "http-error", "errorfile", "errorloc303"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004869
4870
4871errorloc303 <code> <url>
4872 Return an HTTP redirection to a URL instead of errors generated by HAProxy
4873 May be used in sections : defaults | frontend | listen | backend
4874 yes | yes | yes | yes
4875 Arguments :
4876 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004877 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Christopher Faulete095f312020-12-07 11:22:24 +01004878 413, 425, 429, 500, 501, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004879
4880 <url> it is the exact contents of the "Location" header. It may contain
4881 either a relative URI to an error page hosted on the same site,
4882 or an absolute URI designating an error page on another site.
4883 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01004884 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01004885
4886 It is important to understand that this keyword is not meant to rewrite
4887 errors returned by the server, but errors detected and returned by HAProxy.
4888 This is why the list of supported errors is limited to a small set.
4889
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004890 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
4891
Willy Tarreau2769aa02007-12-27 18:26:09 +01004892 Note that both keyword return the HTTP 303 status code, which tells the
4893 client to fetch the designated URL using the same HTTP GET method. This
4894 solves the usual problems associated with "errorloc" and the 302 code. It is
4895 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004896 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004897
Christopher Faulet3b967c12020-05-15 15:47:44 +02004898 See also : "http-error", "errorfile", "errorloc", "errorloc302"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004899
4900
Simon Horman51a1cf62015-02-03 13:00:44 +09004901email-alert from <emailaddr>
4902 Declare the from email address to be used in both the envelope and header
Davor Ocelice9ed2812017-12-25 17:49:28 +01004903 of email alerts. This is the address that email alerts are sent from.
Simon Horman51a1cf62015-02-03 13:00:44 +09004904 May be used in sections: defaults | frontend | listen | backend
4905 yes | yes | yes | yes
4906
4907 Arguments :
4908
4909 <emailaddr> is the from email address to use when sending email alerts
4910
4911 Also requires "email-alert mailers" and "email-alert to" to be set
4912 and if so sending email alerts is enabled for the proxy.
4913
Simon Horman64e34162015-02-06 11:11:57 +09004914 See also : "email-alert level", "email-alert mailers",
Cyril Bonté307ee1e2015-09-28 23:16:06 +02004915 "email-alert myhostname", "email-alert to", section 3.6 about
4916 mailers.
Simon Horman64e34162015-02-06 11:11:57 +09004917
4918
4919email-alert level <level>
4920 Declare the maximum log level of messages for which email alerts will be
4921 sent. This acts as a filter on the sending of email alerts.
4922 May be used in sections: defaults | frontend | listen | backend
4923 yes | yes | yes | yes
4924
4925 Arguments :
4926
4927 <level> One of the 8 syslog levels:
4928 emerg alert crit err warning notice info debug
4929 The above syslog levels are ordered from lowest to highest.
4930
4931 By default level is alert
4932
4933 Also requires "email-alert from", "email-alert mailers" and
4934 "email-alert to" to be set and if so sending email alerts is enabled
4935 for the proxy.
4936
Simon Horman1421e212015-04-30 13:10:35 +09004937 Alerts are sent when :
4938
4939 * An un-paused server is marked as down and <level> is alert or lower
4940 * A paused server is marked as down and <level> is notice or lower
4941 * A server is marked as up or enters the drain state and <level>
4942 is notice or lower
4943 * "option log-health-checks" is enabled, <level> is info or lower,
4944 and a health check status update occurs
4945
Simon Horman64e34162015-02-06 11:11:57 +09004946 See also : "email-alert from", "email-alert mailers",
4947 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09004948 section 3.6 about mailers.
4949
4950
4951email-alert mailers <mailersect>
4952 Declare the mailers to be used when sending email alerts
4953 May be used in sections: defaults | frontend | listen | backend
4954 yes | yes | yes | yes
4955
4956 Arguments :
4957
4958 <mailersect> is the name of the mailers section to send email alerts.
4959
4960 Also requires "email-alert from" and "email-alert to" to be set
4961 and if so sending email alerts is enabled for the proxy.
4962
Simon Horman64e34162015-02-06 11:11:57 +09004963 See also : "email-alert from", "email-alert level", "email-alert myhostname",
4964 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09004965
4966
4967email-alert myhostname <hostname>
4968 Declare the to hostname address to be used when communicating with
4969 mailers.
4970 May be used in sections: defaults | frontend | listen | backend
4971 yes | yes | yes | yes
4972
4973 Arguments :
4974
Baptiste Assmann738bad92015-12-21 15:27:53 +01004975 <hostname> is the hostname to use when communicating with mailers
Simon Horman51a1cf62015-02-03 13:00:44 +09004976
4977 By default the systems hostname is used.
4978
4979 Also requires "email-alert from", "email-alert mailers" and
4980 "email-alert to" to be set and if so sending email alerts is enabled
4981 for the proxy.
4982
Simon Horman64e34162015-02-06 11:11:57 +09004983 See also : "email-alert from", "email-alert level", "email-alert mailers",
4984 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09004985
4986
4987email-alert to <emailaddr>
Davor Ocelice9ed2812017-12-25 17:49:28 +01004988 Declare both the recipient address in the envelope and to address in the
Simon Horman51a1cf62015-02-03 13:00:44 +09004989 header of email alerts. This is the address that email alerts are sent to.
4990 May be used in sections: defaults | frontend | listen | backend
4991 yes | yes | yes | yes
4992
4993 Arguments :
4994
4995 <emailaddr> is the to email address to use when sending email alerts
4996
4997 Also requires "email-alert mailers" and "email-alert to" to be set
4998 and if so sending email alerts is enabled for the proxy.
4999
Simon Horman64e34162015-02-06 11:11:57 +09005000 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09005001 "email-alert myhostname", section 3.6 about mailers.
5002
5003
Willy Tarreau4de91492010-01-22 19:10:05 +01005004force-persist { if | unless } <condition>
5005 Declare a condition to force persistence on down servers
5006 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01005007 no | no | yes | yes
Willy Tarreau4de91492010-01-22 19:10:05 +01005008
5009 By default, requests are not dispatched to down servers. It is possible to
5010 force this using "option persist", but it is unconditional and redispatches
5011 to a valid server if "option redispatch" is set. That leaves with very little
5012 possibilities to force some requests to reach a server which is artificially
5013 marked down for maintenance operations.
5014
5015 The "force-persist" statement allows one to declare various ACL-based
5016 conditions which, when met, will cause a request to ignore the down status of
5017 a server and still try to connect to it. That makes it possible to start a
5018 server, still replying an error to the health checks, and run a specially
5019 configured browser to test the service. Among the handy methods, one could
5020 use a specific source IP address, or a specific cookie. The cookie also has
5021 the advantage that it can easily be added/removed on the browser from a test
5022 page. Once the service is validated, it is then possible to open the service
5023 to the world by returning a valid response to health checks.
5024
5025 The forced persistence is enabled when an "if" condition is met, or unless an
5026 "unless" condition is met. The final redispatch is always disabled when this
5027 is used.
5028
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005029 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02005030 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01005031
Christopher Fauletc3fe5332016-04-07 15:30:10 +02005032
5033filter <name> [param*]
5034 Add the filter <name> in the filter list attached to the proxy.
5035 May be used in sections : defaults | frontend | listen | backend
5036 no | yes | yes | yes
5037 Arguments :
5038 <name> is the name of the filter. Officially supported filters are
5039 referenced in section 9.
5040
Tim Düsterhus4896c442016-11-29 02:15:19 +01005041 <param*> is a list of parameters accepted by the filter <name>. The
Christopher Fauletc3fe5332016-04-07 15:30:10 +02005042 parsing of these parameters are the responsibility of the
Tim Düsterhus4896c442016-11-29 02:15:19 +01005043 filter. Please refer to the documentation of the corresponding
5044 filter (section 9) for all details on the supported parameters.
Christopher Fauletc3fe5332016-04-07 15:30:10 +02005045
5046 Multiple occurrences of the filter line can be used for the same proxy. The
5047 same filter can be referenced many times if needed.
5048
5049 Example:
5050 listen
5051 bind *:80
5052
5053 filter trace name BEFORE-HTTP-COMP
5054 filter compression
5055 filter trace name AFTER-HTTP-COMP
5056
5057 compression algo gzip
5058 compression offload
5059
5060 server srv1 192.168.0.1:80
5061
5062 See also : section 9.
5063
Willy Tarreau4de91492010-01-22 19:10:05 +01005064
Willy Tarreau2769aa02007-12-27 18:26:09 +01005065fullconn <conns>
5066 Specify at what backend load the servers will reach their maxconn
5067 May be used in sections : defaults | frontend | listen | backend
5068 yes | no | yes | yes
5069 Arguments :
5070 <conns> is the number of connections on the backend which will make the
5071 servers use the maximal number of connections.
5072
Willy Tarreau198a7442008-01-17 12:05:32 +01005073 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01005074 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01005075 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01005076 load. The server will then always accept at least <minconn> connections,
5077 never more than <maxconn>, and the limit will be on the ramp between both
5078 values when the backend has less than <conns> concurrent connections. This
5079 makes it possible to limit the load on the servers during normal loads, but
5080 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005081 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005082
Daniel Corbett9f0843f2021-05-08 10:50:37 -04005083 Since it's hard to get this value right, HAProxy automatically sets it to
Willy Tarreaufbb78422011-06-05 15:38:35 +02005084 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01005085 backend (based on "use_backend" and "default_backend" rules). That way it's
5086 safe to leave it unset. However, "use_backend" involving dynamic names are
5087 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02005088
Willy Tarreau2769aa02007-12-27 18:26:09 +01005089 Example :
5090 # The servers will accept between 100 and 1000 concurrent connections each
5091 # and the maximum of 1000 will be reached when the backend reaches 10000
5092 # connections.
5093 backend dynamic
5094 fullconn 10000
5095 server srv1 dyn1:80 minconn 100 maxconn 1000
5096 server srv2 dyn2:80 minconn 100 maxconn 1000
5097
5098 See also : "maxconn", "server"
5099
5100
Willy Tarreauab0a5192020-10-09 19:07:01 +02005101grace <time> (deprecated)
Willy Tarreau2769aa02007-12-27 18:26:09 +01005102 Maintain a proxy operational for some time after a soft stop
5103 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01005104 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01005105 Arguments :
5106 <time> is the time (by default in milliseconds) for which the instance
5107 will remain operational with the frontend sockets still listening
5108 when a soft-stop is received via the SIGUSR1 signal.
5109
5110 This may be used to ensure that the services disappear in a certain order.
5111 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005112 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01005113 needed by the equipment to detect the failure.
5114
5115 Note that currently, there is very little benefit in using this parameter,
5116 and it may in fact complicate the soft-reconfiguration process more than
5117 simplify it.
5118
Willy Tarreau0ba27502007-12-24 16:55:16 +01005119
Andrew Rodland17be45e2016-10-25 17:04:12 -04005120hash-balance-factor <factor>
5121 Specify the balancing factor for bounded-load consistent hashing
5122 May be used in sections : defaults | frontend | listen | backend
5123 yes | no | no | yes
5124 Arguments :
5125 <factor> is the control for the maximum number of concurrent requests to
5126 send to a server, expressed as a percentage of the average number
Frédéric Lécaille93d33162019-03-06 09:35:59 +01005127 of concurrent requests across all of the active servers.
Andrew Rodland17be45e2016-10-25 17:04:12 -04005128
5129 Specifying a "hash-balance-factor" for a server with "hash-type consistent"
5130 enables an algorithm that prevents any one server from getting too many
5131 requests at once, even if some hash buckets receive many more requests than
5132 others. Setting <factor> to 0 (the default) disables the feature. Otherwise,
5133 <factor> is a percentage greater than 100. For example, if <factor> is 150,
5134 then no server will be allowed to have a load more than 1.5 times the average.
5135 If server weights are used, they will be respected.
5136
5137 If the first-choice server is disqualified, the algorithm will choose another
5138 server based on the request hash, until a server with additional capacity is
5139 found. A higher <factor> allows more imbalance between the servers, while a
5140 lower <factor> means that more servers will be checked on average, affecting
5141 performance. Reasonable values are from 125 to 200.
5142
Willy Tarreau760e81d2018-05-03 07:20:40 +02005143 This setting is also used by "balance random" which internally relies on the
5144 consistent hashing mechanism.
5145
Andrew Rodland17be45e2016-10-25 17:04:12 -04005146 See also : "balance" and "hash-type".
5147
5148
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05005149hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02005150 Specify a method to use for mapping hashes to servers
5151 May be used in sections : defaults | frontend | listen | backend
5152 yes | no | yes | yes
5153 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04005154 <method> is the method used to select a server from the hash computed by
5155 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02005156
Bhaskar98634f02013-10-29 23:30:51 -04005157 map-based the hash table is a static array containing all alive servers.
5158 The hashes will be very smooth, will consider weights, but
5159 will be static in that weight changes while a server is up
5160 will be ignored. This means that there will be no slow start.
5161 Also, since a server is selected by its position in the array,
5162 most mappings are changed when the server count changes. This
5163 means that when a server goes up or down, or when a server is
5164 added to a farm, most connections will be redistributed to
5165 different servers. This can be inconvenient with caches for
5166 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01005167
Bhaskar98634f02013-10-29 23:30:51 -04005168 consistent the hash table is a tree filled with many occurrences of each
5169 server. The hash key is looked up in the tree and the closest
5170 server is chosen. This hash is dynamic, it supports changing
5171 weights while the servers are up, so it is compatible with the
5172 slow start feature. It has the advantage that when a server
5173 goes up or down, only its associations are moved. When a
5174 server is added to the farm, only a few part of the mappings
5175 are redistributed, making it an ideal method for caches.
5176 However, due to its principle, the distribution will never be
5177 very smooth and it may sometimes be necessary to adjust a
5178 server's weight or its ID to get a more balanced distribution.
5179 In order to get the same distribution on multiple load
5180 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05005181 same IDs. Note: consistent hash uses sdbm and avalanche if no
5182 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04005183
5184 <function> is the hash function to be used :
5185
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005186 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04005187 reimplementation of ndbm) database library. It was found to do
5188 well in scrambling bits, causing better distribution of the keys
5189 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05005190 function with good distribution, unless the total server weight
5191 is a multiple of 64, in which case applying the avalanche
5192 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04005193
5194 djb2 this function was first proposed by Dan Bernstein many years ago
5195 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05005196 function provides a better distribution than sdbm. It generally
5197 works well with text-based inputs though it can perform extremely
5198 poorly with numeric-only input or when the total server weight is
5199 a multiple of 33, unless the avalanche modifier is also used.
5200
Daniel Corbett9f0843f2021-05-08 10:50:37 -04005201 wt6 this function was designed for HAProxy while testing other
Willy Tarreaua0f42712013-11-14 14:30:35 +01005202 functions in the past. It is not as smooth as the other ones, but
5203 is much less sensible to the input data set or to the number of
5204 servers. It can make sense as an alternative to sdbm+avalanche or
5205 djb2+avalanche for consistent hashing or when hashing on numeric
5206 data such as a source IP address or a visitor identifier in a URL
5207 parameter.
5208
Willy Tarreau324f07f2015-01-20 19:44:50 +01005209 crc32 this is the most common CRC32 implementation as used in Ethernet,
5210 gzip, PNG, etc. It is slower than the other ones but may provide
5211 a better distribution or less predictable results especially when
5212 used on strings.
5213
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05005214 <modifier> indicates an optional method applied after hashing the key :
5215
5216 avalanche This directive indicates that the result from the hash
5217 function above should not be used in its raw form but that
5218 a 4-byte full avalanche hash must be applied first. The
5219 purpose of this step is to mix the resulting bits from the
5220 previous hash in order to avoid any undesired effect when
5221 the input contains some limited values or when the number of
5222 servers is a multiple of one of the hash's components (64
5223 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
5224 result less predictable, but it's also not as smooth as when
5225 using the original function. Some testing might be needed
5226 with some workloads. This hash is one of the many proposed
5227 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02005228
Bhaskar98634f02013-10-29 23:30:51 -04005229 The default hash type is "map-based" and is recommended for most usages. The
5230 default function is "sdbm", the selection of a function should be based on
5231 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02005232
Andrew Rodland17be45e2016-10-25 17:04:12 -04005233 See also : "balance", "hash-balance-factor", "server"
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02005234
5235
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005236http-after-response <action> <options...> [ { if | unless } <condition> ]
5237 Access control for all Layer 7 responses (server, applet/service and internal
5238 ones).
5239
5240 May be used in sections: defaults | frontend | listen | backend
5241 no | yes | yes | yes
5242
5243 The http-after-response statement defines a set of rules which apply to layer
5244 7 processing. The rules are evaluated in their declaration order when they
5245 are met in a frontend, listen or backend section. Any rule may optionally be
5246 followed by an ACL-based condition, in which case it will only be evaluated
5247 if the condition is true. Since these rules apply on responses, the backend
5248 rules are applied first, followed by the frontend's rules.
5249
5250 Unlike http-response rules, these ones are applied on all responses, the
5251 server ones but also to all responses generated by HAProxy. These rules are
5252 evaluated at the end of the responses analysis, before the data forwarding.
5253
5254 The first keyword is the rule's action. The supported actions are described
5255 below.
5256
5257 There is no limit to the number of http-after-response statements per
5258 instance.
5259
Christopher Fauletd5ac6de2020-12-02 08:40:14 +01005260 Note: Errors emitted in early stage of the request parsing are handled by the
5261 multiplexer at a lower level, before any http analysis. Thus no
5262 http-after-response ruleset is evaluated on these errors.
5263
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005264 Example:
5265 http-after-response set-header Strict-Transport-Security "max-age=31536000"
5266 http-after-response set-header Cache-Control "no-store,no-cache,private"
5267 http-after-response set-header Pragma "no-cache"
5268
5269http-after-response add-header <name> <fmt> [ { if | unless } <condition> ]
5270
5271 This appends an HTTP header field whose name is specified in <name> and whose
5272 value is defined by <fmt> which follows the log-format rules (see Custom Log
5273 Format in section 8.2.4). This may be used to send a cookie to a client for
5274 example, or to pass some internal information.
5275 This rule is not final, so it is possible to add other similar rules.
5276 Note that header addition is performed immediately, so one rule might reuse
5277 the resulting header from a previous rule.
5278
5279http-after-response allow [ { if | unless } <condition> ]
5280
5281 This stops the evaluation of the rules and lets the response pass the check.
5282 No further "http-after-response" rules are evaluated.
5283
Maciej Zdebebdd4c52020-11-20 13:58:48 +00005284http-after-response del-header <name> [ -m <meth> ] [ { if | unless } <condition> ]
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005285
Maciej Zdebebdd4c52020-11-20 13:58:48 +00005286 This removes all HTTP header fields whose name is specified in <name>. <meth>
5287 is the matching method, applied on the header name. Supported matching methods
5288 are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub"
5289 (substring match) and "reg" (regex match). If not specified, exact matching
5290 method is used.
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005291
5292http-after-response replace-header <name> <regex-match> <replace-fmt>
5293 [ { if | unless } <condition> ]
5294
5295 This works like "http-response replace-header".
5296
5297 Example:
5298 http-after-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
5299
5300 # applied to:
5301 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
5302
5303 # outputs:
5304 Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
5305
5306 # assuming the backend IP is 192.168.1.20.
5307
5308http-after-response replace-value <name> <regex-match> <replace-fmt>
5309 [ { if | unless } <condition> ]
5310
5311 This works like "http-response replace-value".
5312
5313 Example:
5314 http-after-response replace-value Cache-control ^public$ private
5315
5316 # applied to:
5317 Cache-Control: max-age=3600, public
5318
5319 # outputs:
5320 Cache-Control: max-age=3600, private
5321
5322http-after-response set-header <name> <fmt> [ { if | unless } <condition> ]
5323
5324 This does the same as "add-header" except that the header name is first
5325 removed if it existed. This is useful when passing security information to
5326 the server, where the header must not be manipulated by external users.
5327
5328http-after-response set-status <status> [reason <str>]
5329 [ { if | unless } <condition> ]
5330
5331 This replaces the response status code with <status> which must be an integer
5332 between 100 and 999. Optionally, a custom reason text can be provided defined
5333 by <str>, or the default reason for the specified code will be used as a
5334 fallback.
5335
5336 Example:
5337 # return "431 Request Header Fields Too Large"
5338 http-response set-status 431
5339 # return "503 Slow Down", custom reason
5340 http-response set-status 503 reason "Slow Down"
5341
5342http-after-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
5343
5344 This is used to set the contents of a variable. The variable is declared
5345 inline.
5346
5347 Arguments:
5348 <var-name> The name of the variable starts with an indication about its
5349 scope. The scopes allowed are:
5350 "proc" : the variable is shared with the whole process
5351 "sess" : the variable is shared with the whole session
5352 "txn" : the variable is shared with the transaction
5353 (request and response)
5354 "req" : the variable is shared only during request
5355 processing
5356 "res" : the variable is shared only during response
5357 processing
5358 This prefix is followed by a name. The separator is a '.'.
5359 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
5360 and '_'.
5361
5362 <expr> Is a standard HAProxy expression formed by a sample-fetch
5363 followed by some converters.
5364
5365 Example:
5366 http-after-response set-var(sess.last_redir) res.hdr(location)
5367
5368http-after-response strict-mode { on | off }
5369
5370 This enables or disables the strict rewriting mode for following rules. It
5371 does not affect rules declared before it and it is only applicable on rules
5372 performing a rewrite on the responses. When the strict mode is enabled, any
5373 rewrite failure triggers an internal error. Otherwise, such errors are
5374 silently ignored. The purpose of the strict rewriting mode is to make some
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05005375 rewrites optional while others must be performed to continue the response
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005376 processing.
5377
5378 By default, the strict rewriting mode is enabled. Its value is also reset
5379 when a ruleset evaluation ends. So, for instance, if you change the mode on
Daniel Corbett67a82712020-07-06 23:01:19 -04005380 the backend, the default mode is restored when HAProxy starts the frontend
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005381 rules evaluation.
5382
5383http-after-response unset-var(<var-name>) [ { if | unless } <condition> ]
5384
5385 This is used to unset a variable. See "http-after-response set-var" for
5386 details about <var-name>.
5387
5388 Example:
5389 http-after-response unset-var(sess.last_redir)
5390
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005391
5392http-check comment <string>
5393 Defines a comment for the following the http-check rule, reported in logs if
5394 it fails.
5395 May be used in sections : defaults | frontend | listen | backend
5396 yes | no | yes | yes
5397
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005398 Arguments :
5399 <string> is the comment message to add in logs if the following http-check
5400 rule fails.
5401
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005402 It only works for connect, send and expect rules. It is useful to make
5403 user-friendly error reporting.
5404
Daniel Corbett67a82712020-07-06 23:01:19 -04005405 See also : "option httpchk", "http-check connect", "http-check send" and
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005406 "http-check expect".
5407
5408
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005409http-check connect [default] [port <expr>] [addr <ip>] [send-proxy]
5410 [via-socks4] [ssl] [sni <sni>] [alpn <alpn>] [linger]
Christopher Fauletedc6ed92020-04-23 16:27:59 +02005411 [proto <name>] [comment <msg>]
Christopher Faulete5870d82020-04-15 11:32:03 +02005412 Opens a new connection to perform an HTTP health check
5413 May be used in sections : defaults | frontend | listen | backend
5414 yes | no | yes | yes
5415
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005416 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005417 comment <msg> defines a message to report if the rule evaluation fails.
5418
Christopher Faulete5870d82020-04-15 11:32:03 +02005419 default Use default options of the server line to do the health
Daniel Corbett67a82712020-07-06 23:01:19 -04005420 checks. The server options are used only if not redefined.
Christopher Faulete5870d82020-04-15 11:32:03 +02005421
5422 port <expr> if not set, check port or server port is used.
5423 It tells HAProxy where to open the connection to.
5424 <port> must be a valid TCP port source integer, from 1 to
5425 65535 or an sample-fetch expression.
5426
5427 addr <ip> defines the IP address to do the health check.
5428
5429 send-proxy send a PROXY protocol string
5430
5431 via-socks4 enables outgoing health checks using upstream socks4 proxy.
5432
5433 ssl opens a ciphered connection
5434
5435 sni <sni> specifies the SNI to use to do health checks over SSL.
5436
5437 alpn <alpn> defines which protocols to advertise with ALPN. The protocol
5438 list consists in a comma-delimited list of protocol names,
5439 for instance: "h2,http/1.1". If it is not set, the server ALPN
5440 is used.
5441
Christopher Fauletedc6ed92020-04-23 16:27:59 +02005442 proto <name> forces the multiplexer's protocol to use for this connection.
5443 It must be an HTTP mux protocol and it must be usable on the
5444 backend side. The list of available protocols is reported in
5445 haproxy -vv.
5446
Christopher Faulete5870d82020-04-15 11:32:03 +02005447 linger cleanly close the connection instead of using a single RST.
5448
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005449 Just like tcp-check health checks, it is possible to configure the connection
5450 to use to perform HTTP health check. This directive should also be used to
5451 describe a scenario involving several request/response exchanges, possibly on
5452 different ports or with different servers.
5453
5454 When there are no TCP port configured on the server line neither server port
5455 directive, then the first step of the http-check sequence must be to specify
5456 the port with a "http-check connect".
5457
5458 In an http-check ruleset a 'connect' is required, it is also mandatory to start
5459 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
5460 do.
5461
5462 When a connect must start the ruleset, if may still be preceded by set-var,
5463 unset-var or comment rules.
5464
5465 Examples :
Christopher Faulete5870d82020-04-15 11:32:03 +02005466 # check HTTP and HTTPs services on a server.
5467 # first open port 80 thanks to server line port directive, then
5468 # tcp-check opens port 443, ciphered and run a request on it:
5469 option httpchk
5470
5471 http-check connect
Christopher Fauleta5c14ef2020-04-29 14:19:13 +02005472 http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu
Christopher Faulet8021a5f2020-04-24 13:53:12 +02005473 http-check expect status 200-399
Christopher Faulete5870d82020-04-15 11:32:03 +02005474 http-check connect port 443 ssl sni haproxy.1wt.eu
Christopher Fauleta5c14ef2020-04-29 14:19:13 +02005475 http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu
Christopher Faulet8021a5f2020-04-24 13:53:12 +02005476 http-check expect status 200-399
Christopher Faulete5870d82020-04-15 11:32:03 +02005477
5478 server www 10.0.0.1 check port 80
5479
5480 See also : "option httpchk", "http-check send", "http-check expect"
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01005481
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005482
Willy Tarreau0ba27502007-12-24 16:55:16 +01005483http-check disable-on-404
5484 Enable a maintenance mode upon HTTP/404 response to health-checks
5485 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01005486 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01005487 Arguments : none
5488
5489 When this option is set, a server which returns an HTTP code 404 will be
5490 excluded from further load-balancing, but will still receive persistent
5491 connections. This provides a very convenient method for Web administrators
5492 to perform a graceful shutdown of their servers. It is also important to note
5493 that a server which is detected as failed while it was in this mode will not
5494 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
5495 will immediately be reinserted into the farm. The status on the stats page
5496 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01005497 option only works in conjunction with the "httpchk" option. If this option
5498 is used with "http-check expect", then it has precedence over it so that 404
Christopher Fauletfa8b89a2020-11-20 18:54:13 +01005499 responses will still be considered as soft-stop. Note also that a stopped
5500 server will stay stopped even if it replies 404s. This option is only
5501 evaluated for running servers.
Willy Tarreaubd741542010-03-16 18:46:54 +01005502
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005503 See also : "option httpchk" and "http-check expect".
Willy Tarreaubd741542010-03-16 18:46:54 +01005504
5505
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005506http-check expect [min-recv <int>] [comment <msg>]
Christopher Faulete5870d82020-04-15 11:32:03 +02005507 [ok-status <st>] [error-status <st>] [tout-status <st>]
5508 [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
5509 [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005510 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01005511 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02005512 yes | no | yes | yes
Christopher Faulete5870d82020-04-15 11:32:03 +02005513
Willy Tarreaubd741542010-03-16 18:46:54 +01005514 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005515 comment <msg> defines a message to report if the rule evaluation fails.
5516
Christopher Faulete5870d82020-04-15 11:32:03 +02005517 min-recv is optional and can define the minimum amount of data required to
5518 evaluate the current expect rule. If the number of received bytes
5519 is under this limit, the check will wait for more data. This
5520 option can be used to resolve some ambiguous matching rules or to
5521 avoid executing costly regex matches on content known to be still
5522 incomplete. If an exact string is used, the minimum between the
5523 string length and this parameter is used. This parameter is
5524 ignored if it is set to -1. If the expect rule does not match,
5525 the check will wait for more data. If set to 0, the evaluation
5526 result is always conclusive.
5527
5528 ok-status <st> is optional and can be used to set the check status if
5529 the expect rule is successfully evaluated and if it is
5530 the last rule in the tcp-check ruleset. "L7OK", "L7OKC",
Christopher Fauletd888f0f2020-05-07 07:40:17 +02005531 "L6OK" and "L4OK" are supported :
5532 - L7OK : check passed on layer 7
Christopher Faulet83662b52020-11-20 17:47:47 +01005533 - L7OKC : check conditionally passed on layer 7, set
5534 server to NOLB state.
Christopher Fauletd888f0f2020-05-07 07:40:17 +02005535 - L6OK : check passed on layer 6
5536 - L4OK : check passed on layer 4
5537 By default "L7OK" is used.
Christopher Faulete5870d82020-04-15 11:32:03 +02005538
5539 error-status <st> is optional and can be used to set the check status if
5540 an error occurred during the expect rule evaluation.
Christopher Faulet83662b52020-11-20 17:47:47 +01005541 "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are
5542 supported :
5543 - L7OKC : check conditionally passed on layer 7, set
5544 server to NOLB state.
Christopher Fauletd888f0f2020-05-07 07:40:17 +02005545 - L7RSP : layer 7 invalid response - protocol error
5546 - L7STS : layer 7 response error, for example HTTP 5xx
5547 - L6RSP : layer 6 invalid response - protocol error
5548 - L4CON : layer 1-4 connection problem
5549 By default "L7RSP" is used.
Christopher Faulete5870d82020-04-15 11:32:03 +02005550
5551 tout-status <st> is optional and can be used to set the check status if
5552 a timeout occurred during the expect rule evaluation.
Christopher Fauletd888f0f2020-05-07 07:40:17 +02005553 "L7TOUT", "L6TOUT", and "L4TOUT" are supported :
5554 - L7TOUT : layer 7 (HTTP/SMTP) timeout
5555 - L6TOUT : layer 6 (SSL) timeout
5556 - L4TOUT : layer 1-4 timeout
Christopher Faulete5870d82020-04-15 11:32:03 +02005557 By default "L7TOUT" is used.
5558
5559 on-success <fmt> is optional and can be used to customize the
5560 informational message reported in logs if the expect
5561 rule is successfully evaluated and if it is the last rule
5562 in the tcp-check ruleset. <fmt> is a log-format string.
5563
5564 on-error <fmt> is optional and can be used to customize the
5565 informational message reported in logs if an error
5566 occurred during the expect rule evaluation. <fmt> is a
5567 log-format string.
5568
Willy Tarreaubd741542010-03-16 18:46:54 +01005569 <match> is a keyword indicating how to look for a specific pattern in the
Christopher Fauletb5594262020-05-05 20:23:13 +02005570 response. The keyword may be one of "status", "rstatus", "hdr",
5571 "fhdr", "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01005572 exclamation mark ("!") to negate the match. Spaces are allowed
5573 between the exclamation mark and the keyword. See below for more
5574 details on the supported keywords.
5575
Christopher Faulet39708192020-05-05 10:47:36 +02005576 <pattern> is the pattern to look for. It may be a string, a regular
5577 expression or a more complex pattern with several arguments. If
5578 the string pattern contains spaces, they must be escaped with the
5579 usual backslash ('\').
Willy Tarreaubd741542010-03-16 18:46:54 +01005580
5581 By default, "option httpchk" considers that response statuses 2xx and 3xx
5582 are valid, and that others are invalid. When "http-check expect" is used,
5583 it defines what is considered valid or invalid. Only one "http-check"
5584 statement is supported in a backend. If a server fails to respond or times
5585 out, the check obviously fails. The available matches are :
5586
Christopher Faulet8021a5f2020-04-24 13:53:12 +02005587 status <codes> : test the status codes found parsing <codes> string. it
5588 must be a comma-separated list of status codes or range
5589 codes. A health check response will be considered as
5590 valid if the response's status code matches any status
5591 code or is inside any range of the list. If the "status"
5592 keyword is prefixed with "!", then the response will be
5593 considered invalid if the status code matches.
Willy Tarreaubd741542010-03-16 18:46:54 +01005594
5595 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005596 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01005597 response's status code matches the expression. If the
5598 "rstatus" keyword is prefixed with "!", then the response
5599 will be considered invalid if the status code matches.
5600 This is mostly used to check for multiple codes.
5601
Christopher Fauletb5594262020-05-05 20:23:13 +02005602 hdr { name | name-lf } [ -m <meth> ] <name>
5603 [ { value | value-lf } [ -m <meth> ] <value> :
Christopher Faulet39708192020-05-05 10:47:36 +02005604 test the specified header pattern on the HTTP response
5605 headers. The name pattern is mandatory but the value
5606 pattern is optional. If not specified, only the header
5607 presence is verified. <meth> is the matching method,
5608 applied on the header name or the header value. Supported
5609 matching methods are "str" (exact match), "beg" (prefix
5610 match), "end" (suffix match), "sub" (substring match) or
5611 "reg" (regex match). If not specified, exact matching
Christopher Fauletb5594262020-05-05 20:23:13 +02005612 method is used. If the "name-lf" parameter is used,
5613 <name> is evaluated as a log-format string. If "value-lf"
5614 parameter is used, <value> is evaluated as a log-format
5615 string. These parameters cannot be used with the regex
5616 matching method. Finally, the header value is considered
5617 as comma-separated list. Note that matchings are case
5618 insensitive on the header names.
5619
5620 fhdr { name | name-lf } [ -m <meth> ] <name>
5621 [ { value | value-lf } [ -m <meth> ] <value> :
5622 test the specified full header pattern on the HTTP
5623 response headers. It does exactly the same than "hdr"
5624 keyword, except the full header value is tested, commas
5625 are not considered as delimiters.
Christopher Faulet39708192020-05-05 10:47:36 +02005626
Willy Tarreaubd741542010-03-16 18:46:54 +01005627 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005628 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01005629 response's body contains this exact string. If the
5630 "string" keyword is prefixed with "!", then the response
5631 will be considered invalid if the body contains this
5632 string. This can be used to look for a mandatory word at
5633 the end of a dynamic page, or to detect a failure when a
Davor Ocelice9ed2812017-12-25 17:49:28 +01005634 specific error appears on the check page (e.g. a stack
Willy Tarreaubd741542010-03-16 18:46:54 +01005635 trace).
5636
5637 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005638 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01005639 response's body matches this expression. If the "rstring"
5640 keyword is prefixed with "!", then the response will be
5641 considered invalid if the body matches the expression.
5642 This can be used to look for a mandatory word at the end
5643 of a dynamic page, or to detect a failure when a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01005644 error appears on the check page (e.g. a stack trace).
Willy Tarreaubd741542010-03-16 18:46:54 +01005645
Christopher Fauletaaab0832020-05-05 15:54:22 +02005646 string-lf <fmt> : test a log-format string match in the HTTP response body.
5647 A health check response will be considered valid if the
5648 response's body contains the string resulting of the
5649 evaluation of <fmt>, which follows the log-format rules.
5650 If prefixed with "!", then the response will be
5651 considered invalid if the body contains the string.
5652
Willy Tarreaubd741542010-03-16 18:46:54 +01005653 It is important to note that the responses will be limited to a certain size
Christopher Fauletbb9fb8b2020-11-25 17:20:57 +01005654 defined by the global "tune.bufsize" option, which defaults to 16384 bytes.
Willy Tarreaubd741542010-03-16 18:46:54 +01005655 Thus, too large responses may not contain the mandatory pattern when using
5656 "string" or "rstring". If a large response is absolutely required, it is
5657 possible to change the default max size by setting the global variable.
5658 However, it is worth keeping in mind that parsing very large responses can
5659 waste some CPU cycles, especially when regular expressions are used, and that
5660 it is always better to focus the checks on smaller resources.
5661
Christopher Faulete5870d82020-04-15 11:32:03 +02005662 In an http-check ruleset, the last expect rule may be implicit. If no expect
5663 rule is specified after the last "http-check send", an implicit expect rule
5664 is defined to match on 2xx or 3xx status codes. It means this rule is also
5665 defined if there is no "http-check" rule at all, when only "option httpchk"
5666 is set.
Cyril Bonté32602d22015-01-30 00:07:07 +01005667
Willy Tarreaubd741542010-03-16 18:46:54 +01005668 Last, if "http-check expect" is combined with "http-check disable-on-404",
5669 then this last one has precedence when the server responds with 404.
5670
5671 Examples :
5672 # only accept status 200 as valid
Christopher Faulet8021a5f2020-04-24 13:53:12 +02005673 http-check expect status 200,201,300-310
Willy Tarreaubd741542010-03-16 18:46:54 +01005674
Christopher Faulet39708192020-05-05 10:47:36 +02005675 # be sure a sessid coookie is set
5676 http-check expect header name "set-cookie" value -m beg "sessid="
5677
Willy Tarreaubd741542010-03-16 18:46:54 +01005678 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01005679 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01005680
5681 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01005682 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01005683
5684 # check that we have a correct hexadecimal tag before /html
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03005685 http-check expect rstring <!--tag:[0-9a-f]*--></html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01005686
Christopher Faulete5870d82020-04-15 11:32:03 +02005687 See also : "option httpchk", "http-check connect", "http-check disable-on-404"
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005688 and "http-check send".
Willy Tarreau2769aa02007-12-27 18:26:09 +01005689
5690
Christopher Faulet7c95f5f2020-05-06 15:06:34 +02005691http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
Christopher Faulet574e7bd2020-05-06 15:38:58 +02005692 [hdr <name> <fmt>]* [{ body <string> | body-lf <fmt> }]
5693 [comment <msg>]
Christopher Faulet8acb1282020-04-09 08:44:06 +02005694 Add a possible list of headers and/or a body to the request sent during HTTP
5695 health checks.
5696 May be used in sections : defaults | frontend | listen | backend
5697 yes | no | yes | yes
5698 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005699 comment <msg> defines a message to report if the rule evaluation fails.
5700
Christopher Faulete5870d82020-04-15 11:32:03 +02005701 meth <method> is the optional HTTP method used with the requests. When not
5702 set, the "OPTIONS" method is used, as it generally requires
5703 low server processing and is easy to filter out from the
5704 logs. Any method may be used, though it is not recommended
5705 to invent non-standard ones.
5706
Christopher Faulet7c95f5f2020-05-06 15:06:34 +02005707 uri <uri> is optional and set the URI referenced in the HTTP requests
5708 to the string <uri>. It defaults to "/" which is accessible
5709 by default on almost any server, but may be changed to any
5710 other URI. Query strings are permitted.
5711
5712 uri-lf <fmt> is optional and set the URI referenced in the HTTP requests
5713 using the log-format string <fmt>. It defaults to "/" which
5714 is accessible by default on almost any server, but may be
5715 changed to any other URI. Query strings are permitted.
Christopher Faulet8acb1282020-04-09 08:44:06 +02005716
Christopher Faulet907701b2020-04-28 09:37:00 +02005717 ver <version> is the optional HTTP version string. It defaults to
Christopher Faulete5870d82020-04-15 11:32:03 +02005718 "HTTP/1.0" but some servers might behave incorrectly in HTTP
Daniel Corbett67a82712020-07-06 23:01:19 -04005719 1.0, so turning it to HTTP/1.1 may sometimes help. Note that
Christopher Faulete5870d82020-04-15 11:32:03 +02005720 the Host field is mandatory in HTTP/1.1, use "hdr" argument
5721 to add it.
5722
5723 hdr <name> <fmt> adds the HTTP header field whose name is specified in
5724 <name> and whose value is defined by <fmt>, which follows
5725 to the log-format rules.
5726
5727 body <string> add the body defined by <string> to the request sent during
5728 HTTP health checks. If defined, the "Content-Length" header
5729 is thus automatically added to the request.
Christopher Faulet8acb1282020-04-09 08:44:06 +02005730
Christopher Faulet574e7bd2020-05-06 15:38:58 +02005731 body-lf <fmt> add the body defined by the log-format string <fmt> to the
5732 request sent during HTTP health checks. If defined, the
5733 "Content-Length" header is thus automatically added to the
5734 request.
5735
Christopher Faulet8acb1282020-04-09 08:44:06 +02005736 In addition to the request line defined by the "option httpchk" directive,
5737 this one is the valid way to add some headers and optionally a body to the
5738 request sent during HTTP health checks. If a body is defined, the associate
Christopher Faulet9df910c2020-04-29 14:20:47 +02005739 "Content-Length" header is automatically added. Thus, this header or
5740 "Transfer-encoding" header should not be present in the request provided by
5741 "http-check send". If so, it will be ignored. The old trick consisting to add
5742 headers after the version string on the "option httpchk" line is now
Amaury Denoyelle6d975f02020-12-22 14:08:52 +01005743 deprecated.
Christopher Faulet8acb1282020-04-09 08:44:06 +02005744
Christopher Faulete5870d82020-04-15 11:32:03 +02005745 Also "http-check send" doesn't support HTTP keep-alive. Keep in mind that it
Amaury Denoyelle6d975f02020-12-22 14:08:52 +01005746 will automatically append a "Connection: close" header, unless a Connection
5747 header has already already been configured via a hdr entry.
Christopher Faulet9df910c2020-04-29 14:20:47 +02005748
5749 Note that the Host header and the request authority, when both defined, are
5750 automatically synchronized. It means when the HTTP request is sent, when a
5751 Host is inserted in the request, the request authority is accordingly
5752 updated. Thus, don't be surprised if the Host header value overwrites the
5753 configured request authority.
5754
5755 Note also for now, no Host header is automatically added in HTTP/1.1 or above
5756 requests. You should add it explicitly.
Christopher Faulete5870d82020-04-15 11:32:03 +02005757
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005758 See also : "option httpchk", "http-check send-state" and "http-check expect".
Christopher Faulet8acb1282020-04-09 08:44:06 +02005759
5760
Willy Tarreauef781042010-01-27 11:53:01 +01005761http-check send-state
5762 Enable emission of a state header with HTTP health checks
5763 May be used in sections : defaults | frontend | listen | backend
5764 yes | no | yes | yes
5765 Arguments : none
5766
Daniel Corbett9f0843f2021-05-08 10:50:37 -04005767 When this option is set, HAProxy will systematically send a special header
Willy Tarreauef781042010-01-27 11:53:01 +01005768 "X-Haproxy-Server-State" with a list of parameters indicating to each server
Daniel Corbett9f0843f2021-05-08 10:50:37 -04005769 how they are seen by HAProxy. This can be used for instance when a server is
5770 manipulated without access to HAProxy and the operator needs to know whether
5771 HAProxy still sees it up or not, or if the server is the last one in a farm.
Willy Tarreauef781042010-01-27 11:53:01 +01005772
5773 The header is composed of fields delimited by semi-colons, the first of which
5774 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
5775 checks on the total number before transition, just as appears in the stats
5776 interface. Next headers are in the form "<variable>=<value>", indicating in
5777 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08005778 - a variable "address", containing the address of the backend server.
5779 This corresponds to the <address> field in the server declaration. For
5780 unix domain sockets, it will read "unix".
5781
5782 - a variable "port", containing the port of the backend server. This
5783 corresponds to the <port> field in the server declaration. For unix
5784 domain sockets, it will read "unix".
5785
Willy Tarreauef781042010-01-27 11:53:01 +01005786 - a variable "name", containing the name of the backend followed by a slash
5787 ("/") then the name of the server. This can be used when a server is
5788 checked in multiple backends.
5789
Daniel Corbett9f0843f2021-05-08 10:50:37 -04005790 - a variable "node" containing the name of the HAProxy node, as set in the
Willy Tarreauef781042010-01-27 11:53:01 +01005791 global "node" variable, otherwise the system's hostname if unspecified.
5792
5793 - a variable "weight" indicating the weight of the server, a slash ("/")
5794 and the total weight of the farm (just counting usable servers). This
5795 helps to know if other servers are available to handle the load when this
5796 one fails.
5797
5798 - a variable "scur" indicating the current number of concurrent connections
5799 on the server, followed by a slash ("/") then the total number of
5800 connections on all servers of the same backend.
5801
5802 - a variable "qcur" indicating the current number of requests in the
5803 server's queue.
5804
5805 Example of a header received by the application server :
5806 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
5807 scur=13/22; qcur=0
5808
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005809 See also : "option httpchk", "http-check disable-on-404" and
5810 "http-check send".
Willy Tarreauef781042010-01-27 11:53:01 +01005811
Christopher Faulete5870d82020-04-15 11:32:03 +02005812
5813http-check set-var(<var-name>) <expr>
Christopher Faulete5870d82020-04-15 11:32:03 +02005814 This operation sets the content of a variable. The variable is declared inline.
Christopher Faulete5870d82020-04-15 11:32:03 +02005815 May be used in sections: defaults | frontend | listen | backend
5816 yes | no | yes | yes
5817
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005818 Arguments :
Christopher Faulete5870d82020-04-15 11:32:03 +02005819 <var-name> The name of the variable starts with an indication about its
5820 scope. The scopes allowed for http-check are:
5821 "proc" : the variable is shared with the whole process.
5822 "sess" : the variable is shared with the tcp-check session.
5823 "check": the variable is declared for the lifetime of the tcp-check.
5824 This prefix is followed by a name. The separator is a '.'.
5825 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
5826 and '-'.
5827
5828 <expr> Is a sample-fetch expression potentially followed by converters.
5829
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005830 Examples :
5831 http-check set-var(check.port) int(1234)
Christopher Faulete5870d82020-04-15 11:32:03 +02005832
5833
5834http-check unset-var(<var-name>)
Christopher Faulete5870d82020-04-15 11:32:03 +02005835 Free a reference to a variable within its scope.
Christopher Faulete5870d82020-04-15 11:32:03 +02005836 May be used in sections: defaults | frontend | listen | backend
5837 yes | no | yes | yes
5838
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005839 Arguments :
Christopher Faulete5870d82020-04-15 11:32:03 +02005840 <var-name> The name of the variable starts with an indication about its
5841 scope. The scopes allowed for http-check are:
5842 "proc" : the variable is shared with the whole process.
5843 "sess" : the variable is shared with the tcp-check session.
5844 "check": the variable is declared for the lifetime of the tcp-check.
5845 This prefix is followed by a name. The separator is a '.'.
5846 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
5847 and '-'.
5848
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005849 Examples :
5850 http-check unset-var(check.port)
Christopher Faulete5870d82020-04-15 11:32:03 +02005851
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005852
Christopher Faulet3b967c12020-05-15 15:47:44 +02005853http-error status <code> [content-type <type>]
5854 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
5855 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
5856 [ hdr <name> <fmt> ]*
5857 Defines a custom error message to use instead of errors generated by HAProxy.
5858 May be used in sections : defaults | frontend | listen | backend
5859 yes | yes | yes | yes
5860 Arguments :
Ilya Shipitsin11057a32020-06-21 21:18:27 +05005861 status <code> is the HTTP status code. It must be specified.
Christopher Faulet3b967c12020-05-15 15:47:44 +02005862 Currently, HAProxy is capable of generating codes
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02005863 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 425,
Christopher Faulete095f312020-12-07 11:22:24 +01005864 429, 500, 501, 502, 503, and 504.
Christopher Faulet3b967c12020-05-15 15:47:44 +02005865
5866 content-type <type> is the response content type, for instance
5867 "text/plain". This parameter is ignored and should be
5868 omitted when an errorfile is configured or when the
5869 payload is empty. Otherwise, it must be defined.
5870
5871 default-errorfiles Reset the previously defined error message for current
5872 proxy for the status <code>. If used on a backend, the
5873 frontend error message is used, if defined. If used on
5874 a frontend, the default error message is used.
5875
5876 errorfile <file> designates a file containing the full HTTP response.
5877 It is recommended to follow the common practice of
5878 appending ".http" to the filename so that people do
5879 not confuse the response with HTML error pages, and to
5880 use absolute paths, since files are read before any
5881 chroot is performed.
5882
5883 errorfiles <name> designates the http-errors section to use to import
5884 the error message with the status code <code>. If no
5885 such message is found, the proxy's error messages are
5886 considered.
5887
5888 file <file> specifies the file to use as response payload. If the
5889 file is not empty, its content-type must be set as
5890 argument to "content-type", otherwise, any
5891 "content-type" argument is ignored. <file> is
5892 considered as a raw string.
5893
5894 string <str> specifies the raw string to use as response payload.
5895 The content-type must always be set as argument to
5896 "content-type".
5897
5898 lf-file <file> specifies the file to use as response payload. If the
5899 file is not empty, its content-type must be set as
5900 argument to "content-type", otherwise, any
5901 "content-type" argument is ignored. <file> is
5902 evaluated as a log-format string.
5903
5904 lf-string <str> specifies the log-format string to use as response
5905 payload. The content-type must always be set as
5906 argument to "content-type".
5907
5908 hdr <name> <fmt> adds to the response the HTTP header field whose name
5909 is specified in <name> and whose value is defined by
5910 <fmt>, which follows to the log-format rules.
5911 This parameter is ignored if an errorfile is used.
5912
5913 This directive may be used instead of "errorfile", to define a custom error
5914 message. As "errorfile" directive, it is used for errors detected and
5915 returned by HAProxy. If an errorfile is defined, it is parsed when HAProxy
5916 starts and must be valid according to the HTTP standards. The generated
5917 response must not exceed the configured buffer size (BUFFSIZE), otherwise an
5918 internal error will be returned. Finally, if you consider to use some
5919 http-after-response rules to rewrite these errors, the reserved buffer space
5920 should be available (see "tune.maxrewrite").
5921
5922 The files are read at the same time as the configuration and kept in memory.
5923 For this reason, the errors continue to be returned even when the process is
5924 chrooted, and no file change is considered while the process is running.
5925
Christopher Fauletd5ac6de2020-12-02 08:40:14 +01005926 Note: 400/408/500 errors emitted in early stage of the request parsing are
5927 handled by the multiplexer at a lower level. No custom formatting is
5928 supported at this level. Thus only static error messages, defined with
5929 "errorfile" directive, are supported. However, this limitation only
5930 exists during the request headers parsing or between two transactions.
5931
Christopher Faulet3b967c12020-05-15 15:47:44 +02005932 See also : "errorfile", "errorfiles", "errorloc", "errorloc302",
5933 "errorloc303" and section 3.8 about http-errors.
5934
5935
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005936http-request <action> [options...] [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005937 Access control for Layer 7 requests
5938
5939 May be used in sections: defaults | frontend | listen | backend
5940 no | yes | yes | yes
5941
Willy Tarreau20b0de52012-12-24 15:45:22 +01005942 The http-request statement defines a set of rules which apply to layer 7
5943 processing. The rules are evaluated in their declaration order when they are
5944 met in a frontend, listen or backend section. Any rule may optionally be
5945 followed by an ACL-based condition, in which case it will only be evaluated
5946 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005947
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005948 The first keyword is the rule's action. The supported actions are described
5949 below.
Willy Tarreau20b0de52012-12-24 15:45:22 +01005950
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005951 There is no limit to the number of http-request statements per instance.
Willy Tarreau20b0de52012-12-24 15:45:22 +01005952
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005953 Example:
5954 acl nagios src 192.168.129.3
5955 acl local_net src 192.168.0.0/16
5956 acl auth_ok http_auth(L1)
Willy Tarreau20b0de52012-12-24 15:45:22 +01005957
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005958 http-request allow if nagios
5959 http-request allow if local_net auth_ok
5960 http-request auth realm Gimme if local_net auth_ok
5961 http-request deny
Willy Tarreau81499eb2012-12-27 12:19:02 +01005962
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005963 Example:
5964 acl key req.hdr(X-Add-Acl-Key) -m found
5965 acl add path /addacl
5966 acl del path /delacl
Willy Tarreau20b0de52012-12-24 15:45:22 +01005967
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005968 acl myhost hdr(Host) -f myhost.lst
Willy Tarreau20b0de52012-12-24 15:45:22 +01005969
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005970 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
5971 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02005972
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005973 Example:
5974 acl value req.hdr(X-Value) -m found
5975 acl setmap path /setmap
5976 acl delmap path /delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06005977
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005978 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06005979
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005980 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
5981 http-request del-map(map.lst) %[src] if delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06005982
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005983 See also : "stats http-request", section 3.4 about userlists and section 7
5984 about ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06005985
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005986http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005987
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005988 This is used to add a new entry into an ACL. The ACL must be loaded from a
5989 file (even a dummy empty file). The file name of the ACL to be updated is
5990 passed between parentheses. It takes one argument: <key fmt>, which follows
5991 log-format rules, to collect content of the new entry. It performs a lookup
5992 in the ACL before insertion, to avoid duplicated (or more) values. This
5993 lookup is done by a linear search and can be expensive with large lists!
5994 It is the equivalent of the "add acl" command from the stats socket, but can
5995 be triggered by an HTTP request.
Sasha Pachev218f0642014-06-16 12:05:59 -06005996
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005997http-request add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005998
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005999 This appends an HTTP header field whose name is specified in <name> and
6000 whose value is defined by <fmt> which follows the log-format rules (see
6001 Custom Log Format in section 8.2.4). This is particularly useful to pass
6002 connection-specific information to the server (e.g. the client's SSL
6003 certificate), or to combine several headers into one. This rule is not
6004 final, so it is possible to add other similar rules. Note that header
6005 addition is performed immediately, so one rule might reuse the resulting
6006 header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06006007
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006008http-request allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006009
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006010 This stops the evaluation of the rules and lets the request pass the check.
6011 No further "http-request" rules are evaluated.
Sasha Pachev218f0642014-06-16 12:05:59 -06006012
Sasha Pachev218f0642014-06-16 12:05:59 -06006013
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006014http-request auth [realm <realm>] [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006015
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006016 This stops the evaluation of the rules and immediately responds with an
6017 HTTP 401 or 407 error code to invite the user to present a valid user name
6018 and password. No further "http-request" rules are evaluated. An optional
6019 "realm" parameter is supported, it sets the authentication realm that is
6020 returned with the response (typically the application's name).
Sasha Pachev218f0642014-06-16 12:05:59 -06006021
Christopher Faulet612f2ea2020-05-27 09:57:28 +02006022 The corresponding proxy's error message is used. It may be customized using
6023 an "errorfile" or an "http-error" directive. For 401 responses, all
6024 occurrences of the WWW-Authenticate header are removed and replaced by a new
6025 one with a basic authentication challenge for realm "<realm>". For 407
6026 responses, the same is done on the Proxy-Authenticate header. If the error
6027 message must not be altered, consider to use "http-request return" rule
6028 instead.
6029
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006030 Example:
6031 acl auth_ok http_auth_group(L1) G1
6032 http-request auth unless auth_ok
Sasha Pachev218f0642014-06-16 12:05:59 -06006033
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02006034http-request cache-use <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006035
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02006036 See section 6.2 about cache setup.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01006037
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006038http-request capture <sample> [ len <length> | id <id> ]
6039 [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01006040
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006041 This captures sample expression <sample> from the request buffer, and
6042 converts it to a string of at most <len> characters. The resulting string is
6043 stored into the next request "capture" slot, so it will possibly appear next
6044 to some captured HTTP headers. It will then automatically appear in the logs,
6045 and it will be possible to extract it using sample fetch rules to feed it
6046 into headers or anything. The length should be limited given that this size
6047 will be allocated for each capture during the whole session life.
6048 Please check section 7.3 (Fetching samples) and "capture request header" for
6049 more information.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01006050
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006051 If the keyword "id" is used instead of "len", the action tries to store the
6052 captured string in a previously declared capture slot. This is useful to run
6053 captures in backends. The slot id can be declared by a previous directive
Baptiste Assmann19a69b32020-01-16 14:34:22 +01006054 "http-request capture" or with the "declare capture" keyword.
6055
6056 When using this action in a backend, double check that the relevant
6057 frontend(s) have the required capture slots otherwise, this rule will be
6058 ignored at run time. This can't be detected at configuration parsing time
6059 due to HAProxy's ability to dynamically resolve backend name at runtime.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01006060
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006061http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01006062
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006063 This is used to delete an entry from an ACL. The ACL must be loaded from a
6064 file (even a dummy empty file). The file name of the ACL to be updated is
6065 passed between parentheses. It takes one argument: <key fmt>, which follows
6066 log-format rules, to collect content of the entry to delete.
6067 It is the equivalent of the "del acl" command from the stats socket, but can
6068 be triggered by an HTTP request.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01006069
Maciej Zdebebdd4c52020-11-20 13:58:48 +00006070http-request del-header <name> [ -m <meth> ] [ { if | unless } <condition> ]
Willy Tarreauf4c43c12013-06-11 17:01:13 +02006071
Maciej Zdebebdd4c52020-11-20 13:58:48 +00006072 This removes all HTTP header fields whose name is specified in <name>. <meth>
6073 is the matching method, applied on the header name. Supported matching methods
6074 are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub"
6075 (substring match) and "reg" (regex match). If not specified, exact matching
6076 method is used.
Willy Tarreau9a355ec2013-06-11 17:45:46 +02006077
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006078http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau42cf39e2013-06-11 18:51:32 +02006079
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006080 This is used to delete an entry from a MAP. The MAP must be loaded from a
6081 file (even a dummy empty file). The file name of the MAP to be updated is
6082 passed between parentheses. It takes one argument: <key fmt>, which follows
6083 log-format rules, to collect content of the entry to delete.
6084 It takes one argument: "file name" It is the equivalent of the "del map"
6085 command from the stats socket, but can be triggered by an HTTP request.
Willy Tarreau51347ed2013-06-11 19:34:13 +02006086
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006087http-request deny [deny_status <status>] [ { if | unless } <condition> ]
6088http-request deny [ { status | deny_status } <code>] [content-type <type>]
6089 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
6090 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
6091 [ hdr <name> <fmt> ]*
6092 [ { if | unless } <condition> ]
Patrick Hemmer268a7072018-05-11 12:52:31 -04006093
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006094 This stops the evaluation of the rules and immediately rejects the request.
6095 By default an HTTP 403 error is returned. But the response may be customized
6096 using same syntax than "http-request return" rules. Thus, see "http-request
Ilya Shipitsin11057a32020-06-21 21:18:27 +05006097 return" for details. For compatibility purpose, when no argument is defined,
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006098 or only "deny_status", the argument "default-errorfiles" is implied. It means
6099 "http-request deny [deny_status <status>]" is an alias of
6100 "http-request deny [status <status>] default-errorfiles".
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006101 No further "http-request" rules are evaluated.
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006102 See also "http-request return".
Patrick Hemmer268a7072018-05-11 12:52:31 -04006103
Olivier Houchard602bf7d2019-05-10 13:59:15 +02006104http-request disable-l7-retry [ { if | unless } <condition> ]
6105 This disables any attempt to retry the request if it fails for any other
6106 reason than a connection failure. This can be useful for example to make
6107 sure POST requests aren't retried on failure.
6108
Baptiste Assmann333939c2019-01-21 08:34:50 +01006109http-request do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr> :
6110
6111 This action performs a DNS resolution of the output of <expr> and stores
6112 the result in the variable <var>. It uses the DNS resolvers section
6113 pointed by <resolvers>.
6114 It is possible to choose a resolution preference using the optional
6115 arguments 'ipv4' or 'ipv6'.
6116 When performing the DNS resolution, the client side connection is on
6117 pause waiting till the end of the resolution.
6118 If an IP address can be found, it is stored into <var>. If any kind of
6119 error occurs, then <var> is not set.
6120 One can use this action to discover a server IP address at run time and
6121 based on information found in the request (IE a Host header).
6122 If this action is used to find the server's IP address (using the
6123 "set-dst" action), then the server IP address in the backend must be set
6124 to 0.0.0.0.
6125
6126 Example:
6127 resolvers mydns
6128 nameserver local 127.0.0.53:53
6129 nameserver google 8.8.8.8:53
6130 timeout retry 1s
6131 hold valid 10s
6132 hold nx 3s
6133 hold other 3s
6134 hold obsolete 0s
6135 accepted_payload_size 8192
6136
6137 frontend fe
6138 bind 10.42.0.1:80
6139 http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),lower
6140 http-request capture var(txn.myip) len 40
6141
6142 # return 503 when the variable is not set,
6143 # which mean DNS resolution error
6144 use_backend b_503 unless { var(txn.myip) -m found }
6145
6146 default_backend be
6147
6148 backend b_503
6149 # dummy backend used to return 503.
6150 # one can use the errorfile directive to send a nice
6151 # 503 error page to end users
6152
6153 backend be
6154 # rule to prevent HAProxy from reconnecting to services
6155 # on the local network (forged DNS name used to scan the network)
6156 http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 }
6157 http-request set-dst var(txn.myip)
6158 server clear 0.0.0.0:0
6159
6160 NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't
6161 be used to scan the network or worst won't loop over itself...
6162
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01006163http-request early-hint <name> <fmt> [ { if | unless } <condition> ]
6164
6165 This is used to build an HTTP 103 Early Hints response prior to any other one.
6166 This appends an HTTP header field to this response whose name is specified in
6167 <name> and whose value is defined by <fmt> which follows the log-format rules
6168 (see Custom Log Format in section 8.2.4). This is particularly useful to pass
Frédéric Lécaille3aac1062018-11-13 09:42:13 +01006169 to the client some Link headers to preload resources required to render the
6170 HTML documents.
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01006171
6172 See RFC 8297 for more information.
6173
Tim Duesterhusd371e992021-04-15 21:45:58 +02006174http-request normalize-uri <normalizer> [ { if | unless } <condition> ]
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006175http-request normalize-uri path-merge-slashes [ { if | unless } <condition> ]
Maximilian Maderff3bb8b2021-04-21 00:22:50 +02006176http-request normalize-uri path-strip-dot [ { if | unless } <condition> ]
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006177http-request normalize-uri path-strip-dotdot [ full ] [ { if | unless } <condition> ]
Tim Duesterhus2e4a18e2021-04-21 21:20:36 +02006178http-request normalize-uri percent-decode-unreserved [ strict ] [ { if | unless } <condition> ]
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006179http-request normalize-uri percent-to-uppercase [ strict ] [ { if | unless } <condition> ]
6180http-request normalize-uri query-sort-by-name [ { if | unless } <condition> ]
Tim Duesterhusd371e992021-04-15 21:45:58 +02006181
Tim Duesterhusb918a4a2021-04-16 23:52:29 +02006182 Performs normalization of the request's URI.
6183
Tim Duesterhus2963fd32021-04-17 00:24:56 +02006184 URI normalization in HAProxy 2.4 is currently available as an experimental
Amaury Denoyellea9e639a2021-05-06 15:50:12 +02006185 technical preview. As such, it requires the global directive
6186 'expose-experimental-directives' first to be able to invoke it. You should be
6187 prepared that the behavior of normalizers might change to fix possible
6188 issues, possibly breaking proper request processing in your infrastructure.
Tim Duesterhus2963fd32021-04-17 00:24:56 +02006189
Tim Duesterhusb918a4a2021-04-16 23:52:29 +02006190 Each normalizer handles a single type of normalization to allow for a
6191 fine-grained selection of the level of normalization that is appropriate for
6192 the supported backend.
6193
6194 As an example the "path-strip-dotdot" normalizer might be useful for a static
6195 fileserver that directly maps the requested URI to the path within the local
6196 filesystem. However it might break routing of an API that expects a specific
6197 number of segments in the path.
6198
Tim Duesterhus2e4a18e2021-04-21 21:20:36 +02006199 It is important to note that some normalizers might result in unsafe
6200 transformations for broken URIs. It might also be possible that a combination
6201 of normalizers that are safe by themselves results in unsafe transformations
6202 when improperly combined.
6203
6204 As an example the "percent-decode-unreserved" normalizer might result in
6205 unexpected results when a broken URI includes bare percent characters. One
6206 such a broken URI is "/%%36%36" which would be decoded to "/%66" which in
6207 turn is equivalent to "/f". By specifying the "strict" option requests to
6208 such a broken URI would safely be rejected.
6209
Tim Duesterhusb918a4a2021-04-16 23:52:29 +02006210 The following normalizers are available:
Tim Duesterhusd371e992021-04-15 21:45:58 +02006211
Tim Duesterhusd6d33de2021-04-21 21:20:35 +02006212 - path-strip-dot: Removes "/./" segments within the "path" component
6213 (RFC 3986#6.2.2.3).
Maximilian Maderff3bb8b2021-04-21 00:22:50 +02006214
Tim Duesterhus2e4a18e2021-04-21 21:20:36 +02006215 Segments including percent encoded dots ("%2E") will not be detected. Use
6216 the "percent-decode-unreserved" normalizer first if this is undesired.
6217
Tim Duesterhus7a95f412021-04-21 21:20:33 +02006218 Example:
6219 - /. -> /
6220 - /./bar/ -> /bar/
6221 - /a/./a -> /a/a
6222 - /.well-known/ -> /.well-known/ (no change)
Maximilian Maderff3bb8b2021-04-21 00:22:50 +02006223
Tim Duesterhusd6d33de2021-04-21 21:20:35 +02006224 - path-strip-dotdot: Normalizes "/../" segments within the "path" component
6225 (RFC 3986#6.2.2.3).
6226
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006227 This merges segments that attempt to access the parent directory with
Tim Duesterhus2e4a18e2021-04-21 21:20:36 +02006228 their preceding segment.
6229
6230 Empty segments do not receive special treatment. Use the "merge-slashes"
6231 normalizer first if this is undesired.
6232
6233 Segments including percent encoded dots ("%2E") will not be detected. Use
6234 the "percent-decode-unreserved" normalizer first if this is undesired.
Tim Duesterhus9982fc22021-04-15 21:45:59 +02006235
6236 Example:
6237 - /foo/../ -> /
6238 - /foo/../bar/ -> /bar/
6239 - /foo/bar/../ -> /foo/
6240 - /../bar/ -> /../bar/
Tim Duesterhus560e1a62021-04-15 21:46:00 +02006241 - /bar/../../ -> /../
Tim Duesterhus9982fc22021-04-15 21:45:59 +02006242 - /foo//../ -> /foo/
Tim Duesterhus2e4a18e2021-04-21 21:20:36 +02006243 - /foo/%2E%2E/ -> /foo/%2E%2E/
Tim Duesterhus9982fc22021-04-15 21:45:59 +02006244
Tim Duesterhus560e1a62021-04-15 21:46:00 +02006245 If the "full" option is specified then "../" at the beginning will be
6246 removed as well:
6247
6248 Example:
6249 - /../bar/ -> /bar/
6250 - /bar/../../ -> /
6251
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006252 - path-merge-slashes: Merges adjacent slashes within the "path" component
6253 into a single slash.
Tim Duesterhusd371e992021-04-15 21:45:58 +02006254
6255 Example:
6256 - // -> /
6257 - /foo//bar -> /foo/bar
6258
Tim Duesterhus2e4a18e2021-04-21 21:20:36 +02006259 - percent-decode-unreserved: Decodes unreserved percent encoded characters to
6260 their representation as a regular character (RFC 3986#6.2.2.2).
6261
6262 The set of unreserved characters includes all letters, all digits, "-",
6263 ".", "_", and "~".
6264
6265 Example:
6266 - /%61dmin -> /admin
6267 - /foo%3Fbar=baz -> /foo%3Fbar=baz (no change)
6268 - /%%36%36 -> /%66 (unsafe)
6269 - /%ZZ -> /%ZZ
6270
6271 If the "strict" option is specified then invalid sequences will result
6272 in a HTTP 400 Bad Request being returned.
6273
6274 Example:
6275 - /%%36%36 -> HTTP 400
6276 - /%ZZ -> HTTP 400
6277
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006278 - percent-to-uppercase: Uppercases letters within percent-encoded sequences
Tim Duesterhusc315efd2021-04-21 21:20:34 +02006279 (RFC 3986#6.2.2.1).
Tim Duesterhusa4071932021-04-15 21:46:02 +02006280
6281 Example:
6282 - /%6f -> /%6F
6283 - /%zz -> /%zz
6284
6285 If the "strict" option is specified then invalid sequences will result
6286 in a HTTP 400 Bad Request being returned.
6287
6288 Example:
6289 - /%zz -> HTTP 400
6290
Tim Duesterhus5be6ab22021-04-17 11:21:10 +02006291 - query-sort-by-name: Sorts the query string parameters by parameter name.
Tim Duesterhusd7b89be2021-04-15 21:46:01 +02006292 Parameters are assumed to be delimited by '&'. Shorter names sort before
6293 longer names and identical parameter names maintain their relative order.
6294
6295 Example:
6296 - /?c=3&a=1&b=2 -> /?a=1&b=2&c=3
6297 - /?aaa=3&a=1&aa=2 -> /?a=1&aa=2&aaa=3
6298 - /?a=3&b=4&a=1&b=5&a=2 -> /?a=3&a=1&a=2&b=4&b=5
6299
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006300http-request redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006301
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006302 This performs an HTTP redirection based on a redirect rule. This is exactly
6303 the same as the "redirect" statement except that it inserts a redirect rule
6304 which can be processed in the middle of other "http-request" rules and that
6305 these rules use the "log-format" strings. See the "redirect" keyword for the
6306 rule's syntax.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006307
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006308http-request reject [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006309
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006310 This stops the evaluation of the rules and immediately closes the connection
6311 without sending any response. It acts similarly to the
6312 "tcp-request content reject" rules. It can be useful to force an immediate
6313 connection closure on HTTP/2 connections.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006314
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006315http-request replace-header <name> <match-regex> <replace-fmt>
6316 [ { if | unless } <condition> ]
Willy Tarreaua9083d02015-05-08 15:27:59 +02006317
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006318 This matches the value of all occurrences of header field <name> against
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006319 <match-regex>. Matching is performed case-sensitively. Matching values are
6320 completely replaced by <replace-fmt>. Format characters are allowed in
6321 <replace-fmt> and work like <fmt> arguments in "http-request add-header".
6322 Standard back-references using the backslash ('\') followed by a number are
6323 supported.
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02006324
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006325 This action acts on whole header lines, regardless of the number of values
6326 they may contain. Thus it is well-suited to process headers naturally
6327 containing commas in their value, such as If-Modified-Since. Headers that
6328 contain a comma-separated list of values, such as Accept, should be processed
6329 using "http-request replace-value".
William Lallemand86d0df02017-11-24 21:36:45 +01006330
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006331 Example:
6332 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
6333
6334 # applied to:
6335 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
6336
6337 # outputs:
6338 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
6339
6340 # assuming the backend IP is 192.168.1.20
Willy Tarreau09448f72014-06-25 18:12:15 +02006341
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006342 http-request replace-header User-Agent curl foo
6343
6344 # applied to:
6345 User-Agent: curl/7.47.0
Willy Tarreau09448f72014-06-25 18:12:15 +02006346
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006347 # outputs:
6348 User-Agent: foo
Willy Tarreau09448f72014-06-25 18:12:15 +02006349
Willy Tarreau262c3f12019-12-17 06:52:51 +01006350http-request replace-path <match-regex> <replace-fmt>
6351 [ { if | unless } <condition> ]
6352
6353 This works like "replace-header" except that it works on the request's path
6354 component instead of a header. The path component starts at the first '/'
Christopher Faulet82c83322020-09-02 14:16:59 +02006355 after an optional scheme+authority and ends before the question mark. Thus,
6356 the replacement does not modify the scheme, the authority and the
6357 query-string.
Willy Tarreau262c3f12019-12-17 06:52:51 +01006358
6359 It is worth noting that regular expressions may be more expensive to evaluate
6360 than certain ACLs, so rare replacements may benefit from a condition to avoid
6361 performing the evaluation at all if it does not match.
6362
6363 Example:
6364 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
6365 http-request replace-path (.*) /foo\1
6366
Willy Tarreau262c3f12019-12-17 06:52:51 +01006367 # strip /foo : turn /foo/bar?q=1 into /bar?q=1
6368 http-request replace-path /foo/(.*) /\1
6369 # or more efficient if only some requests match :
6370 http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ }
6371
Christopher Faulet312294f2020-09-02 17:17:44 +02006372http-request replace-pathq <match-regex> <replace-fmt>
6373 [ { if | unless } <condition> ]
6374
6375 This does the same as "http-request replace-path" except that the path
6376 contains the query-string if any is present. Thus, the path and the
6377 query-string are replaced.
6378
6379 Example:
6380 # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 :
6381 http-request replace-pathq ([^?]*)(\?(.*))? \1/foo\2
6382
Willy Tarreau33810222019-06-12 17:44:02 +02006383http-request replace-uri <match-regex> <replace-fmt>
6384 [ { if | unless } <condition> ]
6385
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006386 This works like "replace-header" except that it works on the request's URI part
6387 instead of a header. The URI part may contain an optional scheme, authority or
6388 query string. These are considered to be part of the value that is matched
6389 against.
6390
6391 It is worth noting that regular expressions may be more expensive to evaluate
6392 than certain ACLs, so rare replacements may benefit from a condition to avoid
6393 performing the evaluation at all if it does not match.
Willy Tarreau33810222019-06-12 17:44:02 +02006394
Willy Tarreau62b59132019-12-17 06:51:20 +01006395 IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent
6396 by browsers use the "origin form", which differs from the "absolute form" in
6397 that they do not contain a scheme nor authority in the URI portion. Mostly
6398 only requests sent to proxies, those forged by hand and some emitted by
6399 certain applications use the absolute form. As such, "replace-uri" usually
6400 works fine most of the time in HTTP/1.x with rules starting with a "/". But
6401 with HTTP/2, clients are encouraged to send absolute URIs only, which look
6402 like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri
6403 rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need
Willy Tarreau262c3f12019-12-17 06:52:51 +01006404 to be adapted to optionally match a scheme and authority, or replace-path
6405 should be used.
Willy Tarreau33810222019-06-12 17:44:02 +02006406
Willy Tarreau62b59132019-12-17 06:51:20 +01006407 Example:
6408 # rewrite all "http" absolute requests to "https":
6409 http-request replace-uri ^http://(.*) https://\1
Willy Tarreau33810222019-06-12 17:44:02 +02006410
Willy Tarreau62b59132019-12-17 06:51:20 +01006411 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
6412 http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2
Willy Tarreau33810222019-06-12 17:44:02 +02006413
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006414http-request replace-value <name> <match-regex> <replace-fmt>
6415 [ { if | unless } <condition> ]
Willy Tarreau09448f72014-06-25 18:12:15 +02006416
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006417 This works like "replace-header" except that it matches the regex against
6418 every comma-delimited value of the header field <name> instead of the
6419 entire header. This is suited for all headers which are allowed to carry
6420 more than one value. An example could be the Accept header.
Willy Tarreau09448f72014-06-25 18:12:15 +02006421
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006422 Example:
6423 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
Thierry FOURNIER236657b2015-08-19 08:25:14 +02006424
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006425 # applied to:
6426 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02006427
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006428 # outputs:
6429 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 +01006430
Christopher Faulet24231ab2020-01-24 17:44:23 +01006431http-request return [status <code>] [content-type <type>]
6432 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
6433 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
Christopher Faulet4a2c1422020-01-31 17:36:01 +01006434 [ hdr <name> <fmt> ]*
Christopher Faulet24231ab2020-01-24 17:44:23 +01006435 [ { if | unless } <condition> ]
6436
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006437 This stops the evaluation of the rules and immediately returns a response. The
Christopher Faulet24231ab2020-01-24 17:44:23 +01006438 default status code used for the response is 200. It can be optionally
6439 specified as an arguments to "status". The response content-type may also be
Daniel Corbett67a82712020-07-06 23:01:19 -04006440 specified as an argument to "content-type". Finally the response itself may
Sébastien Grossab877122020-10-08 10:06:03 +02006441 be defined. It can be a full HTTP response specifying the errorfile to use,
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006442 or the response payload specifying the file or the string to use. These rules
Christopher Faulet24231ab2020-01-24 17:44:23 +01006443 are followed to create the response :
6444
6445 * If neither the errorfile nor the payload to use is defined, a dummy
6446 response is returned. Only the "status" argument is considered. It can be
6447 any code in the range [200, 599]. The "content-type" argument, if any, is
6448 ignored.
6449
6450 * If "default-errorfiles" argument is set, the proxy's errorfiles are
6451 considered. If the "status" argument is defined, it must be one of the
Daniel Corbett9f0843f2021-05-08 10:50:37 -04006452 status code handled by HAProxy (200, 400, 403, 404, 405, 408, 410, 413,
Christopher Faulete095f312020-12-07 11:22:24 +01006453 425, 429, 500, 501, 502, 503, and 504). The "content-type" argument, if
6454 any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006455
6456 * If a specific errorfile is defined, with an "errorfile" argument, the
6457 corresponding file, containing a full HTTP response, is returned. Only the
6458 "status" argument is considered. It must be one of the status code handled
Daniel Corbett9f0843f2021-05-08 10:50:37 -04006459 by HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 501,
Christopher Faulete095f312020-12-07 11:22:24 +01006460 502, 503, and 504). The "content-type" argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006461
6462 * If an http-errors section is defined, with an "errorfiles" argument, the
6463 corresponding file in the specified http-errors section, containing a full
6464 HTTP response, is returned. Only the "status" argument is considered. It
Daniel Corbett9f0843f2021-05-08 10:50:37 -04006465 must be one of the status code handled by HAProxy (200, 400, 403, 404, 405,
Christopher Faulete095f312020-12-07 11:22:24 +01006466 408, 410, 413, 425, 429, 500, 501, 502, 503, and 504). The "content-type"
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02006467 argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006468
6469 * If a "file" or a "lf-file" argument is specified, the file's content is
6470 used as the response payload. If the file is not empty, its content-type
6471 must be set as argument to "content-type". Otherwise, any "content-type"
6472 argument is ignored. With a "lf-file" argument, the file's content is
6473 evaluated as a log-format string. With a "file" argument, it is considered
6474 as a raw content.
6475
6476 * If a "string" or "lf-string" argument is specified, the defined string is
6477 used as the response payload. The content-type must always be set as
6478 argument to "content-type". With a "lf-string" argument, the string is
6479 evaluated as a log-format string. With a "string" argument, it is
6480 considered as a raw string.
6481
Sébastien Grossab877122020-10-08 10:06:03 +02006482 When the response is not based on an errorfile, it is possible to append HTTP
Christopher Faulet4a2c1422020-01-31 17:36:01 +01006483 header fields to the response using "hdr" arguments. Otherwise, all "hdr"
6484 arguments are ignored. For each one, the header name is specified in <name>
6485 and its value is defined by <fmt> which follows the log-format rules.
6486
Christopher Faulet24231ab2020-01-24 17:44:23 +01006487 Note that the generated response must be smaller than a buffer. And to avoid
6488 any warning, when an errorfile or a raw file is loaded, the buffer space
Sébastien Grossab877122020-10-08 10:06:03 +02006489 reserved for the headers rewriting should also be free.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006490
6491 No further "http-request" rules are evaluated.
6492
6493 Example:
Daniel Corbett67a82712020-07-06 23:01:19 -04006494 http-request return errorfile /etc/haproxy/errorfiles/200.http \
Christopher Faulet24231ab2020-01-24 17:44:23 +01006495 if { path /ping }
6496
6497 http-request return content-type image/x-icon file /var/www/favicon.ico \
6498 if { path /favicon.ico }
6499
6500 http-request return status 403 content-type text/plain \
6501 lf-string "Access denied. IP %[src] is blacklisted." \
6502 if { src -f /etc/haproxy/blacklist.lst }
6503
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006504http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
6505http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006506
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006507 This actions increments the GPC0 or GPC1 counter according with the sticky
6508 counter designated by <sc-id>. If an error occurs, this action silently fails
6509 and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006510
Cédric Dufour0d7712d2019-11-06 18:38:53 +01006511http-request sc-set-gpt0(<sc-id>) { <int> | <expr> }
6512 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006513
Cédric Dufour0d7712d2019-11-06 18:38:53 +01006514 This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
6515 designated by <sc-id> and the value of <int>/<expr>. The expected result is a
6516 boolean. If an error occurs, this action silently fails and the actions
6517 evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006518
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006519http-request set-dst <expr> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006520
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006521 This is used to set the destination IP address to the value of specified
6522 expression. Useful when a proxy in front of HAProxy rewrites destination IP,
6523 but provides the correct IP in a HTTP header; or you want to mask the IP for
6524 privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
6525 server address in the backend.
Christopher Faulet85d79c92016-11-09 16:54:56 +01006526
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006527 Arguments:
6528 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
6529 by some converters.
Christopher Faulet85d79c92016-11-09 16:54:56 +01006530
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006531 Example:
6532 http-request set-dst hdr(x-dst)
6533 http-request set-dst dst,ipmask(24)
Christopher Faulet85d79c92016-11-09 16:54:56 +01006534
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006535 When possible, set-dst preserves the original destination port as long as the
6536 address family allows it, otherwise the destination port is set to 0.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02006537
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006538http-request set-dst-port <expr> [ { if | unless } <condition> ]
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02006539
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006540 This is used to set the destination port address to the value of specified
6541 expression. If you want to connect to the new address/port, use '0.0.0.0:0'
6542 as a server address in the backend.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02006543
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006544 Arguments:
6545 <expr> Is a standard HAProxy expression formed by a sample-fetch
6546 followed by some converters.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02006547
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006548 Example:
6549 http-request set-dst-port hdr(x-port)
6550 http-request set-dst-port int(4000)
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02006551
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006552 When possible, set-dst-port preserves the original destination address as
6553 long as the address family supports a port, otherwise it forces the
6554 destination address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02006555
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006556http-request set-header <name> <fmt> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02006557
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006558 This does the same as "http-request add-header" except that the header name
6559 is first removed if it existed. This is useful when passing security
6560 information to the server, where the header must not be manipulated by
6561 external users. Note that the new value is computed before the removal so it
6562 is possible to concatenate a value to an existing header.
William Lallemand44be6402016-05-25 01:51:35 +02006563
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006564 Example:
6565 http-request set-header X-Haproxy-Current-Date %T
6566 http-request set-header X-SSL %[ssl_fc]
6567 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
6568 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
6569 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
6570 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
6571 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
6572 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
6573 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
William Lallemand44be6402016-05-25 01:51:35 +02006574
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006575http-request set-log-level <level> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02006576
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006577 This is used to change the log level of the current request when a certain
6578 condition is met. Valid levels are the 8 syslog levels (see the "log"
6579 keyword) plus the special level "silent" which disables logging for this
6580 request. This rule is not final so the last matching rule wins. This rule
6581 can be useful to disable health checks coming from another equipment.
William Lallemand13e9b0c2016-05-25 02:34:07 +02006582
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006583http-request set-map(<file-name>) <key fmt> <value fmt>
6584 [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02006585
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006586 This is used to add a new entry into a MAP. The MAP must be loaded from a
6587 file (even a dummy empty file). The file name of the MAP to be updated is
6588 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
6589 log-format rules, used to collect MAP key, and <value fmt>, which follows
6590 log-format rules, used to collect content for the new entry.
6591 It performs a lookup in the MAP before insertion, to avoid duplicated (or
6592 more) values. This lookup is done by a linear search and can be expensive
6593 with large lists! It is the equivalent of the "set map" command from the
6594 stats socket, but can be triggered by an HTTP request.
William Lallemand13e9b0c2016-05-25 02:34:07 +02006595
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006596http-request set-mark <mark> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02006597
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006598 This is used to set the Netfilter MARK on all packets sent to the client to
6599 the value passed in <mark> on platforms which support it. This value is an
6600 unsigned 32 bit value which can be matched by netfilter and by the routing
6601 table. It can be expressed both in decimal or hexadecimal format (prefixed by
6602 "0x"). This can be useful to force certain packets to take a different route
6603 (for example a cheaper network path for bulk downloads). This works on Linux
6604 kernels 2.6.32 and above and requires admin privileges.
Willy Tarreau00005ce2016-10-21 15:07:45 +02006605
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006606http-request set-method <fmt> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02006607
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006608 This rewrites the request method with the result of the evaluation of format
6609 string <fmt>. There should be very few valid reasons for having to do so as
6610 this is more likely to break something than to fix it.
William Lallemand13e9b0c2016-05-25 02:34:07 +02006611
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006612http-request set-nice <nice> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02006613
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006614 This sets the "nice" factor of the current request being processed. It only
6615 has effect against the other requests being processed at the same time.
6616 The default value is 0, unless altered by the "nice" setting on the "bind"
6617 line. The accepted range is -1024..1024. The higher the value, the nicest
6618 the request will be. Lower values will make the request more important than
6619 other ones. This can be useful to improve the speed of some requests, or
6620 lower the priority of non-important requests. Using this setting without
6621 prior experimentation can cause some major slowdown.
William Lallemand13e9b0c2016-05-25 02:34:07 +02006622
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006623http-request set-path <fmt> [ { if | unless } <condition> ]
Willy Tarreau00005ce2016-10-21 15:07:45 +02006624
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006625 This rewrites the request path with the result of the evaluation of format
6626 string <fmt>. The query string, if any, is left intact. If a scheme and
6627 authority is found before the path, they are left intact as well. If the
6628 request doesn't have a path ("*"), this one is replaced with the format.
6629 This can be used to prepend a directory component in front of a path for
6630 example. See also "http-request set-query" and "http-request set-uri".
Willy Tarreau2d392c22015-08-24 01:43:45 +02006631
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006632 Example :
6633 # prepend the host name before the path
6634 http-request set-path /%[hdr(host)]%[path]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006635
Christopher Faulet312294f2020-09-02 17:17:44 +02006636http-request set-pathq <fmt> [ { if | unless } <condition> ]
6637
6638 This does the same as "http-request set-path" except that the query-string is
6639 also rewritten. It may be used to remove the query-string, including the
6640 question mark (it is not possible using "http-request set-query").
6641
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006642http-request set-priority-class <expr> [ { if | unless } <condition> ]
Olivier Houchardccaa7de2017-10-02 11:51:03 +02006643
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006644 This is used to set the queue priority class of the current request.
6645 The value must be a sample expression which converts to an integer in the
6646 range -2047..2047. Results outside this range will be truncated.
6647 The priority class determines the order in which queued requests are
6648 processed. Lower values have higher priority.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006649
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006650http-request set-priority-offset <expr> [ { if | unless } <condition> ]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006651
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006652 This is used to set the queue priority timestamp offset of the current
6653 request. The value must be a sample expression which converts to an integer
6654 in the range -524287..524287. Results outside this range will be truncated.
6655 When a request is queued, it is ordered first by the priority class, then by
6656 the current timestamp adjusted by the given offset in milliseconds. Lower
6657 values have higher priority.
6658 Note that the resulting timestamp is is only tracked with enough precision
6659 for 524,287ms (8m44s287ms). If the request is queued long enough to where the
6660 adjusted timestamp exceeds this value, it will be misidentified as highest
6661 priority. Thus it is important to set "timeout queue" to a value, where when
6662 combined with the offset, does not exceed this limit.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006663
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006664http-request set-query <fmt> [ { if | unless } <condition> ]
Willy Tarreau20b0de52012-12-24 15:45:22 +01006665
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006666 This rewrites the request's query string which appears after the first
6667 question mark ("?") with the result of the evaluation of format string <fmt>.
6668 The part prior to the question mark is left intact. If the request doesn't
6669 contain a question mark and the new value is not empty, then one is added at
6670 the end of the URI, followed by the new value. If a question mark was
6671 present, it will never be removed even if the value is empty. This can be
6672 used to add or remove parameters from the query string.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08006673
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006674 See also "http-request set-query" and "http-request set-uri".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01006675
6676 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006677 # replace "%3D" with "=" in the query string
6678 http-request set-query %[query,regsub(%3D,=,g)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01006679
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006680http-request set-src <expr> [ { if | unless } <condition> ]
6681 This is used to set the source IP address to the value of specified
6682 expression. Useful when a proxy in front of HAProxy rewrites source IP, but
6683 provides the correct IP in a HTTP header; or you want to mask source IP for
Olivier Doucet56e31202020-04-21 09:32:56 +02006684 privacy. All subsequent calls to "src" fetch will return this value
6685 (see example).
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006686
6687 Arguments :
6688 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
6689 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01006690
Olivier Doucet56e31202020-04-21 09:32:56 +02006691 See also "option forwardfor".
6692
Cyril Bonté78caf842010-03-10 22:41:43 +01006693 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006694 http-request set-src hdr(x-forwarded-for)
6695 http-request set-src src,ipmask(24)
6696
Olivier Doucet56e31202020-04-21 09:32:56 +02006697 # After the masking this will track connections
6698 # based on the IP address with the last byte zeroed out.
6699 http-request track-sc0 src
6700
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006701 When possible, set-src preserves the original source port as long as the
6702 address family allows it, otherwise the source port is set to 0.
6703
6704http-request set-src-port <expr> [ { if | unless } <condition> ]
6705
6706 This is used to set the source port address to the value of specified
6707 expression.
6708
6709 Arguments:
6710 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
6711 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01006712
Willy Tarreau20b0de52012-12-24 15:45:22 +01006713 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006714 http-request set-src-port hdr(x-port)
6715 http-request set-src-port int(4000)
6716
6717 When possible, set-src-port preserves the original source address as long as
6718 the address family supports a port, otherwise it forces the source address to
6719 IPv4 "0.0.0.0" before rewriting the port.
6720
Alex59c53352021-04-27 12:57:07 +02006721http-request set-timeout { server | tunnel } { <timeout> | <expr> }
Amaury Denoyelle8d228232020-12-10 13:43:54 +01006722 [ { if | unless } <condition> ]
6723
6724 This action overrides the specified "server" or "tunnel" timeout for the
6725 current stream only. The timeout can be specified in millisecond or with any
6726 other unit if the number is suffixed by the unit as explained at the top of
6727 this document. It is also possible to write an expression which must returns
6728 a number interpreted as a timeout in millisecond.
6729
6730 Note that the server/tunnel timeouts are only relevant on the backend side
6731 and thus this rule is only available for the proxies with backend
6732 capabilities. Also the timeout value must be non-null to obtain the expected
6733 results.
6734
6735 Example:
Alex59c53352021-04-27 12:57:07 +02006736 http-request set-timeout tunnel 5s
6737 http-request set-timeout server req.hdr(host),map_int(host.lst)
Amaury Denoyelle8d228232020-12-10 13:43:54 +01006738
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006739http-request set-tos <tos> [ { if | unless } <condition> ]
6740
6741 This is used to set the TOS or DSCP field value of packets sent to the client
6742 to the value passed in <tos> on platforms which support this. This value
6743 represents the whole 8 bits of the IP TOS field, and can be expressed both in
6744 decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
6745 bits are used in DSCP or TOS, and the two lower bits are always 0. This can
6746 be used to adjust some routing behavior on border routers based on some
6747 information from the request.
6748
6749 See RFC 2474, 2597, 3260 and 4594 for more information.
6750
6751http-request set-uri <fmt> [ { if | unless } <condition> ]
6752
6753 This rewrites the request URI with the result of the evaluation of format
6754 string <fmt>. The scheme, authority, path and query string are all replaced
6755 at once. This can be used to rewrite hosts in front of proxies, or to
6756 perform complex modifications to the URI such as moving parts between the
6757 path and the query string.
6758 See also "http-request set-path" and "http-request set-query".
6759
6760http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ]
6761
6762 This is used to set the contents of a variable. The variable is declared
6763 inline.
6764
6765 Arguments:
6766 <var-name> The name of the variable starts with an indication about its
6767 scope. The scopes allowed are:
6768 "proc" : the variable is shared with the whole process
6769 "sess" : the variable is shared with the whole session
6770 "txn" : the variable is shared with the transaction
6771 (request and response)
6772 "req" : the variable is shared only during request
6773 processing
6774 "res" : the variable is shared only during response
6775 processing
6776 This prefix is followed by a name. The separator is a '.'.
6777 The name may only contain characters 'a-z', 'A-Z', '0-9'
6778 and '_'.
6779
6780 <expr> Is a standard HAProxy expression formed by a sample-fetch
6781 followed by some converters.
Willy Tarreau20b0de52012-12-24 15:45:22 +01006782
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006783 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006784 http-request set-var(req.my_var) req.fhdr(user-agent),lower
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006785
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006786http-request send-spoe-group <engine-name> <group-name>
6787 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006788
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006789 This action is used to trigger sending of a group of SPOE messages. To do so,
6790 the SPOE engine used to send messages must be defined, as well as the SPOE
6791 group to send. Of course, the SPOE engine must refer to an existing SPOE
6792 filter. If not engine name is provided on the SPOE filter line, the SPOE
6793 agent name must be used.
6794
6795 Arguments:
6796 <engine-name> The SPOE engine name.
6797
6798 <group-name> The SPOE group name as specified in the engine
6799 configuration.
6800
6801http-request silent-drop [ { if | unless } <condition> ]
6802
6803 This stops the evaluation of the rules and makes the client-facing connection
6804 suddenly disappear using a system-dependent way that tries to prevent the
6805 client from being notified. The effect it then that the client still sees an
6806 established connection while there's none on HAProxy. The purpose is to
6807 achieve a comparable effect to "tarpit" except that it doesn't use any local
6808 resource at all on the machine running HAProxy. It can resist much higher
6809 loads than "tarpit", and slow down stronger attackers. It is important to
6810 understand the impact of using this mechanism. All stateful equipment placed
6811 between the client and HAProxy (firewalls, proxies, load balancers) will also
6812 keep the established connection for a long time and may suffer from this
6813 action.
6814 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
6815 option is used to block the emission of a TCP reset. On other systems, the
6816 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
6817 router, though it's still delivered to local networks. Do not use it unless
6818 you fully understand how it works.
6819
Christopher Faulet46f95542019-12-20 10:07:22 +01006820http-request strict-mode { on | off }
6821
6822 This enables or disables the strict rewriting mode for following rules. It
6823 does not affect rules declared before it and it is only applicable on rules
6824 performing a rewrite on the requests. When the strict mode is enabled, any
6825 rewrite failure triggers an internal error. Otherwise, such errors are
6826 silently ignored. The purpose of the strict rewriting mode is to make some
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006827 rewrites optional while others must be performed to continue the request
Christopher Faulet46f95542019-12-20 10:07:22 +01006828 processing.
6829
Christopher Faulet1aea50e2020-01-17 16:03:53 +01006830 By default, the strict rewriting mode is enabled. Its value is also reset
Christopher Faulet46f95542019-12-20 10:07:22 +01006831 when a ruleset evaluation ends. So, for instance, if you change the mode on
6832 the frontend, the default mode is restored when HAProxy starts the backend
6833 rules evaluation.
6834
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006835http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
6836http-request tarpit [ { status | deny_status } <code>] [content-type <type>]
6837 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
6838 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
6839 [ hdr <name> <fmt> ]*
6840 [ { if | unless } <condition> ]
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006841
6842 This stops the evaluation of the rules and immediately blocks the request
6843 without responding for a delay specified by "timeout tarpit" or
6844 "timeout connect" if the former is not set. After that delay, if the client
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006845 is still connected, a response is returned so that the client does not
6846 suspect it has been tarpitted. Logs will report the flags "PT". The goal of
6847 the tarpit rule is to slow down robots during an attack when they're limited
6848 on the number of concurrent requests. It can be very efficient against very
6849 dumb robots, and will significantly reduce the load on firewalls compared to
6850 a "deny" rule. But when facing "correctly" developed robots, it can make
Daniel Corbett9f0843f2021-05-08 10:50:37 -04006851 things worse by forcing HAProxy and the front firewall to support insane
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006852 number of concurrent connections. By default an HTTP error 500 is returned.
6853 But the response may be customized using same syntax than
6854 "http-request return" rules. Thus, see "http-request return" for details.
Ilya Shipitsin11057a32020-06-21 21:18:27 +05006855 For compatibility purpose, when no argument is defined, or only "deny_status",
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006856 the argument "default-errorfiles" is implied. It means
6857 "http-request tarpit [deny_status <status>]" is an alias of
6858 "http-request tarpit [status <status>] default-errorfiles".
6859 No further "http-request" rules are evaluated.
6860 See also "http-request return" and "http-request silent-drop".
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006861
6862http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
6863http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
6864http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
6865
6866 This enables tracking of sticky counters from current request. These rules do
6867 not stop evaluation and do not change default action. The number of counters
6868 that may be simultaneously tracked by the same connection is set in
6869 MAX_SESS_STKCTR at build time (reported in haproxy -vv) which defaults to 3,
Matteo Contrini1857b8c2020-10-16 17:35:54 +02006870 so the track-sc number is between 0 and (MAX_SESS_STKCTR-1). The first
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006871 "track-sc0" rule executed enables tracking of the counters of the specified
6872 table as the first set. The first "track-sc1" rule executed enables tracking
6873 of the counters of the specified table as the second set. The first
6874 "track-sc2" rule executed enables tracking of the counters of the specified
6875 table as the third set. It is a recommended practice to use the first set of
6876 counters for the per-frontend counters and the second set for the per-backend
6877 ones. But this is just a guideline, all may be used everywhere.
6878
6879 Arguments :
6880 <key> is mandatory, and is a sample expression rule as described in
6881 section 7.3. It describes what elements of the incoming request or
6882 connection will be analyzed, extracted, combined, and used to
6883 select which table entry to update the counters.
6884
6885 <table> is an optional table to be used instead of the default one, which
6886 is the stick-table declared in the current proxy. All the counters
6887 for the matches and updates for the key will then be performed in
6888 that table until the session ends.
6889
6890 Once a "track-sc*" rule is executed, the key is looked up in the table and if
6891 it is not found, an entry is allocated for it. Then a pointer to that entry
6892 is kept during all the session's life, and this entry's counters are updated
6893 as often as possible, every time the session's counters are updated, and also
6894 systematically when the session ends. Counters are only updated for events
6895 that happen after the tracking has been started. As an exception, connection
6896 counters and request counters are systematically updated so that they reflect
6897 useful information.
6898
6899 If the entry tracks concurrent connection counters, one connection is counted
6900 for as long as the entry is tracked, and the entry will not expire during
6901 that time. Tracking counters also provides a performance advantage over just
6902 checking the keys, because only one table lookup is performed for all ACL
6903 checks that make use of it.
6904
6905http-request unset-var(<var-name>) [ { if | unless } <condition> ]
6906
6907 This is used to unset a variable. See above for details about <var-name>.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006908
6909 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006910 http-request unset-var(req.my_var)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006911
Christopher Faulet579d83b2019-11-22 15:34:17 +01006912http-request use-service <service-name> [ { if | unless } <condition> ]
6913
6914 This directive executes the configured HTTP service to reply to the request
6915 and stops the evaluation of the rules. An HTTP service may choose to reply by
6916 sending any valid HTTP response or it may immediately close the connection
6917 without sending any response. Outside natives services, for instance the
6918 Prometheus exporter, it is possible to write your own services in Lua. No
6919 further "http-request" rules are evaluated.
6920
6921 Arguments :
6922 <service-name> is mandatory. It is the service to call
6923
6924 Example:
6925 http-request use-service prometheus-exporter if { path /metrics }
6926
Christopher Faulet021a8e42021-03-29 10:46:38 +02006927http-request wait-for-body time <time> [ at-least <bytes> ]
6928 [ { if | unless } <condition> ]
6929
6930 This will delay the processing of the request waiting for the payload for at
6931 most <time> milliseconds. if "at-least" argument is specified, HAProxy stops
6932 to wait the payload when the first <bytes> bytes are received. 0 means no
6933 limit, it is the default value. Regardless the "at-least" argument value,
6934 HAProxy stops to wait if the whole payload is received or if the request
6935 buffer is full. This action may be used as a replacement to "option
6936 http-buffer-request".
6937
6938 Arguments :
6939
6940 <time> is mandatory. It is the maximum time to wait for the body. It
6941 follows the HAProxy time format and is expressed in milliseconds.
6942
6943 <bytes> is optional. It is the minimum payload size to receive to stop to
Ilya Shipitsinb2be9a12021-04-24 13:25:42 +05006944 wait. It follows the HAProxy size format and is expressed in
Christopher Faulet021a8e42021-03-29 10:46:38 +02006945 bytes.
6946
6947 Example:
6948 http-request wait-for-body time 1s at-least 1k if METH_POST
6949
6950 See also : "option http-buffer-request"
6951
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006952http-request wait-for-handshake [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006953
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006954 This will delay the processing of the request until the SSL handshake
6955 happened. This is mostly useful to delay processing early data until we're
6956 sure they are valid.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006957
Willy Tarreauef781042010-01-27 11:53:01 +01006958
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006959http-response <action> <options...> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006960 Access control for Layer 7 responses
6961
6962 May be used in sections: defaults | frontend | listen | backend
6963 no | yes | yes | yes
6964
6965 The http-response statement defines a set of rules which apply to layer 7
6966 processing. The rules are evaluated in their declaration order when they are
6967 met in a frontend, listen or backend section. Any rule may optionally be
6968 followed by an ACL-based condition, in which case it will only be evaluated
6969 if the condition is true. Since these rules apply on responses, the backend
6970 rules are applied first, followed by the frontend's rules.
6971
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006972 The first keyword is the rule's action. The supported actions are described
6973 below.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006974
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006975 There is no limit to the number of http-response statements per instance.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006976
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006977 Example:
6978 acl key_acl res.hdr(X-Acl-Key) -m found
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02006979
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006980 acl myhost hdr(Host) -f myhost.lst
Sasha Pachev218f0642014-06-16 12:05:59 -06006981
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006982 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
6983 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
Sasha Pachev218f0642014-06-16 12:05:59 -06006984
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006985 Example:
6986 acl value res.hdr(X-Value) -m found
Sasha Pachev218f0642014-06-16 12:05:59 -06006987
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006988 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06006989
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006990 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
6991 http-response del-map(map.lst) %[src] if ! value
Sasha Pachev218f0642014-06-16 12:05:59 -06006992
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006993 See also : "http-request", section 3.4 about userlists and section 7 about
6994 ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06006995
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006996http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006997
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006998 This is used to add a new entry into an ACL. The ACL must be loaded from a
6999 file (even a dummy empty file). The file name of the ACL to be updated is
7000 passed between parentheses. It takes one argument: <key fmt>, which follows
7001 log-format rules, to collect content of the new entry. It performs a lookup
7002 in the ACL before insertion, to avoid duplicated (or more) values.
7003 This lookup is done by a linear search and can be expensive with large lists!
7004 It is the equivalent of the "add acl" command from the stats socket, but can
7005 be triggered by an HTTP response.
Sasha Pachev218f0642014-06-16 12:05:59 -06007006
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007007http-response add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06007008
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007009 This appends an HTTP header field whose name is specified in <name> and whose
7010 value is defined by <fmt> which follows the log-format rules (see Custom Log
7011 Format in section 8.2.4). This may be used to send a cookie to a client for
7012 example, or to pass some internal information.
7013 This rule is not final, so it is possible to add other similar rules.
7014 Note that header addition is performed immediately, so one rule might reuse
7015 the resulting header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06007016
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007017http-response allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06007018
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007019 This stops the evaluation of the rules and lets the response pass the check.
7020 No further "http-response" rules are evaluated for the current section.
Sasha Pachev218f0642014-06-16 12:05:59 -06007021
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02007022http-response cache-store <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06007023
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02007024 See section 6.2 about cache setup.
Sasha Pachev218f0642014-06-16 12:05:59 -06007025
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007026http-response capture <sample> id <id> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06007027
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007028 This captures sample expression <sample> from the response buffer, and
7029 converts it to a string. The resulting string is stored into the next request
7030 "capture" slot, so it will possibly appear next to some captured HTTP
7031 headers. It will then automatically appear in the logs, and it will be
7032 possible to extract it using sample fetch rules to feed it into headers or
7033 anything. Please check section 7.3 (Fetching samples) and
7034 "capture response header" for more information.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02007035
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007036 The keyword "id" is the id of the capture slot which is used for storing the
7037 string. The capture slot must be defined in an associated frontend.
7038 This is useful to run captures in backends. The slot id can be declared by a
7039 previous directive "http-response capture" or with the "declare capture"
7040 keyword.
Baptiste Assmann19a69b32020-01-16 14:34:22 +01007041
7042 When using this action in a backend, double check that the relevant
7043 frontend(s) have the required capture slots otherwise, this rule will be
7044 ignored at run time. This can't be detected at configuration parsing time
7045 due to HAProxy's ability to dynamically resolve backend name at runtime.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02007046
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007047http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02007048
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007049 This is used to delete an entry from an ACL. The ACL must be loaded from a
7050 file (even a dummy empty file). The file name of the ACL to be updated is
7051 passed between parentheses. It takes one argument: <key fmt>, which follows
7052 log-format rules, to collect content of the entry to delete.
7053 It is the equivalent of the "del acl" command from the stats socket, but can
7054 be triggered by an HTTP response.
Willy Tarreauf4c43c12013-06-11 17:01:13 +02007055
Maciej Zdebebdd4c52020-11-20 13:58:48 +00007056http-response del-header <name> [ -m <meth> ] [ { if | unless } <condition> ]
Willy Tarreau9a355ec2013-06-11 17:45:46 +02007057
Maciej Zdebebdd4c52020-11-20 13:58:48 +00007058 This removes all HTTP header fields whose name is specified in <name>. <meth>
7059 is the matching method, applied on the header name. Supported matching methods
7060 are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub"
7061 (substring match) and "reg" (regex match). If not specified, exact matching
7062 method is used.
Willy Tarreau42cf39e2013-06-11 18:51:32 +02007063
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007064http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau51347ed2013-06-11 19:34:13 +02007065
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007066 This is used to delete an entry from a MAP. The MAP must be loaded from a
7067 file (even a dummy empty file). The file name of the MAP to be updated is
7068 passed between parentheses. It takes one argument: <key fmt>, which follows
7069 log-format rules, to collect content of the entry to delete.
7070 It takes one argument: "file name" It is the equivalent of the "del map"
7071 command from the stats socket, but can be triggered by an HTTP response.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007072
Christopher Faulet5cb513a2020-05-13 17:56:56 +02007073http-response deny [deny_status <status>] [ { if | unless } <condition> ]
7074http-response deny [ { status | deny_status } <code>] [content-type <type>]
7075 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
7076 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
7077 [ hdr <name> <fmt> ]*
7078 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007079
Christopher Faulet5cb513a2020-05-13 17:56:56 +02007080 This stops the evaluation of the rules and immediately rejects the response.
7081 By default an HTTP 502 error is returned. But the response may be customized
7082 using same syntax than "http-response return" rules. Thus, see
Ilya Shipitsin11057a32020-06-21 21:18:27 +05007083 "http-response return" for details. For compatibility purpose, when no
Christopher Faulet5cb513a2020-05-13 17:56:56 +02007084 argument is defined, or only "deny_status", the argument "default-errorfiles"
7085 is implied. It means "http-response deny [deny_status <status>]" is an alias
7086 of "http-response deny [status <status>] default-errorfiles".
Christopher Faulet040c8cd2020-01-13 16:43:45 +01007087 No further "http-response" rules are evaluated.
Christopher Faulet5cb513a2020-05-13 17:56:56 +02007088 See also "http-response return".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007089
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007090http-response redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007091
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007092 This performs an HTTP redirection based on a redirect rule.
7093 This supports a format string similarly to "http-request redirect" rules,
7094 with the exception that only the "location" type of redirect is possible on
7095 the response. See the "redirect" keyword for the rule's syntax. When a
7096 redirect rule is applied during a response, connections to the server are
7097 closed so that no data can be forwarded from the server to the client.
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02007098
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007099http-response replace-header <name> <regex-match> <replace-fmt>
7100 [ { if | unless } <condition> ]
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02007101
Tim Duesterhus2252beb2019-10-29 00:05:13 +01007102 This works like "http-request replace-header" except that it works on the
7103 server's response instead of the client's request.
William Lallemand86d0df02017-11-24 21:36:45 +01007104
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007105 Example:
7106 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
Willy Tarreau51d861a2015-05-22 17:30:48 +02007107
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007108 # applied to:
7109 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02007110
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007111 # outputs:
7112 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 +02007113
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007114 # assuming the backend IP is 192.168.1.20.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02007115
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007116http-response replace-value <name> <regex-match> <replace-fmt>
7117 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02007118
Tim Duesterhus6bd909b2020-01-17 15:53:18 +01007119 This works like "http-request replace-value" except that it works on the
Tim Duesterhus2252beb2019-10-29 00:05:13 +01007120 server's response instead of the client's request.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02007121
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007122 Example:
7123 http-response replace-value Cache-control ^public$ private
Christopher Faulet85d79c92016-11-09 16:54:56 +01007124
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007125 # applied to:
7126 Cache-Control: max-age=3600, public
Christopher Faulet85d79c92016-11-09 16:54:56 +01007127
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007128 # outputs:
7129 Cache-Control: max-age=3600, private
Christopher Faulet85d79c92016-11-09 16:54:56 +01007130
Christopher Faulet24231ab2020-01-24 17:44:23 +01007131http-response return [status <code>] [content-type <type>]
7132 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
7133 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
Christopher Faulet4a2c1422020-01-31 17:36:01 +01007134 [ hdr <name> <value> ]*
Christopher Faulet24231ab2020-01-24 17:44:23 +01007135 [ { if | unless } <condition> ]
7136
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05007137 This stops the evaluation of the rules and immediately returns a response. The
Christopher Faulet24231ab2020-01-24 17:44:23 +01007138 default status code used for the response is 200. It can be optionally
7139 specified as an arguments to "status". The response content-type may also be
Daniel Corbett67a82712020-07-06 23:01:19 -04007140 specified as an argument to "content-type". Finally the response itself may
Christopher Faulet24231ab2020-01-24 17:44:23 +01007141 be defined. If can be a full HTTP response specifying the errorfile to use,
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05007142 or the response payload specifying the file or the string to use. These rules
Christopher Faulet24231ab2020-01-24 17:44:23 +01007143 are followed to create the response :
7144
7145 * If neither the errorfile nor the payload to use is defined, a dummy
7146 response is returned. Only the "status" argument is considered. It can be
7147 any code in the range [200, 599]. The "content-type" argument, if any, is
7148 ignored.
7149
7150 * If "default-errorfiles" argument is set, the proxy's errorfiles are
7151 considered. If the "status" argument is defined, it must be one of the
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007152 status code handled by HAProxy (200, 400, 403, 404, 405, 408, 410, 413,
Christopher Faulete095f312020-12-07 11:22:24 +01007153 425, 429, 500, 501, 502, 503, and 504). The "content-type" argument, if
7154 any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01007155
7156 * If a specific errorfile is defined, with an "errorfile" argument, the
7157 corresponding file, containing a full HTTP response, is returned. Only the
7158 "status" argument is considered. It must be one of the status code handled
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007159 by HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 501,
Christopher Faulete095f312020-12-07 11:22:24 +01007160 502, 503, and 504). The "content-type" argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01007161
7162 * If an http-errors section is defined, with an "errorfiles" argument, the
7163 corresponding file in the specified http-errors section, containing a full
7164 HTTP response, is returned. Only the "status" argument is considered. It
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007165 must be one of the status code handled by HAProxy (200, 400, 403, 404, 405,
Christopher Faulete095f312020-12-07 11:22:24 +01007166 408, 410, 413, 425, 429, 500, 501, 502, 503, and 504). The "content-type"
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02007167 argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01007168
7169 * If a "file" or a "lf-file" argument is specified, the file's content is
7170 used as the response payload. If the file is not empty, its content-type
7171 must be set as argument to "content-type". Otherwise, any "content-type"
7172 argument is ignored. With a "lf-file" argument, the file's content is
7173 evaluated as a log-format string. With a "file" argument, it is considered
7174 as a raw content.
7175
7176 * If a "string" or "lf-string" argument is specified, the defined string is
7177 used as the response payload. The content-type must always be set as
7178 argument to "content-type". With a "lf-string" argument, the string is
7179 evaluated as a log-format string. With a "string" argument, it is
7180 considered as a raw string.
7181
Christopher Faulet4a2c1422020-01-31 17:36:01 +01007182 When the response is not based an errorfile, it is possible to appends HTTP
7183 header fields to the response using "hdr" arguments. Otherwise, all "hdr"
7184 arguments are ignored. For each one, the header name is specified in <name>
7185 and its value is defined by <fmt> which follows the log-format rules.
7186
Christopher Faulet24231ab2020-01-24 17:44:23 +01007187 Note that the generated response must be smaller than a buffer. And to avoid
7188 any warning, when an errorfile or a raw file is loaded, the buffer space
Ilya Shipitsin11057a32020-06-21 21:18:27 +05007189 reserved to the headers rewriting should also be free.
Christopher Faulet24231ab2020-01-24 17:44:23 +01007190
7191 No further "http-response" rules are evaluated.
7192
7193 Example:
Daniel Corbett67a82712020-07-06 23:01:19 -04007194 http-response return errorfile /etc/haproxy/errorfiles/200.http \
Christopher Faulet24231ab2020-01-24 17:44:23 +01007195 if { status eq 404 }
7196
7197 http-response return content-type text/plain \
7198 string "This is the end !" \
7199 if { status eq 500 }
7200
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007201http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
7202http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08007203
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007204 This action increments the GPC0 or GPC1 counter according with the sticky
7205 counter designated by <sc-id>. If an error occurs, this action silently fails
7206 and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02007207
Cédric Dufour0d7712d2019-11-06 18:38:53 +01007208http-response sc-set-gpt0(<sc-id>) { <int> | <expr> }
7209 [ { if | unless } <condition> ]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02007210
Cédric Dufour0d7712d2019-11-06 18:38:53 +01007211 This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
7212 designated by <sc-id> and the value of <int>/<expr>. The expected result is a
7213 boolean. If an error occurs, this action silently fails and the actions
7214 evaluation continues.
Frédéric Lécaille6778b272018-01-29 15:22:53 +01007215
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007216http-response send-spoe-group [ { if | unless } <condition> ]
Willy Tarreau2d392c22015-08-24 01:43:45 +02007217
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007218 This action is used to trigger sending of a group of SPOE messages. To do so,
7219 the SPOE engine used to send messages must be defined, as well as the SPOE
7220 group to send. Of course, the SPOE engine must refer to an existing SPOE
7221 filter. If not engine name is provided on the SPOE filter line, the SPOE
7222 agent name must be used.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02007223
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007224 Arguments:
7225 <engine-name> The SPOE engine name.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02007226
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007227 <group-name> The SPOE group name as specified in the engine
7228 configuration.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02007229
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007230http-response set-header <name> <fmt> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02007231
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007232 This does the same as "add-header" except that the header name is first
7233 removed if it existed. This is useful when passing security information to
7234 the server, where the header must not be manipulated by external users.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02007235
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007236http-response set-log-level <level> [ { if | unless } <condition> ]
7237
7238 This is used to change the log level of the current request when a certain
7239 condition is met. Valid levels are the 8 syslog levels (see the "log"
7240 keyword) plus the special level "silent" which disables logging for this
7241 request. This rule is not final so the last matching rule wins. This rule can
7242 be useful to disable health checks coming from another equipment.
7243
7244http-response set-map(<file-name>) <key fmt> <value fmt>
7245
7246 This is used to add a new entry into a MAP. The MAP must be loaded from a
7247 file (even a dummy empty file). The file name of the MAP to be updated is
7248 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
7249 log-format rules, used to collect MAP key, and <value fmt>, which follows
7250 log-format rules, used to collect content for the new entry. It performs a
7251 lookup in the MAP before insertion, to avoid duplicated (or more) values.
7252 This lookup is done by a linear search and can be expensive with large lists!
7253 It is the equivalent of the "set map" command from the stats socket, but can
7254 be triggered by an HTTP response.
7255
7256http-response set-mark <mark> [ { if | unless } <condition> ]
7257
7258 This is used to set the Netfilter MARK on all packets sent to the client to
7259 the value passed in <mark> on platforms which support it. This value is an
7260 unsigned 32 bit value which can be matched by netfilter and by the routing
7261 table. It can be expressed both in decimal or hexadecimal format (prefixed
7262 by "0x"). This can be useful to force certain packets to take a different
7263 route (for example a cheaper network path for bulk downloads). This works on
7264 Linux kernels 2.6.32 and above and requires admin privileges.
7265
7266http-response set-nice <nice> [ { if | unless } <condition> ]
7267
7268 This sets the "nice" factor of the current request being processed.
7269 It only has effect against the other requests being processed at the same
7270 time. The default value is 0, unless altered by the "nice" setting on the
7271 "bind" line. The accepted range is -1024..1024. The higher the value, the
7272 nicest the request will be. Lower values will make the request more important
7273 than other ones. This can be useful to improve the speed of some requests, or
7274 lower the priority of non-important requests. Using this setting without
7275 prior experimentation can cause some major slowdown.
7276
7277http-response set-status <status> [reason <str>]
7278 [ { if | unless } <condition> ]
7279
7280 This replaces the response status code with <status> which must be an integer
7281 between 100 and 999. Optionally, a custom reason text can be provided defined
7282 by <str>, or the default reason for the specified code will be used as a
7283 fallback.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007284
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007285 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007286 # return "431 Request Header Fields Too Large"
7287 http-response set-status 431
7288 # return "503 Slow Down", custom reason
7289 http-response set-status 503 reason "Slow Down".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007290
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007291http-response set-tos <tos> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007292
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007293 This is used to set the TOS or DSCP field value of packets sent to the client
7294 to the value passed in <tos> on platforms which support this.
7295 This value represents the whole 8 bits of the IP TOS field, and can be
7296 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note that
7297 only the 6 higher bits are used in DSCP or TOS, and the two lower bits are
7298 always 0. This can be used to adjust some routing behavior on border routers
7299 based on some information from the request.
7300
7301 See RFC 2474, 2597, 3260 and 4594 for more information.
7302
7303http-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
7304
7305 This is used to set the contents of a variable. The variable is declared
7306 inline.
7307
7308 Arguments:
7309 <var-name> The name of the variable starts with an indication about its
7310 scope. The scopes allowed are:
7311 "proc" : the variable is shared with the whole process
7312 "sess" : the variable is shared with the whole session
7313 "txn" : the variable is shared with the transaction
7314 (request and response)
7315 "req" : the variable is shared only during request
7316 processing
7317 "res" : the variable is shared only during response
7318 processing
7319 This prefix is followed by a name. The separator is a '.'.
7320 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
7321 and '_'.
7322
7323 <expr> Is a standard HAProxy expression formed by a sample-fetch
7324 followed by some converters.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007325
7326 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007327 http-response set-var(sess.last_redir) res.hdr(location)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007328
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007329http-response silent-drop [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007330
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007331 This stops the evaluation of the rules and makes the client-facing connection
7332 suddenly disappear using a system-dependent way that tries to prevent the
7333 client from being notified. The effect it then that the client still sees an
7334 established connection while there's none on HAProxy. The purpose is to
7335 achieve a comparable effect to "tarpit" except that it doesn't use any local
7336 resource at all on the machine running HAProxy. It can resist much higher
7337 loads than "tarpit", and slow down stronger attackers. It is important to
7338 understand the impact of using this mechanism. All stateful equipment placed
7339 between the client and HAProxy (firewalls, proxies, load balancers) will also
7340 keep the established connection for a long time and may suffer from this
7341 action.
7342 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
7343 option is used to block the emission of a TCP reset. On other systems, the
7344 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
7345 router, though it's still delivered to local networks. Do not use it unless
7346 you fully understand how it works.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02007347
Christopher Faulet46f95542019-12-20 10:07:22 +01007348http-response strict-mode { on | off }
7349
7350 This enables or disables the strict rewriting mode for following rules. It
7351 does not affect rules declared before it and it is only applicable on rules
7352 performing a rewrite on the responses. When the strict mode is enabled, any
7353 rewrite failure triggers an internal error. Otherwise, such errors are
7354 silently ignored. The purpose of the strict rewriting mode is to make some
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05007355 rewrites optional while others must be performed to continue the response
Christopher Faulet46f95542019-12-20 10:07:22 +01007356 processing.
7357
Christopher Faulet1aea50e2020-01-17 16:03:53 +01007358 By default, the strict rewriting mode is enabled. Its value is also reset
Christopher Faulet46f95542019-12-20 10:07:22 +01007359 when a ruleset evaluation ends. So, for instance, if you change the mode on
Daniel Corbett67a82712020-07-06 23:01:19 -04007360 the backend, the default mode is restored when HAProxy starts the frontend
Christopher Faulet46f95542019-12-20 10:07:22 +01007361 rules evaluation.
7362
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007363http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
7364http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
7365http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02007366
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007367 This enables tracking of sticky counters from current response. Please refer
7368 to "http-request track-sc" for a complete description. The only difference
7369 from "http-request track-sc" is the <key> sample expression can only make use
7370 of samples in response (e.g. res.*, status etc.) and samples below Layer 6
7371 (e.g. SSL-related samples, see section 7.3.4). If the sample is not
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007372 supported, HAProxy will fail and warn while parsing the config.
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02007373
7374http-response unset-var(<var-name>) [ { if | unless } <condition> ]
7375
7376 This is used to unset a variable. See "http-response set-var" for details
7377 about <var-name>.
7378
7379 Example:
7380 http-response unset-var(sess.last_redir)
7381
Christopher Faulet021a8e42021-03-29 10:46:38 +02007382http-response wait-for-body time <time> [ at-least <bytes> ]
7383 [ { if | unless } <condition> ]
7384
7385 This will delay the processing of the response waiting for the payload for at
7386 most <time> milliseconds. if "at-least" argument is specified, HAProxy stops
7387 to wait the payload when the first <bytes> bytes are received. 0 means no
7388 limit, it is the default value. Regardless the "at-least" argument value,
7389 HAProxy stops to wait if the whole payload is received or if the response
7390 buffer is full.
7391
7392 Arguments :
7393
7394 <time> is mandatory. It is the maximum time to wait for the body. It
7395 follows the HAProxy time format and is expressed in milliseconds.
7396
7397 <bytes> is optional. It is the minimum payload size to receive to stop to
Ilya Shipitsinb2be9a12021-04-24 13:25:42 +05007398 wait. It follows the HAProxy size format and is expressed in
Christopher Faulet021a8e42021-03-29 10:46:38 +02007399 bytes.
7400
7401 Example:
7402 http-response wait-for-body time 1s at-least 10k
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02007403
Willy Tarreau30631952015-08-06 15:05:24 +02007404http-reuse { never | safe | aggressive | always }
7405 Declare how idle HTTP connections may be shared between requests
7406
7407 May be used in sections: defaults | frontend | listen | backend
7408 yes | no | yes | yes
7409
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007410 By default, a connection established between HAProxy and the backend server
Olivier Houchard86006a52018-12-14 19:37:49 +01007411 which is considered safe for reuse is moved back to the server's idle
7412 connections pool so that any other request can make use of it. This is the
7413 "safe" strategy below.
Willy Tarreau30631952015-08-06 15:05:24 +02007414
7415 The argument indicates the desired connection reuse strategy :
7416
Olivier Houchard86006a52018-12-14 19:37:49 +01007417 - "never" : idle connections are never shared between sessions. This mode
7418 may be enforced to cancel a different strategy inherited from
7419 a defaults section or for troubleshooting. For example, if an
7420 old bogus application considers that multiple requests over
7421 the same connection come from the same client and it is not
7422 possible to fix the application, it may be desirable to
7423 disable connection sharing in a single backend. An example of
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007424 such an application could be an old HAProxy using cookie
Olivier Houchard86006a52018-12-14 19:37:49 +01007425 insertion in tunnel mode and not checking any request past the
7426 first one.
Willy Tarreau30631952015-08-06 15:05:24 +02007427
Olivier Houchard86006a52018-12-14 19:37:49 +01007428 - "safe" : this is the default and the recommended strategy. The first
7429 request of a session is always sent over its own connection,
7430 and only subsequent requests may be dispatched over other
7431 existing connections. This ensures that in case the server
7432 closes the connection when the request is being sent, the
7433 browser can decide to silently retry it. Since it is exactly
7434 equivalent to regular keep-alive, there should be no side
Amaury Denoyelle27179652020-10-14 18:17:12 +02007435 effects. There is also a special handling for the connections
7436 using protocols subject to Head-of-line blocking (backend with
7437 h2 or fcgi). In this case, when at least one stream is
7438 processed, the used connection is reserved to handle streams
7439 of the same session. When no more streams are processed, the
7440 connection is released and can be reused.
Willy Tarreau30631952015-08-06 15:05:24 +02007441
7442 - "aggressive" : this mode may be useful in webservices environments where
7443 all servers are not necessarily known and where it would be
7444 appreciable to deliver most first requests over existing
7445 connections. In this case, first requests are only delivered
7446 over existing connections that have been reused at least once,
7447 proving that the server correctly supports connection reuse.
7448 It should only be used when it's sure that the client can
7449 retry a failed request once in a while and where the benefit
Michael Prokop4438c602019-05-24 10:25:45 +02007450 of aggressive connection reuse significantly outweighs the
Willy Tarreau30631952015-08-06 15:05:24 +02007451 downsides of rare connection failures.
7452
7453 - "always" : this mode is only recommended when the path to the server is
7454 known for never breaking existing connections quickly after
7455 releasing them. It allows the first request of a session to be
7456 sent to an existing connection. This can provide a significant
7457 performance increase over the "safe" strategy when the backend
7458 is a cache farm, since such components tend to show a
Davor Ocelice9ed2812017-12-25 17:49:28 +01007459 consistent behavior and will benefit from the connection
Willy Tarreau30631952015-08-06 15:05:24 +02007460 sharing. It is recommended that the "http-keep-alive" timeout
7461 remains low in this mode so that no dead connections remain
7462 usable. In most cases, this will lead to the same performance
7463 gains as "aggressive" but with more risks. It should only be
7464 used when it improves the situation over "aggressive".
7465
7466 When http connection sharing is enabled, a great care is taken to respect the
Amaury Denoyelled773a4e2021-01-29 15:18:49 +01007467 connection properties and compatibility. Indeed, some properties are specific
7468 and it is not possibly to reuse it blindly. Those are the SSL SNI, source
7469 and destination address and proxy protocol block. A connection is reused only
7470 if it shares the same set of properties with the request.
Willy Tarreau30631952015-08-06 15:05:24 +02007471
Amaury Denoyelled773a4e2021-01-29 15:18:49 +01007472 Also note that connections with certain bogus authentication schemes (relying
7473 on the connection) like NTLM are marked private and never shared.
Willy Tarreau30631952015-08-06 15:05:24 +02007474
Lukas Tribuse8adfeb2019-11-06 11:50:25 +01007475 A connection pool is involved and configurable with "pool-max-conn".
Willy Tarreau30631952015-08-06 15:05:24 +02007476
7477 Note: connection reuse improves the accuracy of the "server maxconn" setting,
7478 because almost no new connection will be established while idle connections
7479 remain available. This is particularly true with the "always" strategy.
7480
7481 See also : "option http-keep-alive", "server maxconn"
7482
7483
Mark Lamourinec2247f02012-01-04 13:02:01 -05007484http-send-name-header [<header>]
7485 Add the server name to a request. Use the header string given by <header>
Mark Lamourinec2247f02012-01-04 13:02:01 -05007486 May be used in sections: defaults | frontend | listen | backend
7487 yes | no | yes | yes
Mark Lamourinec2247f02012-01-04 13:02:01 -05007488 Arguments :
Mark Lamourinec2247f02012-01-04 13:02:01 -05007489 <header> The header string to use to send the server name
7490
Willy Tarreau81bef7e2019-10-07 14:58:02 +02007491 The "http-send-name-header" statement causes the header field named <header>
7492 to be set to the name of the target server at the moment the request is about
7493 to be sent on the wire. Any existing occurrences of this header are removed.
7494 Upon retries and redispatches, the header field is updated to always reflect
7495 the server being attempted to connect to. Given that this header is modified
7496 very late in the connection setup, it may have unexpected effects on already
7497 modified headers. For example using it with transport-level header such as
7498 connection, content-length, transfer-encoding and so on will likely result in
7499 invalid requests being sent to the server. Additionally it has been reported
7500 that this directive is currently being used as a way to overwrite the Host
7501 header field in outgoing requests; while this trick has been known to work
7502 as a side effect of the feature for some time, it is not officially supported
7503 and might possibly not work anymore in a future version depending on the
7504 technical difficulties this feature induces. A long-term solution instead
7505 consists in fixing the application which required this trick so that it binds
7506 to the correct host name.
Mark Lamourinec2247f02012-01-04 13:02:01 -05007507
7508 See also : "server"
7509
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01007510id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02007511 Set a persistent ID to a proxy.
7512 May be used in sections : defaults | frontend | listen | backend
7513 no | yes | yes | yes
7514 Arguments : none
7515
7516 Set a persistent ID for the proxy. This ID must be unique and positive.
7517 An unused ID will automatically be assigned if unset. The first assigned
7518 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01007519
7520
Cyril Bonté0d4bf012010-04-25 23:21:46 +02007521ignore-persist { if | unless } <condition>
7522 Declare a condition to ignore persistence
7523 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01007524 no | no | yes | yes
Cyril Bonté0d4bf012010-04-25 23:21:46 +02007525
7526 By default, when cookie persistence is enabled, every requests containing
7527 the cookie are unconditionally persistent (assuming the target server is up
7528 and running).
7529
7530 The "ignore-persist" statement allows one to declare various ACL-based
7531 conditions which, when met, will cause a request to ignore persistence.
7532 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007533 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02007534 persistence for a specific User-Agent (for example, some web crawler bots).
7535
Cyril Bonté0d4bf012010-04-25 23:21:46 +02007536 The persistence is ignored when an "if" condition is met, or unless an
7537 "unless" condition is met.
7538
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03007539 Example:
7540 acl url_static path_beg /static /images /img /css
7541 acl url_static path_end .gif .png .jpg .css .js
7542 ignore-persist if url_static
7543
Cyril Bonté0d4bf012010-04-25 23:21:46 +02007544 See also : "force-persist", "cookie", and section 7 about ACL usage.
7545
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007546load-server-state-from-file { global | local | none }
7547 Allow seamless reload of HAProxy
7548 May be used in sections: defaults | frontend | listen | backend
7549 yes | no | yes | yes
7550
7551 This directive points HAProxy to a file where server state from previous
7552 running process has been saved. That way, when starting up, before handling
7553 traffic, the new process can apply old states to servers exactly has if no
Davor Ocelice9ed2812017-12-25 17:49:28 +01007554 reload occurred. The purpose of the "load-server-state-from-file" directive is
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007555 to tell HAProxy which file to use. For now, only 2 arguments to either prevent
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007556 loading state or load states from a file containing all backends and servers.
7557 The state file can be generated by running the command "show servers state"
7558 over the stats socket and redirect output.
7559
Davor Ocelice9ed2812017-12-25 17:49:28 +01007560 The format of the file is versioned and is very specific. To understand it,
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007561 please read the documentation of the "show servers state" command (chapter
Willy Tarreau1af20c72017-06-23 16:01:14 +02007562 9.3 of Management Guide).
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007563
7564 Arguments:
7565 global load the content of the file pointed by the global directive
7566 named "server-state-file".
7567
7568 local load the content of the file pointed by the directive
7569 "server-state-file-name" if set. If not set, then the backend
7570 name is used as a file name.
7571
7572 none don't load any stat for this backend
7573
7574 Notes:
Willy Tarreaue5a60682016-11-09 14:54:53 +01007575 - server's IP address is preserved across reloads by default, but the
7576 order can be changed thanks to the server's "init-addr" setting. This
7577 means that an IP address change performed on the CLI at run time will
Davor Ocelice9ed2812017-12-25 17:49:28 +01007578 be preserved, and that any change to the local resolver (e.g. /etc/hosts)
Willy Tarreaue5a60682016-11-09 14:54:53 +01007579 will possibly not have any effect if the state file is in use.
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007580
7581 - server's weight is applied from previous running process unless it has
7582 has changed between previous and new configuration files.
7583
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007584 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007585
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007586 global
7587 stats socket /tmp/socket
7588 server-state-file /tmp/server_state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007589
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007590 defaults
7591 load-server-state-from-file global
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007592
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007593 backend bk
7594 server s1 127.0.0.1:22 check weight 11
7595 server s2 127.0.0.1:22 check weight 12
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007596
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007597
7598 Then one can run :
7599
7600 socat /tmp/socket - <<< "show servers state" > /tmp/server_state
7601
7602 Content of the file /tmp/server_state would be like this:
7603
7604 1
7605 # <field names skipped for the doc example>
7606 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
7607 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
7608
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007609 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007610
7611 global
7612 stats socket /tmp/socket
7613 server-state-base /etc/haproxy/states
7614
7615 defaults
7616 load-server-state-from-file local
7617
7618 backend bk
7619 server s1 127.0.0.1:22 check weight 11
7620 server s2 127.0.0.1:22 check weight 12
7621
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007622
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007623 Then one can run :
7624
7625 socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
7626
7627 Content of the file /etc/haproxy/states/bk would be like this:
7628
7629 1
7630 # <field names skipped for the doc example>
7631 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
7632 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
7633
7634 See also: "server-state-file", "server-state-file-name", and
7635 "show servers state"
7636
Cyril Bonté0d4bf012010-04-25 23:21:46 +02007637
Willy Tarreau2769aa02007-12-27 18:26:09 +01007638log global
Jan Wagner3e678602020-12-17 22:22:32 +01007639log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02007640 <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02007641no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01007642 Enable per-instance logging of events and traffic.
7643 May be used in sections : defaults | frontend | listen | backend
7644 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02007645
7646 Prefix :
7647 no should be used when the logger list must be flushed. For example,
7648 if you don't want to inherit from the default logger list. This
7649 prefix does not allow arguments.
7650
Willy Tarreau2769aa02007-12-27 18:26:09 +01007651 Arguments :
7652 global should be used when the instance's logging parameters are the
7653 same as the global ones. This is the most common usage. "global"
7654 replaces <address>, <facility> and <level> with those of the log
7655 entries found in the "global" section. Only one "log global"
7656 statement may be used per instance, and this form takes no other
7657 parameter.
7658
7659 <address> indicates where to send the logs. It takes the same format as
7660 for the "global" section's logs, and can be one of :
7661
7662 - An IPv4 address optionally followed by a colon (':') and a UDP
7663 port. If no port is specified, 514 is used by default (the
7664 standard syslog port).
7665
David du Colombier24bb5f52011-03-17 10:40:23 +01007666 - An IPv6 address followed by a colon (':') and optionally a UDP
7667 port. If no port is specified, 514 is used by default (the
7668 standard syslog port).
7669
Willy Tarreau2769aa02007-12-27 18:26:09 +01007670 - A filesystem path to a UNIX domain socket, keeping in mind
7671 considerations for chroot (be sure the path is accessible
7672 inside the chroot) and uid/gid (be sure the path is
Davor Ocelice9ed2812017-12-25 17:49:28 +01007673 appropriately writable).
Willy Tarreau2769aa02007-12-27 18:26:09 +01007674
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01007675 - A file descriptor number in the form "fd@<number>", which may
7676 point to a pipe, terminal, or socket. In this case unbuffered
7677 logs are used and one writev() call per log is performed. This
7678 is a bit expensive but acceptable for most workloads. Messages
7679 sent this way will not be truncated but may be dropped, in
7680 which case the DroppedLogs counter will be incremented. The
7681 writev() call is atomic even on pipes for messages up to
7682 PIPE_BUF size, which POSIX recommends to be at least 512 and
7683 which is 4096 bytes on most modern operating systems. Any
7684 larger message may be interleaved with messages from other
7685 processes. Exceptionally for debugging purposes the file
7686 descriptor may also be directed to a file, but doing so will
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007687 significantly slow HAProxy down as non-blocking calls will be
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01007688 ignored. Also there will be no way to purge nor rotate this
7689 file without restarting the process. Note that the configured
7690 syslog format is preserved, so the output is suitable for use
Willy Tarreauc1b06452018-11-12 11:57:56 +01007691 with a TCP syslog server. See also the "short" and "raw"
7692 formats below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01007693
7694 - "stdout" / "stderr", which are respectively aliases for "fd@1"
7695 and "fd@2", see above.
7696
Willy Tarreauc046d162019-08-30 15:24:59 +02007697 - A ring buffer in the form "ring@<name>", which will correspond
7698 to an in-memory ring buffer accessible over the CLI using the
7699 "show events" command, which will also list existing rings and
7700 their sizes. Such buffers are lost on reload or restart but
7701 when used as a complement this can help troubleshooting by
7702 having the logs instantly available.
7703
Emeric Brun94aab062021-04-02 10:41:36 +02007704 - An explicit stream address prefix such as "tcp@","tcp6@",
7705 "tcp4@" or "uxst@" will allocate an implicit ring buffer with
7706 a stream forward server targeting the given address.
7707
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01007708 You may want to reference some environment variables in the
7709 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01007710
Willy Tarreau18324f52014-06-27 18:10:07 +02007711 <length> is an optional maximum line length. Log lines larger than this
7712 value will be truncated before being sent. The reason is that
7713 syslog servers act differently on log line length. All servers
7714 support the default value of 1024, but some servers simply drop
7715 larger lines while others do log them. If a server supports long
7716 lines, it may make sense to set this value here in order to avoid
7717 truncating long lines. Similarly, if a server drops long lines,
7718 it is preferable to truncate them before sending them. Accepted
7719 values are 80 to 65535 inclusive. The default value of 1024 is
7720 generally fine for all standard usages. Some specific cases of
Davor Ocelice9ed2812017-12-25 17:49:28 +01007721 long captures or JSON-formatted logs may require larger values.
Willy Tarreau18324f52014-06-27 18:10:07 +02007722
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02007723 <ranges> A list of comma-separated ranges to identify the logs to sample.
7724 This is used to balance the load of the logs to send to the log
7725 server. The limits of the ranges cannot be null. They are numbered
7726 from 1. The size or period (in number of logs) of the sample must
7727 be set with <sample_size> parameter.
7728
7729 <sample_size>
7730 The size of the sample in number of logs to consider when balancing
7731 their logging loads. It is used to balance the load of the logs to
7732 send to the syslog server. This size must be greater or equal to the
7733 maximum of the high limits of the ranges.
7734 (see also <ranges> parameter).
7735
Willy Tarreauadb345d2018-11-12 07:56:13 +01007736 <format> is the log format used when generating syslog messages. It may be
7737 one of the following :
7738
Emeric Brun0237c4e2020-11-27 16:24:34 +01007739 local Analog to rfc3164 syslog message format except that hostname
7740 field is stripped. This is the default.
7741 Note: option "log-send-hostname" switches the default to
7742 rfc3164.
7743
7744 rfc3164 The RFC3164 syslog message format.
Willy Tarreauadb345d2018-11-12 07:56:13 +01007745 (https://tools.ietf.org/html/rfc3164)
7746
7747 rfc5424 The RFC5424 syslog message format.
7748 (https://tools.ietf.org/html/rfc5424)
7749
Emeric Brun54648852020-07-06 15:54:06 +02007750 priority A message containing only a level plus syslog facility between
7751 angle brackets such as '<63>', followed by the text. The PID,
7752 date, time, process name and system name are omitted. This is
7753 designed to be used with a local log server.
7754
Willy Tarreaue8746a02018-11-12 08:45:00 +01007755 short A message containing only a level between angle brackets such as
7756 '<3>', followed by the text. The PID, date, time, process name
7757 and system name are omitted. This is designed to be used with a
7758 local log server. This format is compatible with what the
7759 systemd logger consumes.
7760
Emeric Brun54648852020-07-06 15:54:06 +02007761 timed A message containing only a level between angle brackets such as
7762 '<3>', followed by ISO date and by the text. The PID, process
7763 name and system name are omitted. This is designed to be
7764 used with a local log server.
7765
7766 iso A message containing only the ISO date, followed by the text.
7767 The PID, process name and system name are omitted. This is
7768 designed to be used with a local log server.
7769
Willy Tarreauc1b06452018-11-12 11:57:56 +01007770 raw A message containing only the text. The level, PID, date, time,
7771 process name and system name are omitted. This is designed to
7772 be used in containers or during development, where the severity
7773 only depends on the file descriptor used (stdout/stderr).
7774
Willy Tarreau2769aa02007-12-27 18:26:09 +01007775 <facility> must be one of the 24 standard syslog facilities :
7776
Willy Tarreaue8746a02018-11-12 08:45:00 +01007777 kern user mail daemon auth syslog lpr news
7778 uucp cron auth2 ftp ntp audit alert cron2
7779 local0 local1 local2 local3 local4 local5 local6 local7
7780
Willy Tarreauc1b06452018-11-12 11:57:56 +01007781 Note that the facility is ignored for the "short" and "raw"
7782 formats, but still required as a positional field. It is
7783 recommended to use "daemon" in this case to make it clear that
7784 it's only supposed to be used locally.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007785
7786 <level> is optional and can be specified to filter outgoing messages. By
7787 default, all messages are sent. If a level is specified, only
7788 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02007789 will be sent. An optional minimum level can be specified. If it
7790 is set, logs emitted with a more severe level than this one will
7791 be capped to this level. This is used to avoid sending "emerg"
7792 messages on all terminals on some default syslog configurations.
7793 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01007794
7795 emerg alert crit err warning notice info debug
7796
William Lallemand0f99e342011-10-12 17:50:54 +02007797 It is important to keep in mind that it is the frontend which decides what to
7798 log from a connection, and that in case of content switching, the log entries
7799 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007800
7801 However, backend log declaration define how and where servers status changes
7802 will be logged. Level "notice" will be used to indicate a server going up,
7803 "warning" will be used for termination signals and definitive service
7804 termination, and "alert" will be used for when a server goes down.
7805
7806 Note : According to RFC3164, messages are truncated to 1024 bytes before
7807 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007808
7809 Example :
7810 log global
Willy Tarreauc1b06452018-11-12 11:57:56 +01007811 log stdout format short daemon # send log to systemd
7812 log stdout format raw daemon # send everything to stdout
7813 log stderr format raw daemon notice # send important events to stderr
Willy Tarreauf7edefa2009-05-10 17:20:05 +02007814 log 127.0.0.1:514 local0 notice # only send important events
Emeric Brun94aab062021-04-02 10:41:36 +02007815 log tcp@127.0.0.1:514 local0 notice notice # same but limit output
7816 # level and send in tcp
William Lallemandb2f07452015-05-12 14:27:13 +02007817 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01007818
Willy Tarreau2769aa02007-12-27 18:26:09 +01007819
William Lallemand48940402012-01-30 16:47:22 +01007820log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01007821 Specifies the log format string to use for traffic logs
7822 May be used in sections: defaults | frontend | listen | backend
7823 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01007824
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01007825 This directive specifies the log format string that will be used for all logs
7826 resulting from traffic passing through the frontend using this line. If the
7827 directive is used in a defaults section, all subsequent frontends will use
7828 the same log format. Please see section 8.2.4 which covers the log format
7829 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01007830
Guillaume de Lafond29f45602017-03-31 19:52:15 +02007831 "log-format" directive overrides previous "option tcplog", "log-format" and
7832 "option httplog" directives.
7833
Dragan Dosen7ad31542015-09-28 17:16:47 +02007834log-format-sd <string>
7835 Specifies the RFC5424 structured-data log format string
7836 May be used in sections: defaults | frontend | listen | backend
7837 yes | yes | yes | no
7838
7839 This directive specifies the RFC5424 structured-data log format string that
7840 will be used for all logs resulting from traffic passing through the frontend
7841 using this line. If the directive is used in a defaults section, all
7842 subsequent frontends will use the same log format. Please see section 8.2.4
7843 which covers the log format string in depth.
7844
7845 See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
7846 about the RFC5424 structured-data part.
7847
7848 Note : This log format string will be used only for loggers that have set
7849 log format to "rfc5424".
7850
7851 Example :
7852 log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
7853
7854
Willy Tarreau094af4e2015-01-07 15:03:42 +01007855log-tag <string>
7856 Specifies the log tag to use for all outgoing logs
7857 May be used in sections: defaults | frontend | listen | backend
7858 yes | yes | yes | yes
7859
7860 Sets the tag field in the syslog header to this string. It defaults to the
7861 log-tag set in the global section, otherwise the program name as launched
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007862 from the command line, which usually is "HAProxy". Sometimes it can be useful
Willy Tarreau094af4e2015-01-07 15:03:42 +01007863 to differentiate between multiple processes running on the same host, or to
7864 differentiate customer instances running in the same process. In the backend,
7865 logs about servers up/down will use this tag. As a hint, it can be convenient
7866 to set a log-tag related to a hosted customer in a defaults section then put
7867 all the frontends and backends for that customer, then start another customer
7868 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007869
Willy Tarreauc35362a2014-04-25 13:58:37 +02007870max-keep-alive-queue <value>
7871 Set the maximum server queue size for maintaining keep-alive connections
7872 May be used in sections: defaults | frontend | listen | backend
7873 yes | no | yes | yes
7874
7875 HTTP keep-alive tries to reuse the same server connection whenever possible,
7876 but sometimes it can be counter-productive, for example if a server has a lot
7877 of connections while other ones are idle. This is especially true for static
7878 servers.
7879
7880 The purpose of this setting is to set a threshold on the number of queued
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007881 connections at which HAProxy stops trying to reuse the same server and prefers
Willy Tarreauc35362a2014-04-25 13:58:37 +02007882 to find another one. The default value, -1, means there is no limit. A value
7883 of zero means that keep-alive requests will never be queued. For very close
7884 servers which can be reached with a low latency and which are not sensible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01007885 breaking keep-alive, a low value is recommended (e.g. local static server can
Willy Tarreauc35362a2014-04-25 13:58:37 +02007886 use a value of 10 or less). For remote servers suffering from a high latency,
7887 higher values might be needed to cover for the latency and/or the cost of
7888 picking a different server.
7889
7890 Note that this has no impact on responses which are maintained to the same
7891 server consecutively to a 401 response. They will still go to the same server
7892 even if they have to be queued.
7893
7894 See also : "option http-server-close", "option prefer-last-server", server
7895 "maxconn" and cookie persistence.
7896
Olivier Houcharda4d4fdf2018-12-14 19:27:06 +01007897max-session-srv-conns <nb>
7898 Set the maximum number of outgoing connections we can keep idling for a given
7899 client session. The default is 5 (it precisely equals MAX_SRV_LIST which is
7900 defined at build time).
Willy Tarreauc35362a2014-04-25 13:58:37 +02007901
Willy Tarreau2769aa02007-12-27 18:26:09 +01007902maxconn <conns>
7903 Fix the maximum number of concurrent connections on a frontend
7904 May be used in sections : defaults | frontend | listen | backend
7905 yes | yes | yes | no
7906 Arguments :
7907 <conns> is the maximum number of concurrent connections the frontend will
7908 accept to serve. Excess connections will be queued by the system
7909 in the socket's listen queue and will be served once a connection
7910 closes.
7911
7912 If the system supports it, it can be useful on big sites to raise this limit
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007913 very high so that HAProxy manages connection queues, instead of leaving the
Willy Tarreau2769aa02007-12-27 18:26:09 +01007914 clients with unanswered connection attempts. This value should not exceed the
7915 global maxconn. Also, keep in mind that a connection contains two buffers
Baptiste Assmann79fb45d2016-03-06 23:34:31 +01007916 of tune.bufsize (16kB by default) each, as well as some other data resulting
7917 in about 33 kB of RAM being consumed per established connection. That means
7918 that a medium system equipped with 1GB of RAM can withstand around
7919 20000-25000 concurrent connections if properly tuned.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007920
7921 Also, when <conns> is set to large values, it is possible that the servers
7922 are not sized to accept such loads, and for this reason it is generally wise
7923 to assign them some reasonable connection limits.
7924
Willy Tarreauc8d5b952019-02-27 17:25:52 +01007925 When this value is set to zero, which is the default, the global "maxconn"
7926 value is used.
Vincent Bernat6341be52012-06-27 17:18:30 +02007927
Willy Tarreau2769aa02007-12-27 18:26:09 +01007928 See also : "server", global section's "maxconn", "fullconn"
7929
7930
Willy Tarreau77e0dae2020-10-14 15:44:27 +02007931mode { tcp|http }
Willy Tarreau2769aa02007-12-27 18:26:09 +01007932 Set the running mode or protocol of the instance
7933 May be used in sections : defaults | frontend | listen | backend
7934 yes | yes | yes | yes
7935 Arguments :
7936 tcp The instance will work in pure TCP mode. A full-duplex connection
7937 will be established between clients and servers, and no layer 7
7938 examination will be performed. This is the default mode. It
7939 should be used for SSL, SSH, SMTP, ...
7940
7941 http The instance will work in HTTP mode. The client request will be
7942 analyzed in depth before connecting to any server. Any request
7943 which is not RFC-compliant will be rejected. Layer 7 filtering,
7944 processing and switching will be possible. This is the mode which
7945 brings HAProxy most of its value.
7946
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007947 When doing content switching, it is mandatory that the frontend and the
7948 backend are in the same mode (generally HTTP), otherwise the configuration
7949 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007950
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007951 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01007952 defaults http_instances
7953 mode http
7954
Willy Tarreau0ba27502007-12-24 16:55:16 +01007955
Cyril Bontéf0c60612010-02-06 14:44:47 +01007956monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01007957 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007958 May be used in sections : defaults | frontend | listen | backend
7959 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01007960 Arguments :
7961 if <cond> the monitor request will fail if the condition is satisfied,
7962 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007963 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01007964 are met, for instance a low number of servers both in a
7965 backend and its backup.
7966
7967 unless <cond> the monitor request will succeed only if the condition is
7968 satisfied, and will fail otherwise. Such a condition may be
7969 based on a test on the presence of a minimum number of active
7970 servers in a list of backends.
7971
7972 This statement adds a condition which can force the response to a monitor
7973 request to report a failure. By default, when an external component queries
7974 the URI dedicated to monitoring, a 200 response is returned. When one of the
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007975 conditions above is met, HAProxy will return 503 instead of 200. This is
Willy Tarreau0ba27502007-12-24 16:55:16 +01007976 very useful to report a site failure to an external component which may base
7977 routing advertisements between multiple sites on the availability reported by
Daniel Corbett9f0843f2021-05-08 10:50:37 -04007978 HAProxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02007979 criterion. Note that "monitor fail" only works in HTTP mode. Both status
7980 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007981
7982 Example:
7983 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01007984 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01007985 acl site_dead nbsrv(dynamic) lt 2
7986 acl site_dead nbsrv(static) lt 2
7987 monitor-uri /site_alive
7988 monitor fail if site_dead
7989
Willy Tarreau9e9919d2020-10-14 15:55:23 +02007990 See also : "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01007991
7992
Willy Tarreau2769aa02007-12-27 18:26:09 +01007993monitor-uri <uri>
7994 Intercept a URI used by external components' monitor requests
7995 May be used in sections : defaults | frontend | listen | backend
7996 yes | yes | yes | no
7997 Arguments :
7998 <uri> is the exact URI which we want to intercept to return HAProxy's
7999 health status instead of forwarding the request.
8000
8001 When an HTTP request referencing <uri> will be received on a frontend,
8002 HAProxy will not forward it nor log it, but instead will return either
8003 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
8004 conditions defined with "monitor fail". This is normally enough for any
8005 front-end HTTP probe to detect that the service is UP and running without
8006 forwarding the request to a backend server. Note that the HTTP method, the
8007 version and all headers are ignored, but the request must at least be valid
8008 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
8009
Willy Tarreau721d8e02017-12-01 18:25:08 +01008010 Monitor requests are processed very early, just after the request is parsed
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02008011 and even before any "http-request". The only rulesets applied before are the
8012 tcp-request ones. They cannot be logged either, and it is the intended
8013 purpose. They are only used to report HAProxy's health to an upper component,
8014 nothing more. However, it is possible to add any number of conditions using
8015 "monitor fail" and ACLs so that the result can be adjusted to whatever check
8016 can be imagined (most often the number of available servers in a backend).
Willy Tarreau2769aa02007-12-27 18:26:09 +01008017
Christopher Faulet6072beb2020-02-18 15:34:58 +01008018 Note: if <uri> starts by a slash ('/'), the matching is performed against the
8019 request's path instead of the request's uri. It is a workaround to let
8020 the HTTP/2 requests match the monitor-uri. Indeed, in HTTP/2, clients
8021 are encouraged to send absolute URIs only.
8022
Willy Tarreau2769aa02007-12-27 18:26:09 +01008023 Example :
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008024 # Use /haproxy_test to report HAProxy's status
Willy Tarreau2769aa02007-12-27 18:26:09 +01008025 frontend www
8026 mode http
8027 monitor-uri /haproxy_test
8028
Willy Tarreau9e9919d2020-10-14 15:55:23 +02008029 See also : "monitor fail"
Willy Tarreau2769aa02007-12-27 18:26:09 +01008030
Willy Tarreau0ba27502007-12-24 16:55:16 +01008031
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008032option abortonclose
8033no option abortonclose
8034 Enable or disable early dropping of aborted requests pending in queues.
8035 May be used in sections : defaults | frontend | listen | backend
8036 yes | no | yes | yes
8037 Arguments : none
8038
8039 In presence of very high loads, the servers will take some time to respond.
8040 The per-instance connection queue will inflate, and the response time will
8041 increase respective to the size of the queue times the average per-session
8042 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01008043 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008044 the queue, and slowing down other users, and the servers as well, because the
8045 request will eventually be served, then aborted at the first error
8046 encountered while delivering the response.
8047
8048 As there is no way to distinguish between a full STOP and a simple output
8049 close on the client side, HTTP agents should be conservative and consider
8050 that the client might only have closed its output channel while waiting for
8051 the response. However, this introduces risks of congestion when lots of users
8052 do the same, and is completely useless nowadays because probably no client at
8053 all will close the session while waiting for the response. Some HTTP agents
Davor Ocelice9ed2812017-12-25 17:49:28 +01008054 support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008055 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01008056 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008057 of being the single component to break rare but valid traffic is extremely
8058 low, which adds to the temptation to be able to abort a session early while
8059 still not served and not pollute the servers.
8060
Davor Ocelice9ed2812017-12-25 17:49:28 +01008061 In HAProxy, the user can choose the desired behavior using the option
8062 "abortonclose". By default (without the option) the behavior is HTTP
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008063 compliant and aborted requests will be served. But when the option is
8064 specified, a session with an incoming channel closed will be aborted while
8065 it is still possible, either pending in the queue for a connection slot, or
8066 during the connection establishment if the server has not yet acknowledged
8067 the connection request. This considerably reduces the queue size and the load
8068 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01008069 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008070
8071 If this option has been enabled in a "defaults" section, it can be disabled
8072 in a specific instance by prepending the "no" keyword before it.
8073
8074 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
8075
8076
Willy Tarreau4076a152009-04-02 15:18:36 +02008077option accept-invalid-http-request
8078no option accept-invalid-http-request
8079 Enable or disable relaxing of HTTP request parsing
8080 May be used in sections : defaults | frontend | listen | backend
8081 yes | yes | yes | no
8082 Arguments : none
8083
Willy Tarreau91852eb2015-05-01 13:26:00 +02008084 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02008085 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01008086 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02008087 forbidden characters are essentially used to build attacks exploiting server
8088 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
8089 server will emit invalid header names for whatever reason (configuration,
8090 implementation) and the issue will not be immediately fixed. In such a case,
8091 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01008092 even if that does not make sense, by specifying this option. Similarly, the
8093 list of characters allowed to appear in a URI is well defined by RFC3986, and
8094 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
8095 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
Davor Ocelice9ed2812017-12-25 17:49:28 +01008096 not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02008097 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02008098 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
8099 to pass through (no version specified) and multiple digits for both the major
8100 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02008101
8102 This option should never be enabled by default as it hides application bugs
8103 and open security breaches. It should only be deployed after a problem has
8104 been confirmed.
8105
8106 When this option is enabled, erroneous header names will still be accepted in
8107 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01008108 analysis using the "show errors" request on the UNIX stats socket. Similarly,
8109 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02008110 also helps confirming that the issue has been solved.
8111
8112 If this option has been enabled in a "defaults" section, it can be disabled
8113 in a specific instance by prepending the "no" keyword before it.
8114
8115 See also : "option accept-invalid-http-response" and "show errors" on the
8116 stats socket.
8117
8118
8119option accept-invalid-http-response
8120no option accept-invalid-http-response
8121 Enable or disable relaxing of HTTP response parsing
8122 May be used in sections : defaults | frontend | listen | backend
8123 yes | no | yes | yes
8124 Arguments : none
8125
Willy Tarreau91852eb2015-05-01 13:26:00 +02008126 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02008127 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01008128 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02008129 forbidden characters are essentially used to build attacks exploiting server
8130 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
8131 server will emit invalid header names for whatever reason (configuration,
8132 implementation) and the issue will not be immediately fixed. In such a case,
8133 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02008134 even if that does not make sense, by specifying this option. This option also
8135 relaxes the test on the HTTP version format, it allows multiple digits for
8136 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02008137
8138 This option should never be enabled by default as it hides application bugs
8139 and open security breaches. It should only be deployed after a problem has
8140 been confirmed.
8141
8142 When this option is enabled, erroneous header names will still be accepted in
8143 responses, but the complete response will be captured in order to permit
8144 later analysis using the "show errors" request on the UNIX stats socket.
8145 Doing this also helps confirming that the issue has been solved.
8146
8147 If this option has been enabled in a "defaults" section, it can be disabled
8148 in a specific instance by prepending the "no" keyword before it.
8149
8150 See also : "option accept-invalid-http-request" and "show errors" on the
8151 stats socket.
8152
8153
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008154option allbackups
8155no option allbackups
8156 Use either all backup servers at a time or only the first one
8157 May be used in sections : defaults | frontend | listen | backend
8158 yes | no | yes | yes
8159 Arguments : none
8160
8161 By default, the first operational backup server gets all traffic when normal
8162 servers are all down. Sometimes, it may be preferred to use multiple backups
8163 at once, because one will not be enough. When "option allbackups" is enabled,
8164 the load balancing will be performed among all backup servers when all normal
8165 ones are unavailable. The same load balancing algorithm will be used and the
8166 servers' weights will be respected. Thus, there will not be any priority
8167 order between the backup servers anymore.
8168
8169 This option is mostly used with static server farms dedicated to return a
8170 "sorry" page when an application is completely offline.
8171
8172 If this option has been enabled in a "defaults" section, it can be disabled
8173 in a specific instance by prepending the "no" keyword before it.
8174
8175
8176option checkcache
8177no option checkcache
Godbach7056a352013-12-11 20:01:07 +08008178 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008179 May be used in sections : defaults | frontend | listen | backend
8180 yes | no | yes | yes
8181 Arguments : none
8182
8183 Some high-level frameworks set application cookies everywhere and do not
8184 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008185 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008186 high risk of session crossing or stealing between users traversing the same
8187 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02008188 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008189
8190 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008191 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01008192 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008193 response to check if there's a risk of caching a cookie on a client-side
8194 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01008195 to the client are :
Davor Ocelice9ed2812017-12-25 17:49:28 +01008196 - all those without "Set-Cookie" header;
Willy Tarreauc55ddce2017-12-21 11:41:38 +01008197 - all those with a return code other than 200, 203, 204, 206, 300, 301,
8198 404, 405, 410, 414, 501, provided that the server has not set a
Davor Ocelice9ed2812017-12-25 17:49:28 +01008199 "Cache-control: public" header field;
Willy Tarreau24ea0bc2017-12-21 11:32:55 +01008200 - all those that result from a request using a method other than GET, HEAD,
8201 OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
Davor Ocelice9ed2812017-12-25 17:49:28 +01008202 public' header field;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008203 - those with a 'Pragma: no-cache' header
8204 - those with a 'Cache-control: private' header
8205 - those with a 'Cache-control: no-store' header
8206 - those with a 'Cache-control: max-age=0' header
8207 - those with a 'Cache-control: s-maxage=0' header
8208 - those with a 'Cache-control: no-cache' header
8209 - those with a 'Cache-control: no-cache="set-cookie"' header
8210 - those with a 'Cache-control: no-cache="set-cookie,' header
8211 (allowing other fields after set-cookie)
8212
8213 If a response doesn't respect these requirements, then it will be blocked
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02008214 just as if it was from an "http-response deny" rule, with an "HTTP 502 bad
8215 gateway". The session state shows "PH--" meaning that the proxy blocked the
8216 response during headers processing. Additionally, an alert will be sent in
8217 the logs so that admins are informed that there's something to be fixed.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008218
8219 Due to the high impact on the application, the application should be tested
8220 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008221 good practice to always activate it during tests, even if it is not used in
Davor Ocelice9ed2812017-12-25 17:49:28 +01008222 production, as it will report potentially dangerous application behaviors.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008223
8224 If this option has been enabled in a "defaults" section, it can be disabled
8225 in a specific instance by prepending the "no" keyword before it.
8226
8227
8228option clitcpka
8229no option clitcpka
8230 Enable or disable the sending of TCP keepalive packets on the client side
8231 May be used in sections : defaults | frontend | listen | backend
8232 yes | yes | yes | no
8233 Arguments : none
8234
8235 When there is a firewall or any session-aware component between a client and
8236 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01008237 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008238 components decides to expire a session which has remained idle for too long.
8239
8240 Enabling socket-level TCP keep-alives makes the system regularly send packets
8241 to the other end of the connection, leaving it active. The delay between
8242 keep-alive probes is controlled by the system only and depends both on the
8243 operating system and its tuning parameters.
8244
8245 It is important to understand that keep-alive packets are neither emitted nor
8246 received at the application level. It is only the network stacks which sees
8247 them. For this reason, even if one side of the proxy already uses keep-alives
8248 to maintain its connection alive, those keep-alive packets will not be
8249 forwarded to the other side of the proxy.
8250
8251 Please note that this has nothing to do with HTTP keep-alive.
8252
8253 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
8254 client side of a connection, which should help when session expirations are
8255 noticed between HAProxy and a client.
8256
8257 If this option has been enabled in a "defaults" section, it can be disabled
8258 in a specific instance by prepending the "no" keyword before it.
8259
8260 See also : "option srvtcpka", "option tcpka"
8261
8262
Willy Tarreau0ba27502007-12-24 16:55:16 +01008263option contstats
8264 Enable continuous traffic statistics updates
8265 May be used in sections : defaults | frontend | listen | backend
8266 yes | yes | yes | no
8267 Arguments : none
8268
8269 By default, counters used for statistics calculation are incremented
8270 only when a session finishes. It works quite well when serving small
8271 objects, but with big ones (for example large images or archives) or
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008272 with A/V streaming, a graph generated from HAProxy counters looks like
Willy Tarreaudef0d222016-11-08 22:03:00 +01008273 a hedgehog. With this option enabled counters get incremented frequently
8274 along the session, typically every 5 seconds, which is often enough to
8275 produce clean graphs. Recounting touches a hotpath directly so it is not
8276 not enabled by default, as it can cause a lot of wakeups for very large
8277 session counts and cause a small performance drop.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008278
Christopher Faulet89aed322020-06-02 17:33:56 +02008279option disable-h2-upgrade
8280no option disable-h2-upgrade
8281 Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client
8282 connection.
8283 May be used in sections : defaults | frontend | listen | backend
8284 yes | yes | yes | no
8285 Arguments : none
8286
8287 By default, HAProxy is able to implicitly upgrade an HTTP/1.x client
8288 connection to an HTTP/2 connection if the first request it receives from a
8289 given HTTP connection matches the HTTP/2 connection preface (i.e. the string
8290 "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"). This way, it is possible to support
Christopher Faulet982e17d2021-03-26 14:44:18 +01008291 HTTP/1.x and HTTP/2 clients on a non-SSL connections. This option must be
8292 used to disable the implicit upgrade. Note this implicit upgrade is only
8293 supported for HTTP proxies, thus this option too. Note also it is possible to
8294 force the HTTP/2 on clear connections by specifying "proto h2" on the bind
8295 line. Finally, this option is applied on all bind lines. To disable implicit
8296 HTTP/2 upgrades for a specific bind line, it is possible to use "proto h1".
Christopher Faulet89aed322020-06-02 17:33:56 +02008297
8298 If this option has been enabled in a "defaults" section, it can be disabled
8299 in a specific instance by prepending the "no" keyword before it.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008300
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008301option dontlog-normal
8302no option dontlog-normal
8303 Enable or disable logging of normal, successful connections
8304 May be used in sections : defaults | frontend | listen | backend
8305 yes | yes | yes | no
8306 Arguments : none
8307
8308 There are large sites dealing with several thousand connections per second
8309 and for which logging is a major pain. Some of them are even forced to turn
8310 logs off and cannot debug production issues. Setting this option ensures that
8311 normal connections, those which experience no error, no timeout, no retry nor
8312 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
8313 mode, the response status code is checked and return codes 5xx will still be
8314 logged.
8315
8316 It is strongly discouraged to use this option as most of the time, the key to
8317 complex issues is in the normal logs which will not be logged here. If you
8318 need to separate logs, see the "log-separate-errors" option instead.
8319
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008320 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008321 logging.
8322
8323
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008324option dontlognull
8325no option dontlognull
8326 Enable or disable logging of null connections
8327 May be used in sections : defaults | frontend | listen | backend
8328 yes | yes | yes | no
8329 Arguments : none
8330
8331 In certain environments, there are components which will regularly connect to
8332 various systems to ensure that they are still alive. It can be the case from
8333 another load balancer as well as from monitoring systems. By default, even a
8334 simple port probe or scan will produce a log. If those connections pollute
8335 the logs too much, it is possible to enable option "dontlognull" to indicate
8336 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02008337 which typically corresponds to those probes. Note that errors will still be
8338 returned to the client and accounted for in the stats. If this is not what is
8339 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008340
8341 It is generally recommended not to use this option in uncontrolled
Davor Ocelice9ed2812017-12-25 17:49:28 +01008342 environments (e.g. internet), otherwise scans and other malicious activities
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008343 would not be logged.
8344
8345 If this option has been enabled in a "defaults" section, it can be disabled
8346 in a specific instance by prepending the "no" keyword before it.
8347
Willy Tarreau9e9919d2020-10-14 15:55:23 +02008348 See also : "log", "http-ignore-probes", "monitor-uri", and
Willy Tarreau0f228a02015-05-01 15:37:53 +02008349 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008350
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008351
Willy Tarreau87cf5142011-08-19 22:57:24 +02008352option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01008353 Enable insertion of the X-Forwarded-For header to requests sent to servers
8354 May be used in sections : defaults | frontend | listen | backend
8355 yes | yes | yes | yes
8356 Arguments :
8357 <network> is an optional argument used to disable this option for sources
8358 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02008359 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01008360 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008361
8362 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
8363 their client address. This is sometimes annoying when the client's IP address
8364 is expected in server logs. To solve this problem, the well-known HTTP header
8365 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
8366 This header contains a value representing the client's IP address. Since this
8367 header is always appended at the end of the existing header list, the server
8368 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02008369 the server's manual to find how to enable use of this standard header. Note
8370 that only the last occurrence of the header must be used, since it is really
8371 possible that the client has already brought one.
8372
Willy Tarreaud72758d2010-01-12 10:42:19 +01008373 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02008374 the default "X-Forwarded-For". This can be useful where you might already
Davor Ocelice9ed2812017-12-25 17:49:28 +01008375 have a "X-Forwarded-For" header from a different application (e.g. stunnel),
Willy Tarreaud72758d2010-01-12 10:42:19 +01008376 and you need preserve it. Also if your backend server doesn't use the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008377 "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
Ross Westaf72a1d2008-08-03 10:51:45 +02008378 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01008379
8380 Sometimes, a same HAProxy instance may be shared between a direct client
8381 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
8382 used to decrypt HTTPS traffic). It is possible to disable the addition of the
8383 header for a known source address or network by adding the "except" keyword
8384 followed by the network address. In this case, any source IP matching the
8385 network will not cause an addition of this header. Most common uses are with
Christopher Faulet5d1def62021-02-26 09:19:15 +01008386 private networks or 127.0.0.1. IPv4 and IPv6 are both supported.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008387
Willy Tarreau87cf5142011-08-19 22:57:24 +02008388 Alternatively, the keyword "if-none" states that the header will only be
8389 added if it is not present. This should only be used in perfectly trusted
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008390 environment, as this might cause a security issue if headers reaching HAProxy
Willy Tarreau87cf5142011-08-19 22:57:24 +02008391 are under the control of the end-user.
8392
Willy Tarreauc27debf2008-01-06 08:57:02 +01008393 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02008394 least one of them uses it, the header will be added. Note that the backend's
8395 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02008396 both are defined. In the case of the "if-none" argument, if at least one of
8397 the frontend or the backend does not specify it, it wants the addition to be
8398 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008399
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02008400 Example :
Willy Tarreauc27debf2008-01-06 08:57:02 +01008401 # Public HTTP address also used by stunnel on the same machine
8402 frontend www
8403 mode http
8404 option forwardfor except 127.0.0.1 # stunnel already adds the header
8405
Ross Westaf72a1d2008-08-03 10:51:45 +02008406 # Those servers want the IP Address in X-Client
8407 backend www
8408 mode http
8409 option forwardfor header X-Client
8410
Willy Tarreau87cf5142011-08-19 22:57:24 +02008411 See also : "option httpclose", "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02008412 "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01008413
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008414
Christopher Faulet98fbe952019-07-22 16:18:24 +02008415option h1-case-adjust-bogus-client
8416no option h1-case-adjust-bogus-client
8417 Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
8418 May be used in sections : defaults | frontend | listen | backend
8419 yes | yes | yes | no
8420 Arguments : none
8421
8422 There is no standard case for header names because, as stated in RFC7230,
8423 they are case-insensitive. So applications must handle them in a case-
8424 insensitive manner. But some bogus applications violate the standards and
8425 erroneously rely on the cases most commonly used by browsers. This problem
8426 becomes critical with HTTP/2 because all header names must be exchanged in
8427 lower case, and HAProxy follows the same convention. All header names are
8428 sent in lower case to clients and servers, regardless of the HTTP version.
8429
8430 When HAProxy receives an HTTP/1 response, its header names are converted to
8431 lower case and manipulated and sent this way to the clients. If a client is
8432 known to violate the HTTP standards and to fail to process a response coming
8433 from HAProxy, it is possible to transform the lower case header names to a
8434 different format when the response is formatted and sent to the client, by
8435 enabling this option and specifying the list of headers to be reformatted
8436 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
8437 must only be a temporary workaround for the time it takes the client to be
8438 fixed, because clients which require such workarounds might be vulnerable to
8439 content smuggling attacks and must absolutely be fixed.
8440
8441 Please note that this option will not affect standards-compliant clients.
8442
8443 If this option has been enabled in a "defaults" section, it can be disabled
8444 in a specific instance by prepending the "no" keyword before it.
8445
8446 See also: "option h1-case-adjust-bogus-server", "h1-case-adjust",
8447 "h1-case-adjust-file".
8448
8449
8450option h1-case-adjust-bogus-server
8451no option h1-case-adjust-bogus-server
8452 Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
8453 May be used in sections : defaults | frontend | listen | backend
8454 yes | no | yes | yes
8455 Arguments : none
8456
8457 There is no standard case for header names because, as stated in RFC7230,
8458 they are case-insensitive. So applications must handle them in a case-
8459 insensitive manner. But some bogus applications violate the standards and
8460 erroneously rely on the cases most commonly used by browsers. This problem
8461 becomes critical with HTTP/2 because all header names must be exchanged in
8462 lower case, and HAProxy follows the same convention. All header names are
8463 sent in lower case to clients and servers, regardless of the HTTP version.
8464
8465 When HAProxy receives an HTTP/1 request, its header names are converted to
8466 lower case and manipulated and sent this way to the servers. If a server is
8467 known to violate the HTTP standards and to fail to process a request coming
8468 from HAProxy, it is possible to transform the lower case header names to a
8469 different format when the request is formatted and sent to the server, by
8470 enabling this option and specifying the list of headers to be reformatted
8471 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
8472 must only be a temporary workaround for the time it takes the server to be
8473 fixed, because servers which require such workarounds might be vulnerable to
8474 content smuggling attacks and must absolutely be fixed.
8475
8476 Please note that this option will not affect standards-compliant servers.
8477
8478 If this option has been enabled in a "defaults" section, it can be disabled
8479 in a specific instance by prepending the "no" keyword before it.
8480
8481 See also: "option h1-case-adjust-bogus-client", "h1-case-adjust",
8482 "h1-case-adjust-file".
8483
8484
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02008485option http-buffer-request
8486no option http-buffer-request
8487 Enable or disable waiting for whole HTTP request body before proceeding
8488 May be used in sections : defaults | frontend | listen | backend
8489 yes | yes | yes | yes
8490 Arguments : none
8491
8492 It is sometimes desirable to wait for the body of an HTTP request before
8493 taking a decision. This is what is being done by "balance url_param" for
8494 example. The first use case is to buffer requests from slow clients before
8495 connecting to the server. Another use case consists in taking the routing
8496 decision based on the request body's contents. This option placed in a
8497 frontend or backend forces the HTTP processing to wait until either the whole
Christopher Faulet6db8a2e2019-11-19 16:27:25 +01008498 body is received or the request buffer is full. It can have undesired side
8499 effects with some applications abusing HTTP by expecting unbuffered
8500 transmissions between the frontend and the backend, so this should definitely
8501 not be used by default.
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02008502
Christopher Faulet021a8e42021-03-29 10:46:38 +02008503 See also : "option http-no-delay", "timeout http-request",
8504 "http-request wait-for-body"
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02008505
8506
Willy Tarreau0f228a02015-05-01 15:37:53 +02008507option http-ignore-probes
8508no option http-ignore-probes
8509 Enable or disable logging of null connections and request timeouts
8510 May be used in sections : defaults | frontend | listen | backend
8511 yes | yes | yes | no
8512 Arguments : none
8513
8514 Recently some browsers started to implement a "pre-connect" feature
8515 consisting in speculatively connecting to some recently visited web sites
8516 just in case the user would like to visit them. This results in many
8517 connections being established to web sites, which end up in 408 Request
8518 Timeout if the timeout strikes first, or 400 Bad Request when the browser
8519 decides to close them first. These ones pollute the log and feed the error
8520 counters. There was already "option dontlognull" but it's insufficient in
8521 this case. Instead, this option does the following things :
8522 - prevent any 400/408 message from being sent to the client if nothing
Davor Ocelice9ed2812017-12-25 17:49:28 +01008523 was received over a connection before it was closed;
8524 - prevent any log from being emitted in this situation;
Willy Tarreau0f228a02015-05-01 15:37:53 +02008525 - prevent any error counter from being incremented
8526
8527 That way the empty connection is silently ignored. Note that it is better
8528 not to use this unless it is clear that it is needed, because it will hide
8529 real problems. The most common reason for not receiving a request and seeing
8530 a 408 is due to an MTU inconsistency between the client and an intermediary
8531 element such as a VPN, which blocks too large packets. These issues are
8532 generally seen with POST requests as well as GET with large cookies. The logs
8533 are often the only way to detect them.
8534
8535 If this option has been enabled in a "defaults" section, it can be disabled
8536 in a specific instance by prepending the "no" keyword before it.
8537
8538 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
8539
8540
Willy Tarreau16bfb022010-01-16 19:48:41 +01008541option http-keep-alive
8542no option http-keep-alive
8543 Enable or disable HTTP keep-alive from client to server
8544 May be used in sections : defaults | frontend | listen | backend
8545 yes | yes | yes | yes
8546 Arguments : none
8547
Willy Tarreau70dffda2014-01-30 03:07:23 +01008548 By default HAProxy operates in keep-alive mode with regards to persistent
8549 connections: for each connection it processes each request and response, and
Christopher Faulet315b39c2018-09-21 16:26:19 +02008550 leaves the connection idle on both sides between the end of a response and
8551 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02008552 as "option http-server-close" or "option httpclose". This option allows to
8553 set back the keep-alive mode, which can be useful when another mode was used
8554 in a defaults section.
Willy Tarreau70dffda2014-01-30 03:07:23 +01008555
8556 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
8557 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01008558 network) and the fastest session reuse on the server side at the expense
8559 of maintaining idle connections to the servers. In general, it is possible
8560 with this option to achieve approximately twice the request rate that the
8561 "http-server-close" option achieves on small objects. There are mainly two
8562 situations where this option may be useful :
8563
8564 - when the server is non-HTTP compliant and authenticates the connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01008565 instead of requests (e.g. NTLM authentication)
Willy Tarreau16bfb022010-01-16 19:48:41 +01008566
8567 - when the cost of establishing the connection to the server is significant
8568 compared to the cost of retrieving the associated object from the server.
8569
8570 This last case can happen when the server is a fast static server of cache.
8571 In this case, the server will need to be properly tuned to support high enough
8572 connection counts because connections will last until the client sends another
8573 request.
8574
8575 If the client request has to go to another backend or another server due to
8576 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01008577 immediately be closed and a new one re-opened. Option "prefer-last-server" is
8578 available to try optimize server selection so that if the server currently
8579 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01008580
Willy Tarreau16bfb022010-01-16 19:48:41 +01008581 At the moment, logs will not indicate whether requests came from the same
8582 session or not. The accept date reported in the logs corresponds to the end
8583 of the previous request, and the request time corresponds to the time spent
8584 waiting for a new request. The keep-alive request time is still bound to the
8585 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
8586 not set.
8587
Christopher Faulet159e6672019-07-16 15:09:52 +02008588 This option disables and replaces any previous "option httpclose" or "option
8589 http-server-close". When backend and frontend options differ, all of these 4
8590 options have precedence over "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01008591
Christopher Faulet315b39c2018-09-21 16:26:19 +02008592 See also : "option httpclose",, "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01008593 "option prefer-last-server", "option http-pretend-keepalive",
Frédéric Lécaille93d33162019-03-06 09:35:59 +01008594 and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01008595
8596
Willy Tarreau96e31212011-05-30 18:10:30 +02008597option http-no-delay
8598no option http-no-delay
8599 Instruct the system to favor low interactive delays over performance in HTTP
8600 May be used in sections : defaults | frontend | listen | backend
8601 yes | yes | yes | yes
8602 Arguments : none
8603
8604 In HTTP, each payload is unidirectional and has no notion of interactivity.
8605 Any agent is expected to queue data somewhat for a reasonably low delay.
8606 There are some very rare server-to-server applications that abuse the HTTP
8607 protocol and expect the payload phase to be highly interactive, with many
8608 interleaved data chunks in both directions within a single request. This is
8609 absolutely not supported by the HTTP specification and will not work across
8610 most proxies or servers. When such applications attempt to do this through
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008611 HAProxy, it works but they will experience high delays due to the network
Willy Tarreau96e31212011-05-30 18:10:30 +02008612 optimizations which favor performance by instructing the system to wait for
8613 enough data to be available in order to only send full packets. Typical
8614 delays are around 200 ms per round trip. Note that this only happens with
8615 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
8616 affected.
8617
8618 When "option http-no-delay" is present in either the frontend or the backend
8619 used by a connection, all such optimizations will be disabled in order to
8620 make the exchanges as fast as possible. Of course this offers no guarantee on
8621 the functionality, as it may break at any other place. But if it works via
8622 HAProxy, it will work as fast as possible. This option should never be used
8623 by default, and should never be used at all unless such a buggy application
8624 is discovered. The impact of using this option is an increase of bandwidth
8625 usage and CPU usage, which may significantly lower performance in high
8626 latency environments.
8627
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02008628 See also : "option http-buffer-request"
8629
Willy Tarreau96e31212011-05-30 18:10:30 +02008630
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008631option http-pretend-keepalive
8632no option http-pretend-keepalive
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008633 Define whether HAProxy will announce keepalive to the server or not
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008634 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet98db9762018-09-21 10:25:19 +02008635 yes | no | yes | yes
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008636 Arguments : none
8637
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008638 When running with "option http-server-close" or "option httpclose", HAProxy
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008639 adds a "Connection: close" header to the request forwarded to the server.
8640 Unfortunately, when some servers see this header, they automatically refrain
8641 from using the chunked encoding for responses of unknown length, while this
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008642 is totally unrelated. The immediate effect is that this prevents HAProxy from
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008643 maintaining the client connection alive. A second effect is that a client or
8644 a cache could receive an incomplete response without being aware of it, and
8645 consider the response complete.
8646
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008647 By setting "option http-pretend-keepalive", HAProxy will make the server
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008648 believe it will keep the connection alive. The server will then not fall back
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008649 to the abnormal undesired above. When HAProxy gets the whole response, it
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008650 will close the connection with the server just as it would do with the
Christopher Faulet315b39c2018-09-21 16:26:19 +02008651 "option httpclose". That way the client gets a normal response and the
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008652 connection is correctly closed on the server side.
8653
8654 It is recommended not to enable this option by default, because most servers
8655 will more efficiently close the connection themselves after the last packet,
8656 and release its buffers slightly earlier. Also, the added packet on the
8657 network could slightly reduce the overall peak performance. However it is
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008658 worth noting that when this option is enabled, HAProxy will have slightly
8659 less work to do. So if HAProxy is the bottleneck on the whole architecture,
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008660 enabling this option might save a few CPU cycles.
8661
Christopher Faulet98db9762018-09-21 10:25:19 +02008662 This option may be set in backend and listen sections. Using it in a frontend
8663 section will be ignored and a warning will be reported during startup. It is
8664 a backend related option, so there is no real reason to set it on a
8665 frontend. This option may be combined with "option httpclose", which will
8666 cause keepalive to be announced to the server and close to be announced to
8667 the client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008668
8669 If this option has been enabled in a "defaults" section, it can be disabled
8670 in a specific instance by prepending the "no" keyword before it.
8671
Christopher Faulet315b39c2018-09-21 16:26:19 +02008672 See also : "option httpclose", "option http-server-close", and
Willy Tarreau16bfb022010-01-16 19:48:41 +01008673 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02008674
Willy Tarreauc27debf2008-01-06 08:57:02 +01008675
Willy Tarreaub608feb2010-01-02 22:47:18 +01008676option http-server-close
8677no option http-server-close
8678 Enable or disable HTTP connection closing on the server side
8679 May be used in sections : defaults | frontend | listen | backend
8680 yes | yes | yes | yes
8681 Arguments : none
8682
Willy Tarreau70dffda2014-01-30 03:07:23 +01008683 By default HAProxy operates in keep-alive mode with regards to persistent
8684 connections: for each connection it processes each request and response, and
8685 leaves the connection idle on both sides between the end of a response and
8686 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02008687 as "option http-server-close" or "option httpclose". Setting "option
8688 http-server-close" enables HTTP connection-close mode on the server side
8689 while keeping the ability to support HTTP keep-alive and pipelining on the
8690 client side. This provides the lowest latency on the client side (slow
8691 network) and the fastest session reuse on the server side to save server
8692 resources, similarly to "option httpclose". It also permits non-keepalive
8693 capable servers to be served in keep-alive mode to the clients if they
8694 conform to the requirements of RFC7230. Please note that some servers do not
8695 always conform to those requirements when they see "Connection: close" in the
8696 request. The effect will be that keep-alive will never be used. A workaround
8697 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01008698
8699 At the moment, logs will not indicate whether requests came from the same
8700 session or not. The accept date reported in the logs corresponds to the end
8701 of the previous request, and the request time corresponds to the time spent
8702 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01008703 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
8704 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01008705
8706 This option may be set both in a frontend and in a backend. It is enabled if
8707 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet159e6672019-07-16 15:09:52 +02008708 It disables and replaces any previous "option httpclose" or "option
8709 http-keep-alive". Please check section 4 ("Proxies") to see how this option
8710 combines with others when frontend and backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01008711
8712 If this option has been enabled in a "defaults" section, it can be disabled
8713 in a specific instance by prepending the "no" keyword before it.
8714
Christopher Faulet315b39c2018-09-21 16:26:19 +02008715 See also : "option httpclose", "option http-pretend-keepalive",
8716 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01008717
Willy Tarreau88d349d2010-01-25 12:15:43 +01008718option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01008719no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01008720 Make use of non-standard Proxy-Connection header instead of Connection
8721 May be used in sections : defaults | frontend | listen | backend
8722 yes | yes | yes | no
8723 Arguments : none
8724
Lukas Tribus23953682017-04-28 13:24:30 +00008725 While RFC7230 explicitly states that HTTP/1.1 agents must use the
Willy Tarreau88d349d2010-01-25 12:15:43 +01008726 Connection header to indicate their wish of persistent or non-persistent
8727 connections, both browsers and proxies ignore this header for proxied
8728 connections and make use of the undocumented, non-standard Proxy-Connection
8729 header instead. The issue begins when trying to put a load balancer between
8730 browsers and such proxies, because there will be a difference between what
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008731 HAProxy understands and what the client and the proxy agree on.
Willy Tarreau88d349d2010-01-25 12:15:43 +01008732
Daniel Corbett9f0843f2021-05-08 10:50:37 -04008733 By setting this option in a frontend, HAProxy can automatically switch to use
Willy Tarreau88d349d2010-01-25 12:15:43 +01008734 that non-standard header if it sees proxied requests. A proxied request is
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01008735 defined here as one where the URI begins with neither a '/' nor a '*'. This
8736 is incompatible with the HTTP tunnel mode. Note that this option can only be
8737 specified in a frontend and will affect the request along its whole life.
Willy Tarreau88d349d2010-01-25 12:15:43 +01008738
Willy Tarreau844a7e72010-01-31 21:46:18 +01008739 Also, when this option is set, a request which requires authentication will
8740 automatically switch to use proxy authentication headers if it is itself a
8741 proxied request. That makes it possible to check or enforce authentication in
8742 front of an existing proxy.
8743
Willy Tarreau88d349d2010-01-25 12:15:43 +01008744 This option should normally never be used, except in front of a proxy.
8745
Christopher Faulet315b39c2018-09-21 16:26:19 +02008746 See also : "option httpclose", and "option http-server-close".
Willy Tarreau88d349d2010-01-25 12:15:43 +01008747
Willy Tarreaud63335a2010-02-26 12:56:52 +01008748option httpchk
8749option httpchk <uri>
8750option httpchk <method> <uri>
8751option httpchk <method> <uri> <version>
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02008752 Enables HTTP protocol to check on the servers health
Willy Tarreaud63335a2010-02-26 12:56:52 +01008753 May be used in sections : defaults | frontend | listen | backend
8754 yes | no | yes | yes
8755 Arguments :
8756 <method> is the optional HTTP method used with the requests. When not set,
8757 the "OPTIONS" method is used, as it generally requires low server
8758 processing and is easy to filter out from the logs. Any method
8759 may be used, though it is not recommended to invent non-standard
8760 ones.
8761
8762 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
8763 which is accessible by default on almost any server, but may be
8764 changed to any other URI. Query strings are permitted.
8765
8766 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
8767 but some servers might behave incorrectly in HTTP 1.0, so turning
8768 it to HTTP/1.1 may sometimes help. Note that the Host field is
Christopher Faulet8acb1282020-04-09 08:44:06 +02008769 mandatory in HTTP/1.1, use "http-check send" directive to add it.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008770
8771 By default, server health checks only consist in trying to establish a TCP
8772 connection. When "option httpchk" is specified, a complete HTTP request is
8773 sent once the TCP connection is established, and responses 2xx and 3xx are
8774 considered valid, while all other ones indicate a server failure, including
8775 the lack of any response.
8776
Christopher Faulete5870d82020-04-15 11:32:03 +02008777 Combined with "http-check" directives, it is possible to customize the
8778 request sent during the HTTP health checks or the matching rules on the
8779 response. It is also possible to configure a send/expect sequence, just like
8780 with the directive "tcp-check" for TCP health checks.
8781
8782 The server configuration is used by default to open connections to perform
8783 HTTP health checks. By it is also possible to overwrite server parameters
8784 using "http-check connect" rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008785
Christopher Faulete5870d82020-04-15 11:32:03 +02008786 "httpchk" option does not necessarily require an HTTP backend, it also works
8787 with plain TCP backends. This is particularly useful to check simple scripts
Christopher Faulet14cd3162020-04-16 14:50:06 +02008788 bound to some dedicated ports using the inetd daemon. However, it will always
Daniel Corbett67a82712020-07-06 23:01:19 -04008789 internally relies on an HTX multiplexer. Thus, it means the request
Christopher Faulet14cd3162020-04-16 14:50:06 +02008790 formatting and the response parsing will be strict.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008791
Christopher Faulet8acb1282020-04-09 08:44:06 +02008792 Note : For a while, there was no way to add headers or body in the request
8793 used for HTTP health checks. So a workaround was to hide it at the end
8794 of the version string with a "\r\n" after the version. It is now
8795 deprecated. The directive "http-check send" must be used instead.
8796
Willy Tarreaud63335a2010-02-26 12:56:52 +01008797 Examples :
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02008798 # Relay HTTPS traffic to Apache instance and check service availability
8799 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
8800 backend https_relay
8801 mode tcp
8802 option httpchk OPTIONS * HTTP/1.1
8803 http-check send hdr Host www
8804 server apache1 192.168.1.1:443 check port 80
Willy Tarreaud63335a2010-02-26 12:56:52 +01008805
Simon Hormanafc47ee2013-11-25 10:46:35 +09008806 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
8807 "option pgsql-check", "http-check" and the "check", "port" and
8808 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008809
8810
Willy Tarreauc27debf2008-01-06 08:57:02 +01008811option httpclose
8812no option httpclose
Christopher Faulet315b39c2018-09-21 16:26:19 +02008813 Enable or disable HTTP connection closing
Willy Tarreauc27debf2008-01-06 08:57:02 +01008814 May be used in sections : defaults | frontend | listen | backend
8815 yes | yes | yes | yes
8816 Arguments : none
8817
Willy Tarreau70dffda2014-01-30 03:07:23 +01008818 By default HAProxy operates in keep-alive mode with regards to persistent
8819 connections: for each connection it processes each request and response, and
8820 leaves the connection idle on both sides between the end of a response and
8821 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02008822 as "option http-server-close" or "option httpclose".
Willy Tarreau70dffda2014-01-30 03:07:23 +01008823
Christopher Faulet315b39c2018-09-21 16:26:19 +02008824 If "option httpclose" is set, HAProxy will close connections with the server
8825 and the client as soon as the request and the response are received. It will
John Roeslerfb2fce12019-07-10 15:45:51 -05008826 also check if a "Connection: close" header is already set in each direction,
Christopher Faulet315b39c2018-09-21 16:26:19 +02008827 and will add one if missing. Any "Connection" header different from "close"
8828 will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008829
Christopher Faulet315b39c2018-09-21 16:26:19 +02008830 This option may also be combined with "option http-pretend-keepalive", which
8831 will disable sending of the "Connection: close" header, but will still cause
8832 the connection to be closed once the whole response is received.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008833
8834 This option may be set both in a frontend and in a backend. It is enabled if
8835 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet159e6672019-07-16 15:09:52 +02008836 It disables and replaces any previous "option http-server-close" or "option
8837 http-keep-alive". Please check section 4 ("Proxies") to see how this option
8838 combines with others when frontend and backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008839
8840 If this option has been enabled in a "defaults" section, it can be disabled
8841 in a specific instance by prepending the "no" keyword before it.
8842
Christopher Faulet315b39c2018-09-21 16:26:19 +02008843 See also : "option http-server-close" and "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01008844
8845
Emeric Brun3a058f32009-06-30 18:26:00 +02008846option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01008847 Enable logging of HTTP request, session state and timers
8848 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01008849 yes | yes | yes | no
Emeric Brun3a058f32009-06-30 18:26:00 +02008850 Arguments :
8851 clf if the "clf" argument is added, then the output format will be
8852 the CLF format instead of HAProxy's default HTTP format. You can
8853 use this when you need to feed HAProxy's logs through a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01008854 log analyzer which only support the CLF format and which is not
Emeric Brun3a058f32009-06-30 18:26:00 +02008855 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008856
8857 By default, the log output format is very poor, as it only contains the
8858 source and destination addresses, and the instance name. By specifying
8859 "option httplog", each log line turns into a much richer format including,
8860 but not limited to, the HTTP request, the connection timers, the session
8861 status, the connections numbers, the captured headers and cookies, the
8862 frontend, backend and server name, and of course the source address and
8863 ports.
8864
PiBa-NLbd556bf2014-12-11 21:31:54 +01008865 Specifying only "option httplog" will automatically clear the 'clf' mode
8866 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02008867
Guillaume de Lafond29f45602017-03-31 19:52:15 +02008868 "option httplog" overrides any previous "log-format" directive.
8869
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008870 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008871
Willy Tarreau55165fe2009-05-10 12:02:55 +02008872
8873option http_proxy
8874no option http_proxy
8875 Enable or disable plain HTTP proxy mode
8876 May be used in sections : defaults | frontend | listen | backend
8877 yes | yes | yes | yes
8878 Arguments : none
8879
8880 It sometimes happens that people need a pure HTTP proxy which understands
8881 basic proxy requests without caching nor any fancy feature. In this case,
8882 it may be worth setting up an HAProxy instance with the "option http_proxy"
8883 set. In this mode, no server is declared, and the connection is forwarded to
8884 the IP address and port found in the URL after the "http://" scheme.
8885
8886 No host address resolution is performed, so this only works when pure IP
8887 addresses are passed. Since this option's usage perimeter is rather limited,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01008888 it will probably be used only by experts who know they need exactly it. This
8889 is incompatible with the HTTP tunnel mode.
Willy Tarreau55165fe2009-05-10 12:02:55 +02008890
8891 If this option has been enabled in a "defaults" section, it can be disabled
8892 in a specific instance by prepending the "no" keyword before it.
8893
8894 Example :
8895 # this backend understands HTTP proxy requests and forwards them directly.
8896 backend direct_forward
8897 option httpclose
8898 option http_proxy
8899
8900 See also : "option httpclose"
8901
Willy Tarreau211ad242009-10-03 21:45:07 +02008902
Jamie Gloudon801a0a32012-08-25 00:18:33 -04008903option independent-streams
8904no option independent-streams
8905 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02008906 May be used in sections : defaults | frontend | listen | backend
8907 yes | yes | yes | yes
8908 Arguments : none
8909
8910 By default, when data is sent over a socket, both the write timeout and the
8911 read timeout for that socket are refreshed, because we consider that there is
8912 activity on that socket, and we have no other means of guessing if we should
8913 receive data or not.
8914
Davor Ocelice9ed2812017-12-25 17:49:28 +01008915 While this default behavior is desirable for almost all applications, there
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02008916 exists a situation where it is desirable to disable it, and only refresh the
8917 read timeout if there are incoming data. This happens on sessions with large
8918 timeouts and low amounts of exchanged data such as telnet session. If the
8919 server suddenly disappears, the output data accumulates in the system's
8920 socket buffers, both timeouts are correctly refreshed, and there is no way
8921 to know the server does not receive them, so we don't timeout. However, when
8922 the underlying protocol always echoes sent data, it would be enough by itself
8923 to detect the issue using the read timeout. Note that this problem does not
8924 happen with more verbose protocols because data won't accumulate long in the
8925 socket buffers.
8926
8927 When this option is set on the frontend, it will disable read timeout updates
8928 on data sent to the client. There probably is little use of this case. When
8929 the option is set on the backend, it will disable read timeout updates on
8930 data sent to the server. Doing so will typically break large HTTP posts from
8931 slow lines, so use it with caution.
8932
Willy Tarreauce887fd2012-05-12 12:50:00 +02008933 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02008934
8935
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02008936option ldap-check
8937 Use LDAPv3 health checks for server testing
8938 May be used in sections : defaults | frontend | listen | backend
8939 yes | no | yes | yes
8940 Arguments : none
8941
8942 It is possible to test that the server correctly talks LDAPv3 instead of just
8943 testing that it accepts the TCP connection. When this option is set, an
8944 LDAPv3 anonymous simple bind message is sent to the server, and the response
8945 is analyzed to find an LDAPv3 bind response message.
8946
8947 The server is considered valid only when the LDAP response contains success
8948 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
8949
8950 Logging of bind requests is server dependent see your documentation how to
8951 configure it.
8952
8953 Example :
8954 option ldap-check
8955
8956 See also : "option httpchk"
8957
8958
Simon Horman98637e52014-06-20 12:30:16 +09008959option external-check
8960 Use external processes for server health checks
8961 May be used in sections : defaults | frontend | listen | backend
8962 yes | no | yes | yes
8963
8964 It is possible to test the health of a server using an external command.
8965 This is achieved by running the executable set using "external-check
8966 command".
8967
8968 Requires the "external-check" global to be set.
8969
8970 See also : "external-check", "external-check command", "external-check path"
8971
8972
Willy Tarreau211ad242009-10-03 21:45:07 +02008973option log-health-checks
8974no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02008975 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02008976 May be used in sections : defaults | frontend | listen | backend
8977 yes | no | yes | yes
8978 Arguments : none
8979
Willy Tarreaubef1b322014-05-13 21:01:39 +02008980 By default, failed health check are logged if server is UP and successful
8981 health checks are logged if server is DOWN, so the amount of additional
8982 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02008983
Willy Tarreaubef1b322014-05-13 21:01:39 +02008984 When this option is enabled, any change of the health check status or to
8985 the server's health will be logged, so that it becomes possible to know
8986 that a server was failing occasional checks before crashing, or exactly when
8987 it failed to respond a valid HTTP status, then when the port started to
8988 reject connections, then when the server stopped responding at all.
8989
Davor Ocelice9ed2812017-12-25 17:49:28 +01008990 Note that status changes not caused by health checks (e.g. enable/disable on
Willy Tarreaubef1b322014-05-13 21:01:39 +02008991 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02008992
Willy Tarreaubef1b322014-05-13 21:01:39 +02008993 See also: "option httpchk", "option ldap-check", "option mysql-check",
8994 "option pgsql-check", "option redis-check", "option smtpchk",
8995 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02008996
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008997
8998option log-separate-errors
8999no option log-separate-errors
9000 Change log level for non-completely successful connections
9001 May be used in sections : defaults | frontend | listen | backend
9002 yes | yes | yes | no
9003 Arguments : none
9004
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009005 Sometimes looking for errors in logs is not easy. This option makes HAProxy
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02009006 raise the level of logs containing potentially interesting information such
9007 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
9008 level changes from "info" to "err". This makes it possible to log them
9009 separately to a different file with most syslog daemons. Be careful not to
9010 remove them from the original file, otherwise you would lose ordering which
9011 provides very important information.
9012
9013 Using this option, large sites dealing with several thousand connections per
9014 second may log normal traffic to a rotating buffer and only archive smaller
9015 error logs.
9016
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009017 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02009018 logging.
9019
Willy Tarreauc27debf2008-01-06 08:57:02 +01009020
9021option logasap
9022no option logasap
Jerome Magnin95fb57b2020-04-23 19:01:17 +02009023 Enable or disable early logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01009024 May be used in sections : defaults | frontend | listen | backend
9025 yes | yes | yes | no
9026 Arguments : none
9027
Jerome Magnin95fb57b2020-04-23 19:01:17 +02009028 By default, logs are emitted when all the log format variables and sample
9029 fetches used in the definition of the log-format string return a value, or
9030 when the session is terminated. This allows the built in log-format strings
9031 to account for the transfer time, or the number of bytes in log messages.
9032
9033 When handling long lived connections such as large file transfers or RDP,
9034 it may take a while for the request or connection to appear in the logs.
9035 Using "option logasap", the log message is created as soon as the server
9036 connection is established in mode tcp, or as soon as the server sends the
9037 complete headers in mode http. Missing information in the logs will be the
Ilya Shipitsin4329a9a2020-05-05 21:17:10 +05009038 total number of bytes which will only indicate the amount of data transferred
Jerome Magnin95fb57b2020-04-23 19:01:17 +02009039 before the message was created and the total time which will not take the
9040 remainder of the connection life or transfer time into account. For the case
9041 of HTTP, it is good practice to capture the Content-Length response header
9042 so that the logs at least indicate how many bytes are expected to be
Ilya Shipitsin4329a9a2020-05-05 21:17:10 +05009043 transferred.
Willy Tarreauc27debf2008-01-06 08:57:02 +01009044
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009045 Examples :
9046 listen http_proxy 0.0.0.0:80
9047 mode http
9048 option httplog
9049 option logasap
9050 log 192.168.2.200 local3
9051
9052 >>> Feb 6 12:14:14 localhost \
9053 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
9054 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
9055 "GET /image.iso HTTP/1.0"
9056
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009057 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01009058 logging.
9059
9060
Christopher Faulet62f79fe2020-05-18 18:13:03 +02009061option mysql-check [ user <username> [ { post-41 | pre-41 } ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02009062 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01009063 May be used in sections : defaults | frontend | listen | backend
9064 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02009065 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009066 <username> This is the username which will be used when connecting to MySQL
9067 server.
Christopher Faulet62f79fe2020-05-18 18:13:03 +02009068 post-41 Send post v4.1 client compatible checks (the default)
9069 pre-41 Send pre v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02009070
9071 If you specify a username, the check consists of sending two MySQL packet,
9072 one Client Authentication packet, and one QUIT packet, to correctly close
Davor Ocelice9ed2812017-12-25 17:49:28 +01009073 MySQL session. We then parse the MySQL Handshake Initialization packet and/or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02009074 Error packet. It is a basic but useful test which does not produce error nor
9075 aborted connect on the server. However, it requires adding an authorization
9076 in the MySQL table, like this :
9077
9078 USE mysql;
9079 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
9080 FLUSH PRIVILEGES;
9081
9082 If you don't specify a username (it is deprecated and not recommended), the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009083 check only consists in parsing the Mysql Handshake Initialization packet or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02009084 Error packet, we don't send anything in this mode. It was reported that it
9085 can generate lockout if check is too frequent and/or if there is not enough
9086 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
9087 value as if a connection is established successfully within fewer than MySQL
9088 "max_connect_errors" attempts after a previous connection was interrupted,
9089 the error count for the host is cleared to zero. If HAProxy's server get
9090 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
9091
9092 Remember that this does not check database presence nor database consistency.
9093 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01009094
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02009095 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01009096
9097 Most often, an incoming MySQL server needs to see the client's IP address for
9098 various purposes, including IP privilege matching and connection logging.
9099 When possible, it is often wise to masquerade the client's IP address when
9100 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02009101 which requires the transparent proxy feature to be compiled in, and the MySQL
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009102 server to route the client via the machine hosting HAProxy.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01009103
9104 See also: "option httpchk"
9105
9106
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009107option nolinger
9108no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009109 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009110 May be used in sections: defaults | frontend | listen | backend
9111 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009112 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009113
Davor Ocelice9ed2812017-12-25 17:49:28 +01009114 When clients or servers abort connections in a dirty way (e.g. they are
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009115 physically disconnected), the session timeouts triggers and the session is
9116 closed. But it will remain in FIN_WAIT1 state for some time in the system,
9117 using some resources and possibly limiting the ability to establish newer
9118 connections.
9119
9120 When this happens, it is possible to activate "option nolinger" which forces
9121 the system to immediately remove any socket's pending data on close. Thus,
Willy Tarreau4a321032020-10-16 04:55:19 +02009122 a TCP RST is emitted, any pending data are truncated, and the session is
9123 instantly purged from the system's tables. The generally visible effect for
9124 a client is that responses are truncated if the close happens with a last
9125 block of data (e.g. on a redirect or error response). On the server side,
9126 it may help release the source ports immediately when forwarding a client
9127 aborts in tunnels. In both cases, TCP resets are emitted and given that
9128 the session is instantly destroyed, there will be no retransmit. On a lossy
9129 network this can increase problems, especially when there is a firewall on
9130 the lossy side, because the firewall might see and process the reset (hence
9131 purge its session) and block any further traffic for this session,, including
9132 retransmits from the other side. So if the other side doesn't receive it,
9133 it will never receive any RST again, and the firewall might log many blocked
9134 packets.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009135
Willy Tarreau4a321032020-10-16 04:55:19 +02009136 For all these reasons, it is strongly recommended NOT to use this option,
9137 unless absolutely needed as a last resort. In most situations, using the
9138 "client-fin" or "server-fin" timeouts achieves similar results with a more
9139 reliable behavior. On Linux it's also possible to use the "tcp-ut" bind or
9140 server setting.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009141
9142 This option may be used both on frontends and backends, depending on the side
9143 where it is required. Use it on the frontend for clients, and on the backend
Willy Tarreau4a321032020-10-16 04:55:19 +02009144 for servers. While this option is technically supported in "defaults"
Ilya Shipitsin2272d8a2020-12-21 01:22:40 +05009145 sections, it must really not be used there as it risks to accidentally
Willy Tarreau4a321032020-10-16 04:55:19 +02009146 propagate to sections that must no use it and to cause problems there.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009147
9148 If this option has been enabled in a "defaults" section, it can be disabled
9149 in a specific instance by prepending the "no" keyword before it.
9150
Willy Tarreau4a321032020-10-16 04:55:19 +02009151 See also: "timeout client-fin", "timeout server-fin", "tcp-ut" bind or server
9152 keywords.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009153
Willy Tarreau55165fe2009-05-10 12:02:55 +02009154option originalto [ except <network> ] [ header <name> ]
9155 Enable insertion of the X-Original-To header to requests sent to servers
9156 May be used in sections : defaults | frontend | listen | backend
9157 yes | yes | yes | yes
9158 Arguments :
9159 <network> is an optional argument used to disable this option for sources
9160 matching <network>
9161 <name> an optional argument to specify a different "X-Original-To"
9162 header name.
9163
9164 Since HAProxy can work in transparent mode, every request from a client can
9165 be redirected to the proxy and HAProxy itself can proxy every request to a
9166 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
9167 be lost. This is annoying when you want access rules based on destination ip
9168 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
9169 added by HAProxy to all requests sent to the server. This header contains a
9170 value representing the original destination IP address. Since this must be
9171 configured to always use the last occurrence of this header only. Note that
9172 only the last occurrence of the header must be used, since it is really
9173 possible that the client has already brought one.
9174
9175 The keyword "header" may be used to supply a different header name to replace
9176 the default "X-Original-To". This can be useful where you might already
9177 have a "X-Original-To" header from a different application, and you need
9178 preserve it. Also if your backend server doesn't use the "X-Original-To"
9179 header and requires different one.
9180
9181 Sometimes, a same HAProxy instance may be shared between a direct client
9182 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
9183 used to decrypt HTTPS traffic). It is possible to disable the addition of the
Amaury Denoyellef8b42922021-03-04 18:41:14 +01009184 header for a known destination address or network by adding the "except"
9185 keyword followed by the network address. In this case, any destination IP
9186 matching the network will not cause an addition of this header. Most common
9187 uses are with private networks or 127.0.0.1. IPv4 and IPv6 are both
9188 supported.
Willy Tarreau55165fe2009-05-10 12:02:55 +02009189
9190 This option may be specified either in the frontend or in the backend. If at
9191 least one of them uses it, the header will be added. Note that the backend's
9192 setting of the header subargument takes precedence over the frontend's if
9193 both are defined.
9194
Willy Tarreau55165fe2009-05-10 12:02:55 +02009195 Examples :
9196 # Original Destination address
9197 frontend www
9198 mode http
9199 option originalto except 127.0.0.1
9200
9201 # Those servers want the IP Address in X-Client-Dst
9202 backend www
9203 mode http
9204 option originalto header X-Client-Dst
9205
Christopher Faulet315b39c2018-09-21 16:26:19 +02009206 See also : "option httpclose", "option http-server-close".
Willy Tarreau55165fe2009-05-10 12:02:55 +02009207
9208
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009209option persist
9210no option persist
9211 Enable or disable forced persistence on down servers
9212 May be used in sections: defaults | frontend | listen | backend
9213 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009214 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009215
9216 When an HTTP request reaches a backend with a cookie which references a dead
9217 server, by default it is redispatched to another server. It is possible to
9218 force the request to be sent to the dead server first using "option persist"
9219 if absolutely needed. A common use case is when servers are under extreme
9220 load and spend their time flapping. In this case, the users would still be
9221 directed to the server they opened the session on, in the hope they would be
9222 correctly served. It is recommended to use "option redispatch" in conjunction
9223 with this option so that in the event it would not be possible to connect to
9224 the server at all (server definitely dead), the client would finally be
9225 redirected to another valid server.
9226
9227 If this option has been enabled in a "defaults" section, it can be disabled
9228 in a specific instance by prepending the "no" keyword before it.
9229
Willy Tarreau4de91492010-01-22 19:10:05 +01009230 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009231
9232
Willy Tarreau0c122822013-12-15 18:49:01 +01009233option pgsql-check [ user <username> ]
9234 Use PostgreSQL health checks for server testing
9235 May be used in sections : defaults | frontend | listen | backend
9236 yes | no | yes | yes
9237 Arguments :
9238 <username> This is the username which will be used when connecting to
9239 PostgreSQL server.
9240
9241 The check sends a PostgreSQL StartupMessage and waits for either
9242 Authentication request or ErrorResponse message. It is a basic but useful
9243 test which does not produce error nor aborted connect on the server.
9244 This check is identical with the "mysql-check".
9245
9246 See also: "option httpchk"
9247
9248
Willy Tarreau9420b122013-12-15 18:58:25 +01009249option prefer-last-server
9250no option prefer-last-server
9251 Allow multiple load balanced requests to remain on the same server
9252 May be used in sections: defaults | frontend | listen | backend
9253 yes | no | yes | yes
9254 Arguments : none
9255
9256 When the load balancing algorithm in use is not deterministic, and a previous
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009257 request was sent to a server to which HAProxy still holds a connection, it is
Willy Tarreau9420b122013-12-15 18:58:25 +01009258 sometimes desirable that subsequent requests on a same session go to the same
9259 server as much as possible. Note that this is different from persistence, as
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009260 we only indicate a preference which HAProxy tries to apply without any form
Willy Tarreau9420b122013-12-15 18:58:25 +01009261 of warranty. The real use is for keep-alive connections sent to servers. When
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009262 this option is used, HAProxy will try to reuse the same connection that is
Willy Tarreau9420b122013-12-15 18:58:25 +01009263 attached to the server instead of rebalancing to another server, causing a
9264 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01009265 not make much sense to use this in combination with hashing algorithms. Note,
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009266 HAProxy already automatically tries to stick to a server which sends a 401 or
Lukas Tribus80512b12018-10-27 20:07:40 +02009267 to a proxy which sends a 407 (authentication required), when the load
9268 balancing algorithm is not deterministic. This is mandatory for use with the
9269 broken NTLM authentication challenge, and significantly helps in
Willy Tarreau068621e2013-12-23 15:11:25 +01009270 troubleshooting some faulty applications. Option prefer-last-server might be
9271 desirable in these environments as well, to avoid redistributing the traffic
9272 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01009273
9274 If this option has been enabled in a "defaults" section, it can be disabled
9275 in a specific instance by prepending the "no" keyword before it.
9276
9277 See also: "option http-keep-alive"
9278
9279
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009280option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07009281option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009282no option redispatch
9283 Enable or disable session redistribution in case of connection failure
9284 May be used in sections: defaults | frontend | listen | backend
9285 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07009286 Arguments :
9287 <interval> The optional integer value that controls how often redispatches
9288 occur when retrying connections. Positive value P indicates a
9289 redispatch is desired on every Pth retry, and negative value
Davor Ocelice9ed2812017-12-25 17:49:28 +01009290 N indicate a redispatch is desired on the Nth retry prior to the
Joseph Lynch726ab712015-05-11 23:25:34 -07009291 last retry. For example, the default of -1 preserves the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009292 historical behavior of redispatching on the last retry, a
Joseph Lynch726ab712015-05-11 23:25:34 -07009293 positive value of 1 would indicate a redispatch on every retry,
9294 and a positive value of 3 would indicate a redispatch on every
9295 third retry. You can disable redispatches with a value of 0.
9296
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009297
9298 In HTTP mode, if a server designated by a cookie is down, clients may
9299 definitely stick to it because they cannot flush the cookie, so they will not
9300 be able to access the service anymore.
9301
Willy Tarreau59884a62019-01-02 14:48:31 +01009302 Specifying "option redispatch" will allow the proxy to break cookie or
9303 consistent hash based persistence and redistribute them to a working server.
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009304
Olivier Carrère6e6f59b2020-04-15 11:30:18 +02009305 Active servers are selected from a subset of the list of available
9306 servers. Active servers that are not down or in maintenance (i.e., whose
9307 health is not checked or that have been checked as "up"), are selected in the
9308 following order:
9309
9310 1. Any active, non-backup server, if any, or,
9311
9312 2. If the "allbackups" option is not set, the first backup server in the
9313 list, or
9314
9315 3. If the "allbackups" option is set, any backup server.
9316
9317 When a retry occurs, HAProxy tries to select another server than the last
9318 one. The new server is selected from the current list of servers.
9319
9320 Sometimes, if the list is updated between retries (e.g., if numerous retries
9321 occur and last longer than the time needed to check that a server is down,
9322 remove it from the list and fall back on the list of backup servers),
9323 connections may be redirected to a backup server, though.
9324
Joseph Lynch726ab712015-05-11 23:25:34 -07009325 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009326 connection failures. Of course, it requires having "retries" set to a nonzero
9327 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01009328
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009329 If this option has been enabled in a "defaults" section, it can be disabled
9330 in a specific instance by prepending the "no" keyword before it.
9331
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02009332 See also : "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009333
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009334
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02009335option redis-check
9336 Use redis health checks for server testing
9337 May be used in sections : defaults | frontend | listen | backend
9338 yes | no | yes | yes
9339 Arguments : none
9340
9341 It is possible to test that the server correctly talks REDIS protocol instead
9342 of just testing that it accepts the TCP connection. When this option is set,
9343 a PING redis command is sent to the server, and the response is analyzed to
9344 find the "+PONG" response message.
9345
9346 Example :
9347 option redis-check
9348
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009349 See also : "option httpchk", "option tcp-check", "tcp-check expect"
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02009350
9351
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009352option smtpchk
9353option smtpchk <hello> <domain>
9354 Use SMTP health checks for server testing
9355 May be used in sections : defaults | frontend | listen | backend
9356 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01009357 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009358 <hello> is an optional argument. It is the "hello" command to use. It can
Lukas Tribus27935782018-10-01 02:00:16 +02009359 be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009360 values will be turned into the default command ("HELO").
9361
9362 <domain> is the domain name to present to the server. It may only be
9363 specified (and is mandatory) if the hello command has been
9364 specified. By default, "localhost" is used.
9365
9366 When "option smtpchk" is set, the health checks will consist in TCP
9367 connections followed by an SMTP command. By default, this command is
9368 "HELO localhost". The server's return code is analyzed and only return codes
9369 starting with a "2" will be considered as valid. All other responses,
9370 including a lack of response will constitute an error and will indicate a
9371 dead server.
9372
9373 This test is meant to be used with SMTP servers or relays. Depending on the
9374 request, it is possible that some servers do not log each connection attempt,
Davor Ocelice9ed2812017-12-25 17:49:28 +01009375 so you may want to experiment to improve the behavior. Using telnet on port
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009376 25 is often easier than adjusting the configuration.
9377
9378 Most often, an incoming SMTP server needs to see the client's IP address for
9379 various purposes, including spam filtering, anti-spoofing and logging. When
9380 possible, it is often wise to masquerade the client's IP address when
9381 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02009382 which requires the transparent proxy feature to be compiled in.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009383
9384 Example :
9385 option smtpchk HELO mydomain.org
9386
9387 See also : "option httpchk", "source"
9388
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01009389
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02009390option socket-stats
9391no option socket-stats
9392
9393 Enable or disable collecting & providing separate statistics for each socket.
9394 May be used in sections : defaults | frontend | listen | backend
9395 yes | yes | yes | no
9396
9397 Arguments : none
9398
9399
Willy Tarreauff4f82d2009-02-06 11:28:13 +01009400option splice-auto
9401no option splice-auto
9402 Enable or disable automatic kernel acceleration on sockets in both directions
9403 May be used in sections : defaults | frontend | listen | backend
9404 yes | yes | yes | yes
9405 Arguments : none
9406
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009407 When this option is enabled either on a frontend or on a backend, HAProxy
Willy Tarreauff4f82d2009-02-06 11:28:13 +01009408 will automatically evaluate the opportunity to use kernel tcp splicing to
Davor Ocelice9ed2812017-12-25 17:49:28 +01009409 forward data between the client and the server, in either direction. HAProxy
Willy Tarreauff4f82d2009-02-06 11:28:13 +01009410 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009411 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01009412 are not much aggressive in order to limit excessive use of splicing. This
9413 option requires splicing to be enabled at compile time, and may be globally
9414 disabled with the global option "nosplice". Since splice uses pipes, using it
9415 requires that there are enough spare pipes.
9416
9417 Important note: kernel-based TCP splicing is a Linux-specific feature which
9418 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
9419 transfer data between sockets without copying these data to user-space, thus
9420 providing noticeable performance gains and CPU cycles savings. Since many
9421 early implementations are buggy, corrupt data and/or are inefficient, this
9422 feature is not enabled by default, and it should be used with extreme care.
9423 While it is not possible to detect the correctness of an implementation,
9424 2.6.29 is the first version offering a properly working implementation. In
9425 case of doubt, splicing may be globally disabled using the global "nosplice"
9426 keyword.
9427
9428 Example :
9429 option splice-auto
9430
9431 If this option has been enabled in a "defaults" section, it can be disabled
9432 in a specific instance by prepending the "no" keyword before it.
9433
9434 See also : "option splice-request", "option splice-response", and global
9435 options "nosplice" and "maxpipes"
9436
9437
9438option splice-request
9439no option splice-request
9440 Enable or disable automatic kernel acceleration on sockets for requests
9441 May be used in sections : defaults | frontend | listen | backend
9442 yes | yes | yes | yes
9443 Arguments : none
9444
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009445 When this option is enabled either on a frontend or on a backend, HAProxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009446 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01009447 the client to the server. It might still use the recv/send scheme if there
9448 are no spare pipes left. This option requires splicing to be enabled at
9449 compile time, and may be globally disabled with the global option "nosplice".
9450 Since splice uses pipes, using it requires that there are enough spare pipes.
9451
9452 Important note: see "option splice-auto" for usage limitations.
9453
9454 Example :
9455 option splice-request
9456
9457 If this option has been enabled in a "defaults" section, it can be disabled
9458 in a specific instance by prepending the "no" keyword before it.
9459
9460 See also : "option splice-auto", "option splice-response", and global options
9461 "nosplice" and "maxpipes"
9462
9463
9464option splice-response
9465no option splice-response
9466 Enable or disable automatic kernel acceleration on sockets for responses
9467 May be used in sections : defaults | frontend | listen | backend
9468 yes | yes | yes | yes
9469 Arguments : none
9470
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009471 When this option is enabled either on a frontend or on a backend, HAProxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009472 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01009473 the server to the client. It might still use the recv/send scheme if there
9474 are no spare pipes left. This option requires splicing to be enabled at
9475 compile time, and may be globally disabled with the global option "nosplice".
9476 Since splice uses pipes, using it requires that there are enough spare pipes.
9477
9478 Important note: see "option splice-auto" for usage limitations.
9479
9480 Example :
9481 option splice-response
9482
9483 If this option has been enabled in a "defaults" section, it can be disabled
9484 in a specific instance by prepending the "no" keyword before it.
9485
9486 See also : "option splice-auto", "option splice-request", and global options
9487 "nosplice" and "maxpipes"
9488
9489
Christopher Fauletba7bc162016-11-07 21:07:38 +01009490option spop-check
9491 Use SPOP health checks for server testing
9492 May be used in sections : defaults | frontend | listen | backend
9493 no | no | no | yes
9494 Arguments : none
9495
9496 It is possible to test that the server correctly talks SPOP protocol instead
9497 of just testing that it accepts the TCP connection. When this option is set,
9498 a HELLO handshake is performed between HAProxy and the server, and the
9499 response is analyzed to check no error is reported.
9500
9501 Example :
9502 option spop-check
9503
9504 See also : "option httpchk"
9505
9506
Willy Tarreaubf1f8162007-12-28 17:42:56 +01009507option srvtcpka
9508no option srvtcpka
9509 Enable or disable the sending of TCP keepalive packets on the server side
9510 May be used in sections : defaults | frontend | listen | backend
9511 yes | no | yes | yes
9512 Arguments : none
9513
9514 When there is a firewall or any session-aware component between a client and
9515 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01009516 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01009517 components decides to expire a session which has remained idle for too long.
9518
9519 Enabling socket-level TCP keep-alives makes the system regularly send packets
9520 to the other end of the connection, leaving it active. The delay between
9521 keep-alive probes is controlled by the system only and depends both on the
9522 operating system and its tuning parameters.
9523
9524 It is important to understand that keep-alive packets are neither emitted nor
9525 received at the application level. It is only the network stacks which sees
9526 them. For this reason, even if one side of the proxy already uses keep-alives
9527 to maintain its connection alive, those keep-alive packets will not be
9528 forwarded to the other side of the proxy.
9529
9530 Please note that this has nothing to do with HTTP keep-alive.
9531
9532 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
9533 server side of a connection, which should help when session expirations are
9534 noticed between HAProxy and a server.
9535
9536 If this option has been enabled in a "defaults" section, it can be disabled
9537 in a specific instance by prepending the "no" keyword before it.
9538
9539 See also : "option clitcpka", "option tcpka"
9540
9541
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009542option ssl-hello-chk
9543 Use SSLv3 client hello health checks for server testing
9544 May be used in sections : defaults | frontend | listen | backend
9545 yes | no | yes | yes
9546 Arguments : none
9547
9548 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
9549 possible to test that the server correctly talks SSL instead of just testing
9550 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
9551 SSLv3 client hello messages are sent once the connection is established to
9552 the server, and the response is analyzed to find an SSL server hello message.
9553 The server is considered valid only when the response contains this server
9554 hello message.
9555
9556 All servers tested till there correctly reply to SSLv3 client hello messages,
9557 and most servers tested do not even log the requests containing only hello
9558 messages, which is appreciable.
9559
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009560 Note that this check works even when SSL support was not built into HAProxy
Willy Tarreau763a95b2012-10-04 23:15:39 +02009561 because it forges the SSL message. When SSL support is available, it is best
9562 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009563
Willy Tarreau763a95b2012-10-04 23:15:39 +02009564 See also: "option httpchk", "check-ssl"
9565
Willy Tarreaua453bdd2008-01-08 19:50:52 +01009566
Willy Tarreaued179852013-12-16 01:07:00 +01009567option tcp-check
9568 Perform health checks using tcp-check send/expect sequences
9569 May be used in sections: defaults | frontend | listen | backend
9570 yes | no | yes | yes
9571
9572 This health check method is intended to be combined with "tcp-check" command
9573 lists in order to support send/expect types of health check sequences.
9574
9575 TCP checks currently support 4 modes of operations :
9576 - no "tcp-check" directive : the health check only consists in a connection
9577 attempt, which remains the default mode.
9578
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009579 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01009580 used to send a string along with a connection opening. With some
9581 protocols, it helps sending a "QUIT" message for example that prevents
9582 the server from logging a connection error for each health check. The
9583 check result will still be based on the ability to open the connection
9584 only.
9585
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009586 - "tcp-check expect" only is mentioned : this is used to test a banner.
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009587 The connection is opened and HAProxy waits for the server to present some
Willy Tarreaued179852013-12-16 01:07:00 +01009588 contents which must validate some rules. The check result will be based
9589 on the matching between the contents and the rules. This is suited for
9590 POP, IMAP, SMTP, FTP, SSH, TELNET.
9591
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009592 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Davor Ocelice9ed2812017-12-25 17:49:28 +01009593 used to test a hello-type protocol. HAProxy sends a message, the server
9594 responds and its response is analyzed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009595 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01009596 suited for protocols which require a binding or a request/response model.
9597 LDAP, MySQL, Redis and SSL are example of such protocols, though they
9598 already all have their dedicated checks with a deeper understanding of
9599 the respective protocols.
9600 In this mode, many questions may be sent and many answers may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01009601 analyzed.
Willy Tarreaued179852013-12-16 01:07:00 +01009602
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02009603 A fifth mode can be used to insert comments in different steps of the script.
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009604
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02009605 For each tcp-check rule you create, you can add a "comment" directive,
9606 followed by a string. This string will be reported in the log and stderr in
9607 debug mode. It is useful to make user-friendly error reporting. The
9608 "comment" is of course optional.
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009609
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02009610 During the execution of a health check, a variable scope is made available to
9611 store data samples, using the "tcp-check set-var" operation. Freeing those
9612 variable is possible using "tcp-check unset-var".
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +01009613
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009614
Willy Tarreaued179852013-12-16 01:07:00 +01009615 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01009616 # perform a POP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01009617 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009618 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01009619
Davor Ocelice9ed2812017-12-25 17:49:28 +01009620 # perform an IMAP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01009621 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009622 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01009623
9624 # look for the redis master server after ensuring it speaks well
9625 # redis protocol, then it exits properly.
Davor Ocelice9ed2812017-12-25 17:49:28 +01009626 # (send a command then analyze the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01009627 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009628 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01009629 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02009630 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009631 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01009632 tcp-check send info\ replication\r\n
9633 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009634 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01009635 tcp-check send QUIT\r\n
9636 tcp-check expect string +OK
9637
Davor Ocelice9ed2812017-12-25 17:49:28 +01009638 forge a HTTP request, then analyze the response
Willy Tarreaued179852013-12-16 01:07:00 +01009639 (send many headers before analyzing)
9640 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009641 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01009642 tcp-check send HEAD\ /\ HTTP/1.1\r\n
9643 tcp-check send Host:\ www.mydomain.com\r\n
9644 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
9645 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02009646 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01009647
9648
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02009649 See also : "tcp-check connect", "tcp-check expect" and "tcp-check send".
Willy Tarreaued179852013-12-16 01:07:00 +01009650
9651
Willy Tarreau9ea05a72009-06-14 12:07:01 +02009652option tcp-smart-accept
9653no option tcp-smart-accept
9654 Enable or disable the saving of one ACK packet during the accept sequence
9655 May be used in sections : defaults | frontend | listen | backend
9656 yes | yes | yes | no
9657 Arguments : none
9658
9659 When an HTTP connection request comes in, the system acknowledges it on
9660 behalf of HAProxy, then the client immediately sends its request, and the
9661 system acknowledges it too while it is notifying HAProxy about the new
9662 connection. HAProxy then reads the request and responds. This means that we
9663 have one TCP ACK sent by the system for nothing, because the request could
9664 very well be acknowledged by HAProxy when it sends its response.
9665
9666 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
9667 sending this useless ACK on platforms which support it (currently at least
9668 Linux). It must not cause any problem, because the system will send it anyway
9669 after 40 ms if the response takes more time than expected to come.
9670
9671 During complex network debugging sessions, it may be desirable to disable
9672 this optimization because delayed ACKs can make troubleshooting more complex
9673 when trying to identify where packets are delayed. It is then possible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01009674 fall back to normal behavior by specifying "no option tcp-smart-accept".
Willy Tarreau9ea05a72009-06-14 12:07:01 +02009675
9676 It is also possible to force it for non-HTTP proxies by simply specifying
9677 "option tcp-smart-accept". For instance, it can make sense with some services
9678 such as SMTP where the server speaks first.
9679
9680 It is recommended to avoid forcing this option in a defaults section. In case
9681 of doubt, consider setting it back to automatic values by prepending the
9682 "default" keyword before it, or disabling it using the "no" keyword.
9683
Willy Tarreaud88edf22009-06-14 15:48:17 +02009684 See also : "option tcp-smart-connect"
9685
9686
9687option tcp-smart-connect
9688no option tcp-smart-connect
9689 Enable or disable the saving of one ACK packet during the connect sequence
9690 May be used in sections : defaults | frontend | listen | backend
9691 yes | no | yes | yes
9692 Arguments : none
9693
9694 On certain systems (at least Linux), HAProxy can ask the kernel not to
9695 immediately send an empty ACK upon a connection request, but to directly
9696 send the buffer request instead. This saves one packet on the network and
9697 thus boosts performance. It can also be useful for some servers, because they
9698 immediately get the request along with the incoming connection.
9699
9700 This feature is enabled when "option tcp-smart-connect" is set in a backend.
9701 It is not enabled by default because it makes network troubleshooting more
9702 complex.
9703
9704 It only makes sense to enable it with protocols where the client speaks first
9705 such as HTTP. In other situations, if there is no data to send in place of
9706 the ACK, a normal ACK is sent.
9707
9708 If this option has been enabled in a "defaults" section, it can be disabled
9709 in a specific instance by prepending the "no" keyword before it.
9710
9711 See also : "option tcp-smart-accept"
9712
Willy Tarreau9ea05a72009-06-14 12:07:01 +02009713
Willy Tarreaubf1f8162007-12-28 17:42:56 +01009714option tcpka
9715 Enable or disable the sending of TCP keepalive packets on both sides
9716 May be used in sections : defaults | frontend | listen | backend
9717 yes | yes | yes | yes
9718 Arguments : none
9719
9720 When there is a firewall or any session-aware component between a client and
9721 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01009722 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01009723 components decides to expire a session which has remained idle for too long.
9724
9725 Enabling socket-level TCP keep-alives makes the system regularly send packets
9726 to the other end of the connection, leaving it active. The delay between
9727 keep-alive probes is controlled by the system only and depends both on the
9728 operating system and its tuning parameters.
9729
9730 It is important to understand that keep-alive packets are neither emitted nor
9731 received at the application level. It is only the network stacks which sees
9732 them. For this reason, even if one side of the proxy already uses keep-alives
9733 to maintain its connection alive, those keep-alive packets will not be
9734 forwarded to the other side of the proxy.
9735
9736 Please note that this has nothing to do with HTTP keep-alive.
9737
9738 Using option "tcpka" enables the emission of TCP keep-alive probes on both
9739 the client and server sides of a connection. Note that this is meaningful
9740 only in "defaults" or "listen" sections. If this option is used in a
9741 frontend, only the client side will get keep-alives, and if this option is
9742 used in a backend, only the server side will get keep-alives. For this
9743 reason, it is strongly recommended to explicitly use "option clitcpka" and
9744 "option srvtcpka" when the configuration is split between frontends and
9745 backends.
9746
9747 See also : "option clitcpka", "option srvtcpka"
9748
Willy Tarreau844e3c52008-01-11 16:28:18 +01009749
9750option tcplog
9751 Enable advanced logging of TCP connections with session state and timers
9752 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01009753 yes | yes | yes | no
Willy Tarreau844e3c52008-01-11 16:28:18 +01009754 Arguments : none
9755
9756 By default, the log output format is very poor, as it only contains the
9757 source and destination addresses, and the instance name. By specifying
9758 "option tcplog", each log line turns into a much richer format including, but
9759 not limited to, the connection timers, the session status, the connections
9760 numbers, the frontend, backend and server name, and of course the source
9761 address and ports. This option is useful for pure TCP proxies in order to
9762 find which of the client or server disconnects or times out. For normal HTTP
9763 proxies, it's better to use "option httplog" which is even more complete.
9764
Guillaume de Lafond29f45602017-03-31 19:52:15 +02009765 "option tcplog" overrides any previous "log-format" directive.
9766
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009767 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009768
9769
Willy Tarreau844e3c52008-01-11 16:28:18 +01009770option transparent
9771no option transparent
9772 Enable client-side transparent proxying
9773 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01009774 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01009775 Arguments : none
9776
9777 This option was introduced in order to provide layer 7 persistence to layer 3
9778 load balancers. The idea is to use the OS's ability to redirect an incoming
9779 connection for a remote address to a local process (here HAProxy), and let
9780 this process know what address was initially requested. When this option is
9781 used, sessions without cookies will be forwarded to the original destination
9782 IP address of the incoming request (which should match that of another
9783 equipment), while requests with cookies will still be forwarded to the
9784 appropriate server.
9785
9786 Note that contrary to a common belief, this option does NOT make HAProxy
9787 present the client's IP to the server when establishing the connection.
9788
Willy Tarreaua1146052011-03-01 09:51:54 +01009789 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009790 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009791
Willy Tarreaubf1f8162007-12-28 17:42:56 +01009792
Simon Horman98637e52014-06-20 12:30:16 +09009793external-check command <command>
9794 Executable to run when performing an external-check
9795 May be used in sections : defaults | frontend | listen | backend
9796 yes | no | yes | yes
9797
9798 Arguments :
9799 <command> is the external command to run
9800
Simon Horman98637e52014-06-20 12:30:16 +09009801 The arguments passed to the to the command are:
9802
Cyril Bonté777be862014-12-02 21:21:35 +01009803 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09009804
Cyril Bonté777be862014-12-02 21:21:35 +01009805 The <proxy_address> and <proxy_port> are derived from the first listener
9806 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
9807 listener the proxy_address will be the path of the socket and the
9808 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
9809 possible to determine a listener, and both <proxy_address> and <proxy_port>
9810 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09009811
Cyril Bonté72cda2a2014-12-27 22:28:39 +01009812 Some values are also provided through environment variables.
9813
9814 Environment variables :
9815 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
9816 applicable, for example in a "backend" section).
9817
9818 HAPROXY_PROXY_ID The backend id.
9819
9820 HAPROXY_PROXY_NAME The backend name.
9821
9822 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
9823 applicable, for example in a "backend" section or
9824 for a UNIX socket).
9825
9826 HAPROXY_SERVER_ADDR The server address.
9827
9828 HAPROXY_SERVER_CURCONN The current number of connections on the server.
9829
9830 HAPROXY_SERVER_ID The server id.
9831
9832 HAPROXY_SERVER_MAXCONN The server max connections.
9833
9834 HAPROXY_SERVER_NAME The server name.
9835
9836 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
9837 socket).
9838
9839 PATH The PATH environment variable used when executing
9840 the command may be set using "external-check path".
9841
William Lallemand4d03e432019-06-14 15:35:37 +02009842 See also "2.3. Environment variables" for other variables.
9843
Simon Horman98637e52014-06-20 12:30:16 +09009844 If the command executed and exits with a zero status then the check is
9845 considered to have passed, otherwise the check is considered to have
9846 failed.
9847
9848 Example :
9849 external-check command /bin/true
9850
9851 See also : "external-check", "option external-check", "external-check path"
9852
9853
9854external-check path <path>
9855 The value of the PATH environment variable used when running an external-check
9856 May be used in sections : defaults | frontend | listen | backend
9857 yes | no | yes | yes
9858
9859 Arguments :
9860 <path> is the path used when executing external command to run
9861
9862 The default path is "".
9863
9864 Example :
9865 external-check path "/usr/bin:/bin"
9866
9867 See also : "external-check", "option external-check",
9868 "external-check command"
9869
9870
Emeric Brun647caf12009-06-30 17:57:00 +02009871persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009872persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02009873 Enable RDP cookie-based persistence
9874 May be used in sections : defaults | frontend | listen | backend
9875 yes | no | yes | yes
9876 Arguments :
9877 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02009878 default cookie name "msts" will be used. There currently is no
9879 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02009880
9881 This statement enables persistence based on an RDP cookie. The RDP cookie
9882 contains all information required to find the server in the list of known
Davor Ocelice9ed2812017-12-25 17:49:28 +01009883 servers. So when this option is set in the backend, the request is analyzed
Emeric Brun647caf12009-06-30 17:57:00 +02009884 and if an RDP cookie is found, it is decoded. If it matches a known server
9885 which is still UP (or if "option persist" is set), then the connection is
9886 forwarded to this server.
9887
9888 Note that this only makes sense in a TCP backend, but for this to work, the
9889 frontend must have waited long enough to ensure that an RDP cookie is present
9890 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009891 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02009892 a single "listen" section.
9893
Willy Tarreau61e28f22010-05-16 22:31:05 +02009894 Also, it is important to understand that the terminal server will emit this
9895 RDP cookie only if it is configured for "token redirection mode", which means
9896 that the "IP address redirection" option is disabled.
9897
Emeric Brun647caf12009-06-30 17:57:00 +02009898 Example :
9899 listen tse-farm
9900 bind :3389
9901 # wait up to 5s for an RDP cookie in the request
9902 tcp-request inspect-delay 5s
9903 tcp-request content accept if RDP_COOKIE
9904 # apply RDP cookie persistence
9905 persist rdp-cookie
9906 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02009907 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02009908 balance rdp-cookie
9909 server srv1 1.1.1.1:3389
9910 server srv2 1.1.1.2:3389
9911
Simon Hormanab814e02011-06-24 14:50:20 +09009912 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
9913 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02009914
9915
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009916rate-limit sessions <rate>
9917 Set a limit on the number of new sessions accepted per second on a frontend
9918 May be used in sections : defaults | frontend | listen | backend
9919 yes | yes | yes | no
9920 Arguments :
9921 <rate> The <rate> parameter is an integer designating the maximum number
9922 of new sessions per second to accept on the frontend.
9923
9924 When the frontend reaches the specified number of new sessions per second, it
9925 stops accepting new connections until the rate drops below the limit again.
9926 During this time, the pending sessions will be kept in the socket's backlog
Daniel Corbett9f0843f2021-05-08 10:50:37 -04009927 (in system buffers) and HAProxy will not even be aware that sessions are
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009928 pending. When applying very low limit on a highly loaded service, it may make
9929 sense to increase the socket's backlog using the "backlog" keyword.
9930
9931 This feature is particularly efficient at blocking connection-based attacks
9932 or service abuse on fragile servers. Since the session rate is measured every
9933 millisecond, it is extremely accurate. Also, the limit applies immediately,
9934 no delay is needed at all to detect the threshold.
9935
9936 Example : limit the connection rate on SMTP to 10 per second max
9937 listen smtp
9938 mode tcp
9939 bind :25
9940 rate-limit sessions 10
Panagiotis Panagiotopoulos7282d8e2016-02-11 16:37:15 +02009941 server smtp1 127.0.0.1:1025
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009942
Willy Tarreaua17c2d92011-07-25 08:16:20 +02009943 Note : when the maximum rate is reached, the frontend's status is not changed
9944 but its sockets appear as "WAITING" in the statistics if the
9945 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009946
9947 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
9948
9949
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009950redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
9951redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
9952redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009953 Return an HTTP redirection if/unless a condition is matched
9954 May be used in sections : defaults | frontend | listen | backend
9955 no | yes | yes | yes
9956
9957 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01009958 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009959
Willy Tarreau0140f252008-11-19 21:07:09 +01009960 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009961 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009962 the HTTP "Location" header. When used in an "http-request" rule,
9963 <loc> value follows the log-format rules and can include some
9964 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009965
9966 <pfx> With "redirect prefix", the "Location" header is built from the
9967 concatenation of <pfx> and the complete URI path, including the
9968 query string, unless the "drop-query" option is specified (see
9969 below). As a special case, if <pfx> equals exactly "/", then
9970 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009971 redirect to the same URL (for instance, to insert a cookie). When
9972 used in an "http-request" rule, <pfx> value follows the log-format
9973 rules and can include some dynamic values (see Custom Log Format
9974 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009975
9976 <sch> With "redirect scheme", then the "Location" header is built by
9977 concatenating <sch> with "://" then the first occurrence of the
9978 "Host" header, and then the URI path, including the query string
9979 unless the "drop-query" option is specified (see below). If no
9980 path is found or if the path is "*", then "/" is used instead. If
9981 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009982 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009983 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009984 HTTPS. When used in an "http-request" rule, <sch> value follows
9985 the log-format rules and can include some dynamic values (see
9986 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01009987
9988 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01009989 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
9990 with 302 used by default if no code is specified. 301 means
9991 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02009992 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01009993 cache the redirection. 303 is equivalent to 302 except that the
9994 browser will fetch the location with a GET method. 307 is just
9995 like 302 but makes it clear that the same method must be reused.
9996 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01009997
9998 <option> There are several options which can be specified to adjust the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009999 expected behavior of a redirection :
Willy Tarreau0140f252008-11-19 21:07:09 +010010000
10001 - "drop-query"
10002 When this keyword is used in a prefix-based redirection, then the
10003 location will be set without any possible query-string, which is useful
10004 for directing users to a non-secure page for instance. It has no effect
10005 with a location-type redirect.
10006
Willy Tarreau81e3b4f2010-01-10 00:42:19 +010010007 - "append-slash"
10008 This keyword may be used in conjunction with "drop-query" to redirect
10009 users who use a URL not ending with a '/' to the same one with the '/'.
10010 It can be useful to ensure that search engines will only see one URL.
10011 For this, a return code 301 is preferred.
10012
Willy Tarreau0140f252008-11-19 21:07:09 +010010013 - "set-cookie NAME[=value]"
10014 A "Set-Cookie" header will be added with NAME (and optionally "=value")
10015 to the response. This is sometimes used to indicate that a user has
10016 been seen, for instance to protect against some types of DoS. No other
10017 cookie option is added, so the cookie will be a session cookie. Note
10018 that for a browser, a sole cookie name without an equal sign is
10019 different from a cookie with an equal sign.
10020
10021 - "clear-cookie NAME[=]"
10022 A "Set-Cookie" header will be added with NAME (and optionally "="), but
10023 with the "Max-Age" attribute set to zero. This will tell the browser to
10024 delete this cookie. It is useful for instance on logout pages. It is
10025 important to note that clearing the cookie "NAME" will not remove a
10026 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
10027 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +020010028
10029 Example: move the login URL only to HTTPS.
10030 acl clear dst_port 80
10031 acl secure dst_port 8080
10032 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +010010033 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +010010034 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +010010035 acl cookie_set hdr_sub(cookie) SEEN=1
10036
10037 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +010010038 redirect prefix https://mysite.com if login_page !secure
10039 redirect prefix http://mysite.com drop-query if login_page !uid_given
10040 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +010010041 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +020010042
Willy Tarreau81e3b4f2010-01-10 00:42:19 +010010043 Example: send redirects for request for articles without a '/'.
10044 acl missing_slash path_reg ^/article/[^/]*$
10045 redirect code 301 prefix / drop-query append-slash if missing_slash
10046
Daniel Corbett9f0843f2021-05-08 10:50:37 -040010047 Example: redirect all HTTP traffic to HTTPS when SSL is handled by HAProxy.
David BERARDe7153042012-11-03 00:11:31 +010010048 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +020010049
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +010010050 Example: append 'www.' prefix in front of all hosts not having it
Coen Rosdorff596659b2016-04-11 11:33:49 +020010051 http-request redirect code 301 location \
10052 http://www.%[hdr(host)]%[capture.req.uri] \
10053 unless { hdr_beg(host) -i www }
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +010010054
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010055 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +020010056
Willy Tarreau303c0352008-01-17 19:01:39 +010010057
Willy Tarreaue5c5ce92008-06-20 17:27:19 +020010058retries <value>
10059 Set the number of retries to perform on a server after a connection failure
10060 May be used in sections: defaults | frontend | listen | backend
10061 yes | no | yes | yes
10062 Arguments :
10063 <value> is the number of times a connection attempt should be retried on
10064 a server when a connection either is refused or times out. The
10065 default value is 3.
10066
10067 It is important to understand that this value applies to the number of
10068 connection attempts, not full requests. When a connection has effectively
10069 been established to a server, there will be no more retry.
10070
10071 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -070010072 a turn-around timer of min("timeout connect", one second) is applied before
10073 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +020010074
10075 When "option redispatch" is set, the last retry may be performed on another
10076 server even if a cookie references a different server.
10077
10078 See also : "option redispatch"
10079
10080
Olivier Houcharda254a372019-04-05 15:30:12 +020010081retry-on [list of keywords]
Jerome Magnin5ce3c142020-05-13 20:09:57 +020010082 Specify when to attempt to automatically retry a failed request.
10083 This setting is only valid when "mode" is set to http and is silently ignored
10084 otherwise.
Olivier Houcharda254a372019-04-05 15:30:12 +020010085 May be used in sections: defaults | frontend | listen | backend
10086 yes | no | yes | yes
10087 Arguments :
10088 <keywords> is a list of keywords or HTTP status codes, each representing a
10089 type of failure event on which an attempt to retry the request
10090 is desired. Please read the notes at the bottom before changing
10091 this setting. The following keywords are supported :
10092
10093 none never retry
10094
10095 conn-failure retry when the connection or the SSL handshake failed
10096 and the request could not be sent. This is the default.
10097
10098 empty-response retry when the server connection was closed after part
10099 of the request was sent, and nothing was received from
10100 the server. This type of failure may be caused by the
10101 request timeout on the server side, poor network
10102 condition, or a server crash or restart while
10103 processing the request.
10104
Olivier Houcharde3249a92019-05-03 23:01:47 +020010105 junk-response retry when the server returned something not looking
10106 like a complete HTTP response. This includes partial
10107 responses headers as well as non-HTTP contents. It
10108 usually is a bad idea to retry on such events, which
10109 may be caused a configuration issue (wrong server port)
10110 or by the request being harmful to the server (buffer
10111 overflow attack for example).
10112
Olivier Houcharda254a372019-04-05 15:30:12 +020010113 response-timeout the server timeout stroke while waiting for the server
10114 to respond to the request. This may be caused by poor
10115 network condition, the reuse of an idle connection
10116 which has expired on the path, or by the request being
10117 extremely expensive to process. It generally is a bad
10118 idea to retry on such events on servers dealing with
10119 heavy database processing (full scans, etc) as it may
10120 amplify denial of service attacks.
10121
Olivier Houchard865d8392019-05-03 22:46:27 +020010122 0rtt-rejected retry requests which were sent over early data and were
10123 rejected by the server. These requests are generally
10124 considered to be safe to retry.
10125
Julien Pivotto2de240a2020-11-12 11:14:05 +010010126 <status> any HTTP status code among "401" (Unauthorized), "403"
10127 (Forbidden), "404" (Not Found), "408" (Request Timeout),
10128 "425" (Too Early), "500" (Server Error), "501" (Not
10129 Implemented), "502" (Bad Gateway), "503" (Service
10130 Unavailable), "504" (Gateway Timeout).
Olivier Houcharda254a372019-04-05 15:30:12 +020010131
Olivier Houchardddf0e032019-05-10 18:05:40 +020010132 all-retryable-errors
10133 retry request for any error that are considered
10134 retryable. This currently activates "conn-failure",
10135 "empty-response", "junk-response", "response-timeout",
10136 "0rtt-rejected", "500", "502", "503", and "504".
10137
Olivier Houcharda254a372019-04-05 15:30:12 +020010138 Using this directive replaces any previous settings with the new ones; it is
10139 not cumulative.
10140
10141 Please note that using anything other than "none" and "conn-failure" requires
10142 to allocate a buffer and copy the whole request into it, so it has memory and
10143 performance impacts. Requests not fitting in a single buffer will never be
10144 retried (see the global tune.bufsize setting).
10145
10146 You have to make sure the application has a replay protection mechanism built
10147 in such as a unique transaction IDs passed in requests, or that replaying the
10148 same request has no consequence, or it is very dangerous to use any retry-on
10149 value beside "conn-failure" and "none". Static file servers and caches are
10150 generally considered safe against any type of retry. Using a status code can
10151 be useful to quickly leave a server showing an abnormal behavior (out of
10152 memory, file system issues, etc), but in this case it may be a good idea to
10153 immediately redispatch the connection to another server (please see "option
10154 redispatch" for this). Last, it is important to understand that most causes
10155 of failures are the requests themselves and that retrying a request causing a
10156 server to misbehave will often make the situation even worse for this server,
10157 or for the whole service in case of redispatch.
10158
10159 Unless you know exactly how the application deals with replayed requests, you
10160 should not use this directive.
10161
10162 The default is "conn-failure".
10163
10164 See also: "retries", "option redispatch", "tune.bufsize"
10165
David du Colombier486df472011-03-17 10:40:26 +010010166server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010167 Declare a server in a backend
10168 May be used in sections : defaults | frontend | listen | backend
10169 no | no | yes | yes
10170 Arguments :
10171 <name> is the internal name assigned to this server. This name will
Davor Ocelice9ed2812017-12-25 17:49:28 +010010172 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -050010173 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010174
David du Colombier486df472011-03-17 10:40:26 +010010175 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
10176 resolvable hostname is supported, but this name will be resolved
10177 during start-up. Address "0.0.0.0" or "*" has a special meaning.
10178 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +020010179 address as the one from the client connection. This is useful in
10180 transparent proxy architectures where the client's connection is
Daniel Corbett9f0843f2021-05-08 10:50:37 -040010181 intercepted and HAProxy must forward to the original destination
Willy Tarreaud669a4f2010-07-13 14:49:50 +020010182 address. This is more or less what the "transparent" keyword does
10183 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +010010184 to report statistics. Optionally, an address family prefix may be
10185 used before the address to force the family regardless of the
10186 address format, which can be useful to specify a path to a unix
10187 socket with no slash ('/'). Currently supported prefixes are :
10188 - 'ipv4@' -> address is always IPv4
10189 - 'ipv6@' -> address is always IPv6
10190 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +020010191 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemand2fe7dd02018-09-11 16:51:29 +020010192 - 'sockpair@' -> address is the FD of a connected unix
10193 socket or of a socketpair. During a connection, the
10194 backend creates a pair of connected sockets, and passes
10195 one of them over the FD. The bind part will use the
10196 received socket as the client FD. Should be used
10197 carefully.
William Lallemandb2f07452015-05-12 14:27:13 +020010198 You may want to reference some environment variables in the
10199 address parameter, see section 2.3 about environment
Willy Tarreau6a031d12016-11-07 19:42:35 +010010200 variables. The "init-addr" setting can be used to modify the way
10201 IP addresses should be resolved upon startup.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010202
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010203 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010204 be sent to this port. If unset, the same port the client
10205 connected to will be used. The port may also be prefixed by a "+"
10206 or a "-". In this case, the server's port will be determined by
10207 adding this value to the client's port.
10208
10209 <param*> is a list of parameters for this server. The "server" keywords
10210 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010211 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010212
10213 Examples :
10214 server first 10.1.1.1:1080 cookie first check inter 1000
10215 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +010010216 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +020010217 server backup "${SRV_BACKUP}:1080" backup
10218 server www1_dc1 "${LAN_DC1}.101:80"
10219 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010220
Willy Tarreau55dcaf62015-09-27 15:03:15 +020010221 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
10222 sun_path length is used for the address length. Some other programs
10223 such as socat use the string length only by default. Pass the option
10224 ",unix-tightsocklen=0" to any abstract socket definition in socat to
10225 make it compatible with HAProxy's.
10226
Mark Lamourinec2247f02012-01-04 13:02:01 -050010227 See also: "default-server", "http-send-name-header" and section 5 about
10228 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010229
Christopher Faulet583b6de2021-02-12 09:27:10 +010010230server-state-file-name [ { use-backend-name | <file> } ]
Baptiste Assmann01c6cc32015-08-23 11:45:29 +020010231 Set the server state file to read, load and apply to servers available in
Christopher Faulet583b6de2021-02-12 09:27:10 +010010232 this backend.
10233 May be used in sections: defaults | frontend | listen | backend
10234 no | no | yes | yes
10235
10236 It only applies when the directive "load-server-state-from-file" is set to
10237 "local". When <file> is not provided, if "use-backend-name" is used or if
10238 this directive is not set, then backend name is used. If <file> starts with a
10239 slash '/', then it is considered as an absolute path. Otherwise, <file> is
10240 concatenated to the global directive "server-state-base".
Baptiste Assmann01c6cc32015-08-23 11:45:29 +020010241
10242 Example: the minimal configuration below would make HAProxy look for the
10243 state server file '/etc/haproxy/states/bk':
10244
10245 global
10246 server-state-file-base /etc/haproxy/states
10247
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010010248 backend bk
Baptiste Assmann01c6cc32015-08-23 11:45:29 +020010249 load-server-state-from-file
10250
Christopher Faulet583b6de2021-02-12 09:27:10 +010010251 See also: "server-state-base", "load-server-state-from-file", and
Baptiste Assmann01c6cc32015-08-23 11:45:29 +020010252 "show servers state"
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010253
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +020010254server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
10255 Set a template to initialize servers with shared parameters.
10256 The names of these servers are built from <prefix> and <num | range> parameters.
10257 May be used in sections : defaults | frontend | listen | backend
10258 no | no | yes | yes
10259
10260 Arguments:
10261 <prefix> A prefix for the server names to be built.
10262
10263 <num | range>
10264 If <num> is provided, this template initializes <num> servers
10265 with 1 up to <num> as server name suffixes. A range of numbers
10266 <num_low>-<num_high> may also be used to use <num_low> up to
10267 <num_high> as server name suffixes.
10268
10269 <fqdn> A FQDN for all the servers this template initializes.
10270
10271 <port> Same meaning as "server" <port> argument (see "server" keyword).
10272
10273 <params*>
10274 Remaining server parameters among all those supported by "server"
10275 keyword.
10276
10277 Examples:
10278 # Initializes 3 servers with srv1, srv2 and srv3 as names,
10279 # google.com as FQDN, and health-check enabled.
10280 server-template srv 1-3 google.com:80 check
10281
10282 # or
10283 server-template srv 3 google.com:80 check
10284
10285 # would be equivalent to:
10286 server srv1 google.com:80 check
10287 server srv2 google.com:80 check
10288 server srv3 google.com:80 check
10289
10290
10291
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010292source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020010293source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +010010294source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010295 Set the source address for outgoing connections
10296 May be used in sections : defaults | frontend | listen | backend
10297 yes | no | yes | yes
10298 Arguments :
10299 <addr> is the IPv4 address HAProxy will bind to before connecting to a
10300 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +010010301
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010302 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +010010303 the most appropriate address to reach its destination. Optionally
10304 an address family prefix may be used before the address to force
10305 the family regardless of the address format, which can be useful
10306 to specify a path to a unix socket with no slash ('/'). Currently
10307 supported prefixes are :
10308 - 'ipv4@' -> address is always IPv4
10309 - 'ipv6@' -> address is always IPv6
10310 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +020010311 - 'abns@' -> address is in abstract namespace (Linux only)
Cyril Bonté307ee1e2015-09-28 23:16:06 +020010312 You may want to reference some environment variables in the
10313 address parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010314
10315 <port> is an optional port. It is normally not needed but may be useful
10316 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020010317 the system will select a free port. Note that port ranges are not
10318 supported in the backend. If you want to force port ranges, you
10319 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010320
10321 <addr2> is the IP address to present to the server when connections are
10322 forwarded in full transparent proxy mode. This is currently only
10323 supported on some patched Linux kernels. When this address is
10324 specified, clients connecting to the server will be presented
10325 with this address, while health checks will still use the address
10326 <addr>.
10327
10328 <port2> is the optional port to present to the server when connections
10329 are forwarded in full transparent proxy mode (see <addr2> above).
10330 The default value of zero means the system will select a free
10331 port.
10332
Willy Tarreaubce70882009-09-07 11:51:47 +020010333 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
10334 This is the name of a comma-separated header list which can
10335 contain multiple IP addresses. By default, the last occurrence is
10336 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +010010337 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +020010338 by previous proxy, typically Stunnel. In order to use another
10339 occurrence from the last one, please see the <occ> parameter
10340 below. When the header (or occurrence) is not found, no binding
10341 is performed so that the proxy's default IP address is used. Also
10342 keep in mind that the header name is case insensitive, as for any
10343 HTTP header.
10344
10345 <occ> is the occurrence number of a value to be used in a multi-value
10346 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010347 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +020010348 address. Positive values indicate a position from the first
10349 occurrence, 1 being the first one. Negative values indicate
10350 positions relative to the last one, -1 being the last one. This
10351 is helpful for situations where an X-Forwarded-For header is set
10352 at the entry point of an infrastructure and must be used several
10353 proxy layers away. When this value is not specified, -1 is
10354 assumed. Passing a zero here disables the feature.
10355
Willy Tarreaud53f96b2009-02-04 18:46:54 +010010356 <name> is an optional interface name to which to bind to for outgoing
10357 traffic. On systems supporting this features (currently, only
10358 Linux), this allows one to bind all traffic to the server to
10359 this interface even if it is not the one the system would select
10360 based on routing tables. This should be used with extreme care.
10361 Note that using this option requires root privileges.
10362
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010363 The "source" keyword is useful in complex environments where a specific
10364 address only is allowed to connect to the servers. It may be needed when a
10365 private address must be used through a public gateway for instance, and it is
10366 known that the system cannot determine the adequate source address by itself.
10367
10368 An extension which is available on certain patched Linux kernels may be used
10369 through the "usesrc" optional keyword. It makes it possible to connect to the
10370 servers with an IP address which does not belong to the system itself. This
10371 is called "full transparent proxy mode". For this to work, the destination
10372 servers have to route their traffic back to this address through the machine
10373 running HAProxy, and IP forwarding must generally be enabled on this machine.
10374
10375 In this "full transparent proxy" mode, it is possible to force a specific IP
10376 address to be presented to the servers. This is not much used in fact. A more
10377 common use is to tell HAProxy to present the client's IP address. For this,
10378 there are two methods :
10379
10380 - present the client's IP and port addresses. This is the most transparent
10381 mode, but it can cause problems when IP connection tracking is enabled on
10382 the machine, because a same connection may be seen twice with different
10383 states. However, this solution presents the huge advantage of not
10384 limiting the system to the 64k outgoing address+port couples, because all
10385 of the client ranges may be used.
10386
10387 - present only the client's IP address and select a spare port. This
10388 solution is still quite elegant but slightly less transparent (downstream
10389 firewalls logs will not match upstream's). It also presents the downside
10390 of limiting the number of concurrent connections to the usual 64k ports.
10391 However, since the upstream and downstream ports are different, local IP
10392 connection tracking on the machine will not be upset by the reuse of the
10393 same session.
10394
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010395 This option sets the default source for all servers in the backend. It may
10396 also be specified in a "defaults" section. Finer source address specification
10397 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010398 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010399
Baptiste Assmann91bd3372015-07-17 21:59:42 +020010400 In order to work, "usesrc" requires root privileges.
10401
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010402 Examples :
10403 backend private
10404 # Connect to the servers using our 192.168.1.200 source address
10405 source 192.168.1.200
10406
10407 backend transparent_ssl1
10408 # Connect to the SSL farm from the client's source address
10409 source 192.168.1.200 usesrc clientip
10410
10411 backend transparent_ssl2
10412 # Connect to the SSL farm from the client's source address and port
10413 # not recommended if IP conntrack is present on the local machine.
10414 source 192.168.1.200 usesrc client
10415
10416 backend transparent_ssl3
10417 # Connect to the SSL farm from the client's source address. It
10418 # is more conntrack-friendly.
10419 source 192.168.1.200 usesrc clientip
10420
10421 backend transparent_smtp
10422 # Connect to the SMTP farm from the client's source address/port
10423 # with Tproxy version 4.
10424 source 0.0.0.0 usesrc clientip
10425
Willy Tarreaubce70882009-09-07 11:51:47 +020010426 backend transparent_http
10427 # Connect to the servers using the client's IP as seen by previous
10428 # proxy.
10429 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
10430
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010431 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010432 the Linux kernel on www.balabit.com, the "bind" keyword.
10433
Willy Tarreau844e3c52008-01-11 16:28:18 +010010434
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +090010435srvtcpka-cnt <count>
10436 Sets the maximum number of keepalive probes TCP should send before dropping
10437 the connection on the server side.
10438 May be used in sections : defaults | frontend | listen | backend
10439 yes | no | yes | yes
10440 Arguments :
10441 <count> is the maximum number of keepalive probes.
10442
10443 This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword
10444 is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used.
Willy Tarreau52543212020-07-09 05:58:51 +020010445 The availability of this setting depends on the operating system. It is
10446 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +090010447
10448 See also : "option srvtcpka", "srvtcpka-idle", "srvtcpka-intvl".
10449
10450
10451srvtcpka-idle <timeout>
10452 Sets the time the connection needs to remain idle before TCP starts sending
10453 keepalive probes, if enabled the sending of TCP keepalive packets on the
10454 server side.
10455 May be used in sections : defaults | frontend | listen | backend
10456 yes | no | yes | yes
10457 Arguments :
10458 <timeout> is the time the connection needs to remain idle before TCP starts
10459 sending keepalive probes. It is specified in seconds by default,
10460 but can be in any other unit if the number is suffixed by the
10461 unit, as explained at the top of this document.
10462
10463 This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword
10464 is not specified, system-wide TCP parameter (tcp_keepalive_time) is used.
Willy Tarreau52543212020-07-09 05:58:51 +020010465 The availability of this setting depends on the operating system. It is
10466 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +090010467
10468 See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-intvl".
10469
10470
10471srvtcpka-intvl <timeout>
10472 Sets the time between individual keepalive probes on the server side.
10473 May be used in sections : defaults | frontend | listen | backend
10474 yes | no | yes | yes
10475 Arguments :
10476 <timeout> is the time between individual keepalive probes. It is specified
10477 in seconds by default, but can be in any other unit if the number
10478 is suffixed by the unit, as explained at the top of this
10479 document.
10480
10481 This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword
10482 is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used.
Willy Tarreau52543212020-07-09 05:58:51 +020010483 The availability of this setting depends on the operating system. It is
10484 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +090010485
10486 See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-idle".
10487
10488
Cyril Bonté66c327d2010-10-12 00:14:37 +020010489stats admin { if | unless } <cond>
10490 Enable statistics admin level if/unless a condition is matched
10491 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010492 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +020010493
10494 This statement enables the statistics admin level if/unless a condition is
10495 matched.
10496
10497 The admin level allows to enable/disable servers from the web interface. By
10498 default, statistics page is read-only for security reasons.
10499
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010500 Note : Consider not using this feature in multi-process mode (nbproc > 1)
10501 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010010502 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010503
Cyril Bonté23b39d92011-02-10 22:54:44 +010010504 Currently, the POST request is limited to the buffer size minus the reserved
10505 buffer space, which means that if the list of servers is too long, the
10506 request won't be processed. It is recommended to alter few servers at a
10507 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +020010508
10509 Example :
10510 # statistics admin level only for localhost
10511 backend stats_localhost
10512 stats enable
10513 stats admin if LOCALHOST
10514
10515 Example :
10516 # statistics admin level always enabled because of the authentication
10517 backend stats_auth
10518 stats enable
10519 stats auth admin:AdMiN123
10520 stats admin if TRUE
10521
10522 Example :
10523 # statistics admin level depends on the authenticated user
10524 userlist stats-auth
10525 group admin users admin
10526 user admin insecure-password AdMiN123
10527 group readonly users haproxy
10528 user haproxy insecure-password haproxy
10529
10530 backend stats_auth
10531 stats enable
10532 acl AUTH http_auth(stats-auth)
10533 acl AUTH_ADMIN http_auth_group(stats-auth) admin
10534 stats http-request auth unless AUTH
10535 stats admin if AUTH_ADMIN
10536
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010537 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
10538 "bind-process", section 3.4 about userlists and section 7 about
10539 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +020010540
10541
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010542stats auth <user>:<passwd>
10543 Enable statistics with authentication and grant access to an account
10544 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010545 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010546 Arguments :
10547 <user> is a user name to grant access to
10548
10549 <passwd> is the cleartext password associated to this user
10550
10551 This statement enables statistics with default settings, and restricts access
10552 to declared users only. It may be repeated as many times as necessary to
10553 allow as many users as desired. When a user tries to access the statistics
10554 without a valid account, a "401 Forbidden" response will be returned so that
10555 the browser asks the user to provide a valid user and password. The real
10556 which will be returned to the browser is configurable using "stats realm".
10557
10558 Since the authentication method is HTTP Basic Authentication, the passwords
10559 circulate in cleartext on the network. Thus, it was decided that the
10560 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020010561 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010562
10563 It is also possible to reduce the scope of the proxies which appear in the
10564 report using "stats scope".
10565
10566 Though this statement alone is enough to enable statistics reporting, it is
10567 recommended to set all other settings in order to avoid relying on default
10568 unobvious parameters.
10569
10570 Example :
10571 # public access (limited to this backend only)
10572 backend public_www
10573 server srv1 192.168.0.1:80
10574 stats enable
10575 stats hide-version
10576 stats scope .
10577 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010578 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010579 stats auth admin1:AdMiN123
10580 stats auth admin2:AdMiN321
10581
10582 # internal monitoring access (unlimited)
10583 backend private_monitoring
10584 stats enable
10585 stats uri /admin?stats
10586 stats refresh 5s
10587
10588 See also : "stats enable", "stats realm", "stats scope", "stats uri"
10589
10590
10591stats enable
10592 Enable statistics reporting with default settings
10593 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010594 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010595 Arguments : none
10596
10597 This statement enables statistics reporting with default settings defined
10598 at build time. Unless stated otherwise, these settings are used :
10599 - stats uri : /haproxy?stats
10600 - stats realm : "HAProxy Statistics"
10601 - stats auth : no authentication
10602 - stats scope : no restriction
10603
10604 Though this statement alone is enough to enable statistics reporting, it is
10605 recommended to set all other settings in order to avoid relying on default
10606 unobvious parameters.
10607
10608 Example :
10609 # public access (limited to this backend only)
10610 backend public_www
10611 server srv1 192.168.0.1:80
10612 stats enable
10613 stats hide-version
10614 stats scope .
10615 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010616 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010617 stats auth admin1:AdMiN123
10618 stats auth admin2:AdMiN321
10619
10620 # internal monitoring access (unlimited)
10621 backend private_monitoring
10622 stats enable
10623 stats uri /admin?stats
10624 stats refresh 5s
10625
10626 See also : "stats auth", "stats realm", "stats uri"
10627
10628
Willy Tarreaud63335a2010-02-26 12:56:52 +010010629stats hide-version
10630 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +020010631 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010632 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +010010633 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +020010634
Willy Tarreaud63335a2010-02-26 12:56:52 +010010635 By default, the stats page reports some useful status information along with
10636 the statistics. Among them is HAProxy's version. However, it is generally
10637 considered dangerous to report precise version to anyone, as it can help them
10638 target known weaknesses with specific attacks. The "stats hide-version"
10639 statement removes the version from the statistics report. This is recommended
10640 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +020010641
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +020010642 Though this statement alone is enough to enable statistics reporting, it is
10643 recommended to set all other settings in order to avoid relying on default
10644 unobvious parameters.
10645
Willy Tarreaud63335a2010-02-26 12:56:52 +010010646 Example :
10647 # public access (limited to this backend only)
10648 backend public_www
10649 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +020010650 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +010010651 stats hide-version
10652 stats scope .
10653 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010654 stats realm HAProxy\ Statistics
Willy Tarreaud63335a2010-02-26 12:56:52 +010010655 stats auth admin1:AdMiN123
10656 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +020010657
Willy Tarreau1d45b7c2009-08-16 10:29:18 +020010658 # internal monitoring access (unlimited)
10659 backend private_monitoring
10660 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +010010661 stats uri /admin?stats
10662 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +010010663
Willy Tarreaud63335a2010-02-26 12:56:52 +010010664 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +020010665
Willy Tarreau983e01e2010-01-11 18:42:06 +010010666
Cyril Bonté2be1b3f2010-09-30 23:46:30 +020010667stats http-request { allow | deny | auth [realm <realm>] }
10668 [ { if | unless } <condition> ]
10669 Access control for statistics
10670
10671 May be used in sections: defaults | frontend | listen | backend
10672 no | no | yes | yes
10673
10674 As "http-request", these set of options allow to fine control access to
10675 statistics. Each option may be followed by if/unless and acl.
10676 First option with matched condition (or option without condition) is final.
10677 For "deny" a 403 error will be returned, for "allow" normal processing is
10678 performed, for "auth" a 401/407 error code is returned so the client
10679 should be asked to enter a username and password.
10680
10681 There is no fixed limit to the number of http-request statements per
10682 instance.
10683
10684 See also : "http-request", section 3.4 about userlists and section 7
10685 about ACL usage.
10686
10687
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010688stats realm <realm>
10689 Enable statistics and set authentication realm
10690 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010691 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010692 Arguments :
10693 <realm> is the name of the HTTP Basic Authentication realm reported to
10694 the browser. The browser uses it to display it in the pop-up
10695 inviting the user to enter a valid username and password.
10696
10697 The realm is read as a single word, so any spaces in it should be escaped
10698 using a backslash ('\').
10699
10700 This statement is useful only in conjunction with "stats auth" since it is
10701 only related to authentication.
10702
10703 Though this statement alone is enough to enable statistics reporting, it is
10704 recommended to set all other settings in order to avoid relying on default
10705 unobvious parameters.
10706
10707 Example :
10708 # public access (limited to this backend only)
10709 backend public_www
10710 server srv1 192.168.0.1:80
10711 stats enable
10712 stats hide-version
10713 stats scope .
10714 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010715 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010716 stats auth admin1:AdMiN123
10717 stats auth admin2:AdMiN321
10718
10719 # internal monitoring access (unlimited)
10720 backend private_monitoring
10721 stats enable
10722 stats uri /admin?stats
10723 stats refresh 5s
10724
10725 See also : "stats auth", "stats enable", "stats uri"
10726
10727
10728stats refresh <delay>
10729 Enable statistics with automatic refresh
10730 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010731 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010732 Arguments :
10733 <delay> is the suggested refresh delay, specified in seconds, which will
10734 be returned to the browser consulting the report page. While the
10735 browser is free to apply any delay, it will generally respect it
10736 and refresh the page this every seconds. The refresh interval may
10737 be specified in any other non-default time unit, by suffixing the
10738 unit after the value, as explained at the top of this document.
10739
10740 This statement is useful on monitoring displays with a permanent page
10741 reporting the load balancer's activity. When set, the HTML report page will
10742 include a link "refresh"/"stop refresh" so that the user can select whether
Jackie Tapia749f74c2020-07-22 18:59:40 -050010743 they want automatic refresh of the page or not.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010744
10745 Though this statement alone is enough to enable statistics reporting, it is
10746 recommended to set all other settings in order to avoid relying on default
10747 unobvious parameters.
10748
10749 Example :
10750 # public access (limited to this backend only)
10751 backend public_www
10752 server srv1 192.168.0.1:80
10753 stats enable
10754 stats hide-version
10755 stats scope .
10756 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010757 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010758 stats auth admin1:AdMiN123
10759 stats auth admin2:AdMiN321
10760
10761 # internal monitoring access (unlimited)
10762 backend private_monitoring
10763 stats enable
10764 stats uri /admin?stats
10765 stats refresh 5s
10766
10767 See also : "stats auth", "stats enable", "stats realm", "stats uri"
10768
10769
10770stats scope { <name> | "." }
10771 Enable statistics and limit access scope
10772 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010773 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010774 Arguments :
10775 <name> is the name of a listen, frontend or backend section to be
10776 reported. The special name "." (a single dot) designates the
10777 section in which the statement appears.
10778
10779 When this statement is specified, only the sections enumerated with this
10780 statement will appear in the report. All other ones will be hidden. This
10781 statement may appear as many times as needed if multiple sections need to be
10782 reported. Please note that the name checking is performed as simple string
10783 comparisons, and that it is never checked that a give section name really
10784 exists.
10785
10786 Though this statement alone is enough to enable statistics reporting, it is
10787 recommended to set all other settings in order to avoid relying on default
10788 unobvious parameters.
10789
10790 Example :
10791 # public access (limited to this backend only)
10792 backend public_www
10793 server srv1 192.168.0.1:80
10794 stats enable
10795 stats hide-version
10796 stats scope .
10797 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010798 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010799 stats auth admin1:AdMiN123
10800 stats auth admin2:AdMiN321
10801
10802 # internal monitoring access (unlimited)
10803 backend private_monitoring
10804 stats enable
10805 stats uri /admin?stats
10806 stats refresh 5s
10807
10808 See also : "stats auth", "stats enable", "stats realm", "stats uri"
10809
Willy Tarreaud63335a2010-02-26 12:56:52 +010010810
Willy Tarreauc9705a12010-07-27 20:05:50 +020010811stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +010010812 Enable reporting of a description on the statistics page.
10813 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010814 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +010010815
Willy Tarreauc9705a12010-07-27 20:05:50 +020010816 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +010010817 description from global section is automatically used instead.
10818
10819 This statement is useful for users that offer shared services to their
10820 customers, where node or description should be different for each customer.
10821
10822 Though this statement alone is enough to enable statistics reporting, it is
10823 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +010010824 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010825
10826 Example :
10827 # internal monitoring access (unlimited)
10828 backend private_monitoring
10829 stats enable
10830 stats show-desc Master node for Europe, Asia, Africa
10831 stats uri /admin?stats
10832 stats refresh 5s
10833
10834 See also: "show-node", "stats enable", "stats uri" and "description" in
10835 global section.
10836
10837
10838stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +020010839 Enable reporting additional information on the statistics page
10840 May be used in sections : defaults | frontend | listen | backend
10841 yes | yes | yes | yes
10842 Arguments : none
10843
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010844 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +010010845 - cap: capabilities (proxy)
10846 - mode: one of tcp, http or health (proxy)
10847 - id: SNMP ID (proxy, socket, server)
10848 - IP (socket, server)
10849 - cookie (backend, server)
10850
10851 Though this statement alone is enough to enable statistics reporting, it is
10852 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +010010853 unobvious parameters. Default behavior is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010854
10855 See also: "stats enable", "stats uri".
10856
10857
Amaury Denoyelle0b70a8a2020-10-05 11:49:45 +020010858stats show-modules
10859 Enable display of extra statistics module on the statistics page
10860 May be used in sections : defaults | frontend | listen | backend
10861 yes | yes | yes | yes
10862 Arguments : none
10863
10864 New columns are added at the end of the line containing the extra statistics
10865 values as a tooltip.
10866
10867 Though this statement alone is enough to enable statistics reporting, it is
10868 recommended to set all other settings in order to avoid relying on default
10869 unobvious parameters. Default behavior is not to show this information.
10870
10871 See also: "stats enable", "stats uri".
10872
10873
Willy Tarreaud63335a2010-02-26 12:56:52 +010010874stats show-node [ <name> ]
10875 Enable reporting of a host name on the statistics page.
10876 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010877 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +010010878 Arguments:
10879 <name> is an optional name to be reported. If unspecified, the
10880 node name from global section is automatically used instead.
10881
10882 This statement is useful for users that offer shared services to their
10883 customers, where node or description might be different on a stats page
Davor Ocelice9ed2812017-12-25 17:49:28 +010010884 provided for each customer. Default behavior is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010885
10886 Though this statement alone is enough to enable statistics reporting, it is
10887 recommended to set all other settings in order to avoid relying on default
10888 unobvious parameters.
10889
10890 Example:
10891 # internal monitoring access (unlimited)
10892 backend private_monitoring
10893 stats enable
10894 stats show-node Europe-1
10895 stats uri /admin?stats
10896 stats refresh 5s
10897
10898 See also: "show-desc", "stats enable", "stats uri", and "node" in global
10899 section.
10900
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010901
10902stats uri <prefix>
10903 Enable statistics and define the URI prefix to access them
10904 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010905 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010906 Arguments :
10907 <prefix> is the prefix of any URI which will be redirected to stats. This
10908 prefix may contain a question mark ('?') to indicate part of a
10909 query string.
10910
10911 The statistics URI is intercepted on the relayed traffic, so it appears as a
10912 page within the normal application. It is strongly advised to ensure that the
10913 selected URI will never appear in the application, otherwise it will never be
10914 possible to reach it in the application.
10915
Daniel Corbett9f0843f2021-05-08 10:50:37 -040010916 The default URI compiled in HAProxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010917 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010918 It is generally a good idea to include a question mark in the URI so that
10919 intermediate proxies refrain from caching the results. Also, since any string
10920 beginning with the prefix will be accepted as a stats request, the question
10921 mark helps ensuring that no valid URI will begin with the same words.
10922
10923 It is sometimes very convenient to use "/" as the URI prefix, and put that
10924 statement in a "listen" instance of its own. That makes it easy to dedicate
10925 an address or a port to statistics only.
10926
10927 Though this statement alone is enough to enable statistics reporting, it is
10928 recommended to set all other settings in order to avoid relying on default
10929 unobvious parameters.
10930
10931 Example :
10932 # public access (limited to this backend only)
10933 backend public_www
10934 server srv1 192.168.0.1:80
10935 stats enable
10936 stats hide-version
10937 stats scope .
10938 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010939 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010940 stats auth admin1:AdMiN123
10941 stats auth admin2:AdMiN321
10942
10943 # internal monitoring access (unlimited)
10944 backend private_monitoring
10945 stats enable
10946 stats uri /admin?stats
10947 stats refresh 5s
10948
10949 See also : "stats auth", "stats enable", "stats realm"
10950
10951
Willy Tarreaud63335a2010-02-26 12:56:52 +010010952stick match <pattern> [table <table>] [{if | unless} <cond>]
10953 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010954 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +010010955 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010956
10957 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020010958 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010959 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +010010960 will be analyzed in the hope to find a matching entry in a
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010961 stickiness table. This rule is mandatory.
10962
10963 <table> is an optional stickiness table name. If unspecified, the same
10964 backend's table is used. A stickiness table is declared using
10965 the "stick-table" statement.
10966
10967 <cond> is an optional matching condition. It makes it possible to match
10968 on a certain criterion only when other conditions are met (or
10969 not met). For instance, it could be used to match on a source IP
10970 address except when a request passes through a known proxy, in
10971 which case we'd match on a header containing that IP address.
10972
10973 Some protocols or applications require complex stickiness rules and cannot
10974 always simply rely on cookies nor hashing. The "stick match" statement
10975 describes a rule to extract the stickiness criterion from an incoming request
10976 or connection. See section 7 for a complete list of possible patterns and
10977 transformation rules.
10978
10979 The table has to be declared using the "stick-table" statement. It must be of
10980 a type compatible with the pattern. By default it is the one which is present
10981 in the same backend. It is possible to share a table with other backends by
10982 referencing it using the "table" keyword. If another table is referenced,
10983 the server's ID inside the backends are used. By default, all server IDs
10984 start at 1 in each backend, so the server ordering is enough. But in case of
10985 doubt, it is highly recommended to force server IDs using their "id" setting.
10986
10987 It is possible to restrict the conditions where a "stick match" statement
10988 will apply, using "if" or "unless" followed by a condition. See section 7 for
10989 ACL based conditions.
10990
10991 There is no limit on the number of "stick match" statements. The first that
10992 applies and matches will cause the request to be directed to the same server
10993 as was used for the request which created the entry. That way, multiple
10994 matches can be used as fallbacks.
10995
10996 The stick rules are checked after the persistence cookies, so they will not
10997 affect stickiness if a cookie has already been used to select a server. That
10998 way, it becomes very easy to insert cookies and match on IP addresses in
10999 order to maintain stickiness between HTTP and HTTPS.
11000
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011001 Note : Consider not using this feature in multi-process mode (nbproc > 1)
11002 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011003 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011004
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011005 Example :
11006 # forward SMTP users to the same server they just used for POP in the
11007 # last 30 minutes
11008 backend pop
11009 mode tcp
11010 balance roundrobin
11011 stick store-request src
11012 stick-table type ip size 200k expire 30m
11013 server s1 192.168.1.1:110
11014 server s2 192.168.1.1:110
11015
11016 backend smtp
11017 mode tcp
11018 balance roundrobin
11019 stick match src table pop
11020 server s1 192.168.1.1:25
11021 server s2 192.168.1.1:25
11022
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011023 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +020011024 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011025
11026
11027stick on <pattern> [table <table>] [{if | unless} <condition>]
11028 Define a request pattern to associate a user to a server
11029 May be used in sections : defaults | frontend | listen | backend
11030 no | no | yes | yes
11031
11032 Note : This form is exactly equivalent to "stick match" followed by
11033 "stick store-request", all with the same arguments. Please refer
11034 to both keywords for details. It is only provided as a convenience
11035 for writing more maintainable configurations.
11036
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011037 Note : Consider not using this feature in multi-process mode (nbproc > 1)
11038 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011039 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011040
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011041 Examples :
11042 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +010011043 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011044
11045 # ...is strictly equivalent to this one :
11046 stick match src table pop if !localhost
11047 stick store-request src table pop if !localhost
11048
11049
11050 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
11051 # well as HTTP without cookie. Share the same table between both accesses.
11052 backend http
11053 mode http
11054 balance roundrobin
11055 stick on src table https
11056 cookie SRV insert indirect nocache
11057 server s1 192.168.1.1:80 cookie s1
11058 server s2 192.168.1.1:80 cookie s2
11059
11060 backend https
11061 mode tcp
11062 balance roundrobin
11063 stick-table type ip size 200k expire 30m
11064 stick on src
11065 server s1 192.168.1.1:443
11066 server s2 192.168.1.1:443
11067
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011068 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011069
11070
11071stick store-request <pattern> [table <table>] [{if | unless} <condition>]
11072 Define a request pattern used to create an entry in a stickiness table
11073 May be used in sections : defaults | frontend | listen | backend
11074 no | no | yes | yes
11075
11076 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020011077 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011078 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +010011079 will be analyzed, extracted and stored in the table once a
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011080 server is selected.
11081
11082 <table> is an optional stickiness table name. If unspecified, the same
11083 backend's table is used. A stickiness table is declared using
11084 the "stick-table" statement.
11085
11086 <cond> is an optional storage condition. It makes it possible to store
11087 certain criteria only when some conditions are met (or not met).
11088 For instance, it could be used to store the source IP address
11089 except when the request passes through a known proxy, in which
11090 case we'd store a converted form of a header containing that IP
11091 address.
11092
11093 Some protocols or applications require complex stickiness rules and cannot
11094 always simply rely on cookies nor hashing. The "stick store-request" statement
11095 describes a rule to decide what to extract from the request and when to do
11096 it, in order to store it into a stickiness table for further requests to
11097 match it using the "stick match" statement. Obviously the extracted part must
11098 make sense and have a chance to be matched in a further request. Storing a
11099 client's IP address for instance often makes sense. Storing an ID found in a
11100 URL parameter also makes sense. Storing a source port will almost never make
11101 any sense because it will be randomly matched. See section 7 for a complete
11102 list of possible patterns and transformation rules.
11103
11104 The table has to be declared using the "stick-table" statement. It must be of
11105 a type compatible with the pattern. By default it is the one which is present
11106 in the same backend. It is possible to share a table with other backends by
11107 referencing it using the "table" keyword. If another table is referenced,
11108 the server's ID inside the backends are used. By default, all server IDs
11109 start at 1 in each backend, so the server ordering is enough. But in case of
11110 doubt, it is highly recommended to force server IDs using their "id" setting.
11111
11112 It is possible to restrict the conditions where a "stick store-request"
11113 statement will apply, using "if" or "unless" followed by a condition. This
11114 condition will be evaluated while parsing the request, so any criteria can be
11115 used. See section 7 for ACL based conditions.
11116
11117 There is no limit on the number of "stick store-request" statements, but
11118 there is a limit of 8 simultaneous stores per request or response. This
11119 makes it possible to store up to 8 criteria, all extracted from either the
11120 request or the response, regardless of the number of rules. Only the 8 first
11121 ones which match will be kept. Using this, it is possible to feed multiple
11122 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +010011123 another protocol or access method. Using multiple store-request rules with
11124 the same table is possible and may be used to find the best criterion to rely
11125 on, by arranging the rules by decreasing preference order. Only the first
11126 extracted criterion for a given table will be stored. All subsequent store-
11127 request rules referencing the same table will be skipped and their ACLs will
11128 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011129
11130 The "store-request" rules are evaluated once the server connection has been
11131 established, so that the table will contain the real server that processed
11132 the request.
11133
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011134 Note : Consider not using this feature in multi-process mode (nbproc > 1)
11135 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011136 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011137
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011138 Example :
11139 # forward SMTP users to the same server they just used for POP in the
11140 # last 30 minutes
11141 backend pop
11142 mode tcp
11143 balance roundrobin
11144 stick store-request src
11145 stick-table type ip size 200k expire 30m
11146 server s1 192.168.1.1:110
11147 server s2 192.168.1.1:110
11148
11149 backend smtp
11150 mode tcp
11151 balance roundrobin
11152 stick match src table pop
11153 server s1 192.168.1.1:25
11154 server s2 192.168.1.1:25
11155
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011156 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +020011157 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011158
11159
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011160stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Thayne McCombs92149f92020-11-20 01:28:26 -070011161 size <size> [expire <expire>] [nopurge] [peers <peersect>] [srvkey <srvkey>]
Emeric Brunf099e792010-09-27 12:05:28 +020011162 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +080011163 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011164 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +020011165 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011166
11167 Arguments :
11168 ip a table declared with "type ip" will only store IPv4 addresses.
11169 This form is very compact (about 50 bytes per entry) and allows
11170 very fast entry lookup and stores with almost no overhead. This
11171 is mainly used to store client source IP addresses.
11172
David du Colombier9a6d3c92011-03-17 10:40:24 +010011173 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
11174 This form is very compact (about 60 bytes per entry) and allows
11175 very fast entry lookup and stores with almost no overhead. This
11176 is mainly used to store client source IP addresses.
11177
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011178 integer a table declared with "type integer" will store 32bit integers
11179 which can represent a client identifier found in a request for
11180 instance.
11181
11182 string a table declared with "type string" will store substrings of up
11183 to <len> characters. If the string provided by the pattern
11184 extractor is larger than <len>, it will be truncated before
11185 being stored. During matching, at most <len> characters will be
11186 compared between the string in the table and the extracted
11187 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011188 to 32 characters.
11189
11190 binary a table declared with "type binary" will store binary blocks
11191 of <len> bytes. If the block provided by the pattern
11192 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +020011193 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011194 is shorter than <len>, it will be padded by 0. When not
11195 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011196
11197 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011198 "string" type table (See type "string" above). Or the number
11199 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011200 changing this parameter as memory usage will proportionally
11201 increase.
11202
11203 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +010011204 value directly impacts memory usage. Count approximately
11205 50 bytes per entry, plus the size of a string if any. The size
11206 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011207
11208 [nopurge] indicates that we refuse to purge older entries when the table
Daniel Corbett9f0843f2021-05-08 10:50:37 -040011209 is full. When not specified and the table is full when HAProxy
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011210 wants to store an entry in it, it will flush a few of the oldest
11211 entries in order to release some space for the new ones. This is
Davor Ocelice9ed2812017-12-25 17:49:28 +010011212 most often the desired behavior. In some specific cases, it
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011213 be desirable to refuse new entries instead of purging the older
11214 ones. That may be the case when the amount of data to store is
11215 far above the hardware limits and we prefer not to offer access
11216 to new clients than to reject the ones already connected. When
11217 using this parameter, be sure to properly set the "expire"
11218 parameter (see below).
11219
Emeric Brunf099e792010-09-27 12:05:28 +020011220 <peersect> is the name of the peers section to use for replication. Entries
11221 which associate keys to server IDs are kept synchronized with
11222 the remote peers declared in this section. All entries are also
11223 automatically learned from the local peer (old process) during a
11224 soft restart.
11225
Willy Tarreau1abc6732015-05-01 19:21:02 +020011226 NOTE : each peers section may be referenced only by tables
11227 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010011228
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011229 <expire> defines the maximum duration of an entry in the table since it
11230 was last created, refreshed or matched. The expiration delay is
11231 defined using the standard time format, similarly as the various
11232 timeouts. The maximum duration is slightly above 24 days. See
Willy Tarreau4b103022021-02-12 17:59:10 +010011233 section 2.5 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +020011234 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011235 be removed once full. Be sure not to use the "nopurge" parameter
11236 if not expiration delay is specified.
11237
Thayne McCombs92149f92020-11-20 01:28:26 -070011238 <srvkey> specifies how each server is identified for the purposes of the
11239 stick table. The valid values are "name" and "addr". If "name" is
11240 given, then <name> argument for the server (may be generated by
11241 a template). If "addr" is given, then the server is identified
11242 by its current network address, including the port. "addr" is
11243 especially useful if you are using service discovery to generate
11244 the addresses for servers with peered stick-tables and want
11245 to consistently use the same host across peers for a stickiness
11246 token.
11247
Willy Tarreau08d5f982010-06-06 13:34:54 +020011248 <data_type> is used to store additional information in the stick-table. This
11249 may be used by ACLs in order to control various criteria related
11250 to the activity of the client matching the stick-table. For each
11251 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +020011252 that the additional data can fit. Several data types may be
11253 stored with an entry. Multiple data types may be specified after
11254 the "store" keyword, as a comma-separated list. Alternatively,
11255 it is possible to repeat the "store" keyword followed by one or
11256 several data types. Except for the "server_id" type which is
11257 automatically detected and enabled, all data types must be
11258 explicitly declared to be stored. If an ACL references a data
11259 type which is not stored, the ACL will simply not match. Some
11260 data types require an argument which must be passed just after
11261 the type between parenthesis. See below for the supported data
11262 types and their arguments.
11263
11264 The data types that can be stored with an entry are the following :
11265 - server_id : this is an integer which holds the numeric ID of the server a
11266 request was assigned to. It is used by the "stick match", "stick store",
11267 and "stick on" rules. It is automatically enabled when referenced.
11268
11269 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
11270 integer which may be used for anything. Most of the time it will be used
11271 to put a special tag on some entries, for instance to note that a
Davor Ocelice9ed2812017-12-25 17:49:28 +010011272 specific behavior was detected and must be known for future matches.
Willy Tarreauc9705a12010-07-27 20:05:50 +020011273
Willy Tarreauba2ffd12013-05-29 15:54:14 +020011274 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
11275 over a period. It is a positive 32-bit integer integer which may be used
11276 for anything. Just like <gpc0>, it counts events, but instead of keeping
Davor Ocelice9ed2812017-12-25 17:49:28 +010011277 a cumulative number, it maintains the rate at which the counter is
Willy Tarreauba2ffd12013-05-29 15:54:14 +020011278 incremented. Most of the time it will be used to measure the frequency of
Davor Ocelice9ed2812017-12-25 17:49:28 +010011279 occurrence of certain events (e.g. requests to a specific URL).
Willy Tarreauba2ffd12013-05-29 15:54:14 +020011280
Frédéric Lécaille6778b272018-01-29 15:22:53 +010011281 - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
11282 integer which may be used for anything. Most of the time it will be used
11283 to put a special tag on some entries, for instance to note that a
11284 specific behavior was detected and must be known for future matches.
11285
11286 - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
11287 over a period. It is a positive 32-bit integer integer which may be used
11288 for anything. Just like <gpc1>, it counts events, but instead of keeping
11289 a cumulative number, it maintains the rate at which the counter is
11290 incremented. Most of the time it will be used to measure the frequency of
11291 occurrence of certain events (e.g. requests to a specific URL).
11292
Willy Tarreauc9705a12010-07-27 20:05:50 +020011293 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
11294 the absolute number of connections received from clients which matched
11295 this entry. It does not mean the connections were accepted, just that
11296 they were received.
11297
11298 - conn_cur : Current Connections. It is a positive 32-bit integer which
11299 stores the concurrent connection counts for the entry. It is incremented
11300 once an incoming connection matches the entry, and decremented once the
11301 connection leaves. That way it is possible to know at any time the exact
11302 number of concurrent connections for an entry.
11303
11304 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
11305 integer parameter <period> which indicates in milliseconds the length
11306 of the period over which the average is measured. It reports the average
11307 incoming connection rate over that period, in connections per period. The
11308 result is an integer which can be matched using ACLs.
11309
11310 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
11311 the absolute number of sessions received from clients which matched this
11312 entry. A session is a connection that was accepted by the layer 4 rules.
11313
11314 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
11315 integer parameter <period> which indicates in milliseconds the length
11316 of the period over which the average is measured. It reports the average
11317 incoming session rate over that period, in sessions per period. The
11318 result is an integer which can be matched using ACLs.
11319
11320 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
11321 counts the absolute number of HTTP requests received from clients which
11322 matched this entry. It does not matter whether they are valid requests or
11323 not. Note that this is different from sessions when keep-alive is used on
11324 the client side.
11325
11326 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
11327 integer parameter <period> which indicates in milliseconds the length
11328 of the period over which the average is measured. It reports the average
11329 HTTP request rate over that period, in requests per period. The result is
11330 an integer which can be matched using ACLs. It does not matter whether
11331 they are valid requests or not. Note that this is different from sessions
11332 when keep-alive is used on the client side.
11333
11334 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
11335 counts the absolute number of HTTP requests errors induced by clients
11336 which matched this entry. Errors are counted on invalid and truncated
11337 requests, as well as on denied or tarpitted requests, and on failed
11338 authentications. If the server responds with 4xx, then the request is
11339 also counted as an error since it's an error triggered by the client
Davor Ocelice9ed2812017-12-25 17:49:28 +010011340 (e.g. vulnerability scan).
Willy Tarreauc9705a12010-07-27 20:05:50 +020011341
11342 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
11343 integer parameter <period> which indicates in milliseconds the length
11344 of the period over which the average is measured. It reports the average
11345 HTTP request error rate over that period, in requests per period (see
11346 http_err_cnt above for what is accounted as an error). The result is an
11347 integer which can be matched using ACLs.
11348
Willy Tarreau826f3ab2021-02-10 12:07:15 +010011349 - http_fail_cnt : HTTP Failure Count. It is a positive 32-bit integer which
11350 counts the absolute number of HTTP response failures induced by servers
11351 which matched this entry. Errors are counted on invalid and truncated
11352 responses, as well as any 5xx response other than 501 or 505. It aims at
11353 being used combined with path or URI to detect service failures.
11354
11355 - http_fail_rate(<period>) : frequency counter (takes 12 bytes). It takes
11356 an integer parameter <period> which indicates in milliseconds the length
11357 of the period over which the average is measured. It reports the average
11358 HTTP response failure rate over that period, in requests per period (see
11359 http_fail_cnt above for what is accounted as a failure). The result is an
11360 integer which can be matched using ACLs.
11361
Willy Tarreauc9705a12010-07-27 20:05:50 +020011362 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +010011363 integer which counts the cumulative number of bytes received from clients
Willy Tarreauc9705a12010-07-27 20:05:50 +020011364 which matched this entry. Headers are included in the count. This may be
11365 used to limit abuse of upload features on photo or video servers.
11366
11367 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
11368 integer parameter <period> which indicates in milliseconds the length
11369 of the period over which the average is measured. It reports the average
11370 incoming bytes rate over that period, in bytes per period. It may be used
11371 to detect users which upload too much and too fast. Warning: with large
11372 uploads, it is possible that the amount of uploaded data will be counted
11373 once upon termination, thus causing spikes in the average transfer speed
11374 instead of having a smooth one. This may partially be smoothed with
11375 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
11376 recommended for better fairness.
11377
11378 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +010011379 integer which counts the cumulative number of bytes sent to clients which
Willy Tarreauc9705a12010-07-27 20:05:50 +020011380 matched this entry. Headers are included in the count. This may be used
11381 to limit abuse of bots sucking the whole site.
11382
11383 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
11384 an integer parameter <period> which indicates in milliseconds the length
11385 of the period over which the average is measured. It reports the average
11386 outgoing bytes rate over that period, in bytes per period. It may be used
11387 to detect users which download too much and too fast. Warning: with large
11388 transfers, it is possible that the amount of transferred data will be
11389 counted once upon termination, thus causing spikes in the average
11390 transfer speed instead of having a smooth one. This may partially be
11391 smoothed with "option contstats" though this is not perfect yet. Use of
11392 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +020011393
Willy Tarreauc00cdc22010-06-06 16:48:26 +020011394 There is only one stick-table per proxy. At the moment of writing this doc,
11395 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011396 to be required, simply create a dummy backend with a stick-table in it and
11397 reference it.
11398
11399 It is important to understand that stickiness based on learning information
11400 has some limitations, including the fact that all learned associations are
Baptiste Assmann123ff042016-03-06 23:29:28 +010011401 lost upon restart unless peers are properly configured to transfer such
11402 information upon restart (recommended). In general it can be good as a
11403 complement but not always as an exclusive stickiness.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011404
Willy Tarreauc9705a12010-07-27 20:05:50 +020011405 Last, memory requirements may be important when storing many data types.
11406 Indeed, storing all indicators above at once in each entry requires 116 bytes
11407 per entry, or 116 MB for a 1-million entries table. This is definitely not
11408 something that can be ignored.
11409
11410 Example:
11411 # Keep track of counters of up to 1 million IP addresses over 5 minutes
11412 # and store a general purpose counter and the average connection rate
11413 # computed over a sliding window of 30 seconds.
11414 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
11415
Willy Tarreau4b103022021-02-12 17:59:10 +010011416 See also : "stick match", "stick on", "stick store-request", section 2.5
David du Colombiera13d1b92011-03-17 10:40:22 +010011417 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010011418
11419
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011420stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Baptiste Assmann2f2d2ec2016-03-06 23:27:24 +010011421 Define a response pattern used to create an entry in a stickiness table
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011422 May be used in sections : defaults | frontend | listen | backend
11423 no | no | yes | yes
11424
11425 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020011426 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011427 describes what elements of the response or connection will
Davor Ocelice9ed2812017-12-25 17:49:28 +010011428 be analyzed, extracted and stored in the table once a
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011429 server is selected.
11430
11431 <table> is an optional stickiness table name. If unspecified, the same
11432 backend's table is used. A stickiness table is declared using
11433 the "stick-table" statement.
11434
11435 <cond> is an optional storage condition. It makes it possible to store
11436 certain criteria only when some conditions are met (or not met).
11437 For instance, it could be used to store the SSL session ID only
11438 when the response is a SSL server hello.
11439
11440 Some protocols or applications require complex stickiness rules and cannot
11441 always simply rely on cookies nor hashing. The "stick store-response"
11442 statement describes a rule to decide what to extract from the response and
11443 when to do it, in order to store it into a stickiness table for further
11444 requests to match it using the "stick match" statement. Obviously the
11445 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011446 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011447 See section 7 for a complete list of possible patterns and transformation
11448 rules.
11449
11450 The table has to be declared using the "stick-table" statement. It must be of
11451 a type compatible with the pattern. By default it is the one which is present
11452 in the same backend. It is possible to share a table with other backends by
11453 referencing it using the "table" keyword. If another table is referenced,
11454 the server's ID inside the backends are used. By default, all server IDs
11455 start at 1 in each backend, so the server ordering is enough. But in case of
11456 doubt, it is highly recommended to force server IDs using their "id" setting.
11457
11458 It is possible to restrict the conditions where a "stick store-response"
11459 statement will apply, using "if" or "unless" followed by a condition. This
11460 condition will be evaluated while parsing the response, so any criteria can
11461 be used. See section 7 for ACL based conditions.
11462
11463 There is no limit on the number of "stick store-response" statements, but
11464 there is a limit of 8 simultaneous stores per request or response. This
11465 makes it possible to store up to 8 criteria, all extracted from either the
11466 request or the response, regardless of the number of rules. Only the 8 first
11467 ones which match will be kept. Using this, it is possible to feed multiple
11468 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +010011469 another protocol or access method. Using multiple store-response rules with
11470 the same table is possible and may be used to find the best criterion to rely
11471 on, by arranging the rules by decreasing preference order. Only the first
11472 extracted criterion for a given table will be stored. All subsequent store-
11473 response rules referencing the same table will be skipped and their ACLs will
11474 not be evaluated. However, even if a store-request rule references a table, a
11475 store-response rule may also use the same table. This means that each table
11476 may learn exactly one element from the request and one element from the
11477 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011478
11479 The table will contain the real server that processed the request.
11480
11481 Example :
11482 # Learn SSL session ID from both request and response and create affinity.
11483 backend https
11484 mode tcp
11485 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +020011486 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011487 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011488
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011489 acl clienthello req_ssl_hello_type 1
11490 acl serverhello rep_ssl_hello_type 2
11491
11492 # use tcp content accepts to detects ssl client and server hello.
11493 tcp-request inspect-delay 5s
11494 tcp-request content accept if clienthello
11495
11496 # no timeout on response inspect delay by default.
11497 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011498
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011499 # SSL session ID (SSLID) may be present on a client or server hello.
11500 # Its length is coded on 1 byte at offset 43 and its value starts
11501 # at offset 44.
11502
11503 # Match and learn on request if client hello.
11504 stick on payload_lv(43,1) if clienthello
11505
11506 # Learn on response if server hello.
11507 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +020011508
Emeric Brun6a1cefa2010-09-24 18:15:17 +020011509 server s1 192.168.1.1:443
11510 server s2 192.168.1.1:443
11511
11512 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
11513 extraction.
11514
11515
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011516tcp-check comment <string>
11517 Defines a comment for the following the tcp-check rule, reported in logs if
11518 it fails.
11519 May be used in sections : defaults | frontend | listen | backend
11520 yes | no | yes | yes
11521
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011522 Arguments :
11523 <string> is the comment message to add in logs if the following tcp-check
11524 rule fails.
11525
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011526 It only works for connect, send and expect rules. It is useful to make
11527 user-friendly error reporting.
11528
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011529 See also : "option tcp-check", "tcp-check connect", "tcp-check send" and
11530 "tcp-check expect".
11531
11532
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011533tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
11534 [ssl] [sni <sni>] [alpn <alpn>] [linger]
Christopher Fauletedc6ed92020-04-23 16:27:59 +020011535 [proto <name>] [comment <msg>]
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011536 Opens a new connection
11537 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020011538 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011539
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011540 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011541 comment <msg> defines a message to report if the rule evaluation fails.
11542
Christopher Faulet4dce5922020-03-30 13:54:42 +020011543 default Use default options of the server line to do the health
Daniel Corbett67a82712020-07-06 23:01:19 -040011544 checks. The server options are used only if not redefined.
Christopher Faulet4dce5922020-03-30 13:54:42 +020011545
Christopher Fauletb7d30092020-03-30 15:19:03 +020011546 port <expr> if not set, check port or server port is used.
Christopher Faulet5c288742020-03-31 08:15:58 +020011547 It tells HAProxy where to open the connection to.
11548 <port> must be a valid TCP port source integer, from 1 to
Christopher Fauletb7d30092020-03-30 15:19:03 +020011549 65535 or an sample-fetch expression.
Christopher Faulet5c288742020-03-31 08:15:58 +020011550
11551 addr <ip> defines the IP address to do the health check.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011552
11553 send-proxy send a PROXY protocol string
11554
Christopher Faulet085426a2020-03-30 13:07:02 +020011555 via-socks4 enables outgoing health checks using upstream socks4 proxy.
11556
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011557 ssl opens a ciphered connection
11558
Christopher Faulet79b31d42020-03-30 13:00:05 +020011559 sni <sni> specifies the SNI to use to do health checks over SSL.
11560
Christopher Faulet98572322020-03-30 13:16:44 +020011561 alpn <alpn> defines which protocols to advertise with ALPN. The protocol
11562 list consists in a comma-delimited list of protocol names,
11563 for instance: "http/1.1,http/1.0" (without quotes).
11564 If it is not set, the server ALPN is used.
11565
Christopher Fauletedc6ed92020-04-23 16:27:59 +020011566 proto <name> forces the multiplexer's protocol to use for this connection.
11567 It must be a TCP mux protocol and it must be usable on the
11568 backend side. The list of available protocols is reported in
11569 haproxy -vv.
11570
Christopher Faulet5c288742020-03-31 08:15:58 +020011571 linger cleanly close the connection instead of using a single RST.
Gaetan Rivetf8ba6772020-02-07 15:37:17 +010011572
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011573 When an application lies on more than a single TCP port or when HAProxy
11574 load-balance many services in a single backend, it makes sense to probe all
11575 the services individually before considering a server as operational.
11576
11577 When there are no TCP port configured on the server line neither server port
11578 directive, then the 'tcp-check connect port <port>' must be the first step
11579 of the sequence.
11580
11581 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
11582 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
11583 do.
11584
11585 When a connect must start the ruleset, if may still be preceded by set-var,
11586 unset-var or comment rules.
11587
11588 Examples :
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011589 # check HTTP and HTTPs services on a server.
11590 # first open port 80 thanks to server line port directive, then
11591 # tcp-check opens port 443, ciphered and run a request on it:
11592 option tcp-check
11593 tcp-check connect
11594 tcp-check send GET\ /\ HTTP/1.0\r\n
11595 tcp-check send Host:\ haproxy.1wt.eu\r\n
11596 tcp-check send \r\n
11597 tcp-check expect rstring (2..|3..)
11598 tcp-check connect port 443 ssl
11599 tcp-check send GET\ /\ HTTP/1.0\r\n
11600 tcp-check send Host:\ haproxy.1wt.eu\r\n
11601 tcp-check send \r\n
11602 tcp-check expect rstring (2..|3..)
11603 server www 10.0.0.1 check port 80
11604
11605 # check both POP and IMAP from a single server:
11606 option tcp-check
Gaetan Rivetf8ba6772020-02-07 15:37:17 +010011607 tcp-check connect port 110 linger
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011608 tcp-check expect string +OK\ POP3\ ready
11609 tcp-check connect port 143
11610 tcp-check expect string *\ OK\ IMAP4\ ready
11611 server mail 10.0.0.1 check
11612
11613 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
11614
11615
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011616tcp-check expect [min-recv <int>] [comment <msg>]
Christopher Fauletec07e382020-04-07 14:56:26 +020011617 [ok-status <st>] [error-status <st>] [tout-status <st>]
Christopher Faulet98cc57c2020-04-01 20:52:31 +020011618 [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020011619 [!] <match> <pattern>
Davor Ocelice9ed2812017-12-25 17:49:28 +010011620 Specify data to be collected and analyzed during a generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011621 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020011622 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011623
11624 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011625 comment <msg> defines a message to report if the rule evaluation fails.
11626
Gaetan Rivet1afd8262020-02-07 15:37:17 +010011627 min-recv is optional and can define the minimum amount of data required to
11628 evaluate the current expect rule. If the number of received bytes
11629 is under this limit, the check will wait for more data. This
11630 option can be used to resolve some ambiguous matching rules or to
11631 avoid executing costly regex matches on content known to be still
11632 incomplete. If an exact string (string or binary) is used, the
11633 minimum between the string length and this parameter is used.
11634 This parameter is ignored if it is set to -1. If the expect rule
11635 does not match, the check will wait for more data. If set to 0,
11636 the evaluation result is always conclusive.
11637
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011638 <match> is a keyword indicating how to look for a specific pattern in the
Gaetan Rivetefab6c62020-02-07 15:37:17 +010011639 response. The keyword may be one of "string", "rstring", "binary" or
11640 "rbinary".
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011641 The keyword may be preceded by an exclamation mark ("!") to negate
11642 the match. Spaces are allowed between the exclamation mark and the
11643 keyword. See below for more details on the supported keywords.
11644
Christopher Fauletec07e382020-04-07 14:56:26 +020011645 ok-status <st> is optional and can be used to set the check status if
11646 the expect rule is successfully evaluated and if it is
11647 the last rule in the tcp-check ruleset. "L7OK", "L7OKC",
Christopher Fauletd888f0f2020-05-07 07:40:17 +020011648 "L6OK" and "L4OK" are supported :
11649 - L7OK : check passed on layer 7
Christopher Faulet83662b52020-11-20 17:47:47 +010011650 - L7OKC : check conditionally passed on layer 7, set
11651 server to NOLB state.
Christopher Fauletd888f0f2020-05-07 07:40:17 +020011652 - L6OK : check passed on layer 6
11653 - L4OK : check passed on layer 4
Christopher Fauletec07e382020-04-07 14:56:26 +020011654 By default "L7OK" is used.
11655
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020011656 error-status <st> is optional and can be used to set the check status if
11657 an error occurred during the expect rule evaluation.
Christopher Faulet83662b52020-11-20 17:47:47 +010011658 "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are
11659 supported :
11660 - L7OKC : check conditionally passed on layer 7, set
11661 server to NOLB state.
Christopher Fauletd888f0f2020-05-07 07:40:17 +020011662 - L7RSP : layer 7 invalid response - protocol error
11663 - L7STS : layer 7 response error, for example HTTP 5xx
11664 - L6RSP : layer 6 invalid response - protocol error
11665 - L4CON : layer 1-4 connection problem
11666 By default "L7RSP" is used.
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020011667
Christopher Fauletec07e382020-04-07 14:56:26 +020011668 tout-status <st> is optional and can be used to set the check status if
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020011669 a timeout occurred during the expect rule evaluation.
Christopher Fauletd888f0f2020-05-07 07:40:17 +020011670 "L7TOUT", "L6TOUT", and "L4TOUT" are supported :
11671 - L7TOUT : layer 7 (HTTP/SMTP) timeout
11672 - L6TOUT : layer 6 (SSL) timeout
11673 - L4TOUT : layer 1-4 timeout
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020011674 By default "L7TOUT" is used.
11675
Christopher Fauletbe52b4d2020-04-01 16:30:22 +020011676 on-success <fmt> is optional and can be used to customize the
11677 informational message reported in logs if the expect
11678 rule is successfully evaluated and if it is the last rule
11679 in the tcp-check ruleset. <fmt> is a log-format string.
11680
11681 on-error <fmt> is optional and can be used to customize the
11682 informational message reported in logs if an error
11683 occurred during the expect rule evaluation. <fmt> is a
11684 log-format string.
11685
Christopher Faulet98cc57c2020-04-01 20:52:31 +020011686 status-code <expr> is optional and can be used to set the check status code
11687 reported in logs, on success or on error. <expr> is a
11688 standard HAProxy expression formed by a sample-fetch
11689 followed by some converters.
11690
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011691 <pattern> is the pattern to look for. It may be a string or a regular
11692 expression. If the pattern contains spaces, they must be escaped
11693 with the usual backslash ('\').
11694 If the match is set to binary, then the pattern must be passed as
Davor Ocelice9ed2812017-12-25 17:49:28 +010011695 a series of hexadecimal digits in an even number. Each sequence of
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011696 two digits will represent a byte. The hexadecimal digits may be
11697 used upper or lower case.
11698
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011699 The available matches are intentionally similar to their http-check cousins :
11700
11701 string <string> : test the exact string matches in the response buffer.
11702 A health check response will be considered valid if the
11703 response's buffer contains this exact string. If the
11704 "string" keyword is prefixed with "!", then the response
11705 will be considered invalid if the body contains this
11706 string. This can be used to look for a mandatory pattern
11707 in a protocol response, or to detect a failure when a
11708 specific error appears in a protocol banner.
11709
11710 rstring <regex> : test a regular expression on the response buffer.
11711 A health check response will be considered valid if the
11712 response's buffer matches this expression. If the
11713 "rstring" keyword is prefixed with "!", then the response
11714 will be considered invalid if the body matches the
11715 expression.
11716
Christopher Fauletaaab0832020-05-05 15:54:22 +020011717 string-lf <fmt> : test a log-format string match in the response's buffer.
11718 A health check response will be considered valid if the
11719 response's buffer contains the string resulting of the
11720 evaluation of <fmt>, which follows the log-format rules.
11721 If prefixed with "!", then the response will be
11722 considered invalid if the buffer contains the string.
11723
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011724 binary <hexstring> : test the exact string in its hexadecimal form matches
11725 in the response buffer. A health check response will
11726 be considered valid if the response's buffer contains
11727 this exact hexadecimal string.
11728 Purpose is to match data on binary protocols.
11729
Gaetan Rivetefab6c62020-02-07 15:37:17 +010011730 rbinary <regex> : test a regular expression on the response buffer, like
11731 "rstring". However, the response buffer is transformed
11732 into its hexadecimal form, including NUL-bytes. This
11733 allows using all regex engines to match any binary
11734 content. The hexadecimal transformation takes twice the
11735 size of the original response. As such, the expected
11736 pattern should work on at-most half the response buffer
11737 size.
11738
Christopher Fauletaaab0832020-05-05 15:54:22 +020011739 binary-lf <hexfmt> : test a log-format string in its hexadecimal form
11740 match in the response's buffer. A health check response
11741 will be considered valid if the response's buffer
11742 contains the hexadecimal string resulting of the
11743 evaluation of <fmt>, which follows the log-format
11744 rules. If prefixed with "!", then the response will be
11745 considered invalid if the buffer contains the
11746 hexadecimal string. The hexadecimal string is converted
11747 in a binary string before matching the response's
11748 buffer.
11749
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011750 It is important to note that the responses will be limited to a certain size
Christopher Fauletbb9fb8b2020-11-25 17:20:57 +010011751 defined by the global "tune.bufsize" option, which defaults to 16384 bytes.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011752 Thus, too large responses may not contain the mandatory pattern when using
11753 "string", "rstring" or binary. If a large response is absolutely required, it
11754 is possible to change the default max size by setting the global variable.
11755 However, it is worth keeping in mind that parsing very large responses can
11756 waste some CPU cycles, especially when regular expressions are used, and that
11757 it is always better to focus the checks on smaller resources. Also, in its
11758 current state, the check will not find any string nor regex past a null
11759 character in the response. Similarly it is not possible to request matching
11760 the null character.
11761
11762 Examples :
11763 # perform a POP check
11764 option tcp-check
11765 tcp-check expect string +OK\ POP3\ ready
11766
11767 # perform an IMAP check
11768 option tcp-check
11769 tcp-check expect string *\ OK\ IMAP4\ ready
11770
11771 # look for the redis master server
11772 option tcp-check
11773 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +020011774 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011775 tcp-check send info\ replication\r\n
11776 tcp-check expect string role:master
11777 tcp-check send QUIT\r\n
11778 tcp-check expect string +OK
11779
11780
11781 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
Christopher Fauletbb9fb8b2020-11-25 17:20:57 +010011782 "tcp-check send-binary", "http-check expect", tune.bufsize
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011783
11784
Christopher Fauletb50b3e62020-05-05 18:43:43 +020011785tcp-check send <data> [comment <msg>]
11786tcp-check send-lf <fmt> [comment <msg>]
11787 Specify a string or a log-format string to be sent as a question during a
11788 generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011789 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020011790 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011791
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011792 Arguments :
11793 comment <msg> defines a message to report if the rule evaluation fails.
11794
Christopher Fauletb50b3e62020-05-05 18:43:43 +020011795 <data> is the string that will be sent during a generic health
11796 check session.
Christopher Faulet16fff672020-04-30 07:50:54 +020011797
Christopher Fauletb50b3e62020-05-05 18:43:43 +020011798 <fmt> is the log-format string that will be sent, once evaluated,
11799 during a generic health check session.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011800
11801 Examples :
11802 # look for the redis master server
11803 option tcp-check
11804 tcp-check send info\ replication\r\n
11805 tcp-check expect string role:master
11806
11807 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
Christopher Fauletbb9fb8b2020-11-25 17:20:57 +010011808 "tcp-check send-binary", tune.bufsize
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011809
11810
Christopher Fauletb50b3e62020-05-05 18:43:43 +020011811tcp-check send-binary <hexstring> [comment <msg>]
11812tcp-check send-binary-lf <hexfmt> [comment <msg>]
11813 Specify an hex digits string or an hex digits log-format string to be sent as
11814 a binary question during a raw tcp health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011815 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020011816 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011817
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020011818 Arguments :
11819 comment <msg> defines a message to report if the rule evaluation fails.
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011820
Christopher Fauletb50b3e62020-05-05 18:43:43 +020011821 <hexstring> is the hexadecimal string that will be send, once converted
11822 to binary, during a generic health check session.
Christopher Faulet16fff672020-04-30 07:50:54 +020011823
Christopher Fauletb50b3e62020-05-05 18:43:43 +020011824 <hexfmt> is the hexadecimal log-format string that will be send, once
11825 evaluated and converted to binary, during a generic health
11826 check session.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011827
11828 Examples :
11829 # redis check in binary
11830 option tcp-check
11831 tcp-check send-binary 50494e470d0a # PING\r\n
11832 tcp-check expect binary 2b504F4e47 # +PONG
11833
11834
11835 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
Christopher Fauletbb9fb8b2020-11-25 17:20:57 +010011836 "tcp-check send", tune.bufsize
Willy Tarreau938c7fe2014-04-25 14:21:39 +020011837
11838
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011839tcp-check set-var(<var-name>) <expr>
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011840 This operation sets the content of a variable. The variable is declared inline.
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011841 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020011842 yes | no | yes | yes
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011843
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011844 Arguments :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011845 <var-name> The name of the variable starts with an indication about its
11846 scope. The scopes allowed for tcp-check are:
11847 "proc" : the variable is shared with the whole process.
11848 "sess" : the variable is shared with the tcp-check session.
11849 "check": the variable is declared for the lifetime of the tcp-check.
11850 This prefix is followed by a name. The separator is a '.'.
11851 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
11852 and '-'.
11853
11854 <expr> Is a sample-fetch expression potentially followed by converters.
11855
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011856 Examples :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011857 tcp-check set-var(check.port) int(1234)
11858
11859
11860tcp-check unset-var(<var-name>)
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011861 Free a reference to a variable within its scope.
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011862 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020011863 yes | no | yes | yes
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011864
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011865 Arguments :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011866 <var-name> The name of the variable starts with an indication about its
11867 scope. The scopes allowed for tcp-check are:
11868 "proc" : the variable is shared with the whole process.
11869 "sess" : the variable is shared with the tcp-check session.
11870 "check": the variable is declared for the lifetime of the tcp-check.
11871 This prefix is followed by a name. The separator is a '.'.
11872 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
11873 and '-'.
11874
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020011875 Examples :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010011876 tcp-check unset-var(check.port)
11877
11878
Willy Tarreaue9656522010-08-17 15:40:09 +020011879tcp-request connection <action> [{if | unless} <condition>]
11880 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +020011881 May be used in sections : defaults | frontend | listen | backend
11882 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +020011883 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020011884 <action> defines the action to perform if the condition applies. See
11885 below.
Willy Tarreau1a687942010-05-23 22:40:30 +020011886
Willy Tarreaue9656522010-08-17 15:40:09 +020011887 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011888
11889 Immediately after acceptance of a new incoming connection, it is possible to
11890 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +020011891 or dropped or have its counters tracked. Those conditions cannot make use of
11892 any data contents because the connection has not been read from yet, and the
11893 buffers are not yet allocated. This is used to selectively and very quickly
11894 accept or drop connections from various sources with a very low overhead. If
11895 some contents need to be inspected in order to take the decision, the
11896 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011897
Willy Tarreaue9656522010-08-17 15:40:09 +020011898 The "tcp-request connection" rules are evaluated in their exact declaration
11899 order. If no rule matches or if there is no rule, the default action is to
11900 accept the incoming connection. There is no specific limit to the number of
11901 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011902
Willy Tarreaua9083d02015-05-08 15:27:59 +020011903 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +020011904 - accept :
11905 accepts the connection if the condition is true (when used with "if")
11906 or false (when used with "unless"). The first such rule executed ends
11907 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011908
Willy Tarreaue9656522010-08-17 15:40:09 +020011909 - reject :
11910 rejects the connection if the condition is true (when used with "if")
11911 or false (when used with "unless"). The first such rule executed ends
11912 the rules evaluation. Rejected connections do not even become a
11913 session, which is why they are accounted separately for in the stats,
11914 as "denied connections". They are not considered for the session
11915 rate-limit and are not logged either. The reason is that these rules
11916 should only be used to filter extremely high connection rates such as
11917 the ones encountered during a massive DDoS attack. Under these extreme
11918 conditions, the simple action of logging each event would make the
11919 system collapse and would considerably lower the filtering capacity. If
11920 logging is absolutely desired, then "tcp-request content" rules should
Willy Tarreau4f614292016-10-21 17:49:36 +020011921 be used instead, as "tcp-request session" rules will not log either.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011922
Willy Tarreau4f0d9192013-06-11 20:40:55 +020011923 - expect-proxy layer4 :
11924 configures the client-facing connection to receive a PROXY protocol
11925 header before any byte is read from the socket. This is equivalent to
11926 having the "accept-proxy" keyword on the "bind" line, except that using
11927 the TCP rule allows the PROXY protocol to be accepted only for certain
11928 IP address ranges using an ACL. This is convenient when multiple layers
11929 of load balancers are passed through by traffic coming from public
11930 hosts.
11931
Bertrand Jacquin90759682016-06-06 15:35:39 +010011932 - expect-netscaler-cip layer4 :
11933 configures the client-facing connection to receive a NetScaler Client
11934 IP insertion protocol header before any byte is read from the socket.
11935 This is equivalent to having the "accept-netscaler-cip" keyword on the
11936 "bind" line, except that using the TCP rule allows the PROXY protocol
11937 to be accepted only for certain IP address ranges using an ACL. This
11938 is convenient when multiple layers of load balancers are passed
11939 through by traffic coming from public hosts.
11940
Willy Tarreau18bf01e2014-06-13 16:18:52 +020011941 - capture <sample> len <length> :
11942 This only applies to "tcp-request content" rules. It captures sample
11943 expression <sample> from the request buffer, and converts it to a
11944 string of at most <len> characters. The resulting string is stored into
11945 the next request "capture" slot, so it will possibly appear next to
11946 some captured HTTP headers. It will then automatically appear in the
11947 logs, and it will be possible to extract it using sample fetch rules to
11948 feed it into headers or anything. The length should be limited given
11949 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +020011950 session life. Please check section 7.3 (Fetching samples) and "capture
11951 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +020011952
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011953 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +020011954 enables tracking of sticky counters from current connection. These
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020011955 rules do not stop evaluation and do not change default action. The
11956 number of counters that may be simultaneously tracked by the same
11957 connection is set in MAX_SESS_STKCTR at build time (reported in
John Roeslerfb2fce12019-07-10 15:45:51 -050011958 haproxy -vv) which defaults to 3, so the track-sc number is between 0
Matteo Contrini1857b8c2020-10-16 17:35:54 +020011959 and (MAX_SESS_STKCTR-1). The first "track-sc0" rule executed enables
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020011960 tracking of the counters of the specified table as the first set. The
11961 first "track-sc1" rule executed enables tracking of the counters of the
11962 specified table as the second set. The first "track-sc2" rule executed
11963 enables tracking of the counters of the specified table as the third
11964 set. It is a recommended practice to use the first set of counters for
11965 the per-frontend counters and the second set for the per-backend ones.
11966 But this is just a guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011967
Willy Tarreaue9656522010-08-17 15:40:09 +020011968 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020011969 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +020011970 in section 7.3. It describes what elements of the incoming
Davor Ocelice9ed2812017-12-25 17:49:28 +010011971 request or connection will be analyzed, extracted, combined,
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011972 and used to select which table entry to update the counters.
11973 Note that "tcp-request connection" cannot use content-based
11974 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011975
Willy Tarreaue9656522010-08-17 15:40:09 +020011976 <table> is an optional table to be used instead of the default one,
11977 which is the stick-table declared in the current proxy. All
11978 the counters for the matches and updates for the key will
11979 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011980
Willy Tarreaue9656522010-08-17 15:40:09 +020011981 Once a "track-sc*" rule is executed, the key is looked up in the table
11982 and if it is not found, an entry is allocated for it. Then a pointer to
11983 that entry is kept during all the session's life, and this entry's
11984 counters are updated as often as possible, every time the session's
11985 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011986 Counters are only updated for events that happen after the tracking has
11987 been started. For example, connection counters will not be updated when
11988 tracking layer 7 information, since the connection event happens before
11989 layer7 information is extracted.
11990
Willy Tarreaue9656522010-08-17 15:40:09 +020011991 If the entry tracks concurrent connection counters, one connection is
11992 counted for as long as the entry is tracked, and the entry will not
11993 expire during that time. Tracking counters also provides a performance
11994 advantage over just checking the keys, because only one table lookup is
11995 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011996
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020011997 - sc-inc-gpc0(<sc-id>):
11998 The "sc-inc-gpc0" increments the GPC0 counter according to the sticky
11999 counter designated by <sc-id>. If an error occurs, this action silently
12000 fails and the actions evaluation continues.
12001
Frédéric Lécaille6778b272018-01-29 15:22:53 +010012002 - sc-inc-gpc1(<sc-id>):
12003 The "sc-inc-gpc1" increments the GPC1 counter according to the sticky
12004 counter designated by <sc-id>. If an error occurs, this action silently
12005 fails and the actions evaluation continues.
12006
Cédric Dufour0d7712d2019-11-06 18:38:53 +010012007 - sc-set-gpt0(<sc-id>) { <int> | <expr> }:
12008 This action sets the 32-bit unsigned GPT0 tag according to the sticky
12009 counter designated by <sc-id> and the value of <int>/<expr>. The
12010 expected result is a boolean. If an error occurs, this action silently
12011 fails and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +020012012
William Lallemand2e785f22016-05-25 01:48:42 +020012013 - set-src <expr> :
12014 Is used to set the source IP address to the value of specified
12015 expression. Useful if you want to mask source IP for privacy.
12016 If you want to provide an IP from a HTTP header use "http-request
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020012017 set-src".
William Lallemand2e785f22016-05-25 01:48:42 +020012018
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020012019 Arguments:
12020 <expr> Is a standard HAProxy expression formed by a sample-fetch
12021 followed by some converters.
William Lallemand2e785f22016-05-25 01:48:42 +020012022
12023 Example:
William Lallemand2e785f22016-05-25 01:48:42 +020012024 tcp-request connection set-src src,ipmask(24)
12025
Willy Tarreau0c630532016-10-21 17:52:58 +020012026 When possible, set-src preserves the original source port as long as the
12027 address family allows it, otherwise the source port is set to 0.
William Lallemand2e785f22016-05-25 01:48:42 +020012028
William Lallemand44be6402016-05-25 01:51:35 +020012029 - set-src-port <expr> :
12030 Is used to set the source port address to the value of specified
12031 expression.
12032
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020012033 Arguments:
12034 <expr> Is a standard HAProxy expression formed by a sample-fetch
12035 followed by some converters.
William Lallemand44be6402016-05-25 01:51:35 +020012036
12037 Example:
William Lallemand44be6402016-05-25 01:51:35 +020012038 tcp-request connection set-src-port int(4000)
12039
Willy Tarreau0c630532016-10-21 17:52:58 +020012040 When possible, set-src-port preserves the original source address as long
12041 as the address family supports a port, otherwise it forces the source
12042 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +020012043
William Lallemand13e9b0c2016-05-25 02:34:07 +020012044 - set-dst <expr> :
12045 Is used to set the destination IP address to the value of specified
12046 expression. Useful if you want to mask IP for privacy in log.
12047 If you want to provide an IP from a HTTP header use "http-request
12048 set-dst". If you want to connect to the new address/port, use
12049 '0.0.0.0:0' as a server address in the backend.
12050
12051 <expr> Is a standard HAProxy expression formed by a sample-fetch
12052 followed by some converters.
12053
12054 Example:
12055
12056 tcp-request connection set-dst dst,ipmask(24)
12057 tcp-request connection set-dst ipv4(10.0.0.1)
12058
Willy Tarreau0c630532016-10-21 17:52:58 +020012059 When possible, set-dst preserves the original destination port as long as
12060 the address family allows it, otherwise the destination port is set to 0.
12061
William Lallemand13e9b0c2016-05-25 02:34:07 +020012062 - set-dst-port <expr> :
12063 Is used to set the destination port address to the value of specified
12064 expression. If you want to connect to the new address/port, use
12065 '0.0.0.0:0' as a server address in the backend.
12066
12067
12068 <expr> Is a standard HAProxy expression formed by a sample-fetch
12069 followed by some converters.
12070
12071 Example:
12072
12073 tcp-request connection set-dst-port int(4000)
12074
Willy Tarreau0c630532016-10-21 17:52:58 +020012075 When possible, set-dst-port preserves the original destination address as
12076 long as the address family supports a port, otherwise it forces the
12077 destination address to IPv4 "0.0.0.0" before rewriting the port.
12078
Willy Tarreau2d392c22015-08-24 01:43:45 +020012079 - "silent-drop" :
12080 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +010012081 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +020012082 to prevent the client from being notified. The effect it then that the
12083 client still sees an established connection while there's none on
12084 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
12085 except that it doesn't use any local resource at all on the machine
12086 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +010012087 slow down stronger attackers. It is important to understand the impact
12088 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +020012089 client and HAProxy (firewalls, proxies, load balancers) will also keep
12090 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +010012091 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +020012092 TCP_REPAIR socket option is used to block the emission of a TCP
12093 reset. On other systems, the socket's TTL is reduced to 1 so that the
12094 TCP reset doesn't pass the first router, though it's still delivered to
12095 local networks. Do not use it unless you fully understand how it works.
12096
Willy Tarreaue9656522010-08-17 15:40:09 +020012097 Note that the "if/unless" condition is optional. If no condition is set on
12098 the action, it is simply performed unconditionally. That can be useful for
12099 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012100
Willy Tarreaue9656522010-08-17 15:40:09 +020012101 Example: accept all connections from white-listed hosts, reject too fast
12102 connection without counting them, and track accepted connections.
12103 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012104
Willy Tarreaue9656522010-08-17 15:40:09 +020012105 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012106 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012107 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012108
Willy Tarreaue9656522010-08-17 15:40:09 +020012109 Example: accept all connections from white-listed hosts, count all other
12110 connections and reject too fast ones. This results in abusive ones
12111 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012112
Willy Tarreaue9656522010-08-17 15:40:09 +020012113 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012114 tcp-request connection track-sc0 src
12115 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012116
Willy Tarreau4f0d9192013-06-11 20:40:55 +020012117 Example: enable the PROXY protocol for traffic coming from all known proxies.
12118
12119 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
12120
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012121 See section 7 about ACL usage.
12122
Willy Tarreau4f614292016-10-21 17:49:36 +020012123 See also : "tcp-request session", "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012124
12125
Willy Tarreaue9656522010-08-17 15:40:09 +020012126tcp-request content <action> [{if | unless} <condition>]
12127 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +020012128 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +020012129 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +020012130 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020012131 <action> defines the action to perform if the condition applies. See
12132 below.
Willy Tarreau62644772008-07-16 18:36:06 +020012133
Willy Tarreaue9656522010-08-17 15:40:09 +020012134 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +020012135
Davor Ocelice9ed2812017-12-25 17:49:28 +010012136 A request's contents can be analyzed at an early stage of request processing
Willy Tarreaue9656522010-08-17 15:40:09 +020012137 called "TCP content inspection". During this stage, ACL-based rules are
12138 evaluated every time the request contents are updated, until either an
Christopher Fauletae863c62021-03-15 12:03:44 +010012139 "accept", a "reject" or a "switch-mode" rule matches, or the TCP request
12140 inspection delay expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +020012141
Willy Tarreaue9656522010-08-17 15:40:09 +020012142 The first difference between these rules and "tcp-request connection" rules
12143 is that "tcp-request content" rules can make use of contents to take a
12144 decision. Most often, these decisions will consider a protocol recognition or
12145 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +010012146 both frontends and backends. In case of HTTP keep-alive with the client, all
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012147 tcp-request content rules are evaluated again, so HAProxy keeps a record of
Willy Tarreauf3338342014-01-28 21:40:28 +010012148 what sticky counters were assigned by a "tcp-request connection" versus a
12149 "tcp-request content" rule, and flushes all the content-related ones after
12150 processing an HTTP request, so that they may be evaluated again by the rules
12151 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012152 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +010012153 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +020012154
Willy Tarreaue9656522010-08-17 15:40:09 +020012155 Content-based rules are evaluated in their exact declaration order. If no
12156 rule matches or if there is no rule, the default action is to accept the
12157 contents. There is no specific limit to the number of rules which may be
12158 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +020012159
Thierry FOURNIER236657b2015-08-19 08:25:14 +020012160 Several types of actions are supported :
Willy Tarreau18bf01e2014-06-13 16:18:52 +020012161 - accept : the request is accepted
Baptiste Assmann333939c2019-01-21 08:34:50 +010012162 - do-resolve: perform a DNS resolution
Willy Tarreau18bf01e2014-06-13 16:18:52 +020012163 - reject : the request is rejected and the connection is closed
12164 - capture : the specified sample expression is captured
Patrick Hemmer268a7072018-05-11 12:52:31 -040012165 - set-priority-class <expr> | set-priority-offset <expr>
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012166 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020012167 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010012168 - sc-inc-gpc1(<sc-id>)
Cédric Dufour0d7712d2019-11-06 18:38:53 +010012169 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +020012170 - set-dst <expr>
12171 - set-dst-port <expr>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012172 - set-var(<var-name>) <expr>
Christopher Fauletae863c62021-03-15 12:03:44 +010012173 - switch-mode http [ proto <name> ]
Christopher Faulet85d79c92016-11-09 16:54:56 +010012174 - unset-var(<var-name>)
Willy Tarreau2d392c22015-08-24 01:43:45 +020012175 - silent-drop
Davor Ocelice9ed2812017-12-25 17:49:28 +010012176 - send-spoe-group <engine-name> <group-name>
Christopher Faulet579d83b2019-11-22 15:34:17 +010012177 - use-service <service-name>
Willy Tarreau62644772008-07-16 18:36:06 +020012178
Willy Tarreaue9656522010-08-17 15:40:09 +020012179 They have the same meaning as their counter-parts in "tcp-request connection"
12180 so please refer to that section for a complete description.
Baptiste Assmann333939c2019-01-21 08:34:50 +010012181 For "do-resolve" action, please check the "http-request do-resolve"
12182 configuration section.
Willy Tarreau62644772008-07-16 18:36:06 +020012183
Willy Tarreauf3338342014-01-28 21:40:28 +010012184 While there is nothing mandatory about it, it is recommended to use the
12185 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
12186 content" rules in the frontend, and track-sc2 for "tcp-request content"
12187 rules in the backend, because that makes the configuration more readable
12188 and easier to troubleshoot, but this is just a guideline and all counters
12189 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +020012190
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012191 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +020012192 the action, it is simply performed unconditionally. That can be useful for
12193 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +020012194
Christopher Faulet2079a4a2020-10-02 11:48:57 +020012195 Note also that it is recommended to use a "tcp-request session" rule to track
12196 information that does *not* depend on Layer 7 contents, especially for HTTP
12197 frontends. Some HTTP processing are performed at the session level and may
12198 lead to an early rejection of the requests. Thus, the tracking at the content
12199 level may be disturbed in such case. A warning is emitted during startup to
12200 prevent, as far as possible, such unreliable usage.
12201
Willy Tarreaue9656522010-08-17 15:40:09 +020012202 It is perfectly possible to match layer 7 contents with "tcp-request content"
Christopher Faulet7ea509e2020-10-02 11:38:46 +020012203 rules from a TCP proxy, since HTTP-specific ACL matches are able to
12204 preliminarily parse the contents of a buffer before extracting the required
12205 data. If the buffered contents do not parse as a valid HTTP message, then the
12206 ACL does not match. The parser which is involved there is exactly the same
12207 as for all other HTTP processing, so there is no risk of parsing something
12208 differently. In an HTTP frontend or an HTTP backend, it is guaranteed that
12209 HTTP contents will always be immediately present when the rule is evaluated
12210 first because the HTTP parsing is performed in the early stages of the
12211 connection processing, at the session level. But for such proxies, using
12212 "http-request" rules is much more natural and recommended.
Willy Tarreau62644772008-07-16 18:36:06 +020012213
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010012214 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020012215 are present when the rule is processed. The rule processing engine is able to
12216 wait until the inspect delay expires when the data to be tracked is not yet
12217 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010012218
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +020012219 The "set-dst" and "set-dst-port" are used to set respectively the destination
12220 IP and port. More information on how to use it at "http-request set-dst".
12221
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012222 The "set-var" is used to set the content of a variable. The variable is
Willy Tarreau4f614292016-10-21 17:49:36 +020012223 declared inline. For "tcp-request session" rules, only session-level
12224 variables can be used, without any layer7 contents.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012225
Daniel Schneller0b547052016-03-21 20:46:57 +010012226 <var-name> The name of the variable starts with an indication about
12227 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010012228 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010012229 "sess" : the variable is shared with the whole session
12230 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012231 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +010012232 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012233 processing
Daniel Schneller0b547052016-03-21 20:46:57 +010012234 "res" : the variable is shared only during response
12235 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012236 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +010012237 The name may only contain characters 'a-z', 'A-Z', '0-9',
12238 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012239
12240 <expr> Is a standard HAProxy expression formed by a sample-fetch
12241 followed by some converters.
12242
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012243 The "switch-mode" is used to perform a connection upgrade. Only HTTP
Christopher Fauletae863c62021-03-15 12:03:44 +010012244 upgrades are supported for now. The protocol may optionally be
12245 specified. This action is only available for a proxy with the frontend
12246 capability. The connection upgrade is immediately performed, following
12247 "tcp-request content" rules are not evaluated. This upgrade method should be
12248 preferred to the implicit one consisting to rely on the backend mode. When
12249 used, it is possible to set HTTP directives in a frontend without any
Ilya Shipitsin3df59892021-05-10 12:50:00 +050012250 warning. These directives will be conditionally evaluated if the HTTP upgrade
Christopher Fauletae863c62021-03-15 12:03:44 +010012251 is performed. However, an HTTP backend must still be selected. It remains
12252 unsupported to route an HTTP connection (upgraded or not) to a TCP server.
12253
Christopher Faulet4d37e532021-03-26 14:44:00 +010012254 See section 4 about Proxies for more details on HTTP upgrades.
12255
Christopher Faulet85d79c92016-11-09 16:54:56 +010012256 The "unset-var" is used to unset a variable. See above for details about
12257 <var-name>.
12258
Patrick Hemmer268a7072018-05-11 12:52:31 -040012259 The "set-priority-class" is used to set the queue priority class of the
12260 current request. The value must be a sample expression which converts to an
12261 integer in the range -2047..2047. Results outside this range will be
12262 truncated. The priority class determines the order in which queued requests
12263 are processed. Lower values have higher priority.
12264
12265 The "set-priority-offset" is used to set the queue priority timestamp offset
12266 of the current request. The value must be a sample expression which converts
12267 to an integer in the range -524287..524287. Results outside this range will be
12268 truncated. When a request is queued, it is ordered first by the priority
12269 class, then by the current timestamp adjusted by the given offset in
12270 milliseconds. Lower values have higher priority.
12271 Note that the resulting timestamp is is only tracked with enough precision for
12272 524,287ms (8m44s287ms). If the request is queued long enough to where the
12273 adjusted timestamp exceeds this value, it will be misidentified as highest
12274 priority. Thus it is important to set "timeout queue" to a value, where when
12275 combined with the offset, does not exceed this limit.
12276
Christopher Faulet76c09ef2017-09-21 11:03:52 +020012277 The "send-spoe-group" is used to trigger sending of a group of SPOE
12278 messages. To do so, the SPOE engine used to send messages must be defined, as
12279 well as the SPOE group to send. Of course, the SPOE engine must refer to an
12280 existing SPOE filter. If not engine name is provided on the SPOE filter line,
12281 the SPOE agent name must be used.
12282
12283 <engine-name> The SPOE engine name.
12284
12285 <group-name> The SPOE group name as specified in the engine configuration.
12286
Christopher Faulet579d83b2019-11-22 15:34:17 +010012287 The "use-service" is used to executes a TCP service which will reply to the
12288 request and stop the evaluation of the rules. This service may choose to
12289 reply by sending any valid response or it may immediately close the
12290 connection without sending anything. Outside natives services, it is possible
12291 to write your own services in Lua. No further "tcp-request" rules are
12292 evaluated.
12293
12294 Example:
12295 tcp-request content use-service lua.deny { src -f /etc/haproxy/blacklist.lst }
12296
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012297 Example:
12298
12299 tcp-request content set-var(sess.my_var) src
Christopher Faulet85d79c92016-11-09 16:54:56 +010012300 tcp-request content unset-var(sess.my_var2)
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012301
Willy Tarreau62644772008-07-16 18:36:06 +020012302 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +020012303 # Accept HTTP requests containing a Host header saying "example.com"
Christopher Fauletae863c62021-03-15 12:03:44 +010012304 # and reject everything else. (Only works for HTTP/1 connections)
Willy Tarreaue9656522010-08-17 15:40:09 +020012305 acl is_host_com hdr(Host) -i example.com
12306 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +020012307 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +020012308 tcp-request content reject
12309
Christopher Fauletae863c62021-03-15 12:03:44 +010012310 # Accept HTTP requests containing a Host header saying "example.com"
12311 # and reject everything else. (works for HTTP/1 and HTTP/2 connections)
12312 acl is_host_com hdr(Host) -i example.com
12313 tcp-request inspect-delay 5s
12314 tcp-request switch-mode http if HTTP
12315 tcp-request reject # non-HTTP traffic is implicit here
12316 ...
12317 http-request reject unless is_host_com
12318
Willy Tarreaue9656522010-08-17 15:40:09 +020012319 Example:
Willy Tarreau62644772008-07-16 18:36:06 +020012320 # reject SMTP connection if client speaks first
12321 tcp-request inspect-delay 30s
12322 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012323 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +020012324
12325 # Forward HTTPS connection only if client speaks
12326 tcp-request inspect-delay 30s
12327 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +020012328 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +020012329 tcp-request content reject
12330
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010012331 Example:
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030012332 # Track the last IP(stick-table type string) from X-Forwarded-For
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010012333 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020012334 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030012335 # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
12336 tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010012337
12338 Example:
12339 # track request counts per "base" (concatenation of Host+URL)
12340 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020012341 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010012342
Willy Tarreaue9656522010-08-17 15:40:09 +020012343 Example: track per-frontend and per-backend counters, block abusers at the
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030012344 frontend when the backend detects abuse(and marks gpc0).
Willy Tarreaue9656522010-08-17 15:40:09 +020012345
12346 frontend http
Davor Ocelice9ed2812017-12-25 17:49:28 +010012347 # Use General Purpose Counter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +020012348 # protecting all our sites
12349 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012350 tcp-request connection track-sc0 src
12351 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +020012352 ...
12353 use_backend http_dynamic if { path_end .php }
12354
12355 backend http_dynamic
12356 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012357 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +020012358 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012359 acl click_too_fast sc1_http_req_rate gt 10
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030012360 acl mark_as_abuser sc0_inc_gpc0(http) gt 0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012361 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +020012362 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +020012363
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012364 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +020012365
Jarno Huuskonen95b012b2017-04-06 13:59:14 +030012366 See also : "tcp-request connection", "tcp-request session",
12367 "tcp-request inspect-delay", and "http-request".
Willy Tarreau62644772008-07-16 18:36:06 +020012368
12369
12370tcp-request inspect-delay <timeout>
12371 Set the maximum allowed time to wait for data during content inspection
12372 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +020012373 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +020012374 Arguments :
12375 <timeout> is the timeout value specified in milliseconds by default, but
12376 can be in any other unit if the number is suffixed by the unit,
12377 as explained at the top of this document.
12378
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012379 People using HAProxy primarily as a TCP relay are often worried about the
Willy Tarreau62644772008-07-16 18:36:06 +020012380 risk of passing any type of protocol to a server without any analysis. In
12381 order to be able to analyze the request contents, we must first withhold
12382 the data then analyze them. This statement simply enables withholding of
12383 data for at most the specified amount of time.
12384
Willy Tarreaufb356202010-08-03 14:02:05 +020012385 TCP content inspection applies very early when a connection reaches a
12386 frontend, then very early when the connection is forwarded to a backend. This
12387 means that a connection may experience a first delay in the frontend and a
12388 second delay in the backend if both have tcp-request rules.
12389
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012390 Note that when performing content inspection, HAProxy will evaluate the whole
Willy Tarreau62644772008-07-16 18:36:06 +020012391 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012392 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +020012393 a last check is performed upon expiration, this time considering that the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012394 contents are definitive. If no delay is set, HAProxy will not wait at all
Willy Tarreaud869b242009-03-15 14:43:58 +010012395 and will immediately apply a verdict based on the available information.
12396 Obviously this is unlikely to be very useful and might even be racy, so such
12397 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +020012398
12399 As soon as a rule matches, the request is released and continues as usual. If
12400 the timeout is reached and no rule matches, the default policy will be to let
12401 it pass through unaffected.
12402
12403 For most protocols, it is enough to set it to a few seconds, as most clients
12404 send the full request immediately upon connection. Add 3 or more seconds to
12405 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +010012406 to use large values, for instance to ensure that the client never talks
Davor Ocelice9ed2812017-12-25 17:49:28 +010012407 before the server (e.g. SMTP), or to wait for a client to talk before passing
12408 data to the server (e.g. SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +020012409 least the inspection delay, otherwise it will expire first. If the client
12410 closes the connection or if the buffer is full, the delay immediately expires
12411 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +020012412
Willy Tarreau55165fe2009-05-10 12:02:55 +020012413 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +020012414 "timeout client".
12415
12416
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012417tcp-response content <action> [{if | unless} <condition>]
12418 Perform an action on a session response depending on a layer 4-7 condition
12419 May be used in sections : defaults | frontend | listen | backend
12420 no | no | yes | yes
12421 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020012422 <action> defines the action to perform if the condition applies. See
12423 below.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012424
12425 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
12426
Davor Ocelice9ed2812017-12-25 17:49:28 +010012427 Response contents can be analyzed at an early stage of response processing
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012428 called "TCP content inspection". During this stage, ACL-based rules are
12429 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020012430 "accept", "close" or a "reject" rule matches, or a TCP response inspection
12431 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012432
12433 Most often, these decisions will consider a protocol recognition or validity.
12434
12435 Content-based rules are evaluated in their exact declaration order. If no
12436 rule matches or if there is no rule, the default action is to accept the
12437 contents. There is no specific limit to the number of rules which may be
12438 inserted.
12439
Thierry FOURNIER236657b2015-08-19 08:25:14 +020012440 Several types of actions are supported :
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012441 - accept :
12442 accepts the response if the condition is true (when used with "if")
12443 or false (when used with "unless"). The first such rule executed ends
12444 the rules evaluation.
12445
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020012446 - close :
12447 immediately closes the connection with the server if the condition is
12448 true (when used with "if"), or false (when used with "unless"). The
12449 first such rule executed ends the rules evaluation. The main purpose of
12450 this action is to force a connection to be finished between a client
12451 and a server after an exchange when the application protocol expects
12452 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012453 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020012454 protocols.
12455
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012456 - reject :
12457 rejects the response if the condition is true (when used with "if")
12458 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012459 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012460
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012461 - set-var(<var-name>) <expr>
12462 Sets a variable.
12463
Christopher Faulet85d79c92016-11-09 16:54:56 +010012464 - unset-var(<var-name>)
12465 Unsets a variable.
12466
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020012467 - sc-inc-gpc0(<sc-id>):
12468 This action increments the GPC0 counter according to the sticky
12469 counter designated by <sc-id>. If an error occurs, this action fails
12470 silently and the actions evaluation continues.
12471
Frédéric Lécaille6778b272018-01-29 15:22:53 +010012472 - sc-inc-gpc1(<sc-id>):
12473 This action increments the GPC1 counter according to the sticky
12474 counter designated by <sc-id>. If an error occurs, this action fails
12475 silently and the actions evaluation continues.
12476
Cédric Dufour0d7712d2019-11-06 18:38:53 +010012477 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
12478 This action sets the 32-bit unsigned GPT0 tag according to the sticky
12479 counter designated by <sc-id> and the value of <int>/<expr>. The
12480 expected result is a boolean. If an error occurs, this action silently
12481 fails and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +020012482
Willy Tarreau2d392c22015-08-24 01:43:45 +020012483 - "silent-drop" :
12484 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +010012485 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +020012486 to prevent the client from being notified. The effect it then that the
12487 client still sees an established connection while there's none on
12488 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
12489 except that it doesn't use any local resource at all on the machine
12490 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +010012491 slow down stronger attackers. It is important to understand the impact
12492 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +020012493 client and HAProxy (firewalls, proxies, load balancers) will also keep
12494 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +010012495 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +020012496 TCP_REPAIR socket option is used to block the emission of a TCP
12497 reset. On other systems, the socket's TTL is reduced to 1 so that the
12498 TCP reset doesn't pass the first router, though it's still delivered to
12499 local networks. Do not use it unless you fully understand how it works.
12500
Christopher Faulet76c09ef2017-09-21 11:03:52 +020012501 - send-spoe-group <engine-name> <group-name>
12502 Send a group of SPOE messages.
12503
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012504 Note that the "if/unless" condition is optional. If no condition is set on
12505 the action, it is simply performed unconditionally. That can be useful for
12506 for changing the default action to a reject.
12507
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012508 It is perfectly possible to match layer 7 contents with "tcp-response
12509 content" rules, but then it is important to ensure that a full response has
12510 been buffered, otherwise no contents will match. In order to achieve this,
12511 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012512 period.
12513
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012514 The "set-var" is used to set the content of a variable. The variable is
12515 declared inline.
12516
Daniel Schneller0b547052016-03-21 20:46:57 +010012517 <var-name> The name of the variable starts with an indication about
12518 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010012519 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010012520 "sess" : the variable is shared with the whole session
12521 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012522 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +010012523 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012524 processing
Daniel Schneller0b547052016-03-21 20:46:57 +010012525 "res" : the variable is shared only during response
12526 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012527 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +010012528 The name may only contain characters 'a-z', 'A-Z', '0-9',
12529 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020012530
12531 <expr> Is a standard HAProxy expression formed by a sample-fetch
12532 followed by some converters.
12533
12534 Example:
12535
12536 tcp-request content set-var(sess.my_var) src
12537
Christopher Faulet85d79c92016-11-09 16:54:56 +010012538 The "unset-var" is used to unset a variable. See above for details about
12539 <var-name>.
12540
12541 Example:
12542
12543 tcp-request content unset-var(sess.my_var)
12544
Christopher Faulet76c09ef2017-09-21 11:03:52 +020012545 The "send-spoe-group" is used to trigger sending of a group of SPOE
12546 messages. To do so, the SPOE engine used to send messages must be defined, as
12547 well as the SPOE group to send. Of course, the SPOE engine must refer to an
12548 existing SPOE filter. If not engine name is provided on the SPOE filter line,
12549 the SPOE agent name must be used.
12550
12551 <engine-name> The SPOE engine name.
12552
12553 <group-name> The SPOE group name as specified in the engine configuration.
12554
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012555 See section 7 about ACL usage.
12556
12557 See also : "tcp-request content", "tcp-response inspect-delay"
12558
12559
Willy Tarreau4f614292016-10-21 17:49:36 +020012560tcp-request session <action> [{if | unless} <condition>]
12561 Perform an action on a validated session depending on a layer 5 condition
12562 May be used in sections : defaults | frontend | listen | backend
12563 no | yes | yes | no
12564 Arguments :
12565 <action> defines the action to perform if the condition applies. See
12566 below.
12567
12568 <condition> is a standard layer5-only ACL-based condition (see section 7).
12569
Davor Ocelice9ed2812017-12-25 17:49:28 +010012570 Once a session is validated, (i.e. after all handshakes have been completed),
Willy Tarreau4f614292016-10-21 17:49:36 +020012571 it is possible to evaluate some conditions to decide whether this session
12572 must be accepted or dropped or have its counters tracked. Those conditions
12573 cannot make use of any data contents because no buffers are allocated yet and
12574 the processing cannot wait at this stage. The main use case it to copy some
12575 early information into variables (since variables are accessible in the
12576 session), or to keep track of some information collected after the handshake,
12577 such as SSL-level elements (SNI, ciphers, client cert's CN) or information
Davor Ocelice9ed2812017-12-25 17:49:28 +010012578 from the PROXY protocol header (e.g. track a source forwarded this way). The
Willy Tarreau4f614292016-10-21 17:49:36 +020012579 extracted information can thus be copied to a variable or tracked using
12580 "track-sc" rules. Of course it is also possible to decide to accept/reject as
12581 with other rulesets. Most operations performed here could also be performed
12582 in "tcp-request content" rules, except that in HTTP these rules are evaluated
12583 for each new request, and that might not always be acceptable. For example a
12584 rule might increment a counter on each evaluation. It would also be possible
12585 that a country is resolved by geolocation from the source IP address,
12586 assigned to a session-wide variable, then the source address rewritten from
12587 an HTTP header for all requests. If some contents need to be inspected in
12588 order to take the decision, the "tcp-request content" statements must be used
12589 instead.
12590
12591 The "tcp-request session" rules are evaluated in their exact declaration
12592 order. If no rule matches or if there is no rule, the default action is to
12593 accept the incoming session. There is no specific limit to the number of
12594 rules which may be inserted.
12595
12596 Several types of actions are supported :
12597 - accept : the request is accepted
12598 - reject : the request is rejected and the connection is closed
12599 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
12600 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010012601 - sc-inc-gpc1(<sc-id>)
Cédric Dufour0d7712d2019-11-06 18:38:53 +010012602 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
Willy Tarreau4f614292016-10-21 17:49:36 +020012603 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +010012604 - unset-var(<var-name>)
Willy Tarreau4f614292016-10-21 17:49:36 +020012605 - silent-drop
12606
12607 These actions have the same meaning as their respective counter-parts in
12608 "tcp-request connection" and "tcp-request content", so please refer to these
12609 sections for a complete description.
12610
12611 Note that the "if/unless" condition is optional. If no condition is set on
12612 the action, it is simply performed unconditionally. That can be useful for
12613 "track-sc*" actions as well as for changing the default action to a reject.
12614
12615 Example: track the original source address by default, or the one advertised
12616 in the PROXY protocol header for connection coming from the local
12617 proxies. The first connection-level rule enables receipt of the
12618 PROXY protocol for these ones, the second rule tracks whatever
12619 address we decide to keep after optional decoding.
12620
12621 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
12622 tcp-request session track-sc0 src
12623
12624 Example: accept all sessions from white-listed hosts, reject too fast
12625 sessions without counting them, and track accepted sessions.
12626 This results in session rate being capped from abusive sources.
12627
12628 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
12629 tcp-request session reject if { src_sess_rate gt 10 }
12630 tcp-request session track-sc0 src
12631
12632 Example: accept all sessions from white-listed hosts, count all other
12633 sessions and reject too fast ones. This results in abusive ones
12634 being blocked as long as they don't slow down.
12635
12636 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
12637 tcp-request session track-sc0 src
12638 tcp-request session reject if { sc0_sess_rate gt 10 }
12639
12640 See section 7 about ACL usage.
12641
12642 See also : "tcp-request connection", "tcp-request content", "stick-table"
12643
12644
Emeric Brun0a3b67f2010-09-24 15:34:53 +020012645tcp-response inspect-delay <timeout>
12646 Set the maximum allowed time to wait for a response during content inspection
12647 May be used in sections : defaults | frontend | listen | backend
12648 no | no | yes | yes
12649 Arguments :
12650 <timeout> is the timeout value specified in milliseconds by default, but
12651 can be in any other unit if the number is suffixed by the unit,
12652 as explained at the top of this document.
12653
12654 See also : "tcp-response content", "tcp-request inspect-delay".
12655
12656
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012657timeout check <timeout>
12658 Set additional check timeout, but only after a connection has been already
12659 established.
12660
12661 May be used in sections: defaults | frontend | listen | backend
12662 yes | no | yes | yes
12663 Arguments:
12664 <timeout> is the timeout value specified in milliseconds by default, but
12665 can be in any other unit if the number is suffixed by the unit,
12666 as explained at the top of this document.
12667
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012668 If set, HAProxy uses min("timeout connect", "inter") as a connect timeout
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012669 for check and "timeout check" as an additional read timeout. The "min" is
Davor Ocelice9ed2812017-12-25 17:49:28 +010012670 used so that people running with *very* long "timeout connect" (e.g. those
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012671 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +010012672 (Please also note that there is no valid reason to have such long connect
12673 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
12674 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012675
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012676 If "timeout check" is not set HAProxy uses "inter" for complete check
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012677 timeout (connect + read) exactly like all <1.3.15 version.
12678
12679 In most cases check request is much simpler and faster to handle than normal
12680 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +010012681 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012682
12683 This parameter is specific to backends, but can be specified once for all in
12684 "defaults" sections. This is in fact one of the easiest solutions not to
12685 forget about it.
12686
Willy Tarreau41a340d2008-01-22 12:25:31 +010012687 See also: "timeout connect", "timeout queue", "timeout server",
12688 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012689
12690
Willy Tarreau0ba27502007-12-24 16:55:16 +010012691timeout client <timeout>
Willy Tarreau0ba27502007-12-24 16:55:16 +010012692 Set the maximum inactivity time on the client side.
12693 May be used in sections : defaults | frontend | listen | backend
12694 yes | yes | yes | no
12695 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010012696 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010012697 can be in any other unit if the number is suffixed by the unit,
12698 as explained at the top of this document.
12699
12700 The inactivity timeout applies when the client is expected to acknowledge or
12701 send data. In HTTP mode, this timeout is particularly important to consider
12702 during the first phase, when the client sends the request, and during the
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010012703 response while it is reading data sent by the server. That said, for the
12704 first phase, it is preferable to set the "timeout http-request" to better
12705 protect HAProxy from Slowloris like attacks. The value is specified in
12706 milliseconds by default, but can be in any other unit if the number is
Willy Tarreau0ba27502007-12-24 16:55:16 +010012707 suffixed by the unit, as specified at the top of this document. In TCP mode
12708 (and to a lesser extent, in HTTP mode), it is highly recommended that the
12709 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010012710 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +010012711 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +010012712 (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
12713 sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +020012714 which overrides "timeout client" and "timeout server" for tunnels, as well as
12715 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +010012716
12717 This parameter is specific to frontends, but can be specified once for all in
12718 "defaults" sections. This is in fact one of the easiest solutions not to
12719 forget about it. An unspecified timeout results in an infinite timeout, which
12720 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050012721 during startup because it may result in accumulation of expired sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010012722 the system if the system's timeouts are not configured either.
12723
Willy Tarreau95c4e142017-11-26 12:18:55 +010012724 This also applies to HTTP/2 connections, which will be closed with GOAWAY.
Lukas Tribus75df9d72017-11-24 19:05:12 +010012725
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012726 See also : "timeout server", "timeout tunnel", "timeout http-request".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012727
Willy Tarreau0ba27502007-12-24 16:55:16 +010012728
Willy Tarreau05cdd962014-05-10 14:30:07 +020012729timeout client-fin <timeout>
12730 Set the inactivity timeout on the client side for half-closed connections.
12731 May be used in sections : defaults | frontend | listen | backend
12732 yes | yes | yes | no
12733 Arguments :
12734 <timeout> is the timeout value specified in milliseconds by default, but
12735 can be in any other unit if the number is suffixed by the unit,
12736 as explained at the top of this document.
12737
12738 The inactivity timeout applies when the client is expected to acknowledge or
12739 send data while one direction is already shut down. This timeout is different
12740 from "timeout client" in that it only applies to connections which are closed
12741 in one direction. This is particularly useful to avoid keeping connections in
12742 FIN_WAIT state for too long when clients do not disconnect cleanly. This
12743 problem is particularly common long connections such as RDP or WebSocket.
12744 Note that this timeout can override "timeout tunnel" when a connection shuts
Willy Tarreau599391a2017-11-24 10:16:00 +010012745 down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
12746 frame was sent, often indicating an expectation that the connection quickly
12747 ends.
Willy Tarreau05cdd962014-05-10 14:30:07 +020012748
12749 This parameter is specific to frontends, but can be specified once for all in
12750 "defaults" sections. By default it is not set, so half-closed connections
12751 will use the other timeouts (timeout.client or timeout.tunnel).
12752
12753 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
12754
12755
Willy Tarreau0ba27502007-12-24 16:55:16 +010012756timeout connect <timeout>
Willy Tarreau0ba27502007-12-24 16:55:16 +010012757 Set the maximum time to wait for a connection attempt to a server to succeed.
12758 May be used in sections : defaults | frontend | listen | backend
12759 yes | no | yes | yes
12760 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010012761 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010012762 can be in any other unit if the number is suffixed by the unit,
12763 as explained at the top of this document.
12764
Daniel Corbett9f0843f2021-05-08 10:50:37 -040012765 If the server is located on the same LAN as HAProxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010012766 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +010012767 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +010012768 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010012769 connect timeout also presets both queue and tarpit timeouts to the same value
12770 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +010012771
12772 This parameter is specific to backends, but can be specified once for all in
12773 "defaults" sections. This is in fact one of the easiest solutions not to
12774 forget about it. An unspecified timeout results in an infinite timeout, which
12775 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050012776 during startup because it may result in accumulation of failed sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010012777 the system if the system's timeouts are not configured either.
12778
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012779 See also: "timeout check", "timeout queue", "timeout server", "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012780
Willy Tarreau0ba27502007-12-24 16:55:16 +010012781
Willy Tarreaub16a5742010-01-10 14:46:16 +010012782timeout http-keep-alive <timeout>
12783 Set the maximum allowed time to wait for a new HTTP request to appear
12784 May be used in sections : defaults | frontend | listen | backend
12785 yes | yes | yes | yes
12786 Arguments :
12787 <timeout> is the timeout value specified in milliseconds by default, but
12788 can be in any other unit if the number is suffixed by the unit,
12789 as explained at the top of this document.
12790
12791 By default, the time to wait for a new request in case of keep-alive is set
12792 by "timeout http-request". However this is not always convenient because some
12793 people want very short keep-alive timeouts in order to release connections
12794 faster, and others prefer to have larger ones but still have short timeouts
12795 once the request has started to present itself.
12796
12797 The "http-keep-alive" timeout covers these needs. It will define how long to
12798 wait for a new HTTP request to start coming after a response was sent. Once
12799 the first byte of request has been seen, the "http-request" timeout is used
12800 to wait for the complete request to come. Note that empty lines prior to a
12801 new request do not refresh the timeout and are not counted as a new request.
12802
12803 There is also another difference between the two timeouts : when a connection
12804 expires during timeout http-keep-alive, no error is returned, the connection
12805 just closes. If the connection expires in "http-request" while waiting for a
12806 connection to complete, a HTTP 408 error is returned.
12807
12808 In general it is optimal to set this value to a few tens to hundreds of
12809 milliseconds, to allow users to fetch all objects of a page at once but
Davor Ocelice9ed2812017-12-25 17:49:28 +010012810 without waiting for further clicks. Also, if set to a very small value (e.g.
Willy Tarreaub16a5742010-01-10 14:46:16 +010012811 1 millisecond) it will probably only accept pipelined requests but not the
12812 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +020012813 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +010012814
12815 If this parameter is not set, the "http-request" timeout applies, and if both
12816 are not set, "timeout client" still applies at the lower level. It should be
12817 set in the frontend to take effect, unless the frontend is in TCP mode, in
12818 which case the HTTP backend's timeout will be used.
12819
Willy Tarreau95c4e142017-11-26 12:18:55 +010012820 When using HTTP/2 "timeout client" is applied instead. This is so we can keep
12821 using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2
Lukas Tribus75df9d72017-11-24 19:05:12 +010012822 (where we only have one connection per client and a connection setup).
12823
Willy Tarreaub16a5742010-01-10 14:46:16 +010012824 See also : "timeout http-request", "timeout client".
12825
12826
Willy Tarreau036fae02008-01-06 13:24:40 +010012827timeout http-request <timeout>
12828 Set the maximum allowed time to wait for a complete HTTP request
12829 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +020012830 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +010012831 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010012832 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +010012833 can be in any other unit if the number is suffixed by the unit,
12834 as explained at the top of this document.
12835
12836 In order to offer DoS protection, it may be required to lower the maximum
12837 accepted time to receive a complete HTTP request without affecting the client
12838 timeout. This helps protecting against established connections on which
12839 nothing is sent. The client timeout cannot offer a good protection against
12840 this abuse because it is an inactivity timeout, which means that if the
12841 attacker sends one character every now and then, the timeout will not
12842 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +020012843 types, the request will be aborted if it does not complete in time. When the
12844 timeout expires, an HTTP 408 response is sent to the client to inform it
12845 about the problem, and the connection is closed. The logs will report
12846 termination codes "cR". Some recent browsers are having problems with this
Davor Ocelice9ed2812017-12-25 17:49:28 +010012847 standard, well-documented behavior, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +020012848 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
12849 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +010012850
Baptiste Assmanneccdf432015-10-28 13:49:01 +010012851 By default, this timeout only applies to the header part of the request,
12852 and not to any data. As soon as the empty line is received, this timeout is
12853 not used anymore. When combined with "option http-buffer-request", this
12854 timeout also applies to the body of the request..
12855 It is used again on keep-alive connections to wait for a second
Willy Tarreaub16a5742010-01-10 14:46:16 +010012856 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +010012857
12858 Generally it is enough to set it to a few seconds, as most clients send the
12859 full request immediately upon connection. Add 3 or more seconds to cover TCP
Davor Ocelice9ed2812017-12-25 17:49:28 +010012860 retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
Willy Tarreau036fae02008-01-06 13:24:40 +010012861 generally work on local networks as long as there are no packet losses. This
12862 will prevent people from sending bare HTTP requests using telnet.
12863
12864 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +020012865 chunk of the incoming request. It should be set in the frontend to take
12866 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
12867 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +010012868
Willy Tarreau0f228a02015-05-01 15:37:53 +020012869 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
Baptiste Assmanneccdf432015-10-28 13:49:01 +010012870 "timeout client", "option http-buffer-request".
Willy Tarreau036fae02008-01-06 13:24:40 +010012871
Willy Tarreau844e3c52008-01-11 16:28:18 +010012872
12873timeout queue <timeout>
12874 Set the maximum time to wait in the queue for a connection slot to be free
12875 May be used in sections : defaults | frontend | listen | backend
12876 yes | no | yes | yes
12877 Arguments :
12878 <timeout> is the timeout value specified in milliseconds by default, but
12879 can be in any other unit if the number is suffixed by the unit,
12880 as explained at the top of this document.
12881
12882 When a server's maxconn is reached, connections are left pending in a queue
12883 which may be server-specific or global to the backend. In order not to wait
12884 indefinitely, a timeout is applied to requests pending in the queue. If the
12885 timeout is reached, it is considered that the request will almost never be
12886 served, so it is dropped and a 503 error is returned to the client.
12887
12888 The "timeout queue" statement allows to fix the maximum time for a request to
12889 be left pending in a queue. If unspecified, the same value as the backend's
12890 connection timeout ("timeout connect") is used, for backwards compatibility
12891 with older versions with no "timeout queue" parameter.
12892
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012893 See also : "timeout connect".
Willy Tarreau844e3c52008-01-11 16:28:18 +010012894
12895
12896timeout server <timeout>
Willy Tarreau844e3c52008-01-11 16:28:18 +010012897 Set the maximum inactivity time on the server side.
12898 May be used in sections : defaults | frontend | listen | backend
12899 yes | no | yes | yes
12900 Arguments :
12901 <timeout> is the timeout value specified in milliseconds by default, but
12902 can be in any other unit if the number is suffixed by the unit,
12903 as explained at the top of this document.
12904
12905 The inactivity timeout applies when the server is expected to acknowledge or
12906 send data. In HTTP mode, this timeout is particularly important to consider
12907 during the first phase of the server's response, when it has to send the
12908 headers, as it directly represents the server's processing time for the
12909 request. To find out what value to put there, it's often good to start with
12910 what would be considered as unacceptable response times, then check the logs
12911 to observe the response time distribution, and adjust the value accordingly.
12912
12913 The value is specified in milliseconds by default, but can be in any other
12914 unit if the number is suffixed by the unit, as specified at the top of this
12915 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
12916 recommended that the client timeout remains equal to the server timeout in
12917 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010012918 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +010012919 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +010012920 seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
12921 with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
Willy Tarreauce887fd2012-05-12 12:50:00 +020012922 "timeout tunnel", which overrides "timeout client" and "timeout server" for
12923 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012924
12925 This parameter is specific to backends, but can be specified once for all in
12926 "defaults" sections. This is in fact one of the easiest solutions not to
12927 forget about it. An unspecified timeout results in an infinite timeout, which
12928 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050012929 during startup because it may result in accumulation of expired sessions in
Willy Tarreau844e3c52008-01-11 16:28:18 +010012930 the system if the system's timeouts are not configured either.
12931
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012932 See also : "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +010012933
Willy Tarreau05cdd962014-05-10 14:30:07 +020012934
12935timeout server-fin <timeout>
12936 Set the inactivity timeout on the server side for half-closed connections.
12937 May be used in sections : defaults | frontend | listen | backend
12938 yes | no | yes | yes
12939 Arguments :
12940 <timeout> is the timeout value specified in milliseconds by default, but
12941 can be in any other unit if the number is suffixed by the unit,
12942 as explained at the top of this document.
12943
12944 The inactivity timeout applies when the server is expected to acknowledge or
12945 send data while one direction is already shut down. This timeout is different
12946 from "timeout server" in that it only applies to connections which are closed
12947 in one direction. This is particularly useful to avoid keeping connections in
12948 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
12949 This problem is particularly common long connections such as RDP or WebSocket.
12950 Note that this timeout can override "timeout tunnel" when a connection shuts
12951 down in one direction. This setting was provided for completeness, but in most
12952 situations, it should not be needed.
12953
12954 This parameter is specific to backends, but can be specified once for all in
12955 "defaults" sections. By default it is not set, so half-closed connections
12956 will use the other timeouts (timeout.server or timeout.tunnel).
12957
12958 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
12959
Willy Tarreau844e3c52008-01-11 16:28:18 +010012960
12961timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +010012962 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +010012963 May be used in sections : defaults | frontend | listen | backend
12964 yes | yes | yes | yes
12965 Arguments :
12966 <timeout> is the tarpit duration specified in milliseconds by default, but
12967 can be in any other unit if the number is suffixed by the unit,
12968 as explained at the top of this document.
12969
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020012970 When a connection is tarpitted using "http-request tarpit", it is maintained
12971 open with no activity for a certain amount of time, then closed. "timeout
12972 tarpit" defines how long it will be maintained open.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012973
12974 The value is specified in milliseconds by default, but can be in any other
12975 unit if the number is suffixed by the unit, as specified at the top of this
12976 document. If unspecified, the same value as the backend's connection timeout
12977 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +010012978 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012979
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012980 See also : "timeout connect".
Willy Tarreau844e3c52008-01-11 16:28:18 +010012981
12982
Willy Tarreauce887fd2012-05-12 12:50:00 +020012983timeout tunnel <timeout>
12984 Set the maximum inactivity time on the client and server side for tunnels.
12985 May be used in sections : defaults | frontend | listen | backend
12986 yes | no | yes | yes
12987 Arguments :
12988 <timeout> is the timeout value specified in milliseconds by default, but
12989 can be in any other unit if the number is suffixed by the unit,
12990 as explained at the top of this document.
12991
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012992 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +020012993 between a client and a server, and the connection remains inactive in both
12994 directions. This timeout supersedes both the client and server timeouts once
12995 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
Davor Ocelice9ed2812017-12-25 17:49:28 +010012996 analyzer remains attached to either connection (e.g. tcp content rules are
12997 accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
Willy Tarreauce887fd2012-05-12 12:50:00 +020012998 when switching to the WebSocket protocol, or forwarding a CONNECT request
12999 to a proxy), or after the first response when no keepalive/close option is
13000 specified.
13001
Willy Tarreau05cdd962014-05-10 14:30:07 +020013002 Since this timeout is usually used in conjunction with long-lived connections,
13003 it usually is a good idea to also set "timeout client-fin" to handle the
13004 situation where a client suddenly disappears from the net and does not
13005 acknowledge a close, or sends a shutdown and does not acknowledge pending
13006 data anymore. This can happen in lossy networks where firewalls are present,
13007 and is detected by the presence of large amounts of sessions in a FIN_WAIT
13008 state.
13009
Willy Tarreauce887fd2012-05-12 12:50:00 +020013010 The value is specified in milliseconds by default, but can be in any other
13011 unit if the number is suffixed by the unit, as specified at the top of this
13012 document. Whatever the expected normal idle time, it is a good practice to
13013 cover at least one or several TCP packet losses by specifying timeouts that
Davor Ocelice9ed2812017-12-25 17:49:28 +010013014 are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreauce887fd2012-05-12 12:50:00 +020013015
13016 This parameter is specific to backends, but can be specified once for all in
13017 "defaults" sections. This is in fact one of the easiest solutions not to
13018 forget about it.
13019
13020 Example :
13021 defaults http
13022 option http-server-close
13023 timeout connect 5s
13024 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +020013025 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +020013026 timeout server 30s
13027 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
13028
Willy Tarreau05cdd962014-05-10 14:30:07 +020013029 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +020013030
13031
Willy Tarreau844e3c52008-01-11 16:28:18 +010013032transparent (deprecated)
13033 Enable client-side transparent proxying
13034 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +010013035 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +010013036 Arguments : none
13037
13038 This keyword was introduced in order to provide layer 7 persistence to layer
13039 3 load balancers. The idea is to use the OS's ability to redirect an incoming
13040 connection for a remote address to a local process (here HAProxy), and let
13041 this process know what address was initially requested. When this option is
13042 used, sessions without cookies will be forwarded to the original destination
13043 IP address of the incoming request (which should match that of another
13044 equipment), while requests with cookies will still be forwarded to the
13045 appropriate server.
13046
13047 The "transparent" keyword is deprecated, use "option transparent" instead.
13048
13049 Note that contrary to a common belief, this option does NOT make HAProxy
13050 present the client's IP to the server when establishing the connection.
13051
Willy Tarreau844e3c52008-01-11 16:28:18 +010013052 See also: "option transparent"
13053
William Lallemanda73203e2012-03-12 12:48:57 +010013054unique-id-format <string>
13055 Generate a unique ID for each request.
13056 May be used in sections : defaults | frontend | listen | backend
13057 yes | yes | yes | no
13058 Arguments :
13059 <string> is a log-format string.
13060
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013061 This keyword creates a ID for each request using the custom log format. A
13062 unique ID is useful to trace a request passing through many components of
13063 a complex infrastructure. The newly created ID may also be logged using the
13064 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +010013065
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013066 The format should be composed from elements that are guaranteed to be
Daniel Corbett9f0843f2021-05-08 10:50:37 -040013067 unique when combined together. For instance, if multiple HAProxy instances
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013068 are involved, it might be important to include the node name. It is often
13069 needed to log the incoming connection's source and destination addresses
13070 and ports. Note that since multiple requests may be performed over the same
13071 connection, including a request counter may help differentiate them.
13072 Similarly, a timestamp may protect against a rollover of the counter.
13073 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +010013074
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013075 It is recommended to use hexadecimal notation for many fields since it
13076 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +010013077
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013078 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010013079
Julien Vehentf21be322014-03-07 08:27:34 -050013080 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010013081
13082 will generate:
13083
13084 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
13085
13086 See also: "unique-id-header"
13087
13088unique-id-header <name>
13089 Add a unique ID header in the HTTP request.
13090 May be used in sections : defaults | frontend | listen | backend
13091 yes | yes | yes | no
13092 Arguments :
13093 <name> is the name of the header.
13094
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013095 Add a unique-id header in the HTTP request sent to the server, using the
13096 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +010013097
Cyril Bonté108cf6e2012-04-21 23:30:29 +020013098 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010013099
Julien Vehentf21be322014-03-07 08:27:34 -050013100 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010013101 unique-id-header X-Unique-ID
13102
13103 will generate:
13104
13105 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
13106
13107 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +010013108
Willy Tarreauf51658d2014-04-23 01:21:56 +020013109use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020013110 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +010013111 May be used in sections : defaults | frontend | listen | backend
13112 no | yes | yes | no
13113 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010013114 <backend> is the name of a valid backend or "listen" section, or a
13115 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +010013116
Willy Tarreauf51658d2014-04-23 01:21:56 +020013117 <condition> is a condition composed of ACLs, as described in section 7. If
13118 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +010013119
13120 When doing content-switching, connections arrive on a frontend and are then
13121 dispatched to various backends depending on a number of conditions. The
13122 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020013123 "use_backend" keyword. While it is normally used with HTTP processing, it can
Davor Ocelice9ed2812017-12-25 17:49:28 +010013124 also be used in pure TCP, either without content using stateless ACLs (e.g.
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020013125 source address validation) or combined with a "tcp-request" rule to wait for
13126 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +010013127
13128 There may be as many "use_backend" rules as desired. All of these rules are
13129 evaluated in their declaration order, and the first one which matches will
13130 assign the backend.
13131
13132 In the first form, the backend will be used if the condition is met. In the
13133 second form, the backend will be used if the condition is not met. If no
13134 condition is valid, the backend defined with "default_backend" will be used.
13135 If no default backend is defined, either the servers in the same section are
13136 used (in case of a "listen" section) or, in case of a frontend, no server is
13137 used and a 503 service unavailable response is returned.
13138
Willy Tarreau51aecc72009-07-12 09:47:04 +020013139 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010013140 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +020013141 and backend processing will immediately follow, or the backend will wait for
13142 a complete HTTP request to get in. This feature is useful when a frontend
13143 must decode several protocols on a unique port, one of them being HTTP.
13144
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010013145 When <backend> is a simple name, it is resolved at configuration time, and an
13146 error is reported if the specified backend does not exist. If <backend> is
13147 a log-format string instead, no check may be done at configuration time, so
13148 the backend name is resolved dynamically at run time. If the resulting
13149 backend name does not correspond to any valid backend, no other rule is
13150 evaluated, and the default_backend directive is applied instead. Note that
13151 when using dynamic backend names, it is highly recommended to use a prefix
13152 that no other backend uses in order to ensure that an unauthorized backend
13153 cannot be forced from the request.
13154
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013155 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010013156 used to detect the association between frontends and backends to compute the
13157 backend's "fullconn" setting. This cannot be done for dynamic names.
13158
13159 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
13160 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +010013161
Christopher Fauletb30b3102019-09-12 23:03:09 +020013162use-fcgi-app <name>
13163 Defines the FastCGI application to use for the backend.
13164 May be used in sections : defaults | frontend | listen | backend
13165 no | no | yes | yes
13166 Arguments :
13167 <name> is the name of the FastCGI application to use.
13168
13169 See section 10.1 about FastCGI application setup for details.
Willy Tarreau036fae02008-01-06 13:24:40 +010013170
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013171use-server <server> if <condition>
13172use-server <server> unless <condition>
13173 Only use a specific server if/unless an ACL-based condition is matched.
13174 May be used in sections : defaults | frontend | listen | backend
13175 no | no | yes | yes
13176 Arguments :
Jerome Magnin824186b2020-03-29 09:37:12 +020013177 <server> is the name of a valid server in the same backend section
13178 or a "log-format" string resolving to a server name.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013179
13180 <condition> is a condition composed of ACLs, as described in section 7.
13181
13182 By default, connections which arrive to a backend are load-balanced across
13183 the available servers according to the configured algorithm, unless a
13184 persistence mechanism such as a cookie is used and found in the request.
13185
13186 Sometimes it is desirable to forward a particular request to a specific
13187 server without having to declare a dedicated backend for this server. This
13188 can be achieved using the "use-server" rules. These rules are evaluated after
13189 the "redirect" rules and before evaluating cookies, and they have precedence
13190 on them. There may be as many "use-server" rules as desired. All of these
13191 rules are evaluated in their declaration order, and the first one which
13192 matches will assign the server.
13193
13194 If a rule designates a server which is down, and "option persist" is not used
13195 and no force-persist rule was validated, it is ignored and evaluation goes on
13196 with the next rules until one matches.
13197
13198 In the first form, the server will be used if the condition is met. In the
13199 second form, the server will be used if the condition is not met. If no
13200 condition is valid, the processing continues and the server will be assigned
13201 according to other persistence mechanisms.
13202
13203 Note that even if a rule is matched, cookie processing is still performed but
13204 does not assign the server. This allows prefixed cookies to have their prefix
13205 stripped.
13206
13207 The "use-server" statement works both in HTTP and TCP mode. This makes it
13208 suitable for use with content-based inspection. For instance, a server could
Lukas Tribusa267b5d2020-07-19 00:25:06 +020013209 be selected in a farm according to the TLS SNI field when using protocols with
13210 implicit TLS (also see "req_ssl_sni"). And if these servers have their weight
13211 set to zero, they will not be used for other traffic.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013212
13213 Example :
13214 # intercept incoming TLS requests based on the SNI field
13215 use-server www if { req_ssl_sni -i www.example.com }
13216 server www 192.168.0.1:443 weight 0
13217 use-server mail if { req_ssl_sni -i mail.example.com }
Lukas Tribusa267b5d2020-07-19 00:25:06 +020013218 server mail 192.168.0.1:465 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013219 use-server imap if { req_ssl_sni -i imap.example.com }
Lukas Tribus98a3e3f2017-03-26 12:55:35 +000013220 server imap 192.168.0.1:993 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013221 # all the rest is forwarded to this server
13222 server default 192.168.0.2:443 check
13223
Jerome Magnin824186b2020-03-29 09:37:12 +020013224 When <server> is a simple name, it is checked against existing servers in the
13225 configuration and an error is reported if the specified server does not exist.
13226 If it is a log-format, no check is performed when parsing the configuration,
13227 and if we can't resolve a valid server name at runtime but the use-server rule
Ilya Shipitsin11057a32020-06-21 21:18:27 +050013228 was conditioned by an ACL returning true, no other use-server rule is applied
Jerome Magnin824186b2020-03-29 09:37:12 +020013229 and we fall back to load balancing.
13230
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013231 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013232
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013233
Davor Ocelice9ed2812017-12-25 17:49:28 +0100132345. Bind and server options
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013235--------------------------
13236
13237The "bind", "server" and "default-server" keywords support a number of settings
13238depending on some build options and on the system HAProxy was built on. These
13239settings generally each consist in one word sometimes followed by a value,
13240written on the same line as the "bind" or "server" line. All these options are
13241described in this section.
13242
13243
132445.1. Bind options
13245-----------------
13246
13247The "bind" keyword supports a certain number of settings which are all passed
13248as arguments on the same line. The order in which those arguments appear makes
13249no importance, provided that they appear after the bind address. All of these
13250parameters are optional. Some of them consist in a single words (booleans),
13251while other ones expect a value after them. In this case, the value must be
13252provided immediately after the setting name.
13253
13254The currently supported settings are the following ones.
13255
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010013256accept-netscaler-cip <magic number>
13257 Enforces the use of the NetScaler Client IP insertion protocol over any
13258 connection accepted by any of the TCP sockets declared on the same line. The
13259 NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
13260 the incoming connection to be used everywhere an address is used, with the
13261 only exception of "tcp-request connection" rules which will only see the
13262 real connection address. Logs will reflect the addresses indicated in the
13263 protocol, unless it is violated, in which case the real address will still
13264 be used. This keyword combined with support from external components can be
13265 used as an efficient and reliable alternative to the X-Forwarded-For
Bertrand Jacquin90759682016-06-06 15:35:39 +010013266 mechanism which is not always reliable and not even always usable. See also
13267 "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
13268 which client is allowed to use the protocol.
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010013269
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013270accept-proxy
13271 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +020013272 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
13273 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013274 3/4 addresses of the incoming connection to be used everywhere an address is
13275 used, with the only exception of "tcp-request connection" rules which will
13276 only see the real connection address. Logs will reflect the addresses
13277 indicated in the protocol, unless it is violated, in which case the real
Davor Ocelice9ed2812017-12-25 17:49:28 +010013278 address will still be used. This keyword combined with support from external
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013279 components can be used as an efficient and reliable alternative to the
13280 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +020013281 usable. See also "tcp-request connection expect-proxy" for a finer-grained
13282 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013283
Olivier Houchardc2aae742017-09-22 18:26:28 +020013284allow-0rtt
Bertrand Jacquina25282b2018-08-14 00:56:13 +010013285 Allow receiving early data when using TLSv1.3. This is disabled by default,
Olivier Houchard69752962019-01-08 15:35:32 +010013286 due to security considerations. Because it is vulnerable to replay attacks,
John Roeslerfb2fce12019-07-10 15:45:51 -050013287 you should only allow if for requests that are safe to replay, i.e. requests
Olivier Houchard69752962019-01-08 15:35:32 +010013288 that are idempotent. You can use the "wait-for-handshake" action for any
13289 request that wouldn't be safe with early data.
Olivier Houchardc2aae742017-09-22 18:26:28 +020013290
Willy Tarreauab861d32013-04-02 02:30:41 +020013291alpn <protocols>
13292 This enables the TLS ALPN extension and advertises the specified protocol
13293 list as supported on top of ALPN. The protocol list consists in a comma-
13294 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roeslerfb2fce12019-07-10 15:45:51 -050013295 quotes). This requires that the SSL library is built with support for TLS
Willy Tarreauab861d32013-04-02 02:30:41 +020013296 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
Willy Tarreau95c4e142017-11-26 12:18:55 +010013297 initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
13298 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
13299 now obsolete NPN extension. At the time of writing this, most browsers still
13300 support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
13301 a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
13302 are expected to be supported, both versions can be advertised, in order of
13303 preference, like below :
13304
13305 bind :443 ssl crt pub.pem alpn h2,http/1.1
Willy Tarreauab861d32013-04-02 02:30:41 +020013306
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013307backlog <backlog>
Willy Tarreaue2711c72019-02-27 15:39:41 +010013308 Sets the socket's backlog to this value. If unspecified or 0, the frontend's
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013309 backlog is used instead, which generally defaults to the maxconn value.
13310
Emmanuel Hocdete7f2b732017-01-09 16:15:54 +010013311curves <curves>
13312 This setting is only available when support for OpenSSL was built in. It sets
13313 the string describing the list of elliptic curves algorithms ("curve suite")
13314 that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
13315 string is a colon-delimited list of curve name.
13316 Example: "X25519:P-256" (without quote)
13317 When "curves" is set, "ecdhe" parameter is ignored.
13318
Emeric Brun7fb34422012-09-28 15:26:15 +020013319ecdhe <named curve>
13320 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +010013321 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
13322 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +020013323
Emeric Brunfd33a262012-10-11 16:28:27 +020013324ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +020013325 This setting is only available when support for OpenSSL was built in. It
13326 designates a PEM file from which to load CA certificates used to verify
13327 client's certificate.
13328
Emeric Brunb6dc9342012-09-28 17:55:37 +020013329ca-ignore-err [all|<errorID>,...]
13330 This setting is only available when support for OpenSSL was built in.
13331 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
13332 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
13333 error is ignored.
13334
Christopher Faulet31af49d2015-06-09 17:29:50 +020013335ca-sign-file <cafile>
13336 This setting is only available when support for OpenSSL was built in. It
13337 designates a PEM file containing both the CA certificate and the CA private
13338 key used to create and sign server's certificates. This is a mandatory
13339 setting when the dynamic generation of certificates is enabled. See
13340 'generate-certificates' for details.
13341
Bertrand Jacquind4d0a232016-11-13 16:37:12 +000013342ca-sign-pass <passphrase>
Christopher Faulet31af49d2015-06-09 17:29:50 +020013343 This setting is only available when support for OpenSSL was built in. It is
13344 the CA private key passphrase. This setting is optional and used only when
13345 the dynamic generation of certificates is enabled. See
13346 'generate-certificates' for details.
13347
Emmanuel Hocdet842e94e2019-12-16 16:39:17 +010013348ca-verify-file <cafile>
13349 This setting designates a PEM file from which to load CA certificates used to
13350 verify client's certificate. It designates CA certificates which must not be
13351 included in CA names sent in server hello message. Typically, "ca-file" must
13352 be defined with intermediate certificates, and "ca-verify-file" with
13353 certificates to ending the chain, like root CA.
13354
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013355ciphers <ciphers>
13356 This setting is only available when support for OpenSSL was built in. It sets
13357 the string describing the list of cipher algorithms ("cipher suite") that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +000013358 negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000013359 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
Dirkjan Bussink415150f2018-09-14 11:14:21 +020013360 information and recommendations see e.g.
13361 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
13362 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
13363 cipher configuration, please check the "ciphersuites" keyword.
13364
13365ciphersuites <ciphersuites>
13366 This setting is only available when support for OpenSSL was built in and
13367 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
13368 the list of cipher algorithms ("cipher suite") that are negotiated during the
13369 TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000013370 OpenSSL man pages under the "ciphersuites" section. For cipher configuration
13371 for TLSv1.2 and earlier, please check the "ciphers" keyword.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013372
Emeric Brunfd33a262012-10-11 16:28:27 +020013373crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +020013374 This setting is only available when support for OpenSSL was built in. It
13375 designates a PEM file from which to load certificate revocation list used
Remi Tricot-Le Breton02bd6842021-05-04 12:22:34 +020013376 to verify client's certificate. You need to provide a certificate revocation
13377 list for every certificate of your certificate authority chain.
Emeric Brun1a073b42012-09-28 17:07:34 +020013378
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013379crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +000013380 This setting is only available when support for OpenSSL was built in. It
13381 designates a PEM file containing both the required certificates and any
13382 associated private keys. This file can be built by concatenating multiple
13383 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
13384 requires an intermediate certificate, this can also be concatenated into this
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +010013385 file. Intermediate certificate can also be shared in a directory via
13386 "issuers-chain-path" directive.
Alex Davies0fbf0162013-03-02 16:04:50 +000013387
William Lallemand4c5adbf2020-02-24 14:23:22 +010013388 If the file does not contain a private key, HAProxy will try to load
13389 the key at the same path suffixed by a ".key".
13390
Alex Davies0fbf0162013-03-02 16:04:50 +000013391 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
13392 are loaded.
13393
13394 If a directory name is used instead of a PEM file, then all files found in
William Lallemand3f25ae32020-02-24 16:30:12 +010013395 that directory will be loaded in alphabetic order unless their name ends
13396 with '.key', '.issuer', '.ocsp' or '.sctl' (reserved extensions). This
13397 directive may be specified multiple times in order to load certificates from
13398 multiple files or directories. The certificates will be presented to clients
13399 who provide a valid TLS Server Name Indication field matching one of their
13400 CN or alt subjects. Wildcards are supported, where a wildcard character '*'
13401 is used instead of the first hostname component (e.g. *.example.org matches
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010013402 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +000013403
13404 If no SNI is provided by the client or if the SSL library does not support
13405 TLS extensions, or if the client provides an SNI hostname which does not
13406 match any certificate, then the first loaded certificate will be presented.
13407 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +010013408 recommended to load the default one first as a file or to ensure that it will
13409 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +000013410
Emeric Brune032bfa2012-09-28 13:01:45 +020013411 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013412
Davor Ocelice9ed2812017-12-25 17:49:28 +010013413 Some CAs (such as GoDaddy) offer a drop down list of server types that do not
Alex Davies0fbf0162013-03-02 16:04:50 +000013414 include HAProxy when obtaining a certificate. If this happens be sure to
Davor Ocelice9ed2812017-12-25 17:49:28 +010013415 choose a web server that the CA believes requires an intermediate CA (for
13416 GoDaddy, selection Apache Tomcat will get the correct bundle, but many
Alex Davies0fbf0162013-03-02 16:04:50 +000013417 others, e.g. nginx, result in a wrong bundle that will not work for some
13418 clients).
13419
Daniel Corbett9f0843f2021-05-08 10:50:37 -040013420 For each PEM file, HAProxy checks for the presence of file at the same path
Emeric Brun4147b2e2014-06-16 18:36:30 +020013421 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
13422 Status Request extension (also known as "OCSP stapling") is automatically
13423 enabled. The content of this file is optional. If not empty, it must contain
13424 a valid OCSP Response in DER format. In order to be valid an OCSP Response
13425 must comply with the following rules: it has to indicate a good status,
13426 it has to be a single response for the certificate of the PEM file, and it
13427 has to be valid at the moment of addition. If these rules are not respected
13428 the OCSP Response is ignored and a warning is emitted. In order to identify
13429 which certificate an OCSP Response applies to, the issuer's certificate is
13430 necessary. If the issuer's certificate is not found in the PEM file, it will
13431 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
13432 if it exists otherwise it will fail with an error.
13433
Daniel Corbett9f0843f2021-05-08 10:50:37 -040013434 For each PEM file, HAProxy also checks for the presence of file at the same
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010013435 path suffixed by ".sctl". If such file is found, support for Certificate
13436 Transparency (RFC6962) TLS extension is enabled. The file must contain a
13437 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
13438 to check basic syntax, but no signatures are verified.
13439
yanbzhu6c25e9e2016-01-05 12:52:02 -050013440 There are cases where it is desirable to support multiple key types, e.g. RSA
13441 and ECDSA in the cipher suites offered to the clients. This allows clients
13442 that support EC certificates to be able to use EC ciphers, while
13443 simultaneously supporting older, RSA only clients.
yanbzhud19630c2015-12-14 15:10:25 -050013444
William Lallemandf9ff3ec2020-10-02 17:57:44 +020013445 To achieve this, OpenSSL 1.1.1 is required, you can configure this behavior
13446 by providing one crt entry per certificate type, or by configuring a "cert
13447 bundle" like it was required before HAProxy 1.8. See "ssl-load-extra-files".
yanbzhud19630c2015-12-14 15:10:25 -050013448
Emeric Brunb6dc9342012-09-28 17:55:37 +020013449crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +000013450 This setting is only available when support for OpenSSL was built in. Sets a
Davor Ocelice9ed2812017-12-25 17:49:28 +010013451 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013452 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +000013453 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +020013454
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010013455crt-list <file>
13456 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet98263292016-12-29 18:26:15 +010013457 designates a list of PEM file with an optional ssl configuration and a SNI
13458 filter per certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010013459
Emmanuel Hocdet98263292016-12-29 18:26:15 +010013460 <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
13461
William Lallemand5d036392020-06-30 16:11:36 +020013462 sslbindconf supports "allow-0rtt", "alpn", "ca-file", "ca-verify-file",
13463 "ciphers", "ciphersuites", "crl-file", "curves", "ecdhe", "no-ca-names",
13464 "npn", "verify" configuration. With BoringSSL and Openssl >= 1.1.1
13465 "ssl-min-ver" and "ssl-max-ver" are also supported. It overrides the
13466 configuration set in bind line for the certificate.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010013467
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020013468 Wildcards are supported in the SNI filter. Negative filter are also supported,
Joao Moraise51fab02020-11-21 07:42:20 -030013469 useful in combination with a wildcard filter to exclude a particular SNI, or
13470 after the first certificate to exclude a pattern from its CN or Subject Alt
13471 Name (SAN). The certificates will be presented to clients who provide a valid
13472 TLS Server Name Indication field matching one of the SNI filters. If no SNI
13473 filter is specified, the CN and SAN are used. This directive may be specified
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020013474 multiple times. See the "crt" option for more information. The default
13475 certificate is still needed to meet OpenSSL expectations. If it is not used,
13476 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010013477
William Lallemandf9ff3ec2020-10-02 17:57:44 +020013478 Multi-cert bundling (see "ssl-load-extra-files") is supported with crt-list,
13479 as long as only the base name is given in the crt-list. SNI filter will do
13480 the same work on all bundled certificates.
yanbzhud19630c2015-12-14 15:10:25 -050013481
William Lallemand7c26ed72020-06-03 17:34:48 +020013482 Empty lines as well as lines beginning with a hash ('#') will be ignored.
13483
Joao Moraisaa8fcc42020-11-24 08:24:30 -030013484 The first declared certificate of a bind line is used as the default
Daniel Corbett9f0843f2021-05-08 10:50:37 -040013485 certificate, either from crt or crt-list option, which HAProxy should use in
Joao Moraisaa8fcc42020-11-24 08:24:30 -030013486 the TLS handshake if no other certificate matches. This certificate will also
13487 be used if the provided SNI matches its CN or SAN, even if a matching SNI
13488 filter is found on any crt-list. The SNI filter !* can be used after the first
13489 declared certificate to not include its CN and SAN in the SNI tree, so it will
13490 never match except if no other certificate matches. This way the first
13491 declared certificate act as a fallback.
Joao Moraise51fab02020-11-21 07:42:20 -030013492
Emmanuel Hocdet98263292016-12-29 18:26:15 +010013493 crt-list file example:
Joao Moraise51fab02020-11-21 07:42:20 -030013494 cert1.pem !*
William Lallemand7c26ed72020-06-03 17:34:48 +020013495 # comment
Emmanuel Hocdet05942112017-02-20 16:11:50 +010013496 cert2.pem [alpn h2,http/1.1]
Emmanuel Hocdet98263292016-12-29 18:26:15 +010013497 certW.pem *.domain.tld !secure.domain.tld
Emmanuel Hocdet05942112017-02-20 16:11:50 +010013498 certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
Emmanuel Hocdet98263292016-12-29 18:26:15 +010013499
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013500defer-accept
13501 Is an optional keyword which is supported only on certain Linux kernels. It
13502 states that a connection will only be accepted once some data arrive on it,
13503 or at worst after the first retransmit. This should be used only on protocols
Davor Ocelice9ed2812017-12-25 17:49:28 +010013504 for which the client talks first (e.g. HTTP). It can slightly improve
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013505 performance by ensuring that most of the request is already available when
13506 the connection is accepted. On the other hand, it will not be able to detect
13507 connections which don't talk. It is important to note that this option is
13508 broken in all kernels up to 2.6.31, as the connection is never accepted until
13509 the client talks. This can cause issues with front firewalls which would see
13510 an established connection while the proxy will only see it in SYN_RECV. This
13511 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
13512
William Lallemandf6975e92017-05-26 17:42:10 +020013513expose-fd listeners
13514 This option is only usable with the stats socket. It gives your stats socket
13515 the capability to pass listeners FD to another HAProxy process.
William Lallemande202b1e2017-06-01 17:38:56 +020013516 During a reload with the master-worker mode, the process is automatically
13517 reexecuted adding -x and one of the stats socket with this option.
Davor Ocelice9ed2812017-12-25 17:49:28 +010013518 See also "-x" in the management guide.
William Lallemandf6975e92017-05-26 17:42:10 +020013519
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013520force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013521 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013522 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013523 for high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013524 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013525
13526force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013527 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013528 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013529 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013530
13531force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013532 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013533 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013534 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013535
13536force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013537 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013538 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013539 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013540
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013541force-tlsv13
13542 This option enforces use of TLSv1.3 only on SSL connections instantiated from
13543 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013544 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013545
Christopher Faulet31af49d2015-06-09 17:29:50 +020013546generate-certificates
13547 This setting is only available when support for OpenSSL was built in. It
13548 enables the dynamic SSL certificates generation. A CA certificate and its
13549 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
13550 a transparent forward proxy, SSL requests generate errors because of a common
13551 name mismatch on the certificate presented to the client. With this option
13552 enabled, HAProxy will try to forge a certificate using the SNI hostname
13553 indicated by the client. This is done only if no certificate matches the SNI
13554 hostname (see 'crt-list'). If an error occurs, the default certificate is
13555 used, else the 'strict-sni' option is set.
13556 It can also be used when HAProxy is configured as a reverse proxy to ease the
13557 deployment of an architecture with many backends.
13558
13559 Creating a SSL certificate is an expensive operation, so a LRU cache is used
13560 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
Davor Ocelice9ed2812017-12-25 17:49:28 +010013561 increases the HAProxy's memory footprint to reduce latency when the same
Christopher Faulet31af49d2015-06-09 17:29:50 +020013562 certificate is used many times.
13563
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013564gid <gid>
13565 Sets the group of the UNIX sockets to the designated system gid. It can also
13566 be set by default in the global section's "unix-bind" statement. Note that
13567 some platforms simply ignore this. This setting is equivalent to the "group"
13568 setting except that the group ID is used instead of its name. This setting is
13569 ignored by non UNIX sockets.
13570
13571group <group>
13572 Sets the group of the UNIX sockets to the designated system group. It can
13573 also be set by default in the global section's "unix-bind" statement. Note
13574 that some platforms simply ignore this. This setting is equivalent to the
13575 "gid" setting except that the group name is used instead of its gid. This
13576 setting is ignored by non UNIX sockets.
13577
13578id <id>
13579 Fixes the socket ID. By default, socket IDs are automatically assigned, but
13580 sometimes it is more convenient to fix them to ease monitoring. This value
13581 must be strictly positive and unique within the listener/frontend. This
13582 option can only be used when defining only a single socket.
13583
13584interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +010013585 Restricts the socket to a specific interface. When specified, only packets
13586 received from that particular interface are processed by the socket. This is
13587 currently only supported on Linux. The interface must be a primary system
13588 interface, not an aliased interface. It is also possible to bind multiple
13589 frontends to the same address if they are bound to different interfaces. Note
13590 that binding to a network interface requires root privileges. This parameter
Jérôme Magnin61275192018-02-07 11:39:58 +010013591 is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic
13592 uses the same interface as inbound traffic, and its associated routing table,
13593 even if there are explicit routes through different interfaces configured.
13594 This can prove useful to address asymmetric routing issues when the same
13595 client IP addresses need to be able to reach frontends hosted on different
13596 interfaces.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013597
Willy Tarreauabb175f2012-09-24 12:43:26 +020013598level <level>
13599 This setting is used with the stats sockets only to restrict the nature of
13600 the commands that can be issued on the socket. It is ignored by other
13601 sockets. <level> can be one of :
Davor Ocelice9ed2812017-12-25 17:49:28 +010013602 - "user" is the least privileged level; only non-sensitive stats can be
Willy Tarreauabb175f2012-09-24 12:43:26 +020013603 read, and no change is allowed. It would make sense on systems where it
13604 is not easy to restrict access to the socket.
13605 - "operator" is the default level and fits most common uses. All data can
Davor Ocelice9ed2812017-12-25 17:49:28 +010013606 be read, and only non-sensitive changes are permitted (e.g. clear max
Willy Tarreauabb175f2012-09-24 12:43:26 +020013607 counters).
Davor Ocelice9ed2812017-12-25 17:49:28 +010013608 - "admin" should be used with care, as everything is permitted (e.g. clear
Willy Tarreauabb175f2012-09-24 12:43:26 +020013609 all counters).
13610
Andjelko Iharosc4df59e2017-07-20 11:59:48 +020013611severity-output <format>
13612 This setting is used with the stats sockets only to configure severity
13613 level output prepended to informational feedback messages. Severity
13614 level of messages can range between 0 and 7, conforming to syslog
13615 rfc5424. Valid and successful socket commands requesting data
13616 (i.e. "show map", "get acl foo" etc.) will never have a severity level
13617 prepended. It is ignored by other sockets. <format> can be one of :
13618 - "none" (default) no severity level is prepended to feedback messages.
13619 - "number" severity level is prepended as a number.
13620 - "string" severity level is prepended as a string following the
13621 rfc5424 convention.
13622
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013623maxconn <maxconn>
13624 Limits the sockets to this number of concurrent connections. Extraneous
13625 connections will remain in the system's backlog until a connection is
13626 released. If unspecified, the limit will be the same as the frontend's
13627 maxconn. Note that in case of port ranges or multiple addresses, the same
13628 value will be applied to each socket. This setting enables different
13629 limitations on expensive sockets, for instance SSL entries which may easily
13630 eat all memory.
13631
13632mode <mode>
13633 Sets the octal mode used to define access permissions on the UNIX socket. It
13634 can also be set by default in the global section's "unix-bind" statement.
13635 Note that some platforms simply ignore this. This setting is ignored by non
13636 UNIX sockets.
13637
13638mss <maxseg>
13639 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
13640 connections. This can be used to force a lower MSS for certain specific
13641 ports, for instance for connections passing through a VPN. Note that this
13642 relies on a kernel feature which is theoretically supported under Linux but
13643 was buggy in all versions prior to 2.6.28. It may or may not work on other
13644 operating systems. It may also not change the advertised value but change the
13645 effective size of outgoing segments. The commonly advertised value for TCPv4
13646 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
13647 positive, it will be used as the advertised MSS. If it is negative, it will
13648 indicate by how much to reduce the incoming connection's advertised MSS for
13649 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
13650
13651name <name>
13652 Sets an optional name for these sockets, which will be reported on the stats
13653 page.
13654
Willy Tarreaud72f0f32015-10-13 14:50:22 +020013655namespace <name>
13656 On Linux, it is possible to specify which network namespace a socket will
13657 belong to. This directive makes it possible to explicitly bind a listener to
13658 a namespace different from the default one. Please refer to your operating
13659 system's documentation to find more details about network namespaces.
13660
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013661nice <nice>
13662 Sets the 'niceness' of connections initiated from the socket. Value must be
13663 in the range -1024..1024 inclusive, and defaults to zero. Positive values
13664 means that such connections are more friendly to others and easily offer
13665 their place in the scheduler. On the opposite, negative values mean that
13666 connections want to run with a higher priority than others. The difference
13667 only happens under high loads when the system is close to saturation.
13668 Negative values are appropriate for low-latency or administration services,
13669 and high values are generally recommended for CPU intensive tasks such as SSL
13670 processing or bulk transfers which are less sensible to latency. For example,
13671 it may make sense to use a positive value for an SMTP socket and a negative
13672 one for an RDP socket.
13673
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020013674no-ca-names
13675 This setting is only available when support for OpenSSL was built in. It
13676 prevents from send CA names in server hello message when ca-file is used.
Emmanuel Hocdet842e94e2019-12-16 16:39:17 +010013677 Use "ca-verify-file" instead of "ca-file" with "no-ca-names".
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020013678
Emeric Brun9b3009b2012-10-05 11:55:06 +020013679no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013680 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013681 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013682 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013683 be enabled using any configuration option. This option is also available on
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013684 global statement "ssl-default-bind-options". Use "ssl-min-ver" and
13685 "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013686
Emeric Brun90ad8722012-10-02 14:00:59 +020013687no-tls-tickets
13688 This setting is only available when support for OpenSSL was built in. It
13689 disables the stateless session resumption (RFC 5077 TLS Ticket
13690 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013691 session resumption is more expensive in CPU usage. This option is also
13692 available on global statement "ssl-default-bind-options".
Lukas Tribusbdb386d2020-03-10 00:56:09 +010013693 The TLS ticket mechanism is only used up to TLS 1.2.
13694 Forward Secrecy is compromised with TLS tickets, unless ticket keys
13695 are periodically rotated (via reload or by using "tls-ticket-keys").
Emeric Brun90ad8722012-10-02 14:00:59 +020013696
Emeric Brun9b3009b2012-10-05 11:55:06 +020013697no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013698 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013699 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013700 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013701 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013702 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
13703 and "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013704
Emeric Brun9b3009b2012-10-05 11:55:06 +020013705no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +020013706 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013707 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013708 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013709 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013710 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
13711 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020013712
Emeric Brun9b3009b2012-10-05 11:55:06 +020013713no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +020013714 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013715 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020013716 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013717 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013718 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
13719 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020013720
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013721no-tlsv13
13722 This setting is only available when support for OpenSSL was built in. It
13723 disables support for TLSv1.3 on any sockets instantiated from the listener
13724 when SSL is supported. Note that SSLv2 is forced disabled in the code and
13725 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013726 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
13727 and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013728
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020013729npn <protocols>
13730 This enables the NPN TLS extension and advertises the specified protocol list
13731 as supported on top of NPN. The protocol list consists in a comma-delimited
13732 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roeslerfb2fce12019-07-10 15:45:51 -050013733 This requires that the SSL library is built with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +020013734 enabled (check with haproxy -vv). Note that the NPN extension has been
Willy Tarreau95c4e142017-11-26 12:18:55 +010013735 replaced with the ALPN extension (see the "alpn" keyword), though this one is
13736 only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
13737 version of OpenSSL, NPN might still be used as most clients still support it
13738 at the time of writing this. It is possible to enable both NPN and ALPN
13739 though it probably doesn't make any sense out of testing.
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020013740
Lukas Tribus53ae85c2017-05-04 15:45:40 +000013741prefer-client-ciphers
13742 Use the client's preference when selecting the cipher suite, by default
13743 the server's preference is enforced. This option is also available on
13744 global statement "ssl-default-bind-options".
Lukas Tribus926594f2018-05-18 17:55:57 +020013745 Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
13746 (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
13747 the client cipher list.
Lukas Tribus53ae85c2017-05-04 15:45:40 +000013748
Christopher Fauletc644fa92017-11-23 22:44:11 +010013749process <process-set>[/<thread-set>]
Willy Tarreaua36b3242019-02-02 13:14:34 +010013750 This restricts the list of processes or threads on which this listener is
Christopher Fauletc644fa92017-11-23 22:44:11 +010013751 allowed to run. It does not enforce any process but eliminates those which do
Davor Ocelice9ed2812017-12-25 17:49:28 +010013752 not match. If the frontend uses a "bind-process" setting, the intersection
Christopher Fauletc644fa92017-11-23 22:44:11 +010013753 between the two is applied. If in the end the listener is not allowed to run
13754 on any remaining process, a warning is emitted, and the listener will either
13755 run on the first process of the listener if a single process was specified,
13756 or on all of its processes if multiple processes were specified. If a thread
Davor Ocelice9ed2812017-12-25 17:49:28 +010013757 set is specified, it limits the threads allowed to process incoming
Willy Tarreaua36b3242019-02-02 13:14:34 +010013758 connections for this listener, for the the process set. If multiple processes
13759 and threads are configured, a warning is emitted, as it either results from a
13760 configuration error or a misunderstanding of these models. For the unlikely
13761 case where several ranges are needed, this directive may be repeated.
13762 <process-set> and <thread-set> must use the format
Christopher Fauletc644fa92017-11-23 22:44:11 +010013763
13764 all | odd | even | number[-[number]]
13765
13766 Ranges can be partially defined. The higher bound can be omitted. In such
13767 case, it is replaced by the corresponding maximum value. The main purpose of
13768 this directive is to be used with the stats sockets and have one different
13769 socket per process. The second purpose is to have multiple bind lines sharing
13770 the same IP:port but not the same process in a listener, so that the system
13771 can distribute the incoming connections into multiple queues and allow a
13772 smoother inter-process load balancing. Currently Linux 3.9 and above is known
13773 for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +020013774
Christopher Fauleta717b992018-04-10 14:43:00 +020013775proto <name>
13776 Forces the multiplexer's protocol to use for the incoming connections. It
13777 must be compatible with the mode of the frontend (TCP or HTTP). It must also
13778 be usable on the frontend side. The list of available protocols is reported
Christopher Faulet982e17d2021-03-26 14:44:18 +010013779 in haproxy -vv. The protocols properties are reported : the mode (TCP/HTTP),
13780 the side (FE/BE), the mux name and its flags.
13781
13782 Some protocols report errors on aborts (flag=CLEAN_ABRT). Some others are
13783 subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally
13784 some protocols don't support upgrades (flag=NO_UPG). The HTX compatibility is
13785 also reported (flag=HTX).
13786
13787 Here are the protocols that may be used as argument to a "proto" directive on
13788 a bind line :
13789
13790 h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|CLEAN_ABRT|HOL_RISK|NO_UPG
13791 h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG
13792 none : mode=TCP side=FE|BE mux=PASS flags=NO_UPG
13793
Daniel Corbett67a82712020-07-06 23:01:19 -040013794 Idea behind this option is to bypass the selection of the best multiplexer's
Christopher Fauleta717b992018-04-10 14:43:00 +020013795 protocol for all connections instantiated from this listening socket. For
Joseph Herlant71b4b152018-11-13 16:55:16 -080013796 instance, it is possible to force the http/2 on clear TCP by specifying "proto
Christopher Fauleta717b992018-04-10 14:43:00 +020013797 h2" on the bind line.
13798
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013799ssl
13800 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013801 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013802 certificate is necessary (see "crt" above). All contents in the buffers will
13803 appear in clear text, so that ACLs and HTTP processing will only have access
Emmanuel Hocdetbd695fe2017-05-15 15:53:41 +020013804 to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
13805 to enable it.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013806
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013807ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
13808 This option enforces use of <version> or lower on SSL connections instantiated
William Lallemand50df1cb2020-06-02 10:52:24 +020013809 from this listener. Using this setting without "ssl-min-ver" can be
13810 ambiguous because the default ssl-min-ver value could change in future HAProxy
13811 versions. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013812 "ssl-default-bind-options". See also "ssl-min-ver".
13813
13814ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
William Lallemand50df1cb2020-06-02 10:52:24 +020013815 This option enforces use of <version> or upper on SSL connections
13816 instantiated from this listener. The default value is "TLSv1.2". This option
13817 is also available on global statement "ssl-default-bind-options".
13818 See also "ssl-max-ver".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013819
Emmanuel Hocdet65623372013-01-24 17:17:15 +010013820strict-sni
13821 This setting is only available when support for OpenSSL was built in. The
13822 SSL/TLS negotiation is allow only if the client provided an SNI which match
13823 a certificate. The default certificate is not used.
13824 See the "crt" option for more information.
13825
Willy Tarreau2af207a2015-02-04 00:45:58 +010013826tcp-ut <delay>
Tim Düsterhus4896c442016-11-29 02:15:19 +010013827 Sets the TCP User Timeout for all incoming connections instantiated from this
Willy Tarreau2af207a2015-02-04 00:45:58 +010013828 listening socket. This option is available on Linux since version 2.6.37. It
Daniel Corbett9f0843f2021-05-08 10:50:37 -040013829 allows HAProxy to configure a timeout for sockets which contain data not
Davor Ocelice9ed2812017-12-25 17:49:28 +010013830 receiving an acknowledgment for the configured delay. This is especially
Willy Tarreau2af207a2015-02-04 00:45:58 +010013831 useful on long-lived connections experiencing long idle periods such as
13832 remote terminals or database connection pools, where the client and server
13833 timeouts must remain high to allow a long period of idle, but where it is
13834 important to detect that the client has disappeared in order to release all
13835 resources associated with its connection (and the server's session). The
13836 argument is a delay expressed in milliseconds by default. This only works
13837 for regular TCP connections, and is ignored for other protocols.
13838
Willy Tarreau1c862c52012-10-05 16:21:00 +020013839tfo
Lukas Tribus0defb902013-02-13 23:35:39 +010013840 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +020013841 enables TCP Fast Open on the listening socket, which means that clients which
13842 support this feature will be able to send a request and receive a response
13843 during the 3-way handshake starting from second connection, thus saving one
13844 round-trip after the first connection. This only makes sense with protocols
13845 that use high connection rates and where each round trip matters. This can
13846 possibly cause issues with many firewalls which do not accept data on SYN
13847 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +020013848 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
13849 need to build HAProxy with USE_TFO=1 if your libc doesn't define
13850 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +020013851
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010013852tls-ticket-keys <keyfile>
13853 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
Emeric Brun9e754772019-01-10 17:51:55 +010013854 or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64
13855 with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo).
13856 The first key determines the key length used for next keys: you can't mix
13857 aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO
13858 build option (default 3) and at least as many keys need to be present in
13859 the file. Last TLS_TICKETS_NO keys will be used for decryption and the
13860 penultimate one for encryption. This enables easy key rotation by just
13861 appending new key to the file and reloading the process. Keys must be
13862 periodically rotated (ex. every 12h) or Perfect Forward Secrecy is
13863 compromised. It is also a good idea to keep the keys off any permanent
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010013864 storage such as hard drives (hint: use tmpfs and don't swap those files).
13865 Lifetime hint can be changed using tune.ssl.timeout.
13866
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013867transparent
13868 Is an optional keyword which is supported only on certain Linux kernels. It
13869 indicates that the addresses will be bound even if they do not belong to the
13870 local machine, and that packets targeting any of these addresses will be
13871 intercepted just as if the addresses were locally configured. This normally
13872 requires that IP forwarding is enabled. Caution! do not use this with the
13873 default address '*', as it would redirect any traffic for the specified port.
13874 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
13875 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
13876 kernel version. Some distribution kernels include backports of the feature,
13877 so check for support with your vendor.
13878
Willy Tarreau77e3af92012-11-24 15:07:23 +010013879v4v6
13880 Is an optional keyword which is supported only on most recent systems
13881 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
13882 and IPv6 when it uses the default address. Doing so is sometimes necessary
13883 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013884 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +010013885
Willy Tarreau9b6700f2012-11-24 11:55:28 +010013886v6only
13887 Is an optional keyword which is supported only on most recent systems
13888 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
13889 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +010013890 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
13891 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +010013892
Willy Tarreaub6205fd2012-09-24 12:27:33 +020013893uid <uid>
13894 Sets the owner of the UNIX sockets to the designated system uid. It can also
13895 be set by default in the global section's "unix-bind" statement. Note that
13896 some platforms simply ignore this. This setting is equivalent to the "user"
13897 setting except that the user numeric ID is used instead of its name. This
13898 setting is ignored by non UNIX sockets.
13899
13900user <user>
13901 Sets the owner of the UNIX sockets to the designated system user. It can also
13902 be set by default in the global section's "unix-bind" statement. Note that
13903 some platforms simply ignore this. This setting is equivalent to the "uid"
13904 setting except that the user name is used instead of its uid. This setting is
13905 ignored by non UNIX sockets.
13906
Emeric Brun1a073b42012-09-28 17:07:34 +020013907verify [none|optional|required]
13908 This setting is only available when support for OpenSSL was built in. If set
13909 to 'none', client certificate is not requested. This is the default. In other
13910 cases, a client certificate is requested. If the client does not provide a
13911 certificate after the request and if 'verify' is set to 'required', then the
13912 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +020013913 certificate provided by the client is always verified using CAs from
13914 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
13915 is aborted, regardless of the 'verify' option, unless the error code exactly
13916 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013917
Willy Tarreaub6205fd2012-09-24 12:27:33 +0200139185.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +010013919------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020013920
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010013921The "server" and "default-server" keywords support a certain number of settings
13922which are all passed as arguments on the server line. The order in which those
13923arguments appear does not count, and they are all optional. Some of those
13924settings are single words (booleans) while others expect one or several values
13925after them. In this case, the values must immediately follow the setting name.
13926Except default-server, all those settings must be specified after the server's
13927address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +020013928
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013929 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010013930 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +020013931
Frédéric Lécailled2376272017-03-21 18:52:12 +010013932Note that all these settings are supported both by "server" and "default-server"
13933keywords, except "id" which is only supported by "server".
13934
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013935The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +010013936
Willy Tarreauceb4ac92012-04-28 00:41:46 +020013937addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013938 Using the "addr" parameter, it becomes possible to use a different IP address
Baptiste Assmann13f83532016-03-06 23:14:36 +010013939 to send health-checks or to probe the agent-check. On some servers, it may be
13940 desirable to dedicate an IP address to specific component able to perform
13941 complex tests which are more suitable to health-checks than the application.
13942 This parameter is ignored if the "check" parameter is not set. See also the
13943 "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013944
Simon Hormand60d6912013-11-25 10:46:36 +090013945agent-check
13946 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +010013947 health check. An agent health check is performed by making a TCP connection
Willy Tarreau7a0139e2018-12-16 08:42:56 +010013948 to the port set by the "agent-port" parameter and reading an ASCII string
13949 terminated by the first '\r' or '\n' met. The string is made of a series of
13950 words delimited by spaces, tabs or commas in any order, each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +090013951
Willy Tarreau81f5d942013-12-09 20:51:51 +010013952 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +090013953 Values in this format will set the weight proportional to the initial
Daniel Corbett9f0843f2021-05-08 10:50:37 -040013954 weight of a server as configured when HAProxy starts. Note that a zero
Willy Tarreauc5af3a62014-10-07 15:27:33 +020013955 weight is reported on the stats page as "DRAIN" since it has the same
13956 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +090013957
Davor Ocelice9ed2812017-12-25 17:49:28 +010013958 - The string "maxconn:" followed by an integer (no space between). Values
13959 in this format will set the maxconn of a server. The maximum number of
13960 connections advertised needs to be multiplied by the number of load
13961 balancers and different backends that use this health check to get the
13962 total number of connections the server might receive. Example: maxconn:30
Nenad Merdanovic174dd372016-04-24 23:10:06 +020013963
Willy Tarreau81f5d942013-12-09 20:51:51 +010013964 - The word "ready". This will turn the server's administrative state to the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013965 READY mode, thus canceling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +090013966
Willy Tarreau81f5d942013-12-09 20:51:51 +010013967 - The word "drain". This will turn the server's administrative state to the
13968 DRAIN mode, thus it will not accept any new connections other than those
13969 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +090013970
Willy Tarreau81f5d942013-12-09 20:51:51 +010013971 - The word "maint". This will turn the server's administrative state to the
13972 MAINT mode, thus it will not accept any new connections at all, and health
13973 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +090013974
William Dauchyf8e795c2020-09-26 13:35:51 +020013975 - The words "down", "fail", or "stopped", optionally followed by a
Willy Tarreau81f5d942013-12-09 20:51:51 +010013976 description string after a sharp ('#'). All of these mark the server's
13977 operating state as DOWN, but since the word itself is reported on the stats
13978 page, the difference allows an administrator to know if the situation was
13979 expected or not : the service may intentionally be stopped, may appear up
Davor Ocelice9ed2812017-12-25 17:49:28 +010013980 but fail some validity tests, or may be seen as down (e.g. missing process,
Willy Tarreau81f5d942013-12-09 20:51:51 +010013981 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +090013982
Willy Tarreau81f5d942013-12-09 20:51:51 +010013983 - The word "up" sets back the server's operating state as UP if health checks
13984 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +090013985
Willy Tarreau81f5d942013-12-09 20:51:51 +010013986 Parameters which are not advertised by the agent are not changed. For
13987 example, an agent might be designed to monitor CPU usage and only report a
13988 relative weight and never interact with the operating status. Similarly, an
13989 agent could be designed as an end-user interface with 3 radio buttons
13990 allowing an administrator to change only the administrative state. However,
13991 it is important to consider that only the agent may revert its own actions,
13992 so if a server is set to DRAIN mode or to DOWN state using the agent, the
13993 agent must implement the other equivalent actions to bring the service into
13994 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +090013995
Simon Horman2f1f9552013-11-25 10:46:37 +090013996 Failure to connect to the agent is not considered an error as connectivity
13997 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +010013998 parameter. Warning though, it is not a good idea to stop an agent after it
13999 reports "down", since only an agent reporting "up" will be able to turn the
14000 server up again. Note that the CLI on the Unix stats socket is also able to
Willy Tarreau989222a2016-01-15 10:26:26 +010014001 force an agent's result in order to work around a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +090014002
Willy Tarreau81f5d942013-12-09 20:51:51 +010014003 Requires the "agent-port" parameter to be set. See also the "agent-inter"
Frédéric Lécailled2376272017-03-21 18:52:12 +010014004 and "no-agent-check" parameters.
Simon Hormand60d6912013-11-25 10:46:36 +090014005
James Brown55f9ff12015-10-21 18:19:05 -070014006agent-send <string>
Daniel Corbett9f0843f2021-05-08 10:50:37 -040014007 If this option is specified, HAProxy will send the given string (verbatim)
James Brown55f9ff12015-10-21 18:19:05 -070014008 to the agent server upon connection. You could, for example, encode
14009 the backend name into this string, which would enable your agent to send
14010 different responses based on the backend. Make sure to include a '\n' if
14011 you want to terminate your request with a newline.
14012
Simon Hormand60d6912013-11-25 10:46:36 +090014013agent-inter <delay>
14014 The "agent-inter" parameter sets the interval between two agent checks
14015 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
14016
14017 Just as with every other time-based parameter, it may be entered in any
14018 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
14019 parameter also serves as a timeout for agent checks "timeout check" is
14020 not set. In order to reduce "resonance" effects when multiple servers are
14021 hosted on the same hardware, the agent and health checks of all servers
14022 are started with a small time offset between them. It is also possible to
14023 add some random noise in the agent and health checks interval using the
14024 global "spread-checks" keyword. This makes sense for instance when a lot
14025 of backends use the same servers.
14026
14027 See also the "agent-check" and "agent-port" parameters.
14028
Misiek768d8602017-01-09 09:52:43 +010014029agent-addr <addr>
14030 The "agent-addr" parameter sets address for agent check.
14031
14032 You can offload agent-check to another target, so you can make single place
Daniel Corbett9f0843f2021-05-08 10:50:37 -040014033 managing status and weights of servers defined in HAProxy in case you can't
Misiek768d8602017-01-09 09:52:43 +010014034 make self-aware and self-managing services. You can specify both IP or
14035 hostname, it will be resolved.
14036
Simon Hormand60d6912013-11-25 10:46:36 +090014037agent-port <port>
14038 The "agent-port" parameter sets the TCP port used for agent checks.
14039
14040 See also the "agent-check" and "agent-inter" parameters.
14041
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020014042allow-0rtt
14043 Allow sending early data to the server when using TLS 1.3.
Olivier Houchard22c9b442019-05-06 19:01:04 +020014044 Note that early data will be sent only if the client used early data, or
14045 if the backend uses "retry-on" with the "0rtt-rejected" keyword.
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020014046
Olivier Houchardc7566002018-11-20 23:33:50 +010014047alpn <protocols>
14048 This enables the TLS ALPN extension and advertises the specified protocol
14049 list as supported on top of ALPN. The protocol list consists in a comma-
14050 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roeslerfb2fce12019-07-10 15:45:51 -050014051 quotes). This requires that the SSL library is built with support for TLS
Olivier Houchardc7566002018-11-20 23:33:50 +010014052 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
14053 initial NPN extension. ALPN is required to connect to HTTP/2 servers.
14054 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
14055 now obsolete NPN extension.
14056 If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can
14057 be advertised, in order of preference, like below :
14058
14059 server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1
14060
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014061backup
14062 When "backup" is present on a server line, the server is only used in load
14063 balancing when all other non-backup servers are unavailable. Requests coming
14064 with a persistence cookie referencing the server will always be served
14065 though. By default, only the first operational backup server is used, unless
Frédéric Lécailled2376272017-03-21 18:52:12 +010014066 the "allbackups" option is set in the backend. See also the "no-backup" and
14067 "allbackups" options.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014068
Emeric Brunef42d922012-10-11 16:11:36 +020014069ca-file <cafile>
14070 This setting is only available when support for OpenSSL was built in. It
14071 designates a PEM file from which to load CA certificates used to verify
14072 server's certificate.
14073
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014074check
Jerome Magnin90702bc2020-04-26 14:23:04 +020014075 This option enables health checks on a server:
14076 - when not set, no health checking is performed, and the server is always
14077 considered available.
14078 - when set and no other check method is configured, the server is considered
14079 available when a connection can be established at the highest configured
14080 transport layer. This means TCP by default, or SSL/TLS when "ssl" or
14081 "check-ssl" are set, both possibly combined with connection prefixes such
14082 as a PROXY protocol header when "send-proxy" or "check-send-proxy" are
14083 set.
14084 - when set and an application-level health check is defined, the
14085 application-level exchanges are performed on top of the configured
14086 transport layer and the server is considered available if all of the
14087 exchanges succeed.
14088
14089 By default, health checks are performed on the same address and port as
14090 configured on the server, using the same encapsulation parameters (SSL/TLS,
14091 proxy-protocol header, etc... ). It is possible to change the destination
14092 address using "addr" and the port using "port". When done, it is assumed the
14093 server isn't checked on the service port, and configured encapsulation
Ilya Shipitsin4329a9a2020-05-05 21:17:10 +050014094 parameters are not reused. One must explicitly set "check-send-proxy" to send
Jerome Magnin90702bc2020-04-26 14:23:04 +020014095 connection headers, "check-ssl" to use SSL/TLS.
14096
14097 When "sni" or "alpn" are set on the server line, their value is not used for
14098 health checks and one must use "check-sni" or "check-alpn".
14099
14100 The default source address for health check traffic is the same as the one
14101 defined in the backend. It can be changed with the "source" keyword.
14102
14103 The interval between checks can be set using the "inter" keyword, and the
14104 "rise" and "fall" keywords can be used to define how many successful or
14105 failed health checks are required to flag a server available or not
14106 available.
14107
14108 Optional application-level health checks can be configured with "option
14109 httpchk", "option mysql-check" "option smtpchk", "option pgsql-check",
14110 "option ldap-check", or "option redis-check".
14111
14112 Example:
14113 # simple tcp check
14114 backend foo
14115 server s1 192.168.0.1:80 check
14116 # this does a tcp connect + tls handshake
14117 backend foo
14118 server s1 192.168.0.1:443 ssl check
14119 # simple tcp check is enough for check success
14120 backend foo
14121 option tcp-check
14122 tcp-check connect
14123 server s1 192.168.0.1:443 ssl check
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014124
Willy Tarreau6c16adc2012-10-05 00:04:16 +020014125check-send-proxy
14126 This option forces emission of a PROXY protocol line with outgoing health
14127 checks, regardless of whether the server uses send-proxy or not for the
14128 normal traffic. By default, the PROXY protocol is enabled for health checks
14129 if it is already enabled for normal traffic and if no "port" nor "addr"
14130 directive is present. However, if such a directive is present, the
14131 "check-send-proxy" option needs to be used to force the use of the
14132 protocol. See also the "send-proxy" option for more information.
14133
Olivier Houchard92150142018-12-21 19:47:01 +010014134check-alpn <protocols>
14135 Defines which protocols to advertise with ALPN. The protocol list consists in
14136 a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0"
14137 (without quotes). If it is not set, the server ALPN is used.
14138
Christopher Fauletedc6ed92020-04-23 16:27:59 +020014139check-proto <name>
14140 Forces the multiplexer's protocol to use for the server's health-check
14141 connections. It must be compatible with the health-check type (TCP or
14142 HTTP). It must also be usable on the backend side. The list of available
Christopher Faulet982e17d2021-03-26 14:44:18 +010014143 protocols is reported in haproxy -vv. The protocols properties are
14144 reported : the mode (TCP/HTTP), the side (FE/BE), the mux name and its flags.
14145
14146 Some protocols report errors on aborts (flag=CLEAN_ABRT). Some others are
14147 subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally
14148 some protocols don't support upgrades (flag=NO_UPG). The HTX compatibility is
14149 also reported (flag=HTX).
14150
14151 Here are the protocols that may be used as argument to a "check-proto"
14152 directive on a server line:
14153
14154 h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|CLEAN_ABRT|HOL_RISK|NO_UPG
14155 fcgi : mode=HTTP side=BE mux=FCGI flags=HTX|HOL_RISK|NO_UPG
14156 h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG
14157 none : mode=TCP side=FE|BE mux=PASS flags=NO_UPG
14158
Daniel Corbett67a82712020-07-06 23:01:19 -040014159 Idea behind this option is to bypass the selection of the best multiplexer's
Christopher Fauletedc6ed92020-04-23 16:27:59 +020014160 protocol for health-check connections established to this server.
14161 If not defined, the server one will be used, if set.
14162
Jérôme Magninae9bb762018-12-09 16:08:26 +010014163check-sni <sni>
Olivier Houchard9130a962017-10-17 17:33:43 +020014164 This option allows you to specify the SNI to be used when doing health checks
Jérôme Magninae9bb762018-12-09 16:08:26 +010014165 over SSL. It is only possible to use a string to set <sni>. If you want to
14166 set a SNI for proxied traffic, see "sni".
Olivier Houchard9130a962017-10-17 17:33:43 +020014167
Willy Tarreau763a95b2012-10-04 23:15:39 +020014168check-ssl
14169 This option forces encryption of all health checks over SSL, regardless of
14170 whether the server uses SSL or not for the normal traffic. This is generally
14171 used when an explicit "port" or "addr" directive is specified and SSL health
14172 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014173 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +020014174 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
14175 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
Davor Ocelice9ed2812017-12-25 17:49:28 +010014176 All SSL settings are common to health checks and traffic (e.g. ciphers).
Frédéric Lécailled2376272017-03-21 18:52:12 +010014177 See the "ssl" option for more information and "no-check-ssl" to disable
14178 this option.
Willy Tarreau763a95b2012-10-04 23:15:39 +020014179
Alexander Liu2a54bb72019-05-22 19:44:48 +080014180check-via-socks4
John Roeslerfb2fce12019-07-10 15:45:51 -050014181 This option enables outgoing health checks using upstream socks4 proxy. By
Alexander Liu2a54bb72019-05-22 19:44:48 +080014182 default, the health checks won't go through socks tunnel even it was enabled
14183 for normal traffic.
14184
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014185ciphers <ciphers>
Dirkjan Bussink415150f2018-09-14 11:14:21 +020014186 This setting is only available when support for OpenSSL was built in. This
14187 option sets the string describing the list of cipher algorithms that is
14188 negotiated during the SSL/TLS handshake with the server. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000014189 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
14190 information and recommendations see e.g.
14191 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
14192 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
14193 cipher configuration, please check the "ciphersuites" keyword.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014194
Dirkjan Bussink415150f2018-09-14 11:14:21 +020014195ciphersuites <ciphersuites>
14196 This setting is only available when support for OpenSSL was built in and
14197 OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string
14198 describing the list of cipher algorithms that is negotiated during the TLS
14199 1.3 handshake with the server. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000014200 "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section.
14201 For cipher configuration for TLSv1.2 and earlier, please check the "ciphers"
14202 keyword.
Dirkjan Bussink415150f2018-09-14 11:14:21 +020014203
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014204cookie <value>
14205 The "cookie" parameter sets the cookie value assigned to the server to
14206 <value>. This value will be checked in incoming requests, and the first
14207 operational server possessing the same value will be selected. In return, in
14208 cookie insertion or rewrite modes, this value will be assigned to the cookie
14209 sent to the client. There is nothing wrong in having several servers sharing
14210 the same cookie value, and it is in fact somewhat common between normal and
14211 backup servers. See also the "cookie" keyword in backend section.
14212
Emeric Brunef42d922012-10-11 16:11:36 +020014213crl-file <crlfile>
14214 This setting is only available when support for OpenSSL was built in. It
14215 designates a PEM file from which to load certificate revocation list used
14216 to verify server's certificate.
14217
Emeric Bruna7aa3092012-10-26 12:58:00 +020014218crt <cert>
14219 This setting is only available when support for OpenSSL was built in.
14220 It designates a PEM file from which to load both a certificate and the
14221 associated private key. This file can be built by concatenating both PEM
14222 files into one. This certificate will be sent if the server send a client
14223 certificate request.
14224
Remi Tricot-Le Breton7c980df2021-05-07 15:28:08 +020014225 If the file does not contain a private key, HAProxy will try to load the key
14226 at the same path suffixed by a ".key" (provided the "ssl-load-extra-files"
14227 option is set accordingly).
14228
Willy Tarreau96839092010-03-29 10:02:24 +020014229disabled
14230 The "disabled" keyword starts the server in the "disabled" state. That means
14231 that it is marked down in maintenance mode, and no connection other than the
14232 ones allowed by persist mode will reach it. It is very well suited to setup
14233 new servers, because normal traffic will never reach them, while it is still
14234 possible to test the service by making use of the force-persist mechanism.
Frédéric Lécailled2376272017-03-21 18:52:12 +010014235 See also "enabled" setting.
Willy Tarreau96839092010-03-29 10:02:24 +020014236
Frédéric Lécailled2376272017-03-21 18:52:12 +010014237enabled
14238 This option may be used as 'server' setting to reset any 'disabled'
14239 setting which would have been inherited from 'default-server' directive as
14240 default value.
14241 It may also be used as 'default-server' setting to reset any previous
14242 'default-server' 'disabled' setting.
Willy Tarreau96839092010-03-29 10:02:24 +020014243
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014244error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +010014245 If health observing is enabled, the "error-limit" parameter specifies the
14246 number of consecutive errors that triggers event selected by the "on-error"
14247 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010014248
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014249 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010014250
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014251fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014252 The "fall" parameter states that a server will be considered as dead after
14253 <count> consecutive unsuccessful health checks. This value defaults to 3 if
14254 unspecified. See also the "check", "inter" and "rise" parameters.
14255
Emeric Brun8694b9a2012-10-05 14:39:07 +020014256force-sslv3
14257 This option enforces use of SSLv3 only when SSL is used to communicate with
14258 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014259 high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014260 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020014261
14262force-tlsv10
14263 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014264 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014265 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020014266
14267force-tlsv11
14268 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014269 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014270 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020014271
14272force-tlsv12
14273 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014274 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014275 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020014276
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020014277force-tlsv13
14278 This option enforces use of TLSv1.3 only when SSL is used to communicate with
14279 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014280 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020014281
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014282id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +020014283 Set a persistent ID for the server. This ID must be positive and unique for
14284 the proxy. An unused ID will automatically be assigned if unset. The first
14285 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014286
Willy Tarreau6a031d12016-11-07 19:42:35 +010014287init-addr {last | libc | none | <ip>},[...]*
14288 Indicate in what order the server's address should be resolved upon startup
14289 if it uses an FQDN. Attempts are made to resolve the address by applying in
Davor Ocelice9ed2812017-12-25 17:49:28 +010014290 turn each of the methods mentioned in the comma-delimited list. The first
Willy Tarreau6a031d12016-11-07 19:42:35 +010014291 method which succeeds is used. If the end of the list is reached without
14292 finding a working method, an error is thrown. Method "last" suggests to pick
14293 the address which appears in the state file (see "server-state-file"). Method
14294 "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
14295 depending on the operating system and build options). Method "none"
14296 specifically indicates that the server should start without any valid IP
14297 address in a down state. It can be useful to ignore some DNS issues upon
14298 startup, waiting for the situation to get fixed later. Finally, an IP address
14299 (IPv4 or IPv6) may be provided. It can be the currently known address of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010014300 server (e.g. filled by a configuration generator), or the address of a dummy
Willy Tarreau6a031d12016-11-07 19:42:35 +010014301 server used to catch old sessions and present them with a decent error
14302 message for example. When the "first" load balancing algorithm is used, this
14303 IP address could point to a fake server used to trigger the creation of new
14304 instances on the fly. This option defaults to "last,libc" indicating that the
14305 previous address found in the state file (if any) is used first, otherwise
14306 the libc's resolver is used. This ensures continued compatibility with the
Davor Ocelice9ed2812017-12-25 17:49:28 +010014307 historic behavior.
Willy Tarreau6a031d12016-11-07 19:42:35 +010014308
14309 Example:
14310 defaults
14311 # never fail on address resolution
14312 default-server init-addr last,libc,none
14313
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014314inter <delay>
14315fastinter <delay>
14316downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014317 The "inter" parameter sets the interval between two consecutive health checks
14318 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
14319 It is also possible to use "fastinter" and "downinter" to optimize delays
14320 between checks depending on the server state :
14321
Pieter Baauw44fc9df2015-09-17 21:30:46 +020014322 Server state | Interval used
14323 ----------------------------------------+----------------------------------
14324 UP 100% (non-transitional) | "inter"
14325 ----------------------------------------+----------------------------------
14326 Transitionally UP (going down "fall"), | "fastinter" if set,
14327 Transitionally DOWN (going up "rise"), | "inter" otherwise.
14328 or yet unchecked. |
14329 ----------------------------------------+----------------------------------
14330 DOWN 100% (non-transitional) | "downinter" if set,
14331 | "inter" otherwise.
14332 ----------------------------------------+----------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +010014333
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014334 Just as with every other time-based parameter, they can be entered in any
14335 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
14336 serves as a timeout for health checks sent to servers if "timeout check" is
14337 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +090014338 hosted on the same hardware, the agent and health checks of all servers
14339 are started with a small time offset between them. It is also possible to
14340 add some random noise in the agent and health checks interval using the
14341 global "spread-checks" keyword. This makes sense for instance when a lot
14342 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014343
Emeric Brun97556472020-05-30 01:42:45 +020014344log-proto <logproto>
14345 The "log-proto" specifies the protocol used to forward event messages to
14346 a server configured in a ring section. Possible values are "legacy"
14347 and "octet-count" corresponding respectively to "Non-transparent-framing"
14348 and "Octet counting" in rfc6587. "legacy" is the default.
14349
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014350maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014351 The "maxconn" parameter specifies the maximal number of concurrent
14352 connections that will be sent to this server. If the number of incoming
Tim Duesterhuscefbbd92019-11-27 22:35:27 +010014353 concurrent connections goes higher than this value, they will be queued,
14354 waiting for a slot to be released. This parameter is very important as it can
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014355 save fragile servers from going down under extreme loads. If a "minconn"
14356 parameter is specified, the limit becomes dynamic. The default value is "0"
14357 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
14358 the backend's "fullconn" keyword.
14359
Tim Duesterhuscefbbd92019-11-27 22:35:27 +010014360 In HTTP mode this parameter limits the number of concurrent requests instead
14361 of the number of connections. Multiple requests might be multiplexed over a
14362 single TCP connection to the server. As an example if you specify a maxconn
14363 of 50 you might see between 1 and 50 actual server connections, but no more
14364 than 50 concurrent requests.
14365
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014366maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014367 The "maxqueue" parameter specifies the maximal number of connections which
14368 will wait in the queue for this server. If this limit is reached, next
14369 requests will be redispatched to other servers instead of indefinitely
14370 waiting to be served. This will break persistence but may allow people to
Willy Tarreau8ae8c482020-10-22 17:19:07 +020014371 quickly re-log in when the server they try to connect to is dying. Some load
14372 balancing algorithms such as leastconn take this into account and accept to
14373 add requests into a server's queue up to this value if it is explicitly set
14374 to a value greater than zero, which often allows to better smooth the load
14375 when dealing with single-digit maxconn values. The default value is "0" which
14376 means the queue is unlimited. See also the "maxconn" and "minconn" parameters
14377 and "balance leastconn".
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014378
Willy Tarreau9c538e02019-01-23 10:21:49 +010014379max-reuse <count>
14380 The "max-reuse" argument indicates the HTTP connection processors that they
14381 should not reuse a server connection more than this number of times to send
14382 new requests. Permitted values are -1 (the default), which disables this
14383 limit, or any positive value. Value zero will effectively disable keep-alive.
14384 This is only used to work around certain server bugs which cause them to leak
14385 resources over time. The argument is not necessarily respected by the lower
14386 layers as there might be technical limitations making it impossible to
14387 enforce. At least HTTP/2 connections to servers will respect it.
14388
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014389minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014390 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
14391 limit following the backend's load. The server will always accept at least
14392 <minconn> connections, never more than <maxconn>, and the limit will be on
14393 the ramp between both values when the backend has less than <fullconn>
14394 concurrent connections. This makes it possible to limit the load on the
14395 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014396 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014397 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010014398
Willy Tarreaud72f0f32015-10-13 14:50:22 +020014399namespace <name>
14400 On Linux, it is possible to specify which network namespace a socket will
14401 belong to. This directive makes it possible to explicitly bind a server to
14402 a namespace different from the default one. Please refer to your operating
14403 system's documentation to find more details about network namespaces.
14404
Frédéric Lécailled2376272017-03-21 18:52:12 +010014405no-agent-check
14406 This option may be used as "server" setting to reset any "agent-check"
14407 setting which would have been inherited from "default-server" directive as
14408 default value.
14409 It may also be used as "default-server" setting to reset any previous
14410 "default-server" "agent-check" setting.
14411
14412no-backup
14413 This option may be used as "server" setting to reset any "backup"
14414 setting which would have been inherited from "default-server" directive as
14415 default value.
14416 It may also be used as "default-server" setting to reset any previous
14417 "default-server" "backup" setting.
14418
14419no-check
14420 This option may be used as "server" setting to reset any "check"
14421 setting which would have been inherited from "default-server" directive as
14422 default value.
14423 It may also be used as "default-server" setting to reset any previous
14424 "default-server" "check" setting.
14425
14426no-check-ssl
14427 This option may be used as "server" setting to reset any "check-ssl"
14428 setting which would have been inherited from "default-server" directive as
14429 default value.
14430 It may also be used as "default-server" setting to reset any previous
14431 "default-server" "check-ssl" setting.
14432
Frédéric Lécailled2376272017-03-21 18:52:12 +010014433no-send-proxy
14434 This option may be used as "server" setting to reset any "send-proxy"
14435 setting which would have been inherited from "default-server" directive as
14436 default value.
14437 It may also be used as "default-server" setting to reset any previous
14438 "default-server" "send-proxy" setting.
14439
14440no-send-proxy-v2
14441 This option may be used as "server" setting to reset any "send-proxy-v2"
14442 setting which would have been inherited from "default-server" directive as
14443 default value.
14444 It may also be used as "default-server" setting to reset any previous
14445 "default-server" "send-proxy-v2" setting.
14446
14447no-send-proxy-v2-ssl
14448 This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
14449 setting which would have been inherited from "default-server" directive as
14450 default value.
14451 It may also be used as "default-server" setting to reset any previous
14452 "default-server" "send-proxy-v2-ssl" setting.
14453
14454no-send-proxy-v2-ssl-cn
14455 This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
14456 setting which would have been inherited from "default-server" directive as
14457 default value.
14458 It may also be used as "default-server" setting to reset any previous
14459 "default-server" "send-proxy-v2-ssl-cn" setting.
14460
14461no-ssl
14462 This option may be used as "server" setting to reset any "ssl"
14463 setting which would have been inherited from "default-server" directive as
14464 default value.
14465 It may also be used as "default-server" setting to reset any previous
14466 "default-server" "ssl" setting.
14467
William Dauchyf6370442020-11-14 19:25:33 +010014468 Note that using `default-server ssl` setting and `no-ssl` on server will
14469 however init SSL connection, so it can be later be enabled through the
14470 runtime API: see `set server` commands in management doc.
14471
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010014472no-ssl-reuse
14473 This option disables SSL session reuse when SSL is used to communicate with
14474 the server. It will force the server to perform a full handshake for every
14475 new connection. It's probably only useful for benchmarking, troubleshooting,
14476 and for paranoid users.
14477
Emeric Brun9b3009b2012-10-05 11:55:06 +020014478no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014479 This option disables support for SSLv3 when SSL is used to communicate with
14480 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014481 using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014482
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020014483 Supported in default-server: No
14484
Emeric Brunf9c5c472012-10-11 15:28:34 +020014485no-tls-tickets
14486 This setting is only available when support for OpenSSL was built in. It
14487 disables the stateless session resumption (RFC 5077 TLS Ticket
14488 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014489 session resumption is more expensive in CPU usage for servers. This option
14490 is also available on global statement "ssl-default-server-options".
Lukas Tribusbdb386d2020-03-10 00:56:09 +010014491 The TLS ticket mechanism is only used up to TLS 1.2.
14492 Forward Secrecy is compromised with TLS tickets, unless ticket keys
14493 are periodically rotated (via reload or by using "tls-ticket-keys").
Frédéric Lécailled2376272017-03-21 18:52:12 +010014494 See also "tls-tickets".
Emeric Brunf9c5c472012-10-11 15:28:34 +020014495
Emeric Brun9b3009b2012-10-05 11:55:06 +020014496no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020014497 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020014498 the server. Note that SSLv2 is disabled in the code and cannot be enabled
14499 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014500 often makes sense to disable it when communicating with local servers. This
14501 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014502 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020014503
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020014504 Supported in default-server: No
14505
Emeric Brun9b3009b2012-10-05 11:55:06 +020014506no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020014507 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020014508 the server. Note that SSLv2 is disabled in the code and cannot be enabled
14509 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014510 often makes sense to disable it when communicating with local servers. This
14511 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014512 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020014513
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020014514 Supported in default-server: No
14515
Emeric Brun9b3009b2012-10-05 11:55:06 +020014516no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020014517 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014518 the server. Note that SSLv2 is disabled in the code and cannot be enabled
14519 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010014520 often makes sense to disable it when communicating with local servers. This
14521 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014522 Use "ssl-min-ver" and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020014523
14524 Supported in default-server: No
14525
14526no-tlsv13
14527 This option disables support for TLSv1.3 when SSL is used to communicate with
14528 the server. Note that SSLv2 is disabled in the code and cannot be enabled
14529 using any configuration option. TLSv1 is more expensive than SSLv3 so it
14530 often makes sense to disable it when communicating with local servers. This
14531 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014532 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014533
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020014534 Supported in default-server: No
14535
Frédéric Lécailled2376272017-03-21 18:52:12 +010014536no-verifyhost
14537 This option may be used as "server" setting to reset any "verifyhost"
14538 setting which would have been inherited from "default-server" directive as
14539 default value.
14540 It may also be used as "default-server" setting to reset any previous
14541 "default-server" "verifyhost" setting.
Willy Tarreau763a95b2012-10-04 23:15:39 +020014542
Frédéric Lécaille1b9423d2019-07-04 14:19:06 +020014543no-tfo
14544 This option may be used as "server" setting to reset any "tfo"
14545 setting which would have been inherited from "default-server" directive as
14546 default value.
14547 It may also be used as "default-server" setting to reset any previous
14548 "default-server" "tfo" setting.
14549
Simon Hormanfa461682011-06-25 09:39:49 +090014550non-stick
14551 Never add connections allocated to this sever to a stick-table.
14552 This may be used in conjunction with backup to ensure that
14553 stick-table persistence is disabled for backup servers.
14554
Olivier Houchardc7566002018-11-20 23:33:50 +010014555npn <protocols>
14556 This enables the NPN TLS extension and advertises the specified protocol list
14557 as supported on top of NPN. The protocol list consists in a comma-delimited
14558 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roeslerfb2fce12019-07-10 15:45:51 -050014559 This requires that the SSL library is built with support for TLS extensions
Olivier Houchardc7566002018-11-20 23:33:50 +010014560 enabled (check with haproxy -vv). Note that the NPN extension has been
14561 replaced with the ALPN extension (see the "alpn" keyword), though this one is
14562 only available starting with OpenSSL 1.0.2.
14563
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010014564observe <mode>
14565 This option enables health adjusting based on observing communication with
14566 the server. By default this functionality is disabled and enabling it also
14567 requires to enable health checks. There are two supported modes: "layer4" and
14568 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
14569 significant. In layer7, which is only allowed for http proxies, responses
14570 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010014571 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010014572
14573 See also the "check", "on-error" and "error-limit".
14574
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014575on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010014576 Select what should happen when enough consecutive errors are detected.
14577 Currently, four modes are available:
14578 - fastinter: force fastinter
14579 - fail-check: simulate a failed check, also forces fastinter (default)
14580 - sudden-death: simulate a pre-fatal failed health check, one more failed
14581 check will mark a server down, forces fastinter
14582 - mark-down: mark the server immediately down and force fastinter
14583
14584 See also the "check", "observe" and "error-limit".
14585
Simon Hormane0d1bfb2011-06-21 14:34:58 +090014586on-marked-down <action>
14587 Modify what occurs when a server is marked down.
14588 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070014589 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
14590 all connections to the server are immediately terminated when the server
14591 goes down. It might be used if the health check detects more complex cases
14592 than a simple connection status, and long timeouts would cause the service
14593 to remain unresponsive for too long a time. For instance, a health check
14594 might detect that a database is stuck and that there's no chance to reuse
14595 existing connections anymore. Connections killed this way are logged with
14596 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090014597
14598 Actions are disabled by default
14599
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070014600on-marked-up <action>
14601 Modify what occurs when a server is marked up.
14602 Currently one action is available:
14603 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
14604 done only if the server is not in backup state and if it is not disabled
14605 (it must have an effective weight > 0). This can be used sometimes to force
14606 an active server to take all the traffic back after recovery when dealing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014607 with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble
14608 than it tries to solve (e.g. incomplete transactions), so use this feature
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070014609 with extreme care. Sessions killed because a server comes up are logged
14610 with an 'U' termination code (for "Up").
14611
14612 Actions are disabled by default
14613
Willy Tarreau2f3f4d32020-07-01 07:43:51 +020014614pool-low-conn <max>
14615 Set a low threshold on the number of idling connections for a server, below
14616 which a thread will not try to steal a connection from another thread. This
14617 can be useful to improve CPU usage patterns in scenarios involving many very
14618 fast servers, in order to ensure all threads will keep a few idle connections
14619 all the time instead of letting them accumulate over one thread and migrating
14620 them from thread to thread. Typical values of twice the number of threads
14621 seem to show very good performance already with sub-millisecond response
14622 times. The default is zero, indicating that any idle connection can be used
14623 at any time. It is the recommended setting for normal use. This only applies
14624 to connections that can be shared according to the same principles as those
Willy Tarreau0784db82021-02-19 11:45:22 +010014625 applying to "http-reuse". In case connection sharing between threads would
14626 be disabled via "tune.idle-pool.shared", it can become very important to use
14627 this setting to make sure each thread always has a few connections, or the
14628 connection reuse rate will decrease as thread count increases.
Willy Tarreau2f3f4d32020-07-01 07:43:51 +020014629
Olivier Houchard006e3102018-12-10 18:30:32 +010014630pool-max-conn <max>
14631 Set the maximum number of idling connections for a server. -1 means unlimited
14632 connections, 0 means no idle connections. The default is -1. When idle
14633 connections are enabled, orphaned idle connections which do not belong to any
14634 client session anymore are moved to a dedicated pool so that they remain
14635 usable by future clients. This only applies to connections that can be shared
14636 according to the same principles as those applying to "http-reuse".
14637
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010014638pool-purge-delay <delay>
14639 Sets the delay to start purging idle connections. Each <delay> interval, half
Olivier Houcharda56eebf2019-03-19 16:44:02 +010014640 of the idle connections are closed. 0 means we don't keep any idle connection.
Willy Tarreaufb553652019-06-04 14:06:31 +020014641 The default is 5s.
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010014642
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014643port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014644 Using the "port" parameter, it becomes possible to use a different port to
William Dauchy4858fb22021-02-03 22:30:09 +010014645 send health-checks or to probe the agent-check. On some servers, it may be
14646 desirable to dedicate a port to a specific component able to perform complex
14647 tests which are more suitable to health-checks than the application. It is
14648 common to run a simple script in inetd for instance. This parameter is
14649 ignored if the "check" parameter is not set. See also the "addr" parameter.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014650
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020014651proto <name>
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020014652 Forces the multiplexer's protocol to use for the outgoing connections to this
14653 server. It must be compatible with the mode of the backend (TCP or HTTP). It
14654 must also be usable on the backend side. The list of available protocols is
Christopher Faulet982e17d2021-03-26 14:44:18 +010014655 reported in haproxy -vv.The protocols properties are reported : the mode
14656 (TCP/HTTP), the side (FE/BE), the mux name and its flags.
14657
14658 Some protocols report errors on aborts (flag=CLEAN_ABRT). Some others are
14659 subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally
14660 some protocols don't support upgrades (flag=NO_UPG). The HTX compatibility is
14661 also reported (flag=HTX).
14662
14663 Here are the protocols that may be used as argument to a "proto" directive on
14664 a server line :
14665
14666 h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|CLEAN_ABRT|HOL_RISK|NO_UPG
14667 fcgi : mode=HTTP side=BE mux=FCGI flags=HTX|HOL_RISK|NO_UPG
14668 h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG
14669 none : mode=TCP side=FE|BE mux=PASS flags=NO_UPG
14670
Daniel Corbett67a82712020-07-06 23:01:19 -040014671 Idea behind this option is to bypass the selection of the best multiplexer's
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020014672 protocol for all connections established to this server.
14673
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014674redir <prefix>
14675 The "redir" parameter enables the redirection mode for all GET and HEAD
14676 requests addressing this server. This means that instead of having HAProxy
14677 forward the request to the server, it will send an "HTTP 302" response with
14678 the "Location" header composed of this prefix immediately followed by the
14679 requested URI beginning at the leading '/' of the path component. That means
14680 that no trailing slash should be used after <prefix>. All invalid requests
14681 will be rejected, and all non-GET or HEAD requests will be normally served by
14682 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014683 mangling nor cookie insertion is possible in the response. However, cookies in
Davor Ocelice9ed2812017-12-25 17:49:28 +010014684 requests are still analyzed, making this solution completely usable to direct
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014685 users to a remote location in case of local disaster. Main use consists in
14686 increasing bandwidth for static servers by having the clients directly
14687 connect to them. Note: never use a relative location here, it would cause a
14688 loop between the client and HAProxy!
14689
14690 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
14691
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014692rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014693 The "rise" parameter states that a server will be considered as operational
14694 after <count> consecutive successful health checks. This value defaults to 2
14695 if unspecified. See also the "check", "inter" and "fall" parameters.
14696
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020014697resolve-opts <option>,<option>,...
14698 Comma separated list of options to apply to DNS resolution linked to this
14699 server.
14700
14701 Available options:
14702
14703 * allow-dup-ip
14704 By default, HAProxy prevents IP address duplication in a backend when DNS
14705 resolution at runtime is in operation.
14706 That said, for some cases, it makes sense that two servers (in the same
14707 backend, being resolved by the same FQDN) have the same IP address.
14708 For such case, simply enable this option.
14709 This is the opposite of prevent-dup-ip.
14710
Daniel Corbettf8716912019-11-17 09:48:56 -050014711 * ignore-weight
14712 Ignore any weight that is set within an SRV record. This is useful when
14713 you would like to control the weights using an alternate method, such as
14714 using an "agent-check" or through the runtime api.
14715
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020014716 * prevent-dup-ip
14717 Ensure HAProxy's default behavior is enforced on a server: prevent re-using
14718 an IP address already set to a server in the same backend and sharing the
14719 same fqdn.
14720 This is the opposite of allow-dup-ip.
14721
14722 Example:
14723 backend b_myapp
14724 default-server init-addr none resolvers dns
14725 server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
14726 server s2 myapp.example.com:81 check resolve-opts allow-dup-ip
14727
14728 With the option allow-dup-ip set:
14729 * if the nameserver returns a single IP address, then both servers will use
14730 it
14731 * If the nameserver returns 2 IP addresses, then each server will pick up a
14732 different address
14733
14734 Default value: not set
14735
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014736resolve-prefer <family>
14737 When DNS resolution is enabled for a server and multiple IP addresses from
14738 different families are returned, HAProxy will prefer using an IP address
14739 from the family mentioned in the "resolve-prefer" parameter.
14740 Available families: "ipv4" and "ipv6"
14741
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020014742 Default value: ipv6
14743
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020014744 Example:
14745
14746 server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014747
Thierry Fournierac88cfe2016-02-17 22:05:30 +010014748resolve-net <network>[,<network[,...]]
John Roeslerfb2fce12019-07-10 15:45:51 -050014749 This option prioritizes the choice of an ip address matching a network. This is
Thierry Fournierac88cfe2016-02-17 22:05:30 +010014750 useful with clouds to prefer a local ip. In some cases, a cloud high
Tim Düsterhus4896c442016-11-29 02:15:19 +010014751 availability service can be announced with many ip addresses on many
Davor Ocelice9ed2812017-12-25 17:49:28 +010014752 different datacenters. The latency between datacenter is not negligible, so
14753 this patch permits to prefer a local datacenter. If no address matches the
Thierry Fournierac88cfe2016-02-17 22:05:30 +010014754 configured network, another address is selected.
14755
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020014756 Example:
14757
14758 server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8
Thierry Fournierac88cfe2016-02-17 22:05:30 +010014759
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014760resolvers <id>
14761 Points to an existing "resolvers" section to resolve current server's
14762 hostname.
14763
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020014764 Example:
14765
14766 server s1 app1.domain.com:80 check resolvers mydns
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014767
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020014768 See also section 5.3
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014769
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010014770send-proxy
14771 The "send-proxy" parameter enforces use of the PROXY protocol over any
14772 connection established to this server. The PROXY protocol informs the other
14773 end about the layer 3/4 addresses of the incoming connection, so that it can
14774 know the client's address or the public address it accessed to, whatever the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010014775 upper layer protocol. For connections accepted by an "accept-proxy" or
14776 "accept-netscaler-cip" listener, the advertised address will be used. Only
14777 TCPv4 and TCPv6 address families are supported. Other families such as
14778 Unix sockets, will report an UNKNOWN family. Servers using this option can
Daniel Corbett9f0843f2021-05-08 10:50:37 -040014779 fully be chained to another instance of HAProxy listening with an
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010014780 "accept-proxy" setting. This setting must not be used if the server isn't
14781 aware of the protocol. When health checks are sent to the server, the PROXY
14782 protocol is automatically used when this option is set, unless there is an
14783 explicit "port" or "addr" directive, in which case an explicit
14784 "check-send-proxy" directive would also be needed to use the PROXY protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010014785 See also the "no-send-proxy" option of this section and "accept-proxy" and
14786 "accept-netscaler-cip" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010014787
David Safb76832014-05-08 23:42:08 -040014788send-proxy-v2
14789 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
14790 over any connection established to this server. The PROXY protocol informs
14791 the other end about the layer 3/4 addresses of the incoming connection, so
14792 that it can know the client's address or the public address it accessed to,
Emmanuel Hocdet404d9782017-10-24 10:55:14 +020014793 whatever the upper layer protocol. It also send ALPN information if an alpn
14794 have been negotiated. This setting must not be used if the server isn't aware
14795 of this version of the protocol. See also the "no-send-proxy-v2" option of
14796 this section and send-proxy" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040014797
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010014798proxy-v2-options <option>[,<option>]*
Tim Duesterhuscf6e0c82020-03-13 12:34:24 +010014799 The "proxy-v2-options" parameter add options to send in PROXY protocol
14800 version 2 when "send-proxy-v2" is used. Options available are:
14801
14802 - ssl : See also "send-proxy-v2-ssl".
14803 - cert-cn : See also "send-proxy-v2-ssl-cn".
14804 - ssl-cipher: Name of the used cipher.
14805 - cert-sig : Signature algorithm of the used certificate.
14806 - cert-key : Key algorithm of the used certificate
14807 - authority : Host name value passed by the client (only SNI from a TLS
14808 connection is supported).
14809 - crc32c : Checksum of the PROXYv2 header.
14810 - unique-id : Send a unique ID generated using the frontend's
14811 "unique-id-format" within the PROXYv2 header.
14812 This unique-id is primarily meant for "mode tcp". It can
14813 lead to unexpected results in "mode http", because the
14814 generated unique ID is also used for the first HTTP request
14815 within a Keep-Alive connection.
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010014816
David Safb76832014-05-08 23:42:08 -040014817send-proxy-v2-ssl
14818 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
14819 2 over any connection established to this server. The PROXY protocol informs
14820 the other end about the layer 3/4 addresses of the incoming connection, so
14821 that it can know the client's address or the public address it accessed to,
14822 whatever the upper layer protocol. In addition, the SSL information extension
14823 of the PROXY protocol is added to the PROXY protocol header. This setting
14824 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 +010014825 See also the "no-send-proxy-v2-ssl" option of this section and the
14826 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040014827
14828send-proxy-v2-ssl-cn
14829 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
14830 2 over any connection established to this server. The PROXY protocol informs
14831 the other end about the layer 3/4 addresses of the incoming connection, so
14832 that it can know the client's address or the public address it accessed to,
14833 whatever the upper layer protocol. In addition, the SSL information extension
14834 of the PROXY protocol, along along with the Common Name from the subject of
14835 the client certificate (if any), is added to the PROXY protocol header. This
14836 setting must not be used if the server isn't aware of this version of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010014837 protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and
14838 the "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040014839
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014840slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014841 The "slowstart" parameter for a server accepts a value in milliseconds which
14842 indicates after how long a server which has just come back up will run at
14843 full speed. Just as with every other time-based parameter, it can be entered
14844 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
14845 linearly from 0 to 100% during this time. The limitation applies to two
14846 parameters :
14847
14848 - maxconn: the number of connections accepted by the server will grow from 1
14849 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
14850
14851 - weight: when the backend uses a dynamic weighted algorithm, the weight
14852 grows linearly from 1 to 100%. In this case, the weight is updated at every
14853 health-check. For this reason, it is important that the "inter" parameter
14854 is smaller than the "slowstart", in order to maximize the number of steps.
14855
Daniel Corbett9f0843f2021-05-08 10:50:37 -040014856 The slowstart never applies when HAProxy starts, otherwise it would cause
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014857 trouble to running servers. It only applies when a server has been previously
14858 seen as failed.
14859
Willy Tarreau732eac42015-07-09 11:40:25 +020014860sni <expression>
14861 The "sni" parameter evaluates the sample fetch expression, converts it to a
14862 string and uses the result as the host name sent in the SNI TLS extension to
14863 the server. A typical use case is to send the SNI received from the client in
14864 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
Willy Tarreau2ab88672017-07-05 18:23:03 +020014865 expression, though alternatives such as req.hdr(host) can also make sense. If
14866 "verify required" is set (which is the recommended setting), the resulting
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014867 name will also be matched against the server certificate's names. See the
Jérôme Magninb36a6d22018-12-09 16:03:40 +010014868 "verify" directive for more details. If you want to set a SNI for health
14869 checks, see the "check-sni" directive for more details.
Willy Tarreau732eac42015-07-09 11:40:25 +020014870
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020014871source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020014872source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020014873source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014874 The "source" parameter sets the source address which will be used when
14875 connecting to the server. It follows the exact same parameters and principle
14876 as the backend "source" keyword, except that it only applies to the server
14877 referencing it. Please consult the "source" keyword for details.
14878
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020014879 Additionally, the "source" statement on a server line allows one to specify a
14880 source port range by indicating the lower and higher bounds delimited by a
14881 dash ('-'). Some operating systems might require a valid IP address when a
14882 source port range is specified. It is permitted to have the same IP/range for
14883 several servers. Doing so makes it possible to bypass the maximum of 64k
14884 total concurrent connections. The limit will then reach 64k connections per
14885 server.
14886
Lukas Tribus7d56c6d2016-09-13 09:51:15 +000014887 Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
14888 specifying the source address without port(s).
14889
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014890ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020014891 This option enables SSL ciphering on outgoing connections to the server. It
14892 is critical to verify server certificates using "verify" when using SSL to
14893 connect to servers, otherwise the communication is prone to trivial man in
14894 the-middle attacks rendering SSL useless. When this option is used, health
14895 checks are automatically sent in SSL too unless there is a "port" or an
14896 "addr" directive indicating the check should be sent to a different location.
Frédéric Lécailled2376272017-03-21 18:52:12 +010014897 See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
14898 SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020014899
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020014900ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
14901 This option enforces use of <version> or lower when SSL is used to communicate
14902 with the server. This option is also available on global statement
14903 "ssl-default-server-options". See also "ssl-min-ver".
14904
14905ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
14906 This option enforces use of <version> or upper when SSL is used to communicate
14907 with the server. This option is also available on global statement
14908 "ssl-default-server-options". See also "ssl-max-ver".
14909
Frédéric Lécailled2376272017-03-21 18:52:12 +010014910ssl-reuse
14911 This option may be used as "server" setting to reset any "no-ssl-reuse"
14912 setting which would have been inherited from "default-server" directive as
14913 default value.
14914 It may also be used as "default-server" setting to reset any previous
14915 "default-server" "no-ssl-reuse" setting.
14916
14917stick
14918 This option may be used as "server" setting to reset any "non-stick"
14919 setting which would have been inherited from "default-server" directive as
14920 default value.
14921 It may also be used as "default-server" setting to reset any previous
14922 "default-server" "non-stick" setting.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020014923
Alexander Liu2a54bb72019-05-22 19:44:48 +080014924socks4 <addr>:<port>
John Roeslerfb2fce12019-07-10 15:45:51 -050014925 This option enables upstream socks4 tunnel for outgoing connections to the
Alexander Liu2a54bb72019-05-22 19:44:48 +080014926 server. Using this option won't force the health check to go via socks4 by
14927 default. You will have to use the keyword "check-via-socks4" to enable it.
14928
Willy Tarreau163d4622015-10-13 16:16:41 +020014929tcp-ut <delay>
14930 Sets the TCP User Timeout for all outgoing connections to this server. This
Daniel Corbett9f0843f2021-05-08 10:50:37 -040014931 option is available on Linux since version 2.6.37. It allows HAProxy to
Willy Tarreau163d4622015-10-13 16:16:41 +020014932 configure a timeout for sockets which contain data not receiving an
Davor Ocelice9ed2812017-12-25 17:49:28 +010014933 acknowledgment for the configured delay. This is especially useful on
Willy Tarreau163d4622015-10-13 16:16:41 +020014934 long-lived connections experiencing long idle periods such as remote
14935 terminals or database connection pools, where the client and server timeouts
14936 must remain high to allow a long period of idle, but where it is important to
14937 detect that the server has disappeared in order to release all resources
14938 associated with its connection (and the client's session). One typical use
14939 case is also to force dead server connections to die when health checks are
14940 too slow or during a soft reload since health checks are then disabled. The
14941 argument is a delay expressed in milliseconds by default. This only works for
14942 regular TCP connections, and is ignored for other protocols.
14943
Willy Tarreau034c88c2017-01-23 23:36:45 +010014944tfo
14945 This option enables using TCP fast open when connecting to servers, on
14946 systems that support it (currently only the Linux kernel >= 4.11).
14947 See the "tfo" bind option for more information about TCP fast open.
14948 Please note that when using tfo, you should also use the "conn-failure",
Daniel Corbett9f0843f2021-05-08 10:50:37 -040014949 "empty-response" and "response-timeout" keywords for "retry-on", or HAProxy
Frédéric Lécaille1b9423d2019-07-04 14:19:06 +020014950 won't be able to retry the connection on failure. See also "no-tfo".
Willy Tarreau034c88c2017-01-23 23:36:45 +010014951
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014952track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020014953 This option enables ability to set the current state of the server by tracking
14954 another one. It is possible to track a server which itself tracks another
14955 server, provided that at the end of the chain, a server has health checks
14956 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014957 used, it has to be enabled on both proxies.
14958
Frédéric Lécailled2376272017-03-21 18:52:12 +010014959tls-tickets
14960 This option may be used as "server" setting to reset any "no-tls-tickets"
14961 setting which would have been inherited from "default-server" directive as
14962 default value.
Lukas Tribusbdb386d2020-03-10 00:56:09 +010014963 The TLS ticket mechanism is only used up to TLS 1.2.
14964 Forward Secrecy is compromised with TLS tickets, unless ticket keys
14965 are periodically rotated (via reload or by using "tls-ticket-keys").
Frédéric Lécailled2376272017-03-21 18:52:12 +010014966 It may also be used as "default-server" setting to reset any previous
Bjoern Jacke5ab7eb62020-02-13 14:16:16 +010014967 "default-server" "no-tls-tickets" setting.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014968
Emeric Brunef42d922012-10-11 16:11:36 +020014969verify [none|required]
14970 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010014971 to 'none', server certificate is not verified. In the other case, The
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014972 certificate provided by the server is verified using CAs from 'ca-file' and
14973 optional CRLs from 'crl-file' after having checked that the names provided in
Davor Ocelice9ed2812017-12-25 17:49:28 +010014974 the certificate's subject and subjectAlternateNames attributes match either
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014975 the name passed using the "sni" directive, or if not provided, the static
14976 host name passed using the "verifyhost" directive. When no name is found, the
14977 certificate's names are ignored. For this reason, without SNI it's important
14978 to use "verifyhost". On verification failure the handshake is aborted. It is
14979 critically important to verify server certificates when using SSL to connect
14980 to servers, otherwise the communication is prone to trivial man-in-the-middle
14981 attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
14982 the global section, "verify" is set to "required" by default.
Emeric Brunef42d922012-10-11 16:11:36 +020014983
Evan Broderbe554312013-06-27 00:05:25 -070014984verifyhost <hostname>
14985 This setting is only available when support for OpenSSL was built in, and
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014986 only takes effect if 'verify required' is also specified. This directive sets
14987 a default static hostname to check the server's certificate against when no
14988 SNI was used to connect to the server. If SNI is not used, this is the only
14989 way to enable hostname verification. This static hostname, when set, will
14990 also be used for health checks (which cannot provide an SNI value). If none
14991 of the hostnames in the certificate match the specified hostname, the
14992 handshake is aborted. The hostnames in the server-provided certificate may
14993 include wildcards. See also "verify", "sni" and "no-verifyhost" options.
Evan Broderbe554312013-06-27 00:05:25 -070014994
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014995weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014996 The "weight" parameter is used to adjust the server's weight relative to
14997 other servers. All servers will receive a load proportional to their weight
14998 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020014999 load. The default weight is 1, and the maximal value is 256. A value of 0
15000 means the server will not participate in load-balancing but will still accept
15001 persistent connections. If this parameter is used to distribute the load
15002 according to server's capacity, it is recommended to start with values which
15003 can both grow and shrink, for instance between 10 and 100 to leave enough
15004 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015005
15006
Cyril Bonté46175dd2015-07-02 22:45:32 +0200150075.3. Server IP address resolution using DNS
15008-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015009
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015010HAProxy allows using a host name on the server line to retrieve its IP address
15011using name servers. By default, HAProxy resolves the name when parsing the
Thayne McCombscdbcca92021-01-07 21:24:41 -070015012configuration file, at startup and cache the result for the process's life.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015013This is not sufficient in some cases, such as in Amazon where a server's IP
15014can change after a reboot or an ELB Virtual IP can change based on current
15015workload.
15016This chapter describes how HAProxy can be configured to process server's name
15017resolution at run time.
15018Whether run time server name resolution has been enable or not, HAProxy will
15019carry on doing the first resolution when parsing the configuration.
15020
15021
Cyril Bonté46175dd2015-07-02 22:45:32 +0200150225.3.1. Global overview
15023----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015024
15025As we've seen in introduction, name resolution in HAProxy occurs at two
15026different steps of the process life:
15027
15028 1. when starting up, HAProxy parses the server line definition and matches a
15029 host name. It uses libc functions to get the host name resolved. This
15030 resolution relies on /etc/resolv.conf file.
15031
Christopher Faulet67957bd2017-09-27 11:00:59 +020015032 2. at run time, HAProxy performs periodically name resolutions for servers
15033 requiring DNS resolutions.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015034
15035A few other events can trigger a name resolution at run time:
15036 - when a server's health check ends up in a connection timeout: this may be
15037 because the server has a new IP address. So we need to trigger a name
15038 resolution to know this new IP.
15039
Christopher Faulet67957bd2017-09-27 11:00:59 +020015040When using resolvers, the server name can either be a hostname, or a SRV label.
Davor Ocelice9ed2812017-12-25 17:49:28 +010015041HAProxy considers anything that starts with an underscore as a SRV label. If a
Christopher Faulet67957bd2017-09-27 11:00:59 +020015042SRV label is specified, then the corresponding SRV records will be retrieved
15043from the DNS server, and the provided hostnames will be used. The SRV label
Daniel Corbett9f0843f2021-05-08 10:50:37 -040015044will be checked periodically, and if any server are added or removed, HAProxy
Christopher Faulet67957bd2017-09-27 11:00:59 +020015045will automatically do the same.
Olivier Houchardecfa18d2017-08-07 17:30:03 +020015046
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015047A few things important to notice:
John Roeslerfb2fce12019-07-10 15:45:51 -050015048 - all the name servers are queried in the meantime. HAProxy will process the
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015049 first valid response.
15050
15051 - a resolution is considered as invalid (NX, timeout, refused), when all the
15052 servers return an error.
15053
15054
Cyril Bonté46175dd2015-07-02 22:45:32 +0200150555.3.2. The resolvers section
15056----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015057
15058This section is dedicated to host information related to name resolution in
Christopher Faulet67957bd2017-09-27 11:00:59 +020015059HAProxy. There can be as many as resolvers section as needed. Each section can
15060contain many name servers.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015061
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015062When multiple name servers are configured in a resolvers section, then HAProxy
15063uses the first valid response. In case of invalid responses, only the last one
15064is treated. Purpose is to give the chance to a slow server to deliver a valid
15065answer after a fast faulty or outdated server.
15066
15067When each server returns a different error type, then only the last error is
Christopher Faulet67957bd2017-09-27 11:00:59 +020015068used by HAProxy. The following processing is applied on this error:
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015069
Christopher Faulet67957bd2017-09-27 11:00:59 +020015070 1. HAProxy retries the same DNS query with a new query type. The A queries are
15071 switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
15072 errors are also excluded.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015073
Christopher Faulet67957bd2017-09-27 11:00:59 +020015074 2. When the fallback on the query type was done (or not applicable), HAProxy
15075 retries the original DNS query, with the preferred query type.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015076
Christopher Faulet67957bd2017-09-27 11:00:59 +020015077 3. HAProxy retries previous steps <resolve_retires> times. If no valid
15078 response is received after that, it stops the DNS resolution and reports
15079 the error.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015080
Christopher Faulet67957bd2017-09-27 11:00:59 +020015081For example, with 2 name servers configured in a resolvers section, the
15082following scenarios are possible:
15083
15084 - First response is valid and is applied directly, second response is
15085 ignored
15086
15087 - First response is invalid and second one is valid, then second response is
15088 applied
15089
15090 - First response is a NX domain and second one a truncated response, then
15091 HAProxy retries the query with a new type
15092
15093 - First response is a NX domain and second one is a timeout, then HAProxy
15094 retries the query with a new type
15095
15096 - Query timed out for both name servers, then HAProxy retries it with the
15097 same query type
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015098
Daniel Corbett9f0843f2021-05-08 10:50:37 -040015099As a DNS server may not answer all the IPs in one DNS request, HAProxy keeps
Olivier Houcharda8c6db82017-07-06 18:46:47 +020015100a cache of previous answers, an answer will be considered obsolete after
Christopher Faulet67957bd2017-09-27 11:00:59 +020015101<hold obsolete> seconds without the IP returned.
Olivier Houcharda8c6db82017-07-06 18:46:47 +020015102
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015103
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015104resolvers <resolvers id>
Davor Ocelice9ed2812017-12-25 17:49:28 +010015105 Creates a new name server list labeled <resolvers id>
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015106
15107A resolvers section accept the following parameters:
15108
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020015109accepted_payload_size <nb>
Davor Ocelice9ed2812017-12-25 17:49:28 +010015110 Defines the maximum payload size accepted by HAProxy and announced to all the
Christopher Faulet67957bd2017-09-27 11:00:59 +020015111 name servers configured in this resolvers section.
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020015112 <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
15113 by RFC 6891)
15114
Emeric Brun4c751952021-03-08 16:41:29 +010015115 Note: the maximum allowed value is 65535. Recommended value for UDP is
15116 4096 and it is not recommended to exceed 8192 except if you are sure
15117 that your system and network can handle this (over 65507 makes no sense
15118 since is the maximum UDP payload size). If you are using only TCP
15119 nameservers to handle huge DNS responses, you should put this value
15120 to the max: 65535.
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020015121
Emeric Brunc8f3e452021-04-07 16:04:54 +020015122nameserver <name> <address>[:port] [param*]
15123 Used to configure a nameserver. <name> of the nameserver should ne unique.
15124 By default the <address> is considered of type datagram. This means if an
15125 IPv4 or IPv6 is configured without special address prefixes (paragraph 11.)
15126 the UDP protocol will be used. If an stream protocol address prefix is used,
15127 the nameserver will be considered as a stream server (TCP for instance) and
15128 "server" parameters found in 5.2 paragraph which are relevant for DNS
15129 resolving will be considered. Note: currently, in TCP mode, 4 queries are
15130 pipelined on the same connections. A batch of idle connections are removed
15131 every 5 seconds. "maxconn" can be configured to limit the amount of those
Emeric Brun56fc5d92021-02-12 20:05:45 +010015132 concurrent connections and TLS should also usable if the server supports.
15133
Ben Draut44e609b2018-05-29 15:40:08 -060015134parse-resolv-conf
15135 Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers
15136 list. Ordered as if each nameserver in /etc/resolv.conf was individually
15137 placed in the resolvers section in place of this directive.
15138
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015139hold <status> <period>
15140 Defines <period> during which the last name resolution should be kept based
15141 on last resolution <status>
Baptiste Assmann987e16d2016-11-02 22:23:31 +010015142 <status> : last name resolution status. Acceptable values are "nx",
Olivier Houcharda8c6db82017-07-06 18:46:47 +020015143 "other", "refused", "timeout", "valid", "obsolete".
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015144 <period> : interval between two successive name resolution when the last
15145 answer was in <status>. It follows the HAProxy time format.
15146 <period> is in milliseconds by default.
15147
Baptiste Assmann686408b2017-08-18 10:15:42 +020015148 Default value is 10s for "valid", 0s for "obsolete" and 30s for others.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015149
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015150resolve_retries <nb>
15151 Defines the number <nb> of queries to send to resolve a server name before
15152 giving up.
15153 Default value: 3
15154
Baptiste Assmann62b75b42015-09-09 01:11:36 +020015155 A retry occurs on name server timeout or when the full sequence of DNS query
15156 type failover is over and we need to start up from the default ANY query
15157 type.
15158
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015159timeout <event> <time>
15160 Defines timeouts related to name resolution
15161 <event> : the event on which the <time> timeout period applies to.
15162 events available are:
Frédéric Lécaille93d33162019-03-06 09:35:59 +010015163 - resolve : default time to trigger name resolutions when no
15164 other time applied.
Christopher Faulet67957bd2017-09-27 11:00:59 +020015165 Default value: 1s
15166 - retry : time between two DNS queries, when no valid response
Frédéric Lécaille93d33162019-03-06 09:35:59 +010015167 have been received.
Christopher Faulet67957bd2017-09-27 11:00:59 +020015168 Default value: 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015169 <time> : time related to the event. It follows the HAProxy time format.
15170 <time> is expressed in milliseconds.
15171
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020015172 Example:
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015173
15174 resolvers mydns
15175 nameserver dns1 10.0.0.1:53
15176 nameserver dns2 10.0.0.2:53
Emeric Brunc8f3e452021-04-07 16:04:54 +020015177 nameserver dns3 tcp@10.0.0.3:53
Ben Draut44e609b2018-05-29 15:40:08 -060015178 parse-resolv-conf
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015179 resolve_retries 3
Christopher Faulet67957bd2017-09-27 11:00:59 +020015180 timeout resolve 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015181 timeout retry 1s
Baptiste Assmann987e16d2016-11-02 22:23:31 +010015182 hold other 30s
15183 hold refused 30s
15184 hold nx 30s
15185 hold timeout 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015186 hold valid 10s
Olivier Houcharda8c6db82017-07-06 18:46:47 +020015187 hold obsolete 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020015188
15189
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200151906. Cache
15191---------
15192
15193HAProxy provides a cache, which was designed to perform cache on small objects
15194(favicon, css...). This is a minimalist low-maintenance cache which runs in
15195RAM.
15196
15197The cache is based on a memory which is shared between processes and threads,
15198this memory is split in blocks of 1k.
15199
15200If an object is not used anymore, it can be deleted to store a new object
15201independently of its expiration date. The oldest objects are deleted first
15202when we try to allocate a new one.
15203
15204The cache uses a hash of the host header and the URI as the key.
15205
15206It's possible to view the status of a cache using the Unix socket command
15207"show cache" consult section 9.3 "Unix Socket commands" of Management Guide
15208for more details.
15209
15210When an object is delivered from the cache, the server name in the log is
15211replaced by "<CACHE>".
15212
15213
152146.1. Limitation
15215----------------
15216
15217The cache won't store and won't deliver objects in these cases:
15218
15219- If the response is not a 200
Remi Tricot-Le Breton4f730832020-11-26 15:51:50 +010015220- If the response contains a Vary header and either the process-vary option is
15221 disabled, or a currently unmanaged header is specified in the Vary value (only
15222 accept-encoding and referer are managed for now)
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020015223- If the Content-Length + the headers size is greater than "max-object-size"
15224- If the response is not cacheable
Remi Tricot-Le Bretond493bc82020-11-26 15:51:29 +010015225- If the response does not have an explicit expiration time (s-maxage or max-age
15226 Cache-Control directives or Expires header) or a validator (ETag or Last-Modified
15227 headers)
Remi Tricot-Le Breton5853c0c2020-12-10 17:58:43 +010015228- If the process-vary option is enabled and there are already max-secondary-entries
15229 entries with the same primary key as the current response
Remi Tricot-Le Breton6ca89162021-01-07 14:50:51 +010015230- If the process-vary option is enabled and the response has an unknown encoding (not
15231 mentioned in https://www.iana.org/assignments/http-parameters/http-parameters.xhtml)
15232 while varying on the accept-encoding client header
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020015233
15234- If the request is not a GET
15235- If the HTTP version of the request is smaller than 1.1
15236- If the request contains an Authorization header
15237
15238
152396.2. Setup
15240-----------
15241
15242To setup a cache, you must define a cache section and use it in a proxy with
15243the corresponding http-request and response actions.
15244
15245
152466.2.1. Cache section
15247---------------------
15248
15249cache <name>
15250 Declare a cache section, allocate a shared cache memory named <name>, the
15251 size of cache is mandatory.
15252
15253total-max-size <megabytes>
15254 Define the size in RAM of the cache in megabytes. This size is split in
15255 blocks of 1kB which are used by the cache entries. Its maximum value is 4095.
15256
15257max-object-size <bytes>
15258 Define the maximum size of the objects to be cached. Must not be greater than
15259 an half of "total-max-size". If not set, it equals to a 256th of the cache size.
15260 All objects with sizes larger than "max-object-size" will not be cached.
15261
15262max-age <seconds>
Remi Tricot-Le Breton5853c0c2020-12-10 17:58:43 +010015263 Define the maximum expiration duration. The expiration is set as the lowest
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020015264 value between the s-maxage or max-age (in this order) directive in the
15265 Cache-Control response header and this value. The default value is 60
15266 seconds, which means that you can't cache an object more than 60 seconds by
15267 default.
15268
Remi Tricot-Le Bretone6cc5b52020-12-23 18:13:53 +010015269process-vary <on/off>
15270 Enable or disable the processing of the Vary header. When disabled, a response
Remi Tricot-Le Breton754b2422020-11-16 15:56:10 +010015271 containing such a header will never be cached. When enabled, we need to calculate
15272 a preliminary hash for a subset of request headers on all the incoming requests
15273 (which might come with a cpu cost) which will be used to build a secondary key
Remi Tricot-Le Bretone6cc5b52020-12-23 18:13:53 +010015274 for a given request (see RFC 7234#4.1). The default value is off (disabled).
Remi Tricot-Le Breton754b2422020-11-16 15:56:10 +010015275
Remi Tricot-Le Breton5853c0c2020-12-10 17:58:43 +010015276max-secondary-entries <number>
15277 Define the maximum number of simultaneous secondary entries with the same primary
15278 key in the cache. This needs the vary support to be enabled. Its default value is 10
15279 and should be passed a strictly positive integer.
15280
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020015281
152826.2.2. Proxy section
15283---------------------
15284
15285http-request cache-use <name> [ { if | unless } <condition> ]
15286 Try to deliver a cached object from the cache <name>. This directive is also
15287 mandatory to store the cache as it calculates the cache hash. If you want to
15288 use a condition for both storage and delivering that's a good idea to put it
15289 after this one.
15290
15291http-response cache-store <name> [ { if | unless } <condition> ]
15292 Store an http-response within the cache. The storage of the response headers
15293 is done at this step, which means you can use others http-response actions
15294 to modify headers before or after the storage of the response. This action
15295 is responsible for the setup of the cache storage filter.
15296
15297
15298Example:
15299
15300 backend bck1
15301 mode http
15302
15303 http-request cache-use foobar
15304 http-response cache-store foobar
15305 server srv1 127.0.0.1:80
15306
15307 cache foobar
15308 total-max-size 4
15309 max-age 240
15310
15311
Willy Tarreau74ca5042013-06-11 23:12:07 +0200153127. Using ACLs and fetching samples
15313----------------------------------
15314
Davor Ocelice9ed2812017-12-25 17:49:28 +010015315HAProxy is capable of extracting data from request or response streams, from
Willy Tarreau74ca5042013-06-11 23:12:07 +020015316client or server information, from tables, environmental information etc...
15317The action of extracting such data is called fetching a sample. Once retrieved,
15318these samples may be used for various purposes such as a key to a stick-table,
15319but most common usages consist in matching them against predefined constant
15320data called patterns.
15321
15322
153237.1. ACL basics
15324---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015325
15326The use of Access Control Lists (ACL) provides a flexible solution to perform
15327content switching and generally to take decisions based on content extracted
15328from the request, the response or any environmental status. The principle is
15329simple :
15330
Willy Tarreau74ca5042013-06-11 23:12:07 +020015331 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015332 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020015333 - apply one or multiple pattern matching methods on this sample
15334 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015335
Willy Tarreau74ca5042013-06-11 23:12:07 +020015336The actions generally consist in blocking a request, selecting a backend, or
15337adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015338
15339In order to define a test, the "acl" keyword is used. The syntax is :
15340
Willy Tarreau74ca5042013-06-11 23:12:07 +020015341 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015342
15343This creates a new ACL <aclname> or completes an existing one with new tests.
15344Those tests apply to the portion of request/response specified in <criterion>
15345and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015346an operator which may be specified before the set of values. Optionally some
15347conversion operators may be applied to the sample, and they will be specified
15348as a comma-delimited list of keywords just after the first keyword. The values
15349are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015350
15351ACL names must be formed from upper and lower case letters, digits, '-' (dash),
15352'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
15353which means that "my_acl" and "My_Acl" are two different ACLs.
15354
15355There is no enforced limit to the number of ACLs. The unused ones do not affect
15356performance, they just consume a small amount of memory.
15357
Willy Tarreau74ca5042013-06-11 23:12:07 +020015358The criterion generally is the name of a sample fetch method, or one of its ACL
15359specific declinations. The default test method is implied by the output type of
15360this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015361methods of a same sample fetch method. The sample fetch methods are the only
15362ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015363
15364Sample fetch methods return data which can be of the following types :
15365 - boolean
15366 - integer (signed or unsigned)
15367 - IPv4 or IPv6 address
15368 - string
15369 - data block
15370
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015371Converters transform any of these data into any of these. For example, some
15372converters might convert a string to a lower-case string while other ones
15373would turn a string to an IPv4 address, or apply a netmask to an IP address.
15374The resulting sample is of the type of the last converter applied to the list,
15375which defaults to the type of the sample fetch method.
15376
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015377Each sample or converter returns data of a specific type, specified with its
15378keyword in this documentation. When an ACL is declared using a standard sample
15379fetch method, certain types automatically involved a default matching method
15380which are summarized in the table below :
15381
15382 +---------------------+-----------------+
15383 | Sample or converter | Default |
15384 | output type | matching method |
15385 +---------------------+-----------------+
15386 | boolean | bool |
15387 +---------------------+-----------------+
15388 | integer | int |
15389 +---------------------+-----------------+
15390 | ip | ip |
15391 +---------------------+-----------------+
15392 | string | str |
15393 +---------------------+-----------------+
15394 | binary | none, use "-m" |
15395 +---------------------+-----------------+
15396
15397Note that in order to match a binary samples, it is mandatory to specify a
15398matching method, see below.
15399
Willy Tarreau74ca5042013-06-11 23:12:07 +020015400The ACL engine can match these types against patterns of the following types :
15401 - boolean
15402 - integer or integer range
15403 - IP address / network
15404 - string (exact, substring, suffix, prefix, subdir, domain)
15405 - regular expression
15406 - hex block
15407
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015408The following ACL flags are currently supported :
15409
Willy Tarreau2b5285d2010-05-09 23:45:24 +020015410 -i : ignore case during matching of all subsequent patterns.
15411 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015412 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010015413 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010015414 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010015415 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020015416 -- : force end of flags. Useful when a string looks like one of the flags.
15417
Willy Tarreau74ca5042013-06-11 23:12:07 +020015418The "-f" flag is followed by the name of a file from which all lines will be
15419read as individual values. It is even possible to pass multiple "-f" arguments
15420if the patterns are to be loaded from multiple files. Empty lines as well as
15421lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
15422will be stripped. If it is absolutely necessary to insert a valid pattern
15423beginning with a sharp, just prefix it with a space so that it is not taken for
Daniel Corbett9f0843f2021-05-08 10:50:37 -040015424a comment. Depending on the data type and match method, HAProxy may load the
Willy Tarreau74ca5042013-06-11 23:12:07 +020015425lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
15426exact string matching. In this case, duplicates will automatically be removed.
15427
Thierry FOURNIER9860c412014-01-29 14:23:29 +010015428The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
15429parsed as two column file. The first column contains the patterns used by the
15430ACL, and the second column contain the samples. The sample can be used later by
15431a map. This can be useful in some rare cases where an ACL would just be used to
15432check for the existence of a pattern in a map before a mapping is applied.
15433
Thierry FOURNIER3534d882014-01-20 17:01:44 +010015434The "-u" flag forces the unique id of the ACL. This unique id is used with the
15435socket interface to identify ACL and dynamically change its values. Note that a
15436file is always identified by its name even if an id is set.
15437
Willy Tarreau74ca5042013-06-11 23:12:07 +020015438Also, note that the "-i" flag applies to subsequent entries and not to entries
15439loaded from files preceding it. For instance :
15440
15441 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
15442
15443In this example, each line of "exact-ua.lst" will be exactly matched against
15444the "user-agent" header of the request. Then each line of "generic-ua" will be
15445case-insensitively matched. Then the word "test" will be insensitively matched
15446as well.
15447
15448The "-m" flag is used to select a specific pattern matching method on the input
15449sample. All ACL-specific criteria imply a pattern matching method and generally
15450do not need this flag. However, this flag is useful with generic sample fetch
15451methods to describe how they're going to be matched against the patterns. This
15452is required for sample fetches which return data type for which there is no
Davor Ocelice9ed2812017-12-25 17:49:28 +010015453obvious matching method (e.g. string or binary). When "-m" is specified and
Willy Tarreau74ca5042013-06-11 23:12:07 +020015454followed by a pattern matching method name, this method is used instead of the
15455default one for the criterion. This makes it possible to match contents in ways
15456that were not initially planned, or with sample fetch methods which return a
15457string. The matching method also affects the way the patterns are parsed.
15458
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010015459The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
15460By default, if the parser cannot parse ip address it considers that the parsed
15461string is maybe a domain name and try dns resolution. The flag "-n" disable this
15462resolution. It is useful for detecting malformed ip lists. Note that if the DNS
Daniel Corbett9f0843f2021-05-08 10:50:37 -040015463server is not reachable, the HAProxy configuration parsing may last many minutes
John Roeslerfb2fce12019-07-10 15:45:51 -050015464waiting for the timeout. During this time no error messages are displayed. The
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010015465flag "-n" disable this behavior. Note also that during the runtime, this
15466function is disabled for the dynamic acl modifications.
15467
Willy Tarreau74ca5042013-06-11 23:12:07 +020015468There are some restrictions however. Not all methods can be used with all
15469sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
15470be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020015471
15472 - "found" : only check if the requested sample could be found in the stream,
15473 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020015474 to pass any pattern to avoid confusion. This matching method is
15475 particularly useful to detect presence of certain contents such
15476 as headers, cookies, etc... even if they are empty and without
15477 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015478
15479 - "bool" : check the value as a boolean. It can only be applied to fetches
15480 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015481 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015482
15483 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020015484 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015485
15486 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020015487 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015488
Davor Ocelice9ed2812017-12-25 17:49:28 +010015489 - "bin" : match the contents against a hexadecimal string representing a
Willy Tarreau5adeda12013-03-31 22:13:34 +020015490 binary sequence. This may be used with binary or string samples.
15491
15492 - "len" : match the sample's length as an integer. This may be used with
15493 binary or string samples.
15494
Willy Tarreau74ca5042013-06-11 23:12:07 +020015495 - "str" : exact match : match the contents against a string. This may be
15496 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015497
Willy Tarreau74ca5042013-06-11 23:12:07 +020015498 - "sub" : substring match : check that the contents contain at least one of
15499 the provided string patterns. This may be used with binary or
15500 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015501
Willy Tarreau74ca5042013-06-11 23:12:07 +020015502 - "reg" : regex match : match the contents against a list of regular
15503 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015504
Willy Tarreau74ca5042013-06-11 23:12:07 +020015505 - "beg" : prefix match : check that the contents begin like the provided
15506 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015507
Willy Tarreau74ca5042013-06-11 23:12:07 +020015508 - "end" : suffix match : check that the contents end like the provided
15509 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015510
Willy Tarreau74ca5042013-06-11 23:12:07 +020015511 - "dir" : subdir match : check that a slash-delimited portion of the
15512 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015513 This may be used with binary or string samples.
15514
Willy Tarreau74ca5042013-06-11 23:12:07 +020015515 - "dom" : domain match : check that a dot-delimited portion of the contents
15516 exactly match one of the provided string patterns. This may be
15517 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020015518
15519For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
15520request, it is possible to do :
15521
15522 acl jsess_present cook(JSESSIONID) -m found
15523
15524In order to apply a regular expression on the 500 first bytes of data in the
15525buffer, one would use the following acl :
15526
15527 acl script_tag payload(0,500) -m reg -i <script>
15528
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015529On systems where the regex library is much slower when using "-i", it is
15530possible to convert the sample to lowercase before matching, like this :
15531
15532 acl script_tag payload(0,500),lower -m reg <script>
15533
Willy Tarreau74ca5042013-06-11 23:12:07 +020015534All ACL-specific criteria imply a default matching method. Most often, these
15535criteria are composed by concatenating the name of the original sample fetch
15536method and the matching method. For example, "hdr_beg" applies the "beg" match
15537to samples retrieved using the "hdr" fetch method. Since all ACL-specific
15538criteria rely on a sample fetch method, it is always possible instead to use
15539the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020015540
Willy Tarreau74ca5042013-06-11 23:12:07 +020015541If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015542the matching method is simply applied to the underlying sample fetch method.
15543For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020015544
Willy Tarreau74ca5042013-06-11 23:12:07 +020015545 acl short_form hdr_beg(host) www.
15546 acl alternate1 hdr_beg(host) -m beg www.
15547 acl alternate2 hdr_dom(host) -m beg www.
15548 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020015549
Willy Tarreau2b5285d2010-05-09 23:45:24 +020015550
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015551The table below summarizes the compatibility matrix between sample or converter
15552types and the pattern types to fetch against. It indicates for each compatible
15553combination the name of the matching method to be used, surrounded with angle
15554brackets ">" and "<" when the method is the default one and will work by
15555default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010015556
Willy Tarreau74ca5042013-06-11 23:12:07 +020015557 +-------------------------------------------------+
15558 | Input sample type |
15559 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015560 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015561 +----------------------+---------+---------+---------+---------+---------+
15562 | none (presence only) | found | found | found | found | found |
15563 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015564 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015565 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015566 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015567 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015568 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015569 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015570 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015571 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020015572 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015573 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015574 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015575 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015576 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015577 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015578 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015579 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015580 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015581 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015582 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015583 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010015584 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020015585 +----------------------+---------+---------+---------+---------+---------+
15586 | hex block | | | | bin | bin |
15587 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020015588
15589
Willy Tarreau74ca5042013-06-11 23:12:07 +0200155907.1.1. Matching booleans
15591------------------------
15592
15593In order to match a boolean, no value is needed and all values are ignored.
15594Boolean matching is used by default for all fetch methods of type "boolean".
15595When boolean matching is used, the fetched value is returned as-is, which means
15596that a boolean "true" will always match and a boolean "false" will never match.
15597
15598Boolean matching may also be enforced using "-m bool" on fetch methods which
15599return an integer value. Then, integer value 0 is converted to the boolean
15600"false" and all other values are converted to "true".
15601
Willy Tarreau6a06a402007-07-15 20:15:28 +020015602
Willy Tarreau74ca5042013-06-11 23:12:07 +0200156037.1.2. Matching integers
15604------------------------
15605
15606Integer matching applies by default to integer fetch methods. It can also be
15607enforced on boolean fetches using "-m int". In this case, "false" is converted
15608to the integer 0, and "true" is converted to the integer 1.
15609
15610Integer matching also supports integer ranges and operators. Note that integer
15611matching only applies to positive values. A range is a value expressed with a
15612lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015613
15614For instance, "1024:65535" is a valid range to represent a range of
15615unprivileged ports, and "1024:" would also work. "0:1023" is a valid
15616representation of privileged ports, and ":1023" would also work.
15617
Willy Tarreau62644772008-07-16 18:36:06 +020015618As a special case, some ACL functions support decimal numbers which are in fact
15619two integers separated by a dot. This is used with some version checks for
15620instance. All integer properties apply to those decimal numbers, including
15621ranges and operators.
15622
Willy Tarreau6a06a402007-07-15 20:15:28 +020015623For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010015624operators with ranges does not make much sense and is strongly discouraged.
15625Similarly, it does not make much sense to perform order comparisons with a set
15626of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015627
Willy Tarreau0ba27502007-12-24 16:55:16 +010015628Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020015629
15630 eq : true if the tested value equals at least one value
15631 ge : true if the tested value is greater than or equal to at least one value
15632 gt : true if the tested value is greater than at least one value
15633 le : true if the tested value is less than or equal to at least one value
15634 lt : true if the tested value is less than at least one value
15635
Willy Tarreau0ba27502007-12-24 16:55:16 +010015636For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020015637
15638 acl negative-length hdr_val(content-length) lt 0
15639
Willy Tarreau62644772008-07-16 18:36:06 +020015640This one matches SSL versions between 3.0 and 3.1 (inclusive) :
15641
15642 acl sslv3 req_ssl_ver 3:3.1
15643
Willy Tarreau6a06a402007-07-15 20:15:28 +020015644
Willy Tarreau74ca5042013-06-11 23:12:07 +0200156457.1.3. Matching strings
15646-----------------------
15647
15648String matching applies to string or binary fetch methods, and exists in 6
15649different forms :
15650
15651 - exact match (-m str) : the extracted string must exactly match the
Davor Ocelice9ed2812017-12-25 17:49:28 +010015652 patterns;
Willy Tarreau74ca5042013-06-11 23:12:07 +020015653
15654 - substring match (-m sub) : the patterns are looked up inside the
Davor Ocelice9ed2812017-12-25 17:49:28 +010015655 extracted string, and the ACL matches if any of them is found inside;
Willy Tarreau74ca5042013-06-11 23:12:07 +020015656
15657 - prefix match (-m beg) : the patterns are compared with the beginning of
15658 the extracted string, and the ACL matches if any of them matches.
15659
15660 - suffix match (-m end) : the patterns are compared with the end of the
15661 extracted string, and the ACL matches if any of them matches.
15662
Baptiste Assmann33db6002016-03-06 23:32:10 +010015663 - subdir match (-m dir) : the patterns are looked up inside the extracted
Willy Tarreau74ca5042013-06-11 23:12:07 +020015664 string, delimited with slashes ("/"), and the ACL matches if any of them
15665 matches.
15666
15667 - domain match (-m dom) : the patterns are looked up inside the extracted
15668 string, delimited with dots ("."), and the ACL matches if any of them
15669 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015670
15671String matching applies to verbatim strings as they are passed, with the
15672exception of the backslash ("\") which makes it possible to escape some
15673characters such as the space. If the "-i" flag is passed before the first
15674string, then the matching will be performed ignoring the case. In order
15675to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010015676before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020015677
Mathias Weiersmuellercb250fc2019-12-02 09:43:40 +010015678Do not use string matches for binary fetches which might contain null bytes
15679(0x00), as the comparison stops at the occurrence of the first null byte.
15680Instead, convert the binary fetch to a hex string with the hex converter first.
15681
15682Example:
15683 # matches if the string <tag> is present in the binary sample
15684 acl tag_found req.payload(0,0),hex -m sub 3C7461673E
15685
Willy Tarreau6a06a402007-07-15 20:15:28 +020015686
Willy Tarreau74ca5042013-06-11 23:12:07 +0200156877.1.4. Matching regular expressions (regexes)
15688---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020015689
15690Just like with string matching, regex matching applies to verbatim strings as
15691they are passed, with the exception of the backslash ("\") which makes it
15692possible to escape some characters such as the space. If the "-i" flag is
15693passed before the first regex, then the matching will be performed ignoring
15694the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010015695the "--" flag before the first string. Same principle applies of course to
15696match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020015697
15698
Willy Tarreau74ca5042013-06-11 23:12:07 +0200156997.1.5. Matching arbitrary data blocks
15700-------------------------------------
15701
15702It is possible to match some extracted samples against a binary block which may
15703not safely be represented as a string. For this, the patterns must be passed as
15704a series of hexadecimal digits in an even number, when the match method is set
15705to binary. Each sequence of two digits will represent a byte. The hexadecimal
15706digits may be used upper or lower case.
15707
15708Example :
15709 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
15710 acl hello payload(0,6) -m bin 48656c6c6f0a
15711
15712
157137.1.6. Matching IPv4 and IPv6 addresses
15714---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020015715
15716IPv4 addresses values can be specified either as plain addresses or with a
15717netmask appended, in which case the IPv4 address matches whenever it is
15718within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010015719host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010015720difficult to read and debug configurations. If hostnames are used, you should
15721at least ensure that they are present in /etc/hosts so that the configuration
15722does not depend on any random DNS match at the moment the configuration is
15723parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015724
Daniel Schnellereba56342016-04-13 00:26:52 +020015725The dotted IPv4 address notation is supported in both regular as well as the
15726abbreviated form with all-0-octets omitted:
15727
15728 +------------------+------------------+------------------+
15729 | Example 1 | Example 2 | Example 3 |
15730 +------------------+------------------+------------------+
15731 | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 |
15732 | 192.168.1 | 10.12 | 127.1 |
15733 | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 |
15734 | 192.168.1/22 | 10.12/8 | 127.1/8 |
15735 +------------------+------------------+------------------+
15736
15737Notice that this is different from RFC 4632 CIDR address notation in which
15738192.168.42/24 would be equivalent to 192.168.42.0/24.
15739
Willy Tarreauceb4ac92012-04-28 00:41:46 +020015740IPv6 may be entered in their usual form, with or without a netmask appended.
15741Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
15742trouble with randomly resolved IP addresses, host names are never allowed in
15743IPv6 patterns.
15744
15745HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
15746following situations :
15747 - tested address is IPv4, pattern address is IPv4, the match applies
15748 in IPv4 using the supplied mask if any.
15749 - tested address is IPv6, pattern address is IPv6, the match applies
15750 in IPv6 using the supplied mask if any.
15751 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
15752 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
15753 ::IPV4 or ::ffff:IPV4, otherwise it fails.
15754 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
15755 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
15756 applied in IPv6 using the supplied IPv6 mask.
15757
Willy Tarreau74ca5042013-06-11 23:12:07 +020015758
157597.2. Using ACLs to form conditions
15760----------------------------------
15761
15762Some actions are only performed upon a valid condition. A condition is a
15763combination of ACLs with operators. 3 operators are supported :
15764
15765 - AND (implicit)
15766 - OR (explicit with the "or" keyword or the "||" operator)
15767 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020015768
Willy Tarreau74ca5042013-06-11 23:12:07 +020015769A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020015770
Willy Tarreau74ca5042013-06-11 23:12:07 +020015771 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020015772
Willy Tarreau74ca5042013-06-11 23:12:07 +020015773Such conditions are generally used after an "if" or "unless" statement,
15774indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020015775
Willy Tarreau74ca5042013-06-11 23:12:07 +020015776For instance, to block HTTP requests to the "*" URL with methods other than
15777"OPTIONS", as well as POST requests without content-length, and GET or HEAD
15778requests with a content-length greater than 0, and finally every request which
15779is not either GET/HEAD/POST/OPTIONS !
15780
15781 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030015782 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
15783 http-request deny if METH_GET HTTP_CONTENT
15784 http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreau74ca5042013-06-11 23:12:07 +020015785
15786To select a different backend for requests to static contents on the "www" site
15787and to every request on the "img", "video", "download" and "ftp" hosts :
15788
15789 acl url_static path_beg /static /images /img /css
15790 acl url_static path_end .gif .png .jpg .css .js
15791 acl host_www hdr_beg(host) -i www
15792 acl host_static hdr_beg(host) -i img. video. download. ftp.
15793
Davor Ocelice9ed2812017-12-25 17:49:28 +010015794 # now use backend "static" for all static-only hosts, and for static URLs
Willy Tarreau74ca5042013-06-11 23:12:07 +020015795 # of host "www". Use backend "www" for the rest.
15796 use_backend static if host_static or host_www url_static
15797 use_backend www if host_www
15798
15799It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
15800expressions that are built on the fly without needing to be declared. They must
15801be enclosed between braces, with a space before and after each brace (because
15802the braces must be seen as independent words). Example :
15803
15804 The following rule :
15805
15806 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030015807 http-request deny if METH_POST missing_cl
Willy Tarreau74ca5042013-06-11 23:12:07 +020015808
15809 Can also be written that way :
15810
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030015811 http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 }
Willy Tarreau74ca5042013-06-11 23:12:07 +020015812
15813It is generally not recommended to use this construct because it's a lot easier
15814to leave errors in the configuration when written that way. However, for very
15815simple rules matching only one source IP address for instance, it can make more
15816sense to use them than to declare ACLs with random names. Another example of
15817good use is the following :
15818
15819 With named ACLs :
15820
15821 acl site_dead nbsrv(dynamic) lt 2
15822 acl site_dead nbsrv(static) lt 2
15823 monitor fail if site_dead
15824
15825 With anonymous ACLs :
15826
15827 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
15828
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030015829See section 4.2 for detailed help on the "http-request deny" and "use_backend"
15830keywords.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015831
15832
158337.3. Fetching samples
15834---------------------
15835
15836Historically, sample fetch methods were only used to retrieve data to match
15837against patterns using ACLs. With the arrival of stick-tables, a new class of
15838sample fetch methods was created, most often sharing the same syntax as their
15839ACL counterpart. These sample fetch methods are also known as "fetches". As
15840of now, ACLs and fetches have converged. All ACL fetch methods have been made
15841available as fetch methods, and ACLs may use any sample fetch method as well.
15842
15843This section details all available sample fetch methods and their output type.
15844Some sample fetch methods have deprecated aliases that are used to maintain
15845compatibility with existing configurations. They are then explicitly marked as
15846deprecated and should not be used in new setups.
15847
15848The ACL derivatives are also indicated when available, with their respective
15849matching methods. These ones all have a well defined default pattern matching
15850method, so it is never necessary (though allowed) to pass the "-m" option to
15851indicate how the sample will be matched using ACLs.
15852
15853As indicated in the sample type versus matching compatibility matrix above,
15854when using a generic sample fetch method in an ACL, the "-m" option is
15855mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
15856the same keyword exists as an ACL keyword and as a standard fetch method, the
15857ACL engine will automatically pick the ACL-only one by default.
15858
15859Some of these keywords support one or multiple mandatory arguments, and one or
15860multiple optional arguments. These arguments are strongly typed and are checked
15861when the configuration is parsed so that there is no risk of running with an
Davor Ocelice9ed2812017-12-25 17:49:28 +010015862incorrect argument (e.g. an unresolved backend name). Fetch function arguments
15863are passed between parenthesis and are delimited by commas. When an argument
Willy Tarreau74ca5042013-06-11 23:12:07 +020015864is optional, it will be indicated below between square brackets ('[ ]'). When
15865all arguments are optional, the parenthesis may be omitted.
15866
15867Thus, the syntax of a standard sample fetch method is one of the following :
15868 - name
15869 - name(arg1)
15870 - name(arg1,arg2)
15871
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015872
158737.3.1. Converters
15874-----------------
15875
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015876Sample fetch methods may be combined with transformations to be applied on top
15877of the fetched sample (also called "converters"). These combinations form what
15878is called "sample expressions" and the result is a "sample". Initially this
15879was only supported by "stick on" and "stick store-request" directives but this
Davor Ocelice9ed2812017-12-25 17:49:28 +010015880has now be extended to all places where samples may be used (ACLs, log-format,
Willy Tarreaue6b11e42013-11-26 19:02:32 +010015881unique-id-format, add-header, ...).
15882
15883These transformations are enumerated as a series of specific keywords after the
15884sample fetch method. These keywords may equally be appended immediately after
15885the fetch keyword's argument, delimited by a comma. These keywords can also
Davor Ocelice9ed2812017-12-25 17:49:28 +010015886support some arguments (e.g. a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010015887
Willy Tarreau97707872015-01-27 15:12:13 +010015888A certain category of converters are bitwise and arithmetic operators which
15889support performing basic operations on integers. Some bitwise operations are
15890supported (and, or, xor, cpl) and some arithmetic operations are supported
15891(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
15892bool) which make it possible to report a match without having to write an ACL.
15893
Willy Tarreau74ca5042013-06-11 23:12:07 +020015894The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010015895
Ben Shillitof25e8e52016-12-02 14:25:37 +00001589651d.single(<prop>[,<prop>*])
15897 Returns values for the properties requested as a string, where values are
15898 separated by the delimiter specified with "51degrees-property-separator".
15899 The device is identified using the User-Agent header passed to the
15900 converter. The function can be passed up to five property names, and if a
15901 property name can't be found, the value "NoData" is returned.
15902
15903 Example :
Davor Ocelice9ed2812017-12-25 17:49:28 +010015904 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request,
15905 # containing values for the three properties requested by using the
Ben Shillitof25e8e52016-12-02 14:25:37 +000015906 # User-Agent passed to the converter.
15907 frontend http-in
15908 bind *:8081
15909 default_backend servers
15910 http-request set-header X-51D-DeviceTypeMobileTablet \
15911 %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
15912
Willy Tarreau97707872015-01-27 15:12:13 +010015913add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015914 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015915 result as a signed integer. <value> can be a numeric value or a variable
Daniel Schneller0b547052016-03-21 20:46:57 +010015916 name. The name of the variable starts with an indication about its scope. The
15917 scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015918 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015919 "sess" : the variable is shared with the whole session
15920 "txn" : the variable is shared with the transaction (request and response)
15921 "req" : the variable is shared only during request processing
15922 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010015923 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015924 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015925
Nenad Merdanovicc31499d2019-03-23 11:00:32 +010015926aes_gcm_dec(<bits>,<nonce>,<key>,<aead_tag>)
15927 Decrypts the raw byte input using the AES128-GCM, AES192-GCM or
15928 AES256-GCM algorithm, depending on the <bits> parameter. All other parameters
15929 need to be base64 encoded and the returned result is in raw byte format.
15930 If the <aead_tag> validation fails, the converter doesn't return any data.
15931 The <nonce>, <key> and <aead_tag> can either be strings or variables. This
15932 converter requires at least OpenSSL 1.0.1.
15933
15934 Example:
15935 http-response set-header X-Decrypted-Text %[var(txn.enc),\
15936 aes_gcm_dec(128,txn.nonce,Zm9vb2Zvb29mb29wZm9vbw==,txn.aead_tag)]
15937
Willy Tarreau97707872015-01-27 15:12:13 +010015938and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015939 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015940 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010015941 numeric value or a variable name. The name of the variable starts with an
15942 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015943 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015944 "sess" : the variable is shared with the whole session
15945 "txn" : the variable is shared with the transaction (request and response)
15946 "req" : the variable is shared only during request processing
15947 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010015948 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015949 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015950
Holger Just1bfc24b2017-05-06 00:56:53 +020015951b64dec
15952 Converts (decodes) a base64 encoded input string to its binary
15953 representation. It performs the inverse operation of base64().
Moemen MHEDHBI92f7d432021-04-01 20:53:59 +020015954 For base64url("URL and Filename Safe Alphabet" (RFC 4648)) variant
15955 see "ub64dec".
Holger Just1bfc24b2017-05-06 00:56:53 +020015956
Emeric Brun53d1a982014-04-30 18:21:37 +020015957base64
15958 Converts a binary input sample to a base64 string. It is used to log or
Davor Ocelice9ed2812017-12-25 17:49:28 +010015959 transfer binary content in a way that can be reliably transferred (e.g.
Moemen MHEDHBI92f7d432021-04-01 20:53:59 +020015960 an SSL ID can be copied in a header). For base64url("URL and Filename
15961 Safe Alphabet" (RFC 4648)) variant see "ub64enc".
Emeric Brun53d1a982014-04-30 18:21:37 +020015962
Willy Tarreau97707872015-01-27 15:12:13 +010015963bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015964 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010015965 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010015966 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010015967 presence of a flag).
15968
Emeric Brun54c4ac82014-11-03 15:32:43 +010015969bytes(<offset>[,<length>])
15970 Extracts some bytes from an input binary sample. The result is a binary
15971 sample starting at an offset (in bytes) of the original sample and
Tim Düsterhus4896c442016-11-29 02:15:19 +010015972 optionally truncated at the given length.
Emeric Brun54c4ac82014-11-03 15:32:43 +010015973
Willy Tarreau280f42b2018-02-19 15:34:12 +010015974concat([<start>],[<var>],[<end>])
15975 Concatenates up to 3 fields after the current sample which is then turned to
15976 a string. The first one, <start>, is a constant string, that will be appended
15977 immediately after the existing sample. It may be omitted if not used. The
15978 second one, <var>, is a variable name. The variable will be looked up, its
15979 contents converted to a string, and it will be appended immediately after the
15980 <first> part. If the variable is not found, nothing is appended. It may be
15981 omitted as well. The third field, <end> is a constant string that will be
15982 appended after the variable. It may also be omitted. Together, these elements
15983 allow to concatenate variables with delimiters to an existing set of
15984 variables. This can be used to build new variables made of a succession of
Willy Tarreauef21fac2020-02-14 13:37:20 +010015985 other variables, such as colon-delimited values. If commas or closing
Daniel Corbett67a82712020-07-06 23:01:19 -040015986 parenthesis are needed as delimiters, they must be protected by quotes or
Willy Tarreauef21fac2020-02-14 13:37:20 +010015987 backslashes, themselves protected so that they are not stripped by the first
15988 level parser. See examples below.
Willy Tarreau280f42b2018-02-19 15:34:12 +010015989
15990 Example:
15991 tcp-request session set-var(sess.src) src
15992 tcp-request session set-var(sess.dn) ssl_c_s_dn
15993 tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>)
Willy Tarreauef21fac2020-02-14 13:37:20 +010015994 tcp-request session set-var(txn.ipport) "str(),concat('addr=(',sess.ip),concat(',',sess.port,')')"
Willy Tarreau280f42b2018-02-19 15:34:12 +010015995 http-request set-header x-hap-sig %[var(txn.sig)]
15996
Willy Tarreau97707872015-01-27 15:12:13 +010015997cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015998 Takes the input value of type signed integer, applies a ones-complement
15999 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010016000
Willy Tarreau80599772015-01-20 19:35:24 +010016001crc32([<avalanche>])
16002 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
16003 hash function. Optionally, it is possible to apply a full avalanche hash
16004 function to the output if the optional <avalanche> argument equals 1. This
16005 converter uses the same functions as used by the various hash-based load
16006 balancing algorithms, so it will provide exactly the same results. It is
16007 provided for compatibility with other software which want a CRC32 to be
16008 computed on some input keys, so it follows the most common implementation as
16009 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
16010 but may provide a better or at least less predictable distribution. It must
16011 not be used for security purposes as a 32-bit hash is trivial to break. See
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010016012 also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive.
16013
16014crc32c([<avalanche>])
16015 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C
16016 hash function. Optionally, it is possible to apply a full avalanche hash
16017 function to the output if the optional <avalanche> argument equals 1. This
16018 converter uses the same functions as described in RFC4960, Appendix B [8].
16019 It is provided for compatibility with other software which want a CRC32C to be
16020 computed on some input keys. It is slower than the other algorithms and it must
16021 not be used for security purposes as a 32-bit hash is trivial to break. See
16022 also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive.
Willy Tarreau80599772015-01-20 19:35:24 +010016023
Christopher Fauletea159d62020-04-01 16:21:44 +020016024cut_crlf
16025 Cuts the string representation of the input sample on the first carriage
16026 return ('\r') or newline ('\n') character found. Only the string length is
16027 updated.
16028
David Carlier29b3ca32015-09-25 14:09:21 +010016029da-csv-conv(<prop>[,<prop>*])
David Carlier4542b102015-06-01 13:54:29 +020016030 Asks the DeviceAtlas converter to identify the User Agent string passed on
16031 input, and to emit a string made of the concatenation of the properties
16032 enumerated in argument, delimited by the separator defined by the global
16033 keyword "deviceatlas-property-separator", or by default the pipe character
Daniel Corbett9f0843f2021-05-08 10:50:37 -040016034 ('|'). There's a limit of 12 different properties imposed by the HAProxy
David Carlier4542b102015-06-01 13:54:29 +020016035 configuration language.
16036
16037 Example:
16038 frontend www
Cyril Bonté307ee1e2015-09-28 23:16:06 +020016039 bind *:8881
16040 default_backend servers
David Carlier840b0242016-03-16 10:09:55 +000016041 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 +020016042
Willy Tarreau0851fd52019-12-17 10:07:25 +010016043debug([<prefix][,<destination>])
16044 This converter is used as debug tool. It takes a capture of the input sample
16045 and sends it to event sink <destination>, which may designate a ring buffer
16046 such as "buf0", as well as "stdout", or "stderr". Available sinks may be
16047 checked at run time by issuing "show events" on the CLI. When not specified,
16048 the output will be "buf0", which may be consulted via the CLI's "show events"
16049 command. An optional prefix <prefix> may be passed to help distinguish
16050 outputs from multiple expressions. It will then appear before the colon in
16051 the output message. The input sample is passed as-is on the output, so that
16052 it is safe to insert the debug converter anywhere in a chain, even with non-
16053 printable sample types.
16054
16055 Example:
16056 tcp-request connection track-sc0 src,debug(track-sc)
Thierry FOURNIER9687c772015-05-07 15:46:29 +020016057
Patrick Gansterer8e366512020-04-22 16:47:57 +020016058digest(<algorithm>)
16059 Converts a binary input sample to a message digest. The result is a binary
16060 sample. The <algorithm> must be an OpenSSL message digest name (e.g. sha256).
16061
Daniel Corbett9f0843f2021-05-08 10:50:37 -040016062 Please note that this converter is only available when HAProxy has been
Patrick Gansterer8e366512020-04-22 16:47:57 +020016063 compiled with USE_OPENSSL.
16064
Willy Tarreau97707872015-01-27 15:12:13 +010016065div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016066 Divides the input value of type signed integer by <value>, and returns the
16067 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016068 integer is returned (typically 2^63-1). <value> can be a numeric value or a
Daniel Schneller0b547052016-03-21 20:46:57 +010016069 variable name. The name of the variable starts with an indication about its
16070 scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016071 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016072 "sess" : the variable is shared with the whole session
16073 "txn" : the variable is shared with the transaction (request and response)
16074 "req" : the variable is shared only during request processing
16075 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010016076 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016077 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010016078
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020016079djb2([<avalanche>])
16080 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
16081 hash function. Optionally, it is possible to apply a full avalanche hash
16082 function to the output if the optional <avalanche> argument equals 1. This
16083 converter uses the same functions as used by the various hash-based load
16084 balancing algorithms, so it will provide exactly the same results. It is
16085 mostly intended for debugging, but can be used as a stick-table entry to
16086 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010016087 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c",
16088 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020016089
Willy Tarreau97707872015-01-27 15:12:13 +010016090even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016091 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010016092 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
16093
Marcin Deranek9631a282018-04-16 14:30:46 +020016094field(<index>,<delimiters>[,<count>])
16095 Extracts the substring at the given index counting from the beginning
16096 (positive index) or from the end (negative index) considering given delimiters
16097 from an input string. Indexes start at 1 or -1 and delimiters are a string
16098 formatted list of chars. Optionally you can specify <count> of fields to
16099 extract (default: 1). Value of 0 indicates extraction of all remaining
16100 fields.
16101
16102 Example :
16103 str(f1_f2_f3__f5),field(5,_) # f5
16104 str(f1_f2_f3__f5),field(2,_,0) # f2_f3__f5
16105 str(f1_f2_f3__f5),field(2,_,2) # f2_f3
16106 str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_
16107 str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3
Emeric Brunf399b0d2014-11-03 17:07:03 +010016108
Baptiste Assmanne138dda2020-10-22 15:39:03 +020016109fix_is_valid
16110 Parses a binary payload and performs sanity checks regarding FIX (Financial
16111 Information eXchange):
16112
16113 - checks that all tag IDs and values are not empty and the tags IDs are well
16114 numeric
Ilya Shipitsin2272d8a2020-12-21 01:22:40 +050016115 - checks the BeginString tag is the first tag with a valid FIX version
Baptiste Assmanne138dda2020-10-22 15:39:03 +020016116 - checks the BodyLength tag is the second one with the right body length
Christopher Fauleted4bef72021-03-18 17:40:56 +010016117 - checks the MsgType tag is the third tag.
Baptiste Assmanne138dda2020-10-22 15:39:03 +020016118 - checks that last tag in the message is the CheckSum tag with a valid
16119 checksum
16120
16121 Due to current HAProxy design, only the first message sent by the client and
16122 the server can be parsed.
16123
16124 This converter returns a boolean, true if the payload contains a valid FIX
16125 message, false if not.
16126
16127 See also the fix_tag_value converter.
16128
16129 Example:
16130 tcp-request inspect-delay 10s
16131 tcp-request content reject unless { req.payload(0,0),fix_is_valid }
16132
16133fix_tag_value(<tag>)
16134 Parses a FIX (Financial Information eXchange) message and extracts the value
16135 from the tag <tag>. <tag> can be a string or an integer pointing to the
16136 desired tag. Any integer value is accepted, but only the following strings
16137 are translated into their integer equivalent: BeginString, BodyLength,
Daniel Corbettbefef702021-03-09 23:00:34 -050016138 MsgType, SenderCompID, TargetCompID, CheckSum. More tag names can be easily
Baptiste Assmanne138dda2020-10-22 15:39:03 +020016139 added.
16140
16141 Due to current HAProxy design, only the first message sent by the client and
16142 the server can be parsed. No message validation is performed by this
16143 converter. It is highly recommended to validate the message first using
16144 fix_is_valid converter.
16145
16146 See also the fix_is_valid converter.
16147
16148 Example:
16149 tcp-request inspect-delay 10s
16150 tcp-request content reject unless { req.payload(0,0),fix_is_valid }
16151 # MsgType tag ID is 35, so both lines below will return the same content
16152 tcp-request content set-var(txn.foo) req.payload(0,0),fix_tag_value(35)
16153 tcp-request content set-var(txn.bar) req.payload(0,0),fix_tag_value(MsgType)
16154
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016155hex
Davor Ocelice9ed2812017-12-25 17:49:28 +010016156 Converts a binary input sample to a hex string containing two hex digits per
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016157 input byte. It is used to log or transfer hex dumps of some binary input data
Davor Ocelice9ed2812017-12-25 17:49:28 +010016158 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 +020016159 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010016160
Dragan Dosen3f957b22017-10-24 09:27:34 +020016161hex2i
16162 Converts a hex string containing two hex digits per input byte to an
John Roeslerfb2fce12019-07-10 15:45:51 -050016163 integer. If the input value cannot be converted, then zero is returned.
Dragan Dosen3f957b22017-10-24 09:27:34 +020016164
Christopher Faulet4ccc12f2020-04-01 09:08:32 +020016165htonl
16166 Converts the input integer value to its 32-bit binary representation in the
16167 network byte order. Because sample fetches own signed 64-bit integer, when
16168 this converter is used, the input integer value is first casted to an
16169 unsigned 32-bit integer.
16170
Tim Duesterhusa3082092021-01-21 17:40:49 +010016171hmac(<algorithm>,<key>)
Patrick Gansterer8e366512020-04-22 16:47:57 +020016172 Converts a binary input sample to a message authentication code with the given
16173 key. The result is a binary sample. The <algorithm> must be one of the
16174 registered OpenSSL message digest names (e.g. sha256). The <key> parameter must
16175 be base64 encoded and can either be a string or a variable.
16176
Daniel Corbett9f0843f2021-05-08 10:50:37 -040016177 Please note that this converter is only available when HAProxy has been
Patrick Gansterer8e366512020-04-22 16:47:57 +020016178 compiled with USE_OPENSSL.
16179
Cyril Bonté6bcd1822019-11-05 23:13:59 +010016180http_date([<offset],[<unit>])
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016181 Converts an integer supposed to contain a date since epoch to a string
16182 representing this date in a format suitable for use in HTTP header fields. If
Damien Claisseae6f1252019-10-30 15:57:28 +000016183 an offset value is specified, then it is added to the date before the
16184 conversion is operated. This is particularly useful to emit Date header fields,
16185 Expires values in responses when combined with a positive offset, or
16186 Last-Modified values when the offset is negative.
16187 If a unit value is specified, then consider the timestamp as either
16188 "s" for seconds (default behavior), "ms" for milliseconds, or "us" for
16189 microseconds since epoch. Offset is assumed to have the same unit as
16190 input timestamp.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016191
Tim Duesterhus3943e4f2020-09-11 14:25:23 +020016192iif(<true>,<false>)
16193 Returns the <true> string if the input value is true. Returns the <false>
16194 string otherwise.
16195
16196 Example:
Tim Duesterhus870713b2020-09-11 17:13:12 +020016197 http-request set-header x-forwarded-proto %[ssl_fc,iif(https,http)]
Tim Duesterhus3943e4f2020-09-11 14:25:23 +020016198
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016199in_table(<table>)
16200 Uses the string representation of the input sample to perform a look up in
16201 the specified table. If the key is not found in the table, a boolean false
16202 is returned. Otherwise a boolean true is returned. This can be used to verify
Davor Ocelice9ed2812017-12-25 17:49:28 +010016203 the presence of a certain key in a table tracking some elements (e.g. whether
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016204 or not a source IP address or an Authorization header was already seen).
16205
Tim Duesterhusa3082092021-01-21 17:40:49 +010016206ipmask(<mask4>,[<mask6>])
Tim Duesterhus1478aa72018-01-25 16:24:51 +010016207 Apply a mask to an IP address, and use the result for lookups and storage.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020016208 This can be used to make all hosts within a certain mask to share the same
Tim Duesterhus1478aa72018-01-25 16:24:51 +010016209 table entries and as such use the same server. The mask4 can be passed in
16210 dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can
16211 be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64).
16212 If no mask6 is given IPv6 addresses will fail to convert for backwards
16213 compatibility reasons.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020016214
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016215json([<input-code>])
Davor Ocelice9ed2812017-12-25 17:49:28 +010016216 Escapes the input string and produces an ASCII output string ready to use as a
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016217 JSON string. The converter tries to decode the input string according to the
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020016218 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016219 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
16220 of errors:
16221 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
16222 bytes, ...)
16223 - invalid range (the decoded value is within a UTF-8 prohibited range),
16224 - code overlong (the value is encoded with more bytes than necessary).
16225
16226 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
16227 character is greater than 0xffff because the JSON string escape specification
16228 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
16229 in 4 variants designated by a combination of two suffix letters : "p" for
16230 "permissive" and "s" for "silently ignore". The behaviors of the decoders
16231 are :
Davor Ocelice9ed2812017-12-25 17:49:28 +010016232 - "ascii" : never fails;
16233 - "utf8" : fails on any detected errors;
16234 - "utf8s" : never fails, but removes characters corresponding to errors;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016235 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
Davor Ocelice9ed2812017-12-25 17:49:28 +010016236 error;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016237 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
16238 characters corresponding to the other errors.
16239
16240 This converter is particularly useful for building properly escaped JSON for
Davor Ocelice9ed2812017-12-25 17:49:28 +010016241 logging to servers which consume JSON-formatted traffic logs.
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016242
16243 Example:
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016244 capture request header Host len 15
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020016245 capture request header user-agent len 150
16246 log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020016247
16248 Input request from client 127.0.0.1:
16249 GET / HTTP/1.0
16250 User-Agent: Very "Ugly" UA 1/2
16251
16252 Output log:
16253 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
16254
Alex51c8ad42021-04-15 16:45:15 +020016255json_query(<json_path>,[<output_type>])
16256 The json_query converter supports the JSON types string, boolean and
16257 number. Floating point numbers will be returned as a string. By
16258 specifying the output_type 'int' the value will be converted to an
16259 Integer. If conversion is not possible the json_query converter fails.
16260
16261 <json_path> must be a valid JSON Path string as defined in
16262 https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/
16263
16264 Example:
16265 # get a integer value from the request body
16266 # "{"integer":4}" => 5
16267 http-request set-var(txn.pay_int) req.body,json_query('$.integer','int'),add(1)
16268
16269 # get a key with '.' in the name
16270 # {"my.key":"myvalue"} => myvalue
16271 http-request set-var(txn.pay_mykey) req.body,json_query('$.my\\.key')
16272
16273 # {"boolean-false":false} => 0
16274 http-request set-var(txn.pay_boolean_false) req.body,json_query('$.boolean-false')
16275
16276 # get the value of the key 'iss' from a JWT Bearer token
16277 http-request set-var(txn.token_payload) req.hdr(Authorization),word(2,.),ub64dec,json_query('$.iss')
16278
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016279language(<value>[,<default>])
16280 Returns the value with the highest q-factor from a list as extracted from the
16281 "accept-language" header using "req.fhdr". Values with no q-factor have a
16282 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
16283 belong to the list of semi-colon delimited <values> will be considered. The
16284 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
16285 given list and a default value is provided, it is returned. Note that language
16286 names may have a variant after a dash ('-'). If this variant is present in the
16287 list, it will be matched, but if it is not, only the base language is checked.
16288 The match is case-sensitive, and the output string is always one of those
Davor Ocelice9ed2812017-12-25 17:49:28 +010016289 provided in arguments. The ordering of arguments is meaningless, only the
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016290 ordering of the values in the request counts, as the first value among
16291 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020016292
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016293 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020016294
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016295 # this configuration switches to the backend matching a
16296 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020016297
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016298 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
16299 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
16300 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
16301 use_backend spanish if es
16302 use_backend french if fr
16303 use_backend english if en
16304 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020016305
Willy Tarreau60a2ee72017-12-15 07:13:48 +010016306length
Etienne Carriereed0d24e2017-12-13 13:41:34 +010016307 Get the length of the string. This can only be placed after a string
16308 sample fetch function or after a transformation keyword returning a string
16309 type. The result is of type integer.
16310
Willy Tarreauffcb2e42014-07-10 16:29:08 +020016311lower
16312 Convert a string sample to lower case. This can only be placed after a string
16313 sample fetch function or after a transformation keyword returning a string
16314 type. The result is of type string.
16315
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020016316ltime(<format>[,<offset>])
16317 Converts an integer supposed to contain a date since epoch to a string
16318 representing this date in local time using a format defined by the <format>
16319 string using strftime(3). The purpose is to allow any date format to be used
16320 in logs. An optional <offset> in seconds may be applied to the input date
16321 (positive or negative). See the strftime() man page for the format supported
16322 by your operating system. See also the utime converter.
16323
16324 Example :
16325
16326 # Emit two colons, one with the local time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010016327 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020016328 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
16329
Christopher Faulet51fc9d12020-04-01 17:24:41 +020016330ltrim(<chars>)
16331 Skips any characters from <chars> from the beginning of the string
16332 representation of the input sample.
16333
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016334map(<map_file>[,<default_value>])
16335map_<match_type>(<map_file>[,<default_value>])
16336map_<match_type>_<output_type>(<map_file>[,<default_value>])
16337 Search the input value from <map_file> using the <match_type> matching method,
16338 and return the associated value converted to the type <output_type>. If the
16339 input value cannot be found in the <map_file>, the converter returns the
16340 <default_value>. If the <default_value> is not set, the converter fails and
16341 acts as if no input value could be fetched. If the <match_type> is not set, it
16342 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
16343 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
16344 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010016345
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016346 It is important to avoid overlapping between the keys : IP addresses and
16347 strings are stored in trees, so the first of the finest match will be used.
16348 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010016349
Tim Düsterhus4896c442016-11-29 02:15:19 +010016350 The following array contains the list of all map functions available sorted by
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016351 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010016352
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016353 input type | match method | output type str | output type int | output type ip
16354 -----------+--------------+-----------------+-----------------+---------------
16355 str | str | map_str | map_str_int | map_str_ip
16356 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020016357 str | beg | map_beg | map_beg_int | map_end_ip
16358 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016359 str | sub | map_sub | map_sub_int | map_sub_ip
16360 -----------+--------------+-----------------+-----------------+---------------
16361 str | dir | map_dir | map_dir_int | map_dir_ip
16362 -----------+--------------+-----------------+-----------------+---------------
16363 str | dom | map_dom | map_dom_int | map_dom_ip
16364 -----------+--------------+-----------------+-----------------+---------------
16365 str | end | map_end | map_end_int | map_end_ip
16366 -----------+--------------+-----------------+-----------------+---------------
Ruoshan Huang3c5e3742016-12-02 16:25:31 +080016367 str | reg | map_reg | map_reg_int | map_reg_ip
16368 -----------+--------------+-----------------+-----------------+---------------
16369 str | reg | map_regm | map_reg_int | map_reg_ip
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016370 -----------+--------------+-----------------+-----------------+---------------
16371 int | int | map_int | map_int_int | map_int_ip
16372 -----------+--------------+-----------------+-----------------+---------------
16373 ip | ip | map_ip | map_ip_int | map_ip_ip
16374 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010016375
Thierry Fournier8feaa662016-02-10 22:55:20 +010016376 The special map called "map_regm" expect matching zone in the regular
16377 expression and modify the output replacing back reference (like "\1") by
16378 the corresponding match text.
16379
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016380 The file contains one key + value per line. Lines which start with '#' are
16381 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
16382 is then the first "word" (series of non-space/tabs characters), and the value
16383 is what follows this series of space/tab till the end of the line excluding
16384 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010016385
Thierry FOURNIER060762e2014-04-23 13:29:15 +020016386 Example :
16387
16388 # this is a comment and is ignored
16389 2.22.246.0/23 United Kingdom \n
16390 <-><-----------><--><------------><---->
16391 | | | | `- trailing spaces ignored
16392 | | | `---------- value
16393 | | `-------------------- middle spaces ignored
16394 | `---------------------------- key
16395 `------------------------------------ leading spaces ignored
16396
Willy Tarreau97707872015-01-27 15:12:13 +010016397mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016398 Divides the input value of type signed integer by <value>, and returns the
16399 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016400 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010016401 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016402 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016403 "sess" : the variable is shared with the whole session
16404 "txn" : the variable is shared with the transaction (request and response)
16405 "req" : the variable is shared only during request processing
16406 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010016407 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016408 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010016409
Alexbf1bd5a2021-04-24 13:02:21 +020016410mqtt_field_value(<packettype>,<fieldname_or_property_ID>)
Baptiste Assmanne279ca62020-10-27 18:10:06 +010016411 Returns value of <fieldname> found in input MQTT payload of type
16412 <packettype>.
16413 <packettype> can be either a string (case insensitive matching) or a numeric
16414 value corresponding to the type of packet we're supposed to extract data
16415 from.
16416 Supported string and integers can be found here:
16417 https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718021
16418 https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901022
16419
16420 <fieldname> depends on <packettype> and can be any of the following below.
16421 (note that <fieldname> matching is case insensitive).
16422 <property id> can only be found in MQTT v5.0 streams. check this table:
16423 https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901029
16424
16425 - CONNECT (or 1): flags, protocol_name, protocol_version, client_identifier,
16426 will_topic, will_payload, username, password, keepalive
16427 OR any property ID as a numeric value (for MQTT v5.0
16428 packets only):
16429 17: Session Expiry Interval
16430 33: Receive Maximum
16431 39: Maximum Packet Size
16432 34: Topic Alias Maximum
16433 25: Request Response Information
16434 23: Request Problem Information
16435 21: Authentication Method
16436 22: Authentication Data
16437 18: Will Delay Interval
16438 1: Payload Format Indicator
16439 2: Message Expiry Interval
16440 3: Content Type
16441 8: Response Topic
16442 9: Correlation Data
16443 Not supported yet:
16444 38: User Property
16445
16446 - CONNACK (or 2): flags, protocol_version, reason_code
16447 OR any property ID as a numeric value (for MQTT v5.0
16448 packets only):
16449 17: Session Expiry Interval
16450 33: Receive Maximum
16451 36: Maximum QoS
16452 37: Retain Available
16453 39: Maximum Packet Size
16454 18: Assigned Client Identifier
16455 34: Topic Alias Maximum
16456 31: Reason String
16457 40; Wildcard Subscription Available
16458 41: Subscription Identifiers Available
16459 42: Shared Subscription Available
16460 19: Server Keep Alive
16461 26: Response Information
16462 28: Server Reference
16463 21: Authentication Method
16464 22: Authentication Data
16465 Not supported yet:
16466 38: User Property
16467
16468 Due to current HAProxy design, only the first message sent by the client and
16469 the server can be parsed. Thus this converter can extract data only from
16470 CONNECT and CONNACK packet types. CONNECT is the first message sent by the
16471 client and CONNACK is the first response sent by the server.
16472
16473 Example:
16474
16475 acl data_in_buffer req.len ge 4
16476 tcp-request content set-var(txn.username) \
16477 req.payload(0,0),mqtt_field_value(connect,protocol_name) \
16478 if data_in_buffer
16479 # do the same as above
16480 tcp-request content set-var(txn.username) \
16481 req.payload(0,0),mqtt_field_value(1,protocol_name) \
16482 if data_in_buffer
16483
16484mqtt_is_valid
16485 Checks that the binary input is a valid MQTT packet. It returns a boolean.
16486
16487 Due to current HAProxy design, only the first message sent by the client and
16488 the server can be parsed. Thus this converter can extract data only from
16489 CONNECT and CONNACK packet types. CONNECT is the first message sent by the
16490 client and CONNACK is the first response sent by the server.
16491
16492 Example:
16493
16494 acl data_in_buffer req.len ge 4
16495 tcp-request content reject unless req.payload(0,0),mqtt_is_valid
16496
Willy Tarreau97707872015-01-27 15:12:13 +010016497mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016498 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020016499 the product as an signed integer. In case of overflow, the largest possible
16500 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016501 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010016502 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016503 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016504 "sess" : the variable is shared with the whole session
16505 "txn" : the variable is shared with the transaction (request and response)
16506 "req" : the variable is shared only during request processing
16507 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010016508 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016509 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010016510
Nenad Merdanovicb7e7c472017-03-12 21:56:55 +010016511nbsrv
16512 Takes an input value of type string, interprets it as a backend name and
16513 returns the number of usable servers in that backend. Can be used in places
16514 where we want to look up a backend from a dynamic name, like a result of a
16515 map lookup.
16516
Willy Tarreau97707872015-01-27 15:12:13 +010016517neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016518 Takes the input value of type signed integer, computes the opposite value,
16519 and returns the remainder as an signed integer. 0 is identity. This operator
16520 is provided for reversed subtracts : in order to subtract the input from a
16521 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010016522
16523not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016524 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010016525 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010016526 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010016527 absence of a flag).
16528
16529odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016530 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010016531 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
16532
16533or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016534 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016535 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010016536 numeric value or a variable name. The name of the variable starts with an
16537 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016538 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016539 "sess" : the variable is shared with the whole session
16540 "txn" : the variable is shared with the transaction (request and response)
16541 "req" : the variable is shared only during request processing
16542 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010016543 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016544 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010016545
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010016546protobuf(<field_number>,[<field_type>])
16547 This extracts the protocol buffers message field in raw mode of an input binary
16548 sample representation of a protocol buffer message with <field_number> as field
16549 number (dotted notation) if <field_type> is not present, or as an integer sample
16550 if this field is present (see also "ungrpc" below).
16551 The list of the authorized types is the following one: "int32", "int64", "uint32",
16552 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
16553 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
16554 "float" for the wire type 5. Note that "string" is considered as a length-delimited
16555 type, so it does not require any <field_type> argument to be extracted.
16556 More information may be found here about the protocol buffers message field types:
16557 https://developers.google.com/protocol-buffers/docs/encoding
16558
Willy Tarreauc4dc3502015-01-23 20:39:28 +010016559regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010016560 Applies a regex-based substitution to the input string. It does the same
16561 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
16562 default it will replace in the input string the first occurrence of the
16563 largest part matching the regular expression <regex> with the substitution
16564 string <subst>. It is possible to replace all occurrences instead by adding
16565 the flag "g" in the third argument <flags>. It is also possible to make the
16566 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
16567 string, it is made up from the concatenation of all desired flags. Thus if
16568 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
Willy Tarreauef21fac2020-02-14 13:37:20 +010016569 The first use of this converter is to replace certain characters or sequence
16570 of characters with other ones.
16571
16572 It is highly recommended to enclose the regex part using protected quotes to
16573 improve clarity and never have a closing parenthesis from the regex mixed up
16574 with the parenthesis from the function. Just like in Bourne shell, the first
16575 level of quotes is processed when delimiting word groups on the line, a
16576 second level is usable for argument. It is recommended to use single quotes
16577 outside since these ones do not try to resolve backslashes nor dollar signs.
Willy Tarreau7eda8492015-01-20 19:47:06 +010016578
Willy Tarreaucd0d2ed2020-02-14 17:33:06 +010016579 Examples:
Willy Tarreau7eda8492015-01-20 19:47:06 +010016580
16581 # de-duplicate "/" in header "x-path".
16582 # input: x-path: /////a///b/c/xzxyz/
16583 # output: x-path: /a/b/c/xzxyz/
Willy Tarreauef21fac2020-02-14 13:37:20 +010016584 http-request set-header x-path "%[hdr(x-path),regsub('/+','/','g')]"
Willy Tarreau7eda8492015-01-20 19:47:06 +010016585
Willy Tarreaucd0d2ed2020-02-14 17:33:06 +010016586 # copy query string to x-query and drop all leading '?', ';' and '&'
16587 http-request set-header x-query "%[query,regsub([?;&]*,'')]"
16588
Jerome Magnin07e1e3c2020-02-16 19:20:19 +010016589 # capture groups and backreferences
16590 # both lines do the same.
Willy Tarreau465dc7d2020-10-08 18:05:56 +020016591 http-request redirect location %[url,'regsub("(foo|bar)([0-9]+)?","\2\1",i)']
Jerome Magnin07e1e3c2020-02-16 19:20:19 +010016592 http-request redirect location %[url,regsub(\"(foo|bar)([0-9]+)?\",\"\2\1\",i)]
16593
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020016594capture-req(<id>)
16595 Capture the string entry in the request slot <id> and returns the entry as
16596 is. If the slot doesn't exist, the capture fails silently.
16597
16598 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020016599 "http-response capture", "capture.req.hdr" and
16600 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020016601
16602capture-res(<id>)
16603 Capture the string entry in the response slot <id> and returns the entry as
16604 is. If the slot doesn't exist, the capture fails silently.
16605
16606 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020016607 "http-response capture", "capture.req.hdr" and
16608 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020016609
Christopher Faulet568415a2020-04-01 17:24:47 +020016610rtrim(<chars>)
16611 Skips any characters from <chars> from the end of the string representation
16612 of the input sample.
16613
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020016614sdbm([<avalanche>])
16615 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
16616 hash function. Optionally, it is possible to apply a full avalanche hash
16617 function to the output if the optional <avalanche> argument equals 1. This
16618 converter uses the same functions as used by the various hash-based load
16619 balancing algorithms, so it will provide exactly the same results. It is
16620 mostly intended for debugging, but can be used as a stick-table entry to
16621 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010016622 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c",
16623 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020016624
Tim Duesterhusf38175c2020-06-09 11:48:42 +020016625secure_memcmp(<var>)
16626 Compares the contents of <var> with the input value. Both values are treated
16627 as a binary string. Returns a boolean indicating whether both binary strings
16628 match.
16629
16630 If both binary strings have the same length then the comparison will be
16631 performed in constant time.
16632
Daniel Corbett9f0843f2021-05-08 10:50:37 -040016633 Please note that this converter is only available when HAProxy has been
Tim Duesterhusf38175c2020-06-09 11:48:42 +020016634 compiled with USE_OPENSSL.
16635
16636 Example :
16637
16638 http-request set-var(txn.token) hdr(token)
16639 # Check whether the token sent by the client matches the secret token
16640 # value, without leaking the contents using a timing attack.
16641 acl token_given str(my_secret_token),secure_memcmp(txn.token)
16642
Tim Duesterhusef4e45c2021-01-21 17:40:50 +010016643set-var(<var>)
Davor Ocelice9ed2812017-12-25 17:49:28 +010016644 Sets a variable with the input content and returns the content on the output
16645 as-is. The variable keeps the value and the associated input type. The name of
16646 the variable starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016647 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016648 "sess" : the variable is shared with the whole session
16649 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016650 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010016651 "req" : the variable is shared only during request processing,
16652 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016653 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016654 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016655
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020016656sha1
Tim Duesterhusd4376302019-06-17 12:41:44 +020016657 Converts a binary input sample to a SHA-1 digest. The result is a binary
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020016658 sample with length of 20 bytes.
16659
Tim Duesterhusd4376302019-06-17 12:41:44 +020016660sha2([<bits>])
16661 Converts a binary input sample to a digest in the SHA-2 family. The result
16662 is a binary sample with length of <bits>/8 bytes.
16663
16664 Valid values for <bits> are 224, 256, 384, 512, each corresponding to
16665 SHA-<bits>. The default value is 256.
16666
Daniel Corbett9f0843f2021-05-08 10:50:37 -040016667 Please note that this converter is only available when HAProxy has been
Tim Duesterhusd4376302019-06-17 12:41:44 +020016668 compiled with USE_OPENSSL.
16669
Nenad Merdanovic177adc92019-08-27 01:58:13 +020016670srv_queue
16671 Takes an input value of type string, either a server name or <backend>/<server>
16672 format and returns the number of queued sessions on that server. Can be used
16673 in places where we want to look up queued sessions from a dynamic name, like a
16674 cookie value (e.g. req.cook(SRVID),srv_queue) and then make a decision to break
16675 persistence or direct a request elsewhere.
16676
Tim Duesterhusca097c12018-04-27 21:18:45 +020016677strcmp(<var>)
16678 Compares the contents of <var> with the input value of type string. Returns
16679 the result as a signed integer compatible with strcmp(3): 0 if both strings
16680 are identical. A value less than 0 if the left string is lexicographically
16681 smaller than the right string or if the left string is shorter. A value greater
16682 than 0 otherwise (right string greater than left string or the right string is
16683 shorter).
16684
Tim Duesterhusf38175c2020-06-09 11:48:42 +020016685 See also the secure_memcmp converter if you need to compare two binary
16686 strings in constant time.
16687
Tim Duesterhusca097c12018-04-27 21:18:45 +020016688 Example :
16689
16690 http-request set-var(txn.host) hdr(host)
16691 # Check whether the client is attempting domain fronting.
16692 acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0
16693
16694
Willy Tarreau97707872015-01-27 15:12:13 +010016695sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016696 Subtracts <value> from the input value of type signed integer, and returns
16697 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016698 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
Daniel Schneller0b547052016-03-21 20:46:57 +010016699 or a variable name. The name of the variable starts with an indication about
16700 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016701 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016702 "sess" : the variable is shared with the whole session
16703 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016704 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010016705 "req" : the variable is shared only during request processing,
16706 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020016707 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016708 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010016709
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016710table_bytes_in_rate(<table>)
16711 Uses the string representation of the input sample to perform a look up in
16712 the specified table. If the key is not found in the table, integer value zero
16713 is returned. Otherwise the converter returns the average client-to-server
16714 bytes rate associated with the input sample in the designated table, measured
16715 in amount of bytes over the period configured in the table. See also the
16716 sc_bytes_in_rate sample fetch keyword.
16717
16718
16719table_bytes_out_rate(<table>)
16720 Uses the string representation of the input sample to perform a look up in
16721 the specified table. If the key is not found in the table, integer value zero
16722 is returned. Otherwise the converter returns the average server-to-client
16723 bytes rate associated with the input sample in the designated table, measured
16724 in amount of bytes over the period configured in the table. See also the
16725 sc_bytes_out_rate sample fetch keyword.
16726
16727table_conn_cnt(<table>)
16728 Uses the string representation of the input sample to perform a look up in
16729 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010016730 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016731 connections associated with the input sample in the designated table. See
16732 also the sc_conn_cnt sample fetch keyword.
16733
16734table_conn_cur(<table>)
16735 Uses the string representation of the input sample to perform a look up in
16736 the specified table. If the key is not found in the table, integer value zero
16737 is returned. Otherwise the converter returns the current amount of concurrent
16738 tracked connections associated with the input sample in the designated table.
16739 See also the sc_conn_cur sample fetch keyword.
16740
16741table_conn_rate(<table>)
16742 Uses the string representation of the input sample to perform a look up in
16743 the specified table. If the key is not found in the table, integer value zero
16744 is returned. Otherwise the converter returns the average incoming connection
16745 rate associated with the input sample in the designated table. See also the
16746 sc_conn_rate sample fetch keyword.
16747
Thierry FOURNIER236657b2015-08-19 08:25:14 +020016748table_gpt0(<table>)
16749 Uses the string representation of the input sample to perform a look up in
16750 the specified table. If the key is not found in the table, boolean value zero
16751 is returned. Otherwise the converter returns the current value of the first
16752 general purpose tag associated with the input sample in the designated table.
16753 See also the sc_get_gpt0 sample fetch keyword.
16754
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016755table_gpc0(<table>)
16756 Uses the string representation of the input sample to perform a look up in
16757 the specified table. If the key is not found in the table, integer value zero
16758 is returned. Otherwise the converter returns the current value of the first
16759 general purpose counter associated with the input sample in the designated
16760 table. See also the sc_get_gpc0 sample fetch keyword.
16761
16762table_gpc0_rate(<table>)
16763 Uses the string representation of the input sample to perform a look up in
16764 the specified table. If the key is not found in the table, integer value zero
16765 is returned. Otherwise the converter returns the frequency which the gpc0
16766 counter was incremented over the configured period in the table, associated
16767 with the input sample in the designated table. See also the sc_get_gpc0_rate
16768 sample fetch keyword.
16769
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016770table_gpc1(<table>)
16771 Uses the string representation of the input sample to perform a look up in
16772 the specified table. If the key is not found in the table, integer value zero
16773 is returned. Otherwise the converter returns the current value of the second
16774 general purpose counter associated with the input sample in the designated
16775 table. See also the sc_get_gpc1 sample fetch keyword.
16776
16777table_gpc1_rate(<table>)
16778 Uses the string representation of the input sample to perform a look up in
16779 the specified table. If the key is not found in the table, integer value zero
16780 is returned. Otherwise the converter returns the frequency which the gpc1
16781 counter was incremented over the configured period in the table, associated
16782 with the input sample in the designated table. See also the sc_get_gpc1_rate
16783 sample fetch keyword.
16784
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016785table_http_err_cnt(<table>)
16786 Uses the string representation of the input sample to perform a look up in
16787 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010016788 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016789 errors associated with the input sample in the designated table. See also the
16790 sc_http_err_cnt sample fetch keyword.
16791
16792table_http_err_rate(<table>)
16793 Uses the string representation of the input sample to perform a look up in
16794 the specified table. If the key is not found in the table, integer value zero
16795 is returned. Otherwise the average rate of HTTP errors associated with the
16796 input sample in the designated table, measured in amount of errors over the
16797 period configured in the table. See also the sc_http_err_rate sample fetch
16798 keyword.
16799
Willy Tarreau826f3ab2021-02-10 12:07:15 +010016800table_http_fail_cnt(<table>)
16801 Uses the string representation of the input sample to perform a look up in
16802 the specified table. If the key is not found in the table, integer value zero
16803 is returned. Otherwise the converter returns the cumulative number of HTTP
16804 failures associated with the input sample in the designated table. See also
16805 the sc_http_fail_cnt sample fetch keyword.
16806
16807table_http_fail_rate(<table>)
16808 Uses the string representation of the input sample to perform a look up in
16809 the specified table. If the key is not found in the table, integer value zero
16810 is returned. Otherwise the average rate of HTTP failures associated with the
16811 input sample in the designated table, measured in amount of failures over the
16812 period configured in the table. See also the sc_http_fail_rate sample fetch
16813 keyword.
16814
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016815table_http_req_cnt(<table>)
16816 Uses the string representation of the input sample to perform a look up in
16817 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010016818 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016819 requests associated with the input sample in the designated table. See also
16820 the sc_http_req_cnt sample fetch keyword.
16821
16822table_http_req_rate(<table>)
16823 Uses the string representation of the input sample to perform a look up in
16824 the specified table. If the key is not found in the table, integer value zero
16825 is returned. Otherwise the average rate of HTTP requests associated with the
16826 input sample in the designated table, measured in amount of requests over the
16827 period configured in the table. See also the sc_http_req_rate sample fetch
16828 keyword.
16829
16830table_kbytes_in(<table>)
16831 Uses the string representation of the input sample to perform a look up in
16832 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010016833 is returned. Otherwise the converter returns the cumulative number of client-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016834 to-server data associated with the input sample in the designated table,
16835 measured in kilobytes. The test is currently performed on 32-bit integers,
16836 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
16837 keyword.
16838
16839table_kbytes_out(<table>)
16840 Uses the string representation of the input sample to perform a look up in
16841 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010016842 is returned. Otherwise the converter returns the cumulative number of server-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016843 to-client data associated with the input sample in the designated table,
16844 measured in kilobytes. The test is currently performed on 32-bit integers,
16845 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
16846 keyword.
16847
16848table_server_id(<table>)
16849 Uses the string representation of the input sample to perform a look up in
16850 the specified table. If the key is not found in the table, integer value zero
16851 is returned. Otherwise the converter returns the server ID associated with
16852 the input sample in the designated table. A server ID is associated to a
16853 sample by a "stick" rule when a connection to a server succeeds. A server ID
16854 zero means that no server is associated with this key.
16855
16856table_sess_cnt(<table>)
16857 Uses the string representation of the input sample to perform a look up in
16858 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010016859 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020016860 sessions associated with the input sample in the designated table. Note that
16861 a session here refers to an incoming connection being accepted by the
16862 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
16863 keyword.
16864
16865table_sess_rate(<table>)
16866 Uses the string representation of the input sample to perform a look up in
16867 the specified table. If the key is not found in the table, integer value zero
16868 is returned. Otherwise the converter returns the average incoming session
16869 rate associated with the input sample in the designated table. Note that a
16870 session here refers to an incoming connection being accepted by the
16871 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
16872 keyword.
16873
16874table_trackers(<table>)
16875 Uses the string representation of the input sample to perform a look up in
16876 the specified table. If the key is not found in the table, integer value zero
16877 is returned. Otherwise the converter returns the current amount of concurrent
16878 connections tracking the same key as the input sample in the designated
16879 table. It differs from table_conn_cur in that it does not rely on any stored
16880 information but on the table's reference count (the "use" value which is
16881 returned by "show table" on the CLI). This may sometimes be more suited for
16882 layer7 tracking. It can be used to tell a server how many concurrent
16883 connections there are from a given address for example. See also the
16884 sc_trackers sample fetch keyword.
16885
Moemen MHEDHBI92f7d432021-04-01 20:53:59 +020016886ub64dec
16887 This converter is the base64url variant of b64dec converter. base64url
16888 encoding is the "URL and Filename Safe Alphabet" variant of base64 encoding.
16889 It is also the encoding used in JWT (JSON Web Token) standard.
16890
16891 Example:
16892 # Decoding a JWT payload:
16893 http-request set-var(txn.token_payload) req.hdr(Authorization),word(2,.),ub64dec
16894
16895ub64enc
16896 This converter is the base64url variant of base64 converter.
16897
Willy Tarreauffcb2e42014-07-10 16:29:08 +020016898upper
16899 Convert a string sample to upper case. This can only be placed after a string
16900 sample fetch function or after a transformation keyword returning a string
16901 type. The result is of type string.
16902
Willy Tarreau62ba9ba2020-04-23 17:54:47 +020016903url_dec([<in_form>])
16904 Takes an url-encoded string provided as input and returns the decoded version
16905 as output. The input and the output are of type string. If the <in_form>
16906 argument is set to a non-zero integer value, the input string is assumed to
16907 be part of a form or query string and the '+' character will be turned into a
16908 space (' '). Otherwise this will only happen after a question mark indicating
16909 a query string ('?').
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020016910
William Dauchy888b0ae2021-01-06 23:39:50 +010016911url_enc([<enc_type>])
16912 Takes a string provided as input and returns the encoded version as output.
16913 The input and the output are of type string. By default the type of encoding
16914 is meant for `query` type. There is no other type supported for now but the
16915 optional argument is here for future changes.
16916
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016917ungrpc(<field_number>,[<field_type>])
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010016918 This extracts the protocol buffers message field in raw mode of an input binary
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010016919 sample representation of a gRPC message with <field_number> as field number
16920 (dotted notation) if <field_type> is not present, or as an integer sample if this
16921 field is present.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016922 The list of the authorized types is the following one: "int32", "int64", "uint32",
16923 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
16924 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
16925 "float" for the wire type 5. Note that "string" is considered as a length-delimited
Frédéric Lécaille93d33162019-03-06 09:35:59 +010016926 type, so it does not require any <field_type> argument to be extracted.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016927 More information may be found here about the protocol buffers message field types:
16928 https://developers.google.com/protocol-buffers/docs/encoding
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010016929
16930 Example:
16931 // with such a protocol buffer .proto file content adapted from
16932 // https://github.com/grpc/grpc/blob/master/examples/protos/route_guide.proto
16933
16934 message Point {
16935 int32 latitude = 1;
16936 int32 longitude = 2;
16937 }
16938
16939 message PPoint {
16940 Point point = 59;
16941 }
16942
16943 message Rectangle {
16944 // One corner of the rectangle.
16945 PPoint lo = 48;
16946 // The other corner of the rectangle.
16947 PPoint hi = 49;
16948 }
16949
Peter Gervaidf4c9d22020-06-11 18:05:11 +020016950 let's say a body request is made of a "Rectangle" object value (two PPoint
16951 protocol buffers messages), the four protocol buffers fields could be
16952 extracted with these "ungrpc" directives:
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010016953
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016954 req.body,ungrpc(48.59.1,int32) # "latitude" of "lo" first PPoint
16955 req.body,ungrpc(48.59.2,int32) # "longitude" of "lo" first PPoint
John Roeslerfb2fce12019-07-10 15:45:51 -050016956 req.body,ungrpc(49.59.1,int32) # "latitude" of "hi" second PPoint
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016957 req.body,ungrpc(49.59.2,int32) # "longitude" of "hi" second PPoint
16958
Peter Gervaidf4c9d22020-06-11 18:05:11 +020016959 We could also extract the intermediary 48.59 field as a binary sample as follows:
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016960
Frédéric Lécaille93d33162019-03-06 09:35:59 +010016961 req.body,ungrpc(48.59)
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010016962
Peter Gervaidf4c9d22020-06-11 18:05:11 +020016963 As a gRPC message is always made of a gRPC header followed by protocol buffers
16964 messages, in the previous example the "latitude" of "lo" first PPoint
16965 could be extracted with these equivalent directives:
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010016966
16967 req.body,ungrpc(48.59),protobuf(1,int32)
16968 req.body,ungrpc(48),protobuf(59.1,int32)
16969 req.body,ungrpc(48),protobuf(59),protobuf(1,int32)
16970
Peter Gervaidf4c9d22020-06-11 18:05:11 +020016971 Note that the first convert must be "ungrpc", the remaining ones must be
16972 "protobuf" and only the last one may have or not a second argument to
16973 interpret the previous binary sample.
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010016974
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010016975
Tim Duesterhusef4e45c2021-01-21 17:40:50 +010016976unset-var(<var>)
Christopher Faulet85d79c92016-11-09 16:54:56 +010016977 Unsets a variable if the input content is defined. The name of the variable
16978 starts with an indication about its scope. The scopes allowed are:
16979 "proc" : the variable is shared with the whole process
16980 "sess" : the variable is shared with the whole session
16981 "txn" : the variable is shared with the transaction (request and
16982 response),
16983 "req" : the variable is shared only during request processing,
16984 "res" : the variable is shared only during response processing.
16985 This prefix is followed by a name. The separator is a '.'. The name may only
16986 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
16987
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020016988utime(<format>[,<offset>])
16989 Converts an integer supposed to contain a date since epoch to a string
16990 representing this date in UTC time using a format defined by the <format>
16991 string using strftime(3). The purpose is to allow any date format to be used
16992 in logs. An optional <offset> in seconds may be applied to the input date
16993 (positive or negative). See the strftime() man page for the format supported
16994 by your operating system. See also the ltime converter.
16995
16996 Example :
16997
16998 # Emit two colons, one with the UTC time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010016999 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020017000 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
17001
Marcin Deranek9631a282018-04-16 14:30:46 +020017002word(<index>,<delimiters>[,<count>])
17003 Extracts the nth word counting from the beginning (positive index) or from
17004 the end (negative index) considering given delimiters from an input string.
17005 Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
Jerome Magnin88209322020-01-28 13:33:44 +010017006 Delimiters at the beginning or end of the input string are ignored.
Marcin Deranek9631a282018-04-16 14:30:46 +020017007 Optionally you can specify <count> of words to extract (default: 1).
17008 Value of 0 indicates extraction of all remaining words.
17009
17010 Example :
17011 str(f1_f2_f3__f5),word(4,_) # f5
17012 str(f1_f2_f3__f5),word(2,_,0) # f2_f3__f5
17013 str(f1_f2_f3__f5),word(3,_,2) # f3__f5
17014 str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
17015 str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
Jerome Magnin88209322020-01-28 13:33:44 +010017016 str(/f1/f2/f3/f4),word(1,/) # f1
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010017017
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020017018wt6([<avalanche>])
17019 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
17020 hash function. Optionally, it is possible to apply a full avalanche hash
17021 function to the output if the optional <avalanche> argument equals 1. This
17022 converter uses the same functions as used by the various hash-based load
17023 balancing algorithms, so it will provide exactly the same results. It is
17024 mostly intended for debugging, but can be used as a stick-table entry to
17025 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010017026 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c",
17027 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020017028
Willy Tarreau97707872015-01-27 15:12:13 +010017029xor(<value>)
17030 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020017031 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020017032 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010017033 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010017034 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010017035 "sess" : the variable is shared with the whole session
17036 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020017037 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010017038 "req" : the variable is shared only during request processing,
17039 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020017040 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010017041 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010017042
Dragan Dosen04bf0cc2020-12-22 21:44:33 +010017043xxh3([<seed>])
17044 Hashes a binary input sample into a signed 64-bit quantity using the XXH3
17045 64-bit variant of the XXhash hash function. This hash supports a seed which
17046 defaults to zero but a different value maybe passed as the <seed> argument.
17047 This hash is known to be very good and very fast so it can be used to hash
17048 URLs and/or URL parameters for use as stick-table keys to collect statistics
17049 with a low collision rate, though care must be taken as the algorithm is not
17050 considered as cryptographically secure.
17051
Thierry FOURNIER01e09742016-12-26 11:46:11 +010017052xxh32([<seed>])
17053 Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
17054 variant of the XXHash hash function. This hash supports a seed which defaults
17055 to zero but a different value maybe passed as the <seed> argument. This hash
17056 is known to be very good and very fast so it can be used to hash URLs and/or
17057 URL parameters for use as stick-table keys to collect statistics with a low
17058 collision rate, though care must be taken as the algorithm is not considered
17059 as cryptographically secure.
17060
17061xxh64([<seed>])
17062 Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
17063 variant of the XXHash hash function. This hash supports a seed which defaults
17064 to zero but a different value maybe passed as the <seed> argument. This hash
17065 is known to be very good and very fast so it can be used to hash URLs and/or
17066 URL parameters for use as stick-table keys to collect statistics with a low
17067 collision rate, though care must be taken as the algorithm is not considered
17068 as cryptographically secure.
17069
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010017070
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200170717.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020017072--------------------------------------------
17073
17074A first set of sample fetch methods applies to internal information which does
17075not even relate to any client information. These ones are sometimes used with
17076"monitor-fail" directives to report an internal status to external watchers.
17077The sample fetch methods described in this section are usable anywhere.
17078
17079always_false : boolean
17080 Always returns the boolean "false" value. It may be used with ACLs as a
17081 temporary replacement for another one when adjusting configurations.
17082
17083always_true : boolean
17084 Always returns the boolean "true" value. It may be used with ACLs as a
17085 temporary replacement for another one when adjusting configurations.
17086
17087avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010017088 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020017089 divided by the number of active servers. The current backend is used if no
17090 backend is specified. This is very similar to "queue" except that the size of
17091 the farm is considered, in order to give a more accurate measurement of the
17092 time it may take for a new connection to be processed. The main usage is with
17093 ACL to return a sorry page to new users when it becomes certain they will get
17094 a degraded service, or to pass to the backend servers in a header so that
17095 they decide to work in degraded mode or to disable some functions to speed up
17096 the processing a bit. Note that in the event there would not be any active
17097 server anymore, twice the number of queued connections would be considered as
17098 the measured value. This is a fair estimate, as we expect one server to get
17099 back soon anyway, but we still prefer to send new traffic to another backend
17100 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
17101 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010017102
Willy Tarreau74ca5042013-06-11 23:12:07 +020017103be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020017104 Applies to the number of currently established connections on the backend,
17105 possibly including the connection being evaluated. If no backend name is
17106 specified, the current one is used. But it is also possible to check another
17107 backend. It can be used to use a specific farm when the nominal one is full.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040017108 See also the "fe_conn", "queue", "be_conn_free", and "be_sess_rate" criteria.
17109
17110be_conn_free([<backend>]) : integer
17111 Returns an integer value corresponding to the number of available connections
17112 across available servers in the backend. Queue slots are not included. Backup
17113 servers are also not included, unless all other servers are down. If no
17114 backend name is specified, the current one is used. But it is also possible
17115 to check another backend. It can be used to use a specific farm when the
Patrick Hemmer155e93e2018-06-14 18:01:35 -040017116 nominal one is full. See also the "be_conn", "connslots", and "srv_conn_free"
17117 criteria.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040017118
17119 OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0
17120 (meaning unlimited), then this fetch clearly does not make sense, in which
17121 case the value returned will be -1.
Willy Tarreau6a06a402007-07-15 20:15:28 +020017122
Willy Tarreau74ca5042013-06-11 23:12:07 +020017123be_sess_rate([<backend>]) : integer
17124 Returns an integer value corresponding to the sessions creation rate on the
17125 backend, in number of new sessions per second. This is used with ACLs to
17126 switch to an alternate backend when an expensive or fragile one reaches too
Davor Ocelice9ed2812017-12-25 17:49:28 +010017127 high a session rate, or to limit abuse of service (e.g. prevent sucking of an
Willy Tarreau74ca5042013-06-11 23:12:07 +020017128 online dictionary). It can also be useful to add this element to logs using a
17129 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017130
17131 Example :
17132 # Redirect to an error page if the dictionary is requested too often
17133 backend dynamic
17134 mode http
17135 acl being_scanned be_sess_rate gt 100
17136 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010017137
Davor Ocelice9ed2812017-12-25 17:49:28 +010017138bin(<hex>) : bin
Thierry FOURNIERcc103292015-06-06 19:30:17 +020017139 Returns a binary chain. The input is the hexadecimal representation
17140 of the string.
17141
17142bool(<bool>) : bool
17143 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
17144 'false' and '0' are the same. 'true' and '1' are the same.
17145
Willy Tarreau74ca5042013-06-11 23:12:07 +020017146connslots([<backend>]) : integer
17147 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017148 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020017149 connections on all servers and the maximum queue size. This is probably only
17150 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050017151
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080017152 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020017153 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080017154 usage; see "use_backend" keyword) can be redirected to a different backend.
17155
Willy Tarreau55165fe2009-05-10 12:02:55 +020017156 'connslots' = number of available server connection slots, + number of
17157 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080017158
Willy Tarreaua36af912009-10-10 12:02:45 +020017159 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020017160 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020017161 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020017162 you want to be able to differentiate between different backends, and their
Davor Ocelice9ed2812017-12-25 17:49:28 +010017163 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020017164 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020017165 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080017166
Willy Tarreau55165fe2009-05-10 12:02:55 +020017167 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
17168 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020017169 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020017170 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080017171
Willy Tarreau70fe9442018-11-22 16:07:39 +010017172cpu_calls : integer
17173 Returns the number of calls to the task processing the stream or current
17174 request since it was allocated. This number is reset for each new request on
17175 the same connections in case of HTTP keep-alive. This value should usually be
17176 low and stable (around 2 calls for a typically simple request) but may become
17177 high if some processing (compression, caching or analysis) is performed. This
17178 is purely for performance monitoring purposes.
17179
17180cpu_ns_avg : integer
17181 Returns the average number of nanoseconds spent in each call to the task
17182 processing the stream or current request. This number is reset for each new
17183 request on the same connections in case of HTTP keep-alive. This value
17184 indicates the overall cost of processing the request or the connection for
17185 each call. There is no good nor bad value but the time spent in a call
17186 automatically causes latency for other processing (see lat_ns_avg below),
17187 and may affect other connection's apparent response time. Certain operations
17188 like compression, complex regex matching or heavy Lua operations may directly
17189 affect this value, and having it in the logs will make it easier to spot the
17190 faulty processing that needs to be fixed to recover decent performance.
17191 Note: this value is exactly cpu_ns_tot divided by cpu_calls.
17192
17193cpu_ns_tot : integer
17194 Returns the total number of nanoseconds spent in each call to the task
17195 processing the stream or current request. This number is reset for each new
17196 request on the same connections in case of HTTP keep-alive. This value
17197 indicates the overall cost of processing the request or the connection for
17198 each call. There is no good nor bad value but the time spent in a call
17199 automatically causes latency for other processing (see lat_ns_avg below),
17200 induces CPU costs on the machine, and may affect other connection's apparent
17201 response time. Certain operations like compression, complex regex matching or
17202 heavy Lua operations may directly affect this value, and having it in the
17203 logs will make it easier to spot the faulty processing that needs to be fixed
17204 to recover decent performance. The value may be artificially high due to a
17205 high cpu_calls count, for example when processing many HTTP chunks, and for
17206 this reason it is often preferred to log cpu_ns_avg instead.
17207
Cyril Bonté6bcd1822019-11-05 23:13:59 +010017208date([<offset>],[<unit>]) : integer
Willy Tarreau6236d3a2013-07-25 14:28:25 +020017209 Returns the current date as the epoch (number of seconds since 01/01/1970).
Damien Claisseae6f1252019-10-30 15:57:28 +000017210
17211 If an offset value is specified, then it is added to the current date before
17212 returning the value. This is particularly useful to compute relative dates,
17213 as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020017214 It is useful combined with the http_date converter.
17215
Damien Claisseae6f1252019-10-30 15:57:28 +000017216 <unit> is facultative, and can be set to "s" for seconds (default behavior),
17217 "ms" for milliseconds or "us" for microseconds.
17218 If unit is set, return value is an integer reflecting either seconds,
17219 milliseconds or microseconds since epoch, plus offset.
17220 It is useful when a time resolution of less than a second is needed.
17221
Willy Tarreau276fae92013-07-25 14:36:01 +020017222 Example :
17223
17224 # set an expires header to now+1 hour in every response
17225 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020017226
Damien Claisseae6f1252019-10-30 15:57:28 +000017227 # set an expires header to now+1 hour in every response, with
17228 # millisecond granularity
17229 http-response set-header Expires %[date(3600000,ms),http_date(0,ms)]
17230
Etienne Carrierea792a0a2018-01-17 13:43:24 +010017231date_us : integer
17232 Return the microseconds part of the date (the "second" part is returned by
17233 date sample). This sample is coherent with the date sample as it is comes
17234 from the same timeval structure.
17235
Willy Tarreaud716f9b2017-10-13 11:03:15 +020017236distcc_body(<token>[,<occ>]) : binary
17237 Parses a distcc message and returns the body associated to occurrence #<occ>
17238 of the token <token>. Occurrences start at 1, and when unspecified, any may
17239 match though in practice only the first one is checked for now. This can be
17240 used to extract file names or arguments in files built using distcc through
Daniel Corbett9f0843f2021-05-08 10:50:37 -040017241 HAProxy. Please refer to distcc's protocol documentation for the complete
Willy Tarreaud716f9b2017-10-13 11:03:15 +020017242 list of supported tokens.
17243
17244distcc_param(<token>[,<occ>]) : integer
17245 Parses a distcc message and returns the parameter associated to occurrence
17246 #<occ> of the token <token>. Occurrences start at 1, and when unspecified,
17247 any may match though in practice only the first one is checked for now. This
17248 can be used to extract certain information such as the protocol version, the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040017249 file size or the argument in files built using distcc through HAProxy.
Willy Tarreaud716f9b2017-10-13 11:03:15 +020017250 Another use case consists in waiting for the start of the preprocessed file
17251 contents before connecting to the server to avoid keeping idle connections.
17252 Please refer to distcc's protocol documentation for the complete list of
17253 supported tokens.
17254
17255 Example :
17256 # wait up to 20s for the pre-processed file to be uploaded
17257 tcp-request inspect-delay 20s
17258 tcp-request content accept if { distcc_param(DOTI) -m found }
17259 # send large files to the big farm
17260 use_backend big_farm if { distcc_param(DOTI) gt 1000000 }
17261
Willy Tarreau595ec542013-06-12 21:34:28 +020017262env(<name>) : string
17263 Returns a string containing the value of environment variable <name>. As a
17264 reminder, environment variables are per-process and are sampled when the
17265 process starts. This can be useful to pass some information to a next hop
17266 server, or with ACLs to take specific action when the process is started a
17267 certain way.
17268
17269 Examples :
17270 # Pass the Via header to next hop with the local hostname in it
17271 http-request add-header Via 1.1\ %[env(HOSTNAME)]
17272
17273 # reject cookie-less requests when the STOP environment variable is set
17274 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
17275
Willy Tarreau74ca5042013-06-11 23:12:07 +020017276fe_conn([<frontend>]) : integer
17277 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010017278 possibly including the connection being evaluated. If no frontend name is
17279 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020017280 frontend. It can be used to return a sorry page before hard-blocking, or to
17281 use a specific backend to drain new requests when the farm is considered
Davor Ocelice9ed2812017-12-25 17:49:28 +010017282 full. This is mostly used with ACLs but can also be used to pass some
Willy Tarreau74ca5042013-06-11 23:12:07 +020017283 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
17284 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020017285
Nenad Merdanovicad9a7e92016-10-03 04:57:37 +020017286fe_req_rate([<frontend>]) : integer
17287 Returns an integer value corresponding to the number of HTTP requests per
17288 second sent to a frontend. This number can differ from "fe_sess_rate" in
17289 situations where client-side keep-alive is enabled.
17290
Willy Tarreau74ca5042013-06-11 23:12:07 +020017291fe_sess_rate([<frontend>]) : integer
17292 Returns an integer value corresponding to the sessions creation rate on the
17293 frontend, in number of new sessions per second. This is used with ACLs to
17294 limit the incoming session rate to an acceptable range in order to prevent
17295 abuse of service at the earliest moment, for example when combined with other
17296 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
17297 down below the limit. It can also be useful to add this element to logs using
17298 a log-format directive. See also the "rate-limit sessions" directive for use
17299 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010017300
17301 Example :
17302 # This frontend limits incoming mails to 10/s with a max of 100
17303 # concurrent connections. We accept any connection below 10/s, and
17304 # force excess clients to wait for 100 ms. Since clients are limited to
17305 # 100 max, there cannot be more than 10 incoming mails per second.
17306 frontend mail
17307 bind :25
17308 mode tcp
17309 maxconn 100
17310 acl too_fast fe_sess_rate ge 10
17311 tcp-request inspect-delay 100ms
17312 tcp-request content accept if ! too_fast
17313 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010017314
Nenad Merdanovic807a6e72017-03-12 22:00:00 +010017315hostname : string
17316 Returns the system hostname.
17317
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020017318int(<integer>) : signed integer
17319 Returns a signed integer.
17320
Thierry FOURNIERcc103292015-06-06 19:30:17 +020017321ipv4(<ipv4>) : ipv4
17322 Returns an ipv4.
17323
17324ipv6(<ipv6>) : ipv6
17325 Returns an ipv6.
17326
Willy Tarreau70fe9442018-11-22 16:07:39 +010017327lat_ns_avg : integer
17328 Returns the average number of nanoseconds spent between the moment the task
17329 handling the stream is woken up and the moment it is effectively called. This
17330 number is reset for each new request on the same connections in case of HTTP
17331 keep-alive. This value indicates the overall latency inflicted to the current
17332 request by all other requests being processed in parallel, and is a direct
17333 indicator of perceived performance due to noisy neighbours. In order to keep
17334 the value low, it is possible to reduce the scheduler's run queue depth using
17335 "tune.runqueue-depth", to reduce the number of concurrent events processed at
17336 once using "tune.maxpollevents", to decrease the stream's nice value using
Willy Tarreaue7723bd2020-06-24 11:11:02 +020017337 the "nice" option on the "bind" lines or in the frontend, to enable low
17338 latency scheduling using "tune.sched.low-latency", or to look for other heavy
17339 requests in logs (those exhibiting large values of "cpu_ns_avg"), whose
17340 processing needs to be adjusted or fixed. Compression of large buffers could
17341 be a culprit, like heavy regex or long lists of regex. Note: this value is
17342 exactly lat_ns_tot divided by cpu_calls.
Willy Tarreau70fe9442018-11-22 16:07:39 +010017343
17344lat_ns_tot : integer
17345 Returns the total number of nanoseconds spent between the moment the task
17346 handling the stream is woken up and the moment it is effectively called. This
17347 number is reset for each new request on the same connections in case of HTTP
17348 keep-alive. This value indicates the overall latency inflicted to the current
17349 request by all other requests being processed in parallel, and is a direct
17350 indicator of perceived performance due to noisy neighbours. In order to keep
17351 the value low, it is possible to reduce the scheduler's run queue depth using
17352 "tune.runqueue-depth", to reduce the number of concurrent events processed at
17353 once using "tune.maxpollevents", to decrease the stream's nice value using
Willy Tarreaue7723bd2020-06-24 11:11:02 +020017354 the "nice" option on the "bind" lines or in the frontend, to enable low
17355 latency scheduling using "tune.sched.low-latency", or to look for other heavy
17356 requests in logs (those exhibiting large values of "cpu_ns_avg"), whose
17357 processing needs to be adjusted or fixed. Compression of large buffers could
17358 be a culprit, like heavy regex or long lists of regex. Note: while it
Willy Tarreau70fe9442018-11-22 16:07:39 +010017359 may intuitively seem that the total latency adds to a transfer time, it is
17360 almost never true because while a task waits for the CPU, network buffers
17361 continue to fill up and the next call will process more at once. The value
17362 may be artificially high due to a high cpu_calls count, for example when
17363 processing many HTTP chunks, and for this reason it is often preferred to log
17364 lat_ns_avg instead, which is a more relevant performance indicator.
17365
Thierry FOURNIERcc103292015-06-06 19:30:17 +020017366meth(<method>) : method
17367 Returns a method.
17368
Willy Tarreau0f30d262014-11-24 16:02:05 +010017369nbproc : integer
17370 Returns an integer value corresponding to the number of processes that were
17371 started (it equals the global "nbproc" setting). This is useful for logging
17372 and debugging purposes.
17373
Willy Tarreau74ca5042013-06-11 23:12:07 +020017374nbsrv([<backend>]) : integer
17375 Returns an integer value corresponding to the number of usable servers of
17376 either the current backend or the named backend. This is mostly used with
17377 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010017378 switch to an alternate backend when the number of servers is too low to
17379 to handle some load. It is useful to report a failure when combined with
17380 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010017381
Patrick Hemmerfabb24f2018-08-13 14:07:57 -040017382prio_class : integer
17383 Returns the priority class of the current session for http mode or connection
17384 for tcp mode. The value will be that set by the last call to "http-request
17385 set-priority-class" or "tcp-request content set-priority-class".
17386
17387prio_offset : integer
17388 Returns the priority offset of the current session for http mode or
17389 connection for tcp mode. The value will be that set by the last call to
17390 "http-request set-priority-offset" or "tcp-request content
17391 set-priority-offset".
17392
Willy Tarreau0f30d262014-11-24 16:02:05 +010017393proc : integer
17394 Returns an integer value corresponding to the position of the process calling
17395 the function, between 1 and global.nbproc. This is useful for logging and
17396 debugging purposes.
17397
Willy Tarreau74ca5042013-06-11 23:12:07 +020017398queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010017399 Returns the total number of queued connections of the designated backend,
17400 including all the connections in server queues. If no backend name is
17401 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020017402 one. This is useful with ACLs or to pass statistics to backend servers. This
17403 can be used to take actions when queuing goes above a known level, generally
17404 indicating a surge of traffic or a massive slowdown on the servers. One
17405 possible action could be to reject new users but still accept old ones. See
17406 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
17407
Willy Tarreau84310e22014-02-14 11:59:04 +010017408rand([<range>]) : integer
17409 Returns a random integer value within a range of <range> possible values,
17410 starting at zero. If the range is not specified, it defaults to 2^32, which
17411 gives numbers between 0 and 4294967295. It can be useful to pass some values
17412 needed to take some routing decisions for example, or just for debugging
17413 purposes. This random must not be used for security purposes.
17414
Luca Schimweg8a694b82019-09-10 15:42:52 +020017415uuid([<version>]) : string
17416 Returns a UUID following the RFC4122 standard. If the version is not
17417 specified, a UUID version 4 (fully random) is returned.
17418 Currently, only version 4 is supported.
17419
Willy Tarreau74ca5042013-06-11 23:12:07 +020017420srv_conn([<backend>/]<server>) : integer
17421 Returns an integer value corresponding to the number of currently established
17422 connections on the designated server, possibly including the connection being
17423 evaluated. If <backend> is omitted, then the server is looked up in the
17424 current backend. It can be used to use a specific farm when one server is
17425 full, or to inform the server about our view of the number of active
Patrick Hemmer155e93e2018-06-14 18:01:35 -040017426 connections with it. See also the "fe_conn", "be_conn", "queue", and
17427 "srv_conn_free" fetch methods.
17428
17429srv_conn_free([<backend>/]<server>) : integer
17430 Returns an integer value corresponding to the number of available connections
17431 on the designated server, possibly including the connection being evaluated.
17432 The value does not include queue slots. If <backend> is omitted, then the
17433 server is looked up in the current backend. It can be used to use a specific
17434 farm when one server is full, or to inform the server about our view of the
17435 number of active connections with it. See also the "be_conn_free" and
17436 "srv_conn" fetch methods.
17437
17438 OTHER CAVEATS AND NOTES: If the server maxconn is 0, then this fetch clearly
17439 does not make sense, in which case the value returned will be -1.
Willy Tarreau74ca5042013-06-11 23:12:07 +020017440
17441srv_is_up([<backend>/]<server>) : boolean
17442 Returns true when the designated server is UP, and false when it is either
17443 DOWN or in maintenance mode. If <backend> is omitted, then the server is
17444 looked up in the current backend. It is mainly used to take action based on
Davor Ocelice9ed2812017-12-25 17:49:28 +010017445 an external status reported via a health check (e.g. a geographical site's
Willy Tarreau74ca5042013-06-11 23:12:07 +020017446 availability). Another possible use which is more of a hack consists in
17447 using dummy servers as boolean variables that can be enabled or disabled from
17448 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
17449
Willy Tarreauff2b7af2017-10-13 11:46:26 +020017450srv_queue([<backend>/]<server>) : integer
17451 Returns an integer value corresponding to the number of connections currently
17452 pending in the designated server's queue. If <backend> is omitted, then the
17453 server is looked up in the current backend. It can sometimes be used together
17454 with the "use-server" directive to force to use a known faster server when it
17455 is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample
17456 fetch methods.
17457
Willy Tarreau74ca5042013-06-11 23:12:07 +020017458srv_sess_rate([<backend>/]<server>) : integer
17459 Returns an integer corresponding to the sessions creation rate on the
17460 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017461 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020017462 used with ACLs but can make sense with logs too. This is used to switch to an
17463 alternate backend when an expensive or fragile one reaches too high a session
Davor Ocelice9ed2812017-12-25 17:49:28 +010017464 rate, or to limit abuse of service (e.g. prevent latent requests from
Willy Tarreau74ca5042013-06-11 23:12:07 +020017465 overloading servers).
17466
17467 Example :
17468 # Redirect to a separate back
17469 acl srv1_full srv_sess_rate(be1/srv1) gt 50
17470 acl srv2_full srv_sess_rate(be1/srv2) gt 50
17471 use_backend be2 if srv1_full or srv2_full
17472
Alexbf1bd5a2021-04-24 13:02:21 +020017473srv_iweight([<backend>/]<server>) : integer
Christopher Faulet1bea8652020-07-10 16:03:45 +020017474 Returns an integer corresponding to the server's initial weight. If <backend>
17475 is omitted, then the server is looked up in the current backend. See also
17476 "srv_weight" and "srv_uweight".
17477
Alexbf1bd5a2021-04-24 13:02:21 +020017478srv_uweight([<backend>/]<server>) : integer
Christopher Faulet1bea8652020-07-10 16:03:45 +020017479 Returns an integer corresponding to the user visible server's weight. If
17480 <backend> is omitted, then the server is looked up in the current
17481 backend. See also "srv_weight" and "srv_iweight".
17482
Alexbf1bd5a2021-04-24 13:02:21 +020017483srv_weight([<backend>/]<server>) : integer
Christopher Faulet1bea8652020-07-10 16:03:45 +020017484 Returns an integer corresponding to the current (or effective) server's
17485 weight. If <backend> is omitted, then the server is looked up in the current
17486 backend. See also "srv_iweight" and "srv_uweight".
17487
Willy Tarreau0f30d262014-11-24 16:02:05 +010017488stopping : boolean
17489 Returns TRUE if the process calling the function is currently stopping. This
17490 can be useful for logging, or for relaxing certain checks or helping close
17491 certain connections upon graceful shutdown.
17492
Thierry FOURNIERcc103292015-06-06 19:30:17 +020017493str(<string>) : string
17494 Returns a string.
17495
Willy Tarreau74ca5042013-06-11 23:12:07 +020017496table_avl([<table>]) : integer
17497 Returns the total number of available entries in the current proxy's
17498 stick-table or in the designated stick-table. See also table_cnt.
17499
17500table_cnt([<table>]) : integer
17501 Returns the total number of entries currently in use in the current proxy's
17502 stick-table or in the designated stick-table. See also src_conn_cnt and
17503 table_avl for other entry counting methods.
17504
Christopher Faulet34adb2a2017-11-21 21:45:38 +010017505thread : integer
17506 Returns an integer value corresponding to the position of the thread calling
17507 the function, between 0 and (global.nbthread-1). This is useful for logging
17508 and debugging purposes.
17509
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020017510var(<var-name>) : undefined
17511 Returns a variable with the stored type. If the variable is not set, the
Daniel Schneller0b547052016-03-21 20:46:57 +010017512 sample fetch fails. The name of the variable starts with an indication
17513 about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010017514 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010017515 "sess" : the variable is shared with the whole session
17516 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020017517 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010017518 "req" : the variable is shared only during request processing,
17519 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020017520 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010017521 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020017522
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200175237.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020017524----------------------------------
17525
Daniel Corbett9f0843f2021-05-08 10:50:37 -040017526The layer 4 usually describes just the transport layer which in HAProxy is
Willy Tarreau74ca5042013-06-11 23:12:07 +020017527closest to the connection, where no content is yet made available. The fetch
17528methods described here are usable as low as the "tcp-request connection" rule
17529sets unless they require some future information. Those generally include
17530TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020017531the incoming connection. For retrieving a value from a sticky counters, the
17532counter number can be explicitly set as 0, 1, or 2 using the pre-defined
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020017533"sc0_", "sc1_", or "sc2_" prefix. These three pre-defined prefixes can only be
17534used if MAX_SESS_STKCTR value does not exceed 3, otherwise the counter number
17535can be specified as the first integer argument when using the "sc_" prefix.
17536Starting from "sc_0" to "sc_N" where N is (MAX_SESS_STKCTR-1). An optional
17537table may be specified with the "sc*" form, in which case the currently
17538tracked key will be looked up into this alternate table instead of the table
17539currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020017540
Christopher Faulet7d081f02021-04-15 09:38:37 +020017541bc_dst : ip
17542 This is the destination ip address of the connection on the server side,
17543 which is the server address HAProxy connected to. It is of type IP and works
17544 on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 address is mapped to its
17545 IPv6 equivalent, according to RFC 4291.
17546
17547bc_dst_port : integer
17548 Returns an integer value corresponding to the destination TCP port of the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040017549 connection on the server side, which is the port HAProxy connected to.
Christopher Faulet7d081f02021-04-15 09:38:37 +020017550
Jérôme Magnin35e53a62019-01-16 14:38:37 +010017551bc_http_major : integer
Jérôme Magnin86577422018-12-07 09:03:11 +010017552 Returns the backend connection's HTTP major version encoding, which may be 1
17553 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
17554 encoding and not the version present in the request header.
17555
Christopher Faulet7d081f02021-04-15 09:38:37 +020017556bc_src : ip
17557 This is the source ip address of the connection on the server side, which is
Daniel Corbett9f0843f2021-05-08 10:50:37 -040017558 the server address HAProxy connected from. It is of type IP and works on both
Christopher Faulet7d081f02021-04-15 09:38:37 +020017559 IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are mapped to their IPv6
17560 equivalent, according to RFC 4291.
17561
17562bc_src_port : integer
17563 Returns an integer value corresponding to the TCP source port of the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040017564 connection on the server side, which is the port HAProxy connected from.
Christopher Faulet7d081f02021-04-15 09:38:37 +020017565
Willy Tarreau74ca5042013-06-11 23:12:07 +020017566be_id : integer
17567 Returns an integer containing the current backend's id. It can be used in
Christopher Fauletd1b44642020-04-30 09:51:15 +020017568 frontends with responses to check which backend processed the request. It can
17569 also be used in a tcp-check or an http-check ruleset.
Willy Tarreau74ca5042013-06-11 23:12:07 +020017570
Marcin Deranekd2471c22016-12-12 14:08:05 +010017571be_name : string
17572 Returns a string containing the current backend's name. It can be used in
Christopher Fauletd1b44642020-04-30 09:51:15 +020017573 frontends with responses to check which backend processed the request. It can
17574 also be used in a tcp-check or an http-check ruleset.
Marcin Deranekd2471c22016-12-12 14:08:05 +010017575
Amaury Denoyelled91d7792020-12-10 13:43:56 +010017576be_server_timeout : integer
17577 Returns the configuration value in millisecond for the server timeout of the
17578 current backend. This timeout can be overwritten by a "set-timeout" rule. See
17579 also the "cur_server_timeout".
17580
17581be_tunnel_timeout : integer
17582 Returns the configuration value in millisecond for the tunnel timeout of the
17583 current backend. This timeout can be overwritten by a "set-timeout" rule. See
17584 also the "cur_tunnel_timeout".
17585
Amaury Denoyellef7719a22020-12-10 13:43:58 +010017586cur_server_timeout : integer
17587 Returns the currently applied server timeout in millisecond for the stream.
17588 In the default case, this will be equal to be_server_timeout unless a
17589 "set-timeout" rule has been applied. See also "be_server_timeout".
17590
17591cur_tunnel_timeout : integer
17592 Returns the currently applied tunnel timeout in millisecond for the stream.
17593 In the default case, this will be equal to be_tunnel_timeout unless a
17594 "set-timeout" rule has been applied. See also "be_tunnel_timeout".
17595
Willy Tarreau74ca5042013-06-11 23:12:07 +020017596dst : ip
17597 This is the destination IPv4 address of the connection on the client side,
17598 which is the address the client connected to. It can be useful when running
17599 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
17600 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
Willy Tarreau64ded3d2019-01-23 10:02:15 +010017601 RFC 4291. When the incoming connection passed through address translation or
17602 redirection involving connection tracking, the original destination address
17603 before the redirection will be reported. On Linux systems, the source and
17604 destination may seldom appear reversed if the nf_conntrack_tcp_loose sysctl
17605 is set, because a late response may reopen a timed out connection and switch
17606 what is believed to be the source and the destination.
Willy Tarreau74ca5042013-06-11 23:12:07 +020017607
17608dst_conn : integer
17609 Returns an integer value corresponding to the number of currently established
17610 connections on the same socket including the one being evaluated. It is
17611 normally used with ACLs but can as well be used to pass the information to
17612 servers in an HTTP header or in logs. It can be used to either return a sorry
17613 page before hard-blocking, or to use a specific backend to drain new requests
17614 when the socket is considered saturated. This offers the ability to assign
17615 different limits to different listening ports or addresses. See also the
17616 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017617
Willy Tarreau16e01562016-08-09 16:46:18 +020017618dst_is_local : boolean
17619 Returns true if the destination address of the incoming connection is local
17620 to the system, or false if the address doesn't exist on the system, meaning
17621 that it was intercepted in transparent mode. It can be useful to apply
17622 certain rules by default to forwarded traffic and other rules to the traffic
Davor Ocelice9ed2812017-12-25 17:49:28 +010017623 targeting the real address of the machine. For example the stats page could
Willy Tarreau16e01562016-08-09 16:46:18 +020017624 be delivered only on this address, or SSH access could be locally redirected.
17625 Please note that the check involves a few system calls, so it's better to do
17626 it only once per connection.
17627
Willy Tarreau74ca5042013-06-11 23:12:07 +020017628dst_port : integer
17629 Returns an integer value corresponding to the destination TCP port of the
17630 connection on the client side, which is the port the client connected to.
17631 This might be used when running in transparent mode, when assigning dynamic
17632 ports to some clients for a whole application session, to stick all users to
17633 a same server, or to pass the destination port information to a server using
17634 an HTTP header.
17635
Willy Tarreau60ca10a2017-08-18 15:26:54 +020017636fc_http_major : integer
17637 Reports the front connection's HTTP major version encoding, which may be 1
17638 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
17639 encoding and not on the version present in the request header.
17640
Geoff Simmons7185b782019-08-27 18:31:16 +020017641fc_pp_authority : string
17642 Returns the authority TLV sent by the client in the PROXY protocol header,
17643 if any.
17644
Tim Duesterhusd1b15b62020-03-13 12:34:23 +010017645fc_pp_unique_id : string
17646 Returns the unique ID TLV sent by the client in the PROXY protocol header,
17647 if any.
17648
Emeric Brun4f603012017-01-05 15:11:44 +010017649fc_rcvd_proxy : boolean
17650 Returns true if the client initiated the connection with a PROXY protocol
17651 header.
17652
Thierry Fournier / OZON.IO6310bef2016-07-24 20:16:50 +020017653fc_rtt(<unit>) : integer
17654 Returns the Round Trip Time (RTT) measured by the kernel for the client
17655 connection. <unit> is facultative, by default the unit is milliseconds. <unit>
17656 can be set to "ms" for milliseconds or "us" for microseconds. If the server
17657 connection is not established, if the connection is not TCP or if the
17658 operating system does not support TCP_INFO, for example Linux kernels before
17659 2.4, the sample fetch fails.
17660
17661fc_rttvar(<unit>) : integer
17662 Returns the Round Trip Time (RTT) variance measured by the kernel for the
17663 client connection. <unit> is facultative, by default the unit is milliseconds.
17664 <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the
17665 server connection is not established, if the connection is not TCP or if the
17666 operating system does not support TCP_INFO, for example Linux kernels before
17667 2.4, the sample fetch fails.
17668
Christopher Fauletba0c53e2019-10-17 14:40:48 +020017669fc_unacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070017670 Returns the unacked counter measured by the kernel for the client connection.
17671 If the server connection is not established, if the connection is not TCP or
17672 if the operating system does not support TCP_INFO, for example Linux kernels
17673 before 2.4, the sample fetch fails.
17674
Christopher Fauletba0c53e2019-10-17 14:40:48 +020017675fc_sacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070017676 Returns the sacked counter measured by the kernel for the client connection.
17677 If the server connection is not established, if the connection is not TCP or
17678 if the operating system does not support TCP_INFO, for example Linux kernels
17679 before 2.4, the sample fetch fails.
17680
Christopher Fauletba0c53e2019-10-17 14:40:48 +020017681fc_retrans : integer
Joe Williams30fcd392016-08-10 07:06:44 -070017682 Returns the retransmits counter measured by the kernel for the client
17683 connection. If the server connection is not established, if the connection is
17684 not TCP or if the operating system does not support TCP_INFO, for example
17685 Linux kernels before 2.4, the sample fetch fails.
17686
Christopher Fauletba0c53e2019-10-17 14:40:48 +020017687fc_fackets : integer
Joe Williams30fcd392016-08-10 07:06:44 -070017688 Returns the fack counter measured by the kernel for the client
17689 connection. If the server connection is not established, if the connection is
17690 not TCP or if the operating system does not support TCP_INFO, for example
17691 Linux kernels before 2.4, the sample fetch fails.
17692
Christopher Fauletba0c53e2019-10-17 14:40:48 +020017693fc_lost : integer
Joe Williams30fcd392016-08-10 07:06:44 -070017694 Returns the lost counter measured by the kernel for the client
17695 connection. If the server connection is not established, if the connection is
17696 not TCP or if the operating system does not support TCP_INFO, for example
17697 Linux kernels before 2.4, the sample fetch fails.
17698
Christopher Fauletba0c53e2019-10-17 14:40:48 +020017699fc_reordering : integer
Joe Williams30fcd392016-08-10 07:06:44 -070017700 Returns the reordering counter measured by the kernel for the client
17701 connection. If the server connection is not established, if the connection is
17702 not TCP or if the operating system does not support TCP_INFO, for example
17703 Linux kernels before 2.4, the sample fetch fails.
17704
Marcin Deranek9a66dfb2018-04-13 14:37:50 +020017705fe_defbe : string
17706 Returns a string containing the frontend's default backend name. It can be
17707 used in frontends to check which backend will handle requests by default.
17708
Willy Tarreau74ca5042013-06-11 23:12:07 +020017709fe_id : integer
17710 Returns an integer containing the current frontend's id. It can be used in
Marcin Deranek6e413ed2016-12-13 12:40:01 +010017711 backends to check from which frontend it was called, or to stick all users
Willy Tarreau74ca5042013-06-11 23:12:07 +020017712 coming via a same frontend to the same server.
17713
Marcin Deranekd2471c22016-12-12 14:08:05 +010017714fe_name : string
17715 Returns a string containing the current frontend's name. It can be used in
17716 backends to check from which frontend it was called, or to stick all users
17717 coming via a same frontend to the same server.
17718
Amaury Denoyelleda184d52020-12-10 13:43:55 +010017719fe_client_timeout : integer
17720 Returns the configuration value in millisecond for the client timeout of the
17721 current frontend.
17722
Cyril Bonté62ba8702014-04-22 23:52:25 +020017723sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017724sc0_bytes_in_rate([<table>]) : integer
17725sc1_bytes_in_rate([<table>]) : integer
17726sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017727 Returns the average client-to-server bytes rate from the currently tracked
17728 counters, measured in amount of bytes over the period configured in the
17729 table. See also src_bytes_in_rate.
17730
Cyril Bonté62ba8702014-04-22 23:52:25 +020017731sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017732sc0_bytes_out_rate([<table>]) : integer
17733sc1_bytes_out_rate([<table>]) : integer
17734sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017735 Returns the average server-to-client bytes rate from the currently tracked
17736 counters, measured in amount of bytes over the period configured in the
17737 table. See also src_bytes_out_rate.
17738
Cyril Bonté62ba8702014-04-22 23:52:25 +020017739sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017740sc0_clr_gpc0([<table>]) : integer
17741sc1_clr_gpc0([<table>]) : integer
17742sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020017743 Clears the first General Purpose Counter associated to the currently tracked
17744 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010017745 stored value is zero, so first invocation will always return zero. This is
17746 typically used as a second ACL in an expression in order to mark a connection
17747 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020017748
Jarno Huuskonen676f6222017-03-30 09:19:45 +030017749 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020017750 # block if 5 consecutive requests continue to come faster than 10 sess
17751 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020017752 acl abuse sc0_http_req_rate gt 10
17753 acl kill sc0_inc_gpc0 gt 5
17754 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020017755 tcp-request connection accept if !abuse save
17756 tcp-request connection reject if abuse kill
17757
Frédéric Lécaille6778b272018-01-29 15:22:53 +010017758sc_clr_gpc1(<ctr>[,<table>]) : integer
17759sc0_clr_gpc1([<table>]) : integer
17760sc1_clr_gpc1([<table>]) : integer
17761sc2_clr_gpc1([<table>]) : integer
17762 Clears the second General Purpose Counter associated to the currently tracked
17763 counters, and returns its previous value. Before the first invocation, the
17764 stored value is zero, so first invocation will always return zero. This is
17765 typically used as a second ACL in an expression in order to mark a connection
17766 when a first ACL was verified.
17767
Cyril Bonté62ba8702014-04-22 23:52:25 +020017768sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017769sc0_conn_cnt([<table>]) : integer
17770sc1_conn_cnt([<table>]) : integer
17771sc2_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010017772 Returns the cumulative number of incoming connections from currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020017773 counters. See also src_conn_cnt.
17774
Cyril Bonté62ba8702014-04-22 23:52:25 +020017775sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017776sc0_conn_cur([<table>]) : integer
17777sc1_conn_cur([<table>]) : integer
17778sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017779 Returns the current amount of concurrent connections tracking the same
17780 tracked counters. This number is automatically incremented when tracking
17781 begins and decremented when tracking stops. See also src_conn_cur.
17782
Cyril Bonté62ba8702014-04-22 23:52:25 +020017783sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017784sc0_conn_rate([<table>]) : integer
17785sc1_conn_rate([<table>]) : integer
17786sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017787 Returns the average connection rate from the currently tracked counters,
17788 measured in amount of connections over the period configured in the table.
17789 See also src_conn_rate.
17790
Cyril Bonté62ba8702014-04-22 23:52:25 +020017791sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017792sc0_get_gpc0([<table>]) : integer
17793sc1_get_gpc0([<table>]) : integer
17794sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017795 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020017796 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020017797
Frédéric Lécaille6778b272018-01-29 15:22:53 +010017798sc_get_gpc1(<ctr>[,<table>]) : integer
17799sc0_get_gpc1([<table>]) : integer
17800sc1_get_gpc1([<table>]) : integer
17801sc2_get_gpc1([<table>]) : integer
17802 Returns the value of the second General Purpose Counter associated to the
17803 currently tracked counters. See also src_get_gpc1 and sc/sc0/sc1/sc2_inc_gpc1.
17804
Thierry FOURNIER236657b2015-08-19 08:25:14 +020017805sc_get_gpt0(<ctr>[,<table>]) : integer
17806sc0_get_gpt0([<table>]) : integer
17807sc1_get_gpt0([<table>]) : integer
17808sc2_get_gpt0([<table>]) : integer
17809 Returns the value of the first General Purpose Tag associated to the
17810 currently tracked counters. See also src_get_gpt0.
17811
Cyril Bonté62ba8702014-04-22 23:52:25 +020017812sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017813sc0_gpc0_rate([<table>]) : integer
17814sc1_gpc0_rate([<table>]) : integer
17815sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020017816 Returns the average increment rate of the first General Purpose Counter
17817 associated to the currently tracked counters. It reports the frequency
17818 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020017819 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
17820 that the "gpc0_rate" counter must be stored in the stick-table for a value to
17821 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020017822
Frédéric Lécaille6778b272018-01-29 15:22:53 +010017823sc_gpc1_rate(<ctr>[,<table>]) : integer
17824sc0_gpc1_rate([<table>]) : integer
17825sc1_gpc1_rate([<table>]) : integer
17826sc2_gpc1_rate([<table>]) : integer
17827 Returns the average increment rate of the second General Purpose Counter
17828 associated to the currently tracked counters. It reports the frequency
17829 which the gpc1 counter was incremented over the configured period. See also
17830 src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
17831 that the "gpc1_rate" counter must be stored in the stick-table for a value to
17832 be returned, as "gpc1" only holds the event count.
17833
Cyril Bonté62ba8702014-04-22 23:52:25 +020017834sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017835sc0_http_err_cnt([<table>]) : integer
17836sc1_http_err_cnt([<table>]) : integer
17837sc2_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010017838 Returns the cumulative number of HTTP errors from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020017839 counters. This includes the both request errors and 4xx error responses.
17840 See also src_http_err_cnt.
17841
Cyril Bonté62ba8702014-04-22 23:52:25 +020017842sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017843sc0_http_err_rate([<table>]) : integer
17844sc1_http_err_rate([<table>]) : integer
17845sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017846 Returns the average rate of HTTP errors from the currently tracked counters,
17847 measured in amount of errors over the period configured in the table. This
17848 includes the both request errors and 4xx error responses. See also
17849 src_http_err_rate.
17850
Willy Tarreau826f3ab2021-02-10 12:07:15 +010017851sc_http_fail_cnt(<ctr>[,<table>]) : integer
17852sc0_http_fail_cnt([<table>]) : integer
17853sc1_http_fail_cnt([<table>]) : integer
17854sc2_http_fail_cnt([<table>]) : integer
17855 Returns the cumulative number of HTTP response failures from the currently
17856 tracked counters. This includes the both response errors and 5xx status codes
17857 other than 501 and 505. See also src_http_fail_cnt.
17858
17859sc_http_fail_rate(<ctr>[,<table>]) : integer
17860sc0_http_fail_rate([<table>]) : integer
17861sc1_http_fail_rate([<table>]) : integer
17862sc2_http_fail_rate([<table>]) : integer
17863 Returns the average rate of HTTP response failures from the currently tracked
17864 counters, measured in amount of failures over the period configured in the
17865 table. This includes the both response errors and 5xx status codes other than
17866 501 and 505. See also src_http_fail_rate.
17867
Cyril Bonté62ba8702014-04-22 23:52:25 +020017868sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017869sc0_http_req_cnt([<table>]) : integer
17870sc1_http_req_cnt([<table>]) : integer
17871sc2_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010017872 Returns the cumulative number of HTTP requests from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020017873 counters. This includes every started request, valid or not. See also
17874 src_http_req_cnt.
17875
Cyril Bonté62ba8702014-04-22 23:52:25 +020017876sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017877sc0_http_req_rate([<table>]) : integer
17878sc1_http_req_rate([<table>]) : integer
17879sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017880 Returns the average rate of HTTP requests from the currently tracked
17881 counters, measured in amount of requests over the period configured in
17882 the table. This includes every started request, valid or not. See also
17883 src_http_req_rate.
17884
Cyril Bonté62ba8702014-04-22 23:52:25 +020017885sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017886sc0_inc_gpc0([<table>]) : integer
17887sc1_inc_gpc0([<table>]) : integer
17888sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017889 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010017890 tracked counters, and returns its new value. Before the first invocation,
17891 the stored value is zero, so first invocation will increase it to 1 and will
17892 return 1. This is typically used as a second ACL in an expression in order
17893 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020017894
Jarno Huuskonen676f6222017-03-30 09:19:45 +030017895 Example:
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020017896 acl abuse sc0_http_req_rate gt 10
17897 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020017898 tcp-request connection reject if abuse kill
17899
Frédéric Lécaille6778b272018-01-29 15:22:53 +010017900sc_inc_gpc1(<ctr>[,<table>]) : integer
17901sc0_inc_gpc1([<table>]) : integer
17902sc1_inc_gpc1([<table>]) : integer
17903sc2_inc_gpc1([<table>]) : integer
17904 Increments the second General Purpose Counter associated to the currently
17905 tracked counters, and returns its new value. Before the first invocation,
17906 the stored value is zero, so first invocation will increase it to 1 and will
17907 return 1. This is typically used as a second ACL in an expression in order
17908 to mark a connection when a first ACL was verified.
17909
Cyril Bonté62ba8702014-04-22 23:52:25 +020017910sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017911sc0_kbytes_in([<table>]) : integer
17912sc1_kbytes_in([<table>]) : integer
17913sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020017914 Returns the total amount of client-to-server data from the currently tracked
17915 counters, measured in kilobytes. The test is currently performed on 32-bit
17916 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020017917
Cyril Bonté62ba8702014-04-22 23:52:25 +020017918sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017919sc0_kbytes_out([<table>]) : integer
17920sc1_kbytes_out([<table>]) : integer
17921sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020017922 Returns the total amount of server-to-client data from the currently tracked
17923 counters, measured in kilobytes. The test is currently performed on 32-bit
17924 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020017925
Cyril Bonté62ba8702014-04-22 23:52:25 +020017926sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017927sc0_sess_cnt([<table>]) : integer
17928sc1_sess_cnt([<table>]) : integer
17929sc2_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010017930 Returns the cumulative number of incoming connections that were transformed
Willy Tarreaue9656522010-08-17 15:40:09 +020017931 into sessions, which means that they were accepted by a "tcp-request
17932 connection" rule, from the currently tracked counters. A backend may count
17933 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017934 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020017935 with the client. See also src_sess_cnt.
17936
Cyril Bonté62ba8702014-04-22 23:52:25 +020017937sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017938sc0_sess_rate([<table>]) : integer
17939sc1_sess_rate([<table>]) : integer
17940sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020017941 Returns the average session rate from the currently tracked counters,
17942 measured in amount of sessions over the period configured in the table. A
17943 session is a connection that got past the early "tcp-request connection"
17944 rules. A backend may count more sessions than connections because each
17945 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017946 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020017947
Cyril Bonté62ba8702014-04-22 23:52:25 +020017948sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020017949sc0_tracked([<table>]) : boolean
17950sc1_tracked([<table>]) : boolean
17951sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020017952 Returns true if the designated session counter is currently being tracked by
17953 the current session. This can be useful when deciding whether or not we want
17954 to set some values in a header passed to the server.
17955
Cyril Bonté62ba8702014-04-22 23:52:25 +020017956sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020017957sc0_trackers([<table>]) : integer
17958sc1_trackers([<table>]) : integer
17959sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010017960 Returns the current amount of concurrent connections tracking the same
17961 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020017962 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010017963 that it does not rely on any stored information but on the table's reference
17964 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020017965 may sometimes be more suited for layer7 tracking. It can be used to tell a
17966 server how many concurrent connections there are from a given address for
17967 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010017968
Willy Tarreau74ca5042013-06-11 23:12:07 +020017969so_id : integer
17970 Returns an integer containing the current listening socket's id. It is useful
17971 in frontends involving many "bind" lines, or to stick all users coming via a
17972 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017973
Jerome Magnineb421b22020-03-27 22:08:40 +010017974so_name : string
17975 Returns a string containing the current listening socket's name, as defined
17976 with name on a "bind" line. It can serve the same purposes as so_id but with
17977 strings instead of integers.
17978
Willy Tarreau74ca5042013-06-11 23:12:07 +020017979src : ip
Davor Ocelice9ed2812017-12-25 17:49:28 +010017980 This is the source IPv4 address of the client of the session. It is of type
Willy Tarreau74ca5042013-06-11 23:12:07 +020017981 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
17982 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
17983 TCP-level source address which is used, and not the address of a client
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010017984 behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind
17985 directive is used, it can be the address of a client behind another
17986 PROXY-protocol compatible component for all rule sets except
Willy Tarreau64ded3d2019-01-23 10:02:15 +010017987 "tcp-request connection" which sees the real address. When the incoming
17988 connection passed through address translation or redirection involving
17989 connection tracking, the original destination address before the redirection
17990 will be reported. On Linux systems, the source and destination may seldom
17991 appear reversed if the nf_conntrack_tcp_loose sysctl is set, because a late
17992 response may reopen a timed out connection and switch what is believed to be
17993 the source and the destination.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017994
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010017995 Example:
17996 # add an HTTP header in requests with the originating address' country
17997 http-request set-header X-Country %[src,map_ip(geoip.lst)]
17998
Willy Tarreau74ca5042013-06-11 23:12:07 +020017999src_bytes_in_rate([<table>]) : integer
18000 Returns the average bytes rate from the incoming connection's source address
18001 in the current proxy's stick-table or in the designated stick-table, measured
18002 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018003 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018004
Willy Tarreau74ca5042013-06-11 23:12:07 +020018005src_bytes_out_rate([<table>]) : integer
18006 Returns the average bytes rate to the incoming connection's source address in
18007 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020018008 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018009 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018010
Willy Tarreau74ca5042013-06-11 23:12:07 +020018011src_clr_gpc0([<table>]) : integer
18012 Clears the first General Purpose Counter associated to the incoming
18013 connection's source address in the current proxy's stick-table or in the
18014 designated stick-table, and returns its previous value. If the address is not
18015 found, an entry is created and 0 is returned. This is typically used as a
18016 second ACL in an expression in order to mark a connection when a first ACL
18017 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020018018
Jarno Huuskonen676f6222017-03-30 09:19:45 +030018019 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020018020 # block if 5 consecutive requests continue to come faster than 10 sess
18021 # per second, and reset the counter as soon as the traffic slows down.
18022 acl abuse src_http_req_rate gt 10
18023 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010018024 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020018025 tcp-request connection accept if !abuse save
18026 tcp-request connection reject if abuse kill
18027
Frédéric Lécaille6778b272018-01-29 15:22:53 +010018028src_clr_gpc1([<table>]) : integer
18029 Clears the second General Purpose Counter associated to the incoming
18030 connection's source address in the current proxy's stick-table or in the
18031 designated stick-table, and returns its previous value. If the address is not
18032 found, an entry is created and 0 is returned. This is typically used as a
18033 second ACL in an expression in order to mark a connection when a first ACL
18034 was verified.
18035
Willy Tarreau74ca5042013-06-11 23:12:07 +020018036src_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010018037 Returns the cumulative number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020018038 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020018039 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018040 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018041
Willy Tarreau74ca5042013-06-11 23:12:07 +020018042src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020018043 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020018044 current incoming connection's source address in the current proxy's
18045 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018046 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018047
Willy Tarreau74ca5042013-06-11 23:12:07 +020018048src_conn_rate([<table>]) : integer
18049 Returns the average connection rate from the incoming connection's source
18050 address in the current proxy's stick-table or in the designated stick-table,
18051 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018052 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018053
Willy Tarreau74ca5042013-06-11 23:12:07 +020018054src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020018055 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020018056 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020018057 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018058 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018059
Frédéric Lécaille6778b272018-01-29 15:22:53 +010018060src_get_gpc1([<table>]) : integer
18061 Returns the value of the second General Purpose Counter associated to the
18062 incoming connection's source address in the current proxy's stick-table or in
18063 the designated stick-table. If the address is not found, zero is returned.
18064 See also sc/sc0/sc1/sc2_get_gpc1 and src_inc_gpc1.
18065
Thierry FOURNIER236657b2015-08-19 08:25:14 +020018066src_get_gpt0([<table>]) : integer
18067 Returns the value of the first General Purpose Tag associated to the
18068 incoming connection's source address in the current proxy's stick-table or in
18069 the designated stick-table. If the address is not found, zero is returned.
18070 See also sc/sc0/sc1/sc2_get_gpt0.
18071
Willy Tarreau74ca5042013-06-11 23:12:07 +020018072src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020018073 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020018074 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020018075 stick-table or in the designated stick-table. It reports the frequency
18076 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018077 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
18078 that the "gpc0_rate" counter must be stored in the stick-table for a value to
18079 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020018080
Frédéric Lécaille6778b272018-01-29 15:22:53 +010018081src_gpc1_rate([<table>]) : integer
18082 Returns the average increment rate of the second General Purpose Counter
18083 associated to the incoming connection's source address in the current proxy's
18084 stick-table or in the designated stick-table. It reports the frequency
18085 which the gpc1 counter was incremented over the configured period. See also
18086 sc/sc0/sc1/sc2_gpc1_rate, src_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
18087 that the "gpc1_rate" counter must be stored in the stick-table for a value to
18088 be returned, as "gpc1" only holds the event count.
18089
Willy Tarreau74ca5042013-06-11 23:12:07 +020018090src_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010018091 Returns the cumulative number of HTTP errors from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020018092 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020018093 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018094 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020018095 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018096
Willy Tarreau74ca5042013-06-11 23:12:07 +020018097src_http_err_rate([<table>]) : integer
18098 Returns the average rate of HTTP errors from the incoming connection's source
18099 address in the current proxy's stick-table or in the designated stick-table,
18100 measured in amount of errors over the period configured in the table. This
18101 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018102 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018103
Willy Tarreau826f3ab2021-02-10 12:07:15 +010018104src_http_fail_cnt([<table>]) : integer
18105 Returns the cumulative number of HTTP response failures triggered by the
18106 incoming connection's source address in the current proxy's stick-table or in
Ilya Shipitsin0de36ad2021-02-20 00:23:36 +050018107 the designated stick-table. This includes the both response errors and 5xx
Willy Tarreau826f3ab2021-02-10 12:07:15 +010018108 status codes other than 501 and 505. See also sc/sc0/sc1/sc2_http_fail_cnt.
18109 If the address is not found, zero is returned.
18110
18111src_http_fail_rate([<table>]) : integer
18112 Returns the average rate of HTTP response failures triggered by the incoming
18113 connection's source address in the current proxy's stick-table or in the
18114 designated stick-table, measured in amount of failures over the period
18115 configured in the table. This includes the both response errors and 5xx
18116 status codes other than 501 and 505. If the address is not found, zero is
18117 returned. See also sc/sc0/sc1/sc2_http_fail_rate.
18118
Willy Tarreau74ca5042013-06-11 23:12:07 +020018119src_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010018120 Returns the cumulative number of HTTP requests from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020018121 source address in the current proxy's stick-table or in the designated stick-
18122 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018123 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018124
Willy Tarreau74ca5042013-06-11 23:12:07 +020018125src_http_req_rate([<table>]) : integer
18126 Returns the average rate of HTTP requests from the incoming connection's
18127 source address in the current proxy's stick-table or in the designated stick-
18128 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020018129 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018130 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018131
Willy Tarreau74ca5042013-06-11 23:12:07 +020018132src_inc_gpc0([<table>]) : integer
18133 Increments the first General Purpose Counter associated to the incoming
18134 connection's source address in the current proxy's stick-table or in the
18135 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020018136 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020018137 This is typically used as a second ACL in an expression in order to mark a
18138 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020018139
Jarno Huuskonen676f6222017-03-30 09:19:45 +030018140 Example:
Willy Tarreauc9705a12010-07-27 20:05:50 +020018141 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010018142 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020018143 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020018144
Frédéric Lécaille6778b272018-01-29 15:22:53 +010018145src_inc_gpc1([<table>]) : integer
18146 Increments the second General Purpose Counter associated to the incoming
18147 connection's source address in the current proxy's stick-table or in the
18148 designated stick-table, and returns its new value. If the address is not
18149 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc1.
18150 This is typically used as a second ACL in an expression in order to mark a
18151 connection when a first ACL was verified.
18152
Willy Tarreau16e01562016-08-09 16:46:18 +020018153src_is_local : boolean
18154 Returns true if the source address of the incoming connection is local to the
18155 system, or false if the address doesn't exist on the system, meaning that it
18156 comes from a remote machine. Note that UNIX addresses are considered local.
18157 It can be useful to apply certain access restrictions based on where the
Davor Ocelice9ed2812017-12-25 17:49:28 +010018158 client comes from (e.g. require auth or https for remote machines). Please
Willy Tarreau16e01562016-08-09 16:46:18 +020018159 note that the check involves a few system calls, so it's better to do it only
18160 once per connection.
18161
Willy Tarreau74ca5042013-06-11 23:12:07 +020018162src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020018163 Returns the total amount of data received from the incoming connection's
18164 source address in the current proxy's stick-table or in the designated
18165 stick-table, measured in kilobytes. If the address is not found, zero is
18166 returned. The test is currently performed on 32-bit integers, which limits
18167 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018168
Willy Tarreau74ca5042013-06-11 23:12:07 +020018169src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020018170 Returns the total amount of data sent to the incoming connection's source
18171 address in the current proxy's stick-table or in the designated stick-table,
18172 measured in kilobytes. If the address is not found, zero is returned. The
18173 test is currently performed on 32-bit integers, which limits values to 4
18174 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020018175
Willy Tarreau74ca5042013-06-11 23:12:07 +020018176src_port : integer
18177 Returns an integer value corresponding to the TCP source port of the
18178 connection on the client side, which is the port the client connected from.
18179 Usage of this function is very limited as modern protocols do not care much
18180 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010018181
Willy Tarreau74ca5042013-06-11 23:12:07 +020018182src_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010018183 Returns the cumulative number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020018184 connection's source IPv4 address in the current proxy's stick-table or in the
18185 designated stick-table, that were transformed into sessions, which means that
18186 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018187 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018188
Willy Tarreau74ca5042013-06-11 23:12:07 +020018189src_sess_rate([<table>]) : integer
18190 Returns the average session rate from the incoming connection's source
18191 address in the current proxy's stick-table or in the designated stick-table,
18192 measured in amount of sessions over the period configured in the table. A
18193 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020018194 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020018195
Willy Tarreau74ca5042013-06-11 23:12:07 +020018196src_updt_conn_cnt([<table>]) : integer
18197 Creates or updates the entry associated to the incoming connection's source
18198 address in the current proxy's stick-table or in the designated stick-table.
18199 This table must be configured to store the "conn_cnt" data type, otherwise
18200 the match will be ignored. The current count is incremented by one, and the
18201 expiration timer refreshed. The updated count is returned, so this match
18202 can't return zero. This was used to reject service abusers based on their
18203 source address. Note: it is recommended to use the more complete "track-sc*"
18204 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020018205
18206 Example :
18207 # This frontend limits incoming SSH connections to 3 per 10 second for
18208 # each source address, and rejects excess connections until a 10 second
18209 # silence is observed. At most 20 addresses are tracked.
18210 listen ssh
18211 bind :22
18212 mode tcp
18213 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020018214 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020018215 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020018216 server local 127.0.0.1:22
18217
Willy Tarreau74ca5042013-06-11 23:12:07 +020018218srv_id : integer
18219 Returns an integer containing the server's id when processing the response.
18220 While it's almost only used with ACLs, it may be used for logging or
Christopher Fauletd1b44642020-04-30 09:51:15 +020018221 debugging. It can also be used in a tcp-check or an http-check ruleset.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020018222
vkill1dfd1652019-10-30 16:58:14 +080018223srv_name : string
18224 Returns a string containing the server's name when processing the response.
18225 While it's almost only used with ACLs, it may be used for logging or
Christopher Fauletd1b44642020-04-30 09:51:15 +020018226 debugging. It can also be used in a tcp-check or an http-check ruleset.
vkill1dfd1652019-10-30 16:58:14 +080018227
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200182287.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020018229----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020018230
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018231The layer 5 usually describes just the session layer which in HAProxy is
Willy Tarreau74ca5042013-06-11 23:12:07 +020018232closest to the session once all the connection handshakes are finished, but
18233when no content is yet made available. The fetch methods described here are
18234usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030018235future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020018236
Ben Shillitof25e8e52016-12-02 14:25:37 +00001823751d.all(<prop>[,<prop>*]) : string
18238 Returns values for the properties requested as a string, where values are
18239 separated by the delimiter specified with "51degrees-property-separator".
18240 The device is identified using all the important HTTP headers from the
18241 request. The function can be passed up to five property names, and if a
18242 property name can't be found, the value "NoData" is returned.
18243
18244 Example :
18245 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
18246 # containing the three properties requested using all relevant headers from
18247 # the request.
18248 frontend http-in
18249 bind *:8081
18250 default_backend servers
18251 http-request set-header X-51D-DeviceTypeMobileTablet \
18252 %[51d.all(DeviceType,IsMobile,IsTablet)]
18253
Emeric Brun645ae792014-04-30 14:21:06 +020018254ssl_bc : boolean
18255 Returns true when the back connection was made via an SSL/TLS transport
18256 layer and is locally deciphered. This means the outgoing connection was made
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018257 other a server with the "ssl" option. It can be used in a tcp-check or an
18258 http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018259
18260ssl_bc_alg_keysize : integer
18261 Returns the symmetric cipher key size supported in bits when the outgoing
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018262 connection was made over an SSL/TLS transport layer. It can be used in a
18263 tcp-check or an http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018264
Olivier Houchard6b77f492018-11-22 18:18:29 +010018265ssl_bc_alpn : string
18266 This extracts the Application Layer Protocol Negotiation field from an
18267 outgoing connection made via a TLS transport layer.
Michael Prokop4438c602019-05-24 10:25:45 +020018268 The result is a string containing the protocol name negotiated with the
Olivier Houchard6b77f492018-11-22 18:18:29 +010018269 server. The SSL library must have been built with support for TLS
18270 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
18271 not advertised unless the "alpn" keyword on the "server" line specifies a
18272 protocol list. Also, nothing forces the server to pick a protocol from this
18273 list, any other one may be requested. The TLS ALPN extension is meant to
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018274 replace the TLS NPN extension. See also "ssl_bc_npn". It can be used in a
18275 tcp-check or an http-check ruleset.
Olivier Houchard6b77f492018-11-22 18:18:29 +010018276
Emeric Brun645ae792014-04-30 14:21:06 +020018277ssl_bc_cipher : string
18278 Returns the name of the used cipher when the outgoing connection was made
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018279 over an SSL/TLS transport layer. It can be used in a tcp-check or an
18280 http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018281
Patrick Hemmer65674662019-06-04 08:13:03 -040018282ssl_bc_client_random : binary
18283 Returns the client random of the back connection when the incoming connection
18284 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
18285 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018286 It can be used in a tcp-check or an http-check ruleset.
Patrick Hemmer65674662019-06-04 08:13:03 -040018287
Emeric Brun74f7ffa2018-02-19 16:14:12 +010018288ssl_bc_is_resumed : boolean
18289 Returns true when the back connection was made over an SSL/TLS transport
18290 layer and the newly created SSL session was resumed using a cached
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018291 session or a TLS ticket. It can be used in a tcp-check or an http-check
18292 ruleset.
Emeric Brun74f7ffa2018-02-19 16:14:12 +010018293
Olivier Houchard6b77f492018-11-22 18:18:29 +010018294ssl_bc_npn : string
18295 This extracts the Next Protocol Negotiation field from an outgoing connection
18296 made via a TLS transport layer. The result is a string containing the
Michael Prokop4438c602019-05-24 10:25:45 +020018297 protocol name negotiated with the server . The SSL library must have been
Olivier Houchard6b77f492018-11-22 18:18:29 +010018298 built with support for TLS extensions enabled (check haproxy -vv). Note that
18299 the TLS NPN extension is not advertised unless the "npn" keyword on the
18300 "server" line specifies a protocol list. Also, nothing forces the server to
18301 pick a protocol from this list, any other one may be used. Please note that
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018302 the TLS NPN extension was replaced with ALPN. It can be used in a tcp-check
18303 or an http-check ruleset.
Olivier Houchard6b77f492018-11-22 18:18:29 +010018304
Emeric Brun645ae792014-04-30 14:21:06 +020018305ssl_bc_protocol : string
18306 Returns the name of the used protocol when the outgoing connection was made
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018307 over an SSL/TLS transport layer. It can be used in a tcp-check or an
18308 http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018309
Emeric Brunb73a9b02014-04-30 18:49:19 +020018310ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020018311 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020018312 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018313 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64". It
18314 can be used in a tcp-check or an http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018315
Patrick Hemmer65674662019-06-04 08:13:03 -040018316ssl_bc_server_random : binary
18317 Returns the server random of the back connection when the incoming connection
18318 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
18319 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018320 It can be used in a tcp-check or an http-check ruleset.
Patrick Hemmer65674662019-06-04 08:13:03 -040018321
Emeric Brun645ae792014-04-30 14:21:06 +020018322ssl_bc_session_id : binary
18323 Returns the SSL ID of the back connection when the outgoing connection was
18324 made over an SSL/TLS transport layer. It is useful to log if we want to know
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018325 if session was reused or not. It can be used in a tcp-check or an http-check
18326 ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018327
Patrick Hemmere0275472018-04-28 19:15:51 -040018328ssl_bc_session_key : binary
18329 Returns the SSL session master key of the back connection when the outgoing
18330 connection was made over an SSL/TLS transport layer. It is useful to decrypt
18331 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018332 BoringSSL. It can be used in a tcp-check or an http-check ruleset.
Patrick Hemmere0275472018-04-28 19:15:51 -040018333
Emeric Brun645ae792014-04-30 14:21:06 +020018334ssl_bc_use_keysize : integer
18335 Returns the symmetric cipher key size used in bits when the outgoing
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020018336 connection was made over an SSL/TLS transport layer. It can be used in a
18337 tcp-check or an http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020018338
Willy Tarreau74ca5042013-06-11 23:12:07 +020018339ssl_c_ca_err : integer
18340 When the incoming connection was made over an SSL/TLS transport layer,
18341 returns the ID of the first error detected during verification of the client
18342 certificate at depth > 0, or 0 if no error was encountered during this
18343 verification process. Please refer to your SSL library's documentation to
18344 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020018345
Willy Tarreau74ca5042013-06-11 23:12:07 +020018346ssl_c_ca_err_depth : integer
18347 When the incoming connection was made over an SSL/TLS transport layer,
18348 returns the depth in the CA chain of the first error detected during the
18349 verification of the client certificate. If no error is encountered, 0 is
18350 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010018351
Christopher Faulet70d10d12020-11-06 12:10:33 +010018352ssl_c_chain_der : binary
William Dauchya598b502020-08-06 18:11:38 +020018353 Returns the DER formatted chain certificate presented by the client when the
18354 incoming connection was made over an SSL/TLS transport layer. When used for
18355 an ACL, the value(s) to match against can be passed in hexadecimal form. One
Ilya Shipitsin2272d8a2020-12-21 01:22:40 +050018356 can parse the result with any lib accepting ASN.1 DER data. It currently
William Dauchya598b502020-08-06 18:11:38 +020018357 does not support resumed sessions.
18358
Christopher Faulet70d10d12020-11-06 12:10:33 +010018359ssl_c_der : binary
18360 Returns the DER formatted certificate presented by the client when the
18361 incoming connection was made over an SSL/TLS transport layer. When used for
18362 an ACL, the value(s) to match against can be passed in hexadecimal form.
18363
Willy Tarreau74ca5042013-06-11 23:12:07 +020018364ssl_c_err : integer
18365 When the incoming connection was made over an SSL/TLS transport layer,
18366 returns the ID of the first error detected during verification at depth 0, or
18367 0 if no error was encountered during this verification process. Please refer
18368 to your SSL library's documentation to find the exhaustive list of error
18369 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020018370
Elliot Otchet71f82972020-01-15 08:12:14 -050018371ssl_c_i_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020018372 When the incoming connection was made over an SSL/TLS transport layer,
18373 returns the full distinguished name of the issuer of the certificate
18374 presented by the client when no <entry> is specified, or the value of the
18375 first given entry found from the beginning of the DN. If a positive/negative
18376 occurrence number is specified as the optional second argument, it returns
18377 the value of the nth given entry value from the beginning/end of the DN.
18378 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
18379 "ssl_c_i_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050018380 The <format> parameter allows you to receive the DN suitable for
18381 consumption by different protocols. Currently supported is rfc2253 for
18382 LDAP v3.
18383 If you'd like to modify the format only you can specify an empty string
18384 and zero for the first two parameters. Example: ssl_c_i_dn(,0,rfc2253)
Willy Tarreau62644772008-07-16 18:36:06 +020018385
Willy Tarreau74ca5042013-06-11 23:12:07 +020018386ssl_c_key_alg : string
18387 Returns the name of the algorithm used to generate the key of the certificate
18388 presented by the client when the incoming connection was made over an SSL/TLS
18389 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020018390
Willy Tarreau74ca5042013-06-11 23:12:07 +020018391ssl_c_notafter : string
18392 Returns the end date presented by the client as a formatted string
18393 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
18394 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020018395
Willy Tarreau74ca5042013-06-11 23:12:07 +020018396ssl_c_notbefore : string
18397 Returns the start date presented by the client as a formatted string
18398 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
18399 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010018400
Elliot Otchet71f82972020-01-15 08:12:14 -050018401ssl_c_s_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020018402 When the incoming connection was made over an SSL/TLS transport layer,
18403 returns the full distinguished name of the subject of the certificate
18404 presented by the client when no <entry> is specified, or the value of the
18405 first given entry found from the beginning of the DN. If a positive/negative
18406 occurrence number is specified as the optional second argument, it returns
18407 the value of the nth given entry value from the beginning/end of the DN.
18408 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
18409 "ssl_c_s_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050018410 The <format> parameter allows you to receive the DN suitable for
18411 consumption by different protocols. Currently supported is rfc2253 for
18412 LDAP v3.
18413 If you'd like to modify the format only you can specify an empty string
18414 and zero for the first two parameters. Example: ssl_c_s_dn(,0,rfc2253)
Willy Tarreaub6672b52011-12-12 17:23:41 +010018415
Willy Tarreau74ca5042013-06-11 23:12:07 +020018416ssl_c_serial : binary
18417 Returns the serial of the certificate presented by the client when the
18418 incoming connection was made over an SSL/TLS transport layer. When used for
18419 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020018420
Willy Tarreau74ca5042013-06-11 23:12:07 +020018421ssl_c_sha1 : binary
18422 Returns the SHA-1 fingerprint of the certificate presented by the client when
18423 the incoming connection was made over an SSL/TLS transport layer. This can be
18424 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020018425 Note that the output is binary, so if you want to pass that signature to the
18426 server, you need to encode it in hex or base64, such as in the example below:
18427
Jarno Huuskonen676f6222017-03-30 09:19:45 +030018428 Example:
Willy Tarreau2d0caa32014-07-02 19:01:22 +020018429 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020018430
Willy Tarreau74ca5042013-06-11 23:12:07 +020018431ssl_c_sig_alg : string
18432 Returns the name of the algorithm used to sign the certificate presented by
18433 the client when the incoming connection was made over an SSL/TLS transport
18434 layer.
Emeric Brun87855892012-10-17 17:39:35 +020018435
Willy Tarreau74ca5042013-06-11 23:12:07 +020018436ssl_c_used : boolean
18437 Returns true if current SSL session uses a client certificate even if current
18438 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020018439
Willy Tarreau74ca5042013-06-11 23:12:07 +020018440ssl_c_verify : integer
18441 Returns the verify result error ID when the incoming connection was made over
18442 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
18443 refer to your SSL library's documentation for an exhaustive list of error
18444 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020018445
Willy Tarreau74ca5042013-06-11 23:12:07 +020018446ssl_c_version : integer
18447 Returns the version of the certificate presented by the client when the
18448 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020018449
Emeric Brun43e79582014-10-29 19:03:26 +010018450ssl_f_der : binary
18451 Returns the DER formatted certificate presented by the frontend when the
18452 incoming connection was made over an SSL/TLS transport layer. When used for
18453 an ACL, the value(s) to match against can be passed in hexadecimal form.
18454
Elliot Otchet71f82972020-01-15 08:12:14 -050018455ssl_f_i_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020018456 When the incoming connection was made over an SSL/TLS transport layer,
18457 returns the full distinguished name of the issuer of the certificate
18458 presented by the frontend when no <entry> is specified, or the value of the
18459 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020018460 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020018461 the value of the nth given entry value from the beginning/end of the DN.
18462 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
18463 "ssl_f_i_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050018464 The <format> parameter allows you to receive the DN suitable for
18465 consumption by different protocols. Currently supported is rfc2253 for
18466 LDAP v3.
18467 If you'd like to modify the format only you can specify an empty string
18468 and zero for the first two parameters. Example: ssl_f_i_dn(,0,rfc2253)
Emeric Brun87855892012-10-17 17:39:35 +020018469
Willy Tarreau74ca5042013-06-11 23:12:07 +020018470ssl_f_key_alg : string
18471 Returns the name of the algorithm used to generate the key of the certificate
18472 presented by the frontend when the incoming connection was made over an
18473 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020018474
Willy Tarreau74ca5042013-06-11 23:12:07 +020018475ssl_f_notafter : string
18476 Returns the end date presented by the frontend as a formatted string
18477 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
18478 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020018479
Willy Tarreau74ca5042013-06-11 23:12:07 +020018480ssl_f_notbefore : string
18481 Returns the start date presented by the frontend as a formatted string
18482 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
18483 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020018484
Elliot Otchet71f82972020-01-15 08:12:14 -050018485ssl_f_s_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020018486 When the incoming connection was made over an SSL/TLS transport layer,
18487 returns the full distinguished name of the subject of the certificate
18488 presented by the frontend when no <entry> is specified, or the value of the
18489 first given entry found from the beginning of the DN. If a positive/negative
18490 occurrence number is specified as the optional second argument, it returns
18491 the value of the nth given entry value from the beginning/end of the DN.
18492 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
18493 "ssl_f_s_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050018494 The <format> parameter allows you to receive the DN suitable for
18495 consumption by different protocols. Currently supported is rfc2253 for
18496 LDAP v3.
18497 If you'd like to modify the format only you can specify an empty string
18498 and zero for the first two parameters. Example: ssl_f_s_dn(,0,rfc2253)
Emeric Brunce5ad802012-10-22 14:11:22 +020018499
Willy Tarreau74ca5042013-06-11 23:12:07 +020018500ssl_f_serial : binary
18501 Returns the serial of the certificate presented by the frontend when the
18502 incoming connection was made over an SSL/TLS transport layer. When used for
18503 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020018504
Emeric Brun55f4fa82014-04-30 17:11:25 +020018505ssl_f_sha1 : binary
18506 Returns the SHA-1 fingerprint of the certificate presented by the frontend
18507 when the incoming connection was made over an SSL/TLS transport layer. This
18508 can be used to know which certificate was chosen using SNI.
18509
Willy Tarreau74ca5042013-06-11 23:12:07 +020018510ssl_f_sig_alg : string
18511 Returns the name of the algorithm used to sign the certificate presented by
18512 the frontend when the incoming connection was made over an SSL/TLS transport
18513 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020018514
Willy Tarreau74ca5042013-06-11 23:12:07 +020018515ssl_f_version : integer
18516 Returns the version of the certificate presented by the frontend when the
18517 incoming connection was made over an SSL/TLS transport layer.
18518
18519ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020018520 Returns true when the front connection was made via an SSL/TLS transport
18521 layer and is locally deciphered. This means it has matched a socket declared
18522 with a "bind" line having the "ssl" option.
18523
Willy Tarreau74ca5042013-06-11 23:12:07 +020018524 Example :
18525 # This passes "X-Proto: https" to servers when client connects over SSL
18526 listen http-https
18527 bind :80
18528 bind :443 ssl crt /etc/haproxy.pem
18529 http-request add-header X-Proto https if { ssl_fc }
18530
18531ssl_fc_alg_keysize : integer
18532 Returns the symmetric cipher key size supported in bits when the incoming
18533 connection was made over an SSL/TLS transport layer.
18534
18535ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030018536 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020018537 incoming connection made via a TLS transport layer and locally deciphered by
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018538 HAProxy. The result is a string containing the protocol name advertised by
Willy Tarreau74ca5042013-06-11 23:12:07 +020018539 the client. The SSL library must have been built with support for TLS
18540 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
18541 not advertised unless the "alpn" keyword on the "bind" line specifies a
18542 protocol list. Also, nothing forces the client to pick a protocol from this
18543 list, any other one may be requested. The TLS ALPN extension is meant to
18544 replace the TLS NPN extension. See also "ssl_fc_npn".
18545
Willy Tarreau74ca5042013-06-11 23:12:07 +020018546ssl_fc_cipher : string
18547 Returns the name of the used cipher when the incoming connection was made
18548 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020018549
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010018550ssl_fc_cipherlist_bin : binary
18551 Returns the binary form of the client hello cipher list. The maximum returned
18552 value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010018553 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010018554
18555ssl_fc_cipherlist_hex : string
18556 Returns the binary form of the client hello cipher list encoded as
18557 hexadecimal. The maximum returned value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010018558 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010018559
18560ssl_fc_cipherlist_str : string
18561 Returns the decoded text form of the client hello cipher list. The maximum
18562 number of ciphers returned is according with the value of
18563 "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only
Davor Ocelice9ed2812017-12-25 17:49:28 +010018564 available with OpenSSL >= 1.0.2. If the function is not enabled, this
Emmanuel Hocdetddcde192017-09-01 17:32:08 +020018565 sample-fetch returns the hash like "ssl_fc_cipherlist_xxh".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010018566
18567ssl_fc_cipherlist_xxh : integer
18568 Returns a xxh64 of the cipher list. This hash can be return only is the value
18569 "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010018570 take in account all the data of the cipher list.
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010018571
Patrick Hemmer65674662019-06-04 08:13:03 -040018572ssl_fc_client_random : binary
18573 Returns the client random of the front connection when the incoming connection
18574 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
18575 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
18576
William Lallemand7d42ef52020-07-06 11:41:30 +020018577ssl_fc_client_early_traffic_secret : string
18578 Return the CLIENT_EARLY_TRAFFIC_SECRET as an hexadecimal string for the
18579 front connection when the incoming connection was made over a TLS 1.3
18580 transport layer.
18581 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18582 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18583 activated with "tune.ssl.keylog on" in the global section. See also
18584 "tune.ssl.keylog"
18585
18586ssl_fc_client_handshake_traffic_secret : string
18587 Return the CLIENT_HANDSHAKE_TRAFFIC_SECRET as an hexadecimal string for the
18588 front connection when the incoming connection was made over a TLS 1.3
18589 transport layer.
18590 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18591 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18592 activated with "tune.ssl.keylog on" in the global section. See also
18593 "tune.ssl.keylog"
18594
18595ssl_fc_client_traffic_secret_0 : string
18596 Return the CLIENT_TRAFFIC_SECRET_0 as an hexadecimal string for the
18597 front connection when the incoming connection was made over a TLS 1.3
18598 transport layer.
18599 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18600 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18601 activated with "tune.ssl.keylog on" in the global section. See also
18602 "tune.ssl.keylog"
18603
18604ssl_fc_exporter_secret : string
18605 Return the EXPORTER_SECRET as an hexadecimal string for the
18606 front connection when the incoming connection was made over a TLS 1.3
18607 transport layer.
18608 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18609 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18610 activated with "tune.ssl.keylog on" in the global section. See also
18611 "tune.ssl.keylog"
18612
18613ssl_fc_early_exporter_secret : string
18614 Return the EARLY_EXPORTER_SECRET as an hexadecimal string for the
18615 front connection when the incoming connection was made over an TLS 1.3
18616 transport layer.
18617 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18618 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18619 activated with "tune.ssl.keylog on" in the global section. See also
18620 "tune.ssl.keylog"
18621
Willy Tarreau74ca5042013-06-11 23:12:07 +020018622ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020018623 Returns true if a client certificate is present in an incoming connection over
18624 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010018625 Note: on SSL session resumption with Session ID or TLS ticket, client
18626 certificate is not present in the current connection but may be retrieved
18627 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
18628 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020018629
Olivier Houchardccaa7de2017-10-02 11:51:03 +020018630ssl_fc_has_early : boolean
18631 Returns true if early data were sent, and the handshake didn't happen yet. As
18632 it has security implications, it is useful to be able to refuse those, or
18633 wait until the handshake happened.
18634
Willy Tarreau74ca5042013-06-11 23:12:07 +020018635ssl_fc_has_sni : boolean
18636 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020018637 in an incoming connection was made over an SSL/TLS transport layer. Returns
18638 true when the incoming connection presents a TLS SNI field. This requires
John Roeslerfb2fce12019-07-10 15:45:51 -050018639 that the SSL library is built with support for TLS extensions enabled (check
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020018640 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020018641
Nenad Merdanovic1516fe32016-05-17 03:31:21 +020018642ssl_fc_is_resumed : boolean
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020018643 Returns true if the SSL/TLS session has been resumed through the use of
Jérôme Magnin4a326cb2018-01-15 14:01:17 +010018644 SSL session cache or TLS tickets on an incoming connection over an SSL/TLS
18645 transport layer.
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020018646
Willy Tarreau74ca5042013-06-11 23:12:07 +020018647ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030018648 This extracts the Next Protocol Negotiation field from an incoming connection
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018649 made via a TLS transport layer and locally deciphered by HAProxy. The result
Willy Tarreau74ca5042013-06-11 23:12:07 +020018650 is a string containing the protocol name advertised by the client. The SSL
18651 library must have been built with support for TLS extensions enabled (check
18652 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
18653 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
18654 forces the client to pick a protocol from this list, any other one may be
18655 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020018656
Willy Tarreau74ca5042013-06-11 23:12:07 +020018657ssl_fc_protocol : string
18658 Returns the name of the used protocol when the incoming connection was made
18659 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020018660
Emeric Brunb73a9b02014-04-30 18:49:19 +020018661ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040018662 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020018663 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
18664 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040018665
William Lallemand7d42ef52020-07-06 11:41:30 +020018666ssl_fc_server_handshake_traffic_secret : string
18667 Return the SERVER_HANDSHAKE_TRAFFIC_SECRET as an hexadecimal string for the
18668 front connection when the incoming connection was made over a TLS 1.3
18669 transport layer.
18670 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18671 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18672 activated with "tune.ssl.keylog on" in the global section. See also
18673 "tune.ssl.keylog"
18674
18675ssl_fc_server_traffic_secret_0 : string
18676 Return the SERVER_TRAFFIC_SECRET_0 as an hexadecimal string for the
18677 front connection when the incoming connection was made over an TLS 1.3
18678 transport layer.
18679 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
18680 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
18681 activated with "tune.ssl.keylog on" in the global section. See also
18682 "tune.ssl.keylog"
18683
Patrick Hemmer65674662019-06-04 08:13:03 -040018684ssl_fc_server_random : binary
18685 Returns the server random of the front connection when the incoming connection
18686 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
18687 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
18688
Willy Tarreau74ca5042013-06-11 23:12:07 +020018689ssl_fc_session_id : binary
18690 Returns the SSL ID of the front connection when the incoming connection was
18691 made over an SSL/TLS transport layer. It is useful to stick a given client to
18692 a server. It is important to note that some browsers refresh their session ID
18693 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020018694
Patrick Hemmere0275472018-04-28 19:15:51 -040018695ssl_fc_session_key : binary
18696 Returns the SSL session master key of the front connection when the incoming
18697 connection was made over an SSL/TLS transport layer. It is useful to decrypt
18698 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
18699 BoringSSL.
18700
18701
Willy Tarreau74ca5042013-06-11 23:12:07 +020018702ssl_fc_sni : string
18703 This extracts the Server Name Indication TLS extension (SNI) field from an
18704 incoming connection made via an SSL/TLS transport layer and locally
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018705 deciphered by HAProxy. The result (when present) typically is a string
Willy Tarreau74ca5042013-06-11 23:12:07 +020018706 matching the HTTPS host name (253 chars or less). The SSL library must have
18707 been built with support for TLS extensions enabled (check haproxy -vv).
18708
18709 This fetch is different from "req_ssl_sni" above in that it applies to the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018710 connection being deciphered by HAProxy and not to SSL contents being blindly
Willy Tarreau74ca5042013-06-11 23:12:07 +020018711 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
John Roeslerfb2fce12019-07-10 15:45:51 -050018712 requires that the SSL library is built with support for TLS extensions
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020018713 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020018714
Willy Tarreau74ca5042013-06-11 23:12:07 +020018715 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020018716 ssl_fc_sni_end : suffix match
18717 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020018718
Willy Tarreau74ca5042013-06-11 23:12:07 +020018719ssl_fc_use_keysize : integer
18720 Returns the symmetric cipher key size used in bits when the incoming
18721 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020018722
William Lallemandbfa3e812020-06-25 20:07:18 +020018723ssl_s_der : binary
18724 Returns the DER formatted certificate presented by the server when the
18725 outgoing connection was made over an SSL/TLS transport layer. When used for
18726 an ACL, the value(s) to match against can be passed in hexadecimal form.
18727
William Dauchya598b502020-08-06 18:11:38 +020018728ssl_s_chain_der : binary
18729 Returns the DER formatted chain certificate presented by the server when the
18730 outgoing connection was made over an SSL/TLS transport layer. When used for
18731 an ACL, the value(s) to match against can be passed in hexadecimal form. One
Ilya Shipitsin2272d8a2020-12-21 01:22:40 +050018732 can parse the result with any lib accepting ASN.1 DER data. It currently
William Dauchya598b502020-08-06 18:11:38 +020018733 does not support resumed sessions.
18734
William Lallemandbfa3e812020-06-25 20:07:18 +020018735ssl_s_key_alg : string
18736 Returns the name of the algorithm used to generate the key of the certificate
18737 presented by the server when the outgoing connection was made over an
18738 SSL/TLS transport layer.
18739
18740ssl_s_notafter : string
18741 Returns the end date presented by the server as a formatted string
18742 YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS
18743 transport layer.
18744
18745ssl_s_notbefore : string
18746 Returns the start date presented by the server as a formatted string
18747 YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS
18748 transport layer.
18749
18750ssl_s_i_dn([<entry>[,<occ>[,<format>]]]) : string
18751 When the outgoing connection was made over an SSL/TLS transport layer,
18752 returns the full distinguished name of the issuer of the certificate
18753 presented by the server when no <entry> is specified, or the value of the
18754 first given entry found from the beginning of the DN. If a positive/negative
18755 occurrence number is specified as the optional second argument, it returns
18756 the value of the nth given entry value from the beginning/end of the DN.
William Lallemand8f600c82020-06-26 09:55:06 +020018757 For instance, "ssl_s_i_dn(OU,2)" the second organization unit, and
18758 "ssl_s_i_dn(CN)" retrieves the common name.
William Lallemandbfa3e812020-06-25 20:07:18 +020018759 The <format> parameter allows you to receive the DN suitable for
18760 consumption by different protocols. Currently supported is rfc2253 for
18761 LDAP v3.
18762 If you'd like to modify the format only you can specify an empty string
18763 and zero for the first two parameters. Example: ssl_s_i_dn(,0,rfc2253)
18764
18765ssl_s_s_dn([<entry>[,<occ>[,<format>]]]) : string
18766 When the outgoing connection was made over an SSL/TLS transport layer,
18767 returns the full distinguished name of the subject of the certificate
18768 presented by the server when no <entry> is specified, or the value of the
18769 first given entry found from the beginning of the DN. If a positive/negative
18770 occurrence number is specified as the optional second argument, it returns
18771 the value of the nth given entry value from the beginning/end of the DN.
William Lallemand8f600c82020-06-26 09:55:06 +020018772 For instance, "ssl_s_s_dn(OU,2)" the second organization unit, and
18773 "ssl_s_s_dn(CN)" retrieves the common name.
William Lallemandbfa3e812020-06-25 20:07:18 +020018774 The <format> parameter allows you to receive the DN suitable for
18775 consumption by different protocols. Currently supported is rfc2253 for
18776 LDAP v3.
18777 If you'd like to modify the format only you can specify an empty string
18778 and zero for the first two parameters. Example: ssl_s_s_dn(,0,rfc2253)
18779
18780ssl_s_serial : binary
18781 Returns the serial of the certificate presented by the server when the
18782 outgoing connection was made over an SSL/TLS transport layer. When used for
18783 an ACL, the value(s) to match against can be passed in hexadecimal form.
18784
18785ssl_s_sha1 : binary
18786 Returns the SHA-1 fingerprint of the certificate presented by the server
18787 when the outgoing connection was made over an SSL/TLS transport layer. This
18788 can be used to know which certificate was chosen using SNI.
18789
18790ssl_s_sig_alg : string
18791 Returns the name of the algorithm used to sign the certificate presented by
18792 the server when the outgoing connection was made over an SSL/TLS transport
18793 layer.
18794
18795ssl_s_version : integer
18796 Returns the version of the certificate presented by the server when the
18797 outgoing connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020018798
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200187997.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020018800------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020018801
Willy Tarreau74ca5042013-06-11 23:12:07 +020018802Fetching samples from buffer contents is a bit different from the previous
18803sample fetches above because the sampled data are ephemeral. These data can
18804only be used when they're available and will be lost when they're forwarded.
18805For this reason, samples fetched from buffer contents during a request cannot
18806be used in a response for example. Even while the data are being fetched, they
18807can change. Sometimes it is necessary to set some delays or combine multiple
18808sample fetch methods to ensure that the expected data are complete and usable,
18809for example through TCP request content inspection. Please see the "tcp-request
18810content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020018811
Christopher Fauleta434a002021-03-25 11:58:51 +010018812Warning : Following sample fetches are ignored if used from HTTP proxies. They
18813 only deal with raw contents found in the buffers. On their side,
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018814 HTTP proxies use structured content. Thus raw representation of
Christopher Fauleta434a002021-03-25 11:58:51 +010018815 these data are meaningless. A warning is emitted if an ACL relies on
18816 one of the following sample fetches. But it is not possible to detect
18817 all invalid usage (for instance inside a log-format string or a
18818 sample expression). So be careful.
18819
Willy Tarreau74ca5042013-06-11 23:12:07 +020018820payload(<offset>,<length>) : binary (deprecated)
Davor Ocelice9ed2812017-12-25 17:49:28 +010018821 This is an alias for "req.payload" when used in the context of a request (e.g.
Willy Tarreau74ca5042013-06-11 23:12:07 +020018822 "stick on", "stick match"), and for "res.payload" when used in the context of
18823 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010018824
Willy Tarreau74ca5042013-06-11 23:12:07 +020018825payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
18826 This is an alias for "req.payload_lv" when used in the context of a request
Davor Ocelice9ed2812017-12-25 17:49:28 +010018827 (e.g. "stick on", "stick match"), and for "res.payload_lv" when used in the
Willy Tarreau74ca5042013-06-11 23:12:07 +020018828 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010018829
Willy Tarreau74ca5042013-06-11 23:12:07 +020018830req.len : integer
18831req_len : integer (deprecated)
18832 Returns an integer value corresponding to the number of bytes present in the
18833 request buffer. This is mostly used in ACL. It is important to understand
18834 that this test does not return false as long as the buffer is changing. This
18835 means that a check with equality to zero will almost always immediately match
18836 at the beginning of the session, while a test for more data will wait for
Daniel Corbett9f0843f2021-05-08 10:50:37 -040018837 that data to come in and return false only when HAProxy is certain that no
Willy Tarreau74ca5042013-06-11 23:12:07 +020018838 more data will come in. This test was designed to be used with TCP request
18839 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018840
Willy Tarreau74ca5042013-06-11 23:12:07 +020018841req.payload(<offset>,<length>) : binary
18842 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020018843 in the request buffer. As a special case, if the <length> argument is zero,
18844 the the whole buffer from <offset> to the end is extracted. This can be used
18845 with ACLs in order to check for the presence of some content in a buffer at
18846 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018847
Willy Tarreau74ca5042013-06-11 23:12:07 +020018848 ACL alternatives :
18849 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018850
Willy Tarreau74ca5042013-06-11 23:12:07 +020018851req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
18852 This extracts a binary block whose size is specified at <offset1> for <length>
18853 bytes, and which starts at <offset2> if specified or just after the length in
18854 the request buffer. The <offset2> parameter also supports relative offsets if
18855 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018856
Willy Tarreau74ca5042013-06-11 23:12:07 +020018857 ACL alternatives :
18858 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018859
Willy Tarreau74ca5042013-06-11 23:12:07 +020018860 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018861
Willy Tarreau74ca5042013-06-11 23:12:07 +020018862req.proto_http : boolean
18863req_proto_http : boolean (deprecated)
18864 Returns true when data in the request buffer look like HTTP and correctly
18865 parses as such. It is the same parser as the common HTTP request parser which
18866 is used so there should be no surprises. The test does not match until the
18867 request is complete, failed or timed out. This test may be used to report the
18868 protocol in TCP logs, but the biggest use is to block TCP request analysis
18869 until a complete HTTP request is present in the buffer, for example to track
18870 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018871
Willy Tarreau74ca5042013-06-11 23:12:07 +020018872 Example:
18873 # track request counts per "base" (concatenation of Host+URL)
18874 tcp-request inspect-delay 10s
18875 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020018876 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020018877
Willy Tarreau74ca5042013-06-11 23:12:07 +020018878req.rdp_cookie([<name>]) : string
18879rdp_cookie([<name>]) : string (deprecated)
18880 When the request buffer looks like the RDP protocol, extracts the RDP cookie
18881 <name>, or any cookie if unspecified. The parser only checks for the first
18882 cookie, as illustrated in the RDP protocol specification. The cookie name is
18883 case insensitive. Generally the "MSTS" cookie name will be used, as it can
18884 contain the user name of the client connecting to the server if properly
18885 configured on the client. The "MSTSHASH" cookie is often used as well for
18886 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018887
Willy Tarreau74ca5042013-06-11 23:12:07 +020018888 This differs from "balance rdp-cookie" in that any balancing algorithm may be
18889 used and thus the distribution of clients to backend servers is not linked to
18890 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
18891 such as "balance roundrobin" or "balance leastconn" will lead to a more even
18892 distribution of clients to backend servers than the hash used by "balance
18893 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018894
Willy Tarreau74ca5042013-06-11 23:12:07 +020018895 ACL derivatives :
18896 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018897
Willy Tarreau74ca5042013-06-11 23:12:07 +020018898 Example :
18899 listen tse-farm
18900 bind 0.0.0.0:3389
18901 # wait up to 5s for an RDP cookie in the request
18902 tcp-request inspect-delay 5s
18903 tcp-request content accept if RDP_COOKIE
18904 # apply RDP cookie persistence
18905 persist rdp-cookie
18906 # Persist based on the mstshash cookie
18907 # This is only useful makes sense if
18908 # balance rdp-cookie is not used
18909 stick-table type string size 204800
18910 stick on req.rdp_cookie(mstshash)
18911 server srv1 1.1.1.1:3389
18912 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018913
Willy Tarreau74ca5042013-06-11 23:12:07 +020018914 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
18915 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018916
Willy Tarreau74ca5042013-06-11 23:12:07 +020018917req.rdp_cookie_cnt([name]) : integer
18918rdp_cookie_cnt([name]) : integer (deprecated)
18919 Tries to parse the request buffer as RDP protocol, then returns an integer
18920 corresponding to the number of RDP cookies found. If an optional cookie name
18921 is passed, only cookies matching this name are considered. This is mostly
18922 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018923
Willy Tarreau74ca5042013-06-11 23:12:07 +020018924 ACL derivatives :
18925 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018926
Alex Zorin4afdd132018-12-30 13:56:28 +110018927req.ssl_alpn : string
18928 Returns a string containing the values of the Application-Layer Protocol
18929 Negotiation (ALPN) TLS extension (RFC7301), sent by the client within the SSL
18930 ClientHello message. Note that this only applies to raw contents found in the
18931 request buffer and not to the contents deciphered via an SSL data layer, so
18932 this will not work with "bind" lines having the "ssl" option. This is useful
18933 in ACL to make a routing decision based upon the ALPN preferences of a TLS
Jarno Huuskonene504f812019-01-03 07:56:49 +020018934 client, like in the example below. See also "ssl_fc_alpn".
Alex Zorin4afdd132018-12-30 13:56:28 +110018935
18936 Examples :
18937 # Wait for a client hello for at most 5 seconds
18938 tcp-request inspect-delay 5s
18939 tcp-request content accept if { req_ssl_hello_type 1 }
Jarno Huuskonene504f812019-01-03 07:56:49 +020018940 use_backend bk_acme if { req.ssl_alpn acme-tls/1 }
Alex Zorin4afdd132018-12-30 13:56:28 +110018941 default_backend bk_default
18942
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020018943req.ssl_ec_ext : boolean
18944 Returns a boolean identifying if client sent the Supported Elliptic Curves
18945 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
Cyril Bonté307ee1e2015-09-28 23:16:06 +020018946 message. This can be used to present ECC compatible clients with EC
18947 certificate and to use RSA for all others, on the same IP address. Note that
18948 this only applies to raw contents found in the request buffer and not to
18949 contents deciphered via an SSL data layer, so this will not work with "bind"
18950 lines having the "ssl" option.
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020018951
Willy Tarreau74ca5042013-06-11 23:12:07 +020018952req.ssl_hello_type : integer
18953req_ssl_hello_type : integer (deprecated)
18954 Returns an integer value containing the type of the SSL hello message found
18955 in the request buffer if the buffer contains data that parse as a complete
18956 SSL (v3 or superior) client hello message. Note that this only applies to raw
18957 contents found in the request buffer and not to contents deciphered via an
18958 SSL data layer, so this will not work with "bind" lines having the "ssl"
18959 option. This is mostly used in ACL to detect presence of an SSL hello message
18960 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018961
Willy Tarreau74ca5042013-06-11 23:12:07 +020018962req.ssl_sni : string
18963req_ssl_sni : string (deprecated)
18964 Returns a string containing the value of the Server Name TLS extension sent
18965 by a client in a TLS stream passing through the request buffer if the buffer
18966 contains data that parse as a complete SSL (v3 or superior) client hello
18967 message. Note that this only applies to raw contents found in the request
18968 buffer and not to contents deciphered via an SSL data layer, so this will not
Lukas Tribusa267b5d2020-07-19 00:25:06 +020018969 work with "bind" lines having the "ssl" option. This will only work for actual
18970 implicit TLS based protocols like HTTPS (443), IMAPS (993), SMTPS (465),
18971 however it will not work for explicit TLS based protocols, like SMTP (25/587)
18972 or IMAP (143). SNI normally contains the name of the host the client tries to
18973 connect to (for recent browsers). SNI is useful for allowing or denying access
18974 to certain hosts when SSL/TLS is used by the client. This test was designed to
18975 be used with TCP request content inspection. If content switching is needed,
18976 it is recommended to first wait for a complete client hello (type 1), like in
18977 the example below. See also "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018978
Willy Tarreau74ca5042013-06-11 23:12:07 +020018979 ACL derivatives :
18980 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018981
Willy Tarreau74ca5042013-06-11 23:12:07 +020018982 Examples :
18983 # Wait for a client hello for at most 5 seconds
18984 tcp-request inspect-delay 5s
18985 tcp-request content accept if { req_ssl_hello_type 1 }
18986 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
18987 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020018988
Pradeep Jindalbb2acf52015-09-29 10:12:57 +053018989req.ssl_st_ext : integer
18990 Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077)
18991 Returns 1 if the client sent SessionTicket TLS Extension
18992 Returns 2 if the client also sent non-zero length TLS SessionTicket
18993 Note that this only applies to raw contents found in the request buffer and
18994 not to contents deciphered via an SSL data layer, so this will not work with
18995 "bind" lines having the "ssl" option. This can for example be used to detect
18996 whether the client sent a SessionTicket or not and stick it accordingly, if
18997 no SessionTicket then stick on SessionID or don't stick as there's no server
18998 side state is there when SessionTickets are in use.
18999
Willy Tarreau74ca5042013-06-11 23:12:07 +020019000req.ssl_ver : integer
19001req_ssl_ver : integer (deprecated)
19002 Returns an integer value containing the version of the SSL/TLS protocol of a
19003 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
19004 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
19005 composed of the major version multiplied by 65536, added to the minor
19006 version. Note that this only applies to raw contents found in the request
19007 buffer and not to contents deciphered via an SSL data layer, so this will not
19008 work with "bind" lines having the "ssl" option. The ACL version of the test
Davor Ocelice9ed2812017-12-25 17:49:28 +010019009 matches against a decimal notation in the form MAJOR.MINOR (e.g. 3.1). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020019010 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019011
Willy Tarreau74ca5042013-06-11 23:12:07 +020019012 ACL derivatives :
19013 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010019014
Willy Tarreau47e8eba2013-09-11 23:28:46 +020019015res.len : integer
19016 Returns an integer value corresponding to the number of bytes present in the
19017 response buffer. This is mostly used in ACL. It is important to understand
19018 that this test does not return false as long as the buffer is changing. This
19019 means that a check with equality to zero will almost always immediately match
19020 at the beginning of the session, while a test for more data will wait for
Daniel Corbett9f0843f2021-05-08 10:50:37 -040019021 that data to come in and return false only when HAProxy is certain that no
Willy Tarreau47e8eba2013-09-11 23:28:46 +020019022 more data will come in. This test was designed to be used with TCP response
Christopher Faulete596d182020-05-05 17:46:34 +020019023 content inspection. But it may also be used in tcp-check based expect rules.
Willy Tarreau47e8eba2013-09-11 23:28:46 +020019024
Willy Tarreau74ca5042013-06-11 23:12:07 +020019025res.payload(<offset>,<length>) : binary
19026 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020019027 in the response buffer. As a special case, if the <length> argument is zero,
Christopher Faulete596d182020-05-05 17:46:34 +020019028 the whole buffer from <offset> to the end is extracted. This can be used
Willy Tarreau00f00842013-08-02 11:07:32 +020019029 with ACLs in order to check for the presence of some content in a buffer at
Christopher Faulete596d182020-05-05 17:46:34 +020019030 any location. It may also be used in tcp-check based expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019031
Willy Tarreau74ca5042013-06-11 23:12:07 +020019032res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
19033 This extracts a binary block whose size is specified at <offset1> for <length>
19034 bytes, and which starts at <offset2> if specified or just after the length in
19035 the response buffer. The <offset2> parameter also supports relative offsets
Christopher Faulete596d182020-05-05 17:46:34 +020019036 if prepended with a '+' or '-' sign. It may also be used in tcp-check based
19037 expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019038
Willy Tarreau74ca5042013-06-11 23:12:07 +020019039 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019040
Willy Tarreau971f7b62015-09-29 14:06:59 +020019041res.ssl_hello_type : integer
19042rep_ssl_hello_type : integer (deprecated)
19043 Returns an integer value containing the type of the SSL hello message found
19044 in the response buffer if the buffer contains data that parses as a complete
19045 SSL (v3 or superior) hello message. Note that this only applies to raw
19046 contents found in the response buffer and not to contents deciphered via an
19047 SSL data layer, so this will not work with "server" lines having the "ssl"
19048 option. This is mostly used in ACL to detect presence of an SSL hello message
19049 that is supposed to contain an SSL session ID usable for stickiness.
19050
Willy Tarreau74ca5042013-06-11 23:12:07 +020019051wait_end : boolean
19052 This fetch either returns true when the inspection period is over, or does
19053 not fetch. It is only used in ACLs, in conjunction with content analysis to
Davor Ocelice9ed2812017-12-25 17:49:28 +010019054 avoid returning a wrong verdict early. It may also be used to delay some
Willy Tarreau74ca5042013-06-11 23:12:07 +020019055 actions, such as a delayed reject for some special addresses. Since it either
19056 stops the rules evaluation or immediately returns true, it is recommended to
Davor Ocelice9ed2812017-12-25 17:49:28 +010019057 use this acl as the last one in a rule. Please note that the default ACL
Willy Tarreau74ca5042013-06-11 23:12:07 +020019058 "WAIT_END" is always usable without prior declaration. This test was designed
19059 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019060
Willy Tarreau74ca5042013-06-11 23:12:07 +020019061 Examples :
19062 # delay every incoming request by 2 seconds
19063 tcp-request inspect-delay 2s
19064 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010019065
Willy Tarreau74ca5042013-06-11 23:12:07 +020019066 # don't immediately tell bad guys they are rejected
19067 tcp-request inspect-delay 10s
19068 acl goodguys src 10.0.0.0/24
19069 acl badguys src 10.0.1.0/24
19070 tcp-request content accept if goodguys
19071 tcp-request content reject if badguys WAIT_END
19072 tcp-request content reject
19073
19074
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200190757.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020019076--------------------------------------
19077
19078It is possible to fetch samples from HTTP contents, requests and responses.
19079This application layer is also called layer 7. It is only possible to fetch the
19080data in this section when a full HTTP request or response has been parsed from
19081its respective request or response buffer. This is always the case with all
19082HTTP specific rules and for sections running with "mode http". When using TCP
19083content inspection, it may be necessary to support an inspection delay in order
19084to let the request or response come in first. These fetches may require a bit
19085more CPU resources than the layer 4 ones, but not much since the request and
19086response are indexed.
19087
Christopher Faulet4d37e532021-03-26 14:44:00 +010019088Note : Regarding HTTP processing from the tcp-request content rules, everything
19089 will work as expected from an HTTP proxy. However, from a TCP proxy,
19090 without an HTTP upgrade, it will only work for HTTP/1 content. For
19091 HTTP/2 content, only the preface is visible. Thus, it is only possible
19092 to rely to "req.proto_http", "req.ver" and eventually "method" sample
19093 fetches. All other L7 sample fetches will fail. After an HTTP upgrade,
19094 they will work in the same manner than from an HTTP proxy.
19095
Willy Tarreau74ca5042013-06-11 23:12:07 +020019096base : string
19097 This returns the concatenation of the first Host header and the path part of
19098 the request, which starts at the first slash and ends before the question
19099 mark. It can be useful in virtual hosted environments to detect URL abuses as
19100 well as to improve shared caches efficiency. Using this with a limited size
19101 stick table also allows one to collect statistics about most commonly
19102 requested objects by host/path. With ACLs it can allow simple content
19103 switching rules involving the host and the path at the same time, such as
19104 "www.example.com/favicon.ico". See also "path" and "uri".
19105
19106 ACL derivatives :
19107 base : exact string match
19108 base_beg : prefix match
19109 base_dir : subdir match
19110 base_dom : domain match
19111 base_end : suffix match
19112 base_len : length match
19113 base_reg : regex match
19114 base_sub : substring match
19115
19116base32 : integer
19117 This returns a 32-bit hash of the value returned by the "base" fetch method
19118 above. This is useful to track per-URL activity on high traffic sites without
19119 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020019120 memory. The output type is an unsigned integer. The hash function used is
19121 SDBM with full avalanche on the output. Technically, base32 is exactly equal
19122 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020019123
19124base32+src : binary
19125 This returns the concatenation of the base32 fetch above and the src fetch
19126 below. The resulting type is of type binary, with a size of 8 or 20 bytes
19127 depending on the source address family. This can be used to track per-IP,
19128 per-URL counters.
19129
Yves Lafonb4d37082021-02-11 11:01:28 +010019130baseq : string
19131 This returns the concatenation of the first Host header and the path part of
19132 the request with the query-string, which starts at the first slash. Using this
19133 instead of "base" allows one to properly identify the target resource, for
19134 statistics or caching use cases. See also "path", "pathq" and "base".
19135
William Lallemand65ad6e12014-01-31 15:08:02 +010019136capture.req.hdr(<idx>) : string
19137 This extracts the content of the header captured by the "capture request
19138 header", idx is the position of the capture keyword in the configuration.
19139 The first entry is an index of 0. See also: "capture request header".
19140
19141capture.req.method : string
19142 This extracts the METHOD of an HTTP request. It can be used in both request
19143 and response. Unlike "method", it can be used in both request and response
19144 because it's allocated.
19145
19146capture.req.uri : string
19147 This extracts the request's URI, which starts at the first slash and ends
19148 before the first space in the request (without the host part). Unlike "path"
19149 and "url", it can be used in both request and response because it's
19150 allocated.
19151
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020019152capture.req.ver : string
19153 This extracts the request's HTTP version and returns either "HTTP/1.0" or
19154 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
19155 logs because it relies on a persistent flag.
19156
William Lallemand65ad6e12014-01-31 15:08:02 +010019157capture.res.hdr(<idx>) : string
19158 This extracts the content of the header captured by the "capture response
19159 header", idx is the position of the capture keyword in the configuration.
19160 The first entry is an index of 0.
19161 See also: "capture response header"
19162
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020019163capture.res.ver : string
19164 This extracts the response's HTTP version and returns either "HTTP/1.0" or
19165 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
19166 persistent flag.
19167
Willy Tarreaua5910cc2015-05-02 00:46:08 +020019168req.body : binary
Christopher Fauletaf4dc4c2020-05-05 17:33:25 +020019169 This returns the HTTP request's available body as a block of data. It is
19170 recommended to use "option http-buffer-request" to be sure to wait, as much
19171 as possible, for the request's body.
Willy Tarreaua5910cc2015-05-02 00:46:08 +020019172
Thierry FOURNIER9826c772015-05-20 15:50:54 +020019173req.body_param([<name>) : string
19174 This fetch assumes that the body of the POST request is url-encoded. The user
19175 can check if the "content-type" contains the value
19176 "application/x-www-form-urlencoded". This extracts the first occurrence of the
19177 parameter <name> in the body, which ends before '&'. The parameter name is
19178 case-sensitive. If no name is given, any parameter will match, and the first
19179 one will be returned. The result is a string corresponding to the value of the
19180 parameter <name> as presented in the request body (no URL decoding is
19181 performed). Note that the ACL version of this fetch iterates over multiple
19182 parameters and will iteratively report all parameters values if no name is
19183 given.
19184
Willy Tarreaua5910cc2015-05-02 00:46:08 +020019185req.body_len : integer
19186 This returns the length of the HTTP request's available body in bytes. It may
19187 be lower than the advertised length if the body is larger than the buffer. It
Christopher Fauletaf4dc4c2020-05-05 17:33:25 +020019188 is recommended to use "option http-buffer-request" to be sure to wait, as
19189 much as possible, for the request's body.
Willy Tarreaua5910cc2015-05-02 00:46:08 +020019190
19191req.body_size : integer
19192 This returns the advertised length of the HTTP request's body in bytes. It
Christopher Fauletaf4dc4c2020-05-05 17:33:25 +020019193 will represent the advertised Content-Length header, or the size of the
19194 available data in case of chunked encoding.
Willy Tarreaua5910cc2015-05-02 00:46:08 +020019195
Willy Tarreau74ca5042013-06-11 23:12:07 +020019196req.cook([<name>]) : string
19197cook([<name>]) : string (deprecated)
19198 This extracts the last occurrence of the cookie name <name> on a "Cookie"
19199 header line from the request, and returns its value as string. If no name is
19200 specified, the first cookie value is returned. When used with ACLs, all
19201 matching cookies are evaluated. Spaces around the name and the value are
19202 ignored as requested by the Cookie header specification (RFC6265). The cookie
19203 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
19204 well return an empty value if it is present. Use the "found" match to detect
19205 presence. Use the res.cook() variant for response cookies sent by the server.
19206
19207 ACL derivatives :
19208 cook([<name>]) : exact string match
19209 cook_beg([<name>]) : prefix match
19210 cook_dir([<name>]) : subdir match
19211 cook_dom([<name>]) : domain match
19212 cook_end([<name>]) : suffix match
19213 cook_len([<name>]) : length match
19214 cook_reg([<name>]) : regex match
19215 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010019216
Willy Tarreau74ca5042013-06-11 23:12:07 +020019217req.cook_cnt([<name>]) : integer
19218cook_cnt([<name>]) : integer (deprecated)
19219 Returns an integer value representing the number of occurrences of the cookie
19220 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019221
Willy Tarreau74ca5042013-06-11 23:12:07 +020019222req.cook_val([<name>]) : integer
19223cook_val([<name>]) : integer (deprecated)
19224 This extracts the last occurrence of the cookie name <name> on a "Cookie"
19225 header line from the request, and converts its value to an integer which is
19226 returned. If no name is specified, the first cookie value is returned. When
19227 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020019228
Willy Tarreau74ca5042013-06-11 23:12:07 +020019229cookie([<name>]) : string (deprecated)
19230 This extracts the last occurrence of the cookie name <name> on a "Cookie"
19231 header line from the request, or a "Set-Cookie" header from the response, and
19232 returns its value as a string. A typical use is to get multiple clients
19233 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020019234 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020019235 multi-peer synchronization and state keeping across restarts. If no name is
19236 specified, the first cookie value is returned. This fetch should not be used
19237 anymore and should be replaced by req.cook() or res.cook() instead as it
19238 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019239
Willy Tarreau74ca5042013-06-11 23:12:07 +020019240hdr([<name>[,<occ>]]) : string
19241 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
19242 used on responses. Please refer to these respective fetches for more details.
19243 In case of doubt about the fetch direction, please use the explicit ones.
19244 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030019245 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019246
Willy Tarreau74ca5042013-06-11 23:12:07 +020019247req.fhdr(<name>[,<occ>]) : string
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019248 This returns the full value of the last occurrence of header <name> in an
19249 HTTP request. It differs from req.hdr() in that any commas present in the
19250 value are returned and are not used as delimiters. This is sometimes useful
19251 with headers such as User-Agent.
19252
19253 When used from an ACL, all occurrences are iterated over until a match is
19254 found.
19255
Willy Tarreau74ca5042013-06-11 23:12:07 +020019256 Optionally, a specific occurrence might be specified as a position number.
19257 Positive values indicate a position from the first occurrence, with 1 being
19258 the first one. Negative values indicate positions relative to the last one,
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019259 with -1 being the last one.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019260
Willy Tarreau74ca5042013-06-11 23:12:07 +020019261req.fhdr_cnt([<name>]) : integer
19262 Returns an integer value representing the number of occurrences of request
19263 header field name <name>, or the total number of header fields if <name> is
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019264 not specified. Like req.fhdr() it differs from res.hdr_cnt() by not splitting
19265 headers at commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019266
Willy Tarreau74ca5042013-06-11 23:12:07 +020019267req.hdr([<name>[,<occ>]]) : string
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019268 This returns the last comma-separated value of the header <name> in an HTTP
19269 request. The fetch considers any comma as a delimiter for distinct values.
19270 This is useful if you need to process headers that are defined to be a list
19271 of values, such as Accept, or X-Forwarded-For. If full-line headers are
19272 desired instead, use req.fhdr(). Please carefully check RFC 7231 to know how
19273 certain headers are supposed to be parsed. Also, some of them are case
19274 insensitive (e.g. Connection).
19275
19276 When used from an ACL, all occurrences are iterated over until a match is
19277 found.
19278
Willy Tarreau74ca5042013-06-11 23:12:07 +020019279 Optionally, a specific occurrence might be specified as a position number.
19280 Positive values indicate a position from the first occurrence, with 1 being
19281 the first one. Negative values indicate positions relative to the last one,
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019282 with -1 being the last one.
19283
19284 A typical use is with the X-Forwarded-For header once converted to IP,
19285 associated with an IP stick-table.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019286
Willy Tarreau74ca5042013-06-11 23:12:07 +020019287 ACL derivatives :
19288 hdr([<name>[,<occ>]]) : exact string match
19289 hdr_beg([<name>[,<occ>]]) : prefix match
19290 hdr_dir([<name>[,<occ>]]) : subdir match
19291 hdr_dom([<name>[,<occ>]]) : domain match
19292 hdr_end([<name>[,<occ>]]) : suffix match
19293 hdr_len([<name>[,<occ>]]) : length match
19294 hdr_reg([<name>[,<occ>]]) : regex match
19295 hdr_sub([<name>[,<occ>]]) : substring match
19296
19297req.hdr_cnt([<name>]) : integer
19298hdr_cnt([<header>]) : integer (deprecated)
19299 Returns an integer value representing the number of occurrences of request
19300 header field name <name>, or the total number of header field values if
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019301 <name> is not specified. Like req.hdr() it counts each comma separated
19302 part of the header's value. If counting of full-line headers is desired,
19303 then req.fhdr_cnt() should be used instead.
19304
19305 With ACLs, it can be used to detect presence, absence or abuse of a specific
19306 header, as well as to block request smuggling attacks by rejecting requests
19307 which contain more than one of certain headers.
19308
19309 Refer to req.hdr() for more information on header matching.
Willy Tarreau74ca5042013-06-11 23:12:07 +020019310
19311req.hdr_ip([<name>[,<occ>]]) : ip
19312hdr_ip([<name>[,<occ>]]) : ip (deprecated)
19313 This extracts the last occurrence of header <name> in an HTTP request,
19314 converts it to an IPv4 or IPv6 address and returns this address. When used
19315 with ACLs, all occurrences are checked, and if <name> is omitted, every value
Willy Tarreau7b0e00d2021-03-25 14:12:29 +010019316 of every header is checked. The parser strictly adheres to the format
19317 described in RFC7239, with the extension that IPv4 addresses may optionally
19318 be followed by a colon (':') and a valid decimal port number (0 to 65535),
19319 which will be silently dropped. All other forms will not match and will
19320 cause the address to be ignored.
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019321
19322 The <occ> parameter is processed as with req.hdr().
19323
19324 A typical use is with the X-Forwarded-For and X-Client-IP headers.
Willy Tarreau74ca5042013-06-11 23:12:07 +020019325
19326req.hdr_val([<name>[,<occ>]]) : integer
19327hdr_val([<name>[,<occ>]]) : integer (deprecated)
19328 This extracts the last occurrence of header <name> in an HTTP request, and
19329 converts it to an integer value. When used with ACLs, all occurrences are
19330 checked, and if <name> is omitted, every value of every header is checked.
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019331
19332 The <occ> parameter is processed as with req.hdr().
19333
19334 A typical use is with the X-Forwarded-For header.
Willy Tarreau74ca5042013-06-11 23:12:07 +020019335
Christopher Faulet687a68e2020-11-24 17:13:24 +010019336req.hdrs : string
19337 Returns the current request headers as string including the last empty line
19338 separating headers from the request body. The last empty line can be used to
19339 detect a truncated header block. This sample fetch is useful for some SPOE
19340 headers analyzers and for advanced logging.
19341
19342req.hdrs_bin : binary
19343 Returns the current request headers contained in preparsed binary form. This
19344 is useful for offloading some processing with SPOE. Each string is described
19345 by a length followed by the number of bytes indicated in the length. The
19346 length is represented using the variable integer encoding detailed in the
19347 SPOE documentation. The end of the list is marked by a couple of empty header
19348 names and values (length of 0 for both).
19349
19350 *(<str:header-name><str:header-value>)<empty string><empty string>
Frédéric Lécailleec891192019-02-26 15:02:35 +010019351
Christopher Faulet687a68e2020-11-24 17:13:24 +010019352 int: refer to the SPOE documentation for the encoding
19353 str: <int:length><bytes>
Frédéric Lécailleec891192019-02-26 15:02:35 +010019354
Willy Tarreau74ca5042013-06-11 23:12:07 +020019355http_auth(<userlist>) : boolean
19356 Returns a boolean indicating whether the authentication data received from
19357 the client match a username & password stored in the specified userlist. This
19358 fetch function is not really useful outside of ACLs. Currently only http
19359 basic auth is supported.
19360
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010019361http_auth_group(<userlist>) : string
19362 Returns a string corresponding to the user name found in the authentication
19363 data received from the client if both the user name and password are valid
19364 according to the specified userlist. The main purpose is to use it in ACLs
19365 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020019366 This fetch function is not really useful outside of ACLs. Currently only http
19367 basic auth is supported.
19368
19369 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010019370 http_auth_group(<userlist>) : group ...
19371 Returns true when the user extracted from the request and whose password is
19372 valid according to the specified userlist belongs to at least one of the
19373 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020019374
Christopher Fauleta4063562019-08-02 11:51:37 +020019375http_auth_pass : string
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010019376 Returns the user's password found in the authentication data received from
19377 the client, as supplied in the Authorization header. Not checks are
19378 performed by this sample fetch. Only Basic authentication is supported.
Christopher Fauleta4063562019-08-02 11:51:37 +020019379
19380http_auth_type : string
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010019381 Returns the authentication method found in the authentication data received from
19382 the client, as supplied in the Authorization header. Not checks are
19383 performed by this sample fetch. Only Basic authentication is supported.
Christopher Fauleta4063562019-08-02 11:51:37 +020019384
19385http_auth_user : string
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010019386 Returns the user name found in the authentication data received from the
19387 client, as supplied in the Authorization header. Not checks are performed by
19388 this sample fetch. Only Basic authentication is supported.
Christopher Fauleta4063562019-08-02 11:51:37 +020019389
Willy Tarreau74ca5042013-06-11 23:12:07 +020019390http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020019391 Returns true when the request being processed is the first one of the
19392 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020019393 from some requests when a request is not the first one, or to help grouping
19394 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020019395
Willy Tarreau74ca5042013-06-11 23:12:07 +020019396method : integer + string
19397 Returns an integer value corresponding to the method in the HTTP request. For
19398 example, "GET" equals 1 (check sources to establish the matching). Value 9
19399 means "other method" and may be converted to a string extracted from the
19400 stream. This should not be used directly as a sample, this is only meant to
19401 be used from ACLs, which transparently convert methods from patterns to these
19402 integer + string values. Some predefined ACL already check for most common
19403 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019404
Willy Tarreau74ca5042013-06-11 23:12:07 +020019405 ACL derivatives :
19406 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020019407
Willy Tarreau74ca5042013-06-11 23:12:07 +020019408 Example :
19409 # only accept GET and HEAD requests
19410 acl valid_method method GET HEAD
19411 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020019412
Willy Tarreau74ca5042013-06-11 23:12:07 +020019413path : string
19414 This extracts the request's URL path, which starts at the first slash and
19415 ends before the question mark (without the host part). A typical use is with
19416 prefetch-capable caches, and with portals which need to aggregate multiple
19417 information from databases and keep them in caches. Note that with outgoing
19418 caches, it would be wiser to use "url" instead. With ACLs, it's typically
Davor Ocelice9ed2812017-12-25 17:49:28 +010019419 used to match exact file names (e.g. "/login.php"), or directory parts using
Willy Tarreau74ca5042013-06-11 23:12:07 +020019420 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019421
Willy Tarreau74ca5042013-06-11 23:12:07 +020019422 ACL derivatives :
19423 path : exact string match
19424 path_beg : prefix match
19425 path_dir : subdir match
19426 path_dom : domain match
19427 path_end : suffix match
19428 path_len : length match
19429 path_reg : regex match
19430 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020019431
Christopher Faulete720c322020-09-02 17:25:18 +020019432pathq : string
19433 This extracts the request's URL path with the query-string, which starts at
19434 the first slash. This sample fetch is pretty handy to always retrieve a
19435 relative URI, excluding the scheme and the authority part, if any. Indeed,
19436 while it is the common representation for an HTTP/1.1 request target, in
19437 HTTP/2, an absolute URI is often used. This sample fetch will return the same
19438 result in both cases.
19439
Willy Tarreau49ad95c2015-01-19 15:06:26 +010019440query : string
19441 This extracts the request's query string, which starts after the first
19442 question mark. If no question mark is present, this fetch returns nothing. If
19443 a question mark is present but nothing follows, it returns an empty string.
19444 This means it's possible to easily know whether a query string is present
Tim Düsterhus4896c442016-11-29 02:15:19 +010019445 using the "found" matching method. This fetch is the complement of "path"
Willy Tarreau49ad95c2015-01-19 15:06:26 +010019446 which stops before the question mark.
19447
Willy Tarreaueb27ec72015-02-20 13:55:29 +010019448req.hdr_names([<delim>]) : string
19449 This builds a string made from the concatenation of all header names as they
19450 appear in the request when the rule is evaluated. The default delimiter is
19451 the comma (',') but it may be overridden as an optional argument <delim>. In
19452 this case, only the first character of <delim> is considered.
19453
Willy Tarreau74ca5042013-06-11 23:12:07 +020019454req.ver : string
19455req_ver : string (deprecated)
19456 Returns the version string from the HTTP request, for example "1.1". This can
19457 be useful for logs, but is mostly there for ACL. Some predefined ACL already
19458 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019459
Willy Tarreau74ca5042013-06-11 23:12:07 +020019460 ACL derivatives :
19461 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020019462
Christopher Faulete596d182020-05-05 17:46:34 +020019463res.body : binary
19464 This returns the HTTP response's available body as a block of data. Unlike
19465 the request side, there is no directive to wait for the response's body. This
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019466 sample fetch is really useful (and usable) in the health-check context.
19467
19468 It may be used in tcp-check based expect rules.
Christopher Faulete596d182020-05-05 17:46:34 +020019469
19470res.body_len : integer
19471 This returns the length of the HTTP response available body in bytes. Unlike
19472 the request side, there is no directive to wait for the response's body. This
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019473 sample fetch is really useful (and usable) in the health-check context.
19474
19475 It may be used in tcp-check based expect rules.
Christopher Faulete596d182020-05-05 17:46:34 +020019476
19477res.body_size : integer
19478 This returns the advertised length of the HTTP response body in bytes. It
19479 will represent the advertised Content-Length header, or the size of the
19480 available data in case of chunked encoding. Unlike the request side, there is
19481 no directive to wait for the response body. This sample fetch is really
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019482 useful (and usable) in the health-check context.
19483
19484 It may be used in tcp-check based expect rules.
Christopher Faulete596d182020-05-05 17:46:34 +020019485
Remi Tricot-Le Bretonbf971212020-10-27 11:55:57 +010019486res.cache_hit : boolean
19487 Returns the boolean "true" value if the response has been built out of an
19488 HTTP cache entry, otherwise returns boolean "false".
19489
19490res.cache_name : string
19491 Returns a string containing the name of the HTTP cache that was used to
19492 build the HTTP response if res.cache_hit is true, otherwise returns an
19493 empty string.
19494
Willy Tarreau74ca5042013-06-11 23:12:07 +020019495res.comp : boolean
19496 Returns the boolean "true" value if the response has been compressed by
19497 HAProxy, otherwise returns boolean "false". This may be used to add
19498 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019499
Willy Tarreau74ca5042013-06-11 23:12:07 +020019500res.comp_algo : string
19501 Returns a string containing the name of the algorithm used if the response
19502 was compressed by HAProxy, for example : "deflate". This may be used to add
19503 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019504
Willy Tarreau74ca5042013-06-11 23:12:07 +020019505res.cook([<name>]) : string
19506scook([<name>]) : string (deprecated)
19507 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
19508 header line from the response, and returns its value as string. If no name is
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019509 specified, the first cookie value is returned.
19510
19511 It may be used in tcp-check based expect rules.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020019512
Willy Tarreau74ca5042013-06-11 23:12:07 +020019513 ACL derivatives :
19514 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020019515
Willy Tarreau74ca5042013-06-11 23:12:07 +020019516res.cook_cnt([<name>]) : integer
19517scook_cnt([<name>]) : integer (deprecated)
19518 Returns an integer value representing the number of occurrences of the cookie
19519 <name> in the response, or all cookies if <name> is not specified. This is
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019520 mostly useful when combined with ACLs to detect suspicious responses.
19521
19522 It may be used in tcp-check based expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019523
Willy Tarreau74ca5042013-06-11 23:12:07 +020019524res.cook_val([<name>]) : integer
19525scook_val([<name>]) : integer (deprecated)
19526 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
19527 header line from the response, and converts its value to an integer which is
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019528 returned. If no name is specified, the first cookie value is returned.
19529
19530 It may be used in tcp-check based expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010019531
Willy Tarreau74ca5042013-06-11 23:12:07 +020019532res.fhdr([<name>[,<occ>]]) : string
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019533 This fetch works like the req.fhdr() fetch with the difference that it acts
19534 on the headers within an HTTP response.
19535
19536 Like req.fhdr() the res.fhdr() fetch returns full values. If the header is
19537 defined to be a list you should use res.hdr().
19538
19539 This fetch is sometimes useful with headers such as Date or Expires.
19540
19541 It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019542
Willy Tarreau74ca5042013-06-11 23:12:07 +020019543res.fhdr_cnt([<name>]) : integer
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019544 This fetch works like the req.fhdr_cnt() fetch with the difference that it
19545 acts on the headers within an HTTP response.
19546
19547 Like req.fhdr_cnt() the res.fhdr_cnt() fetch acts on full values. If the
19548 header is defined to be a list you should use res.hdr_cnt().
19549
19550 It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019551
Willy Tarreau74ca5042013-06-11 23:12:07 +020019552res.hdr([<name>[,<occ>]]) : string
19553shdr([<name>[,<occ>]]) : string (deprecated)
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019554 This fetch works like the req.hdr() fetch with the difference that it acts
19555 on the headers within an HTTP response.
19556
Ilya Shipitsinacf84592021-02-06 22:29:08 +050019557 Like req.hdr() the res.hdr() fetch considers the comma to be a delimiter. If
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019558 this is not desired res.fhdr() should be used.
19559
19560 It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019561
Willy Tarreau74ca5042013-06-11 23:12:07 +020019562 ACL derivatives :
19563 shdr([<name>[,<occ>]]) : exact string match
19564 shdr_beg([<name>[,<occ>]]) : prefix match
19565 shdr_dir([<name>[,<occ>]]) : subdir match
19566 shdr_dom([<name>[,<occ>]]) : domain match
19567 shdr_end([<name>[,<occ>]]) : suffix match
19568 shdr_len([<name>[,<occ>]]) : length match
19569 shdr_reg([<name>[,<occ>]]) : regex match
19570 shdr_sub([<name>[,<occ>]]) : substring match
19571
19572res.hdr_cnt([<name>]) : integer
19573shdr_cnt([<name>]) : integer (deprecated)
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019574 This fetch works like the req.hdr_cnt() fetch with the difference that it
19575 acts on the headers within an HTTP response.
19576
19577 Like req.hdr_cnt() the res.hdr_cnt() fetch considers the comma to be a
Ilya Shipitsinacf84592021-02-06 22:29:08 +050019578 delimiter. If this is not desired res.fhdr_cnt() should be used.
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019579
19580 It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019581
Willy Tarreau74ca5042013-06-11 23:12:07 +020019582res.hdr_ip([<name>[,<occ>]]) : ip
19583shdr_ip([<name>[,<occ>]]) : ip (deprecated)
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019584 This fetch works like the req.hdr_ip() fetch with the difference that it
19585 acts on the headers within an HTTP response.
19586
19587 This can be useful to learn some data into a stick table.
19588
19589 It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020019590
Willy Tarreaueb27ec72015-02-20 13:55:29 +010019591res.hdr_names([<delim>]) : string
19592 This builds a string made from the concatenation of all header names as they
19593 appear in the response when the rule is evaluated. The default delimiter is
19594 the comma (',') but it may be overridden as an optional argument <delim>. In
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019595 this case, only the first character of <delim> is considered.
19596
19597 It may be used in tcp-check based expect rules.
Willy Tarreaueb27ec72015-02-20 13:55:29 +010019598
Willy Tarreau74ca5042013-06-11 23:12:07 +020019599res.hdr_val([<name>[,<occ>]]) : integer
19600shdr_val([<name>[,<occ>]]) : integer (deprecated)
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019601 This fetch works like the req.hdr_val() fetch with the difference that it
19602 acts on the headers within an HTTP response.
19603
19604 This can be useful to learn some data into a stick table.
19605
19606 It may be used in tcp-check based expect rules.
Christopher Faulete596d182020-05-05 17:46:34 +020019607
19608res.hdrs : string
19609 Returns the current response headers as string including the last empty line
19610 separating headers from the request body. The last empty line can be used to
19611 detect a truncated header block. This sample fetch is useful for some SPOE
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019612 headers analyzers and for advanced logging.
19613
19614 It may also be used in tcp-check based expect rules.
Christopher Faulete596d182020-05-05 17:46:34 +020019615
19616res.hdrs_bin : binary
19617 Returns the current response headers contained in preparsed binary form. This
19618 is useful for offloading some processing with SPOE. It may be used in
19619 tcp-check based expect rules. Each string is described by a length followed
19620 by the number of bytes indicated in the length. The length is represented
19621 using the variable integer encoding detailed in the SPOE documentation. The
19622 end of the list is marked by a couple of empty header names and values
19623 (length of 0 for both).
19624
19625 *(<str:header-name><str:header-value>)<empty string><empty string>
19626
19627 int: refer to the SPOE documentation for the encoding
19628 str: <int:length><bytes>
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010019629
Willy Tarreau74ca5042013-06-11 23:12:07 +020019630res.ver : string
19631resp_ver : string (deprecated)
19632 Returns the version string from the HTTP response, for example "1.1". This
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019633 can be useful for logs, but is mostly there for ACL.
19634
19635 It may be used in tcp-check based expect rules.
Willy Tarreau0e698542011-09-16 08:32:32 +020019636
Willy Tarreau74ca5042013-06-11 23:12:07 +020019637 ACL derivatives :
19638 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010019639
Willy Tarreau74ca5042013-06-11 23:12:07 +020019640set-cookie([<name>]) : string (deprecated)
19641 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
19642 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020019643 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020019644 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010019645
Willy Tarreau74ca5042013-06-11 23:12:07 +020019646 This fetch function is deprecated and has been superseded by the "res.cook"
19647 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010019648
Willy Tarreau74ca5042013-06-11 23:12:07 +020019649status : integer
19650 Returns an integer containing the HTTP status code in the HTTP response, for
19651 example, 302. It is mostly used within ACLs and integer ranges, for example,
Tim Duesterhus27c70ae2021-01-23 17:50:21 +010019652 to remove any Location header if the response is not a 3xx.
19653
19654 It may be used in tcp-check based expect rules.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019655
Thierry Fournier0e00dca2016-04-07 15:47:40 +020019656unique-id : string
19657 Returns the unique-id attached to the request. The directive
19658 "unique-id-format" must be set. If it is not set, the unique-id sample fetch
19659 fails. Note that the unique-id is usually used with HTTP requests, however this
19660 sample fetch can be used with other protocols. Obviously, if it is used with
19661 other protocols than HTTP, the unique-id-format directive must not contain
19662 HTTP parts. See: unique-id-format and unique-id-header
19663
Willy Tarreau74ca5042013-06-11 23:12:07 +020019664url : string
19665 This extracts the request's URL as presented in the request. A typical use is
19666 with prefetch-capable caches, and with portals which need to aggregate
19667 multiple information from databases and keep them in caches. With ACLs, using
19668 "path" is preferred over using "url", because clients may send a full URL as
19669 is normally done with proxies. The only real use is to match "*" which does
19670 not match in "path", and for which there is already a predefined ACL. See
19671 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019672
Willy Tarreau74ca5042013-06-11 23:12:07 +020019673 ACL derivatives :
19674 url : exact string match
19675 url_beg : prefix match
19676 url_dir : subdir match
19677 url_dom : domain match
19678 url_end : suffix match
19679 url_len : length match
19680 url_reg : regex match
19681 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019682
Willy Tarreau74ca5042013-06-11 23:12:07 +020019683url_ip : ip
19684 This extracts the IP address from the request's URL when the host part is
19685 presented as an IP address. Its use is very limited. For instance, a
19686 monitoring system might use this field as an alternative for the source IP in
19687 order to test what path a given source address would follow, or to force an
19688 entry in a table for a given source address. With ACLs it can be used to
19689 restrict access to certain systems through a proxy, for example when combined
19690 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019691
Willy Tarreau74ca5042013-06-11 23:12:07 +020019692url_port : integer
19693 This extracts the port part from the request's URL. Note that if the port is
19694 not specified in the request, port 80 is assumed. With ACLs it can be used to
19695 restrict access to certain systems through a proxy, for example when combined
19696 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019697
Willy Tarreau1ede1da2015-05-07 16:06:18 +020019698urlp([<name>[,<delim>]]) : string
19699url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020019700 This extracts the first occurrence of the parameter <name> in the query
19701 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020019702 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
19703 any parameter will match, and the first one will be returned. The result is
19704 a string corresponding to the value of the parameter <name> as presented in
19705 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020019706 stickiness based on a client ID, to extract an application cookie passed as a
19707 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020019708 this fetch iterates over multiple parameters and will iteratively report all
19709 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019710
Willy Tarreau74ca5042013-06-11 23:12:07 +020019711 ACL derivatives :
19712 urlp(<name>[,<delim>]) : exact string match
19713 urlp_beg(<name>[,<delim>]) : prefix match
19714 urlp_dir(<name>[,<delim>]) : subdir match
19715 urlp_dom(<name>[,<delim>]) : domain match
19716 urlp_end(<name>[,<delim>]) : suffix match
19717 urlp_len(<name>[,<delim>]) : length match
19718 urlp_reg(<name>[,<delim>]) : regex match
19719 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019720
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019721
Willy Tarreau74ca5042013-06-11 23:12:07 +020019722 Example :
19723 # match http://example.com/foo?PHPSESSIONID=some_id
19724 stick on urlp(PHPSESSIONID)
19725 # match http://example.com/foo;JSESSIONID=some_id
19726 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020019727
Jarno Huuskonen676f6222017-03-30 09:19:45 +030019728urlp_val([<name>[,<delim>]]) : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020019729 See "urlp" above. This one extracts the URL parameter <name> in the request
19730 and converts it to an integer value. This can be used for session stickiness
19731 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020019732
Dragan Dosen0070cd52016-06-16 12:19:49 +020019733url32 : integer
19734 This returns a 32-bit hash of the value obtained by concatenating the first
19735 Host header and the whole URL including parameters (not only the path part of
19736 the request, as in the "base32" fetch above). This is useful to track per-URL
19737 activity. A shorter hash is stored, saving a lot of memory. The output type
19738 is an unsigned integer.
19739
19740url32+src : binary
19741 This returns the concatenation of the "url32" fetch and the "src" fetch. The
19742 resulting type is of type binary, with a size of 8 or 20 bytes depending on
19743 the source address family. This can be used to track per-IP, per-URL counters.
19744
Christopher Faulet16032ab2020-04-30 11:30:00 +020019745
Christopher Faulete596d182020-05-05 17:46:34 +0200197467.3.7. Fetching samples for developers
Christopher Fauletd47941d2020-01-08 14:40:19 +010019747---------------------------------------
19748
19749This set of sample fetch methods is reserved to developers and must never be
19750used on a production environment, except on developer demand, for debugging
19751purposes. Moreover, no special care will be taken on backwards compatibility.
19752There is no warranty the following sample fetches will never change, be renamed
19753or simply removed. So be really careful if you should use one of them. To avoid
19754any ambiguity, these sample fetches are placed in the dedicated scope "internal",
19755for instance "internal.strm.is_htx".
19756
19757internal.htx.data : integer
19758 Returns the size in bytes used by data in the HTX message associated to a
19759 channel. The channel is chosen depending on the sample direction.
19760
19761internal.htx.free : integer
19762 Returns the free space (size - used) in bytes in the HTX message associated
19763 to a channel. The channel is chosen depending on the sample direction.
19764
19765internal.htx.free_data : integer
19766 Returns the free space for the data in bytes in the HTX message associated to
19767 a channel. The channel is chosen depending on the sample direction.
19768
19769internal.htx.has_eom : boolean
Christopher Fauletd1ac2b92020-12-02 19:12:22 +010019770 Returns true if the HTX message associated to a channel contains the
19771 end-of-message flag (EOM). Otherwise, it returns false. The channel is chosen
19772 depending on the sample direction.
Christopher Fauletd47941d2020-01-08 14:40:19 +010019773
19774internal.htx.nbblks : integer
19775 Returns the number of blocks present in the HTX message associated to a
19776 channel. The channel is chosen depending on the sample direction.
19777
19778internal.htx.size : integer
19779 Returns the total size in bytes of the HTX message associated to a
19780 channel. The channel is chosen depending on the sample direction.
19781
19782internal.htx.used : integer
19783 Returns the total size used in bytes (data + metadata) in the HTX message
19784 associated to a channel. The channel is chosen depending on the sample
19785 direction.
19786
19787internal.htx_blk.size(<idx>) : integer
19788 Returns the size of the block at the position <idx> in the HTX message
19789 associated to a channel or 0 if it does not exist. The channel is chosen
19790 depending on the sample direction. <idx> may be any positive integer or one
19791 of the special value :
19792 * head : The oldest inserted block
19793 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050019794 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010019795
19796internal.htx_blk.type(<idx>) : string
19797 Returns the type of the block at the position <idx> in the HTX message
19798 associated to a channel or "HTX_BLK_UNUSED" if it does not exist. The channel
19799 is chosen depending on the sample direction. <idx> may be any positive
19800 integer or one of the special value :
19801 * head : The oldest inserted block
19802 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050019803 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010019804
19805internal.htx_blk.data(<idx>) : binary
19806 Returns the value of the DATA block at the position <idx> in the HTX message
19807 associated to a channel or an empty string if it does not exist or if it is
19808 not a DATA block. The channel is chosen depending on the sample direction.
19809 <idx> may be any positive integer or one of the special value :
19810
19811 * head : The oldest inserted block
19812 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050019813 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010019814
19815internal.htx_blk.hdrname(<idx>) : string
19816 Returns the header name of the HEADER block at the position <idx> in the HTX
19817 message associated to a channel or an empty string if it does not exist or if
19818 it is not an HEADER block. The channel is chosen depending on the sample
19819 direction. <idx> may be any positive integer or one of the special value :
19820
19821 * head : The oldest inserted block
19822 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050019823 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010019824
19825internal.htx_blk.hdrval(<idx>) : string
19826 Returns the header value of the HEADER block at the position <idx> in the HTX
19827 message associated to a channel or an empty string if it does not exist or if
19828 it is not an HEADER block. The channel is chosen depending on the sample
19829 direction. <idx> may be any positive integer or one of the special value :
19830
19831 * head : The oldest inserted block
19832 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050019833 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010019834
19835internal.htx_blk.start_line(<idx>) : string
19836 Returns the value of the REQ_SL or RES_SL block at the position <idx> in the
19837 HTX message associated to a channel or an empty string if it does not exist
19838 or if it is not a SL block. The channel is chosen depending on the sample
19839 direction. <idx> may be any positive integer or one of the special value :
19840
19841 * head : The oldest inserted block
19842 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050019843 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010019844
19845internal.strm.is_htx : boolean
19846 Returns true if the current stream is an HTX stream. It means the data in the
19847 channels buffers are stored using the internal HTX representation. Otherwise,
19848 it returns false.
19849
19850
Willy Tarreau74ca5042013-06-11 23:12:07 +0200198517.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019852---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010019853
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019854Some predefined ACLs are hard-coded so that they do not have to be declared in
19855every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020019856order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010019857
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019858ACL name Equivalent to Usage
Christopher Faulet779184e2021-04-01 17:24:04 +020019859---------------+----------------------------------+------------------------------------------------------
19860FALSE always_false never match
19861HTTP req.proto_http match if request protocol is valid HTTP
19862HTTP_1.0 req.ver 1.0 match if HTTP request version is 1.0
19863HTTP_1.1 req.ver 1.1 match if HTTP request version is 1.1
Christopher Faulet8043e832021-03-26 16:00:54 +010019864HTTP_2.0 req.ver 2.0 match if HTTP request version is 2.0
Christopher Faulet779184e2021-04-01 17:24:04 +020019865HTTP_CONTENT req.hdr_val(content-length) gt 0 match an existing content-length in the HTTP request
19866HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
19867HTTP_URL_SLASH url_beg / match URL beginning with "/"
19868HTTP_URL_STAR url * match URL equal to "*"
19869LOCALHOST src 127.0.0.1/8 match connection from local host
19870METH_CONNECT method CONNECT match HTTP CONNECT method
19871METH_DELETE method DELETE match HTTP DELETE method
19872METH_GET method GET HEAD match HTTP GET or HEAD method
19873METH_HEAD method HEAD match HTTP HEAD method
19874METH_OPTIONS method OPTIONS match HTTP OPTIONS method
19875METH_POST method POST match HTTP POST method
19876METH_PUT method PUT match HTTP PUT method
19877METH_TRACE method TRACE match HTTP TRACE method
19878RDP_COOKIE req.rdp_cookie_cnt gt 0 match presence of an RDP cookie in the request buffer
19879REQ_CONTENT req.len gt 0 match data in the request buffer
19880TRUE always_true always match
19881WAIT_END wait_end wait for end of content analysis
19882---------------+----------------------------------+------------------------------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010019883
Willy Tarreaub937b7e2010-01-12 15:27:54 +010019884
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200198858. Logging
19886----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010019887
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019888One of HAProxy's strong points certainly lies is its precise logs. It probably
19889provides the finest level of information available for such a product, which is
19890very important for troubleshooting complex environments. Standard information
19891provided in logs include client ports, TCP/HTTP state timers, precise session
19892state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010019893to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019894headers.
19895
19896In order to improve administrators reactivity, it offers a great transparency
19897about encountered problems, both internal and external, and it is possible to
19898send logs to different sources at the same time with different level filters :
19899
19900 - global process-level logs (system errors, start/stop, etc..)
19901 - per-instance system and internal errors (lack of resource, bugs, ...)
19902 - per-instance external troubles (servers up/down, max connections)
19903 - per-instance activity (client connections), either at the establishment or
19904 at the termination.
Davor Ocelice9ed2812017-12-25 17:49:28 +010019905 - per-request control of log-level, e.g.
Jim Freeman9e8714b2015-05-26 09:16:34 -060019906 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019907
19908The ability to distribute different levels of logs to different log servers
19909allow several production teams to interact and to fix their problems as soon
19910as possible. For example, the system team might monitor system-wide errors,
19911while the application team might be monitoring the up/down for their servers in
19912real time, and the security team might analyze the activity logs with one hour
19913delay.
19914
19915
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199168.1. Log levels
19917---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019918
Simon Hormandf791f52011-05-29 15:01:10 +090019919TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019920source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090019921HTTP request, HTTP return code, number of bytes transmitted, conditions
19922in which the session ended, and even exchanged cookies values. For example
19923track a particular user's problems. All messages may be sent to up to two
19924syslog servers. Check the "log" keyword in section 4.2 for more information
19925about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019926
19927
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199288.2. Log formats
19929----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019930
William Lallemand48940402012-01-30 16:47:22 +010019931HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090019932and will be detailed in the following sections. A few of them may vary
19933slightly with the configuration, due to indicators specific to certain
19934options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019935
19936 - the default format, which is very basic and very rarely used. It only
19937 provides very basic information about the incoming connection at the moment
19938 it is accepted : source IP:port, destination IP:port, and frontend-name.
19939 This mode will eventually disappear so it will not be described to great
19940 extents.
19941
19942 - the TCP format, which is more advanced. This format is enabled when "option
19943 tcplog" is set on the frontend. HAProxy will then usually wait for the
19944 connection to terminate before logging. This format provides much richer
19945 information, such as timers, connection counts, queue size, etc... This
19946 format is recommended for pure TCP proxies.
19947
19948 - the HTTP format, which is the most advanced for HTTP proxying. This format
19949 is enabled when "option httplog" is set on the frontend. It provides the
19950 same information as the TCP format with some HTTP-specific fields such as
19951 the request, the status code, and captures of headers and cookies. This
19952 format is recommended for HTTP proxies.
19953
Emeric Brun3a058f32009-06-30 18:26:00 +020019954 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
19955 fields arranged in the same order as the CLF format. In this mode, all
19956 timers, captures, flags, etc... appear one per field after the end of the
19957 common fields, in the same order they appear in the standard HTTP format.
19958
William Lallemand48940402012-01-30 16:47:22 +010019959 - the custom log format, allows you to make your own log line.
19960
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019961Next sections will go deeper into details for each of these formats. Format
19962specification will be performed on a "field" basis. Unless stated otherwise, a
19963field is a portion of text delimited by any number of spaces. Since syslog
19964servers are susceptible of inserting fields at the beginning of a line, it is
19965always assumed that the first field is the one containing the process name and
19966identifier.
19967
19968Note : Since log lines may be quite long, the log examples in sections below
19969 might be broken into multiple lines. The example log lines will be
19970 prefixed with 3 closing angle brackets ('>>>') and each time a log is
19971 broken into multiple lines, each non-final line will end with a
19972 backslash ('\') and the next line will start indented by two characters.
19973
19974
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199758.2.1. Default log format
19976-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019977
19978This format is used when no specific option is set. The log is emitted as soon
19979as the connection is accepted. One should note that this currently is the only
19980format which logs the request's destination IP and ports.
19981
19982 Example :
19983 listen www
19984 mode http
19985 log global
19986 server srv1 127.0.0.1:8000
19987
19988 >>> Feb 6 12:12:09 localhost \
19989 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
19990 (www/HTTP)
19991
19992 Field Format Extract from the example above
19993 1 process_name '[' pid ']:' haproxy[14385]:
19994 2 'Connect from' Connect from
19995 3 source_ip ':' source_port 10.0.1.2:33312
19996 4 'to' to
19997 5 destination_ip ':' destination_port 10.0.3.31:8012
19998 6 '(' frontend_name '/' mode ')' (www/HTTP)
19999
20000Detailed fields description :
20001 - "source_ip" is the IP address of the client which initiated the connection.
20002 - "source_port" is the TCP port of the client which initiated the connection.
20003 - "destination_ip" is the IP address the client connected to.
20004 - "destination_port" is the TCP port the client connected to.
20005 - "frontend_name" is the name of the frontend (or listener) which received
20006 and processed the connection.
20007 - "mode is the mode the frontend is operating (TCP or HTTP).
20008
Willy Tarreauceb24bc2010-11-09 12:46:41 +010020009In case of a UNIX socket, the source and destination addresses are marked as
20010"unix:" and the ports reflect the internal ID of the socket which accepted the
20011connection (the same ID as reported in the stats).
20012
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020013It is advised not to use this deprecated format for newer installations as it
20014will eventually disappear.
20015
20016
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200200178.2.2. TCP log format
20018---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020019
20020The TCP format is used when "option tcplog" is specified in the frontend, and
20021is the recommended format for pure TCP proxies. It provides a lot of precious
20022information for troubleshooting. Since this format includes timers and byte
20023counts, the log is normally emitted at the end of the session. It can be
20024emitted earlier if "option logasap" is specified, which makes sense in most
20025environments with long sessions such as remote terminals. Sessions which match
20026the "monitor" rules are never logged. It is also possible not to emit logs for
20027sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020020028specifying "option dontlognull" in the frontend. Successful connections will
20029not be logged if "option dontlog-normal" is specified in the frontend. A few
20030fields may slightly vary depending on some configuration options, those are
20031marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020032
20033 Example :
20034 frontend fnt
20035 mode tcp
20036 option tcplog
20037 log global
20038 default_backend bck
20039
20040 backend bck
20041 server srv1 127.0.0.1:8000
20042
20043 >>> Feb 6 12:12:56 localhost \
20044 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
20045 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
20046
20047 Field Format Extract from the example above
20048 1 process_name '[' pid ']:' haproxy[14387]:
20049 2 client_ip ':' client_port 10.0.1.2:33313
20050 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
20051 4 frontend_name fnt
20052 5 backend_name '/' server_name bck/srv1
20053 6 Tw '/' Tc '/' Tt* 0/0/5007
20054 7 bytes_read* 212
20055 8 termination_state --
20056 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
20057 10 srv_queue '/' backend_queue 0/0
20058
20059Detailed fields description :
20060 - "client_ip" is the IP address of the client which initiated the TCP
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020061 connection to HAProxy. If the connection was accepted on a UNIX socket
Willy Tarreauceb24bc2010-11-09 12:46:41 +010020062 instead, the IP address would be replaced with the word "unix". Note that
20063 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010020064 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010020065 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010020066 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020067
20068 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010020069 If the connection was accepted on a UNIX socket instead, the port would be
20070 replaced with the ID of the accepting socket, which is also reported in the
20071 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020072
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020073 - "accept_date" is the exact date when the connection was received by HAProxy
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020074 (which might be very slightly different from the date observed on the
20075 network if there was some queuing in the system's backlog). This is usually
Willy Tarreau590a0512018-09-05 11:56:48 +020020076 the same date which may appear in any upstream firewall's log. When used in
20077 HTTP mode, the accept_date field will be reset to the first moment the
20078 connection is ready to receive a new request (end of previous response for
20079 HTTP/1, immediately after previous request for HTTP/2).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020080
20081 - "frontend_name" is the name of the frontend (or listener) which received
20082 and processed the connection.
20083
20084 - "backend_name" is the name of the backend (or listener) which was selected
20085 to manage the connection to the server. This will be the same as the
20086 frontend if no switching rule has been applied, which is common for TCP
20087 applications.
20088
20089 - "server_name" is the name of the last server to which the connection was
20090 sent, which might differ from the first one if there were connection errors
20091 and a redispatch occurred. Note that this server belongs to the backend
20092 which processed the request. If the connection was aborted before reaching
20093 a server, "<NOSRV>" is indicated instead of a server name.
20094
20095 - "Tw" is the total time in milliseconds spent waiting in the various queues.
20096 It can be "-1" if the connection was aborted before reaching the queue.
20097 See "Timers" below for more details.
20098
20099 - "Tc" is the total time in milliseconds spent waiting for the connection to
20100 establish to the final server, including retries. It can be "-1" if the
20101 connection was aborted before a connection could be established. See
20102 "Timers" below for more details.
20103
20104 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030020105 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020106 "option logasap" was specified, then the time counting stops at the moment
20107 the log is emitted. In this case, a '+' sign is prepended before the value,
20108 indicating that the final one will be larger. See "Timers" below for more
20109 details.
20110
20111 - "bytes_read" is the total number of bytes transmitted from the server to
20112 the client when the log is emitted. If "option logasap" is specified, the
20113 this value will be prefixed with a '+' sign indicating that the final one
20114 may be larger. Please note that this value is a 64-bit counter, so log
20115 analysis tools must be able to handle it without overflowing.
20116
20117 - "termination_state" is the condition the session was in when the session
20118 ended. This indicates the session state, which side caused the end of
20119 session to happen, and for what reason (timeout, error, ...). The normal
20120 flags should be "--", indicating the session was closed by either end with
20121 no data remaining in buffers. See below "Session state at disconnection"
20122 for more details.
20123
20124 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040020125 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020126 limits have been reached. For instance, if actconn is close to 512 when
20127 multiple connection errors occur, chances are high that the system limits
20128 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020020129 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020130
20131 - "feconn" is the total number of concurrent connections on the frontend when
20132 the session was logged. It is useful to estimate the amount of resource
20133 required to sustain high loads, and to detect when the frontend's "maxconn"
20134 has been reached. Most often when this value increases by huge jumps, it is
20135 because there is congestion on the backend servers, but sometimes it can be
20136 caused by a denial of service attack.
20137
20138 - "beconn" is the total number of concurrent connections handled by the
20139 backend when the session was logged. It includes the total number of
20140 concurrent connections active on servers as well as the number of
20141 connections pending in queues. It is useful to estimate the amount of
20142 additional servers needed to support high loads for a given application.
20143 Most often when this value increases by huge jumps, it is because there is
20144 congestion on the backend servers, but sometimes it can be caused by a
20145 denial of service attack.
20146
20147 - "srv_conn" is the total number of concurrent connections still active on
20148 the server when the session was logged. It can never exceed the server's
20149 configured "maxconn" parameter. If this value is very often close or equal
20150 to the server's "maxconn", it means that traffic regulation is involved a
20151 lot, meaning that either the server's maxconn value is too low, or that
20152 there aren't enough servers to process the load with an optimal response
20153 time. When only one of the server's "srv_conn" is high, it usually means
20154 that this server has some trouble causing the connections to take longer to
20155 be processed than on other servers.
20156
20157 - "retries" is the number of connection retries experienced by this session
20158 when trying to connect to the server. It must normally be zero, unless a
20159 server is being stopped at the same moment the connection was attempted.
20160 Frequent retries generally indicate either a network problem between
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020161 HAProxy and the server, or a misconfigured system backlog on the server
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020162 preventing new connections from being queued. This field may optionally be
20163 prefixed with a '+' sign, indicating that the session has experienced a
20164 redispatch after the maximal retry count has been reached on the initial
20165 server. In this case, the server name appearing in the log is the one the
20166 connection was redispatched to, and not the first one, though both may
20167 sometimes be the same in case of hashing for instance. So as a general rule
20168 of thumb, when a '+' is present in front of the retry count, this count
20169 should not be attributed to the logged server.
20170
20171 - "srv_queue" is the total number of requests which were processed before
20172 this one in the server queue. It is zero when the request has not gone
20173 through the server queue. It makes it possible to estimate the approximate
20174 server's response time by dividing the time spent in queue by the number of
20175 requests in the queue. It is worth noting that if a session experiences a
20176 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010020177 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020178 backend queue unless a redispatch occurs.
20179
20180 - "backend_queue" is the total number of requests which were processed before
20181 this one in the backend's global queue. It is zero when the request has not
20182 gone through the global queue. It makes it possible to estimate the average
20183 queue length, which easily translates into a number of missing servers when
20184 divided by a server's "maxconn" parameter. It is worth noting that if a
20185 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010020186 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020187 through both the server queue and the backend queue unless a redispatch
20188 occurs.
20189
20190
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200201918.2.3. HTTP log format
20192----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020193
20194The HTTP format is the most complete and the best suited for HTTP proxies. It
20195is enabled by when "option httplog" is specified in the frontend. It provides
20196the same level of information as the TCP format with additional features which
20197are specific to the HTTP protocol. Just like the TCP format, the log is usually
20198emitted at the end of the session, unless "option logasap" is specified, which
20199generally only makes sense for download sites. A session which matches the
20200"monitor" rules will never logged. It is also possible not to log sessions for
20201which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020020202frontend. Successful connections will not be logged if "option dontlog-normal"
20203is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020204
20205Most fields are shared with the TCP log, some being different. A few fields may
20206slightly vary depending on some configuration options. Those ones are marked
20207with a star ('*') after the field name below.
20208
20209 Example :
20210 frontend http-in
20211 mode http
20212 option httplog
20213 log global
20214 default_backend bck
20215
20216 backend static
20217 server srv1 127.0.0.1:8000
20218
20219 >>> Feb 6 12:14:14 localhost \
20220 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
20221 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 +010020222 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020223
20224 Field Format Extract from the example above
20225 1 process_name '[' pid ']:' haproxy[14389]:
20226 2 client_ip ':' client_port 10.0.1.2:33317
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020227 3 '[' request_date ']' [06/Feb/2009:12:14:14.655]
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020228 4 frontend_name http-in
20229 5 backend_name '/' server_name static/srv1
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020230 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020231 7 status_code 200
20232 8 bytes_read* 2750
20233 9 captured_request_cookie -
20234 10 captured_response_cookie -
20235 11 termination_state ----
20236 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
20237 13 srv_queue '/' backend_queue 0/0
20238 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
20239 15 '{' captured_response_headers* '}' {}
20240 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010020241
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020242Detailed fields description :
20243 - "client_ip" is the IP address of the client which initiated the TCP
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020244 connection to HAProxy. If the connection was accepted on a UNIX socket
Willy Tarreauceb24bc2010-11-09 12:46:41 +010020245 instead, the IP address would be replaced with the word "unix". Note that
20246 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010020247 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010020248 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010020249 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020250
20251 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010020252 If the connection was accepted on a UNIX socket instead, the port would be
20253 replaced with the ID of the accepting socket, which is also reported in the
20254 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020255
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020256 - "request_date" is the exact date when the first byte of the HTTP request
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020257 was received by HAProxy (log field %tr).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020258
20259 - "frontend_name" is the name of the frontend (or listener) which received
20260 and processed the connection.
20261
20262 - "backend_name" is the name of the backend (or listener) which was selected
20263 to manage the connection to the server. This will be the same as the
20264 frontend if no switching rule has been applied.
20265
20266 - "server_name" is the name of the last server to which the connection was
20267 sent, which might differ from the first one if there were connection errors
20268 and a redispatch occurred. Note that this server belongs to the backend
20269 which processed the request. If the request was aborted before reaching a
20270 server, "<NOSRV>" is indicated instead of a server name. If the request was
20271 intercepted by the stats subsystem, "<STATS>" is indicated instead.
20272
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020273 - "TR" is the total time in milliseconds spent waiting for a full HTTP
20274 request from the client (not counting body) after the first byte was
20275 received. It can be "-1" if the connection was aborted before a complete
John Roeslerfb2fce12019-07-10 15:45:51 -050020276 request could be received or a bad request was received. It should
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020277 always be very small because a request generally fits in one single packet.
20278 Large times here generally indicate network issues between the client and
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020279 HAProxy or requests being typed by hand. See section 8.4 "Timing Events"
Willy Tarreau590a0512018-09-05 11:56:48 +020020280 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020281
20282 - "Tw" is the total time in milliseconds spent waiting in the various queues.
20283 It can be "-1" if the connection was aborted before reaching the queue.
Willy Tarreau590a0512018-09-05 11:56:48 +020020284 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020285
20286 - "Tc" is the total time in milliseconds spent waiting for the connection to
20287 establish to the final server, including retries. It can be "-1" if the
Willy Tarreau590a0512018-09-05 11:56:48 +020020288 request was aborted before a connection could be established. See section
20289 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020290
20291 - "Tr" is the total time in milliseconds spent waiting for the server to send
20292 a full HTTP response, not counting data. It can be "-1" if the request was
20293 aborted before a complete response could be received. It generally matches
20294 the server's processing time for the request, though it may be altered by
20295 the amount of data sent by the client to the server. Large times here on
Willy Tarreau590a0512018-09-05 11:56:48 +020020296 "GET" requests generally indicate an overloaded server. See section 8.4
20297 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020298
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020299 - "Ta" is the time the request remained active in HAProxy, which is the total
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020300 time in milliseconds elapsed between the first byte of the request was
20301 received and the last byte of response was sent. It covers all possible
20302 processing except the handshake (see Th) and idle time (see Ti). There is
20303 one exception, if "option logasap" was specified, then the time counting
20304 stops at the moment the log is emitted. In this case, a '+' sign is
20305 prepended before the value, indicating that the final one will be larger.
Willy Tarreau590a0512018-09-05 11:56:48 +020020306 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020307
20308 - "status_code" is the HTTP status code returned to the client. This status
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020309 is generally set by the server, but it might also be set by HAProxy when
20310 the server cannot be reached or when its response is blocked by HAProxy.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020311
20312 - "bytes_read" is the total number of bytes transmitted to the client when
20313 the log is emitted. This does include HTTP headers. If "option logasap" is
John Roeslerfb2fce12019-07-10 15:45:51 -050020314 specified, this value will be prefixed with a '+' sign indicating that
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020315 the final one may be larger. Please note that this value is a 64-bit
20316 counter, so log analysis tools must be able to handle it without
20317 overflowing.
20318
20319 - "captured_request_cookie" is an optional "name=value" entry indicating that
20320 the client had this cookie in the request. The cookie name and its maximum
20321 length are defined by the "capture cookie" statement in the frontend
20322 configuration. The field is a single dash ('-') when the option is not
20323 set. Only one cookie may be captured, it is generally used to track session
20324 ID exchanges between a client and a server to detect session crossing
20325 between clients due to application bugs. For more details, please consult
20326 the section "Capturing HTTP headers and cookies" below.
20327
20328 - "captured_response_cookie" is an optional "name=value" entry indicating
20329 that the server has returned a cookie with its response. The cookie name
20330 and its maximum length are defined by the "capture cookie" statement in the
20331 frontend configuration. The field is a single dash ('-') when the option is
20332 not set. Only one cookie may be captured, it is generally used to track
20333 session ID exchanges between a client and a server to detect session
20334 crossing between clients due to application bugs. For more details, please
20335 consult the section "Capturing HTTP headers and cookies" below.
20336
20337 - "termination_state" is the condition the session was in when the session
20338 ended. This indicates the session state, which side caused the end of
20339 session to happen, for what reason (timeout, error, ...), just like in TCP
20340 logs, and information about persistence operations on cookies in the last
20341 two characters. The normal flags should begin with "--", indicating the
20342 session was closed by either end with no data remaining in buffers. See
20343 below "Session state at disconnection" for more details.
20344
20345 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040020346 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020347 limits have been reached. For instance, if actconn is close to 512 or 1024
20348 when multiple connection errors occur, chances are high that the system
20349 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020020350 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020351 system.
20352
20353 - "feconn" is the total number of concurrent connections on the frontend when
20354 the session was logged. It is useful to estimate the amount of resource
20355 required to sustain high loads, and to detect when the frontend's "maxconn"
20356 has been reached. Most often when this value increases by huge jumps, it is
20357 because there is congestion on the backend servers, but sometimes it can be
20358 caused by a denial of service attack.
20359
20360 - "beconn" is the total number of concurrent connections handled by the
20361 backend when the session was logged. It includes the total number of
20362 concurrent connections active on servers as well as the number of
20363 connections pending in queues. It is useful to estimate the amount of
20364 additional servers needed to support high loads for a given application.
20365 Most often when this value increases by huge jumps, it is because there is
20366 congestion on the backend servers, but sometimes it can be caused by a
20367 denial of service attack.
20368
20369 - "srv_conn" is the total number of concurrent connections still active on
20370 the server when the session was logged. It can never exceed the server's
20371 configured "maxconn" parameter. If this value is very often close or equal
20372 to the server's "maxconn", it means that traffic regulation is involved a
20373 lot, meaning that either the server's maxconn value is too low, or that
20374 there aren't enough servers to process the load with an optimal response
20375 time. When only one of the server's "srv_conn" is high, it usually means
20376 that this server has some trouble causing the requests to take longer to be
20377 processed than on other servers.
20378
20379 - "retries" is the number of connection retries experienced by this session
20380 when trying to connect to the server. It must normally be zero, unless a
20381 server is being stopped at the same moment the connection was attempted.
20382 Frequent retries generally indicate either a network problem between
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020383 HAProxy and the server, or a misconfigured system backlog on the server
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020384 preventing new connections from being queued. This field may optionally be
20385 prefixed with a '+' sign, indicating that the session has experienced a
20386 redispatch after the maximal retry count has been reached on the initial
20387 server. In this case, the server name appearing in the log is the one the
20388 connection was redispatched to, and not the first one, though both may
20389 sometimes be the same in case of hashing for instance. So as a general rule
20390 of thumb, when a '+' is present in front of the retry count, this count
20391 should not be attributed to the logged server.
20392
20393 - "srv_queue" is the total number of requests which were processed before
20394 this one in the server queue. It is zero when the request has not gone
20395 through the server queue. It makes it possible to estimate the approximate
20396 server's response time by dividing the time spent in queue by the number of
20397 requests in the queue. It is worth noting that if a session experiences a
20398 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010020399 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020400 backend queue unless a redispatch occurs.
20401
20402 - "backend_queue" is the total number of requests which were processed before
20403 this one in the backend's global queue. It is zero when the request has not
20404 gone through the global queue. It makes it possible to estimate the average
20405 queue length, which easily translates into a number of missing servers when
20406 divided by a server's "maxconn" parameter. It is worth noting that if a
20407 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010020408 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020409 through both the server queue and the backend queue unless a redispatch
20410 occurs.
20411
20412 - "captured_request_headers" is a list of headers captured in the request due
20413 to the presence of the "capture request header" statement in the frontend.
20414 Multiple headers can be captured, they will be delimited by a vertical bar
20415 ('|'). When no capture is enabled, the braces do not appear, causing a
20416 shift of remaining fields. It is important to note that this field may
20417 contain spaces, and that using it requires a smarter log parser than when
20418 it's not used. Please consult the section "Capturing HTTP headers and
20419 cookies" below for more details.
20420
20421 - "captured_response_headers" is a list of headers captured in the response
20422 due to the presence of the "capture response header" statement in the
20423 frontend. Multiple headers can be captured, they will be delimited by a
20424 vertical bar ('|'). When no capture is enabled, the braces do not appear,
20425 causing a shift of remaining fields. It is important to note that this
20426 field may contain spaces, and that using it requires a smarter log parser
20427 than when it's not used. Please consult the section "Capturing HTTP headers
20428 and cookies" below for more details.
20429
20430 - "http_request" is the complete HTTP request line, including the method,
20431 request and HTTP version string. Non-printable characters are encoded (see
20432 below the section "Non-printable characters"). This is always the last
20433 field, and it is always delimited by quotes and is the only one which can
20434 contain quotes. If new fields are added to the log format, they will be
20435 added before this field. This field might be truncated if the request is
20436 huge and does not fit in the standard syslog buffer (1024 characters). This
20437 is the reason why this field must always remain the last one.
20438
20439
Cyril Bontédc4d9032012-04-08 21:57:39 +0200204408.2.4. Custom log format
20441------------------------
William Lallemand48940402012-01-30 16:47:22 +010020442
Willy Tarreau2beef582012-12-20 17:22:52 +010020443The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010020444mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010020445
Davor Ocelice9ed2812017-12-25 17:49:28 +010020446HAProxy understands some log format variables. % precedes log format variables.
William Lallemand48940402012-01-30 16:47:22 +010020447Variables can take arguments using braces ('{}'), and multiple arguments are
20448separated by commas within the braces. Flags may be added or removed by
20449prefixing them with a '+' or '-' sign.
20450
20451Special variable "%o" may be used to propagate its flags to all other
20452variables on the same format string. This is particularly handy with quoted
Dragan Dosen835b9212016-02-12 13:23:03 +010020453("Q") and escaped ("E") string formats.
William Lallemand48940402012-01-30 16:47:22 +010020454
Willy Tarreauc8368452012-12-21 00:09:23 +010020455If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020020456as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010020457less common information such as the client's SSL certificate's DN, or to log
20458the key that would be used to store an entry into a stick table.
20459
Dragan Dosen1e3b16f2020-06-23 18:16:44 +020020460Note: spaces must be escaped. In configuration directives "log-format",
20461"log-format-sd" and "unique-id-format", spaces are considered as
20462delimiters and are merged. In order to emit a verbatim '%', it must be
20463preceded by another '%' resulting in '%%'.
William Lallemand48940402012-01-30 16:47:22 +010020464
Dragan Dosen835b9212016-02-12 13:23:03 +010020465Note: when using the RFC5424 syslog message format, the characters '"',
20466'\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see
20467https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In
20468such cases, the use of the flag "E" should be considered.
20469
William Lallemand48940402012-01-30 16:47:22 +010020470Flags are :
20471 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040020472 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
Dragan Dosen835b9212016-02-12 13:23:03 +010020473 * E: escape characters '"', '\' and ']' in a string with '\' as prefix
20474 (intended purpose is for the RFC5424 structured-data log formats)
William Lallemand48940402012-01-30 16:47:22 +010020475
20476 Example:
20477
20478 log-format %T\ %t\ Some\ Text
20479 log-format %{+Q}o\ %t\ %s\ %{-Q}r
20480
Dragan Dosen835b9212016-02-12 13:23:03 +010020481 log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]
20482
William Lallemand48940402012-01-30 16:47:22 +010020483At the moment, the default HTTP format is defined this way :
20484
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020485 log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \
20486 %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"
William Lallemand48940402012-01-30 16:47:22 +010020487
William Lallemandbddd4fd2012-02-27 11:23:10 +010020488the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010020489
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020490 log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \
20491 %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \
20492 %bc %sc %rc %sq %bq %CC %CS %hrl %hsl"
William Lallemand48940402012-01-30 16:47:22 +010020493
William Lallemandbddd4fd2012-02-27 11:23:10 +010020494and the default TCP format is defined this way :
20495
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020496 log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \
20497 %ac/%fc/%bc/%sc/%rc %sq/%bq"
William Lallemandbddd4fd2012-02-27 11:23:10 +010020498
William Lallemand48940402012-01-30 16:47:22 +010020499Please refer to the table below for currently defined variables :
20500
William Lallemandbddd4fd2012-02-27 11:23:10 +010020501 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020020502 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020503 +---+------+-----------------------------------------------+-------------+
20504 | | %o | special variable, apply flags on all next var | |
20505 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010020506 | | %B | bytes_read (from server to client) | numeric |
20507 | H | %CC | captured_request_cookie | string |
20508 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020020509 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000020510 | H | %HM | HTTP method (ex: POST) | string |
Maciej Zdeb21acc332020-11-26 10:45:52 +000020511 | H | %HP | HTTP request URI without query string | string |
Maciej Zdebfcdfd852020-11-30 18:27:47 +000020512 | H | %HPO | HTTP path only (without host nor query string)| string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000020513 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000020514 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
20515 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010020516 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020020517 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020020518 | | %T | gmt_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020519 | | %Ta | Active time of the request (from TR to end) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020520 | | %Tc | Tc | numeric |
Willy Tarreau27b639d2016-05-17 17:55:27 +020020521 | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080020522 | | %Tl | local_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020523 | | %Th | connection handshake time (SSL, PROXY proto) | numeric |
20524 | H | %Ti | idle time before the HTTP request | numeric |
20525 | H | %Tq | Th + Ti + TR | numeric |
20526 | H | %TR | time to receive the full request from 1st byte| numeric |
20527 | H | %Tr | Tr (response time) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020020528 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020529 | | %Tt | Tt | numeric |
Damien Claisse57c8eb92020-04-28 12:09:19 +000020530 | | %Tu | Tu | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020531 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010020532 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020533 | | %ac | actconn | numeric |
20534 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010020535 | | %bc | beconn (backend concurrent connections) | numeric |
20536 | | %bi | backend_source_ip (connecting address) | IP |
20537 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020538 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010020539 | | %ci | client_ip (accepted address) | IP |
20540 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020541 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010020542 | | %fc | feconn (frontend concurrent connections) | numeric |
20543 | | %fi | frontend_ip (accepting address) | IP |
20544 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020020545 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020020546 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020020547 | | %hr | captured_request_headers default style | string |
20548 | | %hrl | captured_request_headers CLF style | string list |
20549 | | %hs | captured_response_headers default style | string |
20550 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020020551 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020020552 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020020553 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020554 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010020555 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020556 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010020557 | | %sc | srv_conn (server concurrent connections) | numeric |
20558 | | %si | server_IP (target address) | IP |
20559 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020560 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020020561 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
20562 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010020563 | | %t | date_time (with millisecond resolution) | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020564 | H | %tr | date_time of HTTP request | date |
20565 | H | %trg | gmt_date_time of start of HTTP request | date |
Jens Bissinger15c64ff2018-08-23 14:11:27 +020020566 | H | %trl | local_date_time of start of HTTP request | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020567 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020020568 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010020569 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010020570
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020020571 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010020572
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010020573
205748.2.5. Error log format
20575-----------------------
20576
20577When an incoming connection fails due to an SSL handshake or an invalid PROXY
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020578protocol header, HAProxy will log the event using a shorter, fixed line format.
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010020579By default, logs are emitted at the LOG_INFO level, unless the option
20580"log-separate-errors" is set in the backend, in which case the LOG_ERR level
Davor Ocelice9ed2812017-12-25 17:49:28 +010020581will be used. Connections on which no data are exchanged (e.g. probes) are not
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010020582logged if the "dontlognull" option is set.
20583
20584The format looks like this :
20585
20586 >>> Dec 3 18:27:14 localhost \
20587 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
20588 Connection error during SSL handshake
20589
20590 Field Format Extract from the example above
20591 1 process_name '[' pid ']:' haproxy[6103]:
20592 2 client_ip ':' client_port 127.0.0.1:56059
20593 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
20594 4 frontend_name "/" bind_name ":" frt/f1:
20595 5 message Connection error during SSL handshake
20596
20597These fields just provide minimal information to help debugging connection
20598failures.
20599
20600
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206018.3. Advanced logging options
20602-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020603
20604Some advanced logging options are often looked for but are not easy to find out
20605just by looking at the various options. Here is an entry point for the few
20606options which can enable better logging. Please refer to the keywords reference
20607for more information about their usage.
20608
20609
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206108.3.1. Disabling logging of external tests
20611------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020612
20613It is quite common to have some monitoring tools perform health checks on
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020614HAProxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020615commercial load-balancer, and sometimes it will simply be a more complete
20616monitoring system such as Nagios. When the tests are very frequent, users often
20617ask how to disable logging for those checks. There are three possibilities :
20618
20619 - if connections come from everywhere and are just TCP probes, it is often
20620 desired to simply disable logging of connections without data exchange, by
20621 setting "option dontlognull" in the frontend. It also disables logging of
20622 port scans, which may or may not be desired.
20623
Willy Tarreau9e9919d2020-10-14 15:55:23 +020020624 - it is possible to use the "http-request set-log-level silent" action using
20625 a variety of conditions (source networks, paths, user-agents, etc).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020626
20627 - if the tests are performed on a known URI, use "monitor-uri" to declare
20628 this URI as dedicated to monitoring. Any host sending this request will
20629 only get the result of a health-check, and the request will not be logged.
20630
20631
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206328.3.2. Logging before waiting for the session to terminate
20633----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020634
20635The problem with logging at end of connection is that you have no clue about
20636what is happening during very long sessions, such as remote terminal sessions
20637or large file downloads. This problem can be worked around by specifying
Davor Ocelice9ed2812017-12-25 17:49:28 +010020638"option logasap" in the frontend. HAProxy will then log as soon as possible,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020639just before data transfer begins. This means that in case of TCP, it will still
20640log the connection status to the server, and in case of HTTP, it will log just
20641after processing the server headers. In this case, the number of bytes reported
20642is the number of header bytes sent to the client. In order to avoid confusion
20643with normal logs, the total time field and the number of bytes are prefixed
20644with a '+' sign which means that real numbers are certainly larger.
20645
20646
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206478.3.3. Raising log level upon errors
20648------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020020649
20650Sometimes it is more convenient to separate normal traffic from errors logs,
20651for instance in order to ease error monitoring from log files. When the option
20652"log-separate-errors" is used, connections which experience errors, timeouts,
20653retries, redispatches or HTTP status codes 5xx will see their syslog level
20654raised from "info" to "err". This will help a syslog daemon store the log in
20655a separate file. It is very important to keep the errors in the normal traffic
20656file too, so that log ordering is not altered. You should also be careful if
20657you already have configured your syslog daemon to store all logs higher than
20658"notice" in an "admin" file, because the "err" level is higher than "notice".
20659
20660
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206618.3.4. Disabling logging of successful connections
20662--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020020663
20664Although this may sound strange at first, some large sites have to deal with
20665multiple thousands of logs per second and are experiencing difficulties keeping
20666them intact for a long time or detecting errors within them. If the option
20667"dontlog-normal" is set on the frontend, all normal connections will not be
20668logged. In this regard, a normal connection is defined as one without any
20669error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
20670and a response with a status 5xx is not considered normal and will be logged
20671too. Of course, doing is is really discouraged as it will remove most of the
20672useful information from the logs. Do this only if you have no other
20673alternative.
20674
20675
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206768.4. Timing events
20677------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020678
20679Timers provide a great help in troubleshooting network problems. All values are
20680reported in milliseconds (ms). These timers should be used in conjunction with
20681the session termination flags. In TCP mode with "option tcplog" set on the
20682frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020683mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In
20684addition, three other measures are provided, "Th", "Ti", and "Tq".
20685
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010020686Timings events in HTTP mode:
20687
20688 first request 2nd request
20689 |<-------------------------------->|<-------------- ...
20690 t tr t tr ...
20691 ---|----|----|----|----|----|----|----|----|--
20692 : Th Ti TR Tw Tc Tr Td : Ti ...
20693 :<---- Tq ---->: :
20694 :<-------------- Tt -------------->:
Damien Claisse57c8eb92020-04-28 12:09:19 +000020695 :<-- -----Tu--------------->:
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010020696 :<--------- Ta --------->:
20697
20698Timings events in TCP mode:
20699
20700 TCP session
20701 |<----------------->|
20702 t t
20703 ---|----|----|----|----|---
20704 | Th Tw Tc Td |
20705 |<------ Tt ------->|
20706
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020707 - Th: total time to accept tcp connection and execute handshakes for low level
Davor Ocelice9ed2812017-12-25 17:49:28 +010020708 protocols. Currently, these protocols are proxy-protocol and SSL. This may
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020709 only happen once during the whole connection's lifetime. A large time here
20710 may indicate that the client only pre-established the connection without
20711 speaking, that it is experiencing network issues preventing it from
Davor Ocelice9ed2812017-12-25 17:49:28 +010020712 completing a handshake in a reasonable time (e.g. MTU issues), or that an
Willy Tarreau590a0512018-09-05 11:56:48 +020020713 SSL handshake was very expensive to compute. Please note that this time is
20714 reported only before the first request, so it is safe to average it over
20715 all request to calculate the amortized value. The second and subsequent
20716 request will always report zero here.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020717
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020718 - Ti: is the idle time before the HTTP request (HTTP mode only). This timer
20719 counts between the end of the handshakes and the first byte of the HTTP
20720 request. When dealing with a second request in keep-alive mode, it starts
Willy Tarreau590a0512018-09-05 11:56:48 +020020721 to count after the end of the transmission the previous response. When a
20722 multiplexed protocol such as HTTP/2 is used, it starts to count immediately
20723 after the previous request. Some browsers pre-establish connections to a
20724 server in order to reduce the latency of a future request, and keep them
20725 pending until they need it. This delay will be reported as the idle time. A
20726 value of -1 indicates that nothing was received on the connection.
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020727
20728 - TR: total time to get the client request (HTTP mode only). It's the time
20729 elapsed between the first bytes received and the moment the proxy received
20730 the empty line marking the end of the HTTP headers. The value "-1"
20731 indicates that the end of headers has never been seen. This happens when
20732 the client closes prematurely or times out. This time is usually very short
20733 since most requests fit in a single packet. A large time may indicate a
20734 request typed by hand during a test.
20735
20736 - Tq: total time to get the client request from the accept date or since the
20737 emission of the last byte of the previous response (HTTP mode only). It's
Davor Ocelice9ed2812017-12-25 17:49:28 +010020738 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 +020020739 returns -1 as well. This timer used to be very useful before the arrival of
20740 HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop
20741 it in favor of TR nowadays, as the idle time adds a lot of noise to the
20742 reports.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020743
20744 - Tw: total time spent in the queues waiting for a connection slot. It
20745 accounts for backend queue as well as the server queues, and depends on the
20746 queue size, and the time needed for the server to complete previous
20747 requests. The value "-1" means that the request was killed before reaching
20748 the queue, which is generally what happens with invalid or denied requests.
20749
20750 - Tc: total time to establish the TCP connection to the server. It's the time
20751 elapsed between the moment the proxy sent the connection request, and the
20752 moment it was acknowledged by the server, or between the TCP SYN packet and
20753 the matching SYN/ACK packet in return. The value "-1" means that the
20754 connection never established.
20755
20756 - Tr: server response time (HTTP mode only). It's the time elapsed between
20757 the moment the TCP connection was established to the server and the moment
20758 the server sent its complete response headers. It purely shows its request
20759 processing time, without the network overhead due to the data transmission.
20760 It is worth noting that when the client has data to send to the server, for
20761 instance during a POST request, the time already runs, and this can distort
20762 apparent response time. For this reason, it's generally wise not to trust
20763 too much this field for POST requests initiated from clients behind an
20764 untrusted network. A value of "-1" here means that the last the response
20765 header (empty line) was never seen, most likely because the server timeout
20766 stroke before the server managed to process the request.
20767
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020768 - Ta: total active time for the HTTP request, between the moment the proxy
20769 received the first byte of the request header and the emission of the last
20770 byte of the response body. The exception is when the "logasap" option is
20771 specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with
20772 a '+' sign. From this field, we can deduce "Td", the data transmission time,
20773 by subtracting other timers when valid :
20774
20775 Td = Ta - (TR + Tw + Tc + Tr)
20776
20777 Timers with "-1" values have to be excluded from this equation. Note that
20778 "Ta" can never be negative.
20779
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020780 - Tt: total session duration time, between the moment the proxy accepted it
20781 and the moment both ends were closed. The exception is when the "logasap"
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020782 option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and
20783 is prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030020784 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020785
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020786 Td = Tt - (Th + Ti + TR + Tw + Tc + Tr)
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020787
20788 Timers with "-1" values have to be excluded from this equation. In TCP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020789 mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never
20790 be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020791
Damien Claisse57c8eb92020-04-28 12:09:19 +000020792 - Tu: total estimated time as seen from client, between the moment the proxy
20793 accepted it and the moment both ends were closed, without idle time.
20794 This is useful to roughly measure end-to-end time as a user would see it,
20795 without idle time pollution from keep-alive time between requests. This
20796 timer in only an estimation of time seen by user as it assumes network
20797 latency is the same in both directions. The exception is when the "logasap"
20798 option is specified. In this case, it only equals (Th+TR+Tw+Tc+Tr), and is
20799 prefixed with a '+' sign.
20800
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020801These timers provide precious indications on trouble causes. Since the TCP
20802protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
20803that timers close to multiples of 3s are nearly always related to lost packets
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020804due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or
20805"Tt" is close to a timeout value specified in the configuration, it often means
20806that a session has been aborted on timeout.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020807
20808Most common cases :
20809
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020810 - If "Th" or "Ti" are close to 3000, a packet has probably been lost between
20811 the client and the proxy. This is very rare on local networks but might
20812 happen when clients are on far remote networks and send large requests. It
20813 may happen that values larger than usual appear here without any network
20814 cause. Sometimes, during an attack or just after a resource starvation has
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020815 ended, HAProxy may accept thousands of connections in a few milliseconds.
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020816 The time spent accepting these connections will inevitably slightly delay
20817 processing of other connections, and it can happen that request times in the
20818 order of a few tens of milliseconds are measured after a few thousands of
20819 new connections have been accepted at once. Using one of the keep-alive
20820 modes may display larger idle times since "Ti" measures the time spent
Patrick Mezard105faca2010-06-12 17:02:46 +020020821 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020822
20823 - If "Tc" is close to 3000, a packet has probably been lost between the
20824 server and the proxy during the server connection phase. This value should
20825 always be very low, such as 1 ms on local networks and less than a few tens
20826 of ms on remote networks.
20827
Willy Tarreau55165fe2009-05-10 12:02:55 +020020828 - If "Tr" is nearly always lower than 3000 except some rare values which seem
20829 to be the average majored by 3000, there are probably some packets lost
20830 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020831
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020832 - If "Ta" is large even for small byte counts, it generally is because
20833 neither the client nor the server decides to close the connection while
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020834 HAProxy is running in tunnel mode and both have agreed on a keep-alive
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020835 connection mode. In order to solve this issue, it will be needed to specify
20836 one of the HTTP options to manipulate keep-alive or close options on either
20837 the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is
20838 important when connection regulation is used with the "maxconn" option on
20839 the servers, since no new connection will be sent to the server until
20840 another one is released.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020841
20842Other noticeable HTTP log cases ('xx' means any value to be ignored) :
20843
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020844 TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020845 was emitted before the data phase. All the timers are valid
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020846 except "Ta" which is shorter than reality.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020847
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020848 -1/xx/xx/xx/Ta The client was not able to send a complete request in time
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020849 or it aborted too early. Check the session termination flags
20850 then "timeout http-request" and "timeout client" settings.
20851
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020852 TR/-1/xx/xx/Ta It was not possible to process the request, maybe because
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020853 servers were out of order, because the request was invalid
20854 or forbidden by ACL rules. Check the session termination
20855 flags.
20856
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020857 TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it
20858 actively refused it or it timed out after Ta-(TR+Tw) ms.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020859 Check the session termination flags, then check the
20860 "timeout connect" setting. Note that the tarpit action might
20861 return similar-looking patterns, with "Tw" equal to the time
20862 the client connection was maintained open.
20863
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020864 TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030020865 a complete response in time, or it closed its connection
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020020866 unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020867 termination flags, then check the "timeout server" setting.
20868
20869
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200208708.5. Session state at disconnection
20871-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020872
20873TCP and HTTP logs provide a session termination indicator in the
20874"termination_state" field, just before the number of active connections. It is
208752-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
20876each of which has a special meaning :
20877
20878 - On the first character, a code reporting the first event which caused the
20879 session to terminate :
20880
20881 C : the TCP session was unexpectedly aborted by the client.
20882
20883 S : the TCP session was unexpectedly aborted by the server, or the
20884 server explicitly refused it.
20885
20886 P : the session was prematurely aborted by the proxy, because of a
20887 connection limit enforcement, because a DENY filter was matched,
20888 because of a security check which detected and blocked a dangerous
20889 error in server response which might have caused information leak
Davor Ocelice9ed2812017-12-25 17:49:28 +010020890 (e.g. cacheable cookie).
Willy Tarreau570f2212013-06-10 16:42:09 +020020891
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020892 L : the session was locally processed by HAProxy and was not passed to
Willy Tarreau570f2212013-06-10 16:42:09 +020020893 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020894
20895 R : a resource on the proxy has been exhausted (memory, sockets, source
20896 ports, ...). Usually, this appears during the connection phase, and
20897 system logs should contain a copy of the precise error. If this
20898 happens, it must be considered as a very serious anomaly which
20899 should be fixed as soon as possible by any means.
20900
20901 I : an internal error was identified by the proxy during a self-check.
20902 This should NEVER happen, and you are encouraged to report any log
20903 containing this, because this would almost certainly be a bug. It
20904 would be wise to preventively restart the process after such an
20905 event too, in case it would be caused by memory corruption.
20906
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020907 D : the session was killed by HAProxy because the server was detected
Simon Horman752dc4a2011-06-21 14:34:59 +090020908 as down and was configured to kill all connections when going down.
20909
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020910 U : the session was killed by HAProxy on this backup server because an
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070020911 active server was detected as up and was configured to kill all
20912 backup connections when going up.
20913
Daniel Corbett9f0843f2021-05-08 10:50:37 -040020914 K : the session was actively killed by an admin operating on HAProxy.
Willy Tarreaua2a64e92011-09-07 23:01:56 +020020915
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020916 c : the client-side timeout expired while waiting for the client to
20917 send or receive data.
20918
20919 s : the server-side timeout expired while waiting for the server to
20920 send or receive data.
20921
20922 - : normal session completion, both the client and the server closed
20923 with nothing left in the buffers.
20924
20925 - on the second character, the TCP or HTTP session state when it was closed :
20926
Willy Tarreauf7b30a92010-12-06 22:59:17 +010020927 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020928 (HTTP mode only). Nothing was sent to any server.
20929
20930 Q : the proxy was waiting in the QUEUE for a connection slot. This can
20931 only happen when servers have a 'maxconn' parameter set. It can
20932 also happen in the global queue after a redispatch consecutive to
20933 a failed attempt to connect to a dying server. If no redispatch is
20934 reported, then no connection attempt was made to any server.
20935
20936 C : the proxy was waiting for the CONNECTION to establish on the
20937 server. The server might at most have noticed a connection attempt.
20938
20939 H : the proxy was waiting for complete, valid response HEADERS from the
20940 server (HTTP only).
20941
20942 D : the session was in the DATA phase.
20943
20944 L : the proxy was still transmitting LAST data to the client while the
20945 server had already finished. This one is very rare as it can only
20946 happen when the client dies while receiving the last packets.
20947
20948 T : the request was tarpitted. It has been held open with the client
20949 during the whole "timeout tarpit" duration or until the client
20950 closed, both of which will be reported in the "Tw" timer.
20951
20952 - : normal session completion after end of data transfer.
20953
20954 - the third character tells whether the persistence cookie was provided by
20955 the client (only in HTTP mode) :
20956
20957 N : the client provided NO cookie. This is usually the case for new
20958 visitors, so counting the number of occurrences of this flag in the
20959 logs generally indicate a valid trend for the site frequentation.
20960
20961 I : the client provided an INVALID cookie matching no known server.
20962 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020020963 cookies between HTTP/HTTPS sites, persistence conditionally
20964 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020965
20966 D : the client provided a cookie designating a server which was DOWN,
20967 so either "option persist" was used and the client was sent to
20968 this server, or it was not set and the client was redispatched to
20969 another server.
20970
Willy Tarreau996a92c2010-10-13 19:30:47 +020020971 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020972 server.
20973
Willy Tarreau996a92c2010-10-13 19:30:47 +020020974 E : the client provided a valid cookie, but with a last date which was
20975 older than what is allowed by the "maxidle" cookie parameter, so
20976 the cookie is consider EXPIRED and is ignored. The request will be
20977 redispatched just as if there was no cookie.
20978
20979 O : the client provided a valid cookie, but with a first date which was
20980 older than what is allowed by the "maxlife" cookie parameter, so
20981 the cookie is consider too OLD and is ignored. The request will be
20982 redispatched just as if there was no cookie.
20983
Willy Tarreauc89ccb62012-04-05 21:18:22 +020020984 U : a cookie was present but was not used to select the server because
20985 some other server selection mechanism was used instead (typically a
20986 "use-server" rule).
20987
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020988 - : does not apply (no cookie set in configuration).
20989
20990 - the last character reports what operations were performed on the persistence
20991 cookie returned by the server (only in HTTP mode) :
20992
20993 N : NO cookie was provided by the server, and none was inserted either.
20994
20995 I : no cookie was provided by the server, and the proxy INSERTED one.
20996 Note that in "cookie insert" mode, if the server provides a cookie,
20997 it will still be overwritten and reported as "I" here.
20998
Willy Tarreau996a92c2010-10-13 19:30:47 +020020999 U : the proxy UPDATED the last date in the cookie that was presented by
21000 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030021001 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020021002 date indicated in the cookie. If any other change happens, such as
21003 a redispatch, then the cookie will be marked as inserted instead.
21004
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021005 P : a cookie was PROVIDED by the server and transmitted as-is.
21006
21007 R : the cookie provided by the server was REWRITTEN by the proxy, which
21008 happens in "cookie rewrite" or "cookie prefix" modes.
21009
21010 D : the cookie provided by the server was DELETED by the proxy.
21011
21012 - : does not apply (no cookie set in configuration).
21013
Willy Tarreau996a92c2010-10-13 19:30:47 +020021014The combination of the two first flags gives a lot of information about what
21015was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021016helpful to detect server saturation, network troubles, local system resource
21017starvation, attacks, etc...
21018
21019The most common termination flags combinations are indicated below. They are
21020alphabetically sorted, with the lowercase set just after the upper case for
21021easier finding and understanding.
21022
21023 Flags Reason
21024
21025 -- Normal termination.
21026
21027 CC The client aborted before the connection could be established to the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021028 server. This can happen when HAProxy tries to connect to a recently
21029 dead (or unchecked) server, and the client aborts while HAProxy is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021030 waiting for the server to respond or for "timeout connect" to expire.
21031
21032 CD The client unexpectedly aborted during data transfer. This can be
21033 caused by a browser crash, by an intermediate equipment between the
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021034 client and HAProxy which decided to actively break the connection,
21035 by network routing issues between the client and HAProxy, or by a
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021036 keep-alive session between the server and the client terminated first
21037 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010021038
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021039 cD The client did not send nor acknowledge any data for as long as the
21040 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020021041 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021042
21043 CH The client aborted while waiting for the server to start responding.
21044 It might be the server taking too long to respond or the client
21045 clicking the 'Stop' button too fast.
21046
21047 cH The "timeout client" stroke while waiting for client data during a
21048 POST request. This is sometimes caused by too large TCP MSS values
21049 for PPPoE networks which cannot transport full-sized packets. It can
21050 also happen when client timeout is smaller than server timeout and
21051 the server takes too long to respond.
21052
21053 CQ The client aborted while its session was queued, waiting for a server
21054 with enough empty slots to accept it. It might be that either all the
21055 servers were saturated or that the assigned server was taking too
21056 long a time to respond.
21057
21058 CR The client aborted before sending a full HTTP request. Most likely
21059 the request was typed by hand using a telnet client, and aborted
21060 too early. The HTTP status code is likely a 400 here. Sometimes this
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021061 might also be caused by an IDS killing the connection between HAProxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020021062 and the client. "option http-ignore-probes" can be used to ignore
21063 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021064
21065 cR The "timeout http-request" stroke before the client sent a full HTTP
21066 request. This is sometimes caused by too large TCP MSS values on the
21067 client side for PPPoE networks which cannot transport full-sized
21068 packets, or by clients sending requests by hand and not typing fast
21069 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020021070 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020021071 some browsers started to implement a "pre-connect" feature consisting
21072 in speculatively connecting to some recently visited web sites just
21073 in case the user would like to visit them. This results in many
21074 connections being established to web sites, which end up in 408
21075 Request Timeout if the timeout strikes first, or 400 Bad Request when
21076 the browser decides to close them first. These ones pollute the log
21077 and feed the error counters. Some versions of some browsers have even
21078 been reported to display the error code. It is possible to work
Davor Ocelice9ed2812017-12-25 17:49:28 +010021079 around the undesirable effects of this behavior by adding "option
Willy Tarreau0f228a02015-05-01 15:37:53 +020021080 http-ignore-probes" in the frontend, resulting in connections with
21081 zero data transfer to be totally ignored. This will definitely hide
21082 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021083
21084 CT The client aborted while its session was tarpitted. It is important to
21085 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020021086 wrong tarpit rules have been written. If a lot of them happen, it
21087 might make sense to lower the "timeout tarpit" value to something
21088 closer to the average reported "Tw" timer, in order not to consume
21089 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021090
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021091 LR The request was intercepted and locally handled by HAProxy. Generally
Willy Tarreau570f2212013-06-10 16:42:09 +020021092 it means that this was a redirect or a stats request.
21093
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021094 SC The server or an equipment between it and HAProxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021095 the TCP connection (the proxy received a TCP RST or an ICMP message
21096 in return). Under some circumstances, it can also be the network
Davor Ocelice9ed2812017-12-25 17:49:28 +010021097 stack telling the proxy that the server is unreachable (e.g. no route,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021098 or no ARP response on local network). When this happens in HTTP mode,
21099 the status code is likely a 502 or 503 here.
21100
21101 sC The "timeout connect" stroke before a connection to the server could
21102 complete. When this happens in HTTP mode, the status code is likely a
21103 503 or 504 here.
21104
21105 SD The connection to the server died with an error during the data
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021106 transfer. This usually means that HAProxy has received an RST from
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021107 the server or an ICMP message from an intermediate equipment while
21108 exchanging data with the server. This can be caused by a server crash
21109 or by a network issue on an intermediate equipment.
21110
21111 sD The server did not send nor acknowledge any data for as long as the
21112 "timeout server" setting during the data phase. This is often caused
Davor Ocelice9ed2812017-12-25 17:49:28 +010021113 by too short timeouts on L4 equipment before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021114 load-balancers, ...), as well as keep-alive sessions maintained
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021115 between the client and the server expiring first on HAProxy.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021116
21117 SH The server aborted before sending its full HTTP response headers, or
21118 it crashed while processing the request. Since a server aborting at
21119 this moment is very rare, it would be wise to inspect its logs to
21120 control whether it crashed and why. The logged request may indicate a
21121 small set of faulty requests, demonstrating bugs in the application.
21122 Sometimes this might also be caused by an IDS killing the connection
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021123 between HAProxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021124
21125 sH The "timeout server" stroke before the server could return its
21126 response headers. This is the most common anomaly, indicating too
21127 long transactions, probably caused by server or database saturation.
21128 The immediate workaround consists in increasing the "timeout server"
21129 setting, but it is important to keep in mind that the user experience
21130 will suffer from these long response times. The only long term
21131 solution is to fix the application.
21132
21133 sQ The session spent too much time in queue and has been expired. See
21134 the "timeout queue" and "timeout connect" settings to find out how to
21135 fix this if it happens too often. If it often happens massively in
21136 short periods, it may indicate general problems on the affected
21137 servers due to I/O or database congestion, or saturation caused by
21138 external attacks.
21139
21140 PC The proxy refused to establish a connection to the server because the
Thayne McCombscdbcca92021-01-07 21:24:41 -070021141 process's socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020021142 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021143 so that it does not happen anymore. This status is very rare and
21144 might happen when the global "ulimit-n" parameter is forced by hand.
21145
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010021146 PD The proxy blocked an incorrectly formatted chunked encoded message in
21147 a request or a response, after the server has emitted its headers. In
21148 most cases, this will indicate an invalid message from the server to
Davor Ocelice9ed2812017-12-25 17:49:28 +010021149 the client. HAProxy supports chunk sizes of up to 2GB - 1 (2147483647
Willy Tarreauf3a3e132013-08-31 08:16:26 +020021150 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010021151
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021152 PH The proxy blocked the server's response, because it was invalid,
21153 incomplete, dangerous (cache control), or matched a security filter.
21154 In any case, an HTTP 502 error is sent to the client. One possible
21155 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010021156 containing unauthorized characters. It is also possible but quite
21157 rare, that the proxy blocked a chunked-encoding request from the
21158 client due to an invalid syntax, before the server responded. In this
21159 case, an HTTP 400 error is sent to the client and reported in the
21160 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021161
21162 PR The proxy blocked the client's HTTP request, either because of an
21163 invalid HTTP syntax, in which case it returned an HTTP 400 error to
21164 the client, or because a deny filter matched, in which case it
21165 returned an HTTP 403 error.
21166
21167 PT The proxy blocked the client's request and has tarpitted its
21168 connection before returning it a 500 server error. Nothing was sent
21169 to the server. The connection was maintained open for as long as
21170 reported by the "Tw" timer field.
21171
21172 RC A local resource has been exhausted (memory, sockets, source ports)
21173 preventing the connection to the server from establishing. The error
21174 logs will tell precisely what was missing. This is very rare and can
21175 only be solved by proper system tuning.
21176
Willy Tarreau996a92c2010-10-13 19:30:47 +020021177The combination of the two last flags gives a lot of information about how
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021178persistence was handled by the client, the server and by HAProxy. This is very
Willy Tarreau996a92c2010-10-13 19:30:47 +020021179important to troubleshoot disconnections, when users complain they have to
21180re-authenticate. The commonly encountered flags are :
21181
21182 -- Persistence cookie is not enabled.
21183
21184 NN No cookie was provided by the client, none was inserted in the
21185 response. For instance, this can be in insert mode with "postonly"
21186 set on a GET request.
21187
21188 II A cookie designating an invalid server was provided by the client,
21189 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040021190 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020021191 value can be presented by a client when no other server knows it.
21192
21193 NI No cookie was provided by the client, one was inserted in the
21194 response. This typically happens for first requests from every user
21195 in "insert" mode, which makes it an easy way to count real users.
21196
21197 VN A cookie was provided by the client, none was inserted in the
21198 response. This happens for most responses for which the client has
21199 already got a cookie.
21200
21201 VU A cookie was provided by the client, with a last visit date which is
21202 not completely up-to-date, so an updated cookie was provided in
21203 response. This can also happen if there was no date at all, or if
21204 there was a date but the "maxidle" parameter was not set, so that the
21205 cookie can be switched to unlimited time.
21206
21207 EI A cookie was provided by the client, with a last visit date which is
21208 too old for the "maxidle" parameter, so the cookie was ignored and a
21209 new cookie was inserted in the response.
21210
21211 OI A cookie was provided by the client, with a first visit date which is
21212 too old for the "maxlife" parameter, so the cookie was ignored and a
21213 new cookie was inserted in the response.
21214
21215 DI The server designated by the cookie was down, a new server was
21216 selected and a new cookie was emitted in the response.
21217
21218 VI The server designated by the cookie was not marked dead but could not
21219 be reached. A redispatch happened and selected another one, which was
21220 then advertised in the response.
21221
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021222
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200212238.6. Non-printable characters
21224-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021225
21226In order not to cause trouble to log analysis tools or terminals during log
21227consulting, non-printable characters are not sent as-is into log files, but are
21228converted to the two-digits hexadecimal representation of their ASCII code,
21229prefixed by the character '#'. The only characters that can be logged without
21230being escaped are comprised between 32 and 126 (inclusive). Obviously, the
21231escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
21232is the same for the character '"' which becomes "#22", as well as '{', '|' and
21233'}' when logging headers.
21234
21235Note that the space character (' ') is not encoded in headers, which can cause
21236issues for tools relying on space count to locate fields. A typical header
21237containing spaces is "User-Agent".
21238
21239Last, it has been observed that some syslog daemons such as syslog-ng escape
21240the quote ('"') with a backslash ('\'). The reverse operation can safely be
21241performed since no quote may appear anywhere else in the logs.
21242
21243
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200212448.7. Capturing HTTP cookies
21245---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021246
21247Cookie capture simplifies the tracking a complete user session. This can be
21248achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020021249section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021250cookie will simultaneously be checked in the request ("Cookie:" header) and in
21251the response ("Set-Cookie:" header). The respective values will be reported in
21252the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020021253locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021254not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
21255user switches to a new session for example, because the server will reassign it
21256a new cookie. It is also possible to detect if a server unexpectedly sets a
21257wrong cookie to a client, leading to session crossing.
21258
21259 Examples :
21260 # capture the first cookie whose name starts with "ASPSESSION"
21261 capture cookie ASPSESSION len 32
21262
21263 # capture the first cookie whose name is exactly "vgnvisitor"
21264 capture cookie vgnvisitor= len 32
21265
21266
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200212678.8. Capturing HTTP headers
21268---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021269
21270Header captures are useful to track unique request identifiers set by an upper
21271proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
21272the response, one can search for information about the response length, how the
21273server asked the cache to behave, or an object location during a redirection.
21274
21275Header captures are performed using the "capture request header" and "capture
21276response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020021277section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021278
21279It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010021280time. Non-existent headers are logged as empty strings, and if one header
21281appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021282are grouped within braces '{' and '}' in the same order as they were declared,
21283and delimited with a vertical bar '|' without any space. Response headers
21284follow the same representation, but are displayed after a space following the
21285request headers block. These blocks are displayed just before the HTTP request
21286in the logs.
21287
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020021288As a special case, it is possible to specify an HTTP header capture in a TCP
21289frontend. The purpose is to enable logging of headers which will be parsed in
21290an HTTP backend if the request is then switched to this HTTP backend.
21291
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021292 Example :
21293 # This instance chains to the outgoing proxy
21294 listen proxy-out
21295 mode http
21296 option httplog
21297 option logasap
21298 log global
21299 server cache1 192.168.1.1:3128
21300
21301 # log the name of the virtual server
21302 capture request header Host len 20
21303
21304 # log the amount of data uploaded during a POST
21305 capture request header Content-Length len 10
21306
21307 # log the beginning of the referrer
21308 capture request header Referer len 20
21309
21310 # server name (useful for outgoing proxies only)
21311 capture response header Server len 20
21312
21313 # logging the content-length is useful with "option logasap"
21314 capture response header Content-Length len 10
21315
Davor Ocelice9ed2812017-12-25 17:49:28 +010021316 # log the expected cache behavior on the response
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021317 capture response header Cache-Control len 8
21318
21319 # the Via header will report the next proxy's name
21320 capture response header Via len 20
21321
21322 # log the URL location during a redirection
21323 capture response header Location len 20
21324
21325 >>> Aug 9 20:26:09 localhost \
21326 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
21327 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
21328 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
21329 "GET http://fr.adserver.yahoo.com/"
21330
21331 >>> Aug 9 20:30:46 localhost \
21332 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
21333 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
21334 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010021335 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021336
21337 >>> Aug 9 20:30:46 localhost \
21338 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
21339 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
21340 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
21341 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010021342 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021343
21344
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200213458.9. Examples of logs
21346---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021347
21348These are real-world examples of logs accompanied with an explanation. Some of
21349them have been made up by hand. The syslog part has been removed for better
21350reading. Their sole purpose is to explain how to decipher them.
21351
21352 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
21353 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
21354 "HEAD / HTTP/1.0"
21355
21356 => long request (6.5s) entered by hand through 'telnet'. The server replied
21357 in 147 ms, and the session ended normally ('----')
21358
21359 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
21360 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
21361 0/9 "HEAD / HTTP/1.0"
21362
21363 => Idem, but the request was queued in the global queue behind 9 other
21364 requests, and waited there for 1230 ms.
21365
21366 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
21367 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
21368 "GET /image.iso HTTP/1.0"
21369
21370 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010021371 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021372 14 ms, 243 bytes of headers were sent to the client, and total time from
21373 accept to first data byte is 30 ms.
21374
21375 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
21376 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
21377 "GET /cgi-bin/bug.cgi? HTTP/1.0"
21378
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020021379 => the proxy blocked a server response either because of an "http-response
21380 deny" rule, or because the response was improperly formatted and not
21381 HTTP-compliant, or because it blocked sensitive information which risked
21382 being cached. In this case, the response is replaced with a "502 bad
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021383 gateway". The flags ("PH--") tell us that it was HAProxy who decided to
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020021384 return the 502 and not the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021385
21386 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010021387 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 +010021388
21389 => the client never completed its request and aborted itself ("C---") after
21390 8.5s, while the proxy was waiting for the request headers ("-R--").
21391 Nothing was sent to any server.
21392
21393 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
21394 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
21395
21396 => The client never completed its request, which was aborted by the
21397 time-out ("c---") after 50s, while the proxy was waiting for the request
Davor Ocelice9ed2812017-12-25 17:49:28 +010021398 headers ("-R--"). Nothing was sent to any server, but the proxy could
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021399 send a 408 return code to the client.
21400
21401 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
21402 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
21403
21404 => This log was produced with "option tcplog". The client timed out after
21405 5 seconds ("c----").
21406
21407 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
21408 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010021409 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021410
21411 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020021412 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010021413 (config says 'retries 3'), and no redispatch (otherwise we would have
21414 seen "/+3"). Status code 503 was returned to the client. There were 115
21415 connections on this server, 202 connections on this proxy, and 205 on
21416 the global process. It is possible that the server refused the
21417 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010021418
Willy Tarreau52b2d222011-09-07 23:48:48 +020021419
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200214209. Supported filters
21421--------------------
21422
21423Here are listed officially supported filters with the list of parameters they
21424accept. Depending on compile options, some of these filters might be
21425unavailable. The list of available filters is reported in haproxy -vv.
21426
21427See also : "filter"
21428
214299.1. Trace
21430----------
21431
Christopher Fauletc41d8bd2020-11-17 10:43:26 +010021432filter trace [name <name>] [random-forwarding] [hexdump]
Christopher Fauletc3fe5332016-04-07 15:30:10 +020021433
21434 Arguments:
21435 <name> is an arbitrary name that will be reported in
21436 messages. If no name is provided, "TRACE" is used.
21437
Christopher Faulet96a577a2020-11-17 10:45:05 +010021438 <quiet> inhibits trace messages.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020021439
Davor Ocelice9ed2812017-12-25 17:49:28 +010021440 <random-forwarding> enables the random forwarding of parsed data. By
Christopher Fauletc3fe5332016-04-07 15:30:10 +020021441 default, this filter forwards all previously parsed
21442 data. With this parameter, it only forwards a random
21443 amount of the parsed data.
21444
Davor Ocelice9ed2812017-12-25 17:49:28 +010021445 <hexdump> dumps all forwarded data to the server and the client.
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010021446
Christopher Fauletc3fe5332016-04-07 15:30:10 +020021447This filter can be used as a base to develop new filters. It defines all
21448callbacks and print a message on the standard error stream (stderr) with useful
21449information for all of them. It may be useful to debug the activity of other
21450filters or, quite simply, HAProxy's activity.
21451
21452Using <random-parsing> and/or <random-forwarding> parameters is a good way to
21453tests the behavior of a filter that parses data exchanged between a client and
21454a server by adding some latencies in the processing.
21455
21456
214579.2. HTTP compression
21458---------------------
21459
21460filter compression
21461
21462The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
21463keyword must still be used to enable and configure the HTTP compression. And
Christopher Fauletb30b3102019-09-12 23:03:09 +020021464when no other filter is used, it is enough. When used with the cache or the
21465fcgi-app enabled, it is also enough. In this case, the compression is always
21466done after the response is stored in the cache. But it is mandatory to
21467explicitly use a filter line to enable the HTTP compression when at least one
21468filter other than the cache or the fcgi-app is used for the same
21469listener/frontend/backend. This is important to know the filters evaluation
21470order.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020021471
Christopher Fauletb30b3102019-09-12 23:03:09 +020021472See also : "compression", section 9.4 about the cache filter and section 9.5
21473 about the fcgi-app filter.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020021474
21475
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200214769.3. Stream Processing Offload Engine (SPOE)
21477--------------------------------------------
21478
21479filter spoe [engine <name>] config <file>
21480
21481 Arguments :
21482
21483 <name> is the engine name that will be used to find the right scope in
21484 the configuration file. If not provided, all the file will be
21485 parsed.
21486
21487 <file> is the path of the engine configuration file. This file can
21488 contain configuration of several engines. In this case, each
21489 part must be placed in its own scope.
21490
21491The Stream Processing Offload Engine (SPOE) is a filter communicating with
21492external components. It allows the offload of some specifics processing on the
Davor Ocelice9ed2812017-12-25 17:49:28 +010021493streams in tiered applications. These external components and information
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020021494exchanged with them are configured in dedicated files, for the main part. It
21495also requires dedicated backends, defined in HAProxy configuration.
21496
21497SPOE communicates with external components using an in-house binary protocol,
21498the Stream Processing Offload Protocol (SPOP).
21499
Tim Düsterhus4896c442016-11-29 02:15:19 +010021500For all information about the SPOE configuration and the SPOP specification, see
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020021501"doc/SPOE.txt".
21502
Christopher Faulet99a17a22018-12-11 09:18:27 +0100215039.4. Cache
21504----------
21505
21506filter cache <name>
21507
21508 Arguments :
21509
21510 <name> is name of the cache section this filter will use.
21511
21512The cache uses a filter to store cacheable responses. The HTTP rules
21513"cache-store" and "cache-use" must be used to define how and when to use a
John Roeslerfb2fce12019-07-10 15:45:51 -050021514cache. By default the corresponding filter is implicitly defined. And when no
Christopher Fauletb30b3102019-09-12 23:03:09 +020021515other filters than fcgi-app or compression are used, it is enough. In such
21516case, the compression filter is always evaluated after the cache filter. But it
21517is mandatory to explicitly use a filter line to use a cache when at least one
21518filter other than the compression or the fcgi-app is used for the same
Christopher Faulet27d93c32018-12-15 22:32:02 +010021519listener/frontend/backend. This is important to know the filters evaluation
21520order.
Christopher Faulet99a17a22018-12-11 09:18:27 +010021521
Christopher Fauletb30b3102019-09-12 23:03:09 +020021522See also : section 9.2 about the compression filter, section 9.5 about the
21523 fcgi-app filter and section 6 about cache.
21524
21525
215269.5. Fcgi-app
21527-------------
21528
Daniel Corbett67a82712020-07-06 23:01:19 -040021529filter fcgi-app <name>
Christopher Fauletb30b3102019-09-12 23:03:09 +020021530
21531 Arguments :
21532
21533 <name> is name of the fcgi-app section this filter will use.
21534
21535The FastCGI application uses a filter to evaluate all custom parameters on the
21536request path, and to process the headers on the response path. the <name> must
21537reference an existing fcgi-app section. The directive "use-fcgi-app" should be
21538used to define the application to use. By default the corresponding filter is
21539implicitly defined. And when no other filters than cache or compression are
21540used, it is enough. But it is mandatory to explicitly use a filter line to a
21541fcgi-app when at least one filter other than the compression or the cache is
21542used for the same backend. This is important to know the filters evaluation
21543order.
21544
21545See also: "use-fcgi-app", section 9.2 about the compression filter, section 9.4
21546 about the cache filter and section 10 about FastCGI application.
21547
21548
Miroslav Zagoracdc32cd92020-12-13 18:32:57 +0100215499.6. OpenTracing
21550----------------
21551
21552The OpenTracing filter adds native support for using distributed tracing in
21553HAProxy. This is enabled by sending an OpenTracing compliant request to one
21554of the supported tracers such as Datadog, Jaeger, Lightstep and Zipkin tracers.
21555Please note: tracers are not listed by any preference, but alphabetically.
21556
Daniel Corbett9f0843f2021-05-08 10:50:37 -040021557This feature is only enabled when HAProxy was built with USE_OT=1.
Miroslav Zagoracdc32cd92020-12-13 18:32:57 +010021558
21559The OpenTracing filter activation is done explicitly by specifying it in the
21560HAProxy configuration. If this is not done, the OpenTracing filter in no way
21561participates in the work of HAProxy.
21562
21563filter opentracing [id <id>] config <file>
21564
21565 Arguments :
21566
21567 <id> is the OpenTracing filter id that will be used to find the
21568 right scope in the configuration file. If no filter id is
21569 specified, 'ot-filter' is used as default. If scope is not
21570 specified in the configuration file, it applies to all defined
21571 OpenTracing filters.
21572
21573 <file> is the path of the OpenTracing configuration file. The same
21574 file can contain configurations for multiple OpenTracing
21575 filters simultaneously. In that case we do not need to define
21576 scope so the same configuration applies to all filters or each
21577 filter must have its own scope defined.
21578
21579More detailed documentation related to the operation, configuration and use
Willy Tarreaua63d1a02021-04-02 17:16:46 +020021580of the filter can be found in the addons/ot directory.
Miroslav Zagoracdc32cd92020-12-13 18:32:57 +010021581
21582
Christopher Fauletb30b3102019-09-12 23:03:09 +02002158310. FastCGI applications
21584-------------------------
21585
21586HAProxy is able to send HTTP requests to Responder FastCGI applications. This
21587feature was added in HAProxy 2.1. To do so, servers must be configured to use
21588the FastCGI protocol (using the keyword "proto fcgi" on the server line) and a
21589FastCGI application must be configured and used by the backend managing these
21590servers (using the keyword "use-fcgi-app" into the proxy section). Several
21591FastCGI applications may be defined, but only one can be used at a time by a
21592backend.
21593
21594HAProxy implements all features of the FastCGI specification for Responder
21595application. Especially it is able to multiplex several requests on a simple
21596connection.
21597
2159810.1. Setup
21599-----------
21600
2160110.1.1. Fcgi-app section
21602--------------------------
21603
21604fcgi-app <name>
21605 Declare a FastCGI application named <name>. To be valid, at least the
21606 document root must be defined.
21607
21608acl <aclname> <criterion> [flags] [operator] <value> ...
21609 Declare or complete an access list.
21610
21611 See "acl" keyword in section 4.2 and section 7 about ACL usage for
21612 details. ACLs defined for a FastCGI application are private. They cannot be
21613 used by any other application or by any proxy. In the same way, ACLs defined
21614 in any other section are not usable by a FastCGI application. However,
21615 Pre-defined ACLs are available.
21616
21617docroot <path>
21618 Define the document root on the remote host. <path> will be used to build
21619 the default value of FastCGI parameters SCRIPT_FILENAME and
21620 PATH_TRANSLATED. It is a mandatory setting.
21621
21622index <script-name>
21623 Define the script name that will be appended after an URI that ends with a
21624 slash ("/") to set the default value of the FastCGI parameter SCRIPT_NAME. It
21625 is an optional setting.
21626
21627 Example :
21628 index index.php
21629
21630log-stderr global
21631log-stderr <address> [len <length>] [format <format>]
Jan Wagner3e678602020-12-17 22:22:32 +010021632 [sample <ranges>:<sample_size>] <facility> [<level> [<minlevel>]]
Christopher Fauletb30b3102019-09-12 23:03:09 +020021633 Enable logging of STDERR messages reported by the FastCGI application.
21634
21635 See "log" keyword in section 4.2 for details. It is an optional setting. By
21636 default STDERR messages are ignored.
21637
21638pass-header <name> [ { if | unless } <condition> ]
21639 Specify the name of a request header which will be passed to the FastCGI
21640 application. It may optionally be followed by an ACL-based condition, in
21641 which case it will only be evaluated if the condition is true.
21642
21643 Most request headers are already available to the FastCGI application,
21644 prefixed with "HTTP_". Thus, this directive is only required to pass headers
21645 that are purposefully omitted. Currently, the headers "Authorization",
21646 "Proxy-Authorization" and hop-by-hop headers are omitted.
21647
21648 Note that the headers "Content-type" and "Content-length" are never passed to
21649 the FastCGI application because they are already converted into parameters.
21650
21651path-info <regex>
Christopher Faulet28cb3662020-02-14 14:47:37 +010021652 Define a regular expression to extract the script-name and the path-info from
Christopher Faulet6c57f2d2020-02-14 16:55:52 +010021653 the URL-decoded path. Thus, <regex> may have two captures: the first one to
21654 capture the script name and the second one to capture the path-info. The
21655 first one is mandatory, the second one is optional. This way, it is possible
21656 to extract the script-name from the path ignoring the path-info. It is an
21657 optional setting. If it is not defined, no matching is performed on the
21658 path. and the FastCGI parameters PATH_INFO and PATH_TRANSLATED are not
21659 filled.
Christopher Faulet28cb3662020-02-14 14:47:37 +010021660
21661 For security reason, when this regular expression is defined, the newline and
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050021662 the null characters are forbidden from the path, once URL-decoded. The reason
Christopher Faulet28cb3662020-02-14 14:47:37 +010021663 to such limitation is because otherwise the matching always fails (due to a
21664 limitation one the way regular expression are executed in HAProxy). So if one
21665 of these two characters is found in the URL-decoded path, an error is
21666 returned to the client. The principle of least astonishment is applied here.
Christopher Fauletb30b3102019-09-12 23:03:09 +020021667
21668 Example :
Christopher Faulet6c57f2d2020-02-14 16:55:52 +010021669 path-info ^(/.+\.php)(/.*)?$ # both script-name and path-info may be set
21670 path-info ^(/.+\.php) # the path-info is ignored
Christopher Fauletb30b3102019-09-12 23:03:09 +020021671
21672option get-values
21673no option get-values
21674 Enable or disable the retrieve of variables about connection management.
21675
Daniel Corbett67a82712020-07-06 23:01:19 -040021676 HAProxy is able to send the record FCGI_GET_VALUES on connection
Christopher Fauletb30b3102019-09-12 23:03:09 +020021677 establishment to retrieve the value for following variables:
21678
21679 * FCGI_MAX_REQS The maximum number of concurrent requests this
21680 application will accept.
21681
William Lallemand93e548e2019-09-30 13:54:02 +020021682 * FCGI_MPXS_CONNS "0" if this application does not multiplex connections,
21683 "1" otherwise.
Christopher Fauletb30b3102019-09-12 23:03:09 +020021684
21685 Some FastCGI applications does not support this feature. Some others close
Ilya Shipitsin11057a32020-06-21 21:18:27 +050021686 the connection immediately after sending their response. So, by default, this
Christopher Fauletb30b3102019-09-12 23:03:09 +020021687 option is disabled.
21688
21689 Note that the maximum number of concurrent requests accepted by a FastCGI
21690 application is a connection variable. It only limits the number of streams
21691 per connection. If the global load must be limited on the application, the
21692 server parameters "maxconn" and "pool-max-conn" must be set. In addition, if
21693 an application does not support connection multiplexing, the maximum number
21694 of concurrent requests is automatically set to 1.
21695
21696option keep-conn
21697no option keep-conn
21698 Instruct the FastCGI application to keep the connection open or not after
21699 sending a response.
21700
21701 If disabled, the FastCGI application closes the connection after responding
21702 to this request. By default, this option is enabled.
21703
21704option max-reqs <reqs>
21705 Define the maximum number of concurrent requests this application will
21706 accept.
21707
21708 This option may be overwritten if the variable FCGI_MAX_REQS is retrieved
21709 during connection establishment. Furthermore, if the application does not
21710 support connection multiplexing, this option will be ignored. By default set
21711 to 1.
21712
21713option mpxs-conns
21714no option mpxs-conns
21715 Enable or disable the support of connection multiplexing.
21716
21717 This option may be overwritten if the variable FCGI_MPXS_CONNS is retrieved
21718 during connection establishment. It is disabled by default.
21719
21720set-param <name> <fmt> [ { if | unless } <condition> ]
21721 Set a FastCGI parameter that should be passed to this application. Its
21722 value, defined by <fmt> must follows the log-format rules (see section 8.2.4
21723 "Custom Log format"). It may optionally be followed by an ACL-based
21724 condition, in which case it will only be evaluated if the condition is true.
21725
21726 With this directive, it is possible to overwrite the value of default FastCGI
21727 parameters. If the value is evaluated to an empty string, the rule is
21728 ignored. These directives are evaluated in their declaration order.
21729
21730 Example :
21731 # PHP only, required if PHP was built with --enable-force-cgi-redirect
21732 set-param REDIRECT_STATUS 200
21733
21734 set-param PHP_AUTH_DIGEST %[req.hdr(Authorization)]
21735
21736
2173710.1.2. Proxy section
21738---------------------
21739
21740use-fcgi-app <name>
21741 Define the FastCGI application to use for the backend.
21742
21743 Arguments :
21744 <name> is the name of the FastCGI application to use.
21745
21746 This keyword is only available for HTTP proxies with the backend capability
21747 and with at least one FastCGI server. However, FastCGI servers can be mixed
21748 with HTTP servers. But except there is a good reason to do so, it is not
21749 recommended (see section 10.3 about the limitations for details). Only one
21750 application may be defined at a time per backend.
21751
21752 Note that, once a FastCGI application is referenced for a backend, depending
21753 on the configuration some processing may be done even if the request is not
21754 sent to a FastCGI server. Rules to set parameters or pass headers to an
21755 application are evaluated.
21756
21757
2175810.1.3. Example
21759---------------
21760
21761 frontend front-http
21762 mode http
21763 bind *:80
21764 bind *:
21765
21766 use_backend back-dynamic if { path_reg ^/.+\.php(/.*)?$ }
21767 default_backend back-static
21768
21769 backend back-static
21770 mode http
21771 server www A.B.C.D:80
21772
21773 backend back-dynamic
21774 mode http
21775 use-fcgi-app php-fpm
21776 server php-fpm A.B.C.D:9000 proto fcgi
21777
21778 fcgi-app php-fpm
21779 log-stderr global
21780 option keep-conn
21781
21782 docroot /var/www/my-app
21783 index index.php
21784 path-info ^(/.+\.php)(/.*)?$
21785
21786
2178710.2. Default parameters
21788------------------------
21789
21790A Responder FastCGI application has the same purpose as a CGI/1.1 program. In
21791the CGI/1.1 specification (RFC3875), several variables must be passed to the
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050021792script. So HAProxy set them and some others commonly used by FastCGI
Christopher Fauletb30b3102019-09-12 23:03:09 +020021793applications. All these variables may be overwritten, with caution though.
21794
21795 +-------------------+-----------------------------------------------------+
21796 | AUTH_TYPE | Identifies the mechanism, if any, used by HAProxy |
21797 | | to authenticate the user. Concretely, only the |
21798 | | BASIC authentication mechanism is supported. |
21799 | | |
21800 +-------------------+-----------------------------------------------------+
21801 | CONTENT_LENGTH | Contains the size of the message-body attached to |
21802 | | the request. It means only requests with a known |
21803 | | size are considered as valid and sent to the |
21804 | | application. |
21805 | | |
21806 +-------------------+-----------------------------------------------------+
21807 | CONTENT_TYPE | Contains the type of the message-body attached to |
21808 | | the request. It may not be set. |
21809 | | |
21810 +-------------------+-----------------------------------------------------+
21811 | DOCUMENT_ROOT | Contains the document root on the remote host under |
21812 | | which the script should be executed, as defined in |
21813 | | the application's configuration. |
21814 | | |
21815 +-------------------+-----------------------------------------------------+
21816 | GATEWAY_INTERFACE | Contains the dialect of CGI being used by HAProxy |
21817 | | to communicate with the FastCGI application. |
21818 | | Concretely, it is set to "CGI/1.1". |
21819 | | |
21820 +-------------------+-----------------------------------------------------+
21821 | PATH_INFO | Contains the portion of the URI path hierarchy |
21822 | | following the part that identifies the script |
21823 | | itself. To be set, the directive "path-info" must |
21824 | | be defined. |
21825 | | |
21826 +-------------------+-----------------------------------------------------+
21827 | PATH_TRANSLATED | If PATH_INFO is set, it is its translated version. |
21828 | | It is the concatenation of DOCUMENT_ROOT and |
21829 | | PATH_INFO. If PATH_INFO is not set, this parameters |
21830 | | is not set too. |
21831 | | |
21832 +-------------------+-----------------------------------------------------+
21833 | QUERY_STRING | Contains the request's query string. It may not be |
21834 | | set. |
21835 | | |
21836 +-------------------+-----------------------------------------------------+
21837 | REMOTE_ADDR | Contains the network address of the client sending |
21838 | | the request. |
21839 | | |
21840 +-------------------+-----------------------------------------------------+
21841 | REMOTE_USER | Contains the user identification string supplied by |
21842 | | client as part of user authentication. |
21843 | | |
21844 +-------------------+-----------------------------------------------------+
21845 | REQUEST_METHOD | Contains the method which should be used by the |
21846 | | script to process the request. |
21847 | | |
21848 +-------------------+-----------------------------------------------------+
21849 | REQUEST_URI | Contains the request's URI. |
21850 | | |
21851 +-------------------+-----------------------------------------------------+
21852 | SCRIPT_FILENAME | Contains the absolute pathname of the script. it is |
21853 | | the concatenation of DOCUMENT_ROOT and SCRIPT_NAME. |
21854 | | |
21855 +-------------------+-----------------------------------------------------+
21856 | SCRIPT_NAME | Contains the name of the script. If the directive |
21857 | | "path-info" is defined, it is the first part of the |
21858 | | URI path hierarchy, ending with the script name. |
21859 | | Otherwise, it is the entire URI path. |
21860 | | |
21861 +-------------------+-----------------------------------------------------+
21862 | SERVER_NAME | Contains the name of the server host to which the |
21863 | | client request is directed. It is the value of the |
21864 | | header "Host", if defined. Otherwise, the |
21865 | | destination address of the connection on the client |
21866 | | side. |
21867 | | |
21868 +-------------------+-----------------------------------------------------+
21869 | SERVER_PORT | Contains the destination TCP port of the connection |
21870 | | on the client side, which is the port the client |
21871 | | connected to. |
21872 | | |
21873 +-------------------+-----------------------------------------------------+
21874 | SERVER_PROTOCOL | Contains the request's protocol. |
21875 | | |
21876 +-------------------+-----------------------------------------------------+
21877 | HTTPS | Set to a non-empty value ("on") if the script was |
21878 | | queried through the HTTPS protocol. |
21879 | | |
21880 +-------------------+-----------------------------------------------------+
21881
21882
2188310.3. Limitations
21884------------------
21885
21886The current implementation have some limitations. The first one is about the
21887way some request headers are hidden to the FastCGI applications. This happens
21888during the headers analysis, on the backend side, before the connection
21889establishment. At this stage, HAProxy know the backend is using a FastCGI
21890application but it don't know if the request will be routed to a FastCGI server
21891or not. But to hide request headers, it simply removes them from the HTX
21892message. So, if the request is finally routed to an HTTP server, it never see
21893these headers. For this reason, it is not recommended to mix FastCGI servers
21894and HTTP servers under the same backend.
21895
21896Similarly, the rules "set-param" and "pass-header" are evaluated during the
21897request headers analysis. So the evaluation is always performed, even if the
21898requests is finally forwarded to an HTTP server.
21899
21900About the rules "set-param", when a rule is applied, a pseudo header is added
21901into the HTX message. So, the same way than for HTTP header rewrites, it may
21902fail if the buffer is full. The rules "set-param" will compete with
21903"http-request" ones.
21904
21905Finally, all FastCGI params and HTTP headers are sent into a unique record
21906FCGI_PARAM. Encoding of this record must be done in one pass, otherwise a
21907processing error is returned. It means the record FCGI_PARAM, once encoded,
21908must not exceeds the size of a buffer. However, there is no reserve to respect
21909here.
William Lallemand86d0df02017-11-24 21:36:45 +010021910
Emeric Brunce325c42021-04-02 17:05:09 +020021911
2191211. Address formats
21913-------------------
21914
21915Several statements as "bind, "server", "nameserver" and "log" requires an
21916address.
21917
21918This address can be a host name, an IPv4 address, an IPv6 address, or '*'.
21919The '*' is equal to the special address "0.0.0.0" and can be used, in the case
21920of "bind" or "dgram-bind" to listen on all IPv4 of the system.The IPv6
21921equivalent is '::'.
21922
21923Depending of the statement, a port or port range follows the IP address. This
21924is mandatory on 'bind' statement, optional on 'server'.
21925
21926This address can also begin with a slash '/'. It is considered as the "unix"
21927family, and '/' and following characters must be present the path.
21928
21929Default socket type or transport method "datagram" or "stream" depends on the
21930configuration statement showing the address. Indeed, 'bind' and 'server' will
21931use a "stream" socket type by default whereas 'log', 'nameserver' or
21932'dgram-bind' will use a "datagram".
21933
21934Optionally, a prefix could be used to force the address family and/or the
21935socket type and the transport method.
21936
21937
2193811.1 Address family prefixes
21939----------------------------
21940
21941'abns@<name>' following <name> is an abstract namespace (Linux only).
21942
21943'fd@<n>' following address is a file descriptor <n> inherited from the
21944 parent. The fd must be bound and may or may not already be
21945 listening.
21946
21947'ip@<address>[:port1[-port2]]' following <address> is considered as an IPv4 or
21948 IPv6 address depending on the syntax. Depending
21949 on the statement using this address, a port or
21950 a port range may or must be specified.
21951
21952'ipv4@<address>[:port1[-port2]]' following <address> is always considered as
21953 an IPv4 address. Depending on the statement
21954 using this address, a port or a port range
21955 may or must be specified.
21956
21957'ipv6@<address>[:port1[-port2]]' following <address> is always considered as
21958 an IPv6 address. Depending on the statement
21959 using this address, a port or a port range
21960 may or must be specified.
21961
21962'sockpair@<n>' following address is the file descriptor of a connected unix
21963 socket or of a socketpair. During a connection, the initiator
21964 creates a pair of connected sockets, and passes one of them
21965 over the FD to the other end. The listener waits to receive
21966 the FD from the unix socket and uses it as if it were the FD
21967 of an accept(). Should be used carefully.
21968
21969'unix@<path>' following string is considered as a UNIX socket <path>. this
21970 prefix is useful to declare an UNIX socket path which don't
21971 start by slash '/'.
21972
21973
2197411.2 Socket type prefixes
21975-------------------------
21976
21977Previous "Address family prefixes" can also be prefixed to force the socket
21978type and the transport method. The default depends of the statement using
21979this address but in some cases the user may force it to a different one.
21980This is the case for "log" statement where the default is syslog over UDP
21981but we could force to use syslog over TCP.
21982
21983Those prefixes were designed for internal purpose and users should
21984instead use aliases of the next section "11.5.3 Protocol prefixes".
21985
21986If users need one those prefixes to perform what they expect because
21987they can not configure the same using the protocol prefixes, they should
21988report this to the maintainers.
21989
21990'stream+<family>@<address>' forces socket type and transport method
21991 to "stream"
21992
21993'dgram+<family>@<address>' forces socket type and transport method
21994 to "datagram".
21995
21996
2199711.3 Protocol prefixes
21998----------------------
21999
22000'tcp@<address>[:port1[-port2]]' following <address> is considered as an IPv4
22001 or IPv6 address depending of the syntax but
22002 socket type and transport method is forced to
22003 "stream". Depending on the statement using
22004 this address, a port or a port range can or
22005 must be specified. It is considered as an alias
22006 of 'stream+ip@'.
22007
22008'tcp4@<address>[:port1[-port2]]' following <address> is always considered as
22009 an IPv4 address but socket type and transport
22010 method is forced to "stream". Depending on the
22011 statement using this address, a port or port
22012 range can or must be specified.
22013 It is considered as an alias of 'stream+ipv4@'.
22014
22015'tcp6@<address>[:port1[-port2]]' following <address> is always considered as
22016 an IPv6 address but socket type and transport
22017 method is forced to "stream". Depending on the
22018 statement using this address, a port or port
22019 range can or must be specified.
22020 It is considered as an alias of 'stream+ipv4@'.
22021
22022'udp@<address>[:port1[-port2]]' following <address> is considered as an IPv4
22023 or IPv6 address depending of the syntax but
22024 socket type and transport method is forced to
22025 "datagram". Depending on the statement using
22026 this address, a port or a port range can or
22027 must be specified. It is considered as an alias
22028 of 'dgram+ip@'.
22029
22030'udp4@<address>[:port1[-port2]]' following <address> is always considered as
22031 an IPv4 address but socket type and transport
22032 method is forced to "datagram". Depending on
22033 the statement using this address, a port or
22034 port range can or must be specified.
22035 It is considered as an alias of 'stream+ipv4@'.
22036
22037'udp6@<address>[:port1[-port2]]' following <address> is always considered as
22038 an IPv6 address but socket type and transport
22039 method is forced to "datagram". Depending on
22040 the statement using this address, a port or
22041 port range can or must be specified.
22042 It is considered as an alias of 'stream+ipv4@'.
22043
22044'uxdg@<path>' following string is considered as a unix socket <path> but
22045 transport method is forced to "datagram". It is considered as
22046 an alias of 'dgram+unix@'.
22047
22048'uxst@<path>' following string is considered as a unix socket <path> but
22049 transport method is forced to "stream". It is considered as
22050 an alias of 'stream+unix@'.
22051
22052In future versions, other prefixes could be used to specify protocols like
22053QUIC which proposes stream transport based on socket of type "datagram".
22054
Willy Tarreau0ba27502007-12-24 16:55:16 +010022055/*
22056 * Local variables:
22057 * fill-column: 79
22058 * End:
22059 */