4. Proxies
4.1. Proxy keywords matrix
4.2. Alphabetically sorted keywords reference
+4.3. Actions keywords matrix
+4.4. Alphabetically sorted actions reference
5. Bind and server options
5.1. Bind options
The http-after-response statement defines a set of rules which apply to layer
7 processing. The rules are evaluated in their declaration order when they
- are met in a frontend, listen or backend section. Any rule may optionally be
- followed by an ACL-based condition, in which case it will only be evaluated
- if the condition is true. Since these rules apply on responses, the backend
- rules are applied first, followed by the frontend's rules.
+ are met in a frontend, listen or backend section. Since these rules apply on
+ responses, the backend rules are applied first, followed by the frontend's
+ rules. Any rule may optionally be followed by an ACL-based condition, in
+ which case it will only be evaluated if the condition evaluates true.
Unlike http-response rules, these ones are applied on all responses, the
server ones but also to all responses generated by HAProxy. These rules are
- evaluated at the end of the responses analysis, before the data forwarding.
-
- The first keyword is the rule's action. Several types of actions are
- supported:
- - add-header <name> <fmt>
- - allow
- - capture <sample> id <id>
- - del-acl(<file-name>) <key fmt>
- - del-header <name> [ -m <meth> ]
- - del-map(<file-name>) <key fmt>
- - replace-header <name> <regex-match> <replace-fmt>
- - replace-value <name> <regex-match> <replace-fmt>
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - set-header <name> <fmt>
- - set-log-level <level>
- - set-map(<file-name>) <key fmt> <value fmt>
- - set-status <status> [reason <str>]
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - strict-mode { on | off }
- - unset-var(<var-name>)
-
- The supported actions are described below.
-
- There is no limit to the number of http-after-response statements per
- instance.
+ evaluated at the end of the responses analysis, before the data forwarding
+ phase.
+
+ The condition is evaluated just before the action is executed, and the action
+ is performed exactly once. As such, there is no problem if an action changes
+ an element which is checked as part of the condition. This also means that
+ multiple actions may rely on the same condition so that the first action that
+ changes the condition's evaluation is sufficient to implicitly disable the
+ remaining actions. This is used for example when trying to assign a value to
+ a variable from various sources when it's empty. There is no limit to the
+ number of "http-after-response" statements per instance.
+
+ The first keyword after "http-after-response" in the syntax is the rule's
+ action, optionally followed by a varying number of arguments for the action.
+ The supported actions and their respective syntaxes are enumerated in section
+ 4.3 "Actions" (look for actions which tick "HTTP Aft").
This directive is only available from named defaults sections, not anonymous
ones. Rules defined in the defaults section are evaluated before ones in the
http-after-response set-header Cache-Control "no-store,no-cache,private"
http-after-response set-header Pragma "no-cache"
-http-after-response add-header <name> <fmt> [ { if | unless } <condition> ]
-
- This appends an HTTP header field whose name is specified in <name> and whose
- value is defined by <fmt>. Please refer to "http-request add-header" for a
- complete description.
-
-http-after-response allow [ { if | unless } <condition> ]
-
- This stops the evaluation of the rules and lets the response pass the check.
- No further "http-after-response" rules are evaluated for the current section.
-
-http-after-response capture <sample> id <id> [ { if | unless } <condition> ]
-
- This captures sample expression <sample> from the response buffer, and
- converts it to a string. Please refer to "http-response capture" for a
- complete description.
-
-http-after-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
-
- This is used to delete an entry from an ACL. Please refer to "http-request
- del-acl" for a complete description.
-
-http-after-response del-header <name> [ -m <meth> ] [ { if | unless } <condition> ]
-
- This removes all HTTP header fields whose name is specified in <name>. Please
- refer to "http-request del-header" for a complete description.
-
-http-after-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
-
- This is used to delete an entry from a MAP. Please refer to "http-request
- del-map" for a complete description.
-
-http-after-response replace-header <name> <regex-match> <replace-fmt>
- [ { if | unless } <condition> ]
-
- This works like "http-response replace-header".
-
- Example:
- http-after-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
-
- # applied to:
- Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
-
- # outputs:
- Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
-
- # assuming the backend IP is 192.168.1.20.
-
-http-after-response replace-value <name> <regex-match> <replace-fmt>
- [ { if | unless } <condition> ]
-
- This works like "http-response replace-value".
-
- Example:
- http-after-response replace-value Cache-control ^public$ private
-
- # applied to:
- Cache-Control: max-age=3600, public
-
- # outputs:
- Cache-Control: max-age=3600, private
-
-http-after-response sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-
- This action increments the General Purpose Counter according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-add-gpc" for
- a complete description.
-
-http-after-response sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
-http-after-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-http-after-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
-
- These actions increment the General Purppose Counters according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-inc-gpc",
- "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete
- description.
-
-http-after-response sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-http-after-response sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-
- These actions set the 32-bit unsigned General Purpose Tags according to the
- sticky counter designated by <sc-id>. Please refer to "http-request
- sc-set-gpt" and "http-request sc-set-gpt0" for a complete description.
-
-http-after-response set-log-level <level> [ { if | unless } <condition> ]
-
- This is used to change the log level of the current response. Please refer to
- "http-request set-log-level" for a complete description.
-
-http-after-response set-map(<file-name>) <key fmt> <value fmt>
-
- This is used to add a new entry into a MAP. Please refer to "http-request
- set-map" for a complete description.
-
-http-after-response set-header <name> <fmt> [ { if | unless } <condition> ]
-
- This does the same as "http-after-response add-header" except that the header
- name is first removed if it existed. This is useful when passing security
- information to the server, where the header must not be manipulated by
- external users.
-
-http-after-response set-status <status> [reason <str>]
- [ { if | unless } <condition> ]
-
- This replaces the response status code with <status> which must be an integer
- between 100 and 999. Please refer to "http-response set-status" for a complete
- description.
-
-http-after-response set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-http-after-response set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
-
- This is used to set the contents of a variable. The variable is declared
- inline. Please refer to "http-request set-var" and "http-request set-var-fmt"
- for a complete description.
-
-http-after-response strict-mode { on | off } [ { if | unless } <condition> ]
-
- This enables or disables the strict rewriting mode for following
- rules. Please refer to "http-request strict-mode" for a complete description.
-
-http-after-response unset-var(<var-name>) [ { if | unless } <condition> ]
-
- This is used to unset a variable. See "http-request set-var" for details
- about <var-name>.
-
http-check comment <string>
Defines a comment for the following the http-check rule, reported in logs if
processing. The rules are evaluated in their declaration order when they are
met in a frontend, listen or backend section. Any rule may optionally be
followed by an ACL-based condition, in which case it will only be evaluated
- if the condition is true.
-
- The first keyword is the rule's action. Several types of actions are
- supported:
- - add-acl(<file-name>) <key fmt>
- - add-header <name> <fmt>
- - allow
- - auth [realm <realm>]
- - cache-use <name>
- - capture <sample> [ len <length> | id <id> ]
- - del-acl(<file-name>) <key fmt>
- - del-header <name> [ -m <meth> ]
- - del-map(<file-name>) <key fmt>
- - deny [ { status | deny_status } <code>] ...
- - disable-l7-retry
- - do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr>
- - early-hint <name> <fmt>
- - normalize-uri <normalizer>
- - redirect <rule>
- - reject
- - replace-header <name> <match-regex> <replace-fmt>
- - replace-path <match-regex> <replace-fmt>
- - replace-pathq <match-regex> <replace-fmt>
- - replace-uri <match-regex> <replace-fmt>
- - replace-value <name> <match-regex> <replace-fmt>
- - return [status <code>] [content-type <type>] ...
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
- - set-dst <expr>
- - set-dst-port <expr>
- - set-header <name> <fmt>
- - set-log-level <level>
- - set-map(<file-name>) <key fmt> <value fmt>
- - set-mark <mark>
- - set-method <fmt>
- - set-nice <nice>
- - set-path <fmt>
- - set-pathq <fmt>
- - set-priority-class <expr>
- - set-priority-offset <expr>
- - set-query <fmt>
- - set-src <expr>
- - set-src-port <expr>
- - set-timeout { client | server | tunnel } { <timeout> | <expr> }
- - set-tos <tos>
- - set-uri <fmt>
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - send-spoe-group <engine-name> <group-name>
- - silent-drop [ rst-ttl <ttl> ]
- - strict-mode { on | off }
- - tarpit [ { status | deny_status } <code>] ...
- - track-sc0 <key> [table <table>]
- - track-sc1 <key> [table <table>]
- - track-sc2 <key> [table <table>]
- - unset-var(<var-name>)
- - use-service <service-name>
- - wait-for-body time <time> [ at-least <bytes> ]
- - wait-for-handshake
- - cache-use <name>
-
- The supported actions are described below.
-
- There is no limit to the number of http-request statements per instance.
+ if the condition evaluates to true.
+
+ The condition is evaluated just before the action is executed, and the action
+ is performed exactly once. As such, there is no problem if an action changes
+ an element which is checked as part of the condition. This also means that
+ multiple actions may rely on the same condition so that the first action that
+ changes the condition's evaluation is sufficient to implicitly disable the
+ remaining actions. This is used for example when trying to assign a value to
+ a variable from various sources when it's empty. There is no limit to the
+ number of "http-request" statements per instance.
+
+ The first keyword after "http-request" in the syntax is the rule's action,
+ optionally followed by a varying number of arguments for the action. The
+ supported actions and their respective syntaxes are enumerated in section 4.3
+ "Actions" (look for actions which tick "HTTP Req").
This directive is only available from named defaults sections, not anonymous
ones. Rules defined in the defaults section are evaluated before ones in the
See also : "stats http-request", section 3.4 about userlists and section 7
about ACL usage.
-http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
-
- This is used to add a new entry into an ACL. The ACL must be loaded from a
- file (even a dummy empty file). The file name of the ACL to be updated is
- passed between parentheses. It takes one argument: <key fmt>, which follows
- log-format rules, to collect content of the new entry. It performs a lookup
- in the ACL before insertion, to avoid duplicated (or more) values.
- It is the equivalent of the "add acl" command from the stats socket, but can
- be triggered by an HTTP request.
-
-http-request add-header <name> <fmt> [ { if | unless } <condition> ]
+http-response <action> <options...> [ { if | unless } <condition> ]
+ Access control for Layer 7 responses
- This appends an HTTP header field whose name is specified in <name> and
- whose value is defined by <fmt> which follows the log-format rules (see
- Custom Log Format in section 8.2.4). This is particularly useful to pass
- connection-specific information to the server (e.g. the client's SSL
- certificate), or to combine several headers into one. This rule is not
- final, so it is possible to add other similar rules. Note that header
- addition is performed immediately, so one rule might reuse the resulting
- header from a previous rule.
+ May be used in sections: defaults | frontend | listen | backend
+ yes(!) | yes | yes | yes
-http-request allow [ { if | unless } <condition> ]
+ The http-response statement defines a set of rules which apply to layer 7
+ processing. The rules are evaluated in their declaration order when they are
+ met in a frontend, listen or backend section. Since these rules apply on
+ responses, the backend rules are applied first, followed by the frontend's
+ rules. Any rule may optionally be followed by an ACL-based condition, in
+ which case it will only be evaluated if the condition evaluates to true.
+
+ The condition is evaluated just before the action is executed, and the action
+ is performed exactly once. As such, there is no problem if an action changes
+ an element which is checked as part of the condition. This also means that
+ multiple actions may rely on the same condition so that the first action that
+ changes the condition's evaluation is sufficient to implicitly disable the
+ remaining actions. This is used for example when trying to assign a value to
+ a variable from various sources when it's empty. There is no limit to the
+ number of "http-response" statements per instance.
+
+ The first keyword after "http-response" in the syntax is the rule's action,
+ optionally followed by a varying number of arguments for the action. The
+ supported actions and their respective syntaxes are enumerated in section 4.3
+ "Actions" (look for actions which tick "HTTP Res").
- This stops the evaluation of the rules and lets the request pass the check.
- No further "http-request" rules are evaluated for the current section.
+ This directive is only available from named defaults sections, not anonymous
+ ones. Rules defined in the defaults section are evaluated before ones in the
+ associated proxy section. To avoid ambiguities, in this case the same
+ defaults section cannot be used by proxies with the frontend capability and
+ by proxies with the backend capability. It means a listen section cannot use
+ a defaults section defining such rules.
-http-request auth [realm <realm>] [ { if | unless } <condition> ]
+ Example:
+ acl key_acl res.hdr(X-Acl-Key) -m found
- This stops the evaluation of the rules and immediately responds with an
- HTTP 401 or 407 error code to invite the user to present a valid user name
- and password. No further "http-request" rules are evaluated. An optional
- "realm" parameter is supported, it sets the authentication realm that is
- returned with the response (typically the application's name).
+ acl myhost hdr(Host) -f myhost.lst
- The corresponding proxy's error message is used. It may be customized using
- an "errorfile" or an "http-error" directive. For 401 responses, all
- occurrences of the WWW-Authenticate header are removed and replaced by a new
- one with a basic authentication challenge for realm "<realm>". For 407
- responses, the same is done on the Proxy-Authenticate header. If the error
- message must not be altered, consider to use "http-request return" rule
- instead.
+ http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
+ http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
Example:
- acl auth_ok http_auth_group(L1) G1
- http-request auth unless auth_ok
+ acl value res.hdr(X-Value) -m found
-http-request cache-use <name> [ { if | unless } <condition> ]
+ use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
- See section 6.2 about cache setup.
+ http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
+ http-response del-map(map.lst) %[src] if ! value
-http-request capture <sample> [ len <length> | id <id> ]
- [ { if | unless } <condition> ]
-
- This captures sample expression <sample> from the request buffer, and
- converts it to a string of at most <len> characters. The resulting string is
- stored into the next request "capture" slot, so it will possibly appear next
- to some captured HTTP headers. It will then automatically appear in the logs,
- and it will be possible to extract it using sample fetch rules to feed it
- into headers or anything. The length should be limited given that this size
- will be allocated for each capture during the whole session life.
- Please check section 7.3 (Fetching samples) and "capture request header" for
- more information.
+ See also : "http-request", section 3.4 about userlists and section 7 about
+ ACL usage.
- If the keyword "id" is used instead of "len", the action tries to store the
- captured string in a previously declared capture slot. This is useful to run
- captures in backends. The slot id can be declared by a previous directive
- "http-request capture" or with the "declare capture" keyword.
+http-reuse { never | safe | aggressive | always }
+ Declare how idle HTTP connections may be shared between requests
- When using this action in a backend, double check that the relevant
- frontend(s) have the required capture slots otherwise, this rule will be
- ignored at run time. This can't be detected at configuration parsing time
- due to HAProxy's ability to dynamically resolve backend name at runtime.
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
-http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
+ By default, a connection established between HAProxy and the backend server
+ which is considered safe for reuse is moved back to the server's idle
+ connections pool so that any other request can make use of it. This is the
+ "safe" strategy below.
- This is used to delete an entry from an ACL. The ACL must be loaded from a
- file (even a dummy empty file). The file name of the ACL to be updated is
- passed between parentheses. It takes one argument: <key fmt>, which follows
- log-format rules, to collect content of the entry to delete.
- It is the equivalent of the "del acl" command from the stats socket, but can
- be triggered by an HTTP request.
+ The argument indicates the desired connection reuse strategy :
-http-request del-header <name> [ -m <meth> ] [ { if | unless } <condition> ]
+ - "never" : idle connections are never shared between sessions. This mode
+ may be enforced to cancel a different strategy inherited from
+ a defaults section or for troubleshooting. For example, if an
+ old bogus application considers that multiple requests over
+ the same connection come from the same client and it is not
+ possible to fix the application, it may be desirable to
+ disable connection sharing in a single backend. An example of
+ such an application could be an old HAProxy using cookie
+ insertion in tunnel mode and not checking any request past the
+ first one.
- This removes all HTTP header fields whose name is specified in <name>. <meth>
- is the matching method, applied on the header name. Supported matching methods
- are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub"
- (substring match) and "reg" (regex match). If not specified, exact matching
- method is used.
+ - "safe" : this is the default and the recommended strategy. The first
+ request of a session is always sent over its own connection,
+ and only subsequent requests may be dispatched over other
+ existing connections. This ensures that in case the server
+ closes the connection when the request is being sent, the
+ browser can decide to silently retry it. Since it is exactly
+ equivalent to regular keep-alive, there should be no side
+ effects. There is also a special handling for the connections
+ using protocols subject to Head-of-line blocking (backend with
+ h2 or fcgi). In this case, when at least one stream is
+ processed, the used connection is reserved to handle streams
+ of the same session. When no more streams are processed, the
+ connection is released and can be reused.
-http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
+ - "aggressive" : this mode may be useful in webservices environments where
+ all servers are not necessarily known and where it would be
+ appreciable to deliver most first requests over existing
+ connections. In this case, first requests are only delivered
+ over existing connections that have been reused at least once,
+ proving that the server correctly supports connection reuse.
+ It should only be used when it's sure that the client can
+ retry a failed request once in a while and where the benefit
+ of aggressive connection reuse significantly outweighs the
+ downsides of rare connection failures.
- This is used to delete an entry from a MAP. The MAP must be loaded from a
- file (even a dummy empty file). The file name of the MAP to be updated is
- passed between parentheses. It takes one argument: <key fmt>, which follows
- log-format rules, to collect content of the entry to delete.
- It takes one argument: "file name" It is the equivalent of the "del map"
- command from the stats socket, but can be triggered by an HTTP request.
-
-http-request deny [deny_status <status>] [ { if | unless } <condition> ]
-http-request deny [ { status | deny_status } <code>] [content-type <type>]
- [ { default-errorfiles | errorfile <file> | errorfiles <name> |
- file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
- [ hdr <name> <fmt> ]*
- [ { if | unless } <condition> ]
-
- This stops the evaluation of the rules and immediately rejects the request.
- By default an HTTP 403 error is returned. But the response may be customized
- using same syntax than "http-request return" rules. Thus, see "http-request
- return" for details. For compatibility purpose, when no argument is defined,
- or only "deny_status", the argument "default-errorfiles" is implied. It means
- "http-request deny [deny_status <status>]" is an alias of
- "http-request deny [status <status>] default-errorfiles".
- No further "http-request" rules are evaluated.
- See also "http-request return".
+ - "always" : this mode is only recommended when the path to the server is
+ known for never breaking existing connections quickly after
+ releasing them. It allows the first request of a session to be
+ sent to an existing connection. This can provide a significant
+ performance increase over the "safe" strategy when the backend
+ is a cache farm, since such components tend to show a
+ consistent behavior and will benefit from the connection
+ sharing. It is recommended that the "http-keep-alive" timeout
+ remains low in this mode so that no dead connections remain
+ usable. In most cases, this will lead to the same performance
+ gains as "aggressive" but with more risks. It should only be
+ used when it improves the situation over "aggressive".
-http-request disable-l7-retry [ { if | unless } <condition> ]
- This disables any attempt to retry the request if it fails for any other
- reason than a connection failure. This can be useful for example to make
- sure POST requests aren't retried on failure.
+ When http connection sharing is enabled, a great care is taken to respect the
+ connection properties and compatibility. Indeed, some properties are specific
+ and it is not possibly to reuse it blindly. Those are the SSL SNI, source
+ and destination address and proxy protocol block. A connection is reused only
+ if it shares the same set of properties with the request.
-http-request do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr>
- [ { if | unless } <condition> ]
+ Also note that connections with certain bogus authentication schemes (relying
+ on the connection) like NTLM are marked private and never shared.
- This action performs a DNS resolution of the output of <expr> and stores
- the result in the variable <var>. It uses the DNS resolvers section
- pointed by <resolvers>.
- It is possible to choose a resolution preference using the optional
- arguments 'ipv4' or 'ipv6'.
- When performing the DNS resolution, the client side connection is on
- pause waiting till the end of the resolution.
- If an IP address can be found, it is stored into <var>. If any kind of
- error occurs, then <var> is not set.
- One can use this action to discover a server IP address at run time and
- based on information found in the request (IE a Host header).
- If this action is used to find the server's IP address (using the
- "set-dst" action), then the server IP address in the backend must be set
- to 0.0.0.0. The do-resolve action takes an host-only parameter, any port must
- be removed from the string.
+ A connection pool is involved and configurable with "pool-max-conn".
- Example:
- resolvers mydns
- nameserver local 127.0.0.53:53
- nameserver google 8.8.8.8:53
- timeout retry 1s
- hold valid 10s
- hold nx 3s
- hold other 3s
- hold obsolete 0s
- accepted_payload_size 8192
+ Note: connection reuse improves the accuracy of the "server maxconn" setting,
+ because almost no new connection will be established while idle connections
+ remain available. This is particularly true with the "always" strategy.
- frontend fe
- bind 10.42.0.1:80
- http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),host_only
- http-request capture var(txn.myip) len 40
+ The rules to decide to keep an idle connection opened or to close it after
+ processing are also governed by the "tune.pool-low-fd-ratio" (default: 20%)
+ and "tune.pool-high-fd-ratio" (default: 25%). These correspond to the
+ percentage of total file descriptors spent in idle connections above which
+ haproxy will respectively refrain from keeping a connection opened after a
+ response, and actively kill idle connections. Some setups using a very high
+ ratio of idle connections, either because of too low a global "maxconn", or
+ due to a lot of HTTP/2 or HTTP/3 traffic on the frontend (few connections)
+ but HTTP/1 connections on the backend, may observe a lower reuse rate because
+ too few connections are kept open. It may be desirable in this case to adjust
+ such thresholds or simply to increase the global "maxconn" value.
- # return 503 when the variable is not set,
- # which mean DNS resolution error
- use_backend b_503 unless { var(txn.myip) -m found }
+ Similarly, when thread groups are explicitly enabled, it is important to
+ understand that idle connections are only usable between threads from a same
+ group. As such it may happen that unfair load between groups leads to more
+ idle connections being needed, causing a lower reuse rate. The same solution
+ may then be applied (increase global "maxconn" or increase pool ratios).
- default_backend be
+ See also : "option http-keep-alive", "server maxconn", "thread-groups",
+ "tune.pool-high-fd-ratio", "tune.pool-low-fd-ratio"
- backend b_503
- # dummy backend used to return 503.
- # one can use the errorfile directive to send a nice
- # 503 error page to end users
- backend be
- # rule to prevent HAProxy from reconnecting to services
- # on the local network (forged DNS name used to scan the network)
- http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 }
- http-request set-dst var(txn.myip)
- server clear 0.0.0.0:0
+http-send-name-header [<header>]
+ Add the server name to a request. Use the header string given by <header>
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <header> The header string to use to send the server name
- NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't
- be used to scan the network or worst won't loop over itself...
+ The "http-send-name-header" statement causes the header field named <header>
+ to be set to the name of the target server at the moment the request is about
+ to be sent on the wire. Any existing occurrences of this header are removed.
+ Upon retries and redispatches, the header field is updated to always reflect
+ the server being attempted to connect to. Given that this header is modified
+ very late in the connection setup, it may have unexpected effects on already
+ modified headers. For example using it with transport-level header such as
+ connection, content-length, transfer-encoding and so on will likely result in
+ invalid requests being sent to the server. Additionally it has been reported
+ that this directive is currently being used as a way to overwrite the Host
+ header field in outgoing requests; while this trick has been known to work
+ as a side effect of the feature for some time, it is not officially supported
+ and might possibly not work anymore in a future version depending on the
+ technical difficulties this feature induces. A long-term solution instead
+ consists in fixing the application which required this trick so that it binds
+ to the correct host name.
-http-request early-hint <name> <fmt> [ { if | unless } <condition> ]
+ See also : "server"
- This is used to build an HTTP 103 Early Hints response prior to any other one.
- This appends an HTTP header field to this response whose name is specified in
- <name> and whose value is defined by <fmt> which follows the log-format rules
- (see Custom Log Format in section 8.2.4). This is particularly useful to pass
- to the client some Link headers to preload resources required to render the
- HTML documents.
+id <value>
+ Set a persistent ID to a proxy.
+ May be used in sections : defaults | frontend | listen | backend
+ no | yes | yes | yes
+ Arguments : none
- See RFC 8297 for more information.
+ Set a persistent ID for the proxy. This ID must be unique and positive.
+ An unused ID will automatically be assigned if unset. The first assigned
+ value will be 1. This ID is currently only returned in statistics.
-http-request normalize-uri <normalizer> [ { if | unless } <condition> ]
-http-request normalize-uri fragment-encode [ { if | unless } <condition> ]
-http-request normalize-uri fragment-strip [ { if | unless } <condition> ]
-http-request normalize-uri path-merge-slashes [ { if | unless } <condition> ]
-http-request normalize-uri path-strip-dot [ { if | unless } <condition> ]
-http-request normalize-uri path-strip-dotdot [ full ] [ { if | unless } <condition> ]
-http-request normalize-uri percent-decode-unreserved [ strict ] [ { if | unless } <condition> ]
-http-request normalize-uri percent-to-uppercase [ strict ] [ { if | unless } <condition> ]
-http-request normalize-uri query-sort-by-name [ { if | unless } <condition> ]
- Performs normalization of the request's URI.
+ignore-persist { if | unless } <condition>
+ Declare a condition to ignore persistence
+ May be used in sections: defaults | frontend | listen | backend
+ no | no | yes | yes
- URI normalization in HAProxy 2.4 is currently available as an experimental
- technical preview. As such, it requires the global directive
- 'expose-experimental-directives' first to be able to invoke it. You should be
- prepared that the behavior of normalizers might change to fix possible
- issues, possibly breaking proper request processing in your infrastructure.
+ By default, when cookie persistence is enabled, every requests containing
+ the cookie are unconditionally persistent (assuming the target server is up
+ and running).
- Each normalizer handles a single type of normalization to allow for a
- fine-grained selection of the level of normalization that is appropriate for
- the supported backend.
+ The "ignore-persist" statement allows one to declare various ACL-based
+ conditions which, when met, will cause a request to ignore persistence.
+ This is sometimes useful to load balance requests for static files, which
+ often don't require persistence. This can also be used to fully disable
+ persistence for a specific User-Agent (for example, some web crawler bots).
- As an example the "path-strip-dotdot" normalizer might be useful for a static
- fileserver that directly maps the requested URI to the path within the local
- filesystem. However it might break routing of an API that expects a specific
- number of segments in the path.
+ The persistence is ignored when an "if" condition is met, or unless an
+ "unless" condition is met.
- It is important to note that some normalizers might result in unsafe
- transformations for broken URIs. It might also be possible that a combination
- of normalizers that are safe by themselves results in unsafe transformations
- when improperly combined.
+ Example:
+ acl url_static path_beg /static /images /img /css
+ acl url_static path_end .gif .png .jpg .css .js
+ ignore-persist if url_static
- As an example the "percent-decode-unreserved" normalizer might result in
- unexpected results when a broken URI includes bare percent characters. One
- such a broken URI is "/%%36%36" which would be decoded to "/%66" which in
- turn is equivalent to "/f". By specifying the "strict" option requests to
- such a broken URI would safely be rejected.
+ See also : "force-persist", "cookie", and section 7 about ACL usage.
- The following normalizers are available:
+load-server-state-from-file { global | local | none }
+ Allow seamless reload of HAProxy
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- - fragment-encode: Encodes "#" as "%23".
+ This directive points HAProxy to a file where server state from previous
+ running process has been saved. That way, when starting up, before handling
+ traffic, the new process can apply old states to servers exactly has if no
+ reload occurred. The purpose of the "load-server-state-from-file" directive is
+ to tell HAProxy which file to use. For now, only 2 arguments to either prevent
+ loading state or load states from a file containing all backends and servers.
+ The state file can be generated by running the command "show servers state"
+ over the stats socket and redirect output.
- The "fragment-strip" normalizer should be preferred, unless it is known
- that broken clients do not correctly encode '#' within the path component.
+ The format of the file is versioned and is very specific. To understand it,
+ please read the documentation of the "show servers state" command (chapter
+ 9.3 of Management Guide).
- Example:
- - /#foo -> /%23foo
+ Arguments:
+ global load the content of the file pointed by the global directive
+ named "server-state-file".
- - fragment-strip: Removes the URI's "fragment" component.
+ local load the content of the file pointed by the directive
+ "server-state-file-name" if set. If not set, then the backend
+ name is used as a file name.
- According to RFC 3986#3.5 the "fragment" component of an URI should not
- be sent, but handled by the User Agent after retrieving a resource.
+ none don't load any stat for this backend
- This normalizer should be applied first to ensure that the fragment is
- not interpreted as part of the request's path component.
+ Notes:
+ - server's IP address is preserved across reloads by default, but the
+ order can be changed thanks to the server's "init-addr" setting. This
+ means that an IP address change performed on the CLI at run time will
+ be preserved, and that any change to the local resolver (e.g. /etc/hosts)
+ will possibly not have any effect if the state file is in use.
- Example:
- - /#foo -> /
+ - server's weight is applied from previous running process unless it has
+ has changed between previous and new configuration files.
- - path-strip-dot: Removes "/./" segments within the "path" component
- (RFC 3986#6.2.2.3).
+ Example: Minimal configuration
- Segments including percent encoded dots ("%2E") will not be detected. Use
- the "percent-decode-unreserved" normalizer first if this is undesired.
+ global
+ stats socket /tmp/socket
+ server-state-file /tmp/server_state
- Example:
- - /. -> /
- - /./bar/ -> /bar/
- - /a/./a -> /a/a
- - /.well-known/ -> /.well-known/ (no change)
+ defaults
+ load-server-state-from-file global
- - path-strip-dotdot: Normalizes "/../" segments within the "path" component
- (RFC 3986#6.2.2.3).
+ backend bk
+ server s1 127.0.0.1:22 check weight 11
+ server s2 127.0.0.1:22 check weight 12
- This merges segments that attempt to access the parent directory with
- their preceding segment.
- Empty segments do not receive special treatment. Use the "merge-slashes"
- normalizer first if this is undesired.
+ Then one can run :
- Segments including percent encoded dots ("%2E") will not be detected. Use
- the "percent-decode-unreserved" normalizer first if this is undesired.
+ socat /tmp/socket - <<< "show servers state" > /tmp/server_state
- Example:
- - /foo/../ -> /
- - /foo/../bar/ -> /bar/
- - /foo/bar/../ -> /foo/
- - /../bar/ -> /../bar/
- - /bar/../../ -> /../
- - /foo//../ -> /foo/
- - /foo/%2E%2E/ -> /foo/%2E%2E/
+ Content of the file /tmp/server_state would be like this:
- If the "full" option is specified then "../" at the beginning will be
- removed as well:
+ 1
+ # <field names skipped for the doc example>
+ 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
+ 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
- Example:
- - /../bar/ -> /bar/
- - /bar/../../ -> /
+ Example: Minimal configuration
- - path-merge-slashes: Merges adjacent slashes within the "path" component
- into a single slash.
+ global
+ stats socket /tmp/socket
+ server-state-base /etc/haproxy/states
- Example:
- - // -> /
- - /foo//bar -> /foo/bar
+ defaults
+ load-server-state-from-file local
- - percent-decode-unreserved: Decodes unreserved percent encoded characters to
- their representation as a regular character (RFC 3986#6.2.2.2).
+ backend bk
+ server s1 127.0.0.1:22 check weight 11
+ server s2 127.0.0.1:22 check weight 12
- The set of unreserved characters includes all letters, all digits, "-",
- ".", "_", and "~".
- Example:
- - /%61dmin -> /admin
- - /foo%3Fbar=baz -> /foo%3Fbar=baz (no change)
- - /%%36%36 -> /%66 (unsafe)
- - /%ZZ -> /%ZZ
+ Then one can run :
- If the "strict" option is specified then invalid sequences will result
- in a HTTP 400 Bad Request being returned.
+ socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
- Example:
- - /%%36%36 -> HTTP 400
- - /%ZZ -> HTTP 400
+ Content of the file /etc/haproxy/states/bk would be like this:
- - percent-to-uppercase: Uppercases letters within percent-encoded sequences
- (RFC 3986#6.2.2.1).
+ 1
+ # <field names skipped for the doc example>
+ 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
+ 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
- Example:
- - /%6f -> /%6F
- - /%zz -> /%zz
+ See also: "server-state-file", "server-state-file-name", and
+ "show servers state"
- If the "strict" option is specified then invalid sequences will result
- in a HTTP 400 Bad Request being returned.
- Example:
- - /%zz -> HTTP 400
+log global
+log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
+ <facility> [<level> [<minlevel>]]
+no log
+ Enable per-instance logging of events and traffic.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
- - query-sort-by-name: Sorts the query string parameters by parameter name.
- Parameters are assumed to be delimited by '&'. Shorter names sort before
- longer names and identical parameter names maintain their relative order.
+ Prefix :
+ no should be used when the logger list must be flushed. For example,
+ if you don't want to inherit from the default logger list. This
+ prefix does not allow arguments.
- Example:
- - /?c=3&a=1&b=2 -> /?a=1&b=2&c=3
- - /?aaa=3&a=1&aa=2 -> /?a=1&aa=2&aaa=3
- - /?a=3&b=4&a=1&b=5&a=2 -> /?a=3&a=1&a=2&b=4&b=5
+ Arguments :
+ global should be used when the instance's logging parameters are the
+ same as the global ones. This is the most common usage. "global"
+ replaces <target>, <facility> and <level> with those of the log
+ entries found in the "global" section. Only one "log global"
+ statement may be used per instance, and this form takes no other
+ parameter.
-http-request redirect <rule> [ { if | unless } <condition> ]
+ <target> indicates where to send the logs. It takes the same format as
+ for the "global" section's logs, and can be one of :
- This performs an HTTP redirection based on a redirect rule. This is exactly
- the same as the "redirect" statement except that it inserts a redirect rule
- which can be processed in the middle of other "http-request" rules and that
- these rules use the "log-format" strings. See the "redirect" keyword for the
- rule's syntax.
+ - An IPv4 address optionally followed by a colon (':') and a UDP
+ port. If no port is specified, 514 is used by default (the
+ standard syslog port).
-http-request reject [ { if | unless } <condition> ]
+ - An IPv6 address followed by a colon (':') and optionally a UDP
+ port. If no port is specified, 514 is used by default (the
+ standard syslog port).
- This stops the evaluation of the rules and immediately closes the connection
- without sending any response. It acts similarly to the
- "tcp-request content reject" rules. It can be useful to force an immediate
- connection closure on HTTP/2 connections.
+ - A filesystem path to a UNIX domain socket, keeping in mind
+ considerations for chroot (be sure the path is accessible
+ inside the chroot) and uid/gid (be sure the path is
+ appropriately writable).
-http-request replace-header <name> <match-regex> <replace-fmt>
- [ { if | unless } <condition> ]
+ - A file descriptor number in the form "fd@<number>", which may
+ point to a pipe, terminal, or socket. In this case unbuffered
+ logs are used and one writev() call per log is performed. This
+ is a bit expensive but acceptable for most workloads. Messages
+ sent this way will not be truncated but may be dropped, in
+ which case the DroppedLogs counter will be incremented. The
+ writev() call is atomic even on pipes for messages up to
+ PIPE_BUF size, which POSIX recommends to be at least 512 and
+ which is 4096 bytes on most modern operating systems. Any
+ larger message may be interleaved with messages from other
+ processes. Exceptionally for debugging purposes the file
+ descriptor may also be directed to a file, but doing so will
+ significantly slow HAProxy down as non-blocking calls will be
+ ignored. Also there will be no way to purge nor rotate this
+ file without restarting the process. Note that the configured
+ syslog format is preserved, so the output is suitable for use
+ with a TCP syslog server. See also the "short" and "raw"
+ formats below.
- This matches the value of all occurrences of header field <name> against
- <match-regex>. Matching is performed case-sensitively. Matching values are
- completely replaced by <replace-fmt>. Format characters are allowed in
- <replace-fmt> and work like <fmt> arguments in "http-request add-header".
- Standard back-references using the backslash ('\') followed by a number are
- supported.
+ - "stdout" / "stderr", which are respectively aliases for "fd@1"
+ and "fd@2", see above.
- This action acts on whole header lines, regardless of the number of values
- they may contain. Thus it is well-suited to process headers naturally
- containing commas in their value, such as If-Modified-Since. Headers that
- contain a comma-separated list of values, such as Accept, should be processed
- using "http-request replace-value".
+ - A ring buffer in the form "ring@<name>", which will correspond
+ to an in-memory ring buffer accessible over the CLI using the
+ "show events" command, which will also list existing rings and
+ their sizes. Such buffers are lost on reload or restart but
+ when used as a complement this can help troubleshooting by
+ having the logs instantly available.
- Example:
- http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
+ - A log backend in the form "backend@<name>", which will send
+ log messages to the corresponding log backend responsible for
+ sending the message to the proper server according to the
+ backend's lb settings. A log backend is a backend section with
+ "mode log" set (see "mode" for more information).
- # applied to:
- Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
+ - An explicit stream address prefix such as "tcp@","tcp6@",
+ "tcp4@" or "uxst@" will allocate an implicit ring buffer with
+ a stream forward server targeting the given address.
- # outputs:
- Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
+ You may want to reference some environment variables in the
+ address parameter, see section 2.3 about environment variables.
- # assuming the backend IP is 192.168.1.20
+ <length> is an optional maximum line length. Log lines larger than this
+ value will be truncated before being sent. The reason is that
+ syslog servers act differently on log line length. All servers
+ support the default value of 1024, but some servers simply drop
+ larger lines while others do log them. If a server supports long
+ lines, it may make sense to set this value here in order to avoid
+ truncating long lines. Similarly, if a server drops long lines,
+ it is preferable to truncate them before sending them. Accepted
+ values are 80 to 65535 inclusive. The default value of 1024 is
+ generally fine for all standard usages. Some specific cases of
+ long captures or JSON-formatted logs may require larger values.
+ You may also need to increase "tune.http.logurilen" if your
+ request URIs are truncated.
- http-request replace-header User-Agent curl foo
+ <ranges> A list of comma-separated ranges to identify the logs to sample.
+ This is used to balance the load of the logs to send to the log
+ server. The limits of the ranges cannot be null. They are numbered
+ from 1. The size or period (in number of logs) of the sample must
+ be set with <sample_size> parameter.
- # applied to:
- User-Agent: curl/7.47.0
+ <sample_size>
+ The size of the sample in number of logs to consider when balancing
+ their logging loads. It is used to balance the load of the logs to
+ send to the syslog server. This size must be greater or equal to the
+ maximum of the high limits of the ranges.
+ (see also <ranges> parameter).
- # outputs:
- User-Agent: foo
+ <format> is the log format used when generating syslog messages. It may be
+ one of the following :
-http-request replace-path <match-regex> <replace-fmt>
- [ { if | unless } <condition> ]
+ local Analog to rfc3164 syslog message format except that hostname
+ field is stripped. This is the default.
+ Note: option "log-send-hostname" switches the default to
+ rfc3164.
- This works like "replace-header" except that it works on the request's path
- component instead of a header. The path component starts at the first '/'
- after an optional scheme+authority and ends before the question mark. Thus,
- the replacement does not modify the scheme, the authority and the
- query-string.
+ rfc3164 The RFC3164 syslog message format.
+ (https://tools.ietf.org/html/rfc3164)
- It is worth noting that regular expressions may be more expensive to evaluate
- than certain ACLs, so rare replacements may benefit from a condition to avoid
- performing the evaluation at all if it does not match.
+ rfc5424 The RFC5424 syslog message format.
+ (https://tools.ietf.org/html/rfc5424)
- Example:
- # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
- http-request replace-path (.*) /foo\1
+ priority A message containing only a level plus syslog facility between
+ angle brackets such as '<63>', followed by the text. The PID,
+ date, time, process name and system name are omitted. This is
+ designed to be used with a local log server.
- # strip /foo : turn /foo/bar?q=1 into /bar?q=1
- http-request replace-path /foo/(.*) /\1
- # or more efficient if only some requests match :
- http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ }
+ short A message containing only a level between angle brackets such as
+ '<3>', followed by the text. The PID, date, time, process name
+ and system name are omitted. This is designed to be used with a
+ local log server. This format is compatible with what the
+ systemd logger consumes.
-http-request replace-pathq <match-regex> <replace-fmt>
- [ { if | unless } <condition> ]
+ timed A message containing only a level between angle brackets such as
+ '<3>', followed by ISO date and by the text. The PID, process
+ name and system name are omitted. This is designed to be
+ used with a local log server.
- This does the same as "http-request replace-path" except that the path
- contains the query-string if any is present. Thus, the path and the
- query-string are replaced.
+ iso A message containing only the ISO date, followed by the text.
+ The PID, process name and system name are omitted. This is
+ designed to be used with a local log server.
- Example:
- # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 :
- http-request replace-pathq ([^?]*)(\?(.*))? \1/foo\2
+ raw A message containing only the text. The level, PID, date, time,
+ process name and system name are omitted. This is designed to
+ be used in containers or during development, where the severity
+ only depends on the file descriptor used (stdout/stderr).
-http-request replace-uri <match-regex> <replace-fmt>
- [ { if | unless } <condition> ]
+ <facility> must be one of the 24 standard syslog facilities :
- This works like "replace-header" except that it works on the request's URI part
- instead of a header. The URI part may contain an optional scheme, authority or
- query string. These are considered to be part of the value that is matched
- against.
+ kern user mail daemon auth syslog lpr news
+ uucp cron auth2 ftp ntp audit alert cron2
+ local0 local1 local2 local3 local4 local5 local6 local7
- It is worth noting that regular expressions may be more expensive to evaluate
- than certain ACLs, so rare replacements may benefit from a condition to avoid
- performing the evaluation at all if it does not match.
+ Note that the facility is ignored for the "short" and "raw"
+ formats, but still required as a positional field. It is
+ recommended to use "daemon" in this case to make it clear that
+ it's only supposed to be used locally.
- IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent
- by browsers use the "origin form", which differs from the "absolute form" in
- that they do not contain a scheme nor authority in the URI portion. Mostly
- only requests sent to proxies, those forged by hand and some emitted by
- certain applications use the absolute form. As such, "replace-uri" usually
- works fine most of the time in HTTP/1.x with rules starting with a "/". But
- with HTTP/2, clients are encouraged to send absolute URIs only, which look
- like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri
- rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need
- to be adapted to optionally match a scheme and authority, or replace-path
- should be used.
+ <level> is optional and can be specified to filter outgoing messages. By
+ default, all messages are sent. If a level is specified, only
+ messages with a severity at least as important as this level
+ will be sent. An optional minimum level can be specified. If it
+ is set, logs emitted with a more severe level than this one will
+ be capped to this level. This is used to avoid sending "emerg"
+ messages on all terminals on some default syslog configurations.
+ Eight levels are known :
- Example:
- # rewrite all "http" absolute requests to "https":
- http-request replace-uri ^http://(.*) https://\1
+ emerg alert crit err warning notice info debug
- # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
- http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2
+ It is important to keep in mind that it is the frontend which decides what to
+ log from a connection, and that in case of content switching, the log entries
+ from the backend will be ignored. Connections are logged at level "info".
-http-request replace-value <name> <match-regex> <replace-fmt>
- [ { if | unless } <condition> ]
+ However, backend log declaration define how and where servers status changes
+ will be logged. Level "notice" will be used to indicate a server going up,
+ "warning" will be used for termination signals and definitive service
+ termination, and "alert" will be used for when a server goes down.
- This works like "replace-header" except that it matches the regex against
- every comma-delimited value of the header field <name> instead of the
- entire header. This is suited for all headers which are allowed to carry
- more than one value. An example could be the Accept header.
+ Note : According to RFC3164, messages are truncated to 1024 bytes before
+ being emitted.
- Example:
- http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
+ Example :
+ log global
+ log stdout format short daemon # send log to systemd
+ log stdout format raw daemon # send everything to stdout
+ log stderr format raw daemon notice # send important events to stderr
+ log 127.0.0.1:514 local0 notice # only send important events
+ log tcp@127.0.0.1:514 local0 notice notice # same but limit output
+ # level and send in tcp
+ log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
- # applied to:
- X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
+log-format <string>
+ Specifies the log format string to use for traffic logs
+ May be used in sections: defaults | frontend | listen | backend
+ yes | yes | yes | no
- # outputs:
- X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
+ This directive specifies the log format string that will be used for all logs
+ resulting from traffic passing through the frontend using this line. If the
+ directive is used in a defaults section, all subsequent frontends will use
+ the same log format. Please see section 8.2.4 which covers the log format
+ string in depth.
+ A specific log-format used only in case of connection error can also be
+ defined, see the "error-log-format" option.
-http-request return [status <code>] [content-type <type>]
- [ { default-errorfiles | errorfile <file> | errorfiles <name> |
- file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
- [ hdr <name> <fmt> ]*
- [ { if | unless } <condition> ]
+ "log-format" directive overrides previous "option tcplog", "log-format",
+ "option httplog" and "option httpslog" directives.
- This stops the evaluation of the rules and immediately returns a response. The
- default status code used for the response is 200. It can be optionally
- specified as an arguments to "status". The response content-type may also be
- specified as an argument to "content-type". Finally the response itself may
- be defined. It can be a full HTTP response specifying the errorfile to use,
- or the response payload specifying the file or the string to use. These rules
- are followed to create the response :
+log-format-sd <string>
+ Specifies the RFC5424 structured-data log format string
+ May be used in sections: defaults | frontend | listen | backend
+ yes | yes | yes | no
- * If neither the errorfile nor the payload to use is defined, a dummy
- response is returned. Only the "status" argument is considered. It can be
- any code in the range [200, 599]. The "content-type" argument, if any, is
- ignored.
+ This directive specifies the RFC5424 structured-data log format string that
+ will be used for all logs resulting from traffic passing through the frontend
+ using this line. If the directive is used in a defaults section, all
+ subsequent frontends will use the same log format. Please see section 8.2.4
+ which covers the log format string in depth.
- * If "default-errorfiles" argument is set, the proxy's errorfiles are
- considered. If the "status" argument is defined, it must be one of the
- status code handled by HAProxy (200, 400, 403, 404, 405, 408, 410, 413,
- 425, 429, 500, 501, 502, 503, and 504). The "content-type" argument, if
- any, is ignored.
+ See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
+ about the RFC5424 structured-data part.
- * If a specific errorfile is defined, with an "errorfile" argument, the
- corresponding file, containing a full HTTP response, is returned. Only the
- "status" argument is considered. It must be one of the status code handled
- by HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 501,
- 502, 503, and 504). The "content-type" argument, if any, is ignored.
+ Note : This log format string will be used only for loggers that have set
+ log format to "rfc5424".
- * If an http-errors section is defined, with an "errorfiles" argument, the
- corresponding file in the specified http-errors section, containing a full
- HTTP response, is returned. Only the "status" argument is considered. It
- must be one of the status code handled by HAProxy (200, 400, 403, 404, 405,
- 408, 410, 413, 425, 429, 500, 501, 502, 503, and 504). The "content-type"
- argument, if any, is ignored.
+ Example :
+ log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
- * If a "file" or a "lf-file" argument is specified, the file's content is
- used as the response payload. If the file is not empty, its content-type
- must be set as argument to "content-type". Otherwise, any "content-type"
- argument is ignored. With a "lf-file" argument, the file's content is
- evaluated as a log-format string. With a "file" argument, it is considered
- as a raw content.
- * If a "string" or "lf-string" argument is specified, the defined string is
- used as the response payload. The content-type must always be set as
- argument to "content-type". With a "lf-string" argument, the string is
- evaluated as a log-format string. With a "string" argument, it is
- considered as a raw string.
+log-tag <string>
+ Specifies the log tag to use for all outgoing logs
+ May be used in sections: defaults | frontend | listen | backend
+ yes | yes | yes | yes
- When the response is not based on an errorfile, it is possible to append HTTP
- header fields to the response using "hdr" arguments. Otherwise, all "hdr"
- arguments are ignored. For each one, the header name is specified in <name>
- and its value is defined by <fmt> which follows the log-format rules.
+ Sets the tag field in the syslog header to this string. It defaults to the
+ log-tag set in the global section, otherwise the program name as launched
+ from the command line, which usually is "HAProxy". Sometimes it can be useful
+ to differentiate between multiple processes running on the same host, or to
+ differentiate customer instances running in the same process. In the backend,
+ logs about servers up/down will use this tag. As a hint, it can be convenient
+ to set a log-tag related to a hosted customer in a defaults section then put
+ all the frontends and backends for that customer, then start another customer
+ in a new defaults section. See also the global "log-tag" directive.
- Note that the generated response must be smaller than a buffer. And to avoid
- any warning, when an errorfile or a raw file is loaded, the buffer space
- reserved for the headers rewriting should also be free.
+max-keep-alive-queue <value>
+ Set the maximum server queue size for maintaining keep-alive connections
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- No further "http-request" rules are evaluated.
+ HTTP keep-alive tries to reuse the same server connection whenever possible,
+ but sometimes it can be counter-productive, for example if a server has a lot
+ of connections while other ones are idle. This is especially true for static
+ servers.
- Example:
- http-request return errorfile /etc/haproxy/errorfiles/200.http \
- if { path /ping }
+ The purpose of this setting is to set a threshold on the number of queued
+ connections at which HAProxy stops trying to reuse the same server and prefers
+ to find another one. The default value, -1, means there is no limit. A value
+ of zero means that keep-alive requests will never be queued. For very close
+ servers which can be reached with a low latency and which are not sensible to
+ breaking keep-alive, a low value is recommended (e.g. local static server can
+ use a value of 10 or less). For remote servers suffering from a high latency,
+ higher values might be needed to cover for the latency and/or the cost of
+ picking a different server.
- http-request return content-type image/x-icon file /var/www/favicon.ico \
- if { path /favicon.ico }
+ Note that this has no impact on responses which are maintained to the same
+ server consecutively to a 401 response. They will still go to the same server
+ even if they have to be queued.
- http-request return status 403 content-type text/plain \
- lf-string "Access denied. IP %[src] is blacklisted." \
- if { src -f /etc/haproxy/blacklist.lst }
+ See also : "option http-server-close", "option prefer-last-server", server
+ "maxconn" and cookie persistence.
-http-request sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+max-session-srv-conns <nb>
+ Set the maximum number of outgoing connections we can keep idling for a given
+ client session. The default is 5 (it precisely equals MAX_SRV_LIST which is
+ defined at build time).
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
- This action increments the General Purpose Counter at the index <idx> of the
- array associated to the sticky counter designated by <sc-id> by the value of
- either integer <int> or the integer evaluation of expression <expr>. Integers
- and expressions are limited to unsigned 32-bit values. If an error occurs,
- this action silently fails and the actions evaluation continues. <idx> is an
- integer between 0 and 99 and <sc-id> is an integer between 0 and 2. It also
- silently fails if the there is no GPC stored at this index. The entry in the
- table is refreshed even if the value is zero. The 'gpc_rate' is automatically
- adjusted to reflect the average growth rate of the gpc value.
+maxconn <conns>
+ Fix the maximum number of concurrent connections on a frontend
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments :
+ <conns> is the maximum number of concurrent connections the frontend will
+ accept to serve. Excess connections will be queued by the system
+ in the socket's listen queue and will be served once a connection
+ closes.
- This action applies only to the 'gpc' and 'gpc_rate' array data_types (and
- not to the legacy 'gpc0', 'gpc1', 'gpc0_rate' nor 'gpc1_rate' data_types).
- There is no equivalent function for legacy data types, but if the value is
- always 1, please see 'sc-inc-gpc()', 'sc-inc-gpc0()' and 'sc-inc-gpc1()'.
- There is no way to decrement the value either, but it is possible to store
- exact values in a General Purpose Tag using 'sc-set-gpt()' instead.
+ If the system supports it, it can be useful on big sites to raise this limit
+ very high so that HAProxy manages connection queues, instead of leaving the
+ clients with unanswered connection attempts. This value should not exceed the
+ global maxconn. Also, keep in mind that a connection contains two buffers
+ of tune.bufsize (16kB by default) each, as well as some other data resulting
+ in about 33 kB of RAM being consumed per established connection. That means
+ that a medium system equipped with 1GB of RAM can withstand around
+ 20000-25000 concurrent connections if properly tuned.
- The main use of this action is to count scores or total volumes (e.g.
- estimated danger per source IP reported by the server or a WAF, total
- uploaded bytes, etc).
+ Also, when <conns> is set to large values, it is possible that the servers
+ are not sized to accept such loads, and for this reason it is generally wise
+ to assign them some reasonable connection limits.
-http-request sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
+ When this value is set to zero, which is the default, the global "maxconn"
+ value is used.
- This actions increments the General Purpose Counter at the index <idx>
- of the array associated to the sticky counter designated by <sc-id>.
- If an error occurs, this action silently fails and the actions evaluation
- continues. <idx> is an integer between 0 and 99 and <sc-id> is an integer
- between 0 and 2. It also silently fails if the there is no GPC stored
- at this index.
- This action applies only to the 'gpc' and 'gpc_rate' array data_types (and
- not to the legacy 'gpc0', 'gpc1', 'gpc0_rate' nor 'gpc1_rate' data_types).
+ See also : "server", global section's "maxconn", "fullconn"
-http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
- This actions increments the GPC0 or GPC1 counter according with the sticky
- counter designated by <sc-id>. If an error occurs, this action silently fails
- and the actions evaluation continues.
+mode { tcp|http|log }
+ Set the running mode or protocol of the instance
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments :
+ tcp The instance will work in pure TCP mode. A full-duplex connection
+ will be established between clients and servers, and no layer 7
+ examination will be performed. This is the default mode. It
+ should be used for SSL, SSH, SMTP, ...
-http-request sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
- This action sets the 32-bit unsigned GPT at the index <idx> of the array
- associated to the sticky counter designated by <sc-id> at the value of
- <int>/<expr>. The expected result is a boolean.
- If an error occurs, this action silently fails and the actions evaluation
- continues. <idx> is an integer between 0 and 99 and <sc-id> is an integer
- between 0 and 2. It also silently fails if the there is no GPT stored
- at this index.
- This action applies only to the 'gpt' array data_type (and not to the
- legacy 'gpt0' data-type).
+ http The instance will work in HTTP mode. The client request will be
+ analyzed in depth before connecting to any server. Any request
+ which is not RFC-compliant will be rejected. Layer 7 filtering,
+ processing and switching will be possible. This is the mode which
+ brings HAProxy most of its value.
-http-request sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ log When used in a backend section, it will turn the backend into a
+ log backend. Such backend can be used as a log destination for
+ any "log" directive by using the "backend@<name>" syntax. Log
+ messages will be distributed to the servers from the backend
+ according to the lb settings which can be configured using the
+ "balance" keyword. Log backends support UDP servers by prefixing
+ the server's address with the "udp@" prefix. Common backend and
+ server features are supported, but not TCP or HTTP specific ones.
- This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
- designated by <sc-id> and the value of <int>/<expr>. The expected result is a
- boolean. If an error occurs, this action silently fails and the actions
- evaluation continues.
+ When doing content switching, it is mandatory that the frontend and the
+ backend are in the same mode (generally HTTP), otherwise the configuration
+ will be refused.
-http-request send-spoe-group <engine-name> <group-name>
- [ { if | unless } <condition> ]
+ Example :
+ defaults http_instances
+ mode http
- This action is used to trigger sending of a group of SPOE messages. To do so,
- the SPOE engine used to send messages must be defined, as well as the SPOE
- group to send. Of course, the SPOE engine must refer to an existing SPOE
- filter. If not engine name is provided on the SPOE filter line, the SPOE
- agent name must be used.
- Arguments:
- <engine-name> The SPOE engine name.
+monitor fail { if | unless } <condition>
+ Add a condition to report a failure to a monitor HTTP request.
+ May be used in sections : defaults | frontend | listen | backend
+ no | yes | yes | no
+ Arguments :
+ if <cond> the monitor request will fail if the condition is satisfied,
+ and will succeed otherwise. The condition should describe a
+ combined test which must induce a failure if all conditions
+ are met, for instance a low number of servers both in a
+ backend and its backup.
- <group-name> The SPOE group name as specified in the engine
- configuration.
+ unless <cond> the monitor request will succeed only if the condition is
+ satisfied, and will fail otherwise. Such a condition may be
+ based on a test on the presence of a minimum number of active
+ servers in a list of backends.
-http-request set-bandwidth-limit <name> [limit { <expr> | <size> }]
- [period { <expr> | <time> }] [ { if | unless } <condition> ]
+ This statement adds a condition which can force the response to a monitor
+ request to report a failure. By default, when an external component queries
+ the URI dedicated to monitoring, a 200 response is returned. When one of the
+ conditions above is met, HAProxy will return 503 instead of 200. This is
+ very useful to report a site failure to an external component which may base
+ routing advertisements between multiple sites on the availability reported by
+ HAProxy. In this case, one would rely on an ACL involving the "nbsrv"
+ criterion. Note that "monitor fail" only works in HTTP mode. Both status
+ messages may be tweaked using "errorfile" or "errorloc" if needed.
- This action is used to enable the bandwidth limitation filter <name>, either
- on the upload or download direction depending on the filter type. Custom
- limit and period may be defined, if and only if <name> references a
- per-stream bandwidth limitation filter. When a set-bandwidth-limit rule is
- executed, it first resets all settings of the filter to their defaults prior
- to enabling it. As a consequence, if several "set-bandwidth-limit" actions
- are executed for the same filter, only the last one is considered. Several
- bandwidth limitation filters can be enabled on the same stream.
+ Example:
+ frontend www
+ mode http
+ acl site_dead nbsrv(dynamic) lt 2
+ acl site_dead nbsrv(static) lt 2
+ monitor-uri /site_alive
+ monitor fail if site_dead
- Note that this action cannot be used in a defaults section because bandwidth
- limitation filters cannot be defined in defaults sections. In addition, only
- the HTTP payload transfer is limited. The HTTP headers are not considered.
+ See also : "monitor-uri", "errorfile", "errorloc"
- Arguments:
- <expr> Is a standard HAProxy expression formed by a sample-fetch followed
- by some converters. The result is converted to an integer. It is
- interpreted as a size in bytes for the "limit" parameter and as a
- duration in milliseconds for the "period" parameter.
- <size> Is a number. It follows the HAProxy size format and is expressed in
- bytes.
+monitor-uri <uri>
+ Intercept a URI used by external components' monitor requests
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments :
+ <uri> is the exact URI which we want to intercept to return HAProxy's
+ health status instead of forwarding the request.
- <time> Is a number. It follows the HAProxy time format and is expressed in
- milliseconds.
+ When an HTTP request referencing <uri> will be received on a frontend,
+ HAProxy will not forward it nor log it, but instead will return either
+ "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
+ conditions defined with "monitor fail". This is normally enough for any
+ front-end HTTP probe to detect that the service is UP and running without
+ forwarding the request to a backend server. Note that the HTTP method, the
+ version and all headers are ignored, but the request must at least be valid
+ at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
- Example:
- http-request set-bandwidth-limit global-limit
- http-request set-bandwidth-limit my-limit limit 1m period 10s
+ Monitor requests are processed very early, just after the request is parsed
+ and even before any "http-request". The only rulesets applied before are the
+ tcp-request ones. They cannot be logged either, and it is the intended
+ purpose. Only one URI may be configured for monitoring; when multiple
+ "monitor-uri" statements are present, the last one will define the URI to
+ be used. They are only used to report HAProxy's health to an upper component,
+ nothing more. However, it is possible to add any number of conditions using
+ "monitor fail" and ACLs so that the result can be adjusted to whatever check
+ can be imagined (most often the number of available servers in a backend).
- See section 9.7 about bandwidth limitation filter setup.
-
-http-request set-dst <expr> [ { if | unless } <condition> ]
+ Note: if <uri> starts by a slash ('/'), the matching is performed against the
+ request's path instead of the request's uri. It is a workaround to let
+ the HTTP/2 requests match the monitor-uri. Indeed, in HTTP/2, clients
+ are encouraged to send absolute URIs only.
- This is used to set the destination IP address to the value of specified
- expression. Useful when a proxy in front of HAProxy rewrites destination IP,
- but provides the correct IP in a HTTP header; or you want to mask the IP for
- privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
- server address in the backend.
+ Example :
+ # Use /haproxy_test to report HAProxy's status
+ frontend www
+ mode http
+ monitor-uri /haproxy_test
- Arguments:
- <expr> Is a standard HAProxy expression formed by a sample-fetch followed
- by some converters.
+ See also : "monitor fail"
- Example:
- http-request set-dst hdr(x-dst)
- http-request set-dst dst,ipmask(24)
- When possible, set-dst preserves the original destination port as long as the
- address family allows it, otherwise the destination port is set to 0.
+option abortonclose
+no option abortonclose
+ Enable or disable early dropping of aborted requests pending in queues.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
-http-request set-dst-port <expr> [ { if | unless } <condition> ]
+ In presence of very high loads, the servers will take some time to respond.
+ The per-instance connection queue will inflate, and the response time will
+ increase respective to the size of the queue times the average per-session
+ response time. When clients will wait for more than a few seconds, they will
+ often hit the "STOP" button on their browser, leaving a useless request in
+ the queue, and slowing down other users, and the servers as well, because the
+ request will eventually be served, then aborted at the first error
+ encountered while delivering the response.
- This is used to set the destination port address to the value of specified
- expression. If you want to connect to the new address/port, use '0.0.0.0:0'
- as a server address in the backend.
+ As there is no way to distinguish between a full STOP and a simple output
+ close on the client side, HTTP agents should be conservative and consider
+ that the client might only have closed its output channel while waiting for
+ the response. However, this introduces risks of congestion when lots of users
+ do the same, and is completely useless nowadays because probably no client at
+ all will close the session while waiting for the response. Some HTTP agents
+ support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
+ hardware-based load balancers). So the probability for a closed input channel
+ to represent a user hitting the "STOP" button is close to 100%, and the risk
+ of being the single component to break rare but valid traffic is extremely
+ low, which adds to the temptation to be able to abort a session early while
+ still not served and not pollute the servers.
- Arguments:
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ In HAProxy, the user can choose the desired behavior using the option
+ "abortonclose". By default (without the option) the behavior is HTTP
+ compliant and aborted requests will be served. But when the option is
+ specified, a session with an incoming channel closed will be aborted while
+ it is still possible, either pending in the queue for a connection slot, or
+ during the connection establishment if the server has not yet acknowledged
+ the connection request. This considerably reduces the queue size and the load
+ on saturated servers when users are tempted to click on STOP, which in turn
+ reduces the response time for other users.
- Example:
- http-request set-dst-port hdr(x-port)
- http-request set-dst-port int(4000)
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- When possible, set-dst-port preserves the original destination address as
- long as the address family supports a port, otherwise it forces the
- destination address to IPv4 "0.0.0.0" before rewriting the port.
+ See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
-http-request set-header <name> <fmt> [ { if | unless } <condition> ]
- This does the same as "http-request add-header" except that the header name
- is first removed if it existed. This is useful when passing security
- information to the server, where the header must not be manipulated by
- external users. Note that the new value is computed before the removal so it
- is possible to concatenate a value to an existing header.
+option accept-invalid-http-request
+no option accept-invalid-http-request
+ Enable or disable relaxing of HTTP request parsing
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- Example:
- http-request set-header X-Haproxy-Current-Date %T
- http-request set-header X-SSL %[ssl_fc]
- http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
- http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
- http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
- http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
- http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
- http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
- http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
+ By default, HAProxy complies with RFC7230 in terms of message parsing. This
+ means that invalid characters in header names are not permitted and cause an
+ error to be returned to the client. This is the desired behavior as such
+ forbidden characters are essentially used to build attacks exploiting server
+ weaknesses, and bypass security filtering. Sometimes, a buggy browser or
+ server will emit invalid header names for whatever reason (configuration,
+ implementation) and the issue will not be immediately fixed. In such a case,
+ it is possible to relax HAProxy's header name parser to accept any character
+ even if that does not make sense, by specifying this option. Similarly, the
+ list of characters allowed to appear in a URI is well defined by RFC3986, and
+ chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
+ ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
+ not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
+ remaining ones are blocked by default unless this option is enabled. This
+ option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
+ to pass through (no version specified), as well as different protocol names
+ (e.g. RTSP), and multiple digits for both the major and the minor version.
+ Finally, this option also allows incoming URLs to contain fragment references
+ ('#' after the path).
-http-request set-log-level <level> [ { if | unless } <condition> ]
+ This option should never be enabled by default as it hides application bugs
+ and open security breaches. It should only be deployed after a problem has
+ been confirmed.
- This is used to change the log level of the current request when a certain
- condition is met. Valid levels are the 8 syslog levels (see the "log"
- keyword) plus the special level "silent" which disables logging for this
- request. This rule is not final so the last matching rule wins. This rule
- can be useful to disable health checks coming from another equipment.
+ When this option is enabled, erroneous header names will still be accepted in
+ requests, but the complete request will be captured in order to permit later
+ analysis using the "show errors" request on the UNIX stats socket. Similarly,
+ requests containing invalid chars in the URI part will be logged. Doing this
+ also helps confirming that the issue has been solved.
-http-request set-map(<file-name>) <key fmt> <value fmt>
- [ { if | unless } <condition> ]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- This is used to add a new entry into a MAP. The MAP must be loaded from a
- file (even a dummy empty file). The file name of the MAP to be updated is
- passed between parentheses. It takes 2 arguments: <key fmt>, which follows
- log-format rules, used to collect MAP key, and <value fmt>, which follows
- log-format rules, used to collect content for the new entry.
- It performs a lookup in the MAP before insertion, to avoid duplicated (or
- more) values. It is the equivalent of the "set map" command from the
- stats socket, but can be triggered by an HTTP request.
+ See also : "option accept-invalid-http-response" and "show errors" on the
+ stats socket.
-http-request set-mark <mark> [ { if | unless } <condition> ]
- This is used to set the Netfilter/IPFW MARK on all packets sent to the client
- to the value passed in <mark> on platforms which support it. This value is an
- unsigned 32 bit value which can be matched by netfilter/ipfw and by the
- routing table or monitoring the packets through DTrace. It can be expressed
- both in decimal or hexadecimal format (prefixed by "0x").
- This can be useful to force certain packets to take a different route (for
- example a cheaper network path for bulk downloads). This works on Linux
- kernels 2.6.32 and above and requires admin privileges, as well on FreeBSD
- and OpenBSD.
+option accept-invalid-http-response
+no option accept-invalid-http-response
+ Enable or disable relaxing of HTTP response parsing
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
-http-request set-method <fmt> [ { if | unless } <condition> ]
+ By default, HAProxy complies with RFC7230 in terms of message parsing. This
+ means that invalid characters in header names are not permitted and cause an
+ error to be returned to the client. This is the desired behavior as such
+ forbidden characters are essentially used to build attacks exploiting server
+ weaknesses, and bypass security filtering. Sometimes, a buggy browser or
+ server will emit invalid header names for whatever reason (configuration,
+ implementation) and the issue will not be immediately fixed. In such a case,
+ it is possible to relax HAProxy's header name parser to accept any character
+ even if that does not make sense, by specifying this option. This option also
+ relaxes the test on the HTTP version format, it allows multiple digits for
+ both the major and the minor version.
- This rewrites the request method with the result of the evaluation of format
- string <fmt>. There should be very few valid reasons for having to do so as
- this is more likely to break something than to fix it.
+ This option should never be enabled by default as it hides application bugs
+ and open security breaches. It should only be deployed after a problem has
+ been confirmed.
-http-request set-nice <nice> [ { if | unless } <condition> ]
+ When this option is enabled, erroneous header names will still be accepted in
+ responses, but the complete response will be captured in order to permit
+ later analysis using the "show errors" request on the UNIX stats socket.
+ Doing this also helps confirming that the issue has been solved.
- This sets the "nice" factor of the current request being processed. It only
- has effect against the other requests being processed at the same time.
- The default value is 0, unless altered by the "nice" setting on the "bind"
- line. The accepted range is -1024..1024. The higher the value, the nicest
- the request will be. Lower values will make the request more important than
- other ones. This can be useful to improve the speed of some requests, or
- lower the priority of non-important requests. Using this setting without
- prior experimentation can cause some major slowdown.
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
-http-request set-path <fmt> [ { if | unless } <condition> ]
+ See also : "option accept-invalid-http-request" and "show errors" on the
+ stats socket.
- This rewrites the request path with the result of the evaluation of format
- string <fmt>. The query string, if any, is left intact. If a scheme and
- authority is found before the path, they are left intact as well. If the
- request doesn't have a path ("*"), this one is replaced with the format.
- This can be used to prepend a directory component in front of a path for
- example. See also "http-request set-query" and "http-request set-uri".
- Example :
- # prepend the host name before the path
- http-request set-path /%[hdr(host)]%[path]
+option allbackups
+no option allbackups
+ Use either all backup servers at a time or only the first one
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
-http-request set-pathq <fmt> [ { if | unless } <condition> ]
+ By default, the first operational backup server gets all traffic when normal
+ servers are all down. Sometimes, it may be preferred to use multiple backups
+ at once, because one will not be enough. When "option allbackups" is enabled,
+ the load balancing will be performed among all backup servers when all normal
+ ones are unavailable. The same load balancing algorithm will be used and the
+ servers' weights will be respected. Thus, there will not be any priority
+ order between the backup servers anymore.
- This does the same as "http-request set-path" except that the query-string is
- also rewritten. It may be used to remove the query-string, including the
- question mark (it is not possible using "http-request set-query").
+ This option is mostly used with static server farms dedicated to return a
+ "sorry" page when an application is completely offline.
-http-request set-priority-class <expr> [ { if | unless } <condition> ]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- This is used to set the queue priority class of the current request.
- The value must be a sample expression which converts to an integer in the
- range -2047..2047. Results outside this range will be truncated.
- The priority class determines the order in which queued requests are
- processed. Lower values have higher priority.
-http-request set-priority-offset <expr> [ { if | unless } <condition> ]
+option checkcache
+no option checkcache
+ Analyze all server responses and block responses with cacheable cookies
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- This is used to set the queue priority timestamp offset of the current
- request. The value must be a sample expression which converts to an integer
- in the range -524287..524287. Results outside this range will be truncated.
- When a request is queued, it is ordered first by the priority class, then by
- the current timestamp adjusted by the given offset in milliseconds. Lower
- values have higher priority.
- Note that the resulting timestamp is is only tracked with enough precision
- for 524,287ms (8m44s287ms). If the request is queued long enough to where the
- adjusted timestamp exceeds this value, it will be misidentified as highest
- priority. Thus it is important to set "timeout queue" to a value, where when
- combined with the offset, does not exceed this limit.
+ Some high-level frameworks set application cookies everywhere and do not
+ always let enough control to the developer to manage how the responses should
+ be cached. When a session cookie is returned on a cacheable object, there is a
+ high risk of session crossing or stealing between users traversing the same
+ caches. In some situations, it is better to block the response than to let
+ some sensitive session information go in the wild.
-http-request set-query <fmt> [ { if | unless } <condition> ]
+ The option "checkcache" enables deep inspection of all server responses for
+ strict compliance with HTTP specification in terms of cacheability. It
+ carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
+ response to check if there's a risk of caching a cookie on a client-side
+ proxy. When this option is enabled, the only responses which can be delivered
+ to the client are :
+ - all those without "Set-Cookie" header;
+ - all those with a return code other than 200, 203, 204, 206, 300, 301,
+ 404, 405, 410, 414, 501, provided that the server has not set a
+ "Cache-control: public" header field;
+ - all those that result from a request using a method other than GET, HEAD,
+ OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
+ public' header field;
+ - those with a 'Pragma: no-cache' header
+ - those with a 'Cache-control: private' header
+ - those with a 'Cache-control: no-store' header
+ - those with a 'Cache-control: max-age=0' header
+ - those with a 'Cache-control: s-maxage=0' header
+ - those with a 'Cache-control: no-cache' header
+ - those with a 'Cache-control: no-cache="set-cookie"' header
+ - those with a 'Cache-control: no-cache="set-cookie,' header
+ (allowing other fields after set-cookie)
- This rewrites the request's query string which appears after the first
- question mark ("?") with the result of the evaluation of format string <fmt>.
- The part prior to the question mark is left intact. If the request doesn't
- contain a question mark and the new value is not empty, then one is added at
- the end of the URI, followed by the new value. If a question mark was
- present, it will never be removed even if the value is empty. This can be
- used to add or remove parameters from the query string.
+ If a response doesn't respect these requirements, then it will be blocked
+ just as if it was from an "http-response deny" rule, with an "HTTP 502 bad
+ gateway". The session state shows "PH--" meaning that the proxy blocked the
+ response during headers processing. Additionally, an alert will be sent in
+ the logs so that admins are informed that there's something to be fixed.
- See also "http-request set-query" and "http-request set-uri".
+ Due to the high impact on the application, the application should be tested
+ in depth with the option enabled before going to production. It is also a
+ good practice to always activate it during tests, even if it is not used in
+ production, as it will report potentially dangerous application behaviors.
- Example:
- # replace "%3D" with "=" in the query string
- http-request set-query %[query,regsub(%3D,=,g)]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
-http-request set-src <expr> [ { if | unless } <condition> ]
- This is used to set the source IP address to the value of specified
- expression. Useful when a proxy in front of HAProxy rewrites source IP, but
- provides the correct IP in a HTTP header; or you want to mask source IP for
- privacy. All subsequent calls to "src" fetch will return this value
- (see example).
- Arguments :
- <expr> Is a standard HAProxy expression formed by a sample-fetch followed
- by some converters.
+option clitcpka
+no option clitcpka
+ Enable or disable the sending of TCP keepalive packets on the client side
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- See also "option forwardfor".
+ When there is a firewall or any session-aware component between a client and
+ a server, and when the protocol involves very long sessions with long idle
+ periods (e.g. remote desktops), there is a risk that one of the intermediate
+ components decides to expire a session which has remained idle for too long.
- Example:
- http-request set-src hdr(x-forwarded-for)
- http-request set-src src,ipmask(24)
+ Enabling socket-level TCP keep-alives makes the system regularly send packets
+ to the other end of the connection, leaving it active. The delay between
+ keep-alive probes is controlled by the system only and depends both on the
+ operating system and its tuning parameters.
- # After the masking this will track connections
- # based on the IP address with the last byte zeroed out.
- http-request track-sc0 src
+ It is important to understand that keep-alive packets are neither emitted nor
+ received at the application level. It is only the network stacks which sees
+ them. For this reason, even if one side of the proxy already uses keep-alives
+ to maintain its connection alive, those keep-alive packets will not be
+ forwarded to the other side of the proxy.
- When possible, set-src preserves the original source port as long as the
- address family allows it, otherwise the source port is set to 0.
+ Please note that this has nothing to do with HTTP keep-alive.
-http-request set-src-port <expr> [ { if | unless } <condition> ]
+ Using option "clitcpka" enables the emission of TCP keep-alive probes on the
+ client side of a connection, which should help when session expirations are
+ noticed between HAProxy and a client.
- This is used to set the source port address to the value of specified
- expression.
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- Arguments:
- <expr> Is a standard HAProxy expression formed by a sample-fetch followed
- by some converters.
+ See also : "option srvtcpka", "option tcpka"
- Example:
- http-request set-src-port hdr(x-port)
- http-request set-src-port int(4000)
- When possible, set-src-port preserves the original source address as long as
- the address family supports a port, otherwise it forces the source address to
- IPv4 "0.0.0.0" before rewriting the port.
+option contstats
+ Enable continuous traffic statistics updates
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
-http-request set-timeout { client | server | tunnel } { <timeout> | <expr> }
- [ { if | unless } <condition> ]
+ By default, counters used for statistics calculation are incremented
+ only when a session finishes. It works quite well when serving small
+ objects, but with big ones (for example large images or archives) or
+ with A/V streaming, a graph generated from HAProxy counters looks like
+ a hedgehog. With this option enabled counters get incremented frequently
+ along the session, typically every 5 seconds, which is often enough to
+ produce clean graphs. Recounting touches a hotpath directly so it is not
+ not enabled by default, as it can cause a lot of wakeups for very large
+ session counts and cause a small performance drop.
- This action overrides the specified "client", "server" or "tunnel" timeout for the
- current stream only. The timeout can be specified in millisecond or with any
- other unit if the number is suffixed by the unit as explained at the top of
- this document. It is also possible to write an expression which must returns
- a number interpreted as a timeout in millisecond.
+option disable-h2-upgrade
+no option disable-h2-upgrade
+ Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client
+ connection.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- Note that the server/tunnel timeouts are only relevant on the backend side
- and thus this rule is only available for the proxies with backend
- capabilities. As well as client timeout is only relevant for frontend side.
- Also the timeout value must be non-null to obtain the expected results.
+ By default, HAProxy is able to implicitly upgrade an HTTP/1.x client
+ connection to an HTTP/2 connection if the first request it receives from a
+ given HTTP connection matches the HTTP/2 connection preface (i.e. the string
+ "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"). This way, it is possible to support
+ HTTP/1.x and HTTP/2 clients on a non-SSL connections. This option must be
+ used to disable the implicit upgrade. Note this implicit upgrade is only
+ supported for HTTP proxies, thus this option too. Note also it is possible to
+ force the HTTP/2 on clear connections by specifying "proto h2" on the bind
+ line. Finally, this option is applied on all bind lines. To disable implicit
+ HTTP/2 upgrades for a specific bind line, it is possible to use "proto h1".
- Example:
- http-request set-timeout tunnel 5s
- http-request set-timeout server req.hdr(host),map_int(host.lst)
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
-http-request set-tos <tos> [ { if | unless } <condition> ]
+option dontlog-normal
+no option dontlog-normal
+ Enable or disable logging of normal, successful connections
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- This is used to set the TOS or DSCP field value of packets sent to the client
- to the value passed in <tos> on platforms which support this. This value
- represents the whole 8 bits of the IP TOS field, and can be expressed both in
- decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
- bits are used in DSCP or TOS, and the two lower bits are always 0. This can
- be used to adjust some routing behavior on border routers based on some
- information from the request.
+ There are large sites dealing with several thousand connections per second
+ and for which logging is a major pain. Some of them are even forced to turn
+ logs off and cannot debug production issues. Setting this option ensures that
+ normal connections, those which experience no error, no timeout, no retry nor
+ redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
+ mode, the response status code is checked and return codes 5xx will still be
+ logged.
- See RFC 2474, 2597, 3260 and 4594 for more information.
+ It is strongly discouraged to use this option as most of the time, the key to
+ complex issues is in the normal logs which will not be logged here. If you
+ need to separate logs, see the "log-separate-errors" option instead.
-http-request set-uri <fmt> [ { if | unless } <condition> ]
+ See also : "log", "dontlognull", "log-separate-errors" and section 8 about
+ logging.
- This rewrites the request URI with the result of the evaluation of format
- string <fmt>. The scheme, authority, path and query string are all replaced
- at once. This can be used to rewrite hosts in front of proxies, or to perform
- complex modifications to the URI such as moving parts between the path and
- the query string. If an absolute URI is set, it will be sent as is to
- HTTP/1.1 servers. If it is not the desired behavior, the host, the path
- and/or the query string should be set separately.
- See also "http-request set-path" and "http-request set-query".
-http-request set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-http-request set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
+option dontlognull
+no option dontlognull
+ Enable or disable logging of null connections
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- This is used to set the contents of a variable. The variable is declared
- inline.
+ In certain environments, there are components which will regularly connect to
+ various systems to ensure that they are still alive. It can be the case from
+ another load balancer as well as from monitoring systems. By default, even a
+ simple port probe or scan will produce a log. If those connections pollute
+ the logs too much, it is possible to enable option "dontlognull" to indicate
+ that a connection on which no data has been transferred will not be logged,
+ which typically corresponds to those probes. Note that errors will still be
+ returned to the client and accounted for in the stats. If this is not what is
+ desired, option http-ignore-probes can be used instead.
- Arguments:
- <var-name> The name of the variable starts with an indication about its
- scope. The scopes allowed are:
- "proc" : the variable is shared with the whole process
- "sess" : the variable is shared with the whole session
- "txn" : the variable is shared with the transaction
- (request and response)
- "req" : the variable is shared only during request
- processing
- "res" : the variable is shared only during response
- processing
- This prefix is followed by a name. The separator is a '.'.
- The name may only contain characters 'a-z', 'A-Z', '0-9'
- and '_'.
+ It is generally recommended not to use this option in uncontrolled
+ environments (e.g. internet), otherwise scans and other malicious activities
+ would not be logged.
- <cond> A set of conditions that must all be true for the variable to
- actually be set (such as "ifnotempty", "ifgt" ...). See the
- set-var converter's description for a full list of possible
- conditions.
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ See also : "log", "http-ignore-probes", "monitor-uri", and
+ section 8 about logging.
- <fmt> This is the value expressed using log-format rules (see Custom
- Log Format in section 8.2.4).
+option forwarded [ proto ]
+ [ host | host-expr <host_expr> ]
+ [ by | by-expr <by_expr> ] [ by_port | by_port-expr <by_port_expr>]
+ [ for | for-expr <for_expr> ] [ for_port | for_port-expr <for_port_expr>]
+no option forwarded
+ Enable insertion of the rfc 7239 forwarded header in requests sent to servers
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <host_expr> optional argument to specify a custom sample expression
+ those result will be used as 'host' parameter value
- Example:
- http-request set-var(req.my_var) req.fhdr(user-agent),lower
- http-request set-var-fmt(txn.from) %[src]:%[src_port]
+ <by_expr> optional argument to specicy a custom sample expression
+ those result will be used as 'by' parameter nodename value
-http-request silent-drop [ rst-ttl <ttl> ] [ { if | unless } <condition> ]
+ <for_expr> optional argument to specicy a custom sample expression
+ those result will be used as 'for' parameter nodename value
- This stops the evaluation of the rules and removes the client-facing
- connection in a configurable way: When called without the rst-ttl argument,
- we try to prevent sending any FIN or RST packet back to the client by
- using TCP_REPAIR. If this fails (mainly because of missing privileges),
- we fall back to sending a RST packet with a TTL of 1.
+ <by_port_expr> optional argument to specicy a custom sample expression
+ those result will be used as 'by' parameter nodeport value
- The effect is that the client still sees an established connection while
- there is none on HAProxy, saving resources. However, stateful equipment
- placed between the HAProxy and the client (firewalls, proxies,
- load balancers) will also keep the established connection in their
- session tables.
+ <for_port_expr> optional argument to specicy a custom sample expression
+ those result will be used as 'for' parameter nodeport value
- The optional rst-ttl changes this behaviour: TCP_REPAIR is not used,
- and a RST packet with a configurable TTL is sent. When set to a
- reasonable value, the RST packet travels through your own equipment,
- deleting the connection in your middle-boxes, but does not arrive at
- the client. Future packets from the client will then be dropped
- already by your middle-boxes. These "local RST"s protect your resources,
- but not the client's. Do not use it unless you fully understand how it works.
-http-request strict-mode { on | off } [ { if | unless } <condition> ]
+ Since HAProxy works in reverse-proxy mode, servers are losing some request
+ context (request origin: client ip address, protocol used...)
- This enables or disables the strict rewriting mode for following rules. It
- does not affect rules declared before it and it is only applicable on rules
- performing a rewrite on the requests. When the strict mode is enabled, any
- rewrite failure triggers an internal error. Otherwise, such errors are
- silently ignored. The purpose of the strict rewriting mode is to make some
- rewrites optional while others must be performed to continue the request
- processing.
+ A common way to address this limitation is to use the well known
+ x-forward-for and x-forward-* friends to expose some of this context to the
+ underlying servers/applications.
+ While this use to work and is widely deployed, it is not officially supported
+ by the IETF and can be the root of some interoperability as well as security
+ issues.
- By default, the strict rewriting mode is enabled. Its value is also reset
- when a ruleset evaluation ends. So, for instance, if you change the mode on
- the frontend, the default mode is restored when HAProxy starts the backend
- rules evaluation.
+ To solve this, a new HTTP extension has been described by the IETF:
+ forwarded header (RFC7239).
+ More information here: https://www.rfc-editor.org/rfc/rfc7239.html
-http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
-http-request tarpit [ { status | deny_status } <code>] [content-type <type>]
- [ { default-errorfiles | errorfile <file> | errorfiles <name> |
- file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
- [ hdr <name> <fmt> ]*
- [ { if | unless } <condition> ]
+ The use of this single header allow to convey numerous details
+ within the same header, and most importantly, fixes the proxy chaining
+ issue. (the rfc allows for multiple chained proxies to append their own
+ values to an already existing header).
- This stops the evaluation of the rules and immediately blocks the request
- without responding for a delay specified by "timeout tarpit" or
- "timeout connect" if the former is not set. After that delay, if the client
- is still connected, a response is returned so that the client does not
- suspect it has been tarpitted. Logs will report the flags "PT". The goal of
- the tarpit rule is to slow down robots during an attack when they're limited
- on the number of concurrent requests. It can be very efficient against very
- dumb robots, and will significantly reduce the load on firewalls compared to
- a "deny" rule. But when facing "correctly" developed robots, it can make
- things worse by forcing HAProxy and the front firewall to support insane
- number of concurrent connections. By default an HTTP error 500 is returned.
- But the response may be customized using same syntax than
- "http-request return" rules. Thus, see "http-request return" for details.
- For compatibility purpose, when no argument is defined, or only "deny_status",
- the argument "default-errorfiles" is implied. It means
- "http-request tarpit [deny_status <status>]" is an alias of
- "http-request tarpit [status <status>] default-errorfiles".
- No further "http-request" rules are evaluated.
- See also "http-request return" and "http-request silent-drop".
+ This option may be specified in defaults, listen or backend section, but it
+ will be ignored for frontend sections.
-http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
-http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
-http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
+ Setting option forwarded without arguments results in using default implicit
+ behavior.
+ Default behavior enables proto parameter and injects original client ip.
- This enables tracking of sticky counters from current request. These rules do
- not stop evaluation and do not change default action. The number of counters
- that may be simultaneously tracked by the same connection is set by the
- global "tune.stick-counters" setting, which defaults to MAX_SESS_STKCTR if
- set at build time (it is reported in haproxy -vv) and which defaults to 3,
- so the track-sc number is between 0 and (tune.stick-counters-1). The first
- "track-sc0" rule executed enables tracking of the counters of the specified
- table as the first set. The first "track-sc1" rule executed enables tracking
- of the counters of the specified table as the second set. The first
- "track-sc2" rule executed enables tracking of the counters of the specified
- table as the third set. It is a recommended practice to use the first set of
- counters for the per-frontend counters and the second set for the per-backend
- ones. But this is just a guideline, all may be used everywhere.
+ The equivalent explicit/manual configuration would be:
+ option forwarded proto for
- Arguments :
- <key> is mandatory, and is a sample expression rule as described in
- section 7.3. It describes what elements of the incoming request or
- connection will be analyzed, extracted, combined, and used to
- select which table entry to update the counters.
+ The keyword 'by' is used to enable 'by' parameter ("nodename") in
+ forwarded header. It allows to embed request proxy information.
+ 'by' value will be set to proxy ip (destination address)
+ If not available (ie: UNIX listener), 'by' will be set to
+ "unknown".
- <table> is an optional table to be used instead of the default one, which
- is the stick-table declared in the current proxy. All the counters
- for the matches and updates for the key will then be performed in
- that table until the session ends.
+ The keyword 'by-expr' is used to enable 'by' parameter ("nodename") in
+ forwarded header. It allows to embed request proxy information.
+ 'by' value will be set to the result of the sample expression
+ <by_expr>, if valid, otherwise it will be set to "unknown".
- Once a "track-sc*" rule is executed, the key is looked up in the table and if
- it is not found, an entry is allocated for it. Then a pointer to that entry
- is kept during all the session's life, and this entry's counters are updated
- as often as possible, every time the session's counters are updated, and also
- systematically when the session ends. Counters are only updated for events
- that happen after the tracking has been started. As an exception, connection
- counters and request counters are systematically updated so that they reflect
- useful information.
+ The keyword 'for' is used to enable 'for' parameter ("nodename") in
+ forwarded header. It allows to embed request client information.
+ 'for' value will be set to client ip (source address)
+ If not available (ie: UNIX listener), 'for' will be set to
+ "unknown".
- If the entry tracks concurrent connection counters, one connection is counted
- for as long as the entry is tracked, and the entry will not expire during
- that time. Tracking counters also provides a performance advantage over just
- checking the keys, because only one table lookup is performed for all ACL
- checks that make use of it.
+ The keyword 'for-expr' is used to enable 'for' parameter ("nodename") in
+ forwarded header. It allows to embed request client information.
+ 'for' value will be set to the result of the sample expression
+ <for_expr>, if valid, otherwise it will be set to "unknown".
-http-request unset-var(<var-name>) [ { if | unless } <condition> ]
+ The keyword 'by_port' is used to provide "nodeport" info to
+ 'by' parameter. 'by_port' requires 'by' or 'by-expr' to be set or
+ it will be ignored.
+ "nodeport" will be set to proxy (destination) port if available,
+ otherwise it will be ignored.
- This is used to unset a variable. See above for details about <var-name>.
+ The keyword 'by_port-expr' is used to provide "nodeport" info to
+ 'by' parameter. 'by_port-expr' requires 'by' or 'by-expr' to be set or
+ it will be ignored.
+ "nodeport" will be set to the result of the sample expression
+ <by_port_expr>, if valid, otherwise it will be ignored.
- Example:
- http-request unset-var(req.my_var)
+ The keyword 'for_port' is used to provide "nodeport" info to
+ 'for' parameter. 'for_port' requires 'for' or 'for-expr' to be set or
+ it will be ignored.
+ "nodeport" will be set to client (source) port if available,
+ otherwise it will be ignored.
-http-request use-service <service-name> [ { if | unless } <condition> ]
+ The keyword 'for_port-expr' is used to provide "nodeport" info to
+ 'for' parameter. 'for_port-expr' requires 'for' or 'for-expr' to be set or
+ it will be ignored.
+ "nodeport" will be set to the result of the sample expression
+ <for_port_expr>, if valid, otherwise it will be ignored.
- This directive executes the configured HTTP service to reply to the request
- and stops the evaluation of the rules. An HTTP service may choose to reply by
- sending any valid HTTP response or it may immediately close the connection
- without sending any response. Outside natives services, for instance the
- Prometheus exporter, it is possible to write your own services in Lua. No
- further "http-request" rules are evaluated.
+ Examples :
+ # Those servers want the ip address and protocol of the client request
+ # Resulting header would look like this:
+ # forwarded: proto=http;for=127.0.0.1
+ backend www_default
+ mode http
+ option forwarded
+ #equivalent to: option forwarded proto for
- Arguments :
- <service-name> is mandatory. It is the service to call
+ # Those servers want the requested host and hashed client ip address
+ # as well as client source port (you should use seed for xxh32 if ensuring
+ # ip privacy is a concern)
+ # Resulting header would look like this:
+ # forwarded: host="haproxy.org";for="_000000007F2F367E:60138"
+ backend www_host
+ mode http
+ option forwarded host for-expr src,xxh32,hex for_port
- Example:
- http-request use-service prometheus-exporter if { path /metrics }
+ # Those servers want custom data in host, for and by parameters
+ # Resulting header would look like this:
+ # forwarded: host="host.com";by=_haproxy;for="[::1]:10"
+ backend www_custom
+ mode http
+ option forwarded host-expr str(host.com) by-expr str(_haproxy) for for_port-expr int(10)
-http-request wait-for-body time <time> [ at-least <bytes> ]
- [ { if | unless } <condition> ]
+ # Those servers want random 'for' obfuscated identifiers for request
+ # tracing purposes while protecting sensitive IP information
+ # Resulting header would look like this:
+ # forwarded: for=_000000002B1F4D63
+ backend www_for_hide
+ mode http
+ option forwarded for-expr rand,hex
- This will delay the processing of the request waiting for the payload for at
- most <time> milliseconds. if "at-least" argument is specified, HAProxy stops
- to wait the payload when the first <bytes> bytes are received. 0 means no
- limit, it is the default value. Regardless the "at-least" argument value,
- HAProxy stops to wait if the whole payload is received or if the request
- buffer is full. This action may be used as a replacement to "option
- http-buffer-request".
+ See also : "option forwardfor", "option originalto"
+option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
+ Enable insertion of the X-Forwarded-For header to requests sent to servers
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
Arguments :
+ <network> is an optional argument used to disable this option for sources
+ matching <network>
+ <name> an optional argument to specify a different "X-Forwarded-For"
+ header name.
- <time> is mandatory. It is the maximum time to wait for the body. It
- follows the HAProxy time format and is expressed in milliseconds.
-
- <bytes> is optional. It is the minimum payload size to receive to stop to
- wait. It follows the HAProxy size format and is expressed in
- bytes.
+ Since HAProxy works in reverse-proxy mode, the servers see its IP address as
+ their client address. This is sometimes annoying when the client's IP address
+ is expected in server logs. To solve this problem, the well-known HTTP header
+ "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
+ This header contains a value representing the client's IP address. Since this
+ header is always appended at the end of the existing header list, the server
+ must be configured to always use the last occurrence of this header only. See
+ the server's manual to find how to enable use of this standard header. Note
+ that only the last occurrence of the header must be used, since it is really
+ possible that the client has already brought one.
- Example:
- http-request wait-for-body time 1s at-least 1k if METH_POST
+ The keyword "header" may be used to supply a different header name to replace
+ the default "X-Forwarded-For". This can be useful where you might already
+ have a "X-Forwarded-For" header from a different application (e.g. stunnel),
+ and you need preserve it. Also if your backend server doesn't use the
+ "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
+ require "X-Cluster-Client-IP").
- See also : "option http-buffer-request"
+ Sometimes, a same HAProxy instance may be shared between a direct client
+ access and a reverse-proxy access (for instance when an SSL reverse-proxy is
+ used to decrypt HTTPS traffic). It is possible to disable the addition of the
+ header for a known source address or network by adding the "except" keyword
+ followed by the network address. In this case, any source IP matching the
+ network will not cause an addition of this header. Most common uses are with
+ private networks or 127.0.0.1. IPv4 and IPv6 are both supported.
-http-request wait-for-handshake [ { if | unless } <condition> ]
+ Alternatively, the keyword "if-none" states that the header will only be
+ added if it is not present. This should only be used in perfectly trusted
+ environment, as this might cause a security issue if headers reaching HAProxy
+ are under the control of the end-user.
- This will delay the processing of the request until the SSL handshake
- happened. This is mostly useful to delay processing early data until we're
- sure they are valid.
+ This option may be specified either in the frontend or in the backend. If at
+ least one of them uses it, the header will be added. Note that the backend's
+ setting of the header subargument takes precedence over the frontend's if
+ both are defined. In the case of the "if-none" argument, if at least one of
+ the frontend or the backend does not specify it, it wants the addition to be
+ mandatory, so it wins.
+ Example :
+ # Public HTTP address also used by stunnel on the same machine
+ frontend www
+ mode http
+ option forwardfor except 127.0.0.1 # stunnel already adds the header
-http-response <action> <options...> [ { if | unless } <condition> ]
- Access control for Layer 7 responses
+ # Those servers want the IP Address in X-Client
+ backend www
+ mode http
+ option forwardfor header X-Client
- May be used in sections: defaults | frontend | listen | backend
- yes(!) | yes | yes | yes
+ See also : "option httpclose", "option http-server-close",
+ "option http-keep-alive"
- The http-response statement defines a set of rules which apply to layer 7
- processing. The rules are evaluated in their declaration order when they are
- met in a frontend, listen or backend section. Any rule may optionally be
- followed by an ACL-based condition, in which case it will only be evaluated
- if the condition is true. Since these rules apply on responses, the backend
- rules are applied first, followed by the frontend's rules.
-
- The first keyword is the rule's action. Several types of actions are
- supported:
- - add-acl(<file-name>) <key fmt>
- - add-header <name> <fmt>
- - allow
- - cache-store <name>
- - capture <sample> id <id>
- - del-acl(<file-name>) <key fmt>
- - del-header <name> [ -m <meth> ]
- - del-map(<file-name>) <key fmt>
- - deny [ { status | deny_status } <code>] ...
- - redirect <rule>
- - replace-header <name> <regex-match> <replace-fmt>
- - replace-value <name> <regex-match> <replace-fmt>
- - return [status <code>] [content-type <type>] ...
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - send-spoe-group <engine-name> <group-name>
- - set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
- - set-header <name> <fmt>
- - set-log-level <level>
- - set-map(<file-name>) <key fmt> <value fmt>
- - set-mark <mark>
- - set-nice <nice>
- - set-status <status> [reason <str>]
- - set-timeout { client | server | tunnel } { <timeout> | <expr> }
- - set-tos <tos>
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - silent-drop [ rst-ttl <ttl> ]
- - strict-mode { on | off }
- - track-sc0 <key> [table <table>]
- - track-sc1 <key> [table <table>]
- - track-sc2 <key> [table <table>]
- - unset-var(<var-name>)
- - wait-for-body time <time> [ at-least <bytes> ]
-
- The supported actions are described below.
-
- There is no limit to the number of http-response statements per instance.
- This directive is only available from named defaults sections, not anonymous
- ones. Rules defined in the defaults section are evaluated before ones in the
- associated proxy section. To avoid ambiguities, in this case the same
- defaults section cannot be used by proxies with the frontend capability and
- by proxies with the backend capability. It means a listen section cannot use
- a defaults section defining such rules.
+option h1-case-adjust-bogus-client
+no option h1-case-adjust-bogus-client
+ Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- Example:
- acl key_acl res.hdr(X-Acl-Key) -m found
+ There is no standard case for header names because, as stated in RFC7230,
+ they are case-insensitive. So applications must handle them in a case-
+ insensitive manner. But some bogus applications violate the standards and
+ erroneously rely on the cases most commonly used by browsers. This problem
+ becomes critical with HTTP/2 because all header names must be exchanged in
+ lower case, and HAProxy follows the same convention. All header names are
+ sent in lower case to clients and servers, regardless of the HTTP version.
- acl myhost hdr(Host) -f myhost.lst
+ When HAProxy receives an HTTP/1 response, its header names are converted to
+ lower case and manipulated and sent this way to the clients. If a client is
+ known to violate the HTTP standards and to fail to process a response coming
+ from HAProxy, it is possible to transform the lower case header names to a
+ different format when the response is formatted and sent to the client, by
+ enabling this option and specifying the list of headers to be reformatted
+ using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
+ must only be a temporary workaround for the time it takes the client to be
+ fixed, because clients which require such workarounds might be vulnerable to
+ content smuggling attacks and must absolutely be fixed.
- http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
- http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
+ Please note that this option will not affect standards-compliant clients.
- Example:
- acl value res.hdr(X-Value) -m found
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
+ See also: "option h1-case-adjust-bogus-server", "h1-case-adjust",
+ "h1-case-adjust-file".
- http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
- http-response del-map(map.lst) %[src] if ! value
- See also : "http-request", section 3.4 about userlists and section 7 about
- ACL usage.
+option h1-case-adjust-bogus-server
+no option h1-case-adjust-bogus-server
+ Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
-http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
+ There is no standard case for header names because, as stated in RFC7230,
+ they are case-insensitive. So applications must handle them in a case-
+ insensitive manner. But some bogus applications violate the standards and
+ erroneously rely on the cases most commonly used by browsers. This problem
+ becomes critical with HTTP/2 because all header names must be exchanged in
+ lower case, and HAProxy follows the same convention. All header names are
+ sent in lower case to clients and servers, regardless of the HTTP version.
- This is used to add a new entry into an ACL. Please refer to "http-request
- add-acl" for a complete description.
-
-http-response add-header <name> <fmt> [ { if | unless } <condition> ]
-
- This appends an HTTP header field whose name is specified in <name> and whose
- value is defined by <fmt>. Please refer to "http-request add-header" for a
- complete description.
-
-http-response allow [ { if | unless } <condition> ]
+ When HAProxy receives an HTTP/1 request, its header names are converted to
+ lower case and manipulated and sent this way to the servers. If a server is
+ known to violate the HTTP standards and to fail to process a request coming
+ from HAProxy, it is possible to transform the lower case header names to a
+ different format when the request is formatted and sent to the server, by
+ enabling this option and specifying the list of headers to be reformatted
+ using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
+ must only be a temporary workaround for the time it takes the server to be
+ fixed, because servers which require such workarounds might be vulnerable to
+ content smuggling attacks and must absolutely be fixed.
- This stops the evaluation of the rules and lets the response pass the check.
- No further "http-response" rules are evaluated for the current section.
+ Please note that this option will not affect standards-compliant servers.
-http-response cache-store <name> [ { if | unless } <condition> ]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- See section 6.2 about cache setup.
+ See also: "option h1-case-adjust-bogus-client", "h1-case-adjust",
+ "h1-case-adjust-file".
-http-response capture <sample> id <id> [ { if | unless } <condition> ]
- This captures sample expression <sample> from the response buffer, and
- converts it to a string. The resulting string is stored into the next
- response "capture" slot, so it will possibly appear next to some captured
- HTTP headers. It will then automatically appear in the logs, and it will be
- possible to extract it using sample fetch rules to feed it into headers or
- anything. Please check section 7.3 (Fetching samples) and "capture response
- header" for more information.
+option http-buffer-request
+no option http-buffer-request
+ Enable or disable waiting for whole HTTP request body before proceeding
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
- The keyword "id" is the id of the capture slot which is used for storing the
- string. The capture slot must be defined in an associated frontend.
- This is useful to run captures in backends. The slot id can be declared by a
- previous directive "http-response capture" or with the "declare capture"
- keyword.
+ It is sometimes desirable to wait for the body of an HTTP request before
+ taking a decision. This is what is being done by "balance url_param" for
+ example. The first use case is to buffer requests from slow clients before
+ connecting to the server. Another use case consists in taking the routing
+ decision based on the request body's contents. This option placed in a
+ frontend or backend forces the HTTP processing to wait until either the whole
+ body is received or the request buffer is full. It can have undesired side
+ effects with some applications abusing HTTP by expecting unbuffered
+ transmissions between the frontend and the backend, so this should definitely
+ not be used by default.
- When using this action in a backend, double check that the relevant
- frontend(s) have the required capture slots otherwise, this rule will be
- ignored at run time. This can't be detected at configuration parsing time
- due to HAProxy's ability to dynamically resolve backend name at runtime.
+ See also : "option http-no-delay", "timeout http-request",
+ "http-request wait-for-body"
-http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
- This is used to delete an entry from an ACL. Please refer to "http-request
- del-acl" for a complete description.
+option http-ignore-probes
+no option http-ignore-probes
+ Enable or disable logging of null connections and request timeouts
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
-http-response del-header <name> [ -m <meth> ] [ { if | unless } <condition> ]
+ Recently some browsers started to implement a "pre-connect" feature
+ consisting in speculatively connecting to some recently visited web sites
+ just in case the user would like to visit them. This results in many
+ connections being established to web sites, which end up in 408 Request
+ Timeout if the timeout strikes first, or 400 Bad Request when the browser
+ decides to close them first. These ones pollute the log and feed the error
+ counters. There was already "option dontlognull" but it's insufficient in
+ this case. Instead, this option does the following things :
+ - prevent any 400/408 message from being sent to the client if nothing
+ was received over a connection before it was closed;
+ - prevent any log from being emitted in this situation;
+ - prevent any error counter from being incremented
- This removes all HTTP header fields whose name is specified in <name>. Please
- refer to "http-request del-header" for a complete description.
+ That way the empty connection is silently ignored. Note that it is better
+ not to use this unless it is clear that it is needed, because it will hide
+ real problems. The most common reason for not receiving a request and seeing
+ a 408 is due to an MTU inconsistency between the client and an intermediary
+ element such as a VPN, which blocks too large packets. These issues are
+ generally seen with POST requests as well as GET with large cookies. The logs
+ are often the only way to detect them.
-http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- This is used to delete an entry from a MAP. Please refer to "http-request
- del-map" for a complete description.
+ See also : "log", "dontlognull", "errorfile", and section 8 about logging.
-http-response deny [deny_status <status>] [ { if | unless } <condition> ]
-http-response deny [ { status | deny_status } <code>] [content-type <type>]
- [ { default-errorfiles | errorfile <file> | errorfiles <name> |
- file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
- [ hdr <name> <fmt> ]*
- [ { if | unless } <condition> ]
- This stops the evaluation of the rules and immediately rejects the response.
- By default an HTTP 502 error is returned. But the response may be customized
- using same syntax than "http-response return" rules. Thus, see
- "http-response return" for details. For compatibility purpose, when no
- argument is defined, or only "deny_status", the argument "default-errorfiles"
- is implied. It means "http-response deny [deny_status <status>]" is an alias
- of "http-response deny [status <status>] default-errorfiles".
- No further "http-response" rules are evaluated.
- See also "http-response return".
+option http-keep-alive
+no option http-keep-alive
+ Enable or disable HTTP keep-alive from client to server for HTTP/1.x
+ connections
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
-http-response redirect <rule> [ { if | unless } <condition> ]
+ By default HAProxy operates in keep-alive mode with regards to persistent
+ HTTP/1.x connections: for each connection it processes each request and
+ response, and leaves the connection idle on both sides. This mode may be
+ changed by several options such as "option http-server-close" or "option
+ httpclose". This option allows to set back the keep-alive mode, which can be
+ useful when another mode was used in a defaults section.
- This performs an HTTP redirection based on a redirect rule.
- This supports a format string similarly to "http-request redirect" rules,
- with the exception that only the "location" type of redirect is possible on
- the response. See the "redirect" keyword for the rule's syntax. When a
- redirect rule is applied during a response, connections to the server are
- closed so that no data can be forwarded from the server to the client.
+ Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
+ and server- sides. This provides the lowest latency on the client side (slow
+ network) and the fastest session reuse on the server side at the expense
+ of maintaining idle connections to the servers. In general, it is possible
+ with this option to achieve approximately twice the request rate that the
+ "http-server-close" option achieves on small objects. There are mainly two
+ situations where this option may be useful :
-http-response replace-header <name> <regex-match> <replace-fmt>
- [ { if | unless } <condition> ]
+ - when the server is non-HTTP compliant and authenticates the connection
+ instead of requests (e.g. NTLM authentication)
- This works like "http-request replace-header" except that it works on the
- server's response instead of the client's request.
+ - when the cost of establishing the connection to the server is significant
+ compared to the cost of retrieving the associated object from the server.
- Example:
- http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
+ This last case can happen when the server is a fast static server of cache.
- # applied to:
- Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
+ At the moment, logs will not indicate whether requests came from the same
+ session or not. The accept date reported in the logs corresponds to the end
+ of the previous request, and the request time corresponds to the time spent
+ waiting for a new request. The keep-alive request time is still bound to the
+ timeout defined by "timeout http-keep-alive" or "timeout http-request" if
+ not set.
- # outputs:
- Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
+ This option disables and replaces any previous "option httpclose" or "option
+ http-server-close".
- # assuming the backend IP is 192.168.1.20.
+ See also : "option httpclose",, "option http-server-close",
+ "option prefer-last-server" and "option http-pretend-keepalive".
-http-response replace-value <name> <regex-match> <replace-fmt>
- [ { if | unless } <condition> ]
- This works like "http-request replace-value" except that it works on the
- server's response instead of the client's request.
+option http-no-delay
+no option http-no-delay
+ Instruct the system to favor low interactive delays over performance in HTTP
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
- Example:
- http-response replace-value Cache-control ^public$ private
+ In HTTP, each payload is unidirectional and has no notion of interactivity.
+ Any agent is expected to queue data somewhat for a reasonably low delay.
+ There are some very rare server-to-server applications that abuse the HTTP
+ protocol and expect the payload phase to be highly interactive, with many
+ interleaved data chunks in both directions within a single request. This is
+ absolutely not supported by the HTTP specification and will not work across
+ most proxies or servers. When such applications attempt to do this through
+ HAProxy, it works but they will experience high delays due to the network
+ optimizations which favor performance by instructing the system to wait for
+ enough data to be available in order to only send full packets. Typical
+ delays are around 200 ms per round trip. Note that this only happens with
+ abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
+ affected.
- # applied to:
- Cache-Control: max-age=3600, public
+ When "option http-no-delay" is present in either the frontend or the backend
+ used by a connection, all such optimizations will be disabled in order to
+ make the exchanges as fast as possible. Of course this offers no guarantee on
+ the functionality, as it may break at any other place. But if it works via
+ HAProxy, it will work as fast as possible. This option should never be used
+ by default, and should never be used at all unless such a buggy application
+ is discovered. The impact of using this option is an increase of bandwidth
+ usage and CPU usage, which may significantly lower performance in high
+ latency environments.
- # outputs:
- Cache-Control: max-age=3600, private
+ See also : "option http-buffer-request"
-http-response return [status <code>] [content-type <type>]
- [ { default-errorfiles | errorfile <file> | errorfiles <name> |
- file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
- [ hdr <name> <value> ]*
- [ { if | unless } <condition> ]
- This stops the evaluation of the rules and immediately returns a
- response. Please refer to "http-request return" for a complete
- description. No further "http-response" rules are evaluated.
+option http-pretend-keepalive
+no option http-pretend-keepalive
+ Define whether HAProxy will announce keepalive for HTTP/1.x connection to the
+ server or not
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
-http-response sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ When running with "option http-server-close" or "option httpclose", HAProxy
+ adds a "Connection: close" header to the HTTP/1.x request forwarded to the
+ server. Unfortunately, when some servers see this header, they automatically
+ refrain from using the chunked encoding for responses of unknown length,
+ while this is totally unrelated. The effect is that a client or a cache could
+ receive an incomplete response without being aware of it, and consider the
+ response complete.
- This action increments the General Purpose Counter according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-add-gpc" for
- a complete description.
+ By setting "option http-pretend-keepalive", HAProxy will make the server
+ believe it will keep the connection alive. The server will then not fall back
+ to the abnormal undesired above. When HAProxy gets the whole response, it
+ will close the connection with the server just as it would do with the
+ "option httpclose". That way the client gets a normal response and the
+ connection is correctly closed on the server side.
-http-response sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
-http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
+ It is recommended not to enable this option by default, because most servers
+ will more efficiently close the connection themselves after the last packet,
+ and release its buffers slightly earlier. Also, the added packet on the
+ network could slightly reduce the overall peak performance. However it is
+ worth noting that when this option is enabled, HAProxy will have slightly
+ less work to do. So if HAProxy is the bottleneck on the whole architecture,
+ enabling this option might save a few CPU cycles.
- These actions increment the General Purppose Counters according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-inc-gpc",
- "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete
- description.
+ This option may be set in backend and listen sections. Using it in a frontend
+ section will be ignored and a warning will be reported during startup. It is
+ a backend related option, so there is no real reason to set it on a
+ frontend.
-http-response sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-http-response sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- These actions set the 32-bit unsigned General Purpose Tags according to the
- sticky counter designated by <sc-id>. Please refer to "http-request
- sc-set-gpt" and "http-request sc-set-gpt0" for a complete description.
+ See also : "option httpclose", "option http-server-close", and
+ "option http-keep-alive"
-http-response send-spoe-group <engine-name> <group-name>
- [ { if | unless } <condition> ]
+option http-restrict-req-hdr-names { preserve | delete | reject }
+ Set HAProxy policy about HTTP request header names containing characters
+ outside the "[a-zA-Z0-9-]" charset
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments :
+ preserve disable the filtering. It is the default mode for HTTP proxies
+ with no FastCGI application configured.
- This action is used to trigger sending of a group of SPOE messages. Please
- refer to "http-request send-spoe-group" for a complete description.
+ delete remove request headers with a name containing a character
+ outside the "[a-zA-Z0-9-]" charset. It is the default mode for
+ HTTP backends with a configured FastCGI application.
-http-response set-bandwidth-limit <name> [limit { <expr> | <size> }]
- [period { <expr> | <time> }] [ { if | unless } <condition> ]
+ reject reject the request with a 403-Forbidden response if it contains a
+ header name with a character outside the "[a-zA-Z0-9-]" charset.
- This action is used to enable the bandwidth limitation filter <name>, either
- on the upload or download direction depending on the filter type. Please
- refer to "http-request set-bandwidth-limit" for a complete description.
+ This option may be used to restrict the request header names to alphanumeric
+ and hyphen characters ([A-Za-z0-9-]). This may be mandatory to interoperate
+ with non-HTTP compliant servers that fail to handle some characters in header
+ names. It may also be mandatory for FastCGI applications because all
+ non-alphanumeric characters in header names are replaced by an underscore
+ ('_'). Thus, it is easily possible to mix up header names and bypass some
+ rules. For instance, "X-Forwarded-For" and "X_Forwarded-For" headers are both
+ converted to "HTTP_X_FORWARDED_FOR" in FastCGI.
-http-response set-header <name> <fmt> [ { if | unless } <condition> ]
+ Note this option is evaluated per proxy and after the http-request rules
+ evaluation.
- This does the same as "http-response add-header" except that the header name
- is first removed if it existed. This is useful when passing security
- information to the server, where the header must not be manipulated by
- external users.
+option http-server-close
+no option http-server-close
+ Enable or disable HTTP/1.x connection closing on the server side
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
-http-response set-log-level <level> [ { if | unless } <condition> ]
+ By default HAProxy operates in keep-alive mode with regards to persistent
+ HTTP/1.x connections: for each connection it processes each request and
+ response, and leaves the connection idle on both sides. This mode may be
+ changed by several options such as "option http-server-close" or "option
+ httpclose". Setting "option http-server-close" enables HTTP connection-close
+ mode on the server side while keeping the ability to support HTTP keep-alive
+ and pipelining on the client side. This provides the lowest latency on the
+ client side (slow network) and the fastest session reuse on the server side
+ to save server resources, similarly to "option httpclose". It also permits
+ non-keepalive capable servers to be served in keep-alive mode to the clients
+ if they conform to the requirements of RFC7230. Please note that some servers
+ do not always conform to those requirements when they see "Connection: close"
+ in the request. The effect will be that keep-alive will never be used. A
+ workaround consists in enabling "option http-pretend-keepalive".
- This is used to change the log level of the current response. Please refer to
- "http-request set-log-level" for a complete description.
+ At the moment, logs will not indicate whether requests came from the same
+ session or not. The accept date reported in the logs corresponds to the end
+ of the previous request, and the request time corresponds to the time spent
+ waiting for a new request. The keep-alive request time is still bound to the
+ timeout defined by "timeout http-keep-alive" or "timeout http-request" if
+ not set.
-http-response set-map(<file-name>) <key fmt> <value fmt>
+ This option may be set both in a frontend and in a backend. It is enabled if
+ at least one of the frontend or backend holding a connection has it enabled.
+ It disables and replaces any previous "option httpclose" or "option
+ http-keep-alive". Please check section 4 ("Proxies") to see how this option
+ combines with others when frontend and backend options differ.
- This is used to add a new entry into a MAP. Please refer to "http-request
- set-map" for a complete description.
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
-http-response set-mark <mark> [ { if | unless } <condition> ]
+ See also : "option httpclose", "option http-pretend-keepalive" and
+ "option http-keep-alive".
- This action is used to set the Netfilter/IPFW MARK in all packets sent to the
- client to the value passed in <mark> on platforms which support it. Please
- refer to "http-request set-mark" for a complete description.
+option http-use-proxy-header
+no option http-use-proxy-header
+ Make use of non-standard Proxy-Connection header instead of Connection
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
-http-response set-nice <nice> [ { if | unless } <condition> ]
+ While RFC7230 explicitly states that HTTP/1.1 agents must use the
+ Connection header to indicate their wish of persistent or non-persistent
+ connections, both browsers and proxies ignore this header for proxied
+ connections and make use of the undocumented, non-standard Proxy-Connection
+ header instead. The issue begins when trying to put a load balancer between
+ browsers and such proxies, because there will be a difference between what
+ HAProxy understands and what the client and the proxy agree on.
- This sets the "nice" factor of the current request being processed. Please
- refer to "http-request set-nice" for a complete description.
+ By setting this option in a frontend, HAProxy can automatically switch to use
+ that non-standard header if it sees proxied requests. A proxied request is
+ defined here as one where the URI begins with neither a '/' nor a '*'. This
+ is incompatible with the HTTP tunnel mode. Note that this option can only be
+ specified in a frontend and will affect the request along its whole life.
-http-response set-status <status> [reason <str>]
- [ { if | unless } <condition> ]
-
- This replaces the response status code with <status> which must be an integer
- between 100 and 999. Optionally, a custom reason text can be provided defined
- by <str>, or the default reason for the specified code will be used as a
- fallback.
+ Also, when this option is set, a request which requires authentication will
+ automatically switch to use proxy authentication headers if it is itself a
+ proxied request. That makes it possible to check or enforce authentication in
+ front of an existing proxy.
- Example:
- # return "431 Request Header Fields Too Large"
- http-response set-status 431
- # return "503 Slow Down", custom reason
- http-response set-status 503 reason "Slow Down".
+ This option should normally never be used, except in front of a proxy.
-http-response set-timeout { client | server | tunnel } { <timeout> | <expr> }
- [ { if | unless } <condition> ]
+ See also : "option httpclose", and "option http-server-close".
- This action overrides the specified "client", "server" or "tunnel" timeout for the
- current stream only. The timeout can be specified in millisecond or with any
- other unit if the number is suffixed by the unit as explained at the top of
- this document. It is also possible to write an expression which must returns
- a number interpreted as a timeout in millisecond.
+option httpchk
+option httpchk <uri>
+option httpchk <method> <uri>
+option httpchk <method> <uri> <version>
+ Enables HTTP protocol to check on the servers health
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <method> is the optional HTTP method used with the requests. When not set,
+ the "OPTIONS" method is used, as it generally requires low server
+ processing and is easy to filter out from the logs. Any method
+ may be used, though it is not recommended to invent non-standard
+ ones.
- Note that the server/tunnel timeouts are only relevant on the backend side
- and thus this rule is only available for the proxies with backend
- capabilities. As well as client timeout is only relevant for frontend side.
- Also the timeout value must be non-null to obtain the expected results.
+ <uri> is the URI referenced in the HTTP requests. It defaults to " / "
+ which is accessible by default on almost any server, but may be
+ changed to any other URI. Query strings are permitted.
- Example:
- http-response set-timeout tunnel 5s
- http-response set-timeout server res.hdr(X-Refresh-Seconds),mul(1000)
+ <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
+ but some servers might behave incorrectly in HTTP 1.0, so turning
+ it to HTTP/1.1 may sometimes help. Note that the Host field is
+ mandatory in HTTP/1.1, use "http-check send" directive to add it.
-http-response set-tos <tos> [ { if | unless } <condition> ]
+ By default, server health checks only consist in trying to establish a TCP
+ connection. When "option httpchk" is specified, a complete HTTP request is
+ sent once the TCP connection is established, and responses 2xx and 3xx are
+ considered valid, while all other ones indicate a server failure, including
+ the lack of any response.
- This is used to set the TOS or DSCP field value of packets sent to the client
- to the value passed in <tos> on platforms which support this. Please refer to
- "http-request set-tos" for a complete description.
+ Combined with "http-check" directives, it is possible to customize the
+ request sent during the HTTP health checks or the matching rules on the
+ response. It is also possible to configure a send/expect sequence, just like
+ with the directive "tcp-check" for TCP health checks.
-http-response set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-http-response set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
+ The server configuration is used by default to open connections to perform
+ HTTP health checks. By it is also possible to overwrite server parameters
+ using "http-check connect" rules.
- This is used to set the contents of a variable. The variable is declared
- inline. Please refer to "http-request set-var" and "http-request set-var-fmt"
- for a complete description.
+ "httpchk" option does not necessarily require an HTTP backend, it also works
+ with plain TCP backends. This is particularly useful to check simple scripts
+ bound to some dedicated ports using the inetd daemon. However, it will always
+ internally relies on an HTX multiplexer. Thus, it means the request
+ formatting and the response parsing will be strict.
-http-response silent-drop [ rst-ttl <ttl> ] [ { if | unless } <condition> ]
+ Examples :
+ # Relay HTTPS traffic to Apache instance and check service availability
+ # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
+ backend https_relay
+ mode tcp
+ option httpchk OPTIONS * HTTP/1.1
+ http-check send hdr Host www
+ server apache1 192.168.1.1:443 check port 80
- This stops the evaluation of the rules and makes the client-facing connection
- suddenly disappear using a system-dependent way that tries to prevent the
- client from being notified. Please refer to "http-request silent-drop" for a
- complete description.
+ See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
+ "option pgsql-check", "http-check" and the "check", "port" and
+ "inter" server options.
-http-response strict-mode { on | off } [ { if | unless } <condition> ]
- This enables or disables the strict rewriting mode for following
- rules. Please refer to "http-request strict-mode" for a complete description.
+option httpclose
+no option httpclose
+ Enable or disable HTTP/1.x connection closing
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
-http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
-http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
-http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
+ By default HAProxy operates in keep-alive mode with regards to persistent
+ HTTP/1.x connections: for each connection it processes each request and
+ response, and leaves the connection idle on both sides. This mode may be
+ changed by several options such as "option http-server-close" or "option
+ httpclose".
- This enables tracking of sticky counters from current connection. Please
- refer to "http-request track-sc0", "http-request track-sc1" and "http-request
- track-sc2" for a complete description.
+ If "option httpclose" is set, HAProxy will close the client or the server
+ connection, depending where the option is set. The frontend is considered for
+ client connections while the backend is considered for server ones. If the
+ option is set on a listener, it is applied both on client and server
+ connections. It will check if a "Connection: close" header is already set in
+ each direction, and will add one if missing.
-http-response unset-var(<var-name>) [ { if | unless } <condition> ]
+ This option may also be combined with "option http-pretend-keepalive", which
+ will disable sending of the "Connection: close" request header, but will
+ still cause the connection to be closed once the whole response is received.
- This is used to unset a variable. See "http-request set-var" for details
- about <var-name>.
+ It disables and replaces any previous "option http-server-close" or "option
+ http-keep-alive".
-http-response wait-for-body time <time> [ at-least <bytes> ]
- [ { if | unless } <condition> ]
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- This will delay the processing of the response waiting for the payload for at
- most <time> milliseconds. Please refer to "http-request wait-for-body" for a
- complete description.
+ See also : "option http-server-close".
-http-reuse { never | safe | aggressive | always }
- Declare how idle HTTP connections may be shared between requests
+option httplog [ clf ]
+ Enable logging of HTTP request, session state and timers
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments :
+ clf if the "clf" argument is added, then the output format will be
+ the CLF format instead of HAProxy's default HTTP format. You can
+ use this when you need to feed HAProxy's logs through a specific
+ log analyzer which only support the CLF format and which is not
+ extensible.
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+ By default, the log output format is very poor, as it only contains the
+ source and destination addresses, and the instance name. By specifying
+ "option httplog", each log line turns into a much richer format including,
+ but not limited to, the HTTP request, the connection timers, the session
+ status, the connections numbers, the captured headers and cookies, the
+ frontend, backend and server name, and of course the source address and
+ ports.
- By default, a connection established between HAProxy and the backend server
- which is considered safe for reuse is moved back to the server's idle
- connections pool so that any other request can make use of it. This is the
- "safe" strategy below.
+ Specifying only "option httplog" will automatically clear the 'clf' mode
+ if it was set by default.
- The argument indicates the desired connection reuse strategy :
+ "option httplog" overrides any previous "log-format" directive.
- - "never" : idle connections are never shared between sessions. This mode
- may be enforced to cancel a different strategy inherited from
- a defaults section or for troubleshooting. For example, if an
- old bogus application considers that multiple requests over
- the same connection come from the same client and it is not
- possible to fix the application, it may be desirable to
- disable connection sharing in a single backend. An example of
- such an application could be an old HAProxy using cookie
- insertion in tunnel mode and not checking any request past the
- first one.
+ See also : section 8 about logging.
- - "safe" : this is the default and the recommended strategy. The first
- request of a session is always sent over its own connection,
- and only subsequent requests may be dispatched over other
- existing connections. This ensures that in case the server
- closes the connection when the request is being sent, the
- browser can decide to silently retry it. Since it is exactly
- equivalent to regular keep-alive, there should be no side
- effects. There is also a special handling for the connections
- using protocols subject to Head-of-line blocking (backend with
- h2 or fcgi). In this case, when at least one stream is
- processed, the used connection is reserved to handle streams
- of the same session. When no more streams are processed, the
- connection is released and can be reused.
+option httpslog
+ Enable logging of HTTPS request, session state and timers
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
- - "aggressive" : this mode may be useful in webservices environments where
- all servers are not necessarily known and where it would be
- appreciable to deliver most first requests over existing
- connections. In this case, first requests are only delivered
- over existing connections that have been reused at least once,
- proving that the server correctly supports connection reuse.
- It should only be used when it's sure that the client can
- retry a failed request once in a while and where the benefit
- of aggressive connection reuse significantly outweighs the
- downsides of rare connection failures.
+ By default, the log output format is very poor, as it only contains the
+ source and destination addresses, and the instance name. By specifying
+ "option httpslog", each log line turns into a much richer format including,
+ but not limited to, the HTTP request, the connection timers, the session
+ status, the connections numbers, the captured headers and cookies, the
+ frontend, backend and server name, the SSL certificate verification and SSL
+ handshake statuses, and of course the source address and ports.
- - "always" : this mode is only recommended when the path to the server is
- known for never breaking existing connections quickly after
- releasing them. It allows the first request of a session to be
- sent to an existing connection. This can provide a significant
- performance increase over the "safe" strategy when the backend
- is a cache farm, since such components tend to show a
- consistent behavior and will benefit from the connection
- sharing. It is recommended that the "http-keep-alive" timeout
- remains low in this mode so that no dead connections remain
- usable. In most cases, this will lead to the same performance
- gains as "aggressive" but with more risks. It should only be
- used when it improves the situation over "aggressive".
+ "option httpslog" overrides any previous "log-format" directive.
- When http connection sharing is enabled, a great care is taken to respect the
- connection properties and compatibility. Indeed, some properties are specific
- and it is not possibly to reuse it blindly. Those are the SSL SNI, source
- and destination address and proxy protocol block. A connection is reused only
- if it shares the same set of properties with the request.
+ See also : section 8 about logging.
- Also note that connections with certain bogus authentication schemes (relying
- on the connection) like NTLM are marked private and never shared.
- A connection pool is involved and configurable with "pool-max-conn".
+option independent-streams
+no option independent-streams
+ Enable or disable independent timeout processing for both directions
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
- Note: connection reuse improves the accuracy of the "server maxconn" setting,
- because almost no new connection will be established while idle connections
- remain available. This is particularly true with the "always" strategy.
+ By default, when data is sent over a socket, both the write timeout and the
+ read timeout for that socket are refreshed, because we consider that there is
+ activity on that socket, and we have no other means of guessing if we should
+ receive data or not.
- The rules to decide to keep an idle connection opened or to close it after
- processing are also governed by the "tune.pool-low-fd-ratio" (default: 20%)
- and "tune.pool-high-fd-ratio" (default: 25%). These correspond to the
- percentage of total file descriptors spent in idle connections above which
- haproxy will respectively refrain from keeping a connection opened after a
- response, and actively kill idle connections. Some setups using a very high
- ratio of idle connections, either because of too low a global "maxconn", or
- due to a lot of HTTP/2 or HTTP/3 traffic on the frontend (few connections)
- but HTTP/1 connections on the backend, may observe a lower reuse rate because
- too few connections are kept open. It may be desirable in this case to adjust
- such thresholds or simply to increase the global "maxconn" value.
+ While this default behavior is desirable for almost all applications, there
+ exists a situation where it is desirable to disable it, and only refresh the
+ read timeout if there are incoming data. This happens on sessions with large
+ timeouts and low amounts of exchanged data such as telnet session. If the
+ server suddenly disappears, the output data accumulates in the system's
+ socket buffers, both timeouts are correctly refreshed, and there is no way
+ to know the server does not receive them, so we don't timeout. However, when
+ the underlying protocol always echoes sent data, it would be enough by itself
+ to detect the issue using the read timeout. Note that this problem does not
+ happen with more verbose protocols because data won't accumulate long in the
+ socket buffers.
- Similarly, when thread groups are explicitly enabled, it is important to
- understand that idle connections are only usable between threads from a same
- group. As such it may happen that unfair load between groups leads to more
- idle connections being needed, causing a lower reuse rate. The same solution
- may then be applied (increase global "maxconn" or increase pool ratios).
+ When this option is set on the frontend, it will disable read timeout updates
+ on data sent to the client. There probably is little use of this case. When
+ the option is set on the backend, it will disable read timeout updates on
+ data sent to the server. Doing so will typically break large HTTP posts from
+ slow lines, so use it with caution.
- See also : "option http-keep-alive", "server maxconn", "thread-groups",
- "tune.pool-high-fd-ratio", "tune.pool-low-fd-ratio"
+ See also : "timeout client", "timeout server" and "timeout tunnel"
-http-send-name-header [<header>]
- Add the server name to a request. Use the header string given by <header>
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <header> The header string to use to send the server name
+option ldap-check
+ Use LDAPv3 health checks for server testing
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- The "http-send-name-header" statement causes the header field named <header>
- to be set to the name of the target server at the moment the request is about
- to be sent on the wire. Any existing occurrences of this header are removed.
- Upon retries and redispatches, the header field is updated to always reflect
- the server being attempted to connect to. Given that this header is modified
- very late in the connection setup, it may have unexpected effects on already
- modified headers. For example using it with transport-level header such as
- connection, content-length, transfer-encoding and so on will likely result in
- invalid requests being sent to the server. Additionally it has been reported
- that this directive is currently being used as a way to overwrite the Host
- header field in outgoing requests; while this trick has been known to work
- as a side effect of the feature for some time, it is not officially supported
- and might possibly not work anymore in a future version depending on the
- technical difficulties this feature induces. A long-term solution instead
- consists in fixing the application which required this trick so that it binds
- to the correct host name.
+ It is possible to test that the server correctly talks LDAPv3 instead of just
+ testing that it accepts the TCP connection. When this option is set, an
+ LDAPv3 anonymous simple bind message is sent to the server, and the response
+ is analyzed to find an LDAPv3 bind response message.
- See also : "server"
+ The server is considered valid only when the LDAP response contains success
+ resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
-id <value>
- Set a persistent ID to a proxy.
- May be used in sections : defaults | frontend | listen | backend
- no | yes | yes | yes
- Arguments : none
+ Logging of bind requests is server dependent see your documentation how to
+ configure it.
- Set a persistent ID for the proxy. This ID must be unique and positive.
- An unused ID will automatically be assigned if unset. The first assigned
- value will be 1. This ID is currently only returned in statistics.
+ Example :
+ option ldap-check
+ See also : "option httpchk"
-ignore-persist { if | unless } <condition>
- Declare a condition to ignore persistence
- May be used in sections: defaults | frontend | listen | backend
- no | no | yes | yes
- By default, when cookie persistence is enabled, every requests containing
- the cookie are unconditionally persistent (assuming the target server is up
- and running).
+option external-check
+ Use external processes for server health checks
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
- The "ignore-persist" statement allows one to declare various ACL-based
- conditions which, when met, will cause a request to ignore persistence.
- This is sometimes useful to load balance requests for static files, which
- often don't require persistence. This can also be used to fully disable
- persistence for a specific User-Agent (for example, some web crawler bots).
+ It is possible to test the health of a server using an external command.
+ This is achieved by running the executable set using "external-check
+ command".
- The persistence is ignored when an "if" condition is met, or unless an
- "unless" condition is met.
+ Requires the "external-check" global to be set.
- Example:
- acl url_static path_beg /static /images /img /css
- acl url_static path_end .gif .png .jpg .css .js
- ignore-persist if url_static
+ See also : "external-check", "external-check command", "external-check path"
- See also : "force-persist", "cookie", and section 7 about ACL usage.
-load-server-state-from-file { global | local | none }
- Allow seamless reload of HAProxy
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+option idle-close-on-response
+no option idle-close-on-response
+ Avoid closing idle frontend connections if a soft stop is in progress
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- This directive points HAProxy to a file where server state from previous
- running process has been saved. That way, when starting up, before handling
- traffic, the new process can apply old states to servers exactly has if no
- reload occurred. The purpose of the "load-server-state-from-file" directive is
- to tell HAProxy which file to use. For now, only 2 arguments to either prevent
- loading state or load states from a file containing all backends and servers.
- The state file can be generated by running the command "show servers state"
- over the stats socket and redirect output.
+ By default, idle connections will be closed during a soft stop. In some
+ environments, a client talking to the proxy may have prepared some idle
+ connections in order to send requests later. If there is no proper retry on
+ write errors, this can result in errors while haproxy is reloading. Even
+ though a proper implementation should retry on connection/write errors, this
+ option was introduced to support backwards compatibility with haproxy prior
+ to version 2.4. Indeed before v2.4, haproxy used to wait for a last request
+ and response to add a "connection: close" header before closing, thus
+ notifying the client that the connection would not be reusable.
- The format of the file is versioned and is very specific. To understand it,
- please read the documentation of the "show servers state" command (chapter
- 9.3 of Management Guide).
+ In a real life example, this behavior was seen in AWS using the ALB in front
+ of a haproxy. The end result was ALB sending 502 during haproxy reloads.
- Arguments:
- global load the content of the file pointed by the global directive
- named "server-state-file".
+ Users are warned that using this option may increase the number of old
+ processes if connections remain idle for too long. Adjusting the client
+ timeouts and/or the "hard-stop-after" parameter accordingly might be
+ needed in case of frequent reloads.
- local load the content of the file pointed by the directive
- "server-state-file-name" if set. If not set, then the backend
- name is used as a file name.
+ See also: "timeout client", "timeout client-fin", "timeout http-request",
+ "hard-stop-after"
- none don't load any stat for this backend
- Notes:
- - server's IP address is preserved across reloads by default, but the
- order can be changed thanks to the server's "init-addr" setting. This
- means that an IP address change performed on the CLI at run time will
- be preserved, and that any change to the local resolver (e.g. /etc/hosts)
- will possibly not have any effect if the state file is in use.
+option log-health-checks
+no option log-health-checks
+ Enable or disable logging of health checks status updates
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- - server's weight is applied from previous running process unless it has
- has changed between previous and new configuration files.
+ By default, failed health check are logged if server is UP and successful
+ health checks are logged if server is DOWN, so the amount of additional
+ information is limited.
- Example: Minimal configuration
+ When this option is enabled, any change of the health check status or to
+ the server's health will be logged, so that it becomes possible to know
+ that a server was failing occasional checks before crashing, or exactly when
+ it failed to respond a valid HTTP status, then when the port started to
+ reject connections, then when the server stopped responding at all.
- global
- stats socket /tmp/socket
- server-state-file /tmp/server_state
+ Note that status changes not caused by health checks (e.g. enable/disable on
+ the CLI) are intentionally not logged by this option.
- defaults
- load-server-state-from-file global
+ See also: "option httpchk", "option ldap-check", "option mysql-check",
+ "option pgsql-check", "option redis-check", "option smtpchk",
+ "option tcp-check", "log" and section 8 about logging.
- backend bk
- server s1 127.0.0.1:22 check weight 11
- server s2 127.0.0.1:22 check weight 12
+option log-separate-errors
+no option log-separate-errors
+ Change log level for non-completely successful connections
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- Then one can run :
+ Sometimes looking for errors in logs is not easy. This option makes HAProxy
+ raise the level of logs containing potentially interesting information such
+ as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
+ level changes from "info" to "err". This makes it possible to log them
+ separately to a different file with most syslog daemons. Be careful not to
+ remove them from the original file, otherwise you would lose ordering which
+ provides very important information.
- socat /tmp/socket - <<< "show servers state" > /tmp/server_state
+ Using this option, large sites dealing with several thousand connections per
+ second may log normal traffic to a rotating buffer and only archive smaller
+ error logs.
- Content of the file /tmp/server_state would be like this:
+ See also : "log", "dontlognull", "dontlog-normal" and section 8 about
+ logging.
- 1
- # <field names skipped for the doc example>
- 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
- 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
- Example: Minimal configuration
+option logasap
+no option logasap
+ Enable or disable early logging.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- global
- stats socket /tmp/socket
- server-state-base /etc/haproxy/states
+ By default, logs are emitted when all the log format variables and sample
+ fetches used in the definition of the log-format string return a value, or
+ when the session is terminated. This allows the built in log-format strings
+ to account for the transfer time, or the number of bytes in log messages.
- defaults
- load-server-state-from-file local
+ When handling long lived connections such as large file transfers or RDP,
+ it may take a while for the request or connection to appear in the logs.
+ Using "option logasap", the log message is created as soon as the server
+ connection is established in mode tcp, or as soon as the server sends the
+ complete headers in mode http. Missing information in the logs will be the
+ total number of bytes which will only indicate the amount of data transferred
+ before the message was created and the total time which will not take the
+ remainder of the connection life or transfer time into account. For the case
+ of HTTP, it is good practice to capture the Content-Length response header
+ so that the logs at least indicate how many bytes are expected to be
+ transferred.
- backend bk
- server s1 127.0.0.1:22 check weight 11
- server s2 127.0.0.1:22 check weight 12
+ Examples :
+ listen http_proxy 0.0.0.0:80
+ mode http
+ option httplog
+ option logasap
+ log 192.168.2.200 local3
+ >>> Feb 6 12:14:14 localhost \
+ haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
+ static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
+ "GET /image.iso HTTP/1.0"
- Then one can run :
+ See also : "option httplog", "capture response header", and section 8 about
+ logging.
- socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
- Content of the file /etc/haproxy/states/bk would be like this:
+option mysql-check [ user <username> [ { post-41 | pre-41 } ] ]
+ Use MySQL health checks for server testing
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <username> This is the username which will be used when connecting to MySQL
+ server.
+ post-41 Send post v4.1 client compatible checks (the default)
+ pre-41 Send pre v4.1 client compatible checks
- 1
- # <field names skipped for the doc example>
- 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
- 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
+ If you specify a username, the check consists of sending two MySQL packet,
+ one Client Authentication packet, and one QUIT packet, to correctly close
+ MySQL session. We then parse the MySQL Handshake Initialization packet and/or
+ Error packet. It is a basic but useful test which does not produce error nor
+ aborted connect on the server. However, it requires an unlocked authorised
+ user without a password. To create a basic limited user in MySQL with
+ optional resource limits:
- See also: "server-state-file", "server-state-file-name", and
- "show servers state"
+ CREATE USER '<username>'@'<ip_of_haproxy|network_of_haproxy/netmask>'
+ /*!50701 WITH MAX_QUERIES_PER_HOUR 1 MAX_UPDATES_PER_HOUR 0 */
+ /*M!100201 MAX_STATEMENT_TIME 0.0001 */;
+ If you don't specify a username (it is deprecated and not recommended), the
+ check only consists in parsing the Mysql Handshake Initialization packet or
+ Error packet, we don't send anything in this mode. It was reported that it
+ can generate lockout if check is too frequent and/or if there is not enough
+ traffic. In fact, you need in this case to check MySQL "max_connect_errors"
+ value as if a connection is established successfully within fewer than MySQL
+ "max_connect_errors" attempts after a previous connection was interrupted,
+ the error count for the host is cleared to zero. If HAProxy's server get
+ blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
-log global
-log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
- <facility> [<level> [<minlevel>]]
-no log
- Enable per-instance logging of events and traffic.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
+ Remember that this does not check database presence nor database consistency.
+ To do this, you can use an external check with xinetd for example.
- Prefix :
- no should be used when the logger list must be flushed. For example,
- if you don't want to inherit from the default logger list. This
- prefix does not allow arguments.
+ The check requires MySQL >=3.22, for older version, please use TCP check.
- Arguments :
- global should be used when the instance's logging parameters are the
- same as the global ones. This is the most common usage. "global"
- replaces <target>, <facility> and <level> with those of the log
- entries found in the "global" section. Only one "log global"
- statement may be used per instance, and this form takes no other
- parameter.
+ Most often, an incoming MySQL server needs to see the client's IP address for
+ various purposes, including IP privilege matching and connection logging.
+ When possible, it is often wise to masquerade the client's IP address when
+ connecting to the server using the "usesrc" argument of the "source" keyword,
+ which requires the transparent proxy feature to be compiled in, and the MySQL
+ server to route the client via the machine hosting HAProxy.
- <target> indicates where to send the logs. It takes the same format as
- for the "global" section's logs, and can be one of :
+ See also: "option httpchk"
- - An IPv4 address optionally followed by a colon (':') and a UDP
- port. If no port is specified, 514 is used by default (the
- standard syslog port).
- - An IPv6 address followed by a colon (':') and optionally a UDP
- port. If no port is specified, 514 is used by default (the
- standard syslog port).
+option nolinger
+no option nolinger
+ Enable or disable immediate session resource cleaning after close
+ May be used in sections: defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
- - A filesystem path to a UNIX domain socket, keeping in mind
- considerations for chroot (be sure the path is accessible
- inside the chroot) and uid/gid (be sure the path is
- appropriately writable).
+ When clients or servers abort connections in a dirty way (e.g. they are
+ physically disconnected), the session timeouts triggers and the session is
+ closed. But it will remain in FIN_WAIT1 state for some time in the system,
+ using some resources and possibly limiting the ability to establish newer
+ connections.
- - A file descriptor number in the form "fd@<number>", which may
- point to a pipe, terminal, or socket. In this case unbuffered
- logs are used and one writev() call per log is performed. This
- is a bit expensive but acceptable for most workloads. Messages
- sent this way will not be truncated but may be dropped, in
- which case the DroppedLogs counter will be incremented. The
- writev() call is atomic even on pipes for messages up to
- PIPE_BUF size, which POSIX recommends to be at least 512 and
- which is 4096 bytes on most modern operating systems. Any
- larger message may be interleaved with messages from other
- processes. Exceptionally for debugging purposes the file
- descriptor may also be directed to a file, but doing so will
- significantly slow HAProxy down as non-blocking calls will be
- ignored. Also there will be no way to purge nor rotate this
- file without restarting the process. Note that the configured
- syslog format is preserved, so the output is suitable for use
- with a TCP syslog server. See also the "short" and "raw"
- formats below.
+ When this happens, it is possible to activate "option nolinger" which forces
+ the system to immediately remove any socket's pending data on close. Thus,
+ a TCP RST is emitted, any pending data are truncated, and the session is
+ instantly purged from the system's tables. The generally visible effect for
+ a client is that responses are truncated if the close happens with a last
+ block of data (e.g. on a redirect or error response). On the server side,
+ it may help release the source ports immediately when forwarding a client
+ aborts in tunnels. In both cases, TCP resets are emitted and given that
+ the session is instantly destroyed, there will be no retransmit. On a lossy
+ network this can increase problems, especially when there is a firewall on
+ the lossy side, because the firewall might see and process the reset (hence
+ purge its session) and block any further traffic for this session,, including
+ retransmits from the other side. So if the other side doesn't receive it,
+ it will never receive any RST again, and the firewall might log many blocked
+ packets.
- - "stdout" / "stderr", which are respectively aliases for "fd@1"
- and "fd@2", see above.
+ For all these reasons, it is strongly recommended NOT to use this option,
+ unless absolutely needed as a last resort. In most situations, using the
+ "client-fin" or "server-fin" timeouts achieves similar results with a more
+ reliable behavior. On Linux it's also possible to use the "tcp-ut" bind or
+ server setting.
- - A ring buffer in the form "ring@<name>", which will correspond
- to an in-memory ring buffer accessible over the CLI using the
- "show events" command, which will also list existing rings and
- their sizes. Such buffers are lost on reload or restart but
- when used as a complement this can help troubleshooting by
- having the logs instantly available.
+ This option may be used both on frontends and backends, depending on the side
+ where it is required. Use it on the frontend for clients, and on the backend
+ for servers. While this option is technically supported in "defaults"
+ sections, it must really not be used there as it risks to accidentally
+ propagate to sections that must no use it and to cause problems there.
- - A log backend in the form "backend@<name>", which will send
- log messages to the corresponding log backend responsible for
- sending the message to the proper server according to the
- backend's lb settings. A log backend is a backend section with
- "mode log" set (see "mode" for more information).
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- - An explicit stream address prefix such as "tcp@","tcp6@",
- "tcp4@" or "uxst@" will allocate an implicit ring buffer with
- a stream forward server targeting the given address.
+ See also: "timeout client-fin", "timeout server-fin", "tcp-ut" bind or server
+ keywords.
- You may want to reference some environment variables in the
- address parameter, see section 2.3 about environment variables.
+option originalto [ except <network> ] [ header <name> ]
+ Enable insertion of the X-Original-To header to requests sent to servers
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments :
+ <network> is an optional argument used to disable this option for sources
+ matching <network>
+ <name> an optional argument to specify a different "X-Original-To"
+ header name.
- <length> is an optional maximum line length. Log lines larger than this
- value will be truncated before being sent. The reason is that
- syslog servers act differently on log line length. All servers
- support the default value of 1024, but some servers simply drop
- larger lines while others do log them. If a server supports long
- lines, it may make sense to set this value here in order to avoid
- truncating long lines. Similarly, if a server drops long lines,
- it is preferable to truncate them before sending them. Accepted
- values are 80 to 65535 inclusive. The default value of 1024 is
- generally fine for all standard usages. Some specific cases of
- long captures or JSON-formatted logs may require larger values.
- You may also need to increase "tune.http.logurilen" if your
- request URIs are truncated.
+ Since HAProxy can work in transparent mode, every request from a client can
+ be redirected to the proxy and HAProxy itself can proxy every request to a
+ complex SQUID environment and the destination host from SO_ORIGINAL_DST will
+ be lost. This is annoying when you want access rules based on destination ip
+ addresses. To solve this problem, a new HTTP header "X-Original-To" may be
+ added by HAProxy to all requests sent to the server. This header contains a
+ value representing the original destination IP address. Since this must be
+ configured to always use the last occurrence of this header only. Note that
+ only the last occurrence of the header must be used, since it is really
+ possible that the client has already brought one.
- <ranges> A list of comma-separated ranges to identify the logs to sample.
- This is used to balance the load of the logs to send to the log
- server. The limits of the ranges cannot be null. They are numbered
- from 1. The size or period (in number of logs) of the sample must
- be set with <sample_size> parameter.
+ The keyword "header" may be used to supply a different header name to replace
+ the default "X-Original-To". This can be useful where you might already
+ have a "X-Original-To" header from a different application, and you need
+ preserve it. Also if your backend server doesn't use the "X-Original-To"
+ header and requires different one.
- <sample_size>
- The size of the sample in number of logs to consider when balancing
- their logging loads. It is used to balance the load of the logs to
- send to the syslog server. This size must be greater or equal to the
- maximum of the high limits of the ranges.
- (see also <ranges> parameter).
+ Sometimes, a same HAProxy instance may be shared between a direct client
+ access and a reverse-proxy access (for instance when an SSL reverse-proxy is
+ used to decrypt HTTPS traffic). It is possible to disable the addition of the
+ header for a known destination address or network by adding the "except"
+ keyword followed by the network address. In this case, any destination IP
+ matching the network will not cause an addition of this header. Most common
+ uses are with private networks or 127.0.0.1. IPv4 and IPv6 are both
+ supported.
- <format> is the log format used when generating syslog messages. It may be
- one of the following :
+ This option may be specified either in the frontend or in the backend. If at
+ least one of them uses it, the header will be added. Note that the backend's
+ setting of the header subargument takes precedence over the frontend's if
+ both are defined.
- local Analog to rfc3164 syslog message format except that hostname
- field is stripped. This is the default.
- Note: option "log-send-hostname" switches the default to
- rfc3164.
+ Examples :
+ # Original Destination address
+ frontend www
+ mode http
+ option originalto except 127.0.0.1
- rfc3164 The RFC3164 syslog message format.
- (https://tools.ietf.org/html/rfc3164)
+ # Those servers want the IP Address in X-Client-Dst
+ backend www
+ mode http
+ option originalto header X-Client-Dst
- rfc5424 The RFC5424 syslog message format.
- (https://tools.ietf.org/html/rfc5424)
+ See also : "option httpclose", "option http-server-close".
- priority A message containing only a level plus syslog facility between
- angle brackets such as '<63>', followed by the text. The PID,
- date, time, process name and system name are omitted. This is
- designed to be used with a local log server.
- short A message containing only a level between angle brackets such as
- '<3>', followed by the text. The PID, date, time, process name
- and system name are omitted. This is designed to be used with a
- local log server. This format is compatible with what the
- systemd logger consumes.
+option persist
+no option persist
+ Enable or disable forced persistence on down servers
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- timed A message containing only a level between angle brackets such as
- '<3>', followed by ISO date and by the text. The PID, process
- name and system name are omitted. This is designed to be
- used with a local log server.
+ When an HTTP request reaches a backend with a cookie which references a dead
+ server, by default it is redispatched to another server. It is possible to
+ force the request to be sent to the dead server first using "option persist"
+ if absolutely needed. A common use case is when servers are under extreme
+ load and spend their time flapping. In this case, the users would still be
+ directed to the server they opened the session on, in the hope they would be
+ correctly served. It is recommended to use "option redispatch" in conjunction
+ with this option so that in the event it would not be possible to connect to
+ the server at all (server definitely dead), the client would finally be
+ redirected to another valid server.
- iso A message containing only the ISO date, followed by the text.
- The PID, process name and system name are omitted. This is
- designed to be used with a local log server.
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- raw A message containing only the text. The level, PID, date, time,
- process name and system name are omitted. This is designed to
- be used in containers or during development, where the severity
- only depends on the file descriptor used (stdout/stderr).
+ See also : "option redispatch", "retries", "force-persist"
- <facility> must be one of the 24 standard syslog facilities :
- kern user mail daemon auth syslog lpr news
- uucp cron auth2 ftp ntp audit alert cron2
- local0 local1 local2 local3 local4 local5 local6 local7
+option pgsql-check user <username>
+ Use PostgreSQL health checks for server testing
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <username> This is the username which will be used when connecting to
+ PostgreSQL server.
- Note that the facility is ignored for the "short" and "raw"
- formats, but still required as a positional field. It is
- recommended to use "daemon" in this case to make it clear that
- it's only supposed to be used locally.
+ The check sends a PostgreSQL StartupMessage and waits for either
+ Authentication request or ErrorResponse message. It is a basic but useful
+ test which does not produce error nor aborted connect on the server.
+ This check is identical with the "mysql-check".
- <level> is optional and can be specified to filter outgoing messages. By
- default, all messages are sent. If a level is specified, only
- messages with a severity at least as important as this level
- will be sent. An optional minimum level can be specified. If it
- is set, logs emitted with a more severe level than this one will
- be capped to this level. This is used to avoid sending "emerg"
- messages on all terminals on some default syslog configurations.
- Eight levels are known :
+ See also: "option httpchk"
- emerg alert crit err warning notice info debug
- It is important to keep in mind that it is the frontend which decides what to
- log from a connection, and that in case of content switching, the log entries
- from the backend will be ignored. Connections are logged at level "info".
-
- However, backend log declaration define how and where servers status changes
- will be logged. Level "notice" will be used to indicate a server going up,
- "warning" will be used for termination signals and definitive service
- termination, and "alert" will be used for when a server goes down.
-
- Note : According to RFC3164, messages are truncated to 1024 bytes before
- being emitted.
+option prefer-last-server
+no option prefer-last-server
+ Allow multiple load balanced requests to remain on the same server
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- Example :
- log global
- log stdout format short daemon # send log to systemd
- log stdout format raw daemon # send everything to stdout
- log stderr format raw daemon notice # send important events to stderr
- log 127.0.0.1:514 local0 notice # only send important events
- log tcp@127.0.0.1:514 local0 notice notice # same but limit output
- # level and send in tcp
- log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
+ When the load balancing algorithm in use is not deterministic, and a previous
+ request was sent to a server to which HAProxy still holds a connection, it is
+ sometimes desirable that subsequent requests on a same session go to the same
+ server as much as possible. Note that this is different from persistence, as
+ we only indicate a preference which HAProxy tries to apply without any form
+ of warranty. The real use is for keep-alive connections sent to servers. When
+ this option is used, HAProxy will try to reuse the same connection that is
+ attached to the server instead of rebalancing to another server, causing a
+ close of the connection. This can make sense for static file servers. It does
+ not make much sense to use this in combination with hashing algorithms. Note,
+ HAProxy already automatically tries to stick to a server which sends a 401 or
+ to a proxy which sends a 407 (authentication required), when the load
+ balancing algorithm is not deterministic. This is mandatory for use with the
+ broken NTLM authentication challenge, and significantly helps in
+ troubleshooting some faulty applications. Option prefer-last-server might be
+ desirable in these environments as well, to avoid redistributing the traffic
+ after every other response.
-log-format <string>
- Specifies the log format string to use for traffic logs
- May be used in sections: defaults | frontend | listen | backend
- yes | yes | yes | no
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- This directive specifies the log format string that will be used for all logs
- resulting from traffic passing through the frontend using this line. If the
- directive is used in a defaults section, all subsequent frontends will use
- the same log format. Please see section 8.2.4 which covers the log format
- string in depth.
- A specific log-format used only in case of connection error can also be
- defined, see the "error-log-format" option.
+ See also: "option http-keep-alive"
- "log-format" directive overrides previous "option tcplog", "log-format",
- "option httplog" and "option httpslog" directives.
-log-format-sd <string>
- Specifies the RFC5424 structured-data log format string
+option redispatch
+option redispatch <interval>
+no option redispatch
+ Enable or disable session redistribution in case of connection failure
May be used in sections: defaults | frontend | listen | backend
- yes | yes | yes | no
+ yes | no | yes | yes
+ Arguments :
+ <interval> The optional integer value that controls how often redispatches
+ occur when retrying connections. Positive value P indicates a
+ redispatch is desired on every Pth retry, and negative value
+ N indicate a redispatch is desired on the Nth retry prior to the
+ last retry. For example, the default of -1 preserves the
+ historical behavior of redispatching on the last retry, a
+ positive value of 1 would indicate a redispatch on every retry,
+ and a positive value of 3 would indicate a redispatch on every
+ third retry. You can disable redispatches with a value of 0.
- This directive specifies the RFC5424 structured-data log format string that
- will be used for all logs resulting from traffic passing through the frontend
- using this line. If the directive is used in a defaults section, all
- subsequent frontends will use the same log format. Please see section 8.2.4
- which covers the log format string in depth.
- See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
- about the RFC5424 structured-data part.
+ In HTTP mode, if a server designated by a cookie is down, clients may
+ definitely stick to it because they cannot flush the cookie, so they will not
+ be able to access the service anymore.
- Note : This log format string will be used only for loggers that have set
- log format to "rfc5424".
+ Specifying "option redispatch" will allow the proxy to break cookie or
+ consistent hash based persistence and redistribute them to a working server.
- Example :
- log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
+ Active servers are selected from a subset of the list of available
+ servers. Active servers that are not down or in maintenance (i.e., whose
+ health is not checked or that have been checked as "up"), are selected in the
+ following order:
+ 1. Any active, non-backup server, if any, or,
-log-tag <string>
- Specifies the log tag to use for all outgoing logs
- May be used in sections: defaults | frontend | listen | backend
- yes | yes | yes | yes
+ 2. If the "allbackups" option is not set, the first backup server in the
+ list, or
- Sets the tag field in the syslog header to this string. It defaults to the
- log-tag set in the global section, otherwise the program name as launched
- from the command line, which usually is "HAProxy". Sometimes it can be useful
- to differentiate between multiple processes running on the same host, or to
- differentiate customer instances running in the same process. In the backend,
- logs about servers up/down will use this tag. As a hint, it can be convenient
- to set a log-tag related to a hosted customer in a defaults section then put
- all the frontends and backends for that customer, then start another customer
- in a new defaults section. See also the global "log-tag" directive.
+ 3. If the "allbackups" option is set, any backup server.
-max-keep-alive-queue <value>
- Set the maximum server queue size for maintaining keep-alive connections
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+ When a retry occurs, HAProxy tries to select another server than the last
+ one. The new server is selected from the current list of servers.
- HTTP keep-alive tries to reuse the same server connection whenever possible,
- but sometimes it can be counter-productive, for example if a server has a lot
- of connections while other ones are idle. This is especially true for static
- servers.
+ Sometimes, if the list is updated between retries (e.g., if numerous retries
+ occur and last longer than the time needed to check that a server is down,
+ remove it from the list and fall back on the list of backup servers),
+ connections may be redirected to a backup server, though.
- The purpose of this setting is to set a threshold on the number of queued
- connections at which HAProxy stops trying to reuse the same server and prefers
- to find another one. The default value, -1, means there is no limit. A value
- of zero means that keep-alive requests will never be queued. For very close
- servers which can be reached with a low latency and which are not sensible to
- breaking keep-alive, a low value is recommended (e.g. local static server can
- use a value of 10 or less). For remote servers suffering from a high latency,
- higher values might be needed to cover for the latency and/or the cost of
- picking a different server.
+ It also allows to retry connections to another server in case of multiple
+ connection failures. Of course, it requires having "retries" set to a nonzero
+ value.
- Note that this has no impact on responses which are maintained to the same
- server consecutively to a 401 response. They will still go to the same server
- even if they have to be queued.
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- See also : "option http-server-close", "option prefer-last-server", server
- "maxconn" and cookie persistence.
+ See also : "retries", "force-persist"
-max-session-srv-conns <nb>
- Set the maximum number of outgoing connections we can keep idling for a given
- client session. The default is 5 (it precisely equals MAX_SRV_LIST which is
- defined at build time).
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
-maxconn <conns>
- Fix the maximum number of concurrent connections on a frontend
+option redis-check
+ Use redis health checks for server testing
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <conns> is the maximum number of concurrent connections the frontend will
- accept to serve. Excess connections will be queued by the system
- in the socket's listen queue and will be served once a connection
- closes.
-
- If the system supports it, it can be useful on big sites to raise this limit
- very high so that HAProxy manages connection queues, instead of leaving the
- clients with unanswered connection attempts. This value should not exceed the
- global maxconn. Also, keep in mind that a connection contains two buffers
- of tune.bufsize (16kB by default) each, as well as some other data resulting
- in about 33 kB of RAM being consumed per established connection. That means
- that a medium system equipped with 1GB of RAM can withstand around
- 20000-25000 concurrent connections if properly tuned.
+ yes | no | yes | yes
+ Arguments : none
- Also, when <conns> is set to large values, it is possible that the servers
- are not sized to accept such loads, and for this reason it is generally wise
- to assign them some reasonable connection limits.
+ It is possible to test that the server correctly talks REDIS protocol instead
+ of just testing that it accepts the TCP connection. When this option is set,
+ a PING redis command is sent to the server, and the response is analyzed to
+ find the "+PONG" response message.
- When this value is set to zero, which is the default, the global "maxconn"
- value is used.
+ Example :
+ option redis-check
- See also : "server", global section's "maxconn", "fullconn"
+ See also : "option httpchk", "option tcp-check", "tcp-check expect"
-mode { tcp|http|log }
- Set the running mode or protocol of the instance
+option smtpchk
+option smtpchk <hello> <domain>
+ Use SMTP health checks for server testing
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
+ yes | no | yes | yes
Arguments :
- tcp The instance will work in pure TCP mode. A full-duplex connection
- will be established between clients and servers, and no layer 7
- examination will be performed. This is the default mode. It
- should be used for SSL, SSH, SMTP, ...
+ <hello> is an optional argument. It is the "hello" command to use. It can
+ be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
+ values will be turned into the default command ("HELO").
- http The instance will work in HTTP mode. The client request will be
- analyzed in depth before connecting to any server. Any request
- which is not RFC-compliant will be rejected. Layer 7 filtering,
- processing and switching will be possible. This is the mode which
- brings HAProxy most of its value.
+ <domain> is the domain name to present to the server. It may only be
+ specified (and is mandatory) if the hello command has been
+ specified. By default, "localhost" is used.
- log When used in a backend section, it will turn the backend into a
- log backend. Such backend can be used as a log destination for
- any "log" directive by using the "backend@<name>" syntax. Log
- messages will be distributed to the servers from the backend
- according to the lb settings which can be configured using the
- "balance" keyword. Log backends support UDP servers by prefixing
- the server's address with the "udp@" prefix. Common backend and
- server features are supported, but not TCP or HTTP specific ones.
+ When "option smtpchk" is set, the health checks will consist in TCP
+ connections followed by an SMTP command. By default, this command is
+ "HELO localhost". The server's return code is analyzed and only return codes
+ starting with a "2" will be considered as valid. All other responses,
+ including a lack of response will constitute an error and will indicate a
+ dead server.
- When doing content switching, it is mandatory that the frontend and the
- backend are in the same mode (generally HTTP), otherwise the configuration
- will be refused.
+ This test is meant to be used with SMTP servers or relays. Depending on the
+ request, it is possible that some servers do not log each connection attempt,
+ so you may want to experiment to improve the behavior. Using telnet on port
+ 25 is often easier than adjusting the configuration.
+
+ Most often, an incoming SMTP server needs to see the client's IP address for
+ various purposes, including spam filtering, anti-spoofing and logging. When
+ possible, it is often wise to masquerade the client's IP address when
+ connecting to the server using the "usesrc" argument of the "source" keyword,
+ which requires the transparent proxy feature to be compiled in.
Example :
- defaults http_instances
- mode http
+ option smtpchk HELO mydomain.org
+ See also : "option httpchk", "source"
-monitor fail { if | unless } <condition>
- Add a condition to report a failure to a monitor HTTP request.
- May be used in sections : defaults | frontend | listen | backend
- no | yes | yes | no
- Arguments :
- if <cond> the monitor request will fail if the condition is satisfied,
- and will succeed otherwise. The condition should describe a
- combined test which must induce a failure if all conditions
- are met, for instance a low number of servers both in a
- backend and its backup.
- unless <cond> the monitor request will succeed only if the condition is
- satisfied, and will fail otherwise. Such a condition may be
- based on a test on the presence of a minimum number of active
- servers in a list of backends.
+option socket-stats
+no option socket-stats
- This statement adds a condition which can force the response to a monitor
- request to report a failure. By default, when an external component queries
- the URI dedicated to monitoring, a 200 response is returned. When one of the
- conditions above is met, HAProxy will return 503 instead of 200. This is
- very useful to report a site failure to an external component which may base
- routing advertisements between multiple sites on the availability reported by
- HAProxy. In this case, one would rely on an ACL involving the "nbsrv"
- criterion. Note that "monitor fail" only works in HTTP mode. Both status
- messages may be tweaked using "errorfile" or "errorloc" if needed.
-
- Example:
- frontend www
- mode http
- acl site_dead nbsrv(dynamic) lt 2
- acl site_dead nbsrv(static) lt 2
- monitor-uri /site_alive
- monitor fail if site_dead
-
- See also : "monitor-uri", "errorfile", "errorloc"
-
-
-monitor-uri <uri>
- Intercept a URI used by external components' monitor requests
+ Enable or disable collecting & providing separate statistics for each socket.
May be used in sections : defaults | frontend | listen | backend
yes | yes | yes | no
- Arguments :
- <uri> is the exact URI which we want to intercept to return HAProxy's
- health status instead of forwarding the request.
-
- When an HTTP request referencing <uri> will be received on a frontend,
- HAProxy will not forward it nor log it, but instead will return either
- "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
- conditions defined with "monitor fail". This is normally enough for any
- front-end HTTP probe to detect that the service is UP and running without
- forwarding the request to a backend server. Note that the HTTP method, the
- version and all headers are ignored, but the request must at least be valid
- at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
-
- Monitor requests are processed very early, just after the request is parsed
- and even before any "http-request". The only rulesets applied before are the
- tcp-request ones. They cannot be logged either, and it is the intended
- purpose. Only one URI may be configured for monitoring; when multiple
- "monitor-uri" statements are present, the last one will define the URI to
- be used. They are only used to report HAProxy's health to an upper component,
- nothing more. However, it is possible to add any number of conditions using
- "monitor fail" and ACLs so that the result can be adjusted to whatever check
- can be imagined (most often the number of available servers in a backend).
-
- Note: if <uri> starts by a slash ('/'), the matching is performed against the
- request's path instead of the request's uri. It is a workaround to let
- the HTTP/2 requests match the monitor-uri. Indeed, in HTTP/2, clients
- are encouraged to send absolute URIs only.
-
- Example :
- # Use /haproxy_test to report HAProxy's status
- frontend www
- mode http
- monitor-uri /haproxy_test
- See also : "monitor fail"
+ Arguments : none
-option abortonclose
-no option abortonclose
- Enable or disable early dropping of aborted requests pending in queues.
+option splice-auto
+no option splice-auto
+ Enable or disable automatic kernel acceleration on sockets in both directions
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ yes | yes | yes | yes
Arguments : none
- In presence of very high loads, the servers will take some time to respond.
- The per-instance connection queue will inflate, and the response time will
- increase respective to the size of the queue times the average per-session
- response time. When clients will wait for more than a few seconds, they will
- often hit the "STOP" button on their browser, leaving a useless request in
- the queue, and slowing down other users, and the servers as well, because the
- request will eventually be served, then aborted at the first error
- encountered while delivering the response.
+ When this option is enabled either on a frontend or on a backend, HAProxy
+ will automatically evaluate the opportunity to use kernel tcp splicing to
+ forward data between the client and the server, in either direction. HAProxy
+ uses heuristics to estimate if kernel splicing might improve performance or
+ not. Both directions are handled independently. Note that the heuristics used
+ are not much aggressive in order to limit excessive use of splicing. This
+ option requires splicing to be enabled at compile time, and may be globally
+ disabled with the global option "nosplice". Since splice uses pipes, using it
+ requires that there are enough spare pipes.
- As there is no way to distinguish between a full STOP and a simple output
- close on the client side, HTTP agents should be conservative and consider
- that the client might only have closed its output channel while waiting for
- the response. However, this introduces risks of congestion when lots of users
- do the same, and is completely useless nowadays because probably no client at
- all will close the session while waiting for the response. Some HTTP agents
- support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
- hardware-based load balancers). So the probability for a closed input channel
- to represent a user hitting the "STOP" button is close to 100%, and the risk
- of being the single component to break rare but valid traffic is extremely
- low, which adds to the temptation to be able to abort a session early while
- still not served and not pollute the servers.
+ Important note: kernel-based TCP splicing is a Linux-specific feature which
+ first appeared in kernel 2.6.25. It offers kernel-based acceleration to
+ transfer data between sockets without copying these data to user-space, thus
+ providing noticeable performance gains and CPU cycles savings. Since many
+ early implementations are buggy, corrupt data and/or are inefficient, this
+ feature is not enabled by default, and it should be used with extreme care.
+ While it is not possible to detect the correctness of an implementation,
+ 2.6.29 is the first version offering a properly working implementation. In
+ case of doubt, splicing may be globally disabled using the global "nosplice"
+ keyword.
- In HAProxy, the user can choose the desired behavior using the option
- "abortonclose". By default (without the option) the behavior is HTTP
- compliant and aborted requests will be served. But when the option is
- specified, a session with an incoming channel closed will be aborted while
- it is still possible, either pending in the queue for a connection slot, or
- during the connection establishment if the server has not yet acknowledged
- the connection request. This considerably reduces the queue size and the load
- on saturated servers when users are tempted to click on STOP, which in turn
- reduces the response time for other users.
+ Example :
+ option splice-auto
If this option has been enabled in a "defaults" section, it can be disabled
in a specific instance by prepending the "no" keyword before it.
- See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
+ See also : "option splice-request", "option splice-response", and global
+ options "nosplice" and "maxpipes"
-option accept-invalid-http-request
-no option accept-invalid-http-request
- Enable or disable relaxing of HTTP request parsing
+option splice-request
+no option splice-request
+ Enable or disable automatic kernel acceleration on sockets for requests
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
+ yes | yes | yes | yes
Arguments : none
- By default, HAProxy complies with RFC7230 in terms of message parsing. This
- means that invalid characters in header names are not permitted and cause an
- error to be returned to the client. This is the desired behavior as such
- forbidden characters are essentially used to build attacks exploiting server
- weaknesses, and bypass security filtering. Sometimes, a buggy browser or
- server will emit invalid header names for whatever reason (configuration,
- implementation) and the issue will not be immediately fixed. In such a case,
- it is possible to relax HAProxy's header name parser to accept any character
- even if that does not make sense, by specifying this option. Similarly, the
- list of characters allowed to appear in a URI is well defined by RFC3986, and
- chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
- ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
- not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
- remaining ones are blocked by default unless this option is enabled. This
- option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
- to pass through (no version specified), as well as different protocol names
- (e.g. RTSP), and multiple digits for both the major and the minor version.
- Finally, this option also allows incoming URLs to contain fragment references
- ('#' after the path).
+ When this option is enabled either on a frontend or on a backend, HAProxy
+ will use kernel tcp splicing whenever possible to forward data going from
+ the client to the server. It might still use the recv/send scheme if there
+ are no spare pipes left. This option requires splicing to be enabled at
+ compile time, and may be globally disabled with the global option "nosplice".
+ Since splice uses pipes, using it requires that there are enough spare pipes.
- This option should never be enabled by default as it hides application bugs
- and open security breaches. It should only be deployed after a problem has
- been confirmed.
+ Important note: see "option splice-auto" for usage limitations.
- When this option is enabled, erroneous header names will still be accepted in
- requests, but the complete request will be captured in order to permit later
- analysis using the "show errors" request on the UNIX stats socket. Similarly,
- requests containing invalid chars in the URI part will be logged. Doing this
- also helps confirming that the issue has been solved.
+ Example :
+ option splice-request
If this option has been enabled in a "defaults" section, it can be disabled
in a specific instance by prepending the "no" keyword before it.
- See also : "option accept-invalid-http-response" and "show errors" on the
- stats socket.
+ See also : "option splice-auto", "option splice-response", and global options
+ "nosplice" and "maxpipes"
-option accept-invalid-http-response
-no option accept-invalid-http-response
- Enable or disable relaxing of HTTP response parsing
+option splice-response
+no option splice-response
+ Enable or disable automatic kernel acceleration on sockets for responses
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ yes | yes | yes | yes
Arguments : none
- By default, HAProxy complies with RFC7230 in terms of message parsing. This
- means that invalid characters in header names are not permitted and cause an
- error to be returned to the client. This is the desired behavior as such
- forbidden characters are essentially used to build attacks exploiting server
- weaknesses, and bypass security filtering. Sometimes, a buggy browser or
- server will emit invalid header names for whatever reason (configuration,
- implementation) and the issue will not be immediately fixed. In such a case,
- it is possible to relax HAProxy's header name parser to accept any character
- even if that does not make sense, by specifying this option. This option also
- relaxes the test on the HTTP version format, it allows multiple digits for
- both the major and the minor version.
+ When this option is enabled either on a frontend or on a backend, HAProxy
+ will use kernel tcp splicing whenever possible to forward data going from
+ the server to the client. It might still use the recv/send scheme if there
+ are no spare pipes left. This option requires splicing to be enabled at
+ compile time, and may be globally disabled with the global option "nosplice".
+ Since splice uses pipes, using it requires that there are enough spare pipes.
- This option should never be enabled by default as it hides application bugs
- and open security breaches. It should only be deployed after a problem has
- been confirmed.
+ Important note: see "option splice-auto" for usage limitations.
- When this option is enabled, erroneous header names will still be accepted in
- responses, but the complete response will be captured in order to permit
- later analysis using the "show errors" request on the UNIX stats socket.
- Doing this also helps confirming that the issue has been solved.
+ Example :
+ option splice-response
If this option has been enabled in a "defaults" section, it can be disabled
in a specific instance by prepending the "no" keyword before it.
- See also : "option accept-invalid-http-request" and "show errors" on the
- stats socket.
+ See also : "option splice-auto", "option splice-request", and global options
+ "nosplice" and "maxpipes"
-option allbackups
-no option allbackups
- Use either all backup servers at a time or only the first one
+option spop-check
+ Use SPOP health checks for server testing
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ yes | no | yes | yes
Arguments : none
- By default, the first operational backup server gets all traffic when normal
- servers are all down. Sometimes, it may be preferred to use multiple backups
- at once, because one will not be enough. When "option allbackups" is enabled,
- the load balancing will be performed among all backup servers when all normal
- ones are unavailable. The same load balancing algorithm will be used and the
- servers' weights will be respected. Thus, there will not be any priority
- order between the backup servers anymore.
+ It is possible to test that the server correctly talks SPOP protocol instead
+ of just testing that it accepts the TCP connection. When this option is set,
+ a HELLO handshake is performed between HAProxy and the server, and the
+ response is analyzed to check no error is reported.
- This option is mostly used with static server farms dedicated to return a
- "sorry" page when an application is completely offline.
+ Example :
+ option spop-check
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ See also : "option httpchk"
-option checkcache
-no option checkcache
- Analyze all server responses and block responses with cacheable cookies
+option srvtcpka
+no option srvtcpka
+ Enable or disable the sending of TCP keepalive packets on the server side
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ yes | no | yes | yes
Arguments : none
- Some high-level frameworks set application cookies everywhere and do not
- always let enough control to the developer to manage how the responses should
- be cached. When a session cookie is returned on a cacheable object, there is a
- high risk of session crossing or stealing between users traversing the same
- caches. In some situations, it is better to block the response than to let
- some sensitive session information go in the wild.
-
- The option "checkcache" enables deep inspection of all server responses for
- strict compliance with HTTP specification in terms of cacheability. It
- carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
- response to check if there's a risk of caching a cookie on a client-side
- proxy. When this option is enabled, the only responses which can be delivered
- to the client are :
- - all those without "Set-Cookie" header;
- - all those with a return code other than 200, 203, 204, 206, 300, 301,
- 404, 405, 410, 414, 501, provided that the server has not set a
- "Cache-control: public" header field;
- - all those that result from a request using a method other than GET, HEAD,
- OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
- public' header field;
- - those with a 'Pragma: no-cache' header
- - those with a 'Cache-control: private' header
- - those with a 'Cache-control: no-store' header
- - those with a 'Cache-control: max-age=0' header
- - those with a 'Cache-control: s-maxage=0' header
- - those with a 'Cache-control: no-cache' header
- - those with a 'Cache-control: no-cache="set-cookie"' header
- - those with a 'Cache-control: no-cache="set-cookie,' header
- (allowing other fields after set-cookie)
-
- If a response doesn't respect these requirements, then it will be blocked
- just as if it was from an "http-response deny" rule, with an "HTTP 502 bad
- gateway". The session state shows "PH--" meaning that the proxy blocked the
- response during headers processing. Additionally, an alert will be sent in
- the logs so that admins are informed that there's something to be fixed.
-
- Due to the high impact on the application, the application should be tested
- in depth with the option enabled before going to production. It is also a
- good practice to always activate it during tests, even if it is not used in
- production, as it will report potentially dangerous application behaviors.
-
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
-
-
-option clitcpka
-no option clitcpka
- Enable or disable the sending of TCP keepalive packets on the client side
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
-
- When there is a firewall or any session-aware component between a client and
- a server, and when the protocol involves very long sessions with long idle
- periods (e.g. remote desktops), there is a risk that one of the intermediate
- components decides to expire a session which has remained idle for too long.
+ When there is a firewall or any session-aware component between a client and
+ a server, and when the protocol involves very long sessions with long idle
+ periods (e.g. remote desktops), there is a risk that one of the intermediate
+ components decides to expire a session which has remained idle for too long.
Enabling socket-level TCP keep-alives makes the system regularly send packets
to the other end of the connection, leaving it active. The delay between
Please note that this has nothing to do with HTTP keep-alive.
- Using option "clitcpka" enables the emission of TCP keep-alive probes on the
- client side of a connection, which should help when session expirations are
- noticed between HAProxy and a client.
+ Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
+ server side of a connection, which should help when session expirations are
+ noticed between HAProxy and a server.
If this option has been enabled in a "defaults" section, it can be disabled
in a specific instance by prepending the "no" keyword before it.
- See also : "option srvtcpka", "option tcpka"
+ See also : "option clitcpka", "option tcpka"
-option contstats
- Enable continuous traffic statistics updates
+option ssl-hello-chk
+ Use SSLv3 client hello health checks for server testing
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
+ yes | no | yes | yes
Arguments : none
- By default, counters used for statistics calculation are incremented
- only when a session finishes. It works quite well when serving small
- objects, but with big ones (for example large images or archives) or
- with A/V streaming, a graph generated from HAProxy counters looks like
- a hedgehog. With this option enabled counters get incremented frequently
- along the session, typically every 5 seconds, which is often enough to
- produce clean graphs. Recounting touches a hotpath directly so it is not
- not enabled by default, as it can cause a lot of wakeups for very large
- session counts and cause a small performance drop.
+ When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
+ possible to test that the server correctly talks SSL instead of just testing
+ that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
+ SSLv3 client hello messages are sent once the connection is established to
+ the server, and the response is analyzed to find an SSL server hello message.
+ The server is considered valid only when the response contains this server
+ hello message.
-option disable-h2-upgrade
-no option disable-h2-upgrade
- Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client
- connection.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ All servers tested till there correctly reply to SSLv3 client hello messages,
+ and most servers tested do not even log the requests containing only hello
+ messages, which is appreciable.
- By default, HAProxy is able to implicitly upgrade an HTTP/1.x client
- connection to an HTTP/2 connection if the first request it receives from a
- given HTTP connection matches the HTTP/2 connection preface (i.e. the string
- "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"). This way, it is possible to support
- HTTP/1.x and HTTP/2 clients on a non-SSL connections. This option must be
- used to disable the implicit upgrade. Note this implicit upgrade is only
- supported for HTTP proxies, thus this option too. Note also it is possible to
- force the HTTP/2 on clear connections by specifying "proto h2" on the bind
- line. Finally, this option is applied on all bind lines. To disable implicit
- HTTP/2 upgrades for a specific bind line, it is possible to use "proto h1".
+ Note that this check works even when SSL support was not built into HAProxy
+ because it forges the SSL message. When SSL support is available, it is best
+ to use native SSL health checks instead of this one.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ See also: "option httpchk", "check-ssl"
-option dontlog-normal
-no option dontlog-normal
- Enable or disable logging of normal, successful connections
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
- There are large sites dealing with several thousand connections per second
- and for which logging is a major pain. Some of them are even forced to turn
- logs off and cannot debug production issues. Setting this option ensures that
- normal connections, those which experience no error, no timeout, no retry nor
- redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
- mode, the response status code is checked and return codes 5xx will still be
- logged.
+option tcp-check
+ Perform health checks using tcp-check send/expect sequences
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- It is strongly discouraged to use this option as most of the time, the key to
- complex issues is in the normal logs which will not be logged here. If you
- need to separate logs, see the "log-separate-errors" option instead.
+ This health check method is intended to be combined with "tcp-check" command
+ lists in order to support send/expect types of health check sequences.
- See also : "log", "dontlognull", "log-separate-errors" and section 8 about
- logging.
+ TCP checks currently support 4 modes of operations :
+ - no "tcp-check" directive : the health check only consists in a connection
+ attempt, which remains the default mode.
+ - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
+ used to send a string along with a connection opening. With some
+ protocols, it helps sending a "QUIT" message for example that prevents
+ the server from logging a connection error for each health check. The
+ check result will still be based on the ability to open the connection
+ only.
-option dontlognull
-no option dontlognull
- Enable or disable logging of null connections
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ - "tcp-check expect" only is mentioned : this is used to test a banner.
+ The connection is opened and HAProxy waits for the server to present some
+ contents which must validate some rules. The check result will be based
+ on the matching between the contents and the rules. This is suited for
+ POP, IMAP, SMTP, FTP, SSH, TELNET.
- In certain environments, there are components which will regularly connect to
- various systems to ensure that they are still alive. It can be the case from
- another load balancer as well as from monitoring systems. By default, even a
- simple port probe or scan will produce a log. If those connections pollute
- the logs too much, it is possible to enable option "dontlognull" to indicate
- that a connection on which no data has been transferred will not be logged,
- which typically corresponds to those probes. Note that errors will still be
- returned to the client and accounted for in the stats. If this is not what is
- desired, option http-ignore-probes can be used instead.
+ - both "tcp-check send" and "tcp-check expect" are mentioned : this is
+ used to test a hello-type protocol. HAProxy sends a message, the server
+ responds and its response is analyzed. the check result will be based on
+ the matching between the response contents and the rules. This is often
+ suited for protocols which require a binding or a request/response model.
+ LDAP, MySQL, Redis and SSL are example of such protocols, though they
+ already all have their dedicated checks with a deeper understanding of
+ the respective protocols.
+ In this mode, many questions may be sent and many answers may be
+ analyzed.
- It is generally recommended not to use this option in uncontrolled
- environments (e.g. internet), otherwise scans and other malicious activities
- would not be logged.
+ A fifth mode can be used to insert comments in different steps of the script.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ For each tcp-check rule you create, you can add a "comment" directive,
+ followed by a string. This string will be reported in the log and stderr in
+ debug mode. It is useful to make user-friendly error reporting. The
+ "comment" is of course optional.
- See also : "log", "http-ignore-probes", "monitor-uri", and
- section 8 about logging.
+ During the execution of a health check, a variable scope is made available to
+ store data samples, using the "tcp-check set-var" operation. Freeing those
+ variable is possible using "tcp-check unset-var".
-option forwarded [ proto ]
- [ host | host-expr <host_expr> ]
- [ by | by-expr <by_expr> ] [ by_port | by_port-expr <by_port_expr>]
- [ for | for-expr <for_expr> ] [ for_port | for_port-expr <for_port_expr>]
-no option forwarded
- Enable insertion of the rfc 7239 forwarded header in requests sent to servers
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <host_expr> optional argument to specify a custom sample expression
- those result will be used as 'host' parameter value
- <by_expr> optional argument to specicy a custom sample expression
- those result will be used as 'by' parameter nodename value
+ Examples :
+ # perform a POP check (analyze only server's banner)
+ option tcp-check
+ tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
- <for_expr> optional argument to specicy a custom sample expression
- those result will be used as 'for' parameter nodename value
+ # perform an IMAP check (analyze only server's banner)
+ option tcp-check
+ tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
- <by_port_expr> optional argument to specicy a custom sample expression
- those result will be used as 'by' parameter nodeport value
+ # look for the redis master server after ensuring it speaks well
+ # redis protocol, then it exits properly.
+ # (send a command then analyze the response 3 times)
+ option tcp-check
+ tcp-check comment PING\ phase
+ tcp-check send PING\r\n
+ tcp-check expect string +PONG
+ tcp-check comment role\ check
+ tcp-check send info\ replication\r\n
+ tcp-check expect string role:master
+ tcp-check comment QUIT\ phase
+ tcp-check send QUIT\r\n
+ tcp-check expect string +OK
- <for_port_expr> optional argument to specicy a custom sample expression
- those result will be used as 'for' parameter nodeport value
+ forge a HTTP request, then analyze the response
+ (send many headers before analyzing)
+ option tcp-check
+ tcp-check comment forge\ and\ send\ HTTP\ request
+ tcp-check send HEAD\ /\ HTTP/1.1\r\n
+ tcp-check send Host:\ www.mydomain.com\r\n
+ tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
+ tcp-check send \r\n
+ tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
- Since HAProxy works in reverse-proxy mode, servers are losing some request
- context (request origin: client ip address, protocol used...)
+ See also : "tcp-check connect", "tcp-check expect" and "tcp-check send".
- A common way to address this limitation is to use the well known
- x-forward-for and x-forward-* friends to expose some of this context to the
- underlying servers/applications.
- While this use to work and is widely deployed, it is not officially supported
- by the IETF and can be the root of some interoperability as well as security
- issues.
- To solve this, a new HTTP extension has been described by the IETF:
- forwarded header (RFC7239).
- More information here: https://www.rfc-editor.org/rfc/rfc7239.html
+option tcp-smart-accept
+no option tcp-smart-accept
+ Enable or disable the saving of one ACK packet during the accept sequence
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments : none
- The use of this single header allow to convey numerous details
- within the same header, and most importantly, fixes the proxy chaining
- issue. (the rfc allows for multiple chained proxies to append their own
- values to an already existing header).
+ When an HTTP connection request comes in, the system acknowledges it on
+ behalf of HAProxy, then the client immediately sends its request, and the
+ system acknowledges it too while it is notifying HAProxy about the new
+ connection. HAProxy then reads the request and responds. This means that we
+ have one TCP ACK sent by the system for nothing, because the request could
+ very well be acknowledged by HAProxy when it sends its response.
- This option may be specified in defaults, listen or backend section, but it
- will be ignored for frontend sections.
-
- Setting option forwarded without arguments results in using default implicit
- behavior.
- Default behavior enables proto parameter and injects original client ip.
-
- The equivalent explicit/manual configuration would be:
- option forwarded proto for
-
- The keyword 'by' is used to enable 'by' parameter ("nodename") in
- forwarded header. It allows to embed request proxy information.
- 'by' value will be set to proxy ip (destination address)
- If not available (ie: UNIX listener), 'by' will be set to
- "unknown".
+ For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
+ sending this useless ACK on platforms which support it (currently at least
+ Linux). It must not cause any problem, because the system will send it anyway
+ after 40 ms if the response takes more time than expected to come.
- The keyword 'by-expr' is used to enable 'by' parameter ("nodename") in
- forwarded header. It allows to embed request proxy information.
- 'by' value will be set to the result of the sample expression
- <by_expr>, if valid, otherwise it will be set to "unknown".
+ During complex network debugging sessions, it may be desirable to disable
+ this optimization because delayed ACKs can make troubleshooting more complex
+ when trying to identify where packets are delayed. It is then possible to
+ fall back to normal behavior by specifying "no option tcp-smart-accept".
- The keyword 'for' is used to enable 'for' parameter ("nodename") in
- forwarded header. It allows to embed request client information.
- 'for' value will be set to client ip (source address)
- If not available (ie: UNIX listener), 'for' will be set to
- "unknown".
+ It is also possible to force it for non-HTTP proxies by simply specifying
+ "option tcp-smart-accept". For instance, it can make sense with some services
+ such as SMTP where the server speaks first.
- The keyword 'for-expr' is used to enable 'for' parameter ("nodename") in
- forwarded header. It allows to embed request client information.
- 'for' value will be set to the result of the sample expression
- <for_expr>, if valid, otherwise it will be set to "unknown".
+ It is recommended to avoid forcing this option in a defaults section. In case
+ of doubt, consider setting it back to automatic values by prepending the
+ "default" keyword before it, or disabling it using the "no" keyword.
- The keyword 'by_port' is used to provide "nodeport" info to
- 'by' parameter. 'by_port' requires 'by' or 'by-expr' to be set or
- it will be ignored.
- "nodeport" will be set to proxy (destination) port if available,
- otherwise it will be ignored.
+ See also : "option tcp-smart-connect"
- The keyword 'by_port-expr' is used to provide "nodeport" info to
- 'by' parameter. 'by_port-expr' requires 'by' or 'by-expr' to be set or
- it will be ignored.
- "nodeport" will be set to the result of the sample expression
- <by_port_expr>, if valid, otherwise it will be ignored.
- The keyword 'for_port' is used to provide "nodeport" info to
- 'for' parameter. 'for_port' requires 'for' or 'for-expr' to be set or
- it will be ignored.
- "nodeport" will be set to client (source) port if available,
- otherwise it will be ignored.
+option tcp-smart-connect
+no option tcp-smart-connect
+ Enable or disable the saving of one ACK packet during the connect sequence
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- The keyword 'for_port-expr' is used to provide "nodeport" info to
- 'for' parameter. 'for_port-expr' requires 'for' or 'for-expr' to be set or
- it will be ignored.
- "nodeport" will be set to the result of the sample expression
- <for_port_expr>, if valid, otherwise it will be ignored.
+ On certain systems (at least Linux), HAProxy can ask the kernel not to
+ immediately send an empty ACK upon a connection request, but to directly
+ send the buffer request instead. This saves one packet on the network and
+ thus boosts performance. It can also be useful for some servers, because they
+ immediately get the request along with the incoming connection.
- Examples :
- # Those servers want the ip address and protocol of the client request
- # Resulting header would look like this:
- # forwarded: proto=http;for=127.0.0.1
- backend www_default
- mode http
- option forwarded
- #equivalent to: option forwarded proto for
+ This feature is enabled when "option tcp-smart-connect" is set in a backend.
+ It is not enabled by default because it makes network troubleshooting more
+ complex.
- # Those servers want the requested host and hashed client ip address
- # as well as client source port (you should use seed for xxh32 if ensuring
- # ip privacy is a concern)
- # Resulting header would look like this:
- # forwarded: host="haproxy.org";for="_000000007F2F367E:60138"
- backend www_host
- mode http
- option forwarded host for-expr src,xxh32,hex for_port
+ It only makes sense to enable it with protocols where the client speaks first
+ such as HTTP. In other situations, if there is no data to send in place of
+ the ACK, a normal ACK is sent.
- # Those servers want custom data in host, for and by parameters
- # Resulting header would look like this:
- # forwarded: host="host.com";by=_haproxy;for="[::1]:10"
- backend www_custom
- mode http
- option forwarded host-expr str(host.com) by-expr str(_haproxy) for for_port-expr int(10)
+ If this option has been enabled in a "defaults" section, it can be disabled
+ in a specific instance by prepending the "no" keyword before it.
- # Those servers want random 'for' obfuscated identifiers for request
- # tracing purposes while protecting sensitive IP information
- # Resulting header would look like this:
- # forwarded: for=_000000002B1F4D63
- backend www_for_hide
- mode http
- option forwarded for-expr rand,hex
+ See also : "option tcp-smart-accept"
- See also : "option forwardfor", "option originalto"
-option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
- Enable insertion of the X-Forwarded-For header to requests sent to servers
+option tcpka
+ Enable or disable the sending of TCP keepalive packets on both sides
May be used in sections : defaults | frontend | listen | backend
yes | yes | yes | yes
- Arguments :
- <network> is an optional argument used to disable this option for sources
- matching <network>
- <name> an optional argument to specify a different "X-Forwarded-For"
- header name.
-
- Since HAProxy works in reverse-proxy mode, the servers see its IP address as
- their client address. This is sometimes annoying when the client's IP address
- is expected in server logs. To solve this problem, the well-known HTTP header
- "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
- This header contains a value representing the client's IP address. Since this
- header is always appended at the end of the existing header list, the server
- must be configured to always use the last occurrence of this header only. See
- the server's manual to find how to enable use of this standard header. Note
- that only the last occurrence of the header must be used, since it is really
- possible that the client has already brought one.
-
- The keyword "header" may be used to supply a different header name to replace
- the default "X-Forwarded-For". This can be useful where you might already
- have a "X-Forwarded-For" header from a different application (e.g. stunnel),
- and you need preserve it. Also if your backend server doesn't use the
- "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
- require "X-Cluster-Client-IP").
+ Arguments : none
- Sometimes, a same HAProxy instance may be shared between a direct client
- access and a reverse-proxy access (for instance when an SSL reverse-proxy is
- used to decrypt HTTPS traffic). It is possible to disable the addition of the
- header for a known source address or network by adding the "except" keyword
- followed by the network address. In this case, any source IP matching the
- network will not cause an addition of this header. Most common uses are with
- private networks or 127.0.0.1. IPv4 and IPv6 are both supported.
+ When there is a firewall or any session-aware component between a client and
+ a server, and when the protocol involves very long sessions with long idle
+ periods (e.g. remote desktops), there is a risk that one of the intermediate
+ components decides to expire a session which has remained idle for too long.
- Alternatively, the keyword "if-none" states that the header will only be
- added if it is not present. This should only be used in perfectly trusted
- environment, as this might cause a security issue if headers reaching HAProxy
- are under the control of the end-user.
+ Enabling socket-level TCP keep-alives makes the system regularly send packets
+ to the other end of the connection, leaving it active. The delay between
+ keep-alive probes is controlled by the system only and depends both on the
+ operating system and its tuning parameters.
- This option may be specified either in the frontend or in the backend. If at
- least one of them uses it, the header will be added. Note that the backend's
- setting of the header subargument takes precedence over the frontend's if
- both are defined. In the case of the "if-none" argument, if at least one of
- the frontend or the backend does not specify it, it wants the addition to be
- mandatory, so it wins.
+ It is important to understand that keep-alive packets are neither emitted nor
+ received at the application level. It is only the network stacks which sees
+ them. For this reason, even if one side of the proxy already uses keep-alives
+ to maintain its connection alive, those keep-alive packets will not be
+ forwarded to the other side of the proxy.
- Example :
- # Public HTTP address also used by stunnel on the same machine
- frontend www
- mode http
- option forwardfor except 127.0.0.1 # stunnel already adds the header
+ Please note that this has nothing to do with HTTP keep-alive.
- # Those servers want the IP Address in X-Client
- backend www
- mode http
- option forwardfor header X-Client
+ Using option "tcpka" enables the emission of TCP keep-alive probes on both
+ the client and server sides of a connection. Note that this is meaningful
+ only in "defaults" or "listen" sections. If this option is used in a
+ frontend, only the client side will get keep-alives, and if this option is
+ used in a backend, only the server side will get keep-alives. For this
+ reason, it is strongly recommended to explicitly use "option clitcpka" and
+ "option srvtcpka" when the configuration is split between frontends and
+ backends.
- See also : "option httpclose", "option http-server-close",
- "option http-keep-alive"
+ See also : "option clitcpka", "option srvtcpka"
-option h1-case-adjust-bogus-client
-no option h1-case-adjust-bogus-client
- Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
+option tcplog
+ Enable advanced logging of TCP connections with session state and timers
May be used in sections : defaults | frontend | listen | backend
yes | yes | yes | no
Arguments : none
- There is no standard case for header names because, as stated in RFC7230,
- they are case-insensitive. So applications must handle them in a case-
- insensitive manner. But some bogus applications violate the standards and
- erroneously rely on the cases most commonly used by browsers. This problem
- becomes critical with HTTP/2 because all header names must be exchanged in
- lower case, and HAProxy follows the same convention. All header names are
- sent in lower case to clients and servers, regardless of the HTTP version.
-
- When HAProxy receives an HTTP/1 response, its header names are converted to
- lower case and manipulated and sent this way to the clients. If a client is
- known to violate the HTTP standards and to fail to process a response coming
- from HAProxy, it is possible to transform the lower case header names to a
- different format when the response is formatted and sent to the client, by
- enabling this option and specifying the list of headers to be reformatted
- using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
- must only be a temporary workaround for the time it takes the client to be
- fixed, because clients which require such workarounds might be vulnerable to
- content smuggling attacks and must absolutely be fixed.
-
- Please note that this option will not affect standards-compliant clients.
+ By default, the log output format is very poor, as it only contains the
+ source and destination addresses, and the instance name. By specifying
+ "option tcplog", each log line turns into a much richer format including, but
+ not limited to, the connection timers, the session status, the connections
+ numbers, the frontend, backend and server name, and of course the source
+ address and ports. This option is useful for pure TCP proxies in order to
+ find which of the client or server disconnects or times out. For normal HTTP
+ proxies, it's better to use "option httplog" which is even more complete.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ "option tcplog" overrides any previous "log-format" directive.
- See also: "option h1-case-adjust-bogus-server", "h1-case-adjust",
- "h1-case-adjust-file".
+ See also : "option httplog", and section 8 about logging.
-option h1-case-adjust-bogus-server
-no option h1-case-adjust-bogus-server
- Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
+option transparent
+no option transparent
+ Enable client-side transparent proxying
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ yes | no | yes | yes
Arguments : none
- There is no standard case for header names because, as stated in RFC7230,
- they are case-insensitive. So applications must handle them in a case-
- insensitive manner. But some bogus applications violate the standards and
- erroneously rely on the cases most commonly used by browsers. This problem
- becomes critical with HTTP/2 because all header names must be exchanged in
- lower case, and HAProxy follows the same convention. All header names are
- sent in lower case to clients and servers, regardless of the HTTP version.
+ This option was introduced in order to provide layer 7 persistence to layer 3
+ load balancers. The idea is to use the OS's ability to redirect an incoming
+ connection for a remote address to a local process (here HAProxy), and let
+ this process know what address was initially requested. When this option is
+ used, sessions without cookies will be forwarded to the original destination
+ IP address of the incoming request (which should match that of another
+ equipment), while requests with cookies will still be forwarded to the
+ appropriate server.
- When HAProxy receives an HTTP/1 request, its header names are converted to
- lower case and manipulated and sent this way to the servers. If a server is
- known to violate the HTTP standards and to fail to process a request coming
- from HAProxy, it is possible to transform the lower case header names to a
- different format when the request is formatted and sent to the server, by
- enabling this option and specifying the list of headers to be reformatted
- using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
- must only be a temporary workaround for the time it takes the server to be
- fixed, because servers which require such workarounds might be vulnerable to
- content smuggling attacks and must absolutely be fixed.
-
- Please note that this option will not affect standards-compliant servers.
-
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ Note that contrary to a common belief, this option does NOT make HAProxy
+ present the client's IP to the server when establishing the connection.
- See also: "option h1-case-adjust-bogus-client", "h1-case-adjust",
- "h1-case-adjust-file".
+ See also: the "usesrc" argument of the "source" keyword, and the
+ "transparent" option of the "bind" keyword.
-option http-buffer-request
-no option http-buffer-request
- Enable or disable waiting for whole HTTP request body before proceeding
+external-check command <command>
+ Executable to run when performing an external-check
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
-
- It is sometimes desirable to wait for the body of an HTTP request before
- taking a decision. This is what is being done by "balance url_param" for
- example. The first use case is to buffer requests from slow clients before
- connecting to the server. Another use case consists in taking the routing
- decision based on the request body's contents. This option placed in a
- frontend or backend forces the HTTP processing to wait until either the whole
- body is received or the request buffer is full. It can have undesired side
- effects with some applications abusing HTTP by expecting unbuffered
- transmissions between the frontend and the backend, so this should definitely
- not be used by default.
+ yes | no | yes | yes
- See also : "option http-no-delay", "timeout http-request",
- "http-request wait-for-body"
+ Arguments :
+ <command> is the external command to run
+ The arguments passed to the to the command are:
-option http-ignore-probes
-no option http-ignore-probes
- Enable or disable logging of null connections and request timeouts
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ <proxy_address> <proxy_port> <server_address> <server_port>
- Recently some browsers started to implement a "pre-connect" feature
- consisting in speculatively connecting to some recently visited web sites
- just in case the user would like to visit them. This results in many
- connections being established to web sites, which end up in 408 Request
- Timeout if the timeout strikes first, or 400 Bad Request when the browser
- decides to close them first. These ones pollute the log and feed the error
- counters. There was already "option dontlognull" but it's insufficient in
- this case. Instead, this option does the following things :
- - prevent any 400/408 message from being sent to the client if nothing
- was received over a connection before it was closed;
- - prevent any log from being emitted in this situation;
- - prevent any error counter from being incremented
+ The <proxy_address> and <proxy_port> are derived from the first listener
+ that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
+ listener the proxy_address will be the path of the socket and the
+ <proxy_port> will be the string "NOT_USED". In a backend section, it's not
+ possible to determine a listener, and both <proxy_address> and <proxy_port>
+ will have the string value "NOT_USED".
- That way the empty connection is silently ignored. Note that it is better
- not to use this unless it is clear that it is needed, because it will hide
- real problems. The most common reason for not receiving a request and seeing
- a 408 is due to an MTU inconsistency between the client and an intermediary
- element such as a VPN, which blocks too large packets. These issues are
- generally seen with POST requests as well as GET with large cookies. The logs
- are often the only way to detect them.
+ Some values are also provided through environment variables.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ Environment variables :
+ HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
+ applicable, for example in a "backend" section).
- See also : "log", "dontlognull", "errorfile", and section 8 about logging.
+ HAPROXY_PROXY_ID The backend id.
+ HAPROXY_PROXY_NAME The backend name.
-option http-keep-alive
-no option http-keep-alive
- Enable or disable HTTP keep-alive from client to server for HTTP/1.x
- connections
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ HAPROXY_PROXY_PORT The first bind port if available (or empty if not
+ applicable, for example in a "backend" section or
+ for a UNIX socket).
- By default HAProxy operates in keep-alive mode with regards to persistent
- HTTP/1.x connections: for each connection it processes each request and
- response, and leaves the connection idle on both sides. This mode may be
- changed by several options such as "option http-server-close" or "option
- httpclose". This option allows to set back the keep-alive mode, which can be
- useful when another mode was used in a defaults section.
+ HAPROXY_SERVER_ADDR The server address.
- Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
- and server- sides. This provides the lowest latency on the client side (slow
- network) and the fastest session reuse on the server side at the expense
- of maintaining idle connections to the servers. In general, it is possible
- with this option to achieve approximately twice the request rate that the
- "http-server-close" option achieves on small objects. There are mainly two
- situations where this option may be useful :
+ HAPROXY_SERVER_CURCONN The current number of connections on the server.
- - when the server is non-HTTP compliant and authenticates the connection
- instead of requests (e.g. NTLM authentication)
+ HAPROXY_SERVER_ID The server id.
- - when the cost of establishing the connection to the server is significant
- compared to the cost of retrieving the associated object from the server.
+ HAPROXY_SERVER_MAXCONN The server max connections.
- This last case can happen when the server is a fast static server of cache.
+ HAPROXY_SERVER_NAME The server name.
- At the moment, logs will not indicate whether requests came from the same
- session or not. The accept date reported in the logs corresponds to the end
- of the previous request, and the request time corresponds to the time spent
- waiting for a new request. The keep-alive request time is still bound to the
- timeout defined by "timeout http-keep-alive" or "timeout http-request" if
- not set.
+ HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
+ socket).
- This option disables and replaces any previous "option httpclose" or "option
- http-server-close".
+ HAPROXY_SERVER_SSL "0" when SSL is not used, "1" when it is used
- See also : "option httpclose",, "option http-server-close",
- "option prefer-last-server" and "option http-pretend-keepalive".
+ HAPROXY_SERVER_PROTO The protocol used by this server, which can be one
+ of "cli" (the haproxy CLI), "syslog" (syslog TCP
+ server), "peers" (peers TCP server), "h1" (HTTP/1.x
+ server), "h2" (HTTP/2 server), or "tcp" (any other
+ TCP server).
+ PATH The PATH environment variable used when executing
+ the command may be set using "external-check path".
-option http-no-delay
-no option http-no-delay
- Instruct the system to favor low interactive delays over performance in HTTP
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ See also "2.3. Environment variables" for other variables.
- In HTTP, each payload is unidirectional and has no notion of interactivity.
- Any agent is expected to queue data somewhat for a reasonably low delay.
- There are some very rare server-to-server applications that abuse the HTTP
- protocol and expect the payload phase to be highly interactive, with many
- interleaved data chunks in both directions within a single request. This is
- absolutely not supported by the HTTP specification and will not work across
- most proxies or servers. When such applications attempt to do this through
- HAProxy, it works but they will experience high delays due to the network
- optimizations which favor performance by instructing the system to wait for
- enough data to be available in order to only send full packets. Typical
- delays are around 200 ms per round trip. Note that this only happens with
- abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
- affected.
+ If the command executed and exits with a zero status then the check is
+ considered to have passed, otherwise the check is considered to have
+ failed.
- When "option http-no-delay" is present in either the frontend or the backend
- used by a connection, all such optimizations will be disabled in order to
- make the exchanges as fast as possible. Of course this offers no guarantee on
- the functionality, as it may break at any other place. But if it works via
- HAProxy, it will work as fast as possible. This option should never be used
- by default, and should never be used at all unless such a buggy application
- is discovered. The impact of using this option is an increase of bandwidth
- usage and CPU usage, which may significantly lower performance in high
- latency environments.
+ Example :
+ external-check command /bin/true
- See also : "option http-buffer-request"
+ See also : "external-check", "option external-check", "external-check path"
-option http-pretend-keepalive
-no option http-pretend-keepalive
- Define whether HAProxy will announce keepalive for HTTP/1.x connection to the
- server or not
+external-check path <path>
+ The value of the PATH environment variable used when running an external-check
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
-
- When running with "option http-server-close" or "option httpclose", HAProxy
- adds a "Connection: close" header to the HTTP/1.x request forwarded to the
- server. Unfortunately, when some servers see this header, they automatically
- refrain from using the chunked encoding for responses of unknown length,
- while this is totally unrelated. The effect is that a client or a cache could
- receive an incomplete response without being aware of it, and consider the
- response complete.
+ yes | no | yes | yes
- By setting "option http-pretend-keepalive", HAProxy will make the server
- believe it will keep the connection alive. The server will then not fall back
- to the abnormal undesired above. When HAProxy gets the whole response, it
- will close the connection with the server just as it would do with the
- "option httpclose". That way the client gets a normal response and the
- connection is correctly closed on the server side.
+ Arguments :
+ <path> is the path used when executing external command to run
- It is recommended not to enable this option by default, because most servers
- will more efficiently close the connection themselves after the last packet,
- and release its buffers slightly earlier. Also, the added packet on the
- network could slightly reduce the overall peak performance. However it is
- worth noting that when this option is enabled, HAProxy will have slightly
- less work to do. So if HAProxy is the bottleneck on the whole architecture,
- enabling this option might save a few CPU cycles.
+ The default path is "".
- This option may be set in backend and listen sections. Using it in a frontend
- section will be ignored and a warning will be reported during startup. It is
- a backend related option, so there is no real reason to set it on a
- frontend.
+ Example :
+ external-check path "/usr/bin:/bin"
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ See also : "external-check", "option external-check",
+ "external-check command"
- See also : "option httpclose", "option http-server-close", and
- "option http-keep-alive"
-option http-restrict-req-hdr-names { preserve | delete | reject }
- Set HAProxy policy about HTTP request header names containing characters
- outside the "[a-zA-Z0-9-]" charset
+persist rdp-cookie
+persist rdp-cookie(<name>)
+ Enable RDP cookie-based persistence
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
+ yes | no | yes | yes
Arguments :
- preserve disable the filtering. It is the default mode for HTTP proxies
- with no FastCGI application configured.
+ <name> is the optional name of the RDP cookie to check. If omitted, the
+ default cookie name "msts" will be used. There currently is no
+ valid reason to change this name.
- delete remove request headers with a name containing a character
- outside the "[a-zA-Z0-9-]" charset. It is the default mode for
- HTTP backends with a configured FastCGI application.
+ This statement enables persistence based on an RDP cookie. The RDP cookie
+ contains all information required to find the server in the list of known
+ servers. So when this option is set in the backend, the request is analyzed
+ and if an RDP cookie is found, it is decoded. If it matches a known server
+ which is still UP (or if "option persist" is set), then the connection is
+ forwarded to this server.
- reject reject the request with a 403-Forbidden response if it contains a
- header name with a character outside the "[a-zA-Z0-9-]" charset.
+ Note that this only makes sense in a TCP backend, but for this to work, the
+ frontend must have waited long enough to ensure that an RDP cookie is present
+ in the request buffer. This is the same requirement as with the "rdp-cookie"
+ load-balancing method. Thus it is highly recommended to put all statements in
+ a single "listen" section.
- This option may be used to restrict the request header names to alphanumeric
- and hyphen characters ([A-Za-z0-9-]). This may be mandatory to interoperate
- with non-HTTP compliant servers that fail to handle some characters in header
- names. It may also be mandatory for FastCGI applications because all
- non-alphanumeric characters in header names are replaced by an underscore
- ('_'). Thus, it is easily possible to mix up header names and bypass some
- rules. For instance, "X-Forwarded-For" and "X_Forwarded-For" headers are both
- converted to "HTTP_X_FORWARDED_FOR" in FastCGI.
+ Also, it is important to understand that the terminal server will emit this
+ RDP cookie only if it is configured for "token redirection mode", which means
+ that the "IP address redirection" option is disabled.
- Note this option is evaluated per proxy and after the http-request rules
- evaluation.
-
-option http-server-close
-no option http-server-close
- Enable or disable HTTP/1.x connection closing on the server side
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
-
- By default HAProxy operates in keep-alive mode with regards to persistent
- HTTP/1.x connections: for each connection it processes each request and
- response, and leaves the connection idle on both sides. This mode may be
- changed by several options such as "option http-server-close" or "option
- httpclose". Setting "option http-server-close" enables HTTP connection-close
- mode on the server side while keeping the ability to support HTTP keep-alive
- and pipelining on the client side. This provides the lowest latency on the
- client side (slow network) and the fastest session reuse on the server side
- to save server resources, similarly to "option httpclose". It also permits
- non-keepalive capable servers to be served in keep-alive mode to the clients
- if they conform to the requirements of RFC7230. Please note that some servers
- do not always conform to those requirements when they see "Connection: close"
- in the request. The effect will be that keep-alive will never be used. A
- workaround consists in enabling "option http-pretend-keepalive".
-
- At the moment, logs will not indicate whether requests came from the same
- session or not. The accept date reported in the logs corresponds to the end
- of the previous request, and the request time corresponds to the time spent
- waiting for a new request. The keep-alive request time is still bound to the
- timeout defined by "timeout http-keep-alive" or "timeout http-request" if
- not set.
-
- This option may be set both in a frontend and in a backend. It is enabled if
- at least one of the frontend or backend holding a connection has it enabled.
- It disables and replaces any previous "option httpclose" or "option
- http-keep-alive". Please check section 4 ("Proxies") to see how this option
- combines with others when frontend and backend options differ.
+ Example :
+ listen tse-farm
+ bind :3389
+ # wait up to 5s for an RDP cookie in the request
+ tcp-request inspect-delay 5s
+ tcp-request content accept if RDP_COOKIE
+ # apply RDP cookie persistence
+ persist rdp-cookie
+ # if server is unknown, let's balance on the same cookie.
+ # alternatively, "balance leastconn" may be useful too.
+ balance rdp-cookie
+ server srv1 1.1.1.1:3389
+ server srv2 1.1.1.2:3389
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ See also : "balance rdp-cookie", "tcp-request" and the "req.rdp_cookie" ACL.
- See also : "option httpclose", "option http-pretend-keepalive" and
- "option http-keep-alive".
-option http-use-proxy-header
-no option http-use-proxy-header
- Make use of non-standard Proxy-Connection header instead of Connection
+rate-limit sessions <rate>
+ Set a limit on the number of new sessions accepted per second on a frontend
May be used in sections : defaults | frontend | listen | backend
yes | yes | yes | no
- Arguments : none
+ Arguments :
+ <rate> The <rate> parameter is an integer designating the maximum number
+ of new sessions per second to accept on the frontend.
- While RFC7230 explicitly states that HTTP/1.1 agents must use the
- Connection header to indicate their wish of persistent or non-persistent
- connections, both browsers and proxies ignore this header for proxied
- connections and make use of the undocumented, non-standard Proxy-Connection
- header instead. The issue begins when trying to put a load balancer between
- browsers and such proxies, because there will be a difference between what
- HAProxy understands and what the client and the proxy agree on.
+ When the frontend reaches the specified number of new sessions per second, it
+ stops accepting new connections until the rate drops below the limit again.
+ During this time, the pending sessions will be kept in the socket's backlog
+ (in system buffers) and HAProxy will not even be aware that sessions are
+ pending. When applying very low limit on a highly loaded service, it may make
+ sense to increase the socket's backlog using the "backlog" keyword.
- By setting this option in a frontend, HAProxy can automatically switch to use
- that non-standard header if it sees proxied requests. A proxied request is
- defined here as one where the URI begins with neither a '/' nor a '*'. This
- is incompatible with the HTTP tunnel mode. Note that this option can only be
- specified in a frontend and will affect the request along its whole life.
+ This feature is particularly efficient at blocking connection-based attacks
+ or service abuse on fragile servers. Since the session rate is measured every
+ millisecond, it is extremely accurate. Also, the limit applies immediately,
+ no delay is needed at all to detect the threshold.
- Also, when this option is set, a request which requires authentication will
- automatically switch to use proxy authentication headers if it is itself a
- proxied request. That makes it possible to check or enforce authentication in
- front of an existing proxy.
+ Example : limit the connection rate on SMTP to 10 per second max
+ listen smtp
+ mode tcp
+ bind :25
+ rate-limit sessions 10
+ server smtp1 127.0.0.1:1025
- This option should normally never be used, except in front of a proxy.
+ Note : when the maximum rate is reached, the frontend's status is not changed
+ but its sockets appear as "WAITING" in the statistics if the
+ "socket-stats" option is enabled.
- See also : "option httpclose", and "option http-server-close".
+ See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
-option httpchk
-option httpchk <uri>
-option httpchk <method> <uri>
-option httpchk <method> <uri> <version>
- Enables HTTP protocol to check on the servers health
+
+redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
+redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
+redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
+ Return an HTTP redirection if/unless a condition is matched
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <method> is the optional HTTP method used with the requests. When not set,
- the "OPTIONS" method is used, as it generally requires low server
- processing and is easy to filter out from the logs. Any method
- may be used, though it is not recommended to invent non-standard
- ones.
+ no | yes | yes | yes
- <uri> is the URI referenced in the HTTP requests. It defaults to " / "
- which is accessible by default on almost any server, but may be
- changed to any other URI. Query strings are permitted.
+ If/unless the condition is matched, the HTTP request will lead to a redirect
+ response. If no condition is specified, the redirect applies unconditionally.
- <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
- but some servers might behave incorrectly in HTTP 1.0, so turning
- it to HTTP/1.1 may sometimes help. Note that the Host field is
- mandatory in HTTP/1.1, use "http-check send" directive to add it.
+ Arguments :
+ <loc> With "redirect location", the exact value in <loc> is placed into
+ the HTTP "Location" header. When used in an "http-request" rule,
+ <loc> value follows the log-format rules and can include some
+ dynamic values (see Custom Log Format in section 8.2.4).
- By default, server health checks only consist in trying to establish a TCP
- connection. When "option httpchk" is specified, a complete HTTP request is
- sent once the TCP connection is established, and responses 2xx and 3xx are
- considered valid, while all other ones indicate a server failure, including
- the lack of any response.
+ <pfx> With "redirect prefix", the "Location" header is built from the
+ concatenation of <pfx> and the complete URI path, including the
+ query string, unless the "drop-query" option is specified (see
+ below). As a special case, if <pfx> equals exactly "/", then
+ nothing is inserted before the original URI. It allows one to
+ redirect to the same URL (for instance, to insert a cookie). When
+ used in an "http-request" rule, <pfx> value follows the log-format
+ rules and can include some dynamic values (see Custom Log Format
+ in section 8.2.4).
- Combined with "http-check" directives, it is possible to customize the
- request sent during the HTTP health checks or the matching rules on the
- response. It is also possible to configure a send/expect sequence, just like
- with the directive "tcp-check" for TCP health checks.
+ <sch> With "redirect scheme", then the "Location" header is built by
+ concatenating <sch> with "://" then the first occurrence of the
+ "Host" header, and then the URI path, including the query string
+ unless the "drop-query" option is specified (see below). If no
+ path is found or if the path is "*", then "/" is used instead. If
+ no "Host" header is found, then an empty host component will be
+ returned, which most recent browsers interpret as redirecting to
+ the same host. This directive is mostly used to redirect HTTP to
+ HTTPS. When used in an "http-request" rule, <sch> value follows
+ the log-format rules and can include some dynamic values (see
+ Custom Log Format in section 8.2.4).
- The server configuration is used by default to open connections to perform
- HTTP health checks. By it is also possible to overwrite server parameters
- using "http-check connect" rules.
+ <code> The code is optional. It indicates which type of HTTP redirection
+ is desired. Only codes 301, 302, 303, 307 and 308 are supported,
+ with 302 used by default if no code is specified. 301 means
+ "Moved permanently", and a browser may cache the Location. 302
+ means "Moved temporarily" and means that the browser should not
+ cache the redirection. 303 is equivalent to 302 except that the
+ browser will fetch the location with a GET method. 307 is just
+ like 302 but makes it clear that the same method must be reused.
+ Likewise, 308 replaces 301 if the same method must be used.
- "httpchk" option does not necessarily require an HTTP backend, it also works
- with plain TCP backends. This is particularly useful to check simple scripts
- bound to some dedicated ports using the inetd daemon. However, it will always
- internally relies on an HTX multiplexer. Thus, it means the request
- formatting and the response parsing will be strict.
+ <option> There are several options which can be specified to adjust the
+ expected behavior of a redirection :
- Examples :
- # Relay HTTPS traffic to Apache instance and check service availability
- # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
- backend https_relay
- mode tcp
- option httpchk OPTIONS * HTTP/1.1
- http-check send hdr Host www
- server apache1 192.168.1.1:443 check port 80
+ - "drop-query"
+ When this keyword is used in a prefix-based redirection, then the
+ location will be set without any possible query-string, which is useful
+ for directing users to a non-secure page for instance. It has no effect
+ with a location-type redirect.
- See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
- "option pgsql-check", "http-check" and the "check", "port" and
- "inter" server options.
+ - "append-slash"
+ This keyword may be used in conjunction with "drop-query" to redirect
+ users who use a URL not ending with a '/' to the same one with the '/'.
+ It can be useful to ensure that search engines will only see one URL.
+ For this, a return code 301 is preferred.
+ - "ignore-empty"
+ This keyword only has effect when a location is produced using a log
+ format expression (i.e. when used in http-request or http-response).
+ It indicates that if the result of the expression is empty, the rule
+ should silently be skipped. The main use is to allow mass-redirects
+ of known paths using a simple map.
-option httpclose
-no option httpclose
- Enable or disable HTTP/1.x connection closing
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ - "set-cookie NAME[=value]"
+ A "Set-Cookie" header will be added with NAME (and optionally "=value")
+ to the response. This is sometimes used to indicate that a user has
+ been seen, for instance to protect against some types of DoS. No other
+ cookie option is added, so the cookie will be a session cookie. Note
+ that for a browser, a sole cookie name without an equal sign is
+ different from a cookie with an equal sign.
- By default HAProxy operates in keep-alive mode with regards to persistent
- HTTP/1.x connections: for each connection it processes each request and
- response, and leaves the connection idle on both sides. This mode may be
- changed by several options such as "option http-server-close" or "option
- httpclose".
+ - "clear-cookie NAME[=]"
+ A "Set-Cookie" header will be added with NAME (and optionally "="), but
+ with the "Max-Age" attribute set to zero. This will tell the browser to
+ delete this cookie. It is useful for instance on logout pages. It is
+ important to note that clearing the cookie "NAME" will not remove a
+ cookie set with "NAME=value". You have to clear the cookie "NAME=" for
+ that, because the browser makes the difference.
- If "option httpclose" is set, HAProxy will close the client or the server
- connection, depending where the option is set. The frontend is considered for
- client connections while the backend is considered for server ones. If the
- option is set on a listener, it is applied both on client and server
- connections. It will check if a "Connection: close" header is already set in
- each direction, and will add one if missing.
+ Example: move the login URL only to HTTPS.
+ acl clear dst_port 80
+ acl secure dst_port 8080
+ acl login_page url_beg /login
+ acl logout url_beg /logout
+ acl uid_given url_reg /login?userid=[^&]+
+ acl cookie_set hdr_sub(cookie) SEEN=1
- This option may also be combined with "option http-pretend-keepalive", which
- will disable sending of the "Connection: close" request header, but will
- still cause the connection to be closed once the whole response is received.
+ redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
+ redirect prefix https://mysite.com if login_page !secure
+ redirect prefix http://mysite.com drop-query if login_page !uid_given
+ redirect location http://mysite.com/ if !login_page secure
+ redirect location / clear-cookie USERID= if logout
- It disables and replaces any previous "option http-server-close" or "option
- http-keep-alive".
+ Example: send redirects for request for articles without a '/'.
+ acl missing_slash path_reg ^/article/[^/]*$
+ redirect code 301 prefix / drop-query append-slash if missing_slash
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ Example: redirect all HTTP traffic to HTTPS when SSL is handled by HAProxy.
+ redirect scheme https if !{ ssl_fc }
- See also : "option http-server-close".
+ Example: append 'www.' prefix in front of all hosts not having it
+ http-request redirect code 301 location \
+ http://www.%[hdr(host)]%[capture.req.uri] \
+ unless { hdr_beg(host) -i www }
+ Example: permanently redirect only old URLs to new ones
+ http-request redirect code 301 location \
+ %[path,map_str(old-blog-articles.map)] ignore-empty
-option httplog [ clf ]
- Enable logging of HTTP request, session state and timers
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- clf if the "clf" argument is added, then the output format will be
- the CLF format instead of HAProxy's default HTTP format. You can
- use this when you need to feed HAProxy's logs through a specific
- log analyzer which only support the CLF format and which is not
- extensible.
+ See section 7 about ACL usage.
- By default, the log output format is very poor, as it only contains the
- source and destination addresses, and the instance name. By specifying
- "option httplog", each log line turns into a much richer format including,
- but not limited to, the HTTP request, the connection timers, the session
- status, the connections numbers, the captured headers and cookies, the
- frontend, backend and server name, and of course the source address and
- ports.
- Specifying only "option httplog" will automatically clear the 'clf' mode
- if it was set by default.
+retries <value>
+ Set the number of retries to perform on a server after a failure
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <value> is the number of times a request or connection attempt should be
+ retried on a server after a failure.
- "option httplog" overrides any previous "log-format" directive.
+ By default, retries apply only to new connection attempts. However, when
+ the "retry-on" directive is used, other conditions might trigger a retry
+ (e.g. empty response, undesired status code), and each of them will count
+ one attempt, and when the total number attempts reaches the value here, an
+ error will be returned.
- See also : section 8 about logging.
+ In order to avoid immediate reconnections to a server which is restarting,
+ a turn-around timer of min("timeout connect", one second) is applied before
+ a retry occurs on the same server.
-option httpslog
- Enable logging of HTTPS request, session state and timers
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
+ When "option redispatch" is set, some retries may be performed on another
+ server even if a cookie references a different server. By default this will
+ only be the last retry unless an argument is passed to "option redispatch".
- By default, the log output format is very poor, as it only contains the
- source and destination addresses, and the instance name. By specifying
- "option httpslog", each log line turns into a much richer format including,
- but not limited to, the HTTP request, the connection timers, the session
- status, the connections numbers, the captured headers and cookies, the
- frontend, backend and server name, the SSL certificate verification and SSL
- handshake statuses, and of course the source address and ports.
+ See also : "option redispatch"
- "option httpslog" overrides any previous "log-format" directive.
- See also : section 8 about logging.
+retry-on [space-delimited list of keywords]
+ Specify when to attempt to automatically retry a failed request.
+ This setting is only valid when "mode" is set to http and is silently ignored
+ otherwise.
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <keywords> is a space-delimited list of keywords or HTTP status codes, each
+ representing a type of failure event on which an attempt to
+ retry the request is desired. Please read the notes at the
+ bottom before changing this setting. The following keywords are
+ supported :
+ none never retry
-option independent-streams
-no option independent-streams
- Enable or disable independent timeout processing for both directions
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ conn-failure retry when the connection or the SSL handshake failed
+ and the request could not be sent. This is the default.
- By default, when data is sent over a socket, both the write timeout and the
- read timeout for that socket are refreshed, because we consider that there is
- activity on that socket, and we have no other means of guessing if we should
- receive data or not.
+ empty-response retry when the server connection was closed after part
+ of the request was sent, and nothing was received from
+ the server. This type of failure may be caused by the
+ request timeout on the server side, poor network
+ condition, or a server crash or restart while
+ processing the request.
- While this default behavior is desirable for almost all applications, there
- exists a situation where it is desirable to disable it, and only refresh the
- read timeout if there are incoming data. This happens on sessions with large
- timeouts and low amounts of exchanged data such as telnet session. If the
- server suddenly disappears, the output data accumulates in the system's
- socket buffers, both timeouts are correctly refreshed, and there is no way
- to know the server does not receive them, so we don't timeout. However, when
- the underlying protocol always echoes sent data, it would be enough by itself
- to detect the issue using the read timeout. Note that this problem does not
- happen with more verbose protocols because data won't accumulate long in the
- socket buffers.
+ junk-response retry when the server returned something not looking
+ like a complete HTTP response. This includes partial
+ responses headers as well as non-HTTP contents. It
+ usually is a bad idea to retry on such events, which
+ may be caused a configuration issue (wrong server port)
+ or by the request being harmful to the server (buffer
+ overflow attack for example).
- When this option is set on the frontend, it will disable read timeout updates
- on data sent to the client. There probably is little use of this case. When
- the option is set on the backend, it will disable read timeout updates on
- data sent to the server. Doing so will typically break large HTTP posts from
- slow lines, so use it with caution.
+ response-timeout the server timeout stroke while waiting for the server
+ to respond to the request. This may be caused by poor
+ network condition, the reuse of an idle connection
+ which has expired on the path, or by the request being
+ extremely expensive to process. It generally is a bad
+ idea to retry on such events on servers dealing with
+ heavy database processing (full scans, etc) as it may
+ amplify denial of service attacks.
- See also : "timeout client", "timeout server" and "timeout tunnel"
+ 0rtt-rejected retry requests which were sent over early data and were
+ rejected by the server. These requests are generally
+ considered to be safe to retry.
+ <status> any HTTP status code among "401" (Unauthorized), "403"
+ (Forbidden), "404" (Not Found), "408" (Request Timeout),
+ "425" (Too Early), "500" (Server Error), "501" (Not
+ Implemented), "502" (Bad Gateway), "503" (Service
+ Unavailable), "504" (Gateway Timeout).
-option ldap-check
- Use LDAPv3 health checks for server testing
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ all-retryable-errors
+ retry request for any error that are considered
+ retryable. This currently activates "conn-failure",
+ "empty-response", "junk-response", "response-timeout",
+ "0rtt-rejected", "500", "502", "503", and "504".
- It is possible to test that the server correctly talks LDAPv3 instead of just
- testing that it accepts the TCP connection. When this option is set, an
- LDAPv3 anonymous simple bind message is sent to the server, and the response
- is analyzed to find an LDAPv3 bind response message.
+ Using this directive replaces any previous settings with the new ones; it is
+ not cumulative.
- The server is considered valid only when the LDAP response contains success
- resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
+ Please note that using anything other than "none" and "conn-failure" requires
+ to allocate a buffer and copy the whole request into it, so it has memory and
+ performance impacts. Requests not fitting in a single buffer will never be
+ retried (see the global tune.bufsize setting).
- Logging of bind requests is server dependent see your documentation how to
- configure it.
+ You have to make sure the application has a replay protection mechanism built
+ in such as a unique transaction IDs passed in requests, or that replaying the
+ same request has no consequence, or it is very dangerous to use any retry-on
+ value beside "conn-failure" and "none". Static file servers and caches are
+ generally considered safe against any type of retry. Using a status code can
+ be useful to quickly leave a server showing an abnormal behavior (out of
+ memory, file system issues, etc), but in this case it may be a good idea to
+ immediately redispatch the connection to another server (please see "option
+ redispatch" for this). Last, it is important to understand that most causes
+ of failures are the requests themselves and that retrying a request causing a
+ server to misbehave will often make the situation even worse for this server,
+ or for the whole service in case of redispatch.
- Example :
- option ldap-check
+ Unless you know exactly how the application deals with replayed requests, you
+ should not use this directive.
- See also : "option httpchk"
+ The default is "conn-failure".
+ Example:
+ retry-on 503 504
-option external-check
- Use external processes for server health checks
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ See also: "retries", "option redispatch", "tune.bufsize"
- It is possible to test the health of a server using an external command.
- This is achieved by running the executable set using "external-check
- command".
+server <name> <address>[:[port]] [param*]
+ Declare a server in a backend
+ May be used in sections : defaults | frontend | listen | backend
+ no | no | yes | yes
+ Arguments :
+ <name> is the internal name assigned to this server. This name will
+ appear in logs and alerts. If "http-send-name-header" is
+ set, it will be added to the request header sent to the server.
- Requires the "external-check" global to be set.
+ <address> is the IPv4 or IPv6 address of the server. Alternatively, a
+ resolvable hostname is supported, but this name will be resolved
+ during start-up. Address "0.0.0.0" or "*" has a special meaning.
+ It indicates that the connection will be forwarded to the same IP
+ address as the one from the client connection. This is useful in
+ transparent proxy architectures where the client's connection is
+ intercepted and HAProxy must forward to the original destination
+ address. This is more or less what the "transparent" keyword does
+ except that with a server it's possible to limit concurrency and
+ to report statistics. Optionally, an address family prefix may be
+ used before the address to force the family regardless of the
+ address format, which can be useful to specify a path to a unix
+ socket with no slash ('/'). Currently supported prefixes are :
+ - 'ipv4@' -> address is always IPv4
+ - 'ipv6@' -> address is always IPv6
+ - 'unix@' -> address is a path to a local unix socket
+ - 'abns@' -> address is in abstract namespace (Linux only)
+ - 'sockpair@' -> address is the FD of a connected unix
+ socket or of a socketpair. During a connection, the
+ backend creates a pair of connected sockets, and passes
+ one of them over the FD. The bind part will use the
+ received socket as the client FD. Should be used
+ carefully.
+ - 'rhttp@' -> custom address family for a passive server in
+ HTTP reverse context.
+ You may want to reference some environment variables in the
+ address parameter, see section 2.3 about environment
+ variables. The "init-addr" setting can be used to modify the way
+ IP addresses should be resolved upon startup.
- See also : "external-check", "external-check command", "external-check path"
+ <port> is an optional port specification. If set, all connections will
+ be sent to this port. If unset, the same port the client
+ connected to will be used. The port may also be prefixed by a "+"
+ or a "-". In this case, the server's port will be determined by
+ adding this value to the client's port.
+ <param*> is a list of parameters for this server. The "server" keywords
+ accepts an important number of options and has a complete section
+ dedicated to it. Please refer to section 5 for more details.
-option idle-close-on-response
-no option idle-close-on-response
- Avoid closing idle frontend connections if a soft stop is in progress
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ Examples :
+ server first 10.1.1.1:1080 cookie first check inter 1000
+ server second 10.1.1.2:1080 cookie second check inter 1000
+ server transp ipv4@
+ server backup "${SRV_BACKUP}:1080" backup
+ server www1_dc1 "${LAN_DC1}.101:80"
+ server www1_dc2 "${LAN_DC2}.101:80"
- By default, idle connections will be closed during a soft stop. In some
- environments, a client talking to the proxy may have prepared some idle
- connections in order to send requests later. If there is no proper retry on
- write errors, this can result in errors while haproxy is reloading. Even
- though a proper implementation should retry on connection/write errors, this
- option was introduced to support backwards compatibility with haproxy prior
- to version 2.4. Indeed before v2.4, haproxy used to wait for a last request
- and response to add a "connection: close" header before closing, thus
- notifying the client that the connection would not be reusable.
-
- In a real life example, this behavior was seen in AWS using the ALB in front
- of a haproxy. The end result was ALB sending 502 during haproxy reloads.
-
- Users are warned that using this option may increase the number of old
- processes if connections remain idle for too long. Adjusting the client
- timeouts and/or the "hard-stop-after" parameter accordingly might be
- needed in case of frequent reloads.
-
- See also: "timeout client", "timeout client-fin", "timeout http-request",
- "hard-stop-after"
+ Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
+ sun_path length is used for the address length. Some other programs
+ such as socat use the string length only by default. Pass the option
+ ",unix-tightsocklen=0" to any abstract socket definition in socat to
+ make it compatible with HAProxy's.
+ See also: "default-server", "http-send-name-header" and section 5 about
+ server options
-option log-health-checks
-no option log-health-checks
- Enable or disable logging of health checks status updates
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+server-state-file-name [ { use-backend-name | <file> } ]
+ Set the server state file to read, load and apply to servers available in
+ this backend.
+ May be used in sections: defaults | frontend | listen | backend
+ no | no | yes | yes
- By default, failed health check are logged if server is UP and successful
- health checks are logged if server is DOWN, so the amount of additional
- information is limited.
+ It only applies when the directive "load-server-state-from-file" is set to
+ "local". When <file> is not provided, if "use-backend-name" is used or if
+ this directive is not set, then backend name is used. If <file> starts with a
+ slash '/', then it is considered as an absolute path. Otherwise, <file> is
+ concatenated to the global directive "server-state-base".
- When this option is enabled, any change of the health check status or to
- the server's health will be logged, so that it becomes possible to know
- that a server was failing occasional checks before crashing, or exactly when
- it failed to respond a valid HTTP status, then when the port started to
- reject connections, then when the server stopped responding at all.
+ Example: the minimal configuration below would make HAProxy look for the
+ state server file '/etc/haproxy/states/bk':
- Note that status changes not caused by health checks (e.g. enable/disable on
- the CLI) are intentionally not logged by this option.
+ global
+ server-state-file-base /etc/haproxy/states
- See also: "option httpchk", "option ldap-check", "option mysql-check",
- "option pgsql-check", "option redis-check", "option smtpchk",
- "option tcp-check", "log" and section 8 about logging.
+ backend bk
+ load-server-state-from-file
+ See also: "server-state-base", "load-server-state-from-file", and
+ "show servers state"
-option log-separate-errors
-no option log-separate-errors
- Change log level for non-completely successful connections
+server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
+ Set a template to initialize servers with shared parameters.
+ The names of these servers are built from <prefix> and <num | range> parameters.
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
-
- Sometimes looking for errors in logs is not easy. This option makes HAProxy
- raise the level of logs containing potentially interesting information such
- as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
- level changes from "info" to "err". This makes it possible to log them
- separately to a different file with most syslog daemons. Be careful not to
- remove them from the original file, otherwise you would lose ordering which
- provides very important information.
+ no | no | yes | yes
- Using this option, large sites dealing with several thousand connections per
- second may log normal traffic to a rotating buffer and only archive smaller
- error logs.
+ Arguments:
+ <prefix> A prefix for the server names to be built.
- See also : "log", "dontlognull", "dontlog-normal" and section 8 about
- logging.
+ <num | range>
+ If <num> is provided, this template initializes <num> servers
+ with 1 up to <num> as server name suffixes. A range of numbers
+ <num_low>-<num_high> may also be used to use <num_low> up to
+ <num_high> as server name suffixes.
+ <fqdn> A FQDN for all the servers this template initializes.
-option logasap
-no option logasap
- Enable or disable early logging.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ <port> Same meaning as "server" <port> argument (see "server" keyword).
- By default, logs are emitted when all the log format variables and sample
- fetches used in the definition of the log-format string return a value, or
- when the session is terminated. This allows the built in log-format strings
- to account for the transfer time, or the number of bytes in log messages.
+ <params*>
+ Remaining server parameters among all those supported by "server"
+ keyword.
- When handling long lived connections such as large file transfers or RDP,
- it may take a while for the request or connection to appear in the logs.
- Using "option logasap", the log message is created as soon as the server
- connection is established in mode tcp, or as soon as the server sends the
- complete headers in mode http. Missing information in the logs will be the
- total number of bytes which will only indicate the amount of data transferred
- before the message was created and the total time which will not take the
- remainder of the connection life or transfer time into account. For the case
- of HTTP, it is good practice to capture the Content-Length response header
- so that the logs at least indicate how many bytes are expected to be
- transferred.
+ Examples:
+ # Initializes 3 servers with srv1, srv2 and srv3 as names,
+ # google.com as FQDN, and health-check enabled.
+ server-template srv 1-3 google.com:80 check
- Examples :
- listen http_proxy 0.0.0.0:80
- mode http
- option httplog
- option logasap
- log 192.168.2.200 local3
+ # or
+ server-template srv 3 google.com:80 check
- >>> Feb 6 12:14:14 localhost \
- haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
- static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
- "GET /image.iso HTTP/1.0"
+ # would be equivalent to:
+ server srv1 google.com:80 check
+ server srv2 google.com:80 check
+ server srv3 google.com:80 check
- See also : "option httplog", "capture response header", and section 8 about
- logging.
-option mysql-check [ user <username> [ { post-41 | pre-41 } ] ]
- Use MySQL health checks for server testing
+source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
+source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
+source <addr>[:<port>] [interface <name>]
+ Set the source address for outgoing connections
May be used in sections : defaults | frontend | listen | backend
yes | no | yes | yes
Arguments :
- <username> This is the username which will be used when connecting to MySQL
- server.
- post-41 Send post v4.1 client compatible checks (the default)
- pre-41 Send pre v4.1 client compatible checks
-
- If you specify a username, the check consists of sending two MySQL packet,
- one Client Authentication packet, and one QUIT packet, to correctly close
- MySQL session. We then parse the MySQL Handshake Initialization packet and/or
- Error packet. It is a basic but useful test which does not produce error nor
- aborted connect on the server. However, it requires an unlocked authorised
- user without a password. To create a basic limited user in MySQL with
- optional resource limits:
+ <addr> is the IPv4 address HAProxy will bind to before connecting to a
+ server. This address is also used as a source for health checks.
- CREATE USER '<username>'@'<ip_of_haproxy|network_of_haproxy/netmask>'
- /*!50701 WITH MAX_QUERIES_PER_HOUR 1 MAX_UPDATES_PER_HOUR 0 */
- /*M!100201 MAX_STATEMENT_TIME 0.0001 */;
+ The default value of 0.0.0.0 means that the system will select
+ the most appropriate address to reach its destination. Optionally
+ an address family prefix may be used before the address to force
+ the family regardless of the address format, which can be useful
+ to specify a path to a unix socket with no slash ('/'). Currently
+ supported prefixes are :
+ - 'ipv4@' -> address is always IPv4
+ - 'ipv6@' -> address is always IPv6
+ - 'unix@' -> address is a path to a local unix socket
+ - 'abns@' -> address is in abstract namespace (Linux only)
+ You may want to reference some environment variables in the
+ address parameter, see section 2.3 about environment variables.
- If you don't specify a username (it is deprecated and not recommended), the
- check only consists in parsing the Mysql Handshake Initialization packet or
- Error packet, we don't send anything in this mode. It was reported that it
- can generate lockout if check is too frequent and/or if there is not enough
- traffic. In fact, you need in this case to check MySQL "max_connect_errors"
- value as if a connection is established successfully within fewer than MySQL
- "max_connect_errors" attempts after a previous connection was interrupted,
- the error count for the host is cleared to zero. If HAProxy's server get
- blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
+ <port> is an optional port. It is normally not needed but may be useful
+ in some very specific contexts. The default value of zero means
+ the system will select a free port. Note that port ranges are not
+ supported in the backend. If you want to force port ranges, you
+ have to specify them on each "server" line.
- Remember that this does not check database presence nor database consistency.
- To do this, you can use an external check with xinetd for example.
+ <addr2> is the IP address to present to the server when connections are
+ forwarded in full transparent proxy mode. This is currently only
+ supported on some patched Linux kernels. When this address is
+ specified, clients connecting to the server will be presented
+ with this address, while health checks will still use the address
+ <addr>.
- The check requires MySQL >=3.22, for older version, please use TCP check.
+ <port2> is the optional port to present to the server when connections
+ are forwarded in full transparent proxy mode (see <addr2> above).
+ The default value of zero means the system will select a free
+ port.
- Most often, an incoming MySQL server needs to see the client's IP address for
- various purposes, including IP privilege matching and connection logging.
- When possible, it is often wise to masquerade the client's IP address when
- connecting to the server using the "usesrc" argument of the "source" keyword,
- which requires the transparent proxy feature to be compiled in, and the MySQL
- server to route the client via the machine hosting HAProxy.
+ <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
+ This is the name of a comma-separated header list which can
+ contain multiple IP addresses. By default, the last occurrence is
+ used. This is designed to work with the X-Forwarded-For header
+ and to automatically bind to the client's IP address as seen
+ by previous proxy, typically Stunnel. In order to use another
+ occurrence from the last one, please see the <occ> parameter
+ below. When the header (or occurrence) is not found, no binding
+ is performed so that the proxy's default IP address is used. Also
+ keep in mind that the header name is case insensitive, as for any
+ HTTP header.
- See also: "option httpchk"
+ <occ> is the occurrence number of a value to be used in a multi-value
+ header. This is to be used in conjunction with "hdr_ip(<hdr>)",
+ in order to specify which occurrence to use for the source IP
+ address. Positive values indicate a position from the first
+ occurrence, 1 being the first one. Negative values indicate
+ positions relative to the last one, -1 being the last one. This
+ is helpful for situations where an X-Forwarded-For header is set
+ at the entry point of an infrastructure and must be used several
+ proxy layers away. When this value is not specified, -1 is
+ assumed. Passing a zero here disables the feature.
+ <name> is an optional interface name to which to bind to for outgoing
+ traffic. On systems supporting this features (currently, only
+ Linux), this allows one to bind all traffic to the server to
+ this interface even if it is not the one the system would select
+ based on routing tables. This should be used with extreme care.
+ Note that using this option requires root privileges.
-option nolinger
-no option nolinger
- Enable or disable immediate session resource cleaning after close
- May be used in sections: defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ The "source" keyword is useful in complex environments where a specific
+ address only is allowed to connect to the servers. It may be needed when a
+ private address must be used through a public gateway for instance, and it is
+ known that the system cannot determine the adequate source address by itself.
- When clients or servers abort connections in a dirty way (e.g. they are
- physically disconnected), the session timeouts triggers and the session is
- closed. But it will remain in FIN_WAIT1 state for some time in the system,
- using some resources and possibly limiting the ability to establish newer
- connections.
+ An extension which is available on certain patched Linux kernels may be used
+ through the "usesrc" optional keyword. It makes it possible to connect to the
+ servers with an IP address which does not belong to the system itself. This
+ is called "full transparent proxy mode". For this to work, the destination
+ servers have to route their traffic back to this address through the machine
+ running HAProxy, and IP forwarding must generally be enabled on this machine.
- When this happens, it is possible to activate "option nolinger" which forces
- the system to immediately remove any socket's pending data on close. Thus,
- a TCP RST is emitted, any pending data are truncated, and the session is
- instantly purged from the system's tables. The generally visible effect for
- a client is that responses are truncated if the close happens with a last
- block of data (e.g. on a redirect or error response). On the server side,
- it may help release the source ports immediately when forwarding a client
- aborts in tunnels. In both cases, TCP resets are emitted and given that
- the session is instantly destroyed, there will be no retransmit. On a lossy
- network this can increase problems, especially when there is a firewall on
- the lossy side, because the firewall might see and process the reset (hence
- purge its session) and block any further traffic for this session,, including
- retransmits from the other side. So if the other side doesn't receive it,
- it will never receive any RST again, and the firewall might log many blocked
- packets.
-
- For all these reasons, it is strongly recommended NOT to use this option,
- unless absolutely needed as a last resort. In most situations, using the
- "client-fin" or "server-fin" timeouts achieves similar results with a more
- reliable behavior. On Linux it's also possible to use the "tcp-ut" bind or
- server setting.
-
- This option may be used both on frontends and backends, depending on the side
- where it is required. Use it on the frontend for clients, and on the backend
- for servers. While this option is technically supported in "defaults"
- sections, it must really not be used there as it risks to accidentally
- propagate to sections that must no use it and to cause problems there.
-
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
-
- See also: "timeout client-fin", "timeout server-fin", "tcp-ut" bind or server
- keywords.
-
-option originalto [ except <network> ] [ header <name> ]
- Enable insertion of the X-Original-To header to requests sent to servers
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <network> is an optional argument used to disable this option for sources
- matching <network>
- <name> an optional argument to specify a different "X-Original-To"
- header name.
+ In this "full transparent proxy" mode, it is possible to force a specific IP
+ address to be presented to the servers. This is not much used in fact. A more
+ common use is to tell HAProxy to present the client's IP address. For this,
+ there are two methods :
- Since HAProxy can work in transparent mode, every request from a client can
- be redirected to the proxy and HAProxy itself can proxy every request to a
- complex SQUID environment and the destination host from SO_ORIGINAL_DST will
- be lost. This is annoying when you want access rules based on destination ip
- addresses. To solve this problem, a new HTTP header "X-Original-To" may be
- added by HAProxy to all requests sent to the server. This header contains a
- value representing the original destination IP address. Since this must be
- configured to always use the last occurrence of this header only. Note that
- only the last occurrence of the header must be used, since it is really
- possible that the client has already brought one.
+ - present the client's IP and port addresses. This is the most transparent
+ mode, but it can cause problems when IP connection tracking is enabled on
+ the machine, because a same connection may be seen twice with different
+ states. However, this solution presents the huge advantage of not
+ limiting the system to the 64k outgoing address+port couples, because all
+ of the client ranges may be used.
- The keyword "header" may be used to supply a different header name to replace
- the default "X-Original-To". This can be useful where you might already
- have a "X-Original-To" header from a different application, and you need
- preserve it. Also if your backend server doesn't use the "X-Original-To"
- header and requires different one.
+ - present only the client's IP address and select a spare port. This
+ solution is still quite elegant but slightly less transparent (downstream
+ firewalls logs will not match upstream's). It also presents the downside
+ of limiting the number of concurrent connections to the usual 64k ports.
+ However, since the upstream and downstream ports are different, local IP
+ connection tracking on the machine will not be upset by the reuse of the
+ same session.
- Sometimes, a same HAProxy instance may be shared between a direct client
- access and a reverse-proxy access (for instance when an SSL reverse-proxy is
- used to decrypt HTTPS traffic). It is possible to disable the addition of the
- header for a known destination address or network by adding the "except"
- keyword followed by the network address. In this case, any destination IP
- matching the network will not cause an addition of this header. Most common
- uses are with private networks or 127.0.0.1. IPv4 and IPv6 are both
- supported.
+ This option sets the default source for all servers in the backend. It may
+ also be specified in a "defaults" section. Finer source address specification
+ is possible at the server level using the "source" server option. Refer to
+ section 5 for more information.
- This option may be specified either in the frontend or in the backend. If at
- least one of them uses it, the header will be added. Note that the backend's
- setting of the header subargument takes precedence over the frontend's if
- both are defined.
+ In order to work, "usesrc" requires root privileges, or on supported systems,
+ the "cap_net_raw" capability. See also the "setcap" global directive.
Examples :
- # Original Destination address
- frontend www
- mode http
- option originalto except 127.0.0.1
-
- # Those servers want the IP Address in X-Client-Dst
- backend www
- mode http
- option originalto header X-Client-Dst
+ backend private
+ # Connect to the servers using our 192.168.1.200 source address
+ source 192.168.1.200
- See also : "option httpclose", "option http-server-close".
+ backend transparent_ssl1
+ # Connect to the SSL farm from the client's source address
+ source 192.168.1.200 usesrc clientip
+ backend transparent_ssl2
+ # Connect to the SSL farm from the client's source address and port
+ # not recommended if IP conntrack is present on the local machine.
+ source 192.168.1.200 usesrc client
-option persist
-no option persist
- Enable or disable forced persistence on down servers
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ backend transparent_ssl3
+ # Connect to the SSL farm from the client's source address. It
+ # is more conntrack-friendly.
+ source 192.168.1.200 usesrc clientip
- When an HTTP request reaches a backend with a cookie which references a dead
- server, by default it is redispatched to another server. It is possible to
- force the request to be sent to the dead server first using "option persist"
- if absolutely needed. A common use case is when servers are under extreme
- load and spend their time flapping. In this case, the users would still be
- directed to the server they opened the session on, in the hope they would be
- correctly served. It is recommended to use "option redispatch" in conjunction
- with this option so that in the event it would not be possible to connect to
- the server at all (server definitely dead), the client would finally be
- redirected to another valid server.
+ backend transparent_smtp
+ # Connect to the SMTP farm from the client's source address/port
+ # with Tproxy version 4.
+ source 0.0.0.0 usesrc clientip
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ backend transparent_http
+ # Connect to the servers using the client's IP as seen by previous
+ # proxy.
+ source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
- See also : "option redispatch", "retries", "force-persist"
+ See also : the "source" server option in section 5, the Tproxy patches for
+ the Linux kernel on www.balabit.com, the "bind" keyword.
-option pgsql-check user <username>
- Use PostgreSQL health checks for server testing
+srvtcpka-cnt <count>
+ Sets the maximum number of keepalive probes TCP should send before dropping
+ the connection on the server side.
May be used in sections : defaults | frontend | listen | backend
yes | no | yes | yes
Arguments :
- <username> This is the username which will be used when connecting to
- PostgreSQL server.
+ <count> is the maximum number of keepalive probes.
- The check sends a PostgreSQL StartupMessage and waits for either
- Authentication request or ErrorResponse message. It is a basic but useful
- test which does not produce error nor aborted connect on the server.
- This check is identical with the "mysql-check".
+ This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword
+ is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used.
+ The availability of this setting depends on the operating system. It is
+ known to work on Linux.
- See also: "option httpchk"
+ See also : "option srvtcpka", "srvtcpka-idle", "srvtcpka-intvl".
-option prefer-last-server
-no option prefer-last-server
- Allow multiple load balanced requests to remain on the same server
- May be used in sections: defaults | frontend | listen | backend
+srvtcpka-idle <timeout>
+ Sets the time the connection needs to remain idle before TCP starts sending
+ keepalive probes, if enabled the sending of TCP keepalive packets on the
+ server side.
+ May be used in sections : defaults | frontend | listen | backend
yes | no | yes | yes
- Arguments : none
-
- When the load balancing algorithm in use is not deterministic, and a previous
- request was sent to a server to which HAProxy still holds a connection, it is
- sometimes desirable that subsequent requests on a same session go to the same
- server as much as possible. Note that this is different from persistence, as
- we only indicate a preference which HAProxy tries to apply without any form
- of warranty. The real use is for keep-alive connections sent to servers. When
- this option is used, HAProxy will try to reuse the same connection that is
- attached to the server instead of rebalancing to another server, causing a
- close of the connection. This can make sense for static file servers. It does
- not make much sense to use this in combination with hashing algorithms. Note,
- HAProxy already automatically tries to stick to a server which sends a 401 or
- to a proxy which sends a 407 (authentication required), when the load
- balancing algorithm is not deterministic. This is mandatory for use with the
- broken NTLM authentication challenge, and significantly helps in
- troubleshooting some faulty applications. Option prefer-last-server might be
- desirable in these environments as well, to avoid redistributing the traffic
- after every other response.
+ Arguments :
+ <timeout> is the time the connection needs to remain idle before TCP starts
+ sending keepalive probes. It is specified in seconds by default,
+ but can be in any other unit if the number is suffixed by the
+ unit, as explained at the top of this document.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword
+ is not specified, system-wide TCP parameter (tcp_keepalive_time) is used.
+ The availability of this setting depends on the operating system. It is
+ known to work on Linux.
- See also: "option http-keep-alive"
+ See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-intvl".
-option redispatch
-option redispatch <interval>
-no option redispatch
- Enable or disable session redistribution in case of connection failure
- May be used in sections: defaults | frontend | listen | backend
+srvtcpka-intvl <timeout>
+ Sets the time between individual keepalive probes on the server side.
+ May be used in sections : defaults | frontend | listen | backend
yes | no | yes | yes
Arguments :
- <interval> The optional integer value that controls how often redispatches
- occur when retrying connections. Positive value P indicates a
- redispatch is desired on every Pth retry, and negative value
- N indicate a redispatch is desired on the Nth retry prior to the
- last retry. For example, the default of -1 preserves the
- historical behavior of redispatching on the last retry, a
- positive value of 1 would indicate a redispatch on every retry,
- and a positive value of 3 would indicate a redispatch on every
- third retry. You can disable redispatches with a value of 0.
+ <timeout> is the time between individual keepalive probes. It is specified
+ in seconds by default, but can be in any other unit if the number
+ is suffixed by the unit, as explained at the top of this
+ document.
+ This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword
+ is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used.
+ The availability of this setting depends on the operating system. It is
+ known to work on Linux.
- In HTTP mode, if a server designated by a cookie is down, clients may
- definitely stick to it because they cannot flush the cookie, so they will not
- be able to access the service anymore.
+ See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-idle".
- Specifying "option redispatch" will allow the proxy to break cookie or
- consistent hash based persistence and redistribute them to a working server.
- Active servers are selected from a subset of the list of available
- servers. Active servers that are not down or in maintenance (i.e., whose
- health is not checked or that have been checked as "up"), are selected in the
- following order:
+stats admin { if | unless } <cond>
+ Enable statistics admin level if/unless a condition is matched
+ May be used in sections : defaults | frontend | listen | backend
+ no | yes | yes | yes
- 1. Any active, non-backup server, if any, or,
+ This statement enables the statistics admin level if/unless a condition is
+ matched.
- 2. If the "allbackups" option is not set, the first backup server in the
- list, or
+ The admin level allows to enable/disable servers from the web interface. By
+ default, statistics page is read-only for security reasons.
- 3. If the "allbackups" option is set, any backup server.
+ Currently, the POST request is limited to the buffer size minus the reserved
+ buffer space, which means that if the list of servers is too long, the
+ request won't be processed. It is recommended to alter few servers at a
+ time.
- When a retry occurs, HAProxy tries to select another server than the last
- one. The new server is selected from the current list of servers.
-
- Sometimes, if the list is updated between retries (e.g., if numerous retries
- occur and last longer than the time needed to check that a server is down,
- remove it from the list and fall back on the list of backup servers),
- connections may be redirected to a backup server, though.
-
- It also allows to retry connections to another server in case of multiple
- connection failures. Of course, it requires having "retries" set to a nonzero
- value.
-
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
-
- See also : "retries", "force-persist"
-
-
-option redis-check
- Use redis health checks for server testing
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ Example :
+ # statistics admin level only for localhost
+ backend stats_localhost
+ stats enable
+ stats admin if LOCALHOST
- It is possible to test that the server correctly talks REDIS protocol instead
- of just testing that it accepts the TCP connection. When this option is set,
- a PING redis command is sent to the server, and the response is analyzed to
- find the "+PONG" response message.
+ Example :
+ # statistics admin level always enabled because of the authentication
+ backend stats_auth
+ stats enable
+ stats auth admin:AdMiN123
+ stats admin if TRUE
Example :
- option redis-check
+ # statistics admin level depends on the authenticated user
+ userlist stats-auth
+ group admin users admin
+ user admin insecure-password AdMiN123
+ group readonly users haproxy
+ user haproxy insecure-password haproxy
- See also : "option httpchk", "option tcp-check", "tcp-check expect"
+ backend stats_auth
+ stats enable
+ acl AUTH http_auth(stats-auth)
+ acl AUTH_ADMIN http_auth_group(stats-auth) admin
+ stats http-request auth unless AUTH
+ stats admin if AUTH_ADMIN
+ See also : "stats enable", "stats auth", "stats http-request", section 3.4
+ about userlists and section 7 about ACL usage.
-option smtpchk
-option smtpchk <hello> <domain>
- Use SMTP health checks for server testing
+
+stats auth <user>:<passwd>
+ Enable statistics with authentication and grant access to an account
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ yes | yes | yes | yes
Arguments :
- <hello> is an optional argument. It is the "hello" command to use. It can
- be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
- values will be turned into the default command ("HELO").
-
- <domain> is the domain name to present to the server. It may only be
- specified (and is mandatory) if the hello command has been
- specified. By default, "localhost" is used.
-
- When "option smtpchk" is set, the health checks will consist in TCP
- connections followed by an SMTP command. By default, this command is
- "HELO localhost". The server's return code is analyzed and only return codes
- starting with a "2" will be considered as valid. All other responses,
- including a lack of response will constitute an error and will indicate a
- dead server.
+ <user> is a user name to grant access to
- This test is meant to be used with SMTP servers or relays. Depending on the
- request, it is possible that some servers do not log each connection attempt,
- so you may want to experiment to improve the behavior. Using telnet on port
- 25 is often easier than adjusting the configuration.
+ <passwd> is the cleartext password associated to this user
- Most often, an incoming SMTP server needs to see the client's IP address for
- various purposes, including spam filtering, anti-spoofing and logging. When
- possible, it is often wise to masquerade the client's IP address when
- connecting to the server using the "usesrc" argument of the "source" keyword,
- which requires the transparent proxy feature to be compiled in.
+ This statement enables statistics with default settings, and restricts access
+ to declared users only. It may be repeated as many times as necessary to
+ allow as many users as desired. When a user tries to access the statistics
+ without a valid account, a "401 Forbidden" response will be returned so that
+ the browser asks the user to provide a valid user and password. The real
+ which will be returned to the browser is configurable using "stats realm".
- Example :
- option smtpchk HELO mydomain.org
+ Since the authentication method is HTTP Basic Authentication, the passwords
+ circulate in cleartext on the network. Thus, it was decided that the
+ configuration file would also use cleartext passwords to remind the users
+ that those ones should not be sensitive and not shared with any other account.
- See also : "option httpchk", "source"
+ It is also possible to reduce the scope of the proxies which appear in the
+ report using "stats scope".
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
-option socket-stats
-no option socket-stats
+ Example :
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
- Enable or disable collecting & providing separate statistics for each socket.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
- Arguments : none
+ See also : "stats enable", "stats realm", "stats scope", "stats uri"
-option splice-auto
-no option splice-auto
- Enable or disable automatic kernel acceleration on sockets in both directions
+stats enable
+ Enable statistics reporting with default settings
May be used in sections : defaults | frontend | listen | backend
yes | yes | yes | yes
Arguments : none
- When this option is enabled either on a frontend or on a backend, HAProxy
- will automatically evaluate the opportunity to use kernel tcp splicing to
- forward data between the client and the server, in either direction. HAProxy
- uses heuristics to estimate if kernel splicing might improve performance or
- not. Both directions are handled independently. Note that the heuristics used
- are not much aggressive in order to limit excessive use of splicing. This
- option requires splicing to be enabled at compile time, and may be globally
- disabled with the global option "nosplice". Since splice uses pipes, using it
- requires that there are enough spare pipes.
+ This statement enables statistics reporting with default settings defined
+ at build time. Unless stated otherwise, these settings are used :
+ - stats uri : /haproxy?stats
+ - stats realm : "HAProxy Statistics"
+ - stats auth : no authentication
+ - stats scope : no restriction
- Important note: kernel-based TCP splicing is a Linux-specific feature which
- first appeared in kernel 2.6.25. It offers kernel-based acceleration to
- transfer data between sockets without copying these data to user-space, thus
- providing noticeable performance gains and CPU cycles savings. Since many
- early implementations are buggy, corrupt data and/or are inefficient, this
- feature is not enabled by default, and it should be used with extreme care.
- While it is not possible to detect the correctness of an implementation,
- 2.6.29 is the first version offering a properly working implementation. In
- case of doubt, splicing may be globally disabled using the global "nosplice"
- keyword.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
Example :
- option splice-auto
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
- See also : "option splice-request", "option splice-response", and global
- options "nosplice" and "maxpipes"
+ See also : "stats auth", "stats realm", "stats uri"
-option splice-request
-no option splice-request
- Enable or disable automatic kernel acceleration on sockets for requests
+stats hide-version
+ Enable statistics and hide HAProxy version reporting
May be used in sections : defaults | frontend | listen | backend
yes | yes | yes | yes
Arguments : none
- When this option is enabled either on a frontend or on a backend, HAProxy
- will use kernel tcp splicing whenever possible to forward data going from
- the client to the server. It might still use the recv/send scheme if there
- are no spare pipes left. This option requires splicing to be enabled at
- compile time, and may be globally disabled with the global option "nosplice".
- Since splice uses pipes, using it requires that there are enough spare pipes.
+ By default, the stats page reports some useful status information along with
+ the statistics. Among them is HAProxy's version. However, it is generally
+ considered dangerous to report precise version to anyone, as it can help them
+ target known weaknesses with specific attacks. The "stats hide-version"
+ statement removes the version from the statistics report. This is recommended
+ for public sites or any site with a weak login/password.
- Important note: see "option splice-auto" for usage limitations.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
Example :
- option splice-request
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
- See also : "option splice-auto", "option splice-response", and global options
- "nosplice" and "maxpipes"
+ See also : "stats auth", "stats enable", "stats realm", "stats uri"
-option splice-response
-no option splice-response
- Enable or disable automatic kernel acceleration on sockets for responses
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+stats http-request { allow | deny | auth [realm <realm>] }
+ [ { if | unless } <condition> ]
+ Access control for statistics
- When this option is enabled either on a frontend or on a backend, HAProxy
- will use kernel tcp splicing whenever possible to forward data going from
- the server to the client. It might still use the recv/send scheme if there
- are no spare pipes left. This option requires splicing to be enabled at
- compile time, and may be globally disabled with the global option "nosplice".
- Since splice uses pipes, using it requires that there are enough spare pipes.
+ May be used in sections: defaults | frontend | listen | backend
+ no | no | yes | yes
- Important note: see "option splice-auto" for usage limitations.
+ As "http-request", these set of options allow to fine control access to
+ statistics. Each option may be followed by if/unless and acl.
+ First option with matched condition (or option without condition) is final.
+ For "deny" a 403 error will be returned, for "allow" normal processing is
+ performed, for "auth" a 401/407 error code is returned so the client
+ should be asked to enter a username and password.
- Example :
- option splice-response
+ There is no fixed limit to the number of http-request statements per
+ instance.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
-
- See also : "option splice-auto", "option splice-request", and global options
- "nosplice" and "maxpipes"
+ See also : "http-request", section 3.4 about userlists and section 7
+ about ACL usage.
-option spop-check
- Use SPOP health checks for server testing
+stats realm <realm>
+ Enable statistics and set authentication realm
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ yes | yes | yes | yes
+ Arguments :
+ <realm> is the name of the HTTP Basic Authentication realm reported to
+ the browser. The browser uses it to display it in the pop-up
+ inviting the user to enter a valid username and password.
- It is possible to test that the server correctly talks SPOP protocol instead
- of just testing that it accepts the TCP connection. When this option is set,
- a HELLO handshake is performed between HAProxy and the server, and the
- response is analyzed to check no error is reported.
+ The realm is read as a single word, so any spaces in it should be escaped
+ using a backslash ('\').
- Example :
- option spop-check
+ This statement is useful only in conjunction with "stats auth" since it is
+ only related to authentication.
- See also : "option httpchk"
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
+ Example :
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
-option srvtcpka
-no option srvtcpka
- Enable or disable the sending of TCP keepalive packets on the server side
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
- When there is a firewall or any session-aware component between a client and
- a server, and when the protocol involves very long sessions with long idle
- periods (e.g. remote desktops), there is a risk that one of the intermediate
- components decides to expire a session which has remained idle for too long.
+ See also : "stats auth", "stats enable", "stats uri"
- Enabling socket-level TCP keep-alives makes the system regularly send packets
- to the other end of the connection, leaving it active. The delay between
- keep-alive probes is controlled by the system only and depends both on the
- operating system and its tuning parameters.
- It is important to understand that keep-alive packets are neither emitted nor
- received at the application level. It is only the network stacks which sees
- them. For this reason, even if one side of the proxy already uses keep-alives
- to maintain its connection alive, those keep-alive packets will not be
- forwarded to the other side of the proxy.
+stats refresh <delay>
+ Enable statistics with automatic refresh
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments :
+ <delay> is the suggested refresh delay, specified in seconds, which will
+ be returned to the browser consulting the report page. While the
+ browser is free to apply any delay, it will generally respect it
+ and refresh the page this every seconds. The refresh interval may
+ be specified in any other non-default time unit, by suffixing the
+ unit after the value, as explained at the top of this document.
- Please note that this has nothing to do with HTTP keep-alive.
+ This statement is useful on monitoring displays with a permanent page
+ reporting the load balancer's activity. When set, the HTML report page will
+ include a link "refresh"/"stop refresh" so that the user can select whether
+ they want automatic refresh of the page or not.
- Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
- server side of a connection, which should help when session expirations are
- noticed between HAProxy and a server.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ Example :
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
- See also : "option clitcpka", "option tcpka"
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
+ See also : "stats auth", "stats enable", "stats realm", "stats uri"
-option ssl-hello-chk
- Use SSLv3 client hello health checks for server testing
+
+stats scope { <name> | "." }
+ Enable statistics and limit access scope
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ yes | yes | yes | yes
+ Arguments :
+ <name> is the name of a listen, frontend or backend section to be
+ reported. The special name "." (a single dot) designates the
+ section in which the statement appears.
- When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
- possible to test that the server correctly talks SSL instead of just testing
- that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
- SSLv3 client hello messages are sent once the connection is established to
- the server, and the response is analyzed to find an SSL server hello message.
- The server is considered valid only when the response contains this server
- hello message.
+ When this statement is specified, only the sections enumerated with this
+ statement will appear in the report. All other ones will be hidden. This
+ statement may appear as many times as needed if multiple sections need to be
+ reported. Please note that the name checking is performed as simple string
+ comparisons, and that it is never checked that a give section name really
+ exists.
- All servers tested till there correctly reply to SSLv3 client hello messages,
- and most servers tested do not even log the requests containing only hello
- messages, which is appreciable.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
- Note that this check works even when SSL support was not built into HAProxy
- because it forges the SSL message. When SSL support is available, it is best
- to use native SSL health checks instead of this one.
+ Example :
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
- See also: "option httpchk", "check-ssl"
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
+ See also : "stats auth", "stats enable", "stats realm", "stats uri"
-option tcp-check
- Perform health checks using tcp-check send/expect sequences
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
- This health check method is intended to be combined with "tcp-check" command
- lists in order to support send/expect types of health check sequences.
+stats show-desc [ <desc> ]
+ Enable reporting of a description on the statistics page.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
- TCP checks currently support 4 modes of operations :
- - no "tcp-check" directive : the health check only consists in a connection
- attempt, which remains the default mode.
+ <desc> is an optional description to be reported. If unspecified, the
+ description from global section is automatically used instead.
- - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
- used to send a string along with a connection opening. With some
- protocols, it helps sending a "QUIT" message for example that prevents
- the server from logging a connection error for each health check. The
- check result will still be based on the ability to open the connection
- only.
+ This statement is useful for users that offer shared services to their
+ customers, where node or description should be different for each customer.
- - "tcp-check expect" only is mentioned : this is used to test a banner.
- The connection is opened and HAProxy waits for the server to present some
- contents which must validate some rules. The check result will be based
- on the matching between the contents and the rules. This is suited for
- POP, IMAP, SMTP, FTP, SSH, TELNET.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters. By default description is not shown.
- - both "tcp-check send" and "tcp-check expect" are mentioned : this is
- used to test a hello-type protocol. HAProxy sends a message, the server
- responds and its response is analyzed. the check result will be based on
- the matching between the response contents and the rules. This is often
- suited for protocols which require a binding or a request/response model.
- LDAP, MySQL, Redis and SSL are example of such protocols, though they
- already all have their dedicated checks with a deeper understanding of
- the respective protocols.
- In this mode, many questions may be sent and many answers may be
- analyzed.
+ Example :
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats show-desc Master node for Europe, Asia, Africa
+ stats uri /admin?stats
+ stats refresh 5s
- A fifth mode can be used to insert comments in different steps of the script.
+ See also: "show-node", "stats enable", "stats uri" and "description" in
+ global section.
- For each tcp-check rule you create, you can add a "comment" directive,
- followed by a string. This string will be reported in the log and stderr in
- debug mode. It is useful to make user-friendly error reporting. The
- "comment" is of course optional.
- During the execution of a health check, a variable scope is made available to
- store data samples, using the "tcp-check set-var" operation. Freeing those
- variable is possible using "tcp-check unset-var".
+stats show-legends
+ Enable reporting additional information on the statistics page
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
+ Enable reporting additional information on the statistics page :
+ - cap: capabilities (proxy)
+ - mode: one of tcp, http or health (proxy)
+ - id: SNMP ID (proxy, socket, server)
+ - IP (socket, server)
+ - cookie (backend, server)
- Examples :
- # perform a POP check (analyze only server's banner)
- option tcp-check
- tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters. Default behavior is not to show this information.
- # perform an IMAP check (analyze only server's banner)
- option tcp-check
- tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
+ See also: "stats enable", "stats uri".
- # look for the redis master server after ensuring it speaks well
- # redis protocol, then it exits properly.
- # (send a command then analyze the response 3 times)
- option tcp-check
- tcp-check comment PING\ phase
- tcp-check send PING\r\n
- tcp-check expect string +PONG
- tcp-check comment role\ check
- tcp-check send info\ replication\r\n
- tcp-check expect string role:master
- tcp-check comment QUIT\ phase
- tcp-check send QUIT\r\n
- tcp-check expect string +OK
- forge a HTTP request, then analyze the response
- (send many headers before analyzing)
- option tcp-check
- tcp-check comment forge\ and\ send\ HTTP\ request
- tcp-check send HEAD\ /\ HTTP/1.1\r\n
- tcp-check send Host:\ www.mydomain.com\r\n
- tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
- tcp-check send \r\n
- tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
+stats show-modules
+ Enable display of extra statistics module on the statistics page
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments : none
+ New columns are added at the end of the line containing the extra statistics
+ values as a tooltip.
- See also : "tcp-check connect", "tcp-check expect" and "tcp-check send".
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters. Default behavior is not to show this information.
+ See also: "stats enable", "stats uri".
-option tcp-smart-accept
-no option tcp-smart-accept
- Enable or disable the saving of one ACK packet during the accept sequence
+
+stats show-node [ <name> ]
+ Enable reporting of a host name on the statistics page.
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ yes | yes | yes | yes
+ Arguments:
+ <name> is an optional name to be reported. If unspecified, the
+ node name from global section is automatically used instead.
- When an HTTP connection request comes in, the system acknowledges it on
- behalf of HAProxy, then the client immediately sends its request, and the
- system acknowledges it too while it is notifying HAProxy about the new
- connection. HAProxy then reads the request and responds. This means that we
- have one TCP ACK sent by the system for nothing, because the request could
- very well be acknowledged by HAProxy when it sends its response.
+ This statement is useful for users that offer shared services to their
+ customers, where node or description might be different on a stats page
+ provided for each customer. Default behavior is not to show host name.
- For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
- sending this useless ACK on platforms which support it (currently at least
- Linux). It must not cause any problem, because the system will send it anyway
- after 40 ms if the response takes more time than expected to come.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
- During complex network debugging sessions, it may be desirable to disable
- this optimization because delayed ACKs can make troubleshooting more complex
- when trying to identify where packets are delayed. It is then possible to
- fall back to normal behavior by specifying "no option tcp-smart-accept".
+ Example:
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats show-node Europe-1
+ stats uri /admin?stats
+ stats refresh 5s
- It is also possible to force it for non-HTTP proxies by simply specifying
- "option tcp-smart-accept". For instance, it can make sense with some services
- such as SMTP where the server speaks first.
+ See also: "show-desc", "stats enable", "stats uri", and "node" in global
+ section.
- It is recommended to avoid forcing this option in a defaults section. In case
- of doubt, consider setting it back to automatic values by prepending the
- "default" keyword before it, or disabling it using the "no" keyword.
- See also : "option tcp-smart-connect"
+stats uri <prefix>
+ Enable statistics and define the URI prefix to access them
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
+ Arguments :
+ <prefix> is the prefix of any URI which will be redirected to stats. This
+ prefix may contain a question mark ('?') to indicate part of a
+ query string.
+ The statistics URI is intercepted on the relayed traffic, so it appears as a
+ page within the normal application. It is strongly advised to ensure that the
+ selected URI will never appear in the application, otherwise it will never be
+ possible to reach it in the application.
-option tcp-smart-connect
-no option tcp-smart-connect
- Enable or disable the saving of one ACK packet during the connect sequence
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ The default URI compiled in HAProxy is "/haproxy?stats", but this may be
+ changed at build time, so it's better to always explicitly specify it here.
+ It is generally a good idea to include a question mark in the URI so that
+ intermediate proxies refrain from caching the results. Also, since any string
+ beginning with the prefix will be accepted as a stats request, the question
+ mark helps ensuring that no valid URI will begin with the same words.
- On certain systems (at least Linux), HAProxy can ask the kernel not to
- immediately send an empty ACK upon a connection request, but to directly
- send the buffer request instead. This saves one packet on the network and
- thus boosts performance. It can also be useful for some servers, because they
- immediately get the request along with the incoming connection.
+ It is sometimes very convenient to use "/" as the URI prefix, and put that
+ statement in a "listen" instance of its own. That makes it easy to dedicate
+ an address or a port to statistics only.
- This feature is enabled when "option tcp-smart-connect" is set in a backend.
- It is not enabled by default because it makes network troubleshooting more
- complex.
+ Though this statement alone is enough to enable statistics reporting, it is
+ recommended to set all other settings in order to avoid relying on default
+ unobvious parameters.
- It only makes sense to enable it with protocols where the client speaks first
- such as HTTP. In other situations, if there is no data to send in place of
- the ACK, a normal ACK is sent.
+ Example :
+ # public access (limited to this backend only)
+ backend public_www
+ server srv1 192.168.0.1:80
+ stats enable
+ stats hide-version
+ stats scope .
+ stats uri /admin?stats
+ stats realm HAProxy\ Statistics
+ stats auth admin1:AdMiN123
+ stats auth admin2:AdMiN321
- If this option has been enabled in a "defaults" section, it can be disabled
- in a specific instance by prepending the "no" keyword before it.
+ # internal monitoring access (unlimited)
+ backend private_monitoring
+ stats enable
+ stats uri /admin?stats
+ stats refresh 5s
- See also : "option tcp-smart-accept"
+ See also : "stats auth", "stats enable", "stats realm"
-option tcpka
- Enable or disable the sending of TCP keepalive packets on both sides
+stick match <pattern> [table <table>] [{if | unless} <cond>]
+ Define a request pattern matching condition to stick a user to a server
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ no | no | yes | yes
- When there is a firewall or any session-aware component between a client and
- a server, and when the protocol involves very long sessions with long idle
- periods (e.g. remote desktops), there is a risk that one of the intermediate
- components decides to expire a session which has remained idle for too long.
+ Arguments :
+ <pattern> is a sample expression rule as described in section 7.3. It
+ describes what elements of the incoming request or connection
+ will be analyzed in the hope to find a matching entry in a
+ stickiness table. This rule is mandatory.
- Enabling socket-level TCP keep-alives makes the system regularly send packets
- to the other end of the connection, leaving it active. The delay between
- keep-alive probes is controlled by the system only and depends both on the
- operating system and its tuning parameters.
+ <table> is an optional stickiness table name. If unspecified, the same
+ backend's table is used. A stickiness table is declared using
+ the "stick-table" statement.
- It is important to understand that keep-alive packets are neither emitted nor
- received at the application level. It is only the network stacks which sees
- them. For this reason, even if one side of the proxy already uses keep-alives
- to maintain its connection alive, those keep-alive packets will not be
- forwarded to the other side of the proxy.
+ <cond> is an optional matching condition. It makes it possible to match
+ on a certain criterion only when other conditions are met (or
+ not met). For instance, it could be used to match on a source IP
+ address except when a request passes through a known proxy, in
+ which case we'd match on a header containing that IP address.
- Please note that this has nothing to do with HTTP keep-alive.
+ Some protocols or applications require complex stickiness rules and cannot
+ always simply rely on cookies nor hashing. The "stick match" statement
+ describes a rule to extract the stickiness criterion from an incoming request
+ or connection. See section 7 for a complete list of possible patterns and
+ transformation rules.
- Using option "tcpka" enables the emission of TCP keep-alive probes on both
- the client and server sides of a connection. Note that this is meaningful
- only in "defaults" or "listen" sections. If this option is used in a
- frontend, only the client side will get keep-alives, and if this option is
- used in a backend, only the server side will get keep-alives. For this
- reason, it is strongly recommended to explicitly use "option clitcpka" and
- "option srvtcpka" when the configuration is split between frontends and
- backends.
+ The table has to be declared using the "stick-table" statement. It must be of
+ a type compatible with the pattern. By default it is the one which is present
+ in the same backend. It is possible to share a table with other backends by
+ referencing it using the "table" keyword. If another table is referenced,
+ the server's ID inside the backends are used. By default, all server IDs
+ start at 1 in each backend, so the server ordering is enough. But in case of
+ doubt, it is highly recommended to force server IDs using their "id" setting.
- See also : "option clitcpka", "option srvtcpka"
+ It is possible to restrict the conditions where a "stick match" statement
+ will apply, using "if" or "unless" followed by a condition. See section 7 for
+ ACL based conditions.
+ There is no limit on the number of "stick match" statements. The first that
+ applies and matches will cause the request to be directed to the same server
+ as was used for the request which created the entry. That way, multiple
+ matches can be used as fallbacks.
-option tcplog
- Enable advanced logging of TCP connections with session state and timers
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments : none
+ The stick rules are checked after the persistence cookies, so they will not
+ affect stickiness if a cookie has already been used to select a server. That
+ way, it becomes very easy to insert cookies and match on IP addresses in
+ order to maintain stickiness between HTTP and HTTPS.
- By default, the log output format is very poor, as it only contains the
- source and destination addresses, and the instance name. By specifying
- "option tcplog", each log line turns into a much richer format including, but
- not limited to, the connection timers, the session status, the connections
- numbers, the frontend, backend and server name, and of course the source
- address and ports. This option is useful for pure TCP proxies in order to
- find which of the client or server disconnects or times out. For normal HTTP
- proxies, it's better to use "option httplog" which is even more complete.
+ Example :
+ # forward SMTP users to the same server they just used for POP in the
+ # last 30 minutes
+ backend pop
+ mode tcp
+ balance roundrobin
+ stick store-request src
+ stick-table type ip size 200k expire 30m
+ server s1 192.168.1.1:110
+ server s2 192.168.1.1:110
- "option tcplog" overrides any previous "log-format" directive.
+ backend smtp
+ mode tcp
+ balance roundrobin
+ stick match src table pop
+ server s1 192.168.1.1:25
+ server s2 192.168.1.1:25
- See also : "option httplog", and section 8 about logging.
+ See also : "stick-table", "stick on", and section 7 about ACLs and samples
+ fetching.
-option transparent
-no option transparent
- Enable client-side transparent proxying
+stick on <pattern> [table <table>] [{if | unless} <condition>]
+ Define a request pattern to associate a user to a server
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ no | no | yes | yes
- This option was introduced in order to provide layer 7 persistence to layer 3
- load balancers. The idea is to use the OS's ability to redirect an incoming
- connection for a remote address to a local process (here HAProxy), and let
- this process know what address was initially requested. When this option is
- used, sessions without cookies will be forwarded to the original destination
- IP address of the incoming request (which should match that of another
- equipment), while requests with cookies will still be forwarded to the
- appropriate server.
+ Note : This form is exactly equivalent to "stick match" followed by
+ "stick store-request", all with the same arguments. Please refer
+ to both keywords for details. It is only provided as a convenience
+ for writing more maintainable configurations.
- Note that contrary to a common belief, this option does NOT make HAProxy
- present the client's IP to the server when establishing the connection.
+ Examples :
+ # The following form ...
+ stick on src table pop if !localhost
- See also: the "usesrc" argument of the "source" keyword, and the
- "transparent" option of the "bind" keyword.
+ # ...is strictly equivalent to this one :
+ stick match src table pop if !localhost
+ stick store-request src table pop if !localhost
-external-check command <command>
- Executable to run when performing an external-check
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
-
- Arguments :
- <command> is the external command to run
-
- The arguments passed to the to the command are:
-
- <proxy_address> <proxy_port> <server_address> <server_port>
-
- The <proxy_address> and <proxy_port> are derived from the first listener
- that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
- listener the proxy_address will be the path of the socket and the
- <proxy_port> will be the string "NOT_USED". In a backend section, it's not
- possible to determine a listener, and both <proxy_address> and <proxy_port>
- will have the string value "NOT_USED".
-
- Some values are also provided through environment variables.
-
- Environment variables :
- HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
- applicable, for example in a "backend" section).
-
- HAPROXY_PROXY_ID The backend id.
-
- HAPROXY_PROXY_NAME The backend name.
+ # Use cookie persistence for HTTP, and stick on source address for HTTPS as
+ # well as HTTP without cookie. Share the same table between both accesses.
+ backend http
+ mode http
+ balance roundrobin
+ stick on src table https
+ cookie SRV insert indirect nocache
+ server s1 192.168.1.1:80 cookie s1
+ server s2 192.168.1.1:80 cookie s2
- HAPROXY_PROXY_PORT The first bind port if available (or empty if not
- applicable, for example in a "backend" section or
- for a UNIX socket).
+ backend https
+ mode tcp
+ balance roundrobin
+ stick-table type ip size 200k expire 30m
+ stick on src
+ server s1 192.168.1.1:443
+ server s2 192.168.1.1:443
- HAPROXY_SERVER_ADDR The server address.
+ See also : "stick match", "stick store-request".
- HAPROXY_SERVER_CURCONN The current number of connections on the server.
- HAPROXY_SERVER_ID The server id.
+stick store-request <pattern> [table <table>] [{if | unless} <condition>]
+ Define a request pattern used to create an entry in a stickiness table
+ May be used in sections : defaults | frontend | listen | backend
+ no | no | yes | yes
- HAPROXY_SERVER_MAXCONN The server max connections.
+ Arguments :
+ <pattern> is a sample expression rule as described in section 7.3. It
+ describes what elements of the incoming request or connection
+ will be analyzed, extracted and stored in the table once a
+ server is selected.
- HAPROXY_SERVER_NAME The server name.
+ <table> is an optional stickiness table name. If unspecified, the same
+ backend's table is used. A stickiness table is declared using
+ the "stick-table" statement.
- HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
- socket).
+ <cond> is an optional storage condition. It makes it possible to store
+ certain criteria only when some conditions are met (or not met).
+ For instance, it could be used to store the source IP address
+ except when the request passes through a known proxy, in which
+ case we'd store a converted form of a header containing that IP
+ address.
- HAPROXY_SERVER_SSL "0" when SSL is not used, "1" when it is used
+ Some protocols or applications require complex stickiness rules and cannot
+ always simply rely on cookies nor hashing. The "stick store-request" statement
+ describes a rule to decide what to extract from the request and when to do
+ it, in order to store it into a stickiness table for further requests to
+ match it using the "stick match" statement. Obviously the extracted part must
+ make sense and have a chance to be matched in a further request. Storing a
+ client's IP address for instance often makes sense. Storing an ID found in a
+ URL parameter also makes sense. Storing a source port will almost never make
+ any sense because it will be randomly matched. See section 7 for a complete
+ list of possible patterns and transformation rules.
- HAPROXY_SERVER_PROTO The protocol used by this server, which can be one
- of "cli" (the haproxy CLI), "syslog" (syslog TCP
- server), "peers" (peers TCP server), "h1" (HTTP/1.x
- server), "h2" (HTTP/2 server), or "tcp" (any other
- TCP server).
+ The table has to be declared using the "stick-table" statement. It must be of
+ a type compatible with the pattern. By default it is the one which is present
+ in the same backend. It is possible to share a table with other backends by
+ referencing it using the "table" keyword. If another table is referenced,
+ the server's ID inside the backends are used. By default, all server IDs
+ start at 1 in each backend, so the server ordering is enough. But in case of
+ doubt, it is highly recommended to force server IDs using their "id" setting.
- PATH The PATH environment variable used when executing
- the command may be set using "external-check path".
+ It is possible to restrict the conditions where a "stick store-request"
+ statement will apply, using "if" or "unless" followed by a condition. This
+ condition will be evaluated while parsing the request, so any criteria can be
+ used. See section 7 for ACL based conditions.
- See also "2.3. Environment variables" for other variables.
+ There is no limit on the number of "stick store-request" statements, but
+ there is a limit of 8 simultaneous stores per request or response. This
+ makes it possible to store up to 8 criteria, all extracted from either the
+ request or the response, regardless of the number of rules. Only the 8 first
+ ones which match will be kept. Using this, it is possible to feed multiple
+ tables at once in the hope to increase the chance to recognize a user on
+ another protocol or access method. Using multiple store-request rules with
+ the same table is possible and may be used to find the best criterion to rely
+ on, by arranging the rules by decreasing preference order. Only the first
+ extracted criterion for a given table will be stored. All subsequent store-
+ request rules referencing the same table will be skipped and their ACLs will
+ not be evaluated.
- If the command executed and exits with a zero status then the check is
- considered to have passed, otherwise the check is considered to have
- failed.
+ The "store-request" rules are evaluated once the server connection has been
+ established, so that the table will contain the real server that processed
+ the request.
Example :
- external-check command /bin/true
+ # forward SMTP users to the same server they just used for POP in the
+ # last 30 minutes
+ backend pop
+ mode tcp
+ balance roundrobin
+ stick store-request src
+ stick-table type ip size 200k expire 30m
+ server s1 192.168.1.1:110
+ server s2 192.168.1.1:110
- See also : "external-check", "option external-check", "external-check path"
+ backend smtp
+ mode tcp
+ balance roundrobin
+ stick match src table pop
+ server s1 192.168.1.1:25
+ server s2 192.168.1.1:25
+
+ See also : "stick-table", "stick on", about ACLs and sample fetching.
-external-check path <path>
- The value of the PATH environment variable used when running an external-check
+stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
+ size <size> [expire <expire>] [nopurge] [peers <peersect>] [srvkey <srvkey>]
+ [write-to <wtable>] [store <data_type>]*
+ Configure the stickiness table for the current section
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ no | yes | yes | yes
Arguments :
- <path> is the path used when executing external command to run
-
- The default path is "".
-
- Example :
- external-check path "/usr/bin:/bin"
+ ip a table declared with "type ip" will only store IPv4 addresses.
+ This form is very compact (about 50 bytes per entry) and allows
+ very fast entry lookup and stores with almost no overhead. This
+ is mainly used to store client source IP addresses.
- See also : "external-check", "option external-check",
- "external-check command"
+ ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
+ This form is very compact (about 60 bytes per entry) and allows
+ very fast entry lookup and stores with almost no overhead. This
+ is mainly used to store client source IP addresses.
+ integer a table declared with "type integer" will store 32bit integers
+ which can represent a client identifier found in a request for
+ instance.
-persist rdp-cookie
-persist rdp-cookie(<name>)
- Enable RDP cookie-based persistence
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <name> is the optional name of the RDP cookie to check. If omitted, the
- default cookie name "msts" will be used. There currently is no
- valid reason to change this name.
+ string a table declared with "type string" will store substrings of up
+ to <len> characters. If the string provided by the pattern
+ extractor is larger than <len>, it will be truncated before
+ being stored. During matching, at most <len> characters will be
+ compared between the string in the table and the extracted
+ pattern. When not specified, the string is automatically limited
+ to 32 characters.
- This statement enables persistence based on an RDP cookie. The RDP cookie
- contains all information required to find the server in the list of known
- servers. So when this option is set in the backend, the request is analyzed
- and if an RDP cookie is found, it is decoded. If it matches a known server
- which is still UP (or if "option persist" is set), then the connection is
- forwarded to this server.
+ binary a table declared with "type binary" will store binary blocks
+ of <len> bytes. If the block provided by the pattern
+ extractor is larger than <len>, it will be truncated before
+ being stored. If the block provided by the sample expression
+ is shorter than <len>, it will be padded by 0. When not
+ specified, the block is automatically limited to 32 bytes.
- Note that this only makes sense in a TCP backend, but for this to work, the
- frontend must have waited long enough to ensure that an RDP cookie is present
- in the request buffer. This is the same requirement as with the "rdp-cookie"
- load-balancing method. Thus it is highly recommended to put all statements in
- a single "listen" section.
+ <length> is the maximum number of characters that will be stored in a
+ "string" type table (See type "string" above). Or the number
+ of bytes of the block in "binary" type table. Be careful when
+ changing this parameter as memory usage will proportionally
+ increase.
- Also, it is important to understand that the terminal server will emit this
- RDP cookie only if it is configured for "token redirection mode", which means
- that the "IP address redirection" option is disabled.
+ <size> is the maximum number of entries that can fit in the table. This
+ value directly impacts memory usage. Count approximately
+ 50 bytes per entry, plus the size of a string if any. The size
+ supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
- Example :
- listen tse-farm
- bind :3389
- # wait up to 5s for an RDP cookie in the request
- tcp-request inspect-delay 5s
- tcp-request content accept if RDP_COOKIE
- # apply RDP cookie persistence
- persist rdp-cookie
- # if server is unknown, let's balance on the same cookie.
- # alternatively, "balance leastconn" may be useful too.
- balance rdp-cookie
- server srv1 1.1.1.1:3389
- server srv2 1.1.1.2:3389
+ [nopurge] indicates that we refuse to purge older entries when the table
+ is full. When not specified and the table is full when HAProxy
+ wants to store an entry in it, it will flush a few of the oldest
+ entries in order to release some space for the new ones. This is
+ most often the desired behavior. In some specific cases, it
+ be desirable to refuse new entries instead of purging the older
+ ones. That may be the case when the amount of data to store is
+ far above the hardware limits and we prefer not to offer access
+ to new clients than to reject the ones already connected. When
+ using this parameter, be sure to properly set the "expire"
+ parameter (see below).
- See also : "balance rdp-cookie", "tcp-request" and the "req.rdp_cookie" ACL.
+ <peersect> is the name of the peers section to use for replication. Entries
+ which associate keys to server IDs are kept synchronized with
+ the remote peers declared in this section. All entries are also
+ automatically learned from the local peer (old process) during a
+ soft restart.
+ <wtable> is the name of the stick table where peers updates will be
+ written to in addition to the source table. <wtable> must be of
+ the same type as the table being defined and must have the same
+ key length, and source table cannot be used as a target table
+ itself. Every time an entry update will be received on the source
+ table through a peer, haproxy will try to refresh related
+ <wtable> entry. If the entry doesn't exist yet, it will be
+ created, else its values will be updated as well as its timer.
+ Note that only types that are not involved in arithmetic ops such
+ as server_id, server_key and gpt will be written to <wtable> to
+ prevent processed values from a remote table from interfering with
+ arithmetic operations performed on the local target table.
+ (ie: prevent shared cumulative counter from growing indefinitely)
+ One common use of this option is to be able to use sticking rules
+ (for server persistence) in a peers cluster setup, because
+ matching keys will be learned from remote tables.
-rate-limit sessions <rate>
- Set a limit on the number of new sessions accepted per second on a frontend
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <rate> The <rate> parameter is an integer designating the maximum number
- of new sessions per second to accept on the frontend.
-
- When the frontend reaches the specified number of new sessions per second, it
- stops accepting new connections until the rate drops below the limit again.
- During this time, the pending sessions will be kept in the socket's backlog
- (in system buffers) and HAProxy will not even be aware that sessions are
- pending. When applying very low limit on a highly loaded service, it may make
- sense to increase the socket's backlog using the "backlog" keyword.
-
- This feature is particularly efficient at blocking connection-based attacks
- or service abuse on fragile servers. Since the session rate is measured every
- millisecond, it is extremely accurate. Also, the limit applies immediately,
- no delay is needed at all to detect the threshold.
-
- Example : limit the connection rate on SMTP to 10 per second max
- listen smtp
- mode tcp
- bind :25
- rate-limit sessions 10
- server smtp1 127.0.0.1:1025
-
- Note : when the maximum rate is reached, the frontend's status is not changed
- but its sockets appear as "WAITING" in the statistics if the
- "socket-stats" option is enabled.
-
- See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
-
-
-redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
-redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
-redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
- Return an HTTP redirection if/unless a condition is matched
- May be used in sections : defaults | frontend | listen | backend
- no | yes | yes | yes
-
- If/unless the condition is matched, the HTTP request will lead to a redirect
- response. If no condition is specified, the redirect applies unconditionally.
-
- Arguments :
- <loc> With "redirect location", the exact value in <loc> is placed into
- the HTTP "Location" header. When used in an "http-request" rule,
- <loc> value follows the log-format rules and can include some
- dynamic values (see Custom Log Format in section 8.2.4).
-
- <pfx> With "redirect prefix", the "Location" header is built from the
- concatenation of <pfx> and the complete URI path, including the
- query string, unless the "drop-query" option is specified (see
- below). As a special case, if <pfx> equals exactly "/", then
- nothing is inserted before the original URI. It allows one to
- redirect to the same URL (for instance, to insert a cookie). When
- used in an "http-request" rule, <pfx> value follows the log-format
- rules and can include some dynamic values (see Custom Log Format
- in section 8.2.4).
-
- <sch> With "redirect scheme", then the "Location" header is built by
- concatenating <sch> with "://" then the first occurrence of the
- "Host" header, and then the URI path, including the query string
- unless the "drop-query" option is specified (see below). If no
- path is found or if the path is "*", then "/" is used instead. If
- no "Host" header is found, then an empty host component will be
- returned, which most recent browsers interpret as redirecting to
- the same host. This directive is mostly used to redirect HTTP to
- HTTPS. When used in an "http-request" rule, <sch> value follows
- the log-format rules and can include some dynamic values (see
- Custom Log Format in section 8.2.4).
-
- <code> The code is optional. It indicates which type of HTTP redirection
- is desired. Only codes 301, 302, 303, 307 and 308 are supported,
- with 302 used by default if no code is specified. 301 means
- "Moved permanently", and a browser may cache the Location. 302
- means "Moved temporarily" and means that the browser should not
- cache the redirection. 303 is equivalent to 302 except that the
- browser will fetch the location with a GET method. 307 is just
- like 302 but makes it clear that the same method must be reused.
- Likewise, 308 replaces 301 if the same method must be used.
-
- <option> There are several options which can be specified to adjust the
- expected behavior of a redirection :
-
- - "drop-query"
- When this keyword is used in a prefix-based redirection, then the
- location will be set without any possible query-string, which is useful
- for directing users to a non-secure page for instance. It has no effect
- with a location-type redirect.
-
- - "append-slash"
- This keyword may be used in conjunction with "drop-query" to redirect
- users who use a URL not ending with a '/' to the same one with the '/'.
- It can be useful to ensure that search engines will only see one URL.
- For this, a return code 301 is preferred.
-
- - "ignore-empty"
- This keyword only has effect when a location is produced using a log
- format expression (i.e. when used in http-request or http-response).
- It indicates that if the result of the expression is empty, the rule
- should silently be skipped. The main use is to allow mass-redirects
- of known paths using a simple map.
-
- - "set-cookie NAME[=value]"
- A "Set-Cookie" header will be added with NAME (and optionally "=value")
- to the response. This is sometimes used to indicate that a user has
- been seen, for instance to protect against some types of DoS. No other
- cookie option is added, so the cookie will be a session cookie. Note
- that for a browser, a sole cookie name without an equal sign is
- different from a cookie with an equal sign.
-
- - "clear-cookie NAME[=]"
- A "Set-Cookie" header will be added with NAME (and optionally "="), but
- with the "Max-Age" attribute set to zero. This will tell the browser to
- delete this cookie. It is useful for instance on logout pages. It is
- important to note that clearing the cookie "NAME" will not remove a
- cookie set with "NAME=value". You have to clear the cookie "NAME=" for
- that, because the browser makes the difference.
-
- Example: move the login URL only to HTTPS.
- acl clear dst_port 80
- acl secure dst_port 8080
- acl login_page url_beg /login
- acl logout url_beg /logout
- acl uid_given url_reg /login?userid=[^&]+
- acl cookie_set hdr_sub(cookie) SEEN=1
-
- redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
- redirect prefix https://mysite.com if login_page !secure
- redirect prefix http://mysite.com drop-query if login_page !uid_given
- redirect location http://mysite.com/ if !login_page secure
- redirect location / clear-cookie USERID= if logout
-
- Example: send redirects for request for articles without a '/'.
- acl missing_slash path_reg ^/article/[^/]*$
- redirect code 301 prefix / drop-query append-slash if missing_slash
-
- Example: redirect all HTTP traffic to HTTPS when SSL is handled by HAProxy.
- redirect scheme https if !{ ssl_fc }
-
- Example: append 'www.' prefix in front of all hosts not having it
- http-request redirect code 301 location \
- http://www.%[hdr(host)]%[capture.req.uri] \
- unless { hdr_beg(host) -i www }
-
- Example: permanently redirect only old URLs to new ones
- http-request redirect code 301 location \
- %[path,map_str(old-blog-articles.map)] ignore-empty
-
- See section 7 about ACL usage.
-
-
-retries <value>
- Set the number of retries to perform on a server after a failure
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <value> is the number of times a request or connection attempt should be
- retried on a server after a failure.
-
- By default, retries apply only to new connection attempts. However, when
- the "retry-on" directive is used, other conditions might trigger a retry
- (e.g. empty response, undesired status code), and each of them will count
- one attempt, and when the total number attempts reaches the value here, an
- error will be returned.
-
- In order to avoid immediate reconnections to a server which is restarting,
- a turn-around timer of min("timeout connect", one second) is applied before
- a retry occurs on the same server.
-
- When "option redispatch" is set, some retries may be performed on another
- server even if a cookie references a different server. By default this will
- only be the last retry unless an argument is passed to "option redispatch".
-
- See also : "option redispatch"
-
-
-retry-on [space-delimited list of keywords]
- Specify when to attempt to automatically retry a failed request.
- This setting is only valid when "mode" is set to http and is silently ignored
- otherwise.
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <keywords> is a space-delimited list of keywords or HTTP status codes, each
- representing a type of failure event on which an attempt to
- retry the request is desired. Please read the notes at the
- bottom before changing this setting. The following keywords are
- supported :
-
- none never retry
-
- conn-failure retry when the connection or the SSL handshake failed
- and the request could not be sent. This is the default.
-
- empty-response retry when the server connection was closed after part
- of the request was sent, and nothing was received from
- the server. This type of failure may be caused by the
- request timeout on the server side, poor network
- condition, or a server crash or restart while
- processing the request.
-
- junk-response retry when the server returned something not looking
- like a complete HTTP response. This includes partial
- responses headers as well as non-HTTP contents. It
- usually is a bad idea to retry on such events, which
- may be caused a configuration issue (wrong server port)
- or by the request being harmful to the server (buffer
- overflow attack for example).
-
- response-timeout the server timeout stroke while waiting for the server
- to respond to the request. This may be caused by poor
- network condition, the reuse of an idle connection
- which has expired on the path, or by the request being
- extremely expensive to process. It generally is a bad
- idea to retry on such events on servers dealing with
- heavy database processing (full scans, etc) as it may
- amplify denial of service attacks.
-
- 0rtt-rejected retry requests which were sent over early data and were
- rejected by the server. These requests are generally
- considered to be safe to retry.
-
- <status> any HTTP status code among "401" (Unauthorized), "403"
- (Forbidden), "404" (Not Found), "408" (Request Timeout),
- "425" (Too Early), "500" (Server Error), "501" (Not
- Implemented), "502" (Bad Gateway), "503" (Service
- Unavailable), "504" (Gateway Timeout).
-
- all-retryable-errors
- retry request for any error that are considered
- retryable. This currently activates "conn-failure",
- "empty-response", "junk-response", "response-timeout",
- "0rtt-rejected", "500", "502", "503", and "504".
-
- Using this directive replaces any previous settings with the new ones; it is
- not cumulative.
-
- Please note that using anything other than "none" and "conn-failure" requires
- to allocate a buffer and copy the whole request into it, so it has memory and
- performance impacts. Requests not fitting in a single buffer will never be
- retried (see the global tune.bufsize setting).
-
- You have to make sure the application has a replay protection mechanism built
- in such as a unique transaction IDs passed in requests, or that replaying the
- same request has no consequence, or it is very dangerous to use any retry-on
- value beside "conn-failure" and "none". Static file servers and caches are
- generally considered safe against any type of retry. Using a status code can
- be useful to quickly leave a server showing an abnormal behavior (out of
- memory, file system issues, etc), but in this case it may be a good idea to
- immediately redispatch the connection to another server (please see "option
- redispatch" for this). Last, it is important to understand that most causes
- of failures are the requests themselves and that retrying a request causing a
- server to misbehave will often make the situation even worse for this server,
- or for the whole service in case of redispatch.
-
- Unless you know exactly how the application deals with replayed requests, you
- should not use this directive.
-
- The default is "conn-failure".
-
- Example:
- retry-on 503 504
-
- See also: "retries", "option redispatch", "tune.bufsize"
-
-server <name> <address>[:[port]] [param*]
- Declare a server in a backend
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
- Arguments :
- <name> is the internal name assigned to this server. This name will
- appear in logs and alerts. If "http-send-name-header" is
- set, it will be added to the request header sent to the server.
-
- <address> is the IPv4 or IPv6 address of the server. Alternatively, a
- resolvable hostname is supported, but this name will be resolved
- during start-up. Address "0.0.0.0" or "*" has a special meaning.
- It indicates that the connection will be forwarded to the same IP
- address as the one from the client connection. This is useful in
- transparent proxy architectures where the client's connection is
- intercepted and HAProxy must forward to the original destination
- address. This is more or less what the "transparent" keyword does
- except that with a server it's possible to limit concurrency and
- to report statistics. Optionally, an address family prefix may be
- used before the address to force the family regardless of the
- address format, which can be useful to specify a path to a unix
- socket with no slash ('/'). Currently supported prefixes are :
- - 'ipv4@' -> address is always IPv4
- - 'ipv6@' -> address is always IPv6
- - 'unix@' -> address is a path to a local unix socket
- - 'abns@' -> address is in abstract namespace (Linux only)
- - 'sockpair@' -> address is the FD of a connected unix
- socket or of a socketpair. During a connection, the
- backend creates a pair of connected sockets, and passes
- one of them over the FD. The bind part will use the
- received socket as the client FD. Should be used
- carefully.
- - 'rhttp@' -> custom address family for a passive server in
- HTTP reverse context.
- You may want to reference some environment variables in the
- address parameter, see section 2.3 about environment
- variables. The "init-addr" setting can be used to modify the way
- IP addresses should be resolved upon startup.
-
- <port> is an optional port specification. If set, all connections will
- be sent to this port. If unset, the same port the client
- connected to will be used. The port may also be prefixed by a "+"
- or a "-". In this case, the server's port will be determined by
- adding this value to the client's port.
-
- <param*> is a list of parameters for this server. The "server" keywords
- accepts an important number of options and has a complete section
- dedicated to it. Please refer to section 5 for more details.
-
- Examples :
- server first 10.1.1.1:1080 cookie first check inter 1000
- server second 10.1.1.2:1080 cookie second check inter 1000
- server transp ipv4@
- server backup "${SRV_BACKUP}:1080" backup
- server www1_dc1 "${LAN_DC1}.101:80"
- server www1_dc2 "${LAN_DC2}.101:80"
-
- Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
- sun_path length is used for the address length. Some other programs
- such as socat use the string length only by default. Pass the option
- ",unix-tightsocklen=0" to any abstract socket definition in socat to
- make it compatible with HAProxy's.
-
- See also: "default-server", "http-send-name-header" and section 5 about
- server options
-
-server-state-file-name [ { use-backend-name | <file> } ]
- Set the server state file to read, load and apply to servers available in
- this backend.
- May be used in sections: defaults | frontend | listen | backend
- no | no | yes | yes
-
- It only applies when the directive "load-server-state-from-file" is set to
- "local". When <file> is not provided, if "use-backend-name" is used or if
- this directive is not set, then backend name is used. If <file> starts with a
- slash '/', then it is considered as an absolute path. Otherwise, <file> is
- concatenated to the global directive "server-state-base".
-
- Example: the minimal configuration below would make HAProxy look for the
- state server file '/etc/haproxy/states/bk':
-
- global
- server-state-file-base /etc/haproxy/states
-
- backend bk
- load-server-state-from-file
-
- See also: "server-state-base", "load-server-state-from-file", and
- "show servers state"
-
-server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
- Set a template to initialize servers with shared parameters.
- The names of these servers are built from <prefix> and <num | range> parameters.
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
-
- Arguments:
- <prefix> A prefix for the server names to be built.
-
- <num | range>
- If <num> is provided, this template initializes <num> servers
- with 1 up to <num> as server name suffixes. A range of numbers
- <num_low>-<num_high> may also be used to use <num_low> up to
- <num_high> as server name suffixes.
-
- <fqdn> A FQDN for all the servers this template initializes.
-
- <port> Same meaning as "server" <port> argument (see "server" keyword).
-
- <params*>
- Remaining server parameters among all those supported by "server"
- keyword.
-
- Examples:
- # Initializes 3 servers with srv1, srv2 and srv3 as names,
- # google.com as FQDN, and health-check enabled.
- server-template srv 1-3 google.com:80 check
+ <expire> defines the maximum duration of an entry in the table since it
+ was last created, refreshed using 'track-sc' or matched using
+ 'stick match' or 'stick on' rule. The expiration delay is
+ defined using the standard time format, similarly as the various
+ timeouts. The maximum duration is slightly above 24 days. See
+ section 2.5 for more information. If this delay is not specified,
+ the session won't automatically expire, but older entries will
+ be removed once full. Be sure not to use the "nopurge" parameter
+ if not expiration delay is specified.
+ Note: 'table_*' converters performs lookups but won't update touch
+ expire since they don't require 'track-sc'.
- # or
- server-template srv 3 google.com:80 check
+ <srvkey> specifies how each server is identified for the purposes of the
+ stick table. The valid values are "name" and "addr". If "name" is
+ given, then <name> argument for the server (may be generated by
+ a template). If "addr" is given, then the server is identified
+ by its current network address, including the port. "addr" is
+ especially useful if you are using service discovery to generate
+ the addresses for servers with peered stick-tables and want
+ to consistently use the same host across peers for a stickiness
+ token.
- # would be equivalent to:
- server srv1 google.com:80 check
- server srv2 google.com:80 check
- server srv3 google.com:80 check
+ <data_type> is used to store additional information in the stick-table. This
+ may be used by ACLs in order to control various criteria related
+ to the activity of the client matching the stick-table. For each
+ item specified here, the size of each entry will be inflated so
+ that the additional data can fit. Several data types may be
+ stored with an entry. Multiple data types may be specified after
+ the "store" keyword, as a comma-separated list. Alternatively,
+ it is possible to repeat the "store" keyword followed by one or
+ several data types. Except for the "server_id" type which is
+ automatically detected and enabled, all data types must be
+ explicitly declared to be stored. If an ACL references a data
+ type which is not stored, the ACL will simply not match. Some
+ data types require an argument which must be passed just after
+ the type between parenthesis. See below for the supported data
+ types and their arguments.
+ The data types that can be stored with an entry are the following :
+ - server_id : this is an integer which holds the numeric ID of the server a
+ request was assigned to. It is used by the "stick match", "stick store",
+ and "stick on" rules. It is automatically enabled when referenced.
+ - gpc(<nb>) : General Purpose Counters Array of <nb> elements. This is an
+ array of positive 32-bit integers which may be used to count anything.
+ Most of the time they will be used as a incremental counters on some
+ entries, for instance to note that a limit is reached and trigger some
+ actions. This array is limited to a maximum of 100 elements:
+ gpc0 to gpc99, to ensure that the build of a peer update
+ message can fit into the buffer. Users should take in consideration
+ that a large amount of counters will increase the data size and the
+ traffic load using peers protocol since all data/counters are pushed
+ each time any of them is updated.
+ This data_type will exclude the usage of the legacy data_types 'gpc0'
+ and 'gpc1' on the same table. Using the 'gpc' array data_type, all 'gpc0'
+ and 'gpc1' related fetches and actions will apply to the two first
+ elements of this array.
-source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
-source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
-source <addr>[:<port>] [interface <name>]
- Set the source address for outgoing connections
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <addr> is the IPv4 address HAProxy will bind to before connecting to a
- server. This address is also used as a source for health checks.
+ - gpc_rate(<nb>,<period>) : Array of increment rates of General Purpose
+ Counters over a period. Those elements are positive 32-bit integers which
+ may be used for anything. Just like <gpc>, the count events, but instead
+ of keeping a cumulative number, they maintain the rate at which the
+ counter is incremented. Most of the time it will be used to measure the
+ frequency of occurrence of certain events (e.g. requests to a specific
+ URL). This array is limited to a maximum of 100 elements: gpt(100)
+ allowing the storage of gpc0 to gpc99, to ensure that the build of a peer
+ update message can fit into the buffer.
+ The array cannot contain less than 1 element: use gpc(1) if you want to
+ store only the counter gpc0.
+ Users should take in consideration that a large amount of
+ counters will increase the data size and the traffic load using peers
+ protocol since all data/counters are pushed each time any of them is
+ updated.
+ This data_type will exclude the usage of the legacy data_types
+ 'gpc0_rate' and 'gpc1_rate' on the same table. Using the 'gpc_rate'
+ array data_type, all 'gpc0' and 'gpc1' related fetches and actions
+ will apply to the two first elements of this array.
- The default value of 0.0.0.0 means that the system will select
- the most appropriate address to reach its destination. Optionally
- an address family prefix may be used before the address to force
- the family regardless of the address format, which can be useful
- to specify a path to a unix socket with no slash ('/'). Currently
- supported prefixes are :
- - 'ipv4@' -> address is always IPv4
- - 'ipv6@' -> address is always IPv6
- - 'unix@' -> address is a path to a local unix socket
- - 'abns@' -> address is in abstract namespace (Linux only)
- You may want to reference some environment variables in the
- address parameter, see section 2.3 about environment variables.
+ - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
+ integer which may be used for anything. Most of the time it will be used
+ to put a special tag on some entries, for instance to note that a
+ specific behavior was detected and must be known for future matches.
- <port> is an optional port. It is normally not needed but may be useful
- in some very specific contexts. The default value of zero means
- the system will select a free port. Note that port ranges are not
- supported in the backend. If you want to force port ranges, you
- have to specify them on each "server" line.
+ - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
+ over a period. It is a positive 32-bit integer integer which may be used
+ for anything. Just like <gpc0>, it counts events, but instead of keeping
+ a cumulative number, it maintains the rate at which the counter is
+ incremented. Most of the time it will be used to measure the frequency of
+ occurrence of certain events (e.g. requests to a specific URL).
- <addr2> is the IP address to present to the server when connections are
- forwarded in full transparent proxy mode. This is currently only
- supported on some patched Linux kernels. When this address is
- specified, clients connecting to the server will be presented
- with this address, while health checks will still use the address
- <addr>.
+ - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
+ integer which may be used for anything. Most of the time it will be used
+ to put a special tag on some entries, for instance to note that a
+ specific behavior was detected and must be known for future matches.
- <port2> is the optional port to present to the server when connections
- are forwarded in full transparent proxy mode (see <addr2> above).
- The default value of zero means the system will select a free
- port.
+ - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
+ over a period. It is a positive 32-bit integer integer which may be used
+ for anything. Just like <gpc1>, it counts events, but instead of keeping
+ a cumulative number, it maintains the rate at which the counter is
+ incremented. Most of the time it will be used to measure the frequency of
+ occurrence of certain events (e.g. requests to a specific URL).
- <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
- This is the name of a comma-separated header list which can
- contain multiple IP addresses. By default, the last occurrence is
- used. This is designed to work with the X-Forwarded-For header
- and to automatically bind to the client's IP address as seen
- by previous proxy, typically Stunnel. In order to use another
- occurrence from the last one, please see the <occ> parameter
- below. When the header (or occurrence) is not found, no binding
- is performed so that the proxy's default IP address is used. Also
- keep in mind that the header name is case insensitive, as for any
- HTTP header.
+ - gpt(<nb>) : General Purpose Tags Array of <nb> elements. This is an array
+ of positive 32-bit integers which may be used for anything.
+ Most of the time they will be used to put a special tags on some entries,
+ for instance to note that a specific behavior was detected and must be
+ known for future matches. This array is limited to a maximum of 100
+ elements: gpt(100) allowing the storage of gpt0 to gpt99, to ensure that
+ the build of a peer update message can fit into the buffer.
+ The array cannot contain less than 1 element: use gpt(1) if you want to
+ to store only the tag gpt0.
+ Users should take in consideration that a large amount of counters will
+ increase the data size and the traffic load using peers protocol since
+ all data/counters are pushed each time any of them is updated.
+ This data_type will exclude the usage of the legacy data_type 'gpt0'
+ on the same table. Using the 'gpt' array data_type, all 'gpt0' related
+ fetches and actions will apply to the first element of this array.
- <occ> is the occurrence number of a value to be used in a multi-value
- header. This is to be used in conjunction with "hdr_ip(<hdr>)",
- in order to specify which occurrence to use for the source IP
- address. Positive values indicate a position from the first
- occurrence, 1 being the first one. Negative values indicate
- positions relative to the last one, -1 being the last one. This
- is helpful for situations where an X-Forwarded-For header is set
- at the entry point of an infrastructure and must be used several
- proxy layers away. When this value is not specified, -1 is
- assumed. Passing a zero here disables the feature.
+ - gpt0 : first General Purpose Tag. It is a positive 32-bit integer
+ integer which may be used for anything. Most of the time it will be used
+ to put a special tag on some entries, for instance to note that a
+ specific behavior was detected and must be known for future matches
- <name> is an optional interface name to which to bind to for outgoing
- traffic. On systems supporting this features (currently, only
- Linux), this allows one to bind all traffic to the server to
- this interface even if it is not the one the system would select
- based on routing tables. This should be used with extreme care.
- Note that using this option requires root privileges.
+ - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
+ the absolute number of connections received from clients which matched
+ this entry. It does not mean the connections were accepted, just that
+ they were received.
- The "source" keyword is useful in complex environments where a specific
- address only is allowed to connect to the servers. It may be needed when a
- private address must be used through a public gateway for instance, and it is
- known that the system cannot determine the adequate source address by itself.
+ - conn_cur : Current Connections. It is a positive 32-bit integer which
+ stores the concurrent connection counts for the entry. It is incremented
+ once an incoming connection matches the entry, and decremented once the
+ connection leaves. That way it is possible to know at any time the exact
+ number of concurrent connections for an entry.
- An extension which is available on certain patched Linux kernels may be used
- through the "usesrc" optional keyword. It makes it possible to connect to the
- servers with an IP address which does not belong to the system itself. This
- is called "full transparent proxy mode". For this to work, the destination
- servers have to route their traffic back to this address through the machine
- running HAProxy, and IP forwarding must generally be enabled on this machine.
+ - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
+ integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ incoming connection rate over that period, in connections per period. The
+ result is an integer which can be matched using ACLs.
- In this "full transparent proxy" mode, it is possible to force a specific IP
- address to be presented to the servers. This is not much used in fact. A more
- common use is to tell HAProxy to present the client's IP address. For this,
- there are two methods :
+ - sess_cnt : Session Count. It is a positive 32-bit integer which counts
+ the absolute number of sessions received from clients which matched this
+ entry. A session is a connection that was accepted by the layer 4 rules.
- - present the client's IP and port addresses. This is the most transparent
- mode, but it can cause problems when IP connection tracking is enabled on
- the machine, because a same connection may be seen twice with different
- states. However, this solution presents the huge advantage of not
- limiting the system to the 64k outgoing address+port couples, because all
- of the client ranges may be used.
+ - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
+ integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ incoming session rate over that period, in sessions per period. The
+ result is an integer which can be matched using ACLs.
- - present only the client's IP address and select a spare port. This
- solution is still quite elegant but slightly less transparent (downstream
- firewalls logs will not match upstream's). It also presents the downside
- of limiting the number of concurrent connections to the usual 64k ports.
- However, since the upstream and downstream ports are different, local IP
- connection tracking on the machine will not be upset by the reuse of the
- same session.
+ - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
+ counts the absolute number of HTTP requests received from clients which
+ matched this entry. It does not matter whether they are valid requests or
+ not. Note that this is different from sessions when keep-alive is used on
+ the client side.
- This option sets the default source for all servers in the backend. It may
- also be specified in a "defaults" section. Finer source address specification
- is possible at the server level using the "source" server option. Refer to
- section 5 for more information.
+ - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
+ integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ HTTP request rate over that period, in requests per period. The result is
+ an integer which can be matched using ACLs. It does not matter whether
+ they are valid requests or not. Note that this is different from sessions
+ when keep-alive is used on the client side.
- In order to work, "usesrc" requires root privileges, or on supported systems,
- the "cap_net_raw" capability. See also the "setcap" global directive.
+ - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
+ counts the absolute number of HTTP requests errors induced by clients
+ which matched this entry. Errors are counted on invalid and truncated
+ requests, as well as on denied or tarpitted requests, and on failed
+ authentications. If the server responds with 4xx, then the request is
+ also counted as an error since it's an error triggered by the client
+ (e.g. vulnerability scan).
- Examples :
- backend private
- # Connect to the servers using our 192.168.1.200 source address
- source 192.168.1.200
+ - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
+ integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ HTTP request error rate over that period, in requests per period (see
+ http_err_cnt above for what is accounted as an error). The result is an
+ integer which can be matched using ACLs.
- backend transparent_ssl1
- # Connect to the SSL farm from the client's source address
- source 192.168.1.200 usesrc clientip
+ - http_fail_cnt : HTTP Failure Count. It is a positive 32-bit integer which
+ counts the absolute number of HTTP response failures induced by servers
+ which matched this entry. Errors are counted on invalid and truncated
+ responses, as well as any 5xx response other than 501 or 505. It aims at
+ being used combined with path or URI to detect service failures.
- backend transparent_ssl2
- # Connect to the SSL farm from the client's source address and port
- # not recommended if IP conntrack is present on the local machine.
- source 192.168.1.200 usesrc client
+ - http_fail_rate(<period>) : frequency counter (takes 12 bytes). It takes
+ an integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ HTTP response failure rate over that period, in requests per period (see
+ http_fail_cnt above for what is accounted as a failure). The result is an
+ integer which can be matched using ACLs.
- backend transparent_ssl3
- # Connect to the SSL farm from the client's source address. It
- # is more conntrack-friendly.
- source 192.168.1.200 usesrc clientip
+ - bytes_in_cnt : client to server byte count. It is a positive 64-bit
+ integer which counts the cumulative number of bytes received from clients
+ which matched this entry. Headers are included in the count. This may be
+ used to limit abuse of upload features on photo or video servers.
- backend transparent_smtp
- # Connect to the SMTP farm from the client's source address/port
- # with Tproxy version 4.
- source 0.0.0.0 usesrc clientip
+ - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
+ integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ incoming bytes rate over that period, in bytes per period. It may be used
+ to detect users which upload too much and too fast. Warning: with large
+ uploads, it is possible that the amount of uploaded data will be counted
+ once upon termination, thus causing spikes in the average transfer speed
+ instead of having a smooth one. This may partially be smoothed with
+ "option contstats" though this is not perfect yet. Use of byte_in_cnt is
+ recommended for better fairness.
- backend transparent_http
- # Connect to the servers using the client's IP as seen by previous
- # proxy.
- source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
+ - bytes_out_cnt : server to client byte count. It is a positive 64-bit
+ integer which counts the cumulative number of bytes sent to clients which
+ matched this entry. Headers are included in the count. This may be used
+ to limit abuse of bots sucking the whole site.
- See also : the "source" server option in section 5, the Tproxy patches for
- the Linux kernel on www.balabit.com, the "bind" keyword.
+ - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
+ an integer parameter <period> which indicates in milliseconds the length
+ of the period over which the average is measured. It reports the average
+ outgoing bytes rate over that period, in bytes per period. It may be used
+ to detect users which download too much and too fast. Warning: with large
+ transfers, it is possible that the amount of transferred data will be
+ counted once upon termination, thus causing spikes in the average
+ transfer speed instead of having a smooth one. This may partially be
+ smoothed with "option contstats" though this is not perfect yet. Use of
+ byte_out_cnt is recommended for better fairness.
+ There is only one stick-table per proxy. At the moment of writing this doc,
+ it does not seem useful to have multiple tables per proxy. If this happens
+ to be required, simply create a dummy backend with a stick-table in it and
+ reference it.
-srvtcpka-cnt <count>
- Sets the maximum number of keepalive probes TCP should send before dropping
- the connection on the server side.
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <count> is the maximum number of keepalive probes.
+ It is important to understand that stickiness based on learning information
+ has some limitations, including the fact that all learned associations are
+ lost upon restart unless peers are properly configured to transfer such
+ information upon restart (recommended). In general it can be good as a
+ complement but not always as an exclusive stickiness.
- This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword
- is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used.
- The availability of this setting depends on the operating system. It is
- known to work on Linux.
+ Last, memory requirements may be important when storing many data types.
+ Indeed, storing all indicators above at once in each entry requires 116 bytes
+ per entry, or 116 MB for a 1-million entries table. This is definitely not
+ something that can be ignored.
- See also : "option srvtcpka", "srvtcpka-idle", "srvtcpka-intvl".
+ Example:
+ # Keep track of counters of up to 1 million IP addresses over 5 minutes
+ # and store a general purpose counter and the average connection rate
+ # computed over a sliding window of 30 seconds.
+ stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
+ See also : "stick match", "stick on", "stick store-request", section 2.5
+ about time format and section 7 about ACLs.
-srvtcpka-idle <timeout>
- Sets the time the connection needs to remain idle before TCP starts sending
- keepalive probes, if enabled the sending of TCP keepalive packets on the
- server side.
+
+stick store-response <pattern> [table <table>] [{if | unless} <condition>]
+ Define a response pattern used to create an entry in a stickiness table
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
+ no | no | yes | yes
+
Arguments :
- <timeout> is the time the connection needs to remain idle before TCP starts
- sending keepalive probes. It is specified in seconds by default,
- but can be in any other unit if the number is suffixed by the
- unit, as explained at the top of this document.
+ <pattern> is a sample expression rule as described in section 7.3. It
+ describes what elements of the response or connection will
+ be analyzed, extracted and stored in the table once a
+ server is selected.
- This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword
- is not specified, system-wide TCP parameter (tcp_keepalive_time) is used.
- The availability of this setting depends on the operating system. It is
- known to work on Linux.
+ <table> is an optional stickiness table name. If unspecified, the same
+ backend's table is used. A stickiness table is declared using
+ the "stick-table" statement.
- See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-intvl".
+ <cond> is an optional storage condition. It makes it possible to store
+ certain criteria only when some conditions are met (or not met).
+ For instance, it could be used to store the SSL session ID only
+ when the response is a SSL server hello.
+ Some protocols or applications require complex stickiness rules and cannot
+ always simply rely on cookies nor hashing. The "stick store-response"
+ statement describes a rule to decide what to extract from the response and
+ when to do it, in order to store it into a stickiness table for further
+ requests to match it using the "stick match" statement. Obviously the
+ extracted part must make sense and have a chance to be matched in a further
+ request. Storing an ID found in a header of a response makes sense.
+ See section 7 for a complete list of possible patterns and transformation
+ rules.
-srvtcpka-intvl <timeout>
- Sets the time between individual keepalive probes on the server side.
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <timeout> is the time between individual keepalive probes. It is specified
- in seconds by default, but can be in any other unit if the number
- is suffixed by the unit, as explained at the top of this
- document.
+ The table has to be declared using the "stick-table" statement. It must be of
+ a type compatible with the pattern. By default it is the one which is present
+ in the same backend. It is possible to share a table with other backends by
+ referencing it using the "table" keyword. If another table is referenced,
+ the server's ID inside the backends are used. By default, all server IDs
+ start at 1 in each backend, so the server ordering is enough. But in case of
+ doubt, it is highly recommended to force server IDs using their "id" setting.
- This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword
- is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used.
- The availability of this setting depends on the operating system. It is
- known to work on Linux.
+ It is possible to restrict the conditions where a "stick store-response"
+ statement will apply, using "if" or "unless" followed by a condition. This
+ condition will be evaluated while parsing the response, so any criteria can
+ be used. See section 7 for ACL based conditions.
- See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-idle".
+ There is no limit on the number of "stick store-response" statements, but
+ there is a limit of 8 simultaneous stores per request or response. This
+ makes it possible to store up to 8 criteria, all extracted from either the
+ request or the response, regardless of the number of rules. Only the 8 first
+ ones which match will be kept. Using this, it is possible to feed multiple
+ tables at once in the hope to increase the chance to recognize a user on
+ another protocol or access method. Using multiple store-response rules with
+ the same table is possible and may be used to find the best criterion to rely
+ on, by arranging the rules by decreasing preference order. Only the first
+ extracted criterion for a given table will be stored. All subsequent store-
+ response rules referencing the same table will be skipped and their ACLs will
+ not be evaluated. However, even if a store-request rule references a table, a
+ store-response rule may also use the same table. This means that each table
+ may learn exactly one element from the request and one element from the
+ response at once.
+ The table will contain the real server that processed the request.
-stats admin { if | unless } <cond>
- Enable statistics admin level if/unless a condition is matched
- May be used in sections : defaults | frontend | listen | backend
- no | yes | yes | yes
+ Example :
+ # Learn SSL session ID from both request and response and create affinity.
+ backend https
+ mode tcp
+ balance roundrobin
+ # maximum SSL session ID length is 32 bytes.
+ stick-table type binary len 32 size 30k expire 30m
- This statement enables the statistics admin level if/unless a condition is
- matched.
+ acl clienthello req.ssl_hello_type 1
+ acl serverhello rep.ssl_hello_type 2
- The admin level allows to enable/disable servers from the web interface. By
- default, statistics page is read-only for security reasons.
+ # use tcp content accepts to detects ssl client and server hello.
+ tcp-request inspect-delay 5s
+ tcp-request content accept if clienthello
- Currently, the POST request is limited to the buffer size minus the reserved
- buffer space, which means that if the list of servers is too long, the
- request won't be processed. It is recommended to alter few servers at a
- time.
+ # no timeout on response inspect delay by default.
+ tcp-response content accept if serverhello
- Example :
- # statistics admin level only for localhost
- backend stats_localhost
- stats enable
- stats admin if LOCALHOST
+ # SSL session ID (SSLID) may be present on a client or server hello.
+ # Its length is coded on 1 byte at offset 43 and its value starts
+ # at offset 44.
- Example :
- # statistics admin level always enabled because of the authentication
- backend stats_auth
- stats enable
- stats auth admin:AdMiN123
- stats admin if TRUE
+ # Match and learn on request if client hello.
+ stick on req.payload_lv(43,1) if clienthello
- Example :
- # statistics admin level depends on the authenticated user
- userlist stats-auth
- group admin users admin
- user admin insecure-password AdMiN123
- group readonly users haproxy
- user haproxy insecure-password haproxy
+ # Learn on response if server hello.
+ stick store-response resp.payload_lv(43,1) if serverhello
- backend stats_auth
- stats enable
- acl AUTH http_auth(stats-auth)
- acl AUTH_ADMIN http_auth_group(stats-auth) admin
- stats http-request auth unless AUTH
- stats admin if AUTH_ADMIN
+ server s1 192.168.1.1:443
+ server s2 192.168.1.1:443
- See also : "stats enable", "stats auth", "stats http-request", section 3.4
- about userlists and section 7 about ACL usage.
+ See also : "stick-table", "stick on", and section 7 about ACLs and pattern
+ extraction.
-stats auth <user>:<passwd>
- Enable statistics with authentication and grant access to an account
+tcp-check comment <string>
+ Defines a comment for the following the tcp-check rule, reported in logs if
+ it fails.
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <user> is a user name to grant access to
+ yes | no | yes | yes
- <passwd> is the cleartext password associated to this user
+ Arguments :
+ <string> is the comment message to add in logs if the following tcp-check
+ rule fails.
- This statement enables statistics with default settings, and restricts access
- to declared users only. It may be repeated as many times as necessary to
- allow as many users as desired. When a user tries to access the statistics
- without a valid account, a "401 Forbidden" response will be returned so that
- the browser asks the user to provide a valid user and password. The real
- which will be returned to the browser is configurable using "stats realm".
+ It only works for connect, send and expect rules. It is useful to make
+ user-friendly error reporting.
- Since the authentication method is HTTP Basic Authentication, the passwords
- circulate in cleartext on the network. Thus, it was decided that the
- configuration file would also use cleartext passwords to remind the users
- that those ones should not be sensitive and not shared with any other account.
+ See also : "option tcp-check", "tcp-check connect", "tcp-check send" and
+ "tcp-check expect".
- It is also possible to reduce the scope of the proxies which appear in the
- report using "stats scope".
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
+ [ssl] [sni <sni>] [alpn <alpn>] [linger]
+ [proto <name>] [comment <msg>]
+ Opens a new connection
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
+ Arguments :
+ comment <msg> defines a message to report if the rule evaluation fails.
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+ default Use default options of the server line to do the health
+ checks. The server options are used only if not redefined.
- See also : "stats enable", "stats realm", "stats scope", "stats uri"
+ port <expr> if not set, check port or server port is used.
+ It tells HAProxy where to open the connection to.
+ <port> must be a valid TCP port source integer, from 1 to
+ 65535 or an sample-fetch expression.
+ addr <ip> defines the IP address to do the health check.
-stats enable
- Enable statistics reporting with default settings
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ send-proxy send a PROXY protocol string
- This statement enables statistics reporting with default settings defined
- at build time. Unless stated otherwise, these settings are used :
- - stats uri : /haproxy?stats
- - stats realm : "HAProxy Statistics"
- - stats auth : no authentication
- - stats scope : no restriction
+ via-socks4 enables outgoing health checks using upstream socks4 proxy.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+ ssl opens a ciphered connection
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
+ sni <sni> specifies the SNI to use to do health checks over SSL.
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+ alpn <alpn> defines which protocols to advertise with ALPN. The protocol
+ list consists in a comma-delimited list of protocol names,
+ for instance: "http/1.1,http/1.0" (without quotes).
+ If it is not set, the server ALPN is used.
- See also : "stats auth", "stats realm", "stats uri"
+ proto <name> forces the multiplexer's protocol to use for this connection.
+ It must be a TCP mux protocol and it must be usable on the
+ backend side. The list of available protocols is reported in
+ haproxy -vv.
+ linger cleanly close the connection instead of using a single RST.
-stats hide-version
- Enable statistics and hide HAProxy version reporting
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ When an application lies on more than a single TCP port or when HAProxy
+ load-balance many services in a single backend, it makes sense to probe all
+ the services individually before considering a server as operational.
- By default, the stats page reports some useful status information along with
- the statistics. Among them is HAProxy's version. However, it is generally
- considered dangerous to report precise version to anyone, as it can help them
- target known weaknesses with specific attacks. The "stats hide-version"
- statement removes the version from the statistics report. This is recommended
- for public sites or any site with a weak login/password.
+ When there are no TCP port configured on the server line neither server port
+ directive, then the 'tcp-check connect port <port>' must be the first step
+ of the sequence.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+ In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
+ the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
+ do.
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
+ When a connect must start the ruleset, if may still be preceded by set-var,
+ unset-var or comment rules.
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+ Examples :
+ # check HTTP and HTTPs services on a server.
+ # first open port 80 thanks to server line port directive, then
+ # tcp-check opens port 443, ciphered and run a request on it:
+ option tcp-check
+ tcp-check connect
+ tcp-check send GET\ /\ HTTP/1.0\r\n
+ tcp-check send Host:\ haproxy.1wt.eu\r\n
+ tcp-check send \r\n
+ tcp-check expect rstring (2..|3..)
+ tcp-check connect port 443 ssl
+ tcp-check send GET\ /\ HTTP/1.0\r\n
+ tcp-check send Host:\ haproxy.1wt.eu\r\n
+ tcp-check send \r\n
+ tcp-check expect rstring (2..|3..)
+ server www 10.0.0.1 check port 80
- See also : "stats auth", "stats enable", "stats realm", "stats uri"
+ # check both POP and IMAP from a single server:
+ option tcp-check
+ tcp-check connect port 110 linger
+ tcp-check expect string +OK\ POP3\ ready
+ tcp-check connect port 143
+ tcp-check expect string *\ OK\ IMAP4\ ready
+ server mail 10.0.0.1 check
+ See also : "option tcp-check", "tcp-check send", "tcp-check expect"
-stats http-request { allow | deny | auth [realm <realm>] }
- [ { if | unless } <condition> ]
- Access control for statistics
+tcp-check expect [min-recv <int>] [comment <msg>]
+ [ok-status <st>] [error-status <st>] [tout-status <st>]
+ [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
+ [!] <match> <pattern>
+ Specify data to be collected and analyzed during a generic health check
May be used in sections: defaults | frontend | listen | backend
- no | no | yes | yes
+ yes | no | yes | yes
- As "http-request", these set of options allow to fine control access to
- statistics. Each option may be followed by if/unless and acl.
- First option with matched condition (or option without condition) is final.
- For "deny" a 403 error will be returned, for "allow" normal processing is
- performed, for "auth" a 401/407 error code is returned so the client
- should be asked to enter a username and password.
+ Arguments :
+ comment <msg> defines a message to report if the rule evaluation fails.
- There is no fixed limit to the number of http-request statements per
- instance.
+ min-recv is optional and can define the minimum amount of data required to
+ evaluate the current expect rule. If the number of received bytes
+ is under this limit, the check will wait for more data. This
+ option can be used to resolve some ambiguous matching rules or to
+ avoid executing costly regex matches on content known to be still
+ incomplete. If an exact string (string or binary) is used, the
+ minimum between the string length and this parameter is used.
+ This parameter is ignored if it is set to -1. If the expect rule
+ does not match, the check will wait for more data. If set to 0,
+ the evaluation result is always conclusive.
- See also : "http-request", section 3.4 about userlists and section 7
- about ACL usage.
+ <match> is a keyword indicating how to look for a specific pattern in the
+ response. The keyword may be one of "string", "rstring", "binary" or
+ "rbinary".
+ The keyword may be preceded by an exclamation mark ("!") to negate
+ the match. Spaces are allowed between the exclamation mark and the
+ keyword. See below for more details on the supported keywords.
+
+ ok-status <st> is optional and can be used to set the check status if
+ the expect rule is successfully evaluated and if it is
+ the last rule in the tcp-check ruleset. "L7OK", "L7OKC",
+ "L6OK" and "L4OK" are supported :
+ - L7OK : check passed on layer 7
+ - L7OKC : check conditionally passed on layer 7, set
+ server to NOLB state.
+ - L6OK : check passed on layer 6
+ - L4OK : check passed on layer 4
+ By default "L7OK" is used.
+ error-status <st> is optional and can be used to set the check status if
+ an error occurred during the expect rule evaluation.
+ "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are
+ supported :
+ - L7OKC : check conditionally passed on layer 7, set
+ server to NOLB state.
+ - L7RSP : layer 7 invalid response - protocol error
+ - L7STS : layer 7 response error, for example HTTP 5xx
+ - L6RSP : layer 6 invalid response - protocol error
+ - L4CON : layer 1-4 connection problem
+ By default "L7RSP" is used.
-stats realm <realm>
- Enable statistics and set authentication realm
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <realm> is the name of the HTTP Basic Authentication realm reported to
- the browser. The browser uses it to display it in the pop-up
- inviting the user to enter a valid username and password.
+ tout-status <st> is optional and can be used to set the check status if
+ a timeout occurred during the expect rule evaluation.
+ "L7TOUT", "L6TOUT", and "L4TOUT" are supported :
+ - L7TOUT : layer 7 (HTTP/SMTP) timeout
+ - L6TOUT : layer 6 (SSL) timeout
+ - L4TOUT : layer 1-4 timeout
+ By default "L7TOUT" is used.
- The realm is read as a single word, so any spaces in it should be escaped
- using a backslash ('\').
+ on-success <fmt> is optional and can be used to customize the
+ informational message reported in logs if the expect
+ rule is successfully evaluated and if it is the last rule
+ in the tcp-check ruleset. <fmt> is a log-format string.
- This statement is useful only in conjunction with "stats auth" since it is
- only related to authentication.
+ on-error <fmt> is optional and can be used to customize the
+ informational message reported in logs if an error
+ occurred during the expect rule evaluation. <fmt> is a
+ log-format string.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+ status-code <expr> is optional and can be used to set the check status code
+ reported in logs, on success or on error. <expr> is a
+ standard HAProxy expression formed by a sample-fetch
+ followed by some converters.
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
+ <pattern> is the pattern to look for. It may be a string or a regular
+ expression. If the pattern contains spaces, they must be escaped
+ with the usual backslash ('\').
+ If the match is set to binary, then the pattern must be passed as
+ a series of hexadecimal digits in an even number. Each sequence of
+ two digits will represent a byte. The hexadecimal digits may be
+ used upper or lower case.
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+ The available matches are intentionally similar to their http-check cousins :
- See also : "stats auth", "stats enable", "stats uri"
+ string <string> : test the exact string matches in the response buffer.
+ A health check response will be considered valid if the
+ response's buffer contains this exact string. If the
+ "string" keyword is prefixed with "!", then the response
+ will be considered invalid if the body contains this
+ string. This can be used to look for a mandatory pattern
+ in a protocol response, or to detect a failure when a
+ specific error appears in a protocol banner.
+ rstring <regex> : test a regular expression on the response buffer.
+ A health check response will be considered valid if the
+ response's buffer matches this expression. If the
+ "rstring" keyword is prefixed with "!", then the response
+ will be considered invalid if the body matches the
+ expression.
-stats refresh <delay>
- Enable statistics with automatic refresh
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <delay> is the suggested refresh delay, specified in seconds, which will
- be returned to the browser consulting the report page. While the
- browser is free to apply any delay, it will generally respect it
- and refresh the page this every seconds. The refresh interval may
- be specified in any other non-default time unit, by suffixing the
- unit after the value, as explained at the top of this document.
+ string-lf <fmt> : test a log-format string match in the response's buffer.
+ A health check response will be considered valid if the
+ response's buffer contains the string resulting of the
+ evaluation of <fmt>, which follows the log-format rules.
+ If prefixed with "!", then the response will be
+ considered invalid if the buffer contains the string.
- This statement is useful on monitoring displays with a permanent page
- reporting the load balancer's activity. When set, the HTML report page will
- include a link "refresh"/"stop refresh" so that the user can select whether
- they want automatic refresh of the page or not.
+ binary <hexstring> : test the exact string in its hexadecimal form matches
+ in the response buffer. A health check response will
+ be considered valid if the response's buffer contains
+ this exact hexadecimal string.
+ Purpose is to match data on binary protocols.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+ rbinary <regex> : test a regular expression on the response buffer, like
+ "rstring". However, the response buffer is transformed
+ into its hexadecimal form, including NUL-bytes. This
+ allows using all regex engines to match any binary
+ content. The hexadecimal transformation takes twice the
+ size of the original response. As such, the expected
+ pattern should work on at-most half the response buffer
+ size.
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
+ binary-lf <hexfmt> : test a log-format string in its hexadecimal form
+ match in the response's buffer. A health check response
+ will be considered valid if the response's buffer
+ contains the hexadecimal string resulting of the
+ evaluation of <fmt>, which follows the log-format
+ rules. If prefixed with "!", then the response will be
+ considered invalid if the buffer contains the
+ hexadecimal string. The hexadecimal string is converted
+ in a binary string before matching the response's
+ buffer.
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+ It is important to note that the responses will be limited to a certain size
+ defined by the global "tune.bufsize" option, which defaults to 16384 bytes.
+ Thus, too large responses may not contain the mandatory pattern when using
+ "string", "rstring" or binary. If a large response is absolutely required, it
+ is possible to change the default max size by setting the global variable.
+ However, it is worth keeping in mind that parsing very large responses can
+ waste some CPU cycles, especially when regular expressions are used, and that
+ it is always better to focus the checks on smaller resources. Also, in its
+ current state, the check will not find any string nor regex past a null
+ character in the response. Similarly it is not possible to request matching
+ the null character.
- See also : "stats auth", "stats enable", "stats realm", "stats uri"
+ Examples :
+ # perform a POP check
+ option tcp-check
+ tcp-check expect string +OK\ POP3\ ready
+ # perform an IMAP check
+ option tcp-check
+ tcp-check expect string *\ OK\ IMAP4\ ready
-stats scope { <name> | "." }
- Enable statistics and limit access scope
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <name> is the name of a listen, frontend or backend section to be
- reported. The special name "." (a single dot) designates the
- section in which the statement appears.
+ # look for the redis master server
+ option tcp-check
+ tcp-check send PING\r\n
+ tcp-check expect string +PONG
+ tcp-check send info\ replication\r\n
+ tcp-check expect string role:master
+ tcp-check send QUIT\r\n
+ tcp-check expect string +OK
- When this statement is specified, only the sections enumerated with this
- statement will appear in the report. All other ones will be hidden. This
- statement may appear as many times as needed if multiple sections need to be
- reported. Please note that the name checking is performed as simple string
- comparisons, and that it is never checked that a give section name really
- exists.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+ See also : "option tcp-check", "tcp-check connect", "tcp-check send",
+ "tcp-check send-binary", "http-check expect", tune.bufsize
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+tcp-check send <data> [comment <msg>]
+tcp-check send-lf <fmt> [comment <msg>]
+ Specify a string or a log-format string to be sent as a question during a
+ generic health check
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- See also : "stats auth", "stats enable", "stats realm", "stats uri"
+ Arguments :
+ comment <msg> defines a message to report if the rule evaluation fails.
+ <data> is the string that will be sent during a generic health
+ check session.
-stats show-desc [ <desc> ]
- Enable reporting of a description on the statistics page.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
+ <fmt> is the log-format string that will be sent, once evaluated,
+ during a generic health check session.
- <desc> is an optional description to be reported. If unspecified, the
- description from global section is automatically used instead.
+ Examples :
+ # look for the redis master server
+ option tcp-check
+ tcp-check send info\ replication\r\n
+ tcp-check expect string role:master
- This statement is useful for users that offer shared services to their
- customers, where node or description should be different for each customer.
+ See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
+ "tcp-check send-binary", tune.bufsize
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters. By default description is not shown.
- Example :
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats show-desc Master node for Europe, Asia, Africa
- stats uri /admin?stats
- stats refresh 5s
+tcp-check send-binary <hexstring> [comment <msg>]
+tcp-check send-binary-lf <hexfmt> [comment <msg>]
+ Specify an hex digits string or an hex digits log-format string to be sent as
+ a binary question during a raw tcp health check
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- See also: "show-node", "stats enable", "stats uri" and "description" in
- global section.
+ Arguments :
+ comment <msg> defines a message to report if the rule evaluation fails.
+ <hexstring> is the hexadecimal string that will be send, once converted
+ to binary, during a generic health check session.
-stats show-legends
- Enable reporting additional information on the statistics page
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+ <hexfmt> is the hexadecimal log-format string that will be send, once
+ evaluated and converted to binary, during a generic health
+ check session.
- Enable reporting additional information on the statistics page :
- - cap: capabilities (proxy)
- - mode: one of tcp, http or health (proxy)
- - id: SNMP ID (proxy, socket, server)
- - IP (socket, server)
- - cookie (backend, server)
+ Examples :
+ # redis check in binary
+ option tcp-check
+ tcp-check send-binary 50494e470d0a # PING\r\n
+ tcp-check expect binary 2b504F4e47 # +PONG
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters. Default behavior is not to show this information.
- See also: "stats enable", "stats uri".
+ See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
+ "tcp-check send", tune.bufsize
-stats show-modules
- Enable display of extra statistics module on the statistics page
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments : none
+tcp-check set-var(<var-name>[,<cond>...]) <expr>
+tcp-check set-var-fmt(<var-name>[,<cond>...]) <fmt>
+ This operation sets the content of a variable. The variable is declared inline.
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- New columns are added at the end of the line containing the extra statistics
- values as a tooltip.
+ Arguments :
+ <var-name> The name of the variable starts with an indication about its
+ scope. The scopes allowed for tcp-check are:
+ "proc" : the variable is shared with the whole process.
+ "sess" : the variable is shared with the tcp-check session.
+ "check": the variable is declared for the lifetime of the tcp-check.
+ This prefix is followed by a name. The separator is a '.'.
+ The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
+ and '-'.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters. Default behavior is not to show this information.
+ <cond> A set of conditions that must all be true for the variable to
+ actually be set (such as "ifnotempty", "ifgt" ...). See the
+ set-var converter's description for a full list of possible
+ conditions.
- See also: "stats enable", "stats uri".
+ <expr> Is a sample-fetch expression potentially followed by converters.
+ <fmt> This is the value expressed using log-format rules (see Custom
+ Log Format in section 8.2.4).
-stats show-node [ <name> ]
- Enable reporting of a host name on the statistics page.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments:
- <name> is an optional name to be reported. If unspecified, the
- node name from global section is automatically used instead.
+ Examples :
+ tcp-check set-var(check.port) int(1234)
+ tcp-check set-var-fmt(check.name) "%H"
- This statement is useful for users that offer shared services to their
- customers, where node or description might be different on a stats page
- provided for each customer. Default behavior is not to show host name.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+tcp-check unset-var(<var-name>)
+ Free a reference to a variable within its scope.
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
- Example:
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats show-node Europe-1
- stats uri /admin?stats
- stats refresh 5s
+ Arguments :
+ <var-name> The name of the variable starts with an indication about its
+ scope. The scopes allowed for tcp-check are:
+ "proc" : the variable is shared with the whole process.
+ "sess" : the variable is shared with the tcp-check session.
+ "check": the variable is declared for the lifetime of the tcp-check.
+ This prefix is followed by a name. The separator is a '.'.
+ The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
+ and '-'.
- See also: "show-desc", "stats enable", "stats uri", and "node" in global
- section.
+ Examples :
+ tcp-check unset-var(check.port)
-stats uri <prefix>
- Enable statistics and define the URI prefix to access them
+tcp-request connection <action> <options...> [ { if | unless } <condition> ]
+ Perform an action on an incoming connection depending on a layer 4 condition
May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
+ yes(!) | yes | yes | no
Arguments :
- <prefix> is the prefix of any URI which will be redirected to stats. This
- prefix may contain a question mark ('?') to indicate part of a
- query string.
+ <action> defines the action to perform if the condition applies. See
+ below.
- The statistics URI is intercepted on the relayed traffic, so it appears as a
- page within the normal application. It is strongly advised to ensure that the
- selected URI will never appear in the application, otherwise it will never be
- possible to reach it in the application.
+ <condition> is a standard layer4-only ACL-based condition (see section 7).
- The default URI compiled in HAProxy is "/haproxy?stats", but this may be
- changed at build time, so it's better to always explicitly specify it here.
- It is generally a good idea to include a question mark in the URI so that
- intermediate proxies refrain from caching the results. Also, since any string
- beginning with the prefix will be accepted as a stats request, the question
- mark helps ensuring that no valid URI will begin with the same words.
+ Immediately after acceptance of a new incoming connection, it is possible to
+ evaluate some conditions to decide whether this connection must be accepted
+ or dropped or have its counters tracked. Those conditions cannot make use of
+ any data contents because the connection has not been read from yet, and the
+ buffers are not yet allocated. This is used to selectively and very quickly
+ accept or drop connections from various sources with a very low overhead. If
+ some contents need to be inspected in order to take the decision, the
+ "tcp-request content" statements must be used instead.
- It is sometimes very convenient to use "/" as the URI prefix, and put that
- statement in a "listen" instance of its own. That makes it easy to dedicate
- an address or a port to statistics only.
+ The "tcp-request connection" rules are evaluated in their exact declaration
+ order. If no rule matches or if there is no rule, the default action is to
+ accept the incoming connection. There is no specific limit to the number of
+ rules which may be inserted. Any rule may optionally be followed by an
+ ACL-based condition, in which case it will only be evaluated if the condition
+ evaluates to true.
- Though this statement alone is enough to enable statistics reporting, it is
- recommended to set all other settings in order to avoid relying on default
- unobvious parameters.
+ The condition is evaluated just before the action is executed, and the action
+ is performed exactly once. As such, there is no problem if an action changes
+ an element which is checked as part of the condition. This also means that
+ multiple actions may rely on the same condition so that the first action that
+ changes the condition's evaluation is sufficient to implicitly disable the
+ remaining actions. This is used for example when trying to assign a value to
+ a variable from various sources when it's empty.
- Example :
- # public access (limited to this backend only)
- backend public_www
- server srv1 192.168.0.1:80
- stats enable
- stats hide-version
- stats scope .
- stats uri /admin?stats
- stats realm HAProxy\ Statistics
- stats auth admin1:AdMiN123
- stats auth admin2:AdMiN321
+ The first keyword after "tcp-request connection" in the syntax is the rule's
+ action, optionally followed by a varying number of arguments for the action.
+ The supported actions and their respective syntaxes are enumerated in
+ section 4.3 "Actions" (look for actions which tick "TCP RqCon").
- # internal monitoring access (unlimited)
- backend private_monitoring
- stats enable
- stats uri /admin?stats
- stats refresh 5s
+ This directive is only available from named defaults sections, not anonymous
+ ones. Rules defined in the defaults section are evaluated before ones in the
+ associated proxy section. To avoid ambiguities, in this case the same
+ defaults section cannot be used by proxies with the frontend capability and
+ by proxies with the backend capability. It means a listen section cannot use
+ a defaults section defining such rules.
- See also : "stats auth", "stats enable", "stats realm"
+ Note that the "if/unless" condition is optional. If no condition is set on
+ the action, it is simply performed unconditionally. That can be useful for
+ "track-sc*" actions as well as for changing the default action to a reject.
+ Example: accept all connections from white-listed hosts, reject too fast
+ connection without counting them, and track accepted connections.
+ This results in connection rate being capped from abusive sources.
-stick match <pattern> [table <table>] [{if | unless} <cond>]
- Define a request pattern matching condition to stick a user to a server
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
+ tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
+ tcp-request connection reject if { src_conn_rate gt 10 }
+ tcp-request connection track-sc0 src
- Arguments :
- <pattern> is a sample expression rule as described in section 7.3. It
- describes what elements of the incoming request or connection
- will be analyzed in the hope to find a matching entry in a
- stickiness table. This rule is mandatory.
+ Example: accept all connections from white-listed hosts, count all other
+ connections and reject too fast ones. This results in abusive ones
+ being blocked as long as they don't slow down.
- <table> is an optional stickiness table name. If unspecified, the same
- backend's table is used. A stickiness table is declared using
- the "stick-table" statement.
+ tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
+ tcp-request connection track-sc0 src
+ tcp-request connection reject if { sc0_conn_rate gt 10 }
- <cond> is an optional matching condition. It makes it possible to match
- on a certain criterion only when other conditions are met (or
- not met). For instance, it could be used to match on a source IP
- address except when a request passes through a known proxy, in
- which case we'd match on a header containing that IP address.
+ Example: enable the PROXY protocol for traffic coming from all known proxies.
- Some protocols or applications require complex stickiness rules and cannot
- always simply rely on cookies nor hashing. The "stick match" statement
- describes a rule to extract the stickiness criterion from an incoming request
- or connection. See section 7 for a complete list of possible patterns and
- transformation rules.
+ tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
- The table has to be declared using the "stick-table" statement. It must be of
- a type compatible with the pattern. By default it is the one which is present
- in the same backend. It is possible to share a table with other backends by
- referencing it using the "table" keyword. If another table is referenced,
- the server's ID inside the backends are used. By default, all server IDs
- start at 1 in each backend, so the server ordering is enough. But in case of
- doubt, it is highly recommended to force server IDs using their "id" setting.
+ See section 7 about ACL usage.
- It is possible to restrict the conditions where a "stick match" statement
- will apply, using "if" or "unless" followed by a condition. See section 7 for
- ACL based conditions.
+ See also : "tcp-request session", "tcp-request content", "stick-table"
- There is no limit on the number of "stick match" statements. The first that
- applies and matches will cause the request to be directed to the same server
- as was used for the request which created the entry. That way, multiple
- matches can be used as fallbacks.
+tcp-request content <action> [{if | unless} <condition>]
+ Perform an action on a new session depending on a layer 4-7 condition
+ May be used in sections : defaults | frontend | listen | backend
+ yes(!) | yes | yes | yes
+ Arguments :
+ <action> defines the action to perform if the condition applies. See
+ below.
- The stick rules are checked after the persistence cookies, so they will not
- affect stickiness if a cookie has already been used to select a server. That
- way, it becomes very easy to insert cookies and match on IP addresses in
- order to maintain stickiness between HTTP and HTTPS.
+ <condition> is a standard layer 4-7 ACL-based condition (see section 7).
- Example :
- # forward SMTP users to the same server they just used for POP in the
- # last 30 minutes
- backend pop
- mode tcp
- balance roundrobin
- stick store-request src
- stick-table type ip size 200k expire 30m
- server s1 192.168.1.1:110
- server s2 192.168.1.1:110
+ A request's contents can be analyzed at an early stage of request processing
+ called "TCP content inspection". During this stage, ACL-based rules are
+ evaluated every time the request contents are updated, until either an
+ "accept", a "reject" or a "switch-mode" rule matches, or the TCP request
+ inspection delay expires with no matching rule.
- backend smtp
- mode tcp
- balance roundrobin
- stick match src table pop
- server s1 192.168.1.1:25
- server s2 192.168.1.1:25
+ The first difference between these rules and "tcp-request connection" rules
+ is that "tcp-request content" rules can make use of contents to take a
+ decision. Most often, these decisions will consider a protocol recognition or
+ validity. The second difference is that content-based rules can be used in
+ both frontends and backends. In case of HTTP keep-alive with the client, all
+ tcp-request content rules are evaluated again, so HAProxy keeps a record of
+ what sticky counters were assigned by a "tcp-request connection" versus a
+ "tcp-request content" rule, and flushes all the content-related ones after
+ processing an HTTP request, so that they may be evaluated again by the rules
+ being evaluated again for the next request. This is of particular importance
+ when the rule tracks some L7 information or when it is conditioned by an
+ L7-based ACL, since tracking may change between requests.
+
+ Content-based rules are evaluated in their exact declaration order. If no
+ rule matches or if there is no rule, the default action is to accept the
+ contents. There is no specific limit to the number of rules which may be
+ inserted.
- See also : "stick-table", "stick on", and section 7 about ACLs and samples
- fetching.
+ While there is nothing mandatory about it, it is recommended to use the
+ track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
+ content" rules in the frontend, and track-sc2 for "tcp-request content"
+ rules in the backend, because that makes the configuration more readable
+ and easier to troubleshoot, but this is just a guideline and all counters
+ may be used everywhere.
+ The first keyword after "tcp-request content" in the syntax is the rule's
+ action, optionally followed by a varying number of arguments for the action.
+ The supported actions and their respective syntaxes are enumerated in
+ section 4.3 "Actions" (look for actions which tick "TCP RqCnt").
-stick on <pattern> [table <table>] [{if | unless} <condition>]
- Define a request pattern to associate a user to a server
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
+ This directive is only available from named defaults sections, not anonymous
+ ones. Rules defined in the defaults section are evaluated before ones in the
+ associated proxy section. To avoid ambiguities, in this case the same
+ defaults section cannot be used by proxies with the frontend capability and
+ by proxies with the backend capability. It means a listen section cannot use
+ a defaults section defining such rules.
- Note : This form is exactly equivalent to "stick match" followed by
- "stick store-request", all with the same arguments. Please refer
- to both keywords for details. It is only provided as a convenience
- for writing more maintainable configurations.
+ Note that the "if/unless" condition is optional. If no condition is set on
+ the action, it is simply performed unconditionally. That can be useful for
+ "track-sc*" actions as well as for changing the default action to a reject.
- Examples :
- # The following form ...
- stick on src table pop if !localhost
+ Note also that it is recommended to use a "tcp-request session" rule to track
+ information that does *not* depend on Layer 7 contents, especially for HTTP
+ frontends. Some HTTP processing are performed at the session level and may
+ lead to an early rejection of the requests. Thus, the tracking at the content
+ level may be disturbed in such case. A warning is emitted during startup to
+ prevent, as far as possible, such unreliable usage.
- # ...is strictly equivalent to this one :
- stick match src table pop if !localhost
- stick store-request src table pop if !localhost
+ It is perfectly possible to match layer 7 contents with "tcp-request content"
+ rules from a TCP proxy, since HTTP-specific ACL matches are able to
+ preliminarily parse the contents of a buffer before extracting the required
+ data. If the buffered contents do not parse as a valid HTTP message, then the
+ ACL does not match. The parser which is involved there is exactly the same
+ as for all other HTTP processing, so there is no risk of parsing something
+ differently. In an HTTP frontend or an HTTP backend, it is guaranteed that
+ HTTP contents will always be immediately present when the rule is evaluated
+ first because the HTTP parsing is performed in the early stages of the
+ connection processing, at the session level. But for such proxies, using
+ "http-request" rules is much more natural and recommended.
+ Tracking layer7 information is also possible provided that the information
+ are present when the rule is processed. The rule processing engine is able to
+ wait until the inspect delay expires when the data to be tracked is not yet
+ available.
- # Use cookie persistence for HTTP, and stick on source address for HTTPS as
- # well as HTTP without cookie. Share the same table between both accesses.
- backend http
- mode http
- balance roundrobin
- stick on src table https
- cookie SRV insert indirect nocache
- server s1 192.168.1.1:80 cookie s1
- server s2 192.168.1.1:80 cookie s2
+ Example:
+ tcp-request content use-service lua.deny if { src -f /etc/haproxy/blacklist.lst }
- backend https
- mode tcp
- balance roundrobin
- stick-table type ip size 200k expire 30m
- stick on src
- server s1 192.168.1.1:443
- server s2 192.168.1.1:443
+ Example:
+ tcp-request content set-var(sess.my_var) src
+ tcp-request content set-var-fmt(sess.from) %[src]:%[src_port]
+ tcp-request content unset-var(sess.my_var2)
- See also : "stick match", "stick store-request".
+ Example:
+ # Accept HTTP requests containing a Host header saying "example.com"
+ # and reject everything else. (Only works for HTTP/1 connections)
+ acl is_host_com hdr(Host) -i example.com
+ tcp-request inspect-delay 30s
+ tcp-request content accept if is_host_com
+ tcp-request content reject
+ # Accept HTTP requests containing a Host header saying "example.com"
+ # and reject everything else. (works for HTTP/1 and HTTP/2 connections)
+ acl is_host_com hdr(Host) -i example.com
+ tcp-request inspect-delay 5s
+ tcp-request switch-mode http if HTTP
+ tcp-request reject # non-HTTP traffic is implicit here
+ ...
+ http-request reject unless is_host_com
-stick store-request <pattern> [table <table>] [{if | unless} <condition>]
- Define a request pattern used to create an entry in a stickiness table
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
+ Example:
+ # reject SMTP connection if client speaks first
+ tcp-request inspect-delay 30s
+ acl content_present req.len gt 0
+ tcp-request content reject if content_present
- Arguments :
- <pattern> is a sample expression rule as described in section 7.3. It
- describes what elements of the incoming request or connection
- will be analyzed, extracted and stored in the table once a
- server is selected.
+ # Forward HTTPS connection only if client speaks
+ tcp-request inspect-delay 30s
+ acl content_present req.len gt 0
+ tcp-request content accept if content_present
+ tcp-request content reject
- <table> is an optional stickiness table name. If unspecified, the same
- backend's table is used. A stickiness table is declared using
- the "stick-table" statement.
+ Example:
+ # Track the last IP(stick-table type string) from X-Forwarded-For
+ tcp-request inspect-delay 10s
+ tcp-request content track-sc0 hdr(x-forwarded-for,-1)
+ # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
+ tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
- <cond> is an optional storage condition. It makes it possible to store
- certain criteria only when some conditions are met (or not met).
- For instance, it could be used to store the source IP address
- except when the request passes through a known proxy, in which
- case we'd store a converted form of a header containing that IP
- address.
+ Example:
+ # track request counts per "base" (concatenation of Host+URL)
+ tcp-request inspect-delay 10s
+ tcp-request content track-sc0 base table req-rate
- Some protocols or applications require complex stickiness rules and cannot
- always simply rely on cookies nor hashing. The "stick store-request" statement
- describes a rule to decide what to extract from the request and when to do
- it, in order to store it into a stickiness table for further requests to
- match it using the "stick match" statement. Obviously the extracted part must
- make sense and have a chance to be matched in a further request. Storing a
- client's IP address for instance often makes sense. Storing an ID found in a
- URL parameter also makes sense. Storing a source port will almost never make
- any sense because it will be randomly matched. See section 7 for a complete
- list of possible patterns and transformation rules.
+ Example: track per-frontend and per-backend counters, block abusers at the
+ frontend when the backend detects abuse(and marks gpc0).
- The table has to be declared using the "stick-table" statement. It must be of
- a type compatible with the pattern. By default it is the one which is present
- in the same backend. It is possible to share a table with other backends by
- referencing it using the "table" keyword. If another table is referenced,
- the server's ID inside the backends are used. By default, all server IDs
- start at 1 in each backend, so the server ordering is enough. But in case of
- doubt, it is highly recommended to force server IDs using their "id" setting.
+ frontend http
+ # Use General Purpose Counter 0 in SC0 as a global abuse counter
+ # protecting all our sites
+ stick-table type ip size 1m expire 5m store gpc0
+ tcp-request connection track-sc0 src
+ tcp-request connection reject if { sc0_get_gpc0 gt 0 }
+ ...
+ use_backend http_dynamic if { path_end .php }
- It is possible to restrict the conditions where a "stick store-request"
- statement will apply, using "if" or "unless" followed by a condition. This
- condition will be evaluated while parsing the request, so any criteria can be
- used. See section 7 for ACL based conditions.
+ backend http_dynamic
+ # if a source makes too fast requests to this dynamic site (tracked
+ # by SC1), block it globally in the frontend.
+ stick-table type ip size 1m expire 5m store http_req_rate(10s)
+ acl click_too_fast sc1_http_req_rate gt 10
+ acl mark_as_abuser sc0_inc_gpc0(http) gt 0
+ tcp-request content track-sc1 src
+ tcp-request content reject if click_too_fast mark_as_abuser
- There is no limit on the number of "stick store-request" statements, but
- there is a limit of 8 simultaneous stores per request or response. This
- makes it possible to store up to 8 criteria, all extracted from either the
- request or the response, regardless of the number of rules. Only the 8 first
- ones which match will be kept. Using this, it is possible to feed multiple
- tables at once in the hope to increase the chance to recognize a user on
- another protocol or access method. Using multiple store-request rules with
- the same table is possible and may be used to find the best criterion to rely
- on, by arranging the rules by decreasing preference order. Only the first
- extracted criterion for a given table will be stored. All subsequent store-
- request rules referencing the same table will be skipped and their ACLs will
- not be evaluated.
+ See section 7 about ACL usage.
- The "store-request" rules are evaluated once the server connection has been
- established, so that the table will contain the real server that processed
- the request.
+ See also : "tcp-request connection", "tcp-request session",
+ "tcp-request inspect-delay", and "http-request".
- Example :
- # forward SMTP users to the same server they just used for POP in the
- # last 30 minutes
- backend pop
- mode tcp
- balance roundrobin
- stick store-request src
- stick-table type ip size 200k expire 30m
- server s1 192.168.1.1:110
- server s2 192.168.1.1:110
+tcp-request inspect-delay <timeout>
+ Set the maximum allowed time to wait for data during content inspection
+ May be used in sections : defaults | frontend | listen | backend
+ yes(!) | yes | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- backend smtp
- mode tcp
- balance roundrobin
- stick match src table pop
- server s1 192.168.1.1:25
- server s2 192.168.1.1:25
+ People using HAProxy primarily as a TCP relay are often worried about the
+ risk of passing any type of protocol to a server without any analysis. In
+ order to be able to analyze the request contents, we must first withhold
+ the data then analyze them. This statement simply enables withholding of
+ data for at most the specified amount of time.
- See also : "stick-table", "stick on", about ACLs and sample fetching.
+ TCP content inspection applies very early when a connection reaches a
+ frontend, then very early when the connection is forwarded to a backend. This
+ means that a connection may experience a first delay in the frontend and a
+ second delay in the backend if both have tcp-request rules.
+ Note that when performing content inspection, HAProxy will evaluate the whole
+ rules for every new chunk which gets in, taking into account the fact that
+ those data are partial. If no rule matches before the aforementioned delay,
+ a last check is performed upon expiration, this time considering that the
+ contents are definitive. If no delay is set, HAProxy will not wait at all
+ and will immediately apply a verdict based on the available information.
+ Obviously this is unlikely to be very useful and might even be racy, so such
+ setups are not recommended.
-stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
- size <size> [expire <expire>] [nopurge] [peers <peersect>] [srvkey <srvkey>]
- [write-to <wtable>] [store <data_type>]*
- Configure the stickiness table for the current section
- May be used in sections : defaults | frontend | listen | backend
- no | yes | yes | yes
+ Note the inspection delay is shortened if an connection error or shutdown is
+ experienced or if the request buffer appears as full.
- Arguments :
- ip a table declared with "type ip" will only store IPv4 addresses.
- This form is very compact (about 50 bytes per entry) and allows
- very fast entry lookup and stores with almost no overhead. This
- is mainly used to store client source IP addresses.
+ As soon as a rule matches, the request is released and continues as usual. If
+ the timeout is reached and no rule matches, the default policy will be to let
+ it pass through unaffected.
- ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
- This form is very compact (about 60 bytes per entry) and allows
- very fast entry lookup and stores with almost no overhead. This
- is mainly used to store client source IP addresses.
+ For most protocols, it is enough to set it to a few seconds, as most clients
+ send the full request immediately upon connection. Add 3 or more seconds to
+ cover TCP retransmits but that's all. For some protocols, it may make sense
+ to use large values, for instance to ensure that the client never talks
+ before the server (e.g. SMTP), or to wait for a client to talk before passing
+ data to the server (e.g. SSL). Note that the client timeout must cover at
+ least the inspection delay, otherwise it will expire first. If the client
+ closes the connection or if the buffer is full, the delay immediately expires
+ since the contents will not be able to change anymore.
- integer a table declared with "type integer" will store 32bit integers
- which can represent a client identifier found in a request for
- instance.
+ This directive is only available from named defaults sections, not anonymous
+ ones. Proxies inherit this value from their defaults section.
- string a table declared with "type string" will store substrings of up
- to <len> characters. If the string provided by the pattern
- extractor is larger than <len>, it will be truncated before
- being stored. During matching, at most <len> characters will be
- compared between the string in the table and the extracted
- pattern. When not specified, the string is automatically limited
- to 32 characters.
+ See also : "tcp-request content accept", "tcp-request content reject",
+ "timeout client".
- binary a table declared with "type binary" will store binary blocks
- of <len> bytes. If the block provided by the pattern
- extractor is larger than <len>, it will be truncated before
- being stored. If the block provided by the sample expression
- is shorter than <len>, it will be padded by 0. When not
- specified, the block is automatically limited to 32 bytes.
- <length> is the maximum number of characters that will be stored in a
- "string" type table (See type "string" above). Or the number
- of bytes of the block in "binary" type table. Be careful when
- changing this parameter as memory usage will proportionally
- increase.
+tcp-request session <action> [{if | unless} <condition>]
+ Perform an action on a validated session depending on a layer 5 condition
+ May be used in sections : defaults | frontend | listen | backend
+ yes(!) | yes | yes | no
+ Arguments :
+ <action> defines the action to perform if the condition applies. See
+ below.
- <size> is the maximum number of entries that can fit in the table. This
- value directly impacts memory usage. Count approximately
- 50 bytes per entry, plus the size of a string if any. The size
- supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
+ <condition> is a standard layer5-only ACL-based condition (see section 7).
- [nopurge] indicates that we refuse to purge older entries when the table
- is full. When not specified and the table is full when HAProxy
- wants to store an entry in it, it will flush a few of the oldest
- entries in order to release some space for the new ones. This is
- most often the desired behavior. In some specific cases, it
- be desirable to refuse new entries instead of purging the older
- ones. That may be the case when the amount of data to store is
- far above the hardware limits and we prefer not to offer access
- to new clients than to reject the ones already connected. When
- using this parameter, be sure to properly set the "expire"
- parameter (see below).
+ Once a session is validated, (i.e. after all handshakes have been completed),
+ it is possible to evaluate some conditions to decide whether this session
+ must be accepted or dropped or have its counters tracked. Those conditions
+ cannot make use of any data contents because no buffers are allocated yet and
+ the processing cannot wait at this stage. The main use case is to copy some
+ early information into variables (since variables are accessible in the
+ session), or to keep track of some information collected after the handshake,
+ such as SSL-level elements (SNI, ciphers, client cert's CN) or information
+ from the PROXY protocol header (e.g. track a source forwarded this way). The
+ extracted information can thus be copied to a variable or tracked using
+ "track-sc" rules. Of course it is also possible to decide to accept/reject as
+ with other rulesets. Most operations performed here could also be performed
+ in "tcp-request content" rules, except that in HTTP these rules are evaluated
+ for each new request, and that might not always be acceptable. For example a
+ rule might increment a counter on each evaluation. It would also be possible
+ that a country is resolved by geolocation from the source IP address,
+ assigned to a session-wide variable, then the source address rewritten from
+ an HTTP header for all requests. If some contents need to be inspected in
+ order to take the decision, the "tcp-request content" statements must be used
+ instead.
- <peersect> is the name of the peers section to use for replication. Entries
- which associate keys to server IDs are kept synchronized with
- the remote peers declared in this section. All entries are also
- automatically learned from the local peer (old process) during a
- soft restart.
+ The "tcp-request session" rules are evaluated in their exact declaration
+ order. If no rule matches or if there is no rule, the default action is to
+ accept the incoming session. There is no specific limit to the number of
+ rules which may be inserted.
- <wtable> is the name of the stick table where peers updates will be
- written to in addition to the source table. <wtable> must be of
- the same type as the table being defined and must have the same
- key length, and source table cannot be used as a target table
- itself. Every time an entry update will be received on the source
- table through a peer, haproxy will try to refresh related
- <wtable> entry. If the entry doesn't exist yet, it will be
- created, else its values will be updated as well as its timer.
- Note that only types that are not involved in arithmetic ops such
- as server_id, server_key and gpt will be written to <wtable> to
- prevent processed values from a remote table from interfering with
- arithmetic operations performed on the local target table.
- (ie: prevent shared cumulative counter from growing indefinitely)
- One common use of this option is to be able to use sticking rules
- (for server persistence) in a peers cluster setup, because
- matching keys will be learned from remote tables.
+ The first keyword after "tcp-request session" in the syntax is the rule's
+ action, optionally followed by a varying number of arguments for the action.
+ The supported actions and their respective syntaxes are enumerated in
+ section 4.3 "Actions" (look for actions which tick "TCP RqSes").
- <expire> defines the maximum duration of an entry in the table since it
- was last created, refreshed using 'track-sc' or matched using
- 'stick match' or 'stick on' rule. The expiration delay is
- defined using the standard time format, similarly as the various
- timeouts. The maximum duration is slightly above 24 days. See
- section 2.5 for more information. If this delay is not specified,
- the session won't automatically expire, but older entries will
- be removed once full. Be sure not to use the "nopurge" parameter
- if not expiration delay is specified.
- Note: 'table_*' converters performs lookups but won't update touch
- expire since they don't require 'track-sc'.
+ This directive is only available from named defaults sections, not anonymous
+ ones. Rules defined in the defaults section are evaluated before ones in the
+ associated proxy section. To avoid ambiguities, in this case the same
+ defaults section cannot be used by proxies with the frontend capability and
+ by proxies with the backend capability. It means a listen section cannot use
+ a defaults section defining such rules.
- <srvkey> specifies how each server is identified for the purposes of the
- stick table. The valid values are "name" and "addr". If "name" is
- given, then <name> argument for the server (may be generated by
- a template). If "addr" is given, then the server is identified
- by its current network address, including the port. "addr" is
- especially useful if you are using service discovery to generate
- the addresses for servers with peered stick-tables and want
- to consistently use the same host across peers for a stickiness
- token.
+ Note that the "if/unless" condition is optional. If no condition is set on
+ the action, it is simply performed unconditionally. That can be useful for
+ "track-sc*" actions as well as for changing the default action to a reject.
- <data_type> is used to store additional information in the stick-table. This
- may be used by ACLs in order to control various criteria related
- to the activity of the client matching the stick-table. For each
- item specified here, the size of each entry will be inflated so
- that the additional data can fit. Several data types may be
- stored with an entry. Multiple data types may be specified after
- the "store" keyword, as a comma-separated list. Alternatively,
- it is possible to repeat the "store" keyword followed by one or
- several data types. Except for the "server_id" type which is
- automatically detected and enabled, all data types must be
- explicitly declared to be stored. If an ACL references a data
- type which is not stored, the ACL will simply not match. Some
- data types require an argument which must be passed just after
- the type between parenthesis. See below for the supported data
- types and their arguments.
+ Example: track the original source address by default, or the one advertised
+ in the PROXY protocol header for connection coming from the local
+ proxies. The first connection-level rule enables receipt of the
+ PROXY protocol for these ones, the second rule tracks whatever
+ address we decide to keep after optional decoding.
- The data types that can be stored with an entry are the following :
- - server_id : this is an integer which holds the numeric ID of the server a
- request was assigned to. It is used by the "stick match", "stick store",
- and "stick on" rules. It is automatically enabled when referenced.
+ tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
+ tcp-request session track-sc0 src
- - gpc(<nb>) : General Purpose Counters Array of <nb> elements. This is an
- array of positive 32-bit integers which may be used to count anything.
- Most of the time they will be used as a incremental counters on some
- entries, for instance to note that a limit is reached and trigger some
- actions. This array is limited to a maximum of 100 elements:
- gpc0 to gpc99, to ensure that the build of a peer update
- message can fit into the buffer. Users should take in consideration
- that a large amount of counters will increase the data size and the
- traffic load using peers protocol since all data/counters are pushed
- each time any of them is updated.
- This data_type will exclude the usage of the legacy data_types 'gpc0'
- and 'gpc1' on the same table. Using the 'gpc' array data_type, all 'gpc0'
- and 'gpc1' related fetches and actions will apply to the two first
- elements of this array.
+ Example: accept all sessions from white-listed hosts, reject too fast
+ sessions without counting them, and track accepted sessions.
+ This results in session rate being capped from abusive sources.
- - gpc_rate(<nb>,<period>) : Array of increment rates of General Purpose
- Counters over a period. Those elements are positive 32-bit integers which
- may be used for anything. Just like <gpc>, the count events, but instead
- of keeping a cumulative number, they maintain the rate at which the
- counter is incremented. Most of the time it will be used to measure the
- frequency of occurrence of certain events (e.g. requests to a specific
- URL). This array is limited to a maximum of 100 elements: gpt(100)
- allowing the storage of gpc0 to gpc99, to ensure that the build of a peer
- update message can fit into the buffer.
- The array cannot contain less than 1 element: use gpc(1) if you want to
- store only the counter gpc0.
- Users should take in consideration that a large amount of
- counters will increase the data size and the traffic load using peers
- protocol since all data/counters are pushed each time any of them is
- updated.
- This data_type will exclude the usage of the legacy data_types
- 'gpc0_rate' and 'gpc1_rate' on the same table. Using the 'gpc_rate'
- array data_type, all 'gpc0' and 'gpc1' related fetches and actions
- will apply to the two first elements of this array.
+ tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
+ tcp-request session reject if { src_sess_rate gt 10 }
+ tcp-request session track-sc0 src
- - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
- integer which may be used for anything. Most of the time it will be used
- to put a special tag on some entries, for instance to note that a
- specific behavior was detected and must be known for future matches.
+ Example: accept all sessions from white-listed hosts, count all other
+ sessions and reject too fast ones. This results in abusive ones
+ being blocked as long as they don't slow down.
- - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
- over a period. It is a positive 32-bit integer integer which may be used
- for anything. Just like <gpc0>, it counts events, but instead of keeping
- a cumulative number, it maintains the rate at which the counter is
- incremented. Most of the time it will be used to measure the frequency of
- occurrence of certain events (e.g. requests to a specific URL).
+ tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
+ tcp-request session track-sc0 src
+ tcp-request session reject if { sc0_sess_rate gt 10 }
- - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
- integer which may be used for anything. Most of the time it will be used
- to put a special tag on some entries, for instance to note that a
- specific behavior was detected and must be known for future matches.
+ See section 7 about ACL usage.
- - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
- over a period. It is a positive 32-bit integer integer which may be used
- for anything. Just like <gpc1>, it counts events, but instead of keeping
- a cumulative number, it maintains the rate at which the counter is
- incremented. Most of the time it will be used to measure the frequency of
- occurrence of certain events (e.g. requests to a specific URL).
+ See also : "tcp-request connection", "tcp-request content", "stick-table"
- - gpt(<nb>) : General Purpose Tags Array of <nb> elements. This is an array
- of positive 32-bit integers which may be used for anything.
- Most of the time they will be used to put a special tags on some entries,
- for instance to note that a specific behavior was detected and must be
- known for future matches. This array is limited to a maximum of 100
- elements: gpt(100) allowing the storage of gpt0 to gpt99, to ensure that
- the build of a peer update message can fit into the buffer.
- The array cannot contain less than 1 element: use gpt(1) if you want to
- to store only the tag gpt0.
- Users should take in consideration that a large amount of counters will
- increase the data size and the traffic load using peers protocol since
- all data/counters are pushed each time any of them is updated.
- This data_type will exclude the usage of the legacy data_type 'gpt0'
- on the same table. Using the 'gpt' array data_type, all 'gpt0' related
- fetches and actions will apply to the first element of this array.
+tcp-response content <action> [{if | unless} <condition>]
+ Perform an action on a session response depending on a layer 4-7 condition
+ May be used in sections : defaults | frontend | listen | backend
+ yes(!) | no | yes | yes
+ Arguments :
+ <action> defines the action to perform if the condition applies. See
+ below.
- - gpt0 : first General Purpose Tag. It is a positive 32-bit integer
- integer which may be used for anything. Most of the time it will be used
- to put a special tag on some entries, for instance to note that a
- specific behavior was detected and must be known for future matches
+ <condition> is a standard layer 4-7 ACL-based condition (see section 7).
- - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
- the absolute number of connections received from clients which matched
- this entry. It does not mean the connections were accepted, just that
- they were received.
+ Response contents can be analyzed at an early stage of response processing
+ called "TCP content inspection". During this stage, ACL-based rules are
+ evaluated every time the response contents are updated, until either a final
+ rule matches, or a TCP response inspection delay is set and expires with no
+ matching rule.
- - conn_cur : Current Connections. It is a positive 32-bit integer which
- stores the concurrent connection counts for the entry. It is incremented
- once an incoming connection matches the entry, and decremented once the
- connection leaves. That way it is possible to know at any time the exact
- number of concurrent connections for an entry.
+ Most often, these decisions will consider a protocol recognition or validity.
- - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
- integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- incoming connection rate over that period, in connections per period. The
- result is an integer which can be matched using ACLs.
+ Content-based rules are evaluated in their exact declaration order. If no
+ rule matches or if there is no rule, the default action is to accept the
+ contents. There is no specific limit to the number of rules which may be
+ inserted.
- - sess_cnt : Session Count. It is a positive 32-bit integer which counts
- the absolute number of sessions received from clients which matched this
- entry. A session is a connection that was accepted by the layer 4 rules.
+ The first keyword after "tcp-response content" in the syntax is the rule's
+ action, optionally followed by a varying number of arguments for the action.
+ The supported actions and their respective syntaxes are enumerated in
+ section 4.3 "Actions" (look for actions which tick "TCP RsCnt").
- - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
- integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- incoming session rate over that period, in sessions per period. The
- result is an integer which can be matched using ACLs.
+ This directive is only available from named defaults sections, not anonymous
+ ones. Rules defined in the defaults section are evaluated before ones in the
+ associated proxy section. To avoid ambiguities, in this case the same
+ defaults section cannot be used by proxies with the frontend capability and
+ by proxies with the backend capability. It means a listen section cannot use
+ a defaults section defining such rules.
- - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
- counts the absolute number of HTTP requests received from clients which
- matched this entry. It does not matter whether they are valid requests or
- not. Note that this is different from sessions when keep-alive is used on
- the client side.
+ Note that the "if/unless" condition is optional. If no condition is set on
+ the action, it is simply performed unconditionally. That can be useful for
+ for changing the default action to a reject.
- - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
- integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- HTTP request rate over that period, in requests per period. The result is
- an integer which can be matched using ACLs. It does not matter whether
- they are valid requests or not. Note that this is different from sessions
- when keep-alive is used on the client side.
+ Several types of actions are supported :
- - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
- counts the absolute number of HTTP requests errors induced by clients
- which matched this entry. Errors are counted on invalid and truncated
- requests, as well as on denied or tarpitted requests, and on failed
- authentications. If the server responds with 4xx, then the request is
- also counted as an error since it's an error triggered by the client
- (e.g. vulnerability scan).
+ It is perfectly possible to match layer 7 contents with "tcp-response
+ content" rules, but then it is important to ensure that a full response has
+ been buffered, otherwise no contents will match. In order to achieve this,
+ the best solution involves detecting the HTTP protocol during the inspection
+ period.
- - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
- integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- HTTP request error rate over that period, in requests per period (see
- http_err_cnt above for what is accounted as an error). The result is an
- integer which can be matched using ACLs.
+ See section 7 about ACL usage.
- - http_fail_cnt : HTTP Failure Count. It is a positive 32-bit integer which
- counts the absolute number of HTTP response failures induced by servers
- which matched this entry. Errors are counted on invalid and truncated
- responses, as well as any 5xx response other than 501 or 505. It aims at
- being used combined with path or URI to detect service failures.
+ See also : "tcp-request content", "tcp-response inspect-delay"
- - http_fail_rate(<period>) : frequency counter (takes 12 bytes). It takes
- an integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- HTTP response failure rate over that period, in requests per period (see
- http_fail_cnt above for what is accounted as a failure). The result is an
- integer which can be matched using ACLs.
+tcp-response inspect-delay <timeout>
+ Set the maximum allowed time to wait for a response during content inspection
+ May be used in sections : defaults | frontend | listen | backend
+ yes(!) | no | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- - bytes_in_cnt : client to server byte count. It is a positive 64-bit
- integer which counts the cumulative number of bytes received from clients
- which matched this entry. Headers are included in the count. This may be
- used to limit abuse of upload features on photo or video servers.
+ This directive is only available from named defaults sections, not anonymous
+ ones. Proxies inherit this value from their defaults section.
- - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
- integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- incoming bytes rate over that period, in bytes per period. It may be used
- to detect users which upload too much and too fast. Warning: with large
- uploads, it is possible that the amount of uploaded data will be counted
- once upon termination, thus causing spikes in the average transfer speed
- instead of having a smooth one. This may partially be smoothed with
- "option contstats" though this is not perfect yet. Use of byte_in_cnt is
- recommended for better fairness.
+ See also : "tcp-response content", "tcp-request inspect-delay".
- - bytes_out_cnt : server to client byte count. It is a positive 64-bit
- integer which counts the cumulative number of bytes sent to clients which
- matched this entry. Headers are included in the count. This may be used
- to limit abuse of bots sucking the whole site.
- - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
- an integer parameter <period> which indicates in milliseconds the length
- of the period over which the average is measured. It reports the average
- outgoing bytes rate over that period, in bytes per period. It may be used
- to detect users which download too much and too fast. Warning: with large
- transfers, it is possible that the amount of transferred data will be
- counted once upon termination, thus causing spikes in the average
- transfer speed instead of having a smooth one. This may partially be
- smoothed with "option contstats" though this is not perfect yet. Use of
- byte_out_cnt is recommended for better fairness.
+timeout check <timeout>
+ Set additional check timeout, but only after a connection has been already
+ established.
- There is only one stick-table per proxy. At the moment of writing this doc,
- it does not seem useful to have multiple tables per proxy. If this happens
- to be required, simply create a dummy backend with a stick-table in it and
- reference it.
+ May be used in sections: defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments:
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- It is important to understand that stickiness based on learning information
- has some limitations, including the fact that all learned associations are
- lost upon restart unless peers are properly configured to transfer such
- information upon restart (recommended). In general it can be good as a
- complement but not always as an exclusive stickiness.
+ If set, HAProxy uses min("timeout connect", "inter") as a connect timeout
+ for check and "timeout check" as an additional read timeout. The "min" is
+ used so that people running with *very* long "timeout connect" (e.g. those
+ who needed this due to the queue or tarpit) do not slow down their checks.
+ (Please also note that there is no valid reason to have such long connect
+ timeouts, because "timeout queue" and "timeout tarpit" can always be used to
+ avoid that).
- Last, memory requirements may be important when storing many data types.
- Indeed, storing all indicators above at once in each entry requires 116 bytes
- per entry, or 116 MB for a 1-million entries table. This is definitely not
- something that can be ignored.
+ If "timeout check" is not set HAProxy uses "inter" for complete check
+ timeout (connect + read) exactly like all <1.3.15 version.
- Example:
- # Keep track of counters of up to 1 million IP addresses over 5 minutes
- # and store a general purpose counter and the average connection rate
- # computed over a sliding window of 30 seconds.
- stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
+ In most cases check request is much simpler and faster to handle than normal
+ requests and people may want to kick out laggy servers so this timeout should
+ be smaller than "timeout server".
- See also : "stick match", "stick on", "stick store-request", section 2.5
- about time format and section 7 about ACLs.
+ This parameter is specific to backends, but can be specified once for all in
+ "defaults" sections. This is in fact one of the easiest solutions not to
+ forget about it.
+ See also: "timeout connect", "timeout queue", "timeout server",
+ "timeout tarpit".
-stick store-response <pattern> [table <table>] [{if | unless} <condition>]
- Define a response pattern used to create an entry in a stickiness table
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
+timeout client <timeout>
+ Set the maximum inactivity time on the client side.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
Arguments :
- <pattern> is a sample expression rule as described in section 7.3. It
- describes what elements of the response or connection will
- be analyzed, extracted and stored in the table once a
- server is selected.
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- <table> is an optional stickiness table name. If unspecified, the same
- backend's table is used. A stickiness table is declared using
- the "stick-table" statement.
+ The inactivity timeout applies when the client is expected to acknowledge or
+ send data. In HTTP mode, this timeout is particularly important to consider
+ during the first phase, when the client sends the request, and during the
+ response while it is reading data sent by the server. That said, for the
+ first phase, it is preferable to set the "timeout http-request" to better
+ protect HAProxy from Slowloris like attacks. The value is specified in
+ milliseconds by default, but can be in any other unit if the number is
+ suffixed by the unit, as specified at the top of this document. In TCP mode
+ (and to a lesser extent, in HTTP mode), it is highly recommended that the
+ client timeout remains equal to the server timeout in order to avoid complex
+ situations to debug. It is a good practice to cover one or several TCP packet
+ losses by specifying timeouts that are slightly above multiples of 3 seconds
+ (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
+ sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
+ which overrides "timeout client" and "timeout server" for tunnels, as well as
+ "timeout client-fin" for half-closed connections.
- <cond> is an optional storage condition. It makes it possible to store
- certain criteria only when some conditions are met (or not met).
- For instance, it could be used to store the SSL session ID only
- when the response is a SSL server hello.
+ This parameter is specific to frontends, but can be specified once for all in
+ "defaults" sections. This is in fact one of the easiest solutions not to
+ forget about it. An unspecified timeout results in an infinite timeout, which
+ is not recommended. Such a usage is accepted and works but reports a warning
+ during startup because it may result in accumulation of expired sessions in
+ the system if the system's timeouts are not configured either.
- Some protocols or applications require complex stickiness rules and cannot
- always simply rely on cookies nor hashing. The "stick store-response"
- statement describes a rule to decide what to extract from the response and
- when to do it, in order to store it into a stickiness table for further
- requests to match it using the "stick match" statement. Obviously the
- extracted part must make sense and have a chance to be matched in a further
- request. Storing an ID found in a header of a response makes sense.
- See section 7 for a complete list of possible patterns and transformation
- rules.
+ See also : "timeout server", "timeout tunnel", "timeout http-request".
- The table has to be declared using the "stick-table" statement. It must be of
- a type compatible with the pattern. By default it is the one which is present
- in the same backend. It is possible to share a table with other backends by
- referencing it using the "table" keyword. If another table is referenced,
- the server's ID inside the backends are used. By default, all server IDs
- start at 1 in each backend, so the server ordering is enough. But in case of
- doubt, it is highly recommended to force server IDs using their "id" setting.
- It is possible to restrict the conditions where a "stick store-response"
- statement will apply, using "if" or "unless" followed by a condition. This
- condition will be evaluated while parsing the response, so any criteria can
- be used. See section 7 for ACL based conditions.
+timeout client-fin <timeout>
+ Set the inactivity timeout on the client side for half-closed connections.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- There is no limit on the number of "stick store-response" statements, but
- there is a limit of 8 simultaneous stores per request or response. This
- makes it possible to store up to 8 criteria, all extracted from either the
- request or the response, regardless of the number of rules. Only the 8 first
- ones which match will be kept. Using this, it is possible to feed multiple
- tables at once in the hope to increase the chance to recognize a user on
- another protocol or access method. Using multiple store-response rules with
- the same table is possible and may be used to find the best criterion to rely
- on, by arranging the rules by decreasing preference order. Only the first
- extracted criterion for a given table will be stored. All subsequent store-
- response rules referencing the same table will be skipped and their ACLs will
- not be evaluated. However, even if a store-request rule references a table, a
- store-response rule may also use the same table. This means that each table
- may learn exactly one element from the request and one element from the
- response at once.
+ The inactivity timeout applies when the client is expected to acknowledge or
+ send data while one direction is already shut down. This timeout is different
+ from "timeout client" in that it only applies to connections which are closed
+ in one direction. This is particularly useful to avoid keeping connections in
+ FIN_WAIT state for too long when clients do not disconnect cleanly. This
+ problem is particularly common long connections such as RDP or WebSocket.
+ Note that this timeout can override "timeout tunnel" when a connection shuts
+ down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
+ frame was sent, often indicating an expectation that the connection quickly
+ ends.
- The table will contain the real server that processed the request.
+ This parameter is specific to frontends, but can be specified once for all in
+ "defaults" sections. By default it is not set, so half-closed connections
+ will use the other timeouts (timeout.client or timeout.tunnel).
- Example :
- # Learn SSL session ID from both request and response and create affinity.
- backend https
- mode tcp
- balance roundrobin
- # maximum SSL session ID length is 32 bytes.
- stick-table type binary len 32 size 30k expire 30m
+ See also : "timeout client", "timeout server-fin", and "timeout tunnel".
- acl clienthello req.ssl_hello_type 1
- acl serverhello rep.ssl_hello_type 2
- # use tcp content accepts to detects ssl client and server hello.
- tcp-request inspect-delay 5s
- tcp-request content accept if clienthello
+timeout client-hs <timeout>
+ Set the maximum time to wait for a client TLS handshake to complete. This is
+ usable both for TCP and QUIC connections.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- # no timeout on response inspect delay by default.
- tcp-response content accept if serverhello
+ If this handshake timeout is not set, this is the client timeout which is used
+ in place.
- # SSL session ID (SSLID) may be present on a client or server hello.
- # Its length is coded on 1 byte at offset 43 and its value starts
- # at offset 44.
- # Match and learn on request if client hello.
- stick on req.payload_lv(43,1) if clienthello
+timeout connect <timeout>
+ Set the maximum time to wait for a connection attempt to a server to succeed.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- # Learn on response if server hello.
- stick store-response resp.payload_lv(43,1) if serverhello
+ If the server is located on the same LAN as HAProxy, the connection should be
+ immediate (less than a few milliseconds). Anyway, it is a good practice to
+ cover one or several TCP packet losses by specifying timeouts that are
+ slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
+ connect timeout also presets both queue and tarpit timeouts to the same value
+ if these have not been specified.
- server s1 192.168.1.1:443
- server s2 192.168.1.1:443
+ This parameter is specific to backends, but can be specified once for all in
+ "defaults" sections. This is in fact one of the easiest solutions not to
+ forget about it. An unspecified timeout results in an infinite timeout, which
+ is not recommended. Such a usage is accepted and works but reports a warning
+ during startup because it may result in accumulation of failed sessions in
+ the system if the system's timeouts are not configured either.
- See also : "stick-table", "stick on", and section 7 about ACLs and pattern
- extraction.
+ See also: "timeout check", "timeout queue", "timeout server", "timeout tarpit".
-tcp-check comment <string>
- Defines a comment for the following the tcp-check rule, reported in logs if
- it fails.
+timeout http-keep-alive <timeout>
+ Set the maximum allowed time to wait for a new HTTP request to appear
May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
-
+ yes | yes | yes | yes
Arguments :
- <string> is the comment message to add in logs if the following tcp-check
- rule fails.
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- It only works for connect, send and expect rules. It is useful to make
- user-friendly error reporting.
+ By default, the time to wait for a new request in case of keep-alive is set
+ by "timeout http-request". However this is not always convenient because some
+ people want very short keep-alive timeouts in order to release connections
+ faster, and others prefer to have larger ones but still have short timeouts
+ once the request has started to present itself.
- See also : "option tcp-check", "tcp-check connect", "tcp-check send" and
- "tcp-check expect".
+ The "http-keep-alive" timeout covers these needs. It will define how long to
+ wait for a new HTTP request to start coming after a response was sent. Once
+ the first byte of request has been seen, the "http-request" timeout is used
+ to wait for the complete request to come. Note that empty lines prior to a
+ new request do not refresh the timeout and are not counted as a new request.
+ There is also another difference between the two timeouts : when a connection
+ expires during timeout http-keep-alive, no error is returned, the connection
+ just closes. If the connection expires in "http-request" while waiting for a
+ connection to complete, a HTTP 408 error is returned.
+
+ In general it is optimal to set this value to a few tens to hundreds of
+ milliseconds, to allow users to fetch all objects of a page at once but
+ without waiting for further clicks. Also, if set to a very small value (e.g.
+ 1 millisecond) it will probably only accept pipelined requests but not the
+ non-pipelined ones. It may be a nice trade-off for very large sites running
+ with tens to hundreds of thousands of clients.
+
+ If this parameter is not set, the "http-request" timeout applies, and if both
+ are not set, "timeout client" still applies at the lower level. It should be
+ set in the frontend to take effect, unless the frontend is in TCP mode, in
+ which case the HTTP backend's timeout will be used.
+
+ See also : "timeout http-request", "timeout client".
-tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
- [ssl] [sni <sni>] [alpn <alpn>] [linger]
- [proto <name>] [comment <msg>]
- Opens a new connection
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+timeout http-request <timeout>
+ Set the maximum allowed time to wait for a complete HTTP request
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
Arguments :
- comment <msg> defines a message to report if the rule evaluation fails.
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- default Use default options of the server line to do the health
- checks. The server options are used only if not redefined.
+ In order to offer DoS protection, it may be required to lower the maximum
+ accepted time to receive a complete HTTP request without affecting the client
+ timeout. This helps protecting against established connections on which
+ nothing is sent. The client timeout cannot offer a good protection against
+ this abuse because it is an inactivity timeout, which means that if the
+ attacker sends one character every now and then, the timeout will not
+ trigger. With the HTTP request timeout, no matter what speed the client
+ types, the request will be aborted if it does not complete in time. When the
+ timeout expires, an HTTP 408 response is sent to the client to inform it
+ about the problem, and the connection is closed. The logs will report
+ termination codes "cR". Some recent browsers are having problems with this
+ standard, well-documented behavior, so it might be needed to hide the 408
+ code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
+ more details in the explanations of the "cR" termination code in section 8.5.
- port <expr> if not set, check port or server port is used.
- It tells HAProxy where to open the connection to.
- <port> must be a valid TCP port source integer, from 1 to
- 65535 or an sample-fetch expression.
+ By default, this timeout only applies to the header part of the request,
+ and not to any data. As soon as the empty line is received, this timeout is
+ not used anymore. When combined with "option http-buffer-request", this
+ timeout also applies to the body of the request..
+ It is used again on keep-alive connections to wait for a second
+ request if "timeout http-keep-alive" is not set.
- addr <ip> defines the IP address to do the health check.
+ Generally it is enough to set it to a few seconds, as most clients send the
+ full request immediately upon connection. Add 3 or more seconds to cover TCP
+ retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
+ generally work on local networks as long as there are no packet losses. This
+ will prevent people from sending bare HTTP requests using telnet.
- send-proxy send a PROXY protocol string
+ If this parameter is not set, the client timeout still applies between each
+ chunk of the incoming request. It should be set in the frontend to take
+ effect, unless the frontend is in TCP mode, in which case the HTTP backend's
+ timeout will be used.
- via-socks4 enables outgoing health checks using upstream socks4 proxy.
+ See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
+ "timeout client", "option http-buffer-request".
- ssl opens a ciphered connection
- sni <sni> specifies the SNI to use to do health checks over SSL.
+timeout queue <timeout>
+ Set the maximum time to wait in the queue for a connection slot to be free
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- alpn <alpn> defines which protocols to advertise with ALPN. The protocol
- list consists in a comma-delimited list of protocol names,
- for instance: "http/1.1,http/1.0" (without quotes).
- If it is not set, the server ALPN is used.
+ When a server's maxconn is reached, connections are left pending in a queue
+ which may be server-specific or global to the backend. In order not to wait
+ indefinitely, a timeout is applied to requests pending in the queue. If the
+ timeout is reached, it is considered that the request will almost never be
+ served, so it is dropped and a 503 error is returned to the client.
- proto <name> forces the multiplexer's protocol to use for this connection.
- It must be a TCP mux protocol and it must be usable on the
- backend side. The list of available protocols is reported in
- haproxy -vv.
+ The "timeout queue" statement allows to fix the maximum time for a request to
+ be left pending in a queue. If unspecified, the same value as the backend's
+ connection timeout ("timeout connect") is used, for backwards compatibility
+ with older versions with no "timeout queue" parameter.
- linger cleanly close the connection instead of using a single RST.
+ See also : "timeout connect".
- When an application lies on more than a single TCP port or when HAProxy
- load-balance many services in a single backend, it makes sense to probe all
- the services individually before considering a server as operational.
- When there are no TCP port configured on the server line neither server port
- directive, then the 'tcp-check connect port <port>' must be the first step
- of the sequence.
+timeout server <timeout>
+ Set the maximum inactivity time on the server side.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
- the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
- do.
+ The inactivity timeout applies when the server is expected to acknowledge or
+ send data. In HTTP mode, this timeout is particularly important to consider
+ during the first phase of the server's response, when it has to send the
+ headers, as it directly represents the server's processing time for the
+ request. To find out what value to put there, it's often good to start with
+ what would be considered as unacceptable response times, then check the logs
+ to observe the response time distribution, and adjust the value accordingly.
- When a connect must start the ruleset, if may still be preceded by set-var,
- unset-var or comment rules.
+ The value is specified in milliseconds by default, but can be in any other
+ unit if the number is suffixed by the unit, as specified at the top of this
+ document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
+ recommended that the client timeout remains equal to the server timeout in
+ order to avoid complex situations to debug. Whatever the expected server
+ response times, it is a good practice to cover at least one or several TCP
+ packet losses by specifying timeouts that are slightly above multiples of 3
+ seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
+ with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
+ "timeout tunnel", which overrides "timeout client" and "timeout server" for
+ tunnels.
- Examples :
- # check HTTP and HTTPs services on a server.
- # first open port 80 thanks to server line port directive, then
- # tcp-check opens port 443, ciphered and run a request on it:
- option tcp-check
- tcp-check connect
- tcp-check send GET\ /\ HTTP/1.0\r\n
- tcp-check send Host:\ haproxy.1wt.eu\r\n
- tcp-check send \r\n
- tcp-check expect rstring (2..|3..)
- tcp-check connect port 443 ssl
- tcp-check send GET\ /\ HTTP/1.0\r\n
- tcp-check send Host:\ haproxy.1wt.eu\r\n
- tcp-check send \r\n
- tcp-check expect rstring (2..|3..)
- server www 10.0.0.1 check port 80
+ This parameter is specific to backends, but can be specified once for all in
+ "defaults" sections. This is in fact one of the easiest solutions not to
+ forget about it. An unspecified timeout results in an infinite timeout, which
+ is not recommended. Such a usage is accepted and works but reports a warning
+ during startup because it may result in accumulation of expired sessions in
+ the system if the system's timeouts are not configured either.
+
+ See also : "timeout client" and "timeout tunnel".
+
+
+timeout server-fin <timeout>
+ Set the inactivity timeout on the server side for half-closed connections.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- # check both POP and IMAP from a single server:
- option tcp-check
- tcp-check connect port 110 linger
- tcp-check expect string +OK\ POP3\ ready
- tcp-check connect port 143
- tcp-check expect string *\ OK\ IMAP4\ ready
- server mail 10.0.0.1 check
+ The inactivity timeout applies when the server is expected to acknowledge or
+ send data while one direction is already shut down. This timeout is different
+ from "timeout server" in that it only applies to connections which are closed
+ in one direction. This is particularly useful to avoid keeping connections in
+ FIN_WAIT state for too long when a remote server does not disconnect cleanly.
+ This problem is particularly common long connections such as RDP or WebSocket.
+ Note that this timeout can override "timeout tunnel" when a connection shuts
+ down in one direction. This setting was provided for completeness, but in most
+ situations, it should not be needed.
- See also : "option tcp-check", "tcp-check send", "tcp-check expect"
+ This parameter is specific to backends, but can be specified once for all in
+ "defaults" sections. By default it is not set, so half-closed connections
+ will use the other timeouts (timeout.server or timeout.tunnel).
+ See also : "timeout client-fin", "timeout server", and "timeout tunnel".
-tcp-check expect [min-recv <int>] [comment <msg>]
- [ok-status <st>] [error-status <st>] [tout-status <st>]
- [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
- [!] <match> <pattern>
- Specify data to be collected and analyzed during a generic health check
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+timeout tarpit <timeout>
+ Set the duration for which tarpitted connections will be maintained
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | yes
Arguments :
- comment <msg> defines a message to report if the rule evaluation fails.
+ <timeout> is the tarpit duration specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- min-recv is optional and can define the minimum amount of data required to
- evaluate the current expect rule. If the number of received bytes
- is under this limit, the check will wait for more data. This
- option can be used to resolve some ambiguous matching rules or to
- avoid executing costly regex matches on content known to be still
- incomplete. If an exact string (string or binary) is used, the
- minimum between the string length and this parameter is used.
- This parameter is ignored if it is set to -1. If the expect rule
- does not match, the check will wait for more data. If set to 0,
- the evaluation result is always conclusive.
+ When a connection is tarpitted using "http-request tarpit", it is maintained
+ open with no activity for a certain amount of time, then closed. "timeout
+ tarpit" defines how long it will be maintained open.
- <match> is a keyword indicating how to look for a specific pattern in the
- response. The keyword may be one of "string", "rstring", "binary" or
- "rbinary".
- The keyword may be preceded by an exclamation mark ("!") to negate
- the match. Spaces are allowed between the exclamation mark and the
- keyword. See below for more details on the supported keywords.
+ The value is specified in milliseconds by default, but can be in any other
+ unit if the number is suffixed by the unit, as specified at the top of this
+ document. If unspecified, the same value as the backend's connection timeout
+ ("timeout connect") is used, for backwards compatibility with older versions
+ with no "timeout tarpit" parameter.
- ok-status <st> is optional and can be used to set the check status if
- the expect rule is successfully evaluated and if it is
- the last rule in the tcp-check ruleset. "L7OK", "L7OKC",
- "L6OK" and "L4OK" are supported :
- - L7OK : check passed on layer 7
- - L7OKC : check conditionally passed on layer 7, set
- server to NOLB state.
- - L6OK : check passed on layer 6
- - L4OK : check passed on layer 4
- By default "L7OK" is used.
+ See also : "timeout connect".
- error-status <st> is optional and can be used to set the check status if
- an error occurred during the expect rule evaluation.
- "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are
- supported :
- - L7OKC : check conditionally passed on layer 7, set
- server to NOLB state.
- - L7RSP : layer 7 invalid response - protocol error
- - L7STS : layer 7 response error, for example HTTP 5xx
- - L6RSP : layer 6 invalid response - protocol error
- - L4CON : layer 1-4 connection problem
- By default "L7RSP" is used.
- tout-status <st> is optional and can be used to set the check status if
- a timeout occurred during the expect rule evaluation.
- "L7TOUT", "L6TOUT", and "L4TOUT" are supported :
- - L7TOUT : layer 7 (HTTP/SMTP) timeout
- - L6TOUT : layer 6 (SSL) timeout
- - L4TOUT : layer 1-4 timeout
- By default "L7TOUT" is used.
+timeout tunnel <timeout>
+ Set the maximum inactivity time on the client and server side for tunnels.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments :
+ <timeout> is the timeout value specified in milliseconds by default, but
+ can be in any other unit if the number is suffixed by the unit,
+ as explained at the top of this document.
- on-success <fmt> is optional and can be used to customize the
- informational message reported in logs if the expect
- rule is successfully evaluated and if it is the last rule
- in the tcp-check ruleset. <fmt> is a log-format string.
+ The tunnel timeout applies when a bidirectional connection is established
+ between a client and a server, and the connection remains inactive in both
+ directions. This timeout supersedes both the client and server timeouts once
+ the connection becomes a tunnel. In TCP, this timeout is used as soon as no
+ analyzer remains attached to either connection (e.g. tcp content rules are
+ accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
+ when switching to the WebSocket protocol, or forwarding a CONNECT request
+ to a proxy), or after the first response when no keepalive/close option is
+ specified.
- on-error <fmt> is optional and can be used to customize the
- informational message reported in logs if an error
- occurred during the expect rule evaluation. <fmt> is a
- log-format string.
+ Since this timeout is usually used in conjunction with long-lived connections,
+ it usually is a good idea to also set "timeout client-fin" to handle the
+ situation where a client suddenly disappears from the net and does not
+ acknowledge a close, or sends a shutdown and does not acknowledge pending
+ data anymore. This can happen in lossy networks where firewalls are present,
+ and is detected by the presence of large amounts of sessions in a FIN_WAIT
+ state.
- status-code <expr> is optional and can be used to set the check status code
- reported in logs, on success or on error. <expr> is a
- standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ The value is specified in milliseconds by default, but can be in any other
+ unit if the number is suffixed by the unit, as specified at the top of this
+ document. Whatever the expected normal idle time, it is a good practice to
+ cover at least one or several TCP packet losses by specifying timeouts that
+ are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
- <pattern> is the pattern to look for. It may be a string or a regular
- expression. If the pattern contains spaces, they must be escaped
- with the usual backslash ('\').
- If the match is set to binary, then the pattern must be passed as
- a series of hexadecimal digits in an even number. Each sequence of
- two digits will represent a byte. The hexadecimal digits may be
- used upper or lower case.
+ This parameter is specific to backends, but can be specified once for all in
+ "defaults" sections. This is in fact one of the easiest solutions not to
+ forget about it.
- The available matches are intentionally similar to their http-check cousins :
+ Example :
+ defaults http
+ option http-server-close
+ timeout connect 5s
+ timeout client 30s
+ timeout client-fin 30s
+ timeout server 30s
+ timeout tunnel 1h # timeout to use with WebSocket and CONNECT
- string <string> : test the exact string matches in the response buffer.
- A health check response will be considered valid if the
- response's buffer contains this exact string. If the
- "string" keyword is prefixed with "!", then the response
- will be considered invalid if the body contains this
- string. This can be used to look for a mandatory pattern
- in a protocol response, or to detect a failure when a
- specific error appears in a protocol banner.
+ See also : "timeout client", "timeout client-fin", "timeout server".
- rstring <regex> : test a regular expression on the response buffer.
- A health check response will be considered valid if the
- response's buffer matches this expression. If the
- "rstring" keyword is prefixed with "!", then the response
- will be considered invalid if the body matches the
- expression.
- string-lf <fmt> : test a log-format string match in the response's buffer.
- A health check response will be considered valid if the
- response's buffer contains the string resulting of the
- evaluation of <fmt>, which follows the log-format rules.
- If prefixed with "!", then the response will be
- considered invalid if the buffer contains the string.
+transparent (deprecated)
+ Enable client-side transparent proxying
+ May be used in sections : defaults | frontend | listen | backend
+ yes | no | yes | yes
+ Arguments : none
- binary <hexstring> : test the exact string in its hexadecimal form matches
- in the response buffer. A health check response will
- be considered valid if the response's buffer contains
- this exact hexadecimal string.
- Purpose is to match data on binary protocols.
+ This keyword was introduced in order to provide layer 7 persistence to layer
+ 3 load balancers. The idea is to use the OS's ability to redirect an incoming
+ connection for a remote address to a local process (here HAProxy), and let
+ this process know what address was initially requested. When this option is
+ used, sessions without cookies will be forwarded to the original destination
+ IP address of the incoming request (which should match that of another
+ equipment), while requests with cookies will still be forwarded to the
+ appropriate server.
- rbinary <regex> : test a regular expression on the response buffer, like
- "rstring". However, the response buffer is transformed
- into its hexadecimal form, including NUL-bytes. This
- allows using all regex engines to match any binary
- content. The hexadecimal transformation takes twice the
- size of the original response. As such, the expected
- pattern should work on at-most half the response buffer
- size.
+ The "transparent" keyword is deprecated, use "option transparent" instead.
- binary-lf <hexfmt> : test a log-format string in its hexadecimal form
- match in the response's buffer. A health check response
- will be considered valid if the response's buffer
- contains the hexadecimal string resulting of the
- evaluation of <fmt>, which follows the log-format
- rules. If prefixed with "!", then the response will be
- considered invalid if the buffer contains the
- hexadecimal string. The hexadecimal string is converted
- in a binary string before matching the response's
- buffer.
+ Note that contrary to a common belief, this option does NOT make HAProxy
+ present the client's IP to the server when establishing the connection.
- It is important to note that the responses will be limited to a certain size
- defined by the global "tune.bufsize" option, which defaults to 16384 bytes.
- Thus, too large responses may not contain the mandatory pattern when using
- "string", "rstring" or binary. If a large response is absolutely required, it
- is possible to change the default max size by setting the global variable.
- However, it is worth keeping in mind that parsing very large responses can
- waste some CPU cycles, especially when regular expressions are used, and that
- it is always better to focus the checks on smaller resources. Also, in its
- current state, the check will not find any string nor regex past a null
- character in the response. Similarly it is not possible to request matching
- the null character.
+ See also: "option transparent"
- Examples :
- # perform a POP check
- option tcp-check
- tcp-check expect string +OK\ POP3\ ready
+unique-id-format <string>
+ Generate a unique ID for each request.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
+ Arguments :
+ <string> is a log-format string.
- # perform an IMAP check
- option tcp-check
- tcp-check expect string *\ OK\ IMAP4\ ready
+ This keyword creates a ID for each request using the custom log format. A
+ unique ID is useful to trace a request passing through many components of
+ a complex infrastructure. The newly created ID may also be logged using the
+ %ID tag the log-format string.
- # look for the redis master server
- option tcp-check
- tcp-check send PING\r\n
- tcp-check expect string +PONG
- tcp-check send info\ replication\r\n
- tcp-check expect string role:master
- tcp-check send QUIT\r\n
- tcp-check expect string +OK
+ The format should be composed from elements that are guaranteed to be
+ unique when combined together. For instance, if multiple HAProxy instances
+ are involved, it might be important to include the node name. It is often
+ needed to log the incoming connection's source and destination addresses
+ and ports. Note that since multiple requests may be performed over the same
+ connection, including a request counter may help differentiate them.
+ Similarly, a timestamp may protect against a rollover of the counter.
+ Logging the process ID will avoid collisions after a service restart.
+ It is recommended to use hexadecimal notation for many fields since it
+ makes them more compact and saves space in logs.
- See also : "option tcp-check", "tcp-check connect", "tcp-check send",
- "tcp-check send-binary", "http-check expect", tune.bufsize
+ Example:
+ unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
-tcp-check send <data> [comment <msg>]
-tcp-check send-lf <fmt> [comment <msg>]
- Specify a string or a log-format string to be sent as a question during a
- generic health check
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+ will generate:
+
+ 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
+
+ See also: "unique-id-header"
+unique-id-header <name>
+ Add a unique ID header in the HTTP request.
+ May be used in sections : defaults | frontend | listen | backend
+ yes | yes | yes | no
Arguments :
- comment <msg> defines a message to report if the rule evaluation fails.
+ <name> is the name of the header.
- <data> is the string that will be sent during a generic health
- check session.
+ Add a unique-id header in the HTTP request sent to the server, using the
+ unique-id-format. It can't work if the unique-id-format doesn't exist.
- <fmt> is the log-format string that will be sent, once evaluated,
- during a generic health check session.
+ Example:
- Examples :
- # look for the redis master server
- option tcp-check
- tcp-check send info\ replication\r\n
- tcp-check expect string role:master
+ unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
+ unique-id-header X-Unique-ID
- See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
- "tcp-check send-binary", tune.bufsize
+ will generate:
+ X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
-tcp-check send-binary <hexstring> [comment <msg>]
-tcp-check send-binary-lf <hexfmt> [comment <msg>]
- Specify an hex digits string or an hex digits log-format string to be sent as
- a binary question during a raw tcp health check
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+ See also: "unique-id-format"
+use_backend <backend> [{if | unless} <condition>]
+ Switch to a specific backend if/unless an ACL-based condition is matched.
+ May be used in sections : defaults | frontend | listen | backend
+ no | yes | yes | no
Arguments :
- comment <msg> defines a message to report if the rule evaluation fails.
+ <backend> is the name of a valid backend or "listen" section, or a
+ "log-format" string resolving to a backend name.
- <hexstring> is the hexadecimal string that will be send, once converted
- to binary, during a generic health check session.
+ <condition> is a condition composed of ACLs, as described in section 7. If
+ it is omitted, the rule is unconditionally applied.
- <hexfmt> is the hexadecimal log-format string that will be send, once
- evaluated and converted to binary, during a generic health
- check session.
+ When doing content-switching, connections arrive on a frontend and are then
+ dispatched to various backends depending on a number of conditions. The
+ relation between the conditions and the backends is described with the
+ "use_backend" keyword. While it is normally used with HTTP processing, it can
+ also be used in pure TCP, either without content using stateless ACLs (e.g.
+ source address validation) or combined with a "tcp-request" rule to wait for
+ some payload.
- Examples :
- # redis check in binary
- option tcp-check
- tcp-check send-binary 50494e470d0a # PING\r\n
- tcp-check expect binary 2b504F4e47 # +PONG
+ There may be as many "use_backend" rules as desired. All of these rules are
+ evaluated in their declaration order, and the first one which matches will
+ assign the backend.
+
+ In the first form, the backend will be used if the condition is met. In the
+ second form, the backend will be used if the condition is not met. If no
+ condition is valid, the backend defined with "default_backend" will be used.
+ If no default backend is defined, either the servers in the same section are
+ used (in case of a "listen" section) or, in case of a frontend, no server is
+ used and a 503 service unavailable response is returned.
+ Note that it is possible to switch from a TCP frontend to an HTTP backend. In
+ this case, either the frontend has already checked that the protocol is HTTP,
+ and backend processing will immediately follow, or the backend will wait for
+ a complete HTTP request to get in. This feature is useful when a frontend
+ must decode several protocols on a unique port, one of them being HTTP.
- See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
- "tcp-check send", tune.bufsize
+ When <backend> is a simple name, it is resolved at configuration time, and an
+ error is reported if the specified backend does not exist. If <backend> is
+ a log-format string instead, no check may be done at configuration time, so
+ the backend name is resolved dynamically at run time. If the resulting
+ backend name does not correspond to any valid backend, no other rule is
+ evaluated, and the default_backend directive is applied instead. Note that
+ when using dynamic backend names, it is highly recommended to use a prefix
+ that no other backend uses in order to ensure that an unauthorized backend
+ cannot be forced from the request.
+ It is worth mentioning that "use_backend" rules with an explicit name are
+ used to detect the association between frontends and backends to compute the
+ backend's "fullconn" setting. This cannot be done for dynamic names.
-tcp-check set-var(<var-name>[,<cond>...]) <expr>
-tcp-check set-var-fmt(<var-name>[,<cond>...]) <fmt>
- This operation sets the content of a variable. The variable is declared inline.
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+ See also: "default_backend", "tcp-request", "fullconn", "log-format", and
+ section 7 about ACLs.
+use-fcgi-app <name>
+ Defines the FastCGI application to use for the backend.
+ May be used in sections : defaults | frontend | listen | backend
+ no | no | yes | yes
Arguments :
- <var-name> The name of the variable starts with an indication about its
- scope. The scopes allowed for tcp-check are:
- "proc" : the variable is shared with the whole process.
- "sess" : the variable is shared with the tcp-check session.
- "check": the variable is declared for the lifetime of the tcp-check.
- This prefix is followed by a name. The separator is a '.'.
- The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
- and '-'.
+ <name> is the name of the FastCGI application to use.
- <cond> A set of conditions that must all be true for the variable to
- actually be set (such as "ifnotempty", "ifgt" ...). See the
- set-var converter's description for a full list of possible
- conditions.
+ See section 10.1 about FastCGI application setup for details.
- <expr> Is a sample-fetch expression potentially followed by converters.
+use-server <server> if <condition>
+use-server <server> unless <condition>
+ Only use a specific server if/unless an ACL-based condition is matched.
+ May be used in sections : defaults | frontend | listen | backend
+ no | no | yes | yes
+ Arguments :
+ <server> is the name of a valid server in the same backend section
+ or a "log-format" string resolving to a server name.
- <fmt> This is the value expressed using log-format rules (see Custom
- Log Format in section 8.2.4).
+ <condition> is a condition composed of ACLs, as described in section 7.
- Examples :
- tcp-check set-var(check.port) int(1234)
- tcp-check set-var-fmt(check.name) "%H"
+ By default, connections which arrive to a backend are load-balanced across
+ the available servers according to the configured algorithm, unless a
+ persistence mechanism such as a cookie is used and found in the request.
+ Sometimes it is desirable to forward a particular request to a specific
+ server without having to declare a dedicated backend for this server. This
+ can be achieved using the "use-server" rules. These rules are evaluated after
+ the "redirect" rules and before evaluating cookies, and they have precedence
+ on them. There may be as many "use-server" rules as desired. All of these
+ rules are evaluated in their declaration order, and the first one which
+ matches will assign the server.
-tcp-check unset-var(<var-name>)
- Free a reference to a variable within its scope.
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
+ If a rule designates a server which is down, and "option persist" is not used
+ and no force-persist rule was validated, it is ignored and evaluation goes on
+ with the next rules until one matches.
- Arguments :
- <var-name> The name of the variable starts with an indication about its
- scope. The scopes allowed for tcp-check are:
- "proc" : the variable is shared with the whole process.
- "sess" : the variable is shared with the tcp-check session.
- "check": the variable is declared for the lifetime of the tcp-check.
- This prefix is followed by a name. The separator is a '.'.
- The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
- and '-'.
+ In the first form, the server will be used if the condition is met. In the
+ second form, the server will be used if the condition is not met. If no
+ condition is valid, the processing continues and the server will be assigned
+ according to other persistence mechanisms.
- Examples :
- tcp-check unset-var(check.port)
+ Note that even if a rule is matched, cookie processing is still performed but
+ does not assign the server. This allows prefixed cookies to have their prefix
+ stripped.
+ The "use-server" statement works both in HTTP and TCP mode. This makes it
+ suitable for use with content-based inspection. For instance, a server could
+ be selected in a farm according to the TLS SNI field when using protocols with
+ implicit TLS (also see "req.ssl_sni"). And if these servers have their weight
+ set to zero, they will not be used for other traffic.
-tcp-request connection <action> <options...> [ { if | unless } <condition> ]
- Perform an action on an incoming connection depending on a layer 4 condition
- May be used in sections : defaults | frontend | listen | backend
- yes(!) | yes | yes | no
- Arguments :
- <action> defines the action to perform if the condition applies. See
- below.
+ Example :
+ # intercept incoming TLS requests based on the SNI field
+ use-server www if { req.ssl_sni -i www.example.com }
+ server www 192.168.0.1:443 weight 0
+ use-server mail if { req.ssl_sni -i mail.example.com }
+ server mail 192.168.0.1:465 weight 0
+ use-server imap if { req.ssl_sni -i imap.example.com }
+ server imap 192.168.0.1:993 weight 0
+ # all the rest is forwarded to this server
+ server default 192.168.0.2:443 check
- <condition> is a standard layer4-only ACL-based condition (see section 7).
+ When <server> is a simple name, it is checked against existing servers in the
+ configuration and an error is reported if the specified server does not exist.
+ If it is a log-format, no check is performed when parsing the configuration,
+ and if we can't resolve a valid server name at runtime but the use-server rule
+ was conditioned by an ACL returning true, no other use-server rule is applied
+ and we fall back to load balancing.
- Immediately after acceptance of a new incoming connection, it is possible to
- evaluate some conditions to decide whether this connection must be accepted
- or dropped or have its counters tracked. Those conditions cannot make use of
- any data contents because the connection has not been read from yet, and the
- buffers are not yet allocated. This is used to selectively and very quickly
- accept or drop connections from various sources with a very low overhead. If
- some contents need to be inspected in order to take the decision, the
- "tcp-request content" statements must be used instead.
+ See also: "use_backend", section 5 about server and section 7 about ACLs.
- The "tcp-request connection" rules are evaluated in their exact declaration
- order. If no rule matches or if there is no rule, the default action is to
- accept the incoming connection. There is no specific limit to the number of
- rules which may be inserted. Any rule may optionally be followed by an
- ACL-based condition, in which case it will only be evaluated if the condition
- is true.
-
- The first keyword is the rule's action. Several types of actions are
- supported:
- - accept
- - expect-netscaler-cip layer4
- - expect-proxy layer4
- - reject
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - set-dst <expr>
- - set-dst-port <expr>
- - set-mark <mark>
- - set-src <expr>
- - set-src-port <expr>
- - set-tos <tos>
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - silent-drop [ rst-ttl <ttl> ]
- - track-sc0 <key> [table <table>]
- - track-sc1 <key> [table <table>]
- - track-sc2 <key> [table <table>]
- - unset-var(<var-name>)
-
- The supported actions are described below.
-
- There is no limit to the number of "tcp-request connection" statements per
- instance.
- This directive is only available from named defaults sections, not anonymous
- ones. Rules defined in the defaults section are evaluated before ones in the
- associated proxy section. To avoid ambiguities, in this case the same
- defaults section cannot be used by proxies with the frontend capability and
- by proxies with the backend capability. It means a listen section cannot use
- a defaults section defining such rules.
+4.3. Actions keywords matrix
+----------------------------
- Note that the "if/unless" condition is optional. If no condition is set on
- the action, it is simply performed unconditionally. That can be useful for
- "track-sc*" actions as well as for changing the default action to a reject.
+Several rule sets are evaluated at various stages of the request or response
+processing, and for each rule found in these rule sets, an action may be
+executed if the optional condition is met.
+
+A large number of actions are provided by default, they can modify contents,
+accept/block processing, change internal states etc. And it is possible to
+define new actions in Lua (in which case their names will always be prefixed
+with "lua.").
+
+While historically some actions did only exist in specific rule sets, nowadays
+many actions are usable with many rule sets. The listing in this section will
+indicate for which supported action where it may be used, by ticking the
+corresponding abbreviated entry names among the following rule sets:
+
+ - TCP RqCon: the action is valid for "tcp-request connection" rules
+ - TCP RqSes: the action is valid for "tcp-request session" rules
+ - TCP RqCnt: the action is valid for "tcp-request content" rules
+ - TCP RsCnt: the action is valid for "tcp-response content" rules
+ - HTTP Req: the action is valid for "http-request" rules
+ - HTTP Res: the action is valid for "http-response" rules
+ - HTTP Aft: the action is valid for "http-after-response" rules
+
+The same abbreviations are used in the reference section 4.4 below.
+
+
+ keyword TCP: RqCon RqSes RqCnt RsCnt HTTP: Req Res Aft
+----------------------+-----------+-----+-----+------+----------+---+----
+accept X X X X - - -
+add-acl - - - - X X -
+add-header - - - - X X X
+allow - - - - X X X
+attach-srv - X - - - - -
+auth - - - - X - -
+cache-store - - - - - X -
+cache-use - - - - X - -
+capture - - X - X X X
+close - - - X - - -
+del-acl - - - - X X -
+del-header - - - - X X X
+del-map - - - - X X X
+deny - - - - X X -
+disable-l7-retry - - - - X - -
+do-resolve - - X - X - -
+early-hint - - - - X - -
+expect-netscaler-cip X - - - - - -
+expect-proxy layer4 X - - - - - -
+normalize-uri - - - - X - -
+redirect - - - - X X -
+reject X X X X X - -
+replace-header - - - - X X X
+replace-path - - - - X - -
+replace-pathq - - - - X - -
+replace-uri - - - - X - -
+replace-value - - - - X X X
+return - - - - X X -
+sc-add-gpc X X X X X X X
+--keyword---------------TCP--RqCon-RqSes-RqCnt-RsCnt---HTTP--Req-Res-Aft-
+sc-inc-gpc X X X X X X X
+sc-inc-gpc0 X X X X X X X
+sc-inc-gpc1 X X X X X X X
+sc-set-gpt X X X X X X X
+sc-set-gpt0 X X X X X X X
+send-spoe-group - - X X X X -
+set-bandwidth-limit - - X X X X -
+set-dst <expr> X X X - X - -
+set-dst-port X X X - X - -
+set-header - - - - X X X
+set-log-level - - X X X X X
+set-map - - - - X X X
+set-mark X X X X X X -
+set-method - - - - X - -
+set-nice - - X X X X -
+set-path - - - - X - -
+set-pathq - - - - X - -
+set-priority-class - - X - X - -
+set-priority-offset - - X - X - -
+--keyword---------------TCP--RqCon-RqSes-RqCnt-RsCnt---HTTP--Req-Res-Aft-
+set-query - - - - X - -
+set-src X X X - X - -
+set-src-port X X X - X - -
+set-status - - - - - X X
+set-timeout - - - - X X -
+set-tos X X X X X X -
+set-uri - - - - X - -
+set-var X X X X X X X
+set-var-fmt X X X X X X X
+silent-drop X X X X X X -
+strict-mode - - - - X X X
+switch-mode - - X - - - -
+tarpit - - - - X - -
+track-sc1 X X X - X X -
+track-sc2 X X X - X X -
+unset-var X X X X X X X
+use-service - - X - X - -
+wait-for-body - - - - X X -
+wait-for-handshake - - - - X - -
+--keyword---------------TCP--RqCon-RqSes-RqCnt-RsCnt---HTTP--Req-Res-Aft-
+
+
+4.4. Alphabetically sorted actions reference
+--------------------------------------------
- Example: accept all connections from white-listed hosts, reject too fast
- connection without counting them, and track accepted connections.
- This results in connection rate being capped from abusive sources.
+This section provides a detailed description of each action and its usage,
+using the same ruleset terminology marking as described in section 4.3 above.
- tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
- tcp-request connection reject if { src_conn_rate gt 10 }
- tcp-request connection track-sc0 src
- Example: accept all connections from white-listed hosts, count all other
- connections and reject too fast ones. This results in abusive ones
- being blocked as long as they don't slow down.
+accept
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt | HTTP Req| Res| Aft
+ X | X | X | X | - | - | -
- tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
- tcp-request connection track-sc0 src
- tcp-request connection reject if { sc0_conn_rate gt 10 }
+ This stops the evaluation of the rules and lets the request or response pass
+ the check. This action is final, i.e. no further rules from the same rule set
+ are evaluated for the current section. There is no difference between this
+ and the "allow" action except that for historical compatibility, "accept" is
+ used for TCP rules and "allow" for HTTP rules. See also the "allow" action
+ below.
+
+
+add-acl(<file-name>) <key fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
+
+ This is used to add a new entry into an ACL. The ACL must be loaded from a
+ file (even a dummy empty file). The file name of the ACL to be updated is
+ passed between parentheses. It takes one argument: <key fmt>, which follows
+ log-format rules, to collect content of the new entry. It performs a lookup
+ in the ACL before insertion, to avoid duplicated (or more) values.
+ It is the equivalent of the "add acl" command from the stats socket, but can
+ be triggered by an HTTP request.
- Example: enable the PROXY protocol for traffic coming from all known proxies.
- tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
+add-header <name> <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- See section 7 about ACL usage.
+ This appends an HTTP header field whose name is specified in <name> and
+ whose value is defined by <fmt> which follows the log-format rules (see
+ Custom Log Format in section 8.2.4). This is particularly useful to pass
+ connection-specific information to the server (e.g. the client's SSL
+ certificate), or to combine several headers into one. This rule is not
+ final, so it is possible to add other similar rules. Note that header
+ addition is performed immediately, so one rule might reuse the resulting
+ header from a previous rule.
- See also : "tcp-request session", "tcp-request content", "stick-table"
-tcp-request connection accept [ { if | unless } <condition> ]
+allow
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- This is used to accept the connection. No further "tcp-request connection"
- rules are evaluated.
+ This stops the evaluation of the rules and lets the request pass the check.
+ This action is final, i.e. no further rules from the same rule set are
+ evaluated for the current section. There is no difference between this and
+ the "accept" action except that for historical compatibility, "accept" is
+ used for TCP rules and "allow" for HTTP rules. See also the "accept" action
+ above.
-tcp-request connection expect-netscaler-cip layer4
- [ { if | unless } <condition> ]
- This configures the client-facing connection to receive a NetScaler Client IP
- insertion protocol header before any byte is read from the socket. This is
- equivalent to having the "accept-netscaler-cip" keyword on the "bind" line,
- except that using the TCP rule allows the PROXY protocol to be accepted only
- for certain IP address ranges using an ACL. This is convenient when multiple
- layers of load balancers are passed through by traffic coming from public
- hosts.
+attach-srv <srv> [name <expr>]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | X | - | - | - | - | -
-tcp-request connection expect-proxy layer4 [ { if | unless } <condition> ]
+ This is used to intercept the connection after proper HTTP/2 establishment.
+ The connection is reversed to the backend side and inserted into the idle
+ pool of server <srv>. This may only be used with servers having an 'rhttp@'
+ address.
- This configures the client-facing connection to receive a PROXY protocol
- header before any byte is read from the socket. This is equivalent to having
- the "accept-proxy" keyword on the "bind" line, except that using the TCP rule
- allows the PROXY protocol to be accepted only for certain IP address ranges
- using an ACL. This is convenient when multiple layers of load balancers are
- passed through by traffic coming from public hosts.
+ An extra parameter <expr> can be specified. Its value is interpreted as a
+ sample expression to name the connection inside the server idle pool. When
+ routing an outgoing request through this server, this name will be matched
+ against the 'sni' parameter of the server line. Otherwise, the connection
+ will have no name and will only match requests without SNI.
-tcp-request connection reject [ { if | unless } <condition> ]
+ This rule is only valid for frontend in HTTP mode. Also all listeners must
+ not require a protocol different from HTTP/2.
- This is used to reject the connection. No further "tcp-request connection"
- rules are evaluated. Rejected connections do not even become a session, which
- is why they are accounted separately for in the stats, as "denied
- connections". They are not considered for the session rate-limit and are not
- logged either. The reason is that these rules should only be used to filter
- extremely high connection rates such as the ones encountered during a massive
- DDoS attack. Under these extreme conditions, the simple action of logging
- each event would make the system collapse and would considerably lower the
- filtering capacity. If logging is absolutely desired, then "tcp-request
- content" rules should be used instead, as "tcp-request session" rules will
- not log either.
-tcp-request connection sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+auth [realm <realm>]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- This action increments the General Purpose Counter according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-add-gpc" for
- a complete description.
+ This stops the evaluation of the rules and immediately responds with an
+ HTTP 401 or 407 error code to invite the user to present a valid user name
+ and password. No further "http-request" rules are evaluated. An optional
+ "realm" parameter is supported, it sets the authentication realm that is
+ returned with the response (typically the application's name).
-tcp-request connection sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
-tcp-request connection sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-tcp-request connection sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
+ The corresponding proxy's error message is used. It may be customized using
+ an "errorfile" or an "http-error" directive. For 401 responses, all
+ occurrences of the WWW-Authenticate header are removed and replaced by a new
+ one with a basic authentication challenge for realm "<realm>". For 407
+ responses, the same is done on the Proxy-Authenticate header. If the error
+ message must not be altered, consider to use "http-request return" rule
+ instead.
- These actions increment the General Purppose Counters according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-inc-gpc",
- "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete
- description.
+ Example:
+ acl auth_ok http_auth_group(L1) G1
+ http-request auth unless auth_ok
-tcp-request connection sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-tcp-request connection sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
- These actions set the 32-bit unsigned General Purpose Tags according to the
- sticky counter designated by <sc-id>. Please refer to "http-request
- sc-set-gpt" and "http-request sc-set-gpt0" for a complete description.
+cache-store <name>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | - | X | -
-tcp-request connection set-dst <expr> [ { if | unless } <condition> ]
-tcp-request connection set-dst-port <expr> [ { if | unless } <condition> ]
+ See section 6.2 about cache setup.
- These actions are used to set the destination IP/Port address to the value of
- specified expression. Please refer to "http-request set-dst" and
- "http-request set-dst-port" for a complete description.
-tcp-request connection set-mark <mark> [ { if | unless } <condition> ]
+cache-use <name>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- This action is used to set the Netfilter/IPFW MARK in all packets sent to the
- client to the value passed in <mark> on platforms which support it. Please
- refer to "http-request set-mark" for a complete description.
+ See section 6.2 about cache setup.
-tcp-request connection set-src <expr> [ { if | unless } <condition> ]
-tcp-request connection set-src-port <expr> [ { if | unless } <condition> ]
- These actions are used to set the source IP/Port address to the value of
- specified expression. Please refer to "http-request set-src" and
- "http-request set-src-port" for a complete description.
+capture <sample> [ len <length> | id <id> ]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | - | X | X | X
-tcp-request connection set-tos <tos> [ { if | unless } <condition> ]
+ This captures sample expression <sample> from the request or response buffer,
+ and converts it to a string of at most <len> characters. The resulting string
+ is stored into the next "capture" slot (either request or reponse), so it
+ will possibly appear next to some captured HTTP headers. It will then
+ automatically appear in the logs, and it will be possible to extract it using
+ sample fetch methods to feed it into headers or anything. The length should
+ be limited given that this size will be allocated for each capture during the
+ whole session life. Note that the length is only usable with "http-request"
+ rules. Please check section 7.3 (Fetching samples), "capture request header"
+ and "capture response header" for more information.
- This is used to set the TOS or DSCP field value of packets sent to the client
- to the value passed in <tos> on platforms which support this. Please refer to
- "http-request set-tos" for a complete description.
+ If the keyword "id" is used instead of "len", the action tries to store the
+ captured string in a previously declared capture slot. This is useful to run
+ captures in backends. The slot id can be declared by a previous directive
+ "http-request capture" or with the "declare capture" keyword.
-tcp-request connection set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-tcp-request connection set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
+ When using this action in a backend, please double check that the relevant
+ frontend(s) have the required capture slots otherwise, this rule will be
+ ignored at run time. This can't be detected at configuration parsing time due
+ to HAProxy's ability to dynamically resolve backend name at runtime.
- This is used to set the contents of a variable. The variable is declared
- inline. "tcp-request connection" can set variables in the "proc" and "sess"
- scopes. Please refer to "http-request set-var" and "http-request set-var-fmt"
- for a complete description.
-tcp-request connection silent-drop [ rst-ttl <ttl> ] [ { if | unless } <condition> ]
+close
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | X | - | - | -
- This stops the evaluation of the rules and makes the client-facing connection
- suddenly disappear using a system-dependent way that tries to prevent the
- client from being notified. Please refer to "http-request silent-drop" for a
- complete description.
+ This is used to immediately close the connection with the server. No further
+ "tcp-response content" rules are evaluated. The main purpose of this action
+ is to force a connection to be finished between a client and a server after
+ an exchange when the application protocol expects some long time outs to
+ elapse first. The goal is to eliminate idle connections which take
+ significant resources on servers with certain protocols.
-tcp-request connection track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
-tcp-request connection track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
-tcp-request connection track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
- This enables tracking of sticky counters from current connection. Please
- refer to "http-request track-sc0", "http-request track-sc1" and "http-request
- track-sc2" for a complete description.
+del-acl(<file-name>) <key fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
-tcp-request connection unset-var(<var-name>) [ { if | unless } <condition> ]
+ This is used to delete an entry from an ACL. The ACL must be loaded from a
+ file (even a dummy empty file). The file name of the ACL to be updated is
+ passed between parentheses. It takes one argument: <key fmt>, which follows
+ log-format rules, to collect content of the entry to delete.
+ It is the equivalent of the "del acl" command from the stats socket, but can
+ be triggered by an HTTP request or response.
- This is used to unset a variable. Please refer to "http-request set-var" for
- details about variables.
+del-header <name> [ -m <meth> ]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
-tcp-request content <action> [{if | unless} <condition>]
- Perform an action on a new session depending on a layer 4-7 condition
- May be used in sections : defaults | frontend | listen | backend
- yes(!) | yes | yes | yes
- Arguments :
- <action> defines the action to perform if the condition applies. See
- below.
+ This removes all HTTP header fields whose name is specified in <name>. <meth>
+ is the matching method, applied on the header name. Supported matching methods
+ are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub"
+ (substring match) and "reg" (regex match). If not specified, exact matching
+ method is used.
- <condition> is a standard layer 4-7 ACL-based condition (see section 7).
- A request's contents can be analyzed at an early stage of request processing
- called "TCP content inspection". During this stage, ACL-based rules are
- evaluated every time the request contents are updated, until either an
- "accept", a "reject" or a "switch-mode" rule matches, or the TCP request
- inspection delay expires with no matching rule.
+del-map(<file-name>) <key fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- The first difference between these rules and "tcp-request connection" rules
- is that "tcp-request content" rules can make use of contents to take a
- decision. Most often, these decisions will consider a protocol recognition or
- validity. The second difference is that content-based rules can be used in
- both frontends and backends. In case of HTTP keep-alive with the client, all
- tcp-request content rules are evaluated again, so HAProxy keeps a record of
- what sticky counters were assigned by a "tcp-request connection" versus a
- "tcp-request content" rule, and flushes all the content-related ones after
- processing an HTTP request, so that they may be evaluated again by the rules
- being evaluated again for the next request. This is of particular importance
- when the rule tracks some L7 information or when it is conditioned by an
- L7-based ACL, since tracking may change between requests.
+ This is used to delete an entry from a MAP. The MAP must be loaded from a
+ file (even a dummy empty file). The file name of the MAP to be updated is
+ passed between parentheses. It takes one argument: <key fmt>, which follows
+ log-format rules, to collect content of the entry to delete.
+ It takes one argument: "file name" It is the equivalent of the "del map"
+ command from the stats socket, but can be triggered by an HTTP request or
+ response.
- Content-based rules are evaluated in their exact declaration order. If no
- rule matches or if there is no rule, the default action is to accept the
- contents. There is no specific limit to the number of rules which may be
- inserted.
- The first keyword is the rule's action. Several types of actions are
- supported:
- - accept
- - capture <sample> len <length>
- - do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr>
- - reject
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - send-spoe-group <engine-name> <group-name>
- - set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
- - set-dst <expr>
- - set-dst-port <expr>
- - set-log-level <level>
- - set-mark <mark>
- - set-nice <nice>
- - set-priority-class <expr>
- - set-priority-offset <expr>
- - set-src <expr>
- - set-src-port <expr>
- - set-tos <tos>
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - silent-drop [ rst-ttl <ttl> ]
- - switch-mode http [ proto <name> ]
- - track-sc0 <key> [table <table>]
- - track-sc1 <key> [table <table>]
- - track-sc2 <key> [table <table>]
- - unset-var(<var-name>)
- - use-service <service-name>
-
- The supported actions are described below.
+deny [ { status | deny_status } <code> ] [ content-type <type> ]
+ [ { default-errorfiles | errorfile <file> | errorfiles <name> |
+ file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
+ [ hdr <name> <fmt> ]*
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
- While there is nothing mandatory about it, it is recommended to use the
- track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
- content" rules in the frontend, and track-sc2 for "tcp-request content"
- rules in the backend, because that makes the configuration more readable
- and easier to troubleshoot, but this is just a guideline and all counters
- may be used everywhere.
+ This stops the evaluation of the rules and immediately rejects the request or
+ response. By default an HTTP 403 error is returned for requests, and 502 for
+ responses, but the returned response may be customized using same syntax as
+ for the "return" action. Thus, see "return" below for details. For
+ compatibility purposes, when no argument is defined, or only "deny_status",
+ the argument "default-errorfiles" is implied. It means "deny [deny_status
+ <status>]" is an alias of "deny [status <status>] default-errorfiles". This
+ action is final, i.e. no further rules from the same rule set are evaluated
+ for the current section. See also the "return" action for the advanced
+ syntax.
- This directive is only available from named defaults sections, not anonymous
- ones. Rules defined in the defaults section are evaluated before ones in the
- associated proxy section. To avoid ambiguities, in this case the same
- defaults section cannot be used by proxies with the frontend capability and
- by proxies with the backend capability. It means a listen section cannot use
- a defaults section defining such rules.
- Note that the "if/unless" condition is optional. If no condition is set on
- the action, it is simply performed unconditionally. That can be useful for
- "track-sc*" actions as well as for changing the default action to a reject.
+disable-l7-retry
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- Note also that it is recommended to use a "tcp-request session" rule to track
- information that does *not* depend on Layer 7 contents, especially for HTTP
- frontends. Some HTTP processing are performed at the session level and may
- lead to an early rejection of the requests. Thus, the tracking at the content
- level may be disturbed in such case. A warning is emitted during startup to
- prevent, as far as possible, such unreliable usage.
+ This disables any attempt to retry the request if it fails for any other
+ reason than a connection failure. This can be useful for example to make
+ sure POST requests aren't retried on failure.
- It is perfectly possible to match layer 7 contents with "tcp-request content"
- rules from a TCP proxy, since HTTP-specific ACL matches are able to
- preliminarily parse the contents of a buffer before extracting the required
- data. If the buffered contents do not parse as a valid HTTP message, then the
- ACL does not match. The parser which is involved there is exactly the same
- as for all other HTTP processing, so there is no risk of parsing something
- differently. In an HTTP frontend or an HTTP backend, it is guaranteed that
- HTTP contents will always be immediately present when the rule is evaluated
- first because the HTTP parsing is performed in the early stages of the
- connection processing, at the session level. But for such proxies, using
- "http-request" rules is much more natural and recommended.
- Tracking layer7 information is also possible provided that the information
- are present when the rule is processed. The rule processing engine is able to
- wait until the inspect delay expires when the data to be tracked is not yet
- available.
+do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | - | X | - | -
- Example:
- tcp-request content use-service lua.deny if { src -f /etc/haproxy/blacklist.lst }
+ This action performs a DNS resolution of the output of <expr> and stores
+ the result in the variable <var>. It uses the DNS resolvers section
+ pointed by <resolvers>.
+ It is possible to choose a resolution preference using the optional
+ arguments 'ipv4' or 'ipv6'.
+ When performing the DNS resolution, the client side connection is on
+ pause waiting till the end of the resolution.
+ If an IP address can be found, it is stored into <var>. If any kind of
+ error occurs, then <var> is not set.
+ One can use this action to discover a server IP address at run time and
+ based on information found in the request (IE a Host header).
+ If this action is used to find the server's IP address (using the
+ "set-dst" action), then the server IP address in the backend must be set
+ to 0.0.0.0. The do-resolve action takes an host-only parameter, any port must
+ be removed from the string.
Example:
+ resolvers mydns
+ nameserver local 127.0.0.53:53
+ nameserver google 8.8.8.8:53
+ timeout retry 1s
+ hold valid 10s
+ hold nx 3s
+ hold other 3s
+ hold obsolete 0s
+ accepted_payload_size 8192
- tcp-request content set-var(sess.my_var) src
- tcp-request content set-var-fmt(sess.from) %[src]:%[src_port]
- tcp-request content unset-var(sess.my_var2)
-
- Example:
- # Accept HTTP requests containing a Host header saying "example.com"
- # and reject everything else. (Only works for HTTP/1 connections)
- acl is_host_com hdr(Host) -i example.com
- tcp-request inspect-delay 30s
- tcp-request content accept if is_host_com
- tcp-request content reject
+ frontend fe
+ bind 10.42.0.1:80
+ http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),host_only
+ http-request capture var(txn.myip) len 40
- # Accept HTTP requests containing a Host header saying "example.com"
- # and reject everything else. (works for HTTP/1 and HTTP/2 connections)
- acl is_host_com hdr(Host) -i example.com
- tcp-request inspect-delay 5s
- tcp-request switch-mode http if HTTP
- tcp-request reject # non-HTTP traffic is implicit here
- ...
- http-request reject unless is_host_com
+ # return 503 when the variable is not set,
+ # which mean DNS resolution error
+ use_backend b_503 unless { var(txn.myip) -m found }
- Example:
- # reject SMTP connection if client speaks first
- tcp-request inspect-delay 30s
- acl content_present req.len gt 0
- tcp-request content reject if content_present
+ default_backend be
- # Forward HTTPS connection only if client speaks
- tcp-request inspect-delay 30s
- acl content_present req.len gt 0
- tcp-request content accept if content_present
- tcp-request content reject
+ backend b_503
+ # dummy backend used to return 503.
+ # one can use the errorfile directive to send a nice
+ # 503 error page to end users
- Example:
- # Track the last IP(stick-table type string) from X-Forwarded-For
- tcp-request inspect-delay 10s
- tcp-request content track-sc0 hdr(x-forwarded-for,-1)
- # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
- tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
+ backend be
+ # rule to prevent HAProxy from reconnecting to services
+ # on the local network (forged DNS name used to scan the network)
+ http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 }
+ http-request set-dst var(txn.myip)
+ server clear 0.0.0.0:0
- Example:
- # track request counts per "base" (concatenation of Host+URL)
- tcp-request inspect-delay 10s
- tcp-request content track-sc0 base table req-rate
+ NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't
+ be used to scan the network or worst won't loop over itself...
- Example: track per-frontend and per-backend counters, block abusers at the
- frontend when the backend detects abuse(and marks gpc0).
- frontend http
- # Use General Purpose Counter 0 in SC0 as a global abuse counter
- # protecting all our sites
- stick-table type ip size 1m expire 5m store gpc0
- tcp-request connection track-sc0 src
- tcp-request connection reject if { sc0_get_gpc0 gt 0 }
- ...
- use_backend http_dynamic if { path_end .php }
+early-hint <name> <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- backend http_dynamic
- # if a source makes too fast requests to this dynamic site (tracked
- # by SC1), block it globally in the frontend.
- stick-table type ip size 1m expire 5m store http_req_rate(10s)
- acl click_too_fast sc1_http_req_rate gt 10
- acl mark_as_abuser sc0_inc_gpc0(http) gt 0
- tcp-request content track-sc1 src
- tcp-request content reject if click_too_fast mark_as_abuser
+ This is used to build an HTTP 103 Early Hints response prior to any other one.
+ This appends an HTTP header field to this response whose name is specified in
+ <name> and whose value is defined by <fmt> which follows the log-format rules
+ (see Custom Log Format in section 8.2.4). This is particularly useful to pass
+ to the client some Link headers to preload resources required to render the
+ HTML documents.
- See section 7 about ACL usage.
+ See RFC 8297 for more information.
- See also : "tcp-request connection", "tcp-request session",
- "tcp-request inspect-delay", and "http-request".
-tcp-request content accept [ { if | unless } <condition> ]
+expect-netscaler-cip layer4
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | - | - | - | - | - | -
- This is used to accept the connection. No further "tcp-request content"
- rules are evaluated for the current section.
+ This configures the client-facing connection to receive a NetScaler Client IP
+ insertion protocol header before any byte is read from the socket. This is
+ equivalent to having the "accept-netscaler-cip" keyword on the "bind" line,
+ except that using the TCP rule allows the PROXY protocol to be accepted only
+ for certain IP address ranges using an ACL. This is convenient when multiple
+ layers of load balancers are passed through by traffic coming from public
+ hosts.
-tcp-request content capture <sample> len <length>
- [ { if | unless } <condition> ]
- This captures sample expression <sample> from the request buffer, and
- converts it to a string of at most <len> characters. The resulting string is
- stored into the next request "capture" slot, so it will possibly appear next
- to some captured HTTP headers. It will then automatically appear in the logs,
- and it will be possible to extract it using sample fetch rules to feed it
- into headers or anything. The length should be limited given that this size
- will be allocated for each capture during the whole session life. Please
- check section 7.3 (Fetching samples) and "capture request header" for more
- information.
+expect-proxy layer4
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | - | - | - | - | - | -
-tcp-request content do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr>
+ This configures the client-facing connection to receive a PROXY protocol
+ header before any byte is read from the socket. This is equivalent to having
+ the "accept-proxy" keyword on the "bind" line, except that using the TCP rule
+ allows the PROXY protocol to be accepted only for certain IP address ranges
+ using an ACL. This is convenient when multiple layers of load balancers are
+ passed through by traffic coming from public hosts.
- This action performs a DNS resolution of the output of <expr> and stores the
- result in the variable <var>. Please refer to "http-request do-resolve" for a
- complete description.
-tcp-request content reject [ { if | unless } <condition> ]
+normalize-uri <normalizer>
+normalize-uri fragment-encode
+normalize-uri fragment-strip
+normalize-uri path-merge-slashes
+normalize-uri path-strip-dot
+normalize-uri path-strip-dotdot [ full ]
+normalize-uri percent-decode-unreserved [ strict ]
+normalize-uri percent-to-uppercase [ strict ]
+normalize-uri query-sort-by-name
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- This is used to reject the connection. No further "tcp-request content" rules
- are evaluated.
+ Performs normalization of the request's URI.
-tcp-request content sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ URI normalization in HAProxy 2.4 is currently available as an experimental
+ technical preview. As such, it requires the global directive
+ 'expose-experimental-directives' first to be able to invoke it. You should be
+ prepared that the behavior of normalizers might change to fix possible
+ issues, possibly breaking proper request processing in your infrastructure.
- This action increments the General Purpose Counter according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-add-gpc" for
- a complete description.
+ Each normalizer handles a single type of normalization to allow for a
+ fine-grained selection of the level of normalization that is appropriate for
+ the supported backend.
-tcp-request content sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
-tcp-request content sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-tcp-request content sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
+ As an example the "path-strip-dotdot" normalizer might be useful for a static
+ fileserver that directly maps the requested URI to the path within the local
+ filesystem. However it might break routing of an API that expects a specific
+ number of segments in the path.
- These actions increment the General Purppose Counters according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-inc-gpc",
- "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete
- description.
+ It is important to note that some normalizers might result in unsafe
+ transformations for broken URIs. It might also be possible that a combination
+ of normalizers that are safe by themselves results in unsafe transformations
+ when improperly combined.
-tcp-request content sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-tcp-request content sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ As an example the "percent-decode-unreserved" normalizer might result in
+ unexpected results when a broken URI includes bare percent characters. One
+ such a broken URI is "/%%36%36" which would be decoded to "/%66" which in
+ turn is equivalent to "/f". By specifying the "strict" option requests to
+ such a broken URI would safely be rejected.
- These actions set the 32-bit unsigned General Purpose Tags according to the
- sticky counter designated by <sc-id>. Please refer to "http-request
- sc-set-gpt" and "http-request sc-set-gpt0" for a complete description.
+ The following normalizers are available:
-tcp-request content send-spoe-group <engine-name> <group-name>
- [ { if | unless } <condition> ]
+ - fragment-encode: Encodes "#" as "%23".
- This action is is used to trigger sending of a group of SPOE messages. Please
- refer to "http-request send-spoe-group" for a complete description.
+ The "fragment-strip" normalizer should be preferred, unless it is known
+ that broken clients do not correctly encode '#' within the path component.
-tcp-request content set-bandwidth-limit <name> [limit { <expr> | <size> }]
- [period { <expr> | <time> }] [ { if | unless } <condition> ]
+ Example:
+ - /#foo -> /%23foo
- This action is used to enable the bandwidth limitation filter <name>, either
- on the upload or download direction depending on the filter type. Please
- refer to "http-request set-bandwidth-limit" for a complete description.
+ - fragment-strip: Removes the URI's "fragment" component.
-tcp-request content set-dst <expr> [ { if | unless } <condition> ]
-tcp-request content set-dst-port <expr> [ { if | unless } <condition> ]
+ According to RFC 3986#3.5 the "fragment" component of an URI should not
+ be sent, but handled by the User Agent after retrieving a resource.
- These actions are used to set the destination IP/Port address to the value of
- specified expression. Please refer to "http-request set-dst" and
- "http-request set-dst-port" for a complete description.
+ This normalizer should be applied first to ensure that the fragment is
+ not interpreted as part of the request's path component.
-tcp-request content set-log-level <level> [ { if | unless } <condition> ]
+ Example:
+ - /#foo -> /
- This action is used to set the log level of the current session. Please refer
- to "http-request set-log-level". for a complete description.
+ - path-strip-dot: Removes "/./" segments within the "path" component
+ (RFC 3986#6.2.2.3).
-tcp-request content set-mark <mark> [ { if | unless } <condition> ]
+ Segments including percent encoded dots ("%2E") will not be detected. Use
+ the "percent-decode-unreserved" normalizer first if this is undesired.
- This action is used to set the Netfilter/IPFW MARK in all packets sent to the
- client to the value passed in <mark> on platforms which support it. Please
- refer to "http-request set-mark" for a complete description.
+ Example:
+ - /. -> /
+ - /./bar/ -> /bar/
+ - /a/./a -> /a/a
+ - /.well-known/ -> /.well-known/ (no change)
-tcp-request content set-nice <nice> [ { if | unless } <condition> ]
+ - path-strip-dotdot: Normalizes "/../" segments within the "path" component
+ (RFC 3986#6.2.2.3).
- This sets the "nice" factor of the current request being processed. Please
- refer to "http-request set-nice" for a complete description.
+ This merges segments that attempt to access the parent directory with
+ their preceding segment.
-tcp-request content set-priority-class <expr> [ { if | unless } <condition> ]
+ Empty segments do not receive special treatment. Use the "merge-slashes"
+ normalizer first if this is undesired.
- This is used to set the queue priority class of the current request. Please
- refer to "http-request set-priority-class" for a complete description.
+ Segments including percent encoded dots ("%2E") will not be detected. Use
+ the "percent-decode-unreserved" normalizer first if this is undesired.
-tcp-request content set-priority-offset <expr> [ { if | unless } <condition> ]
+ Example:
+ - /foo/../ -> /
+ - /foo/../bar/ -> /bar/
+ - /foo/bar/../ -> /foo/
+ - /../bar/ -> /../bar/
+ - /bar/../../ -> /../
+ - /foo//../ -> /foo/
+ - /foo/%2E%2E/ -> /foo/%2E%2E/
- This is used to set the queue priority timestamp offset of the current
- request. Please refer to "http-request set-priority-offset" for a complete
- description.
+ If the "full" option is specified then "../" at the beginning will be
+ removed as well:
-tcp-request content set-src <expr> [ { if | unless } <condition> ]
-tcp-request content set-src-port <expr> [ { if | unless } <condition> ]
+ Example:
+ - /../bar/ -> /bar/
+ - /bar/../../ -> /
- These actions are used to set the source IP/Port address to the value of
- specified expression. Please refer to "http-request set-src" and
- "http-request set-src-port" for a complete description.
+ - path-merge-slashes: Merges adjacent slashes within the "path" component
+ into a single slash.
-tcp-request content set-tos <tos> [ { if | unless } <condition> ]
+ Example:
+ - // -> /
+ - /foo//bar -> /foo/bar
- This is used to set the TOS or DSCP field value of packets sent to the client
- to the value passed in <tos> on platforms which support this. Please refer to
- "http-request set-tos" for a complete description.
+ - percent-decode-unreserved: Decodes unreserved percent encoded characters to
+ their representation as a regular character (RFC 3986#6.2.2.2).
-tcp-request content set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-tcp-request content set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
+ The set of unreserved characters includes all letters, all digits, "-",
+ ".", "_", and "~".
- This is used to set the contents of a variable. The variable is declared
- inline. Please refer to "http-request set-var" and "http-request set-var-fmt"
- for a complete description.
+ Example:
+ - /%61dmin -> /admin
+ - /foo%3Fbar=baz -> /foo%3Fbar=baz (no change)
+ - /%%36%36 -> /%66 (unsafe)
+ - /%ZZ -> /%ZZ
-tcp-request content silent-drop [ rst-ttl <ttl> ] [ { if | unless } <condition> ]
+ If the "strict" option is specified then invalid sequences will result
+ in a HTTP 400 Bad Request being returned.
- This stops the evaluation of the rules and makes the client-facing connection
- suddenly disappear using a system-dependent way that tries to prevent the
- client from being notified. Please refer to "http-request silent-drop" for a
- complete description.
+ Example:
+ - /%%36%36 -> HTTP 400
+ - /%ZZ -> HTTP 400
-tcp-request content switch-mode http [ proto <name> ]
- [ { if | unless } <condition> ]
+ - percent-to-uppercase: Uppercases letters within percent-encoded sequences
+ (RFC 3986#6.2.2.1).
- This action is used to perform a connection upgrade. Only HTTP upgrades are
- supported for now. The protocol may optionally be specified. This action is
- only available for a proxy with the frontend capability. The connection
- upgrade is immediately performed, following "tcp-request content" rules are
- not evaluated. This upgrade method should be preferred to the implicit one
- consisting to rely on the backend mode. When used, it is possible to set HTTP
- directives in a frontend without any warning. These directives will be
- conditionally evaluated if the HTTP upgrade is performed. However, an HTTP
- backend must still be selected. It remains unsupported to route an HTTP
- connection (upgraded or not) to a TCP server.
+ Example:
+ - /%6f -> /%6F
+ - /%zz -> /%zz
- See section 4 about Proxies for more details on HTTP upgrades.
+ If the "strict" option is specified then invalid sequences will result
+ in a HTTP 400 Bad Request being returned.
-tcp-request content track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
-tcp-request content track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
-tcp-request content track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
+ Example:
+ - /%zz -> HTTP 400
- This enables tracking of sticky counters from current connection. Please
- refer to "http-request track-sc0", "http-request track-sc1" and "http-request
- track-sc2" for a complete description.
+ - query-sort-by-name: Sorts the query string parameters by parameter name.
+ Parameters are assumed to be delimited by '&'. Shorter names sort before
+ longer names and identical parameter names maintain their relative order.
-tcp-request content unset-var(<var-name>) [ { if | unless } <condition> ]
+ Example:
+ - /?c=3&a=1&b=2 -> /?a=1&b=2&c=3
+ - /?aaa=3&a=1&aa=2 -> /?a=1&aa=2&aaa=3
+ - /?a=3&b=4&a=1&b=5&a=2 -> /?a=3&a=1&a=2&b=4&b=5
- This is used to unset a variable. Please refer to "http-request set-var" for
- details about variables.
-tcp-request content use-service <service-name> [ { if | unless } <condition> ]
+redirect <rule>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
- This action is used to executes a TCP service which will reply to the request
- and stop the evaluation of the rules. This service may choose to reply by
- sending any valid response or it may immediately close the connection without
- sending anything. Outside natives services, it is possible to write your own
- services in Lua. No further "tcp-request content" rules are evaluated.
+ This performs an HTTP redirection based on a redirect rule. This is exactly
+ the same as the "redirect" statement except that it inserts a redirect rule
+ which is processed in the middle of other "http-request" or "http-response"
+ rules and that these rules use the "log-format" strings. For responses, only
+ the "location" type of redirect is permitted. In addition, when a redirect is
+ performed during a response, the transfer from the server to HAProxy is
+ interrupted so that no payload can be forwarded to the client. This may cause
+ some connections to be closed on HTTP/1. This action is final, i.e. no
+ further rules from the same rule set are evaluated for the current section.
+ See the "redirect" keyword for the rule's syntax.
-tcp-request inspect-delay <timeout>
- Set the maximum allowed time to wait for data during content inspection
- May be used in sections : defaults | frontend | listen | backend
- yes(!) | yes | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+reject
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | - | -
- People using HAProxy primarily as a TCP relay are often worried about the
- risk of passing any type of protocol to a server without any analysis. In
- order to be able to analyze the request contents, we must first withhold
- the data then analyze them. This statement simply enables withholding of
- data for at most the specified amount of time.
+ This stops the evaluation of the rules and immediately closes the connection
+ without sending any response. For HTTP rules, it acts similarly to the
+ "tcp-request content reject" rules. It can be useful to force an immediate
+ connection closure on HTTP/2 connections.
- TCP content inspection applies very early when a connection reaches a
- frontend, then very early when the connection is forwarded to a backend. This
- means that a connection may experience a first delay in the frontend and a
- second delay in the backend if both have tcp-request rules.
+ In "tcp-request connection" rules, rejected connections do not even become a
+ session, which is why they are accounted separately for in the stats, as
+ "denied connections". They are not considered for the session rate-limit and
+ are not logged either. The reason is that these rules should only be used to
+ filter extremely high connection rates such as the ones encountered during a
+ massive DDoS attack. Under these extreme conditions, the simple action of
+ logging each event would make the system collapse and would considerably
+ lower the filtering capacity. If logging is absolutely desired, then
+ "tcp-request content" rules should be used instead, as "tcp-request session"
+ rules will not log either.
- Note that when performing content inspection, HAProxy will evaluate the whole
- rules for every new chunk which gets in, taking into account the fact that
- those data are partial. If no rule matches before the aforementioned delay,
- a last check is performed upon expiration, this time considering that the
- contents are definitive. If no delay is set, HAProxy will not wait at all
- and will immediately apply a verdict based on the available information.
- Obviously this is unlikely to be very useful and might even be racy, so such
- setups are not recommended.
+ When used in "tcp-response content" rules, the server connection will be
+ closed and the response aborted. This is generally used to prevent sensitive
+ information from leaking, typically after inspecting contents in conjunction
+ with the "wait-for-body" action.
- Note the inspection delay is shortened if an connection error or shutdown is
- experienced or if the request buffer appears as full.
- As soon as a rule matches, the request is released and continues as usual. If
- the timeout is reached and no rule matches, the default policy will be to let
- it pass through unaffected.
+replace-header <name> <match-regex> <replace-fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- For most protocols, it is enough to set it to a few seconds, as most clients
- send the full request immediately upon connection. Add 3 or more seconds to
- cover TCP retransmits but that's all. For some protocols, it may make sense
- to use large values, for instance to ensure that the client never talks
- before the server (e.g. SMTP), or to wait for a client to talk before passing
- data to the server (e.g. SSL). Note that the client timeout must cover at
- least the inspection delay, otherwise it will expire first. If the client
- closes the connection or if the buffer is full, the delay immediately expires
- since the contents will not be able to change anymore.
+ This matches the value of all occurrences of header field <name> against
+ <match-regex>. Matching is performed case-sensitively. Matching values are
+ completely replaced by <replace-fmt>. Format characters are allowed in
+ <replace-fmt> and work like <fmt> arguments in "http-request add-header".
+ Standard back-references using the backslash ('\') followed by a number are
+ supported.
- This directive is only available from named defaults sections, not anonymous
- ones. Proxies inherit this value from their defaults section.
+ This action acts on whole header lines, regardless of the number of values
+ they may contain. Thus it is well-suited to process headers naturally
+ containing commas in their value, such as If-Modified-Since or Set-Cookie.
+ Headers that contain a comma-separated list of values, such as Accept, or
+ Cache-Control should be processed using the "replace-value" action instead.
+ See also the "replace-value" action.
- See also : "tcp-request content accept", "tcp-request content reject",
- "timeout client".
+ Example:
+ http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
+ # applied to:
+ Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
-tcp-request session <action> [{if | unless} <condition>]
- Perform an action on a validated session depending on a layer 5 condition
- May be used in sections : defaults | frontend | listen | backend
- yes(!) | yes | yes | no
- Arguments :
- <action> defines the action to perform if the condition applies. See
- below.
+ # outputs:
+ Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
- <condition> is a standard layer5-only ACL-based condition (see section 7).
+ # assuming the backend IP is 192.168.1.20
- Once a session is validated, (i.e. after all handshakes have been completed),
- it is possible to evaluate some conditions to decide whether this session
- must be accepted or dropped or have its counters tracked. Those conditions
- cannot make use of any data contents because no buffers are allocated yet and
- the processing cannot wait at this stage. The main use case is to copy some
- early information into variables (since variables are accessible in the
- session), or to keep track of some information collected after the handshake,
- such as SSL-level elements (SNI, ciphers, client cert's CN) or information
- from the PROXY protocol header (e.g. track a source forwarded this way). The
- extracted information can thus be copied to a variable or tracked using
- "track-sc" rules. Of course it is also possible to decide to accept/reject as
- with other rulesets. Most operations performed here could also be performed
- in "tcp-request content" rules, except that in HTTP these rules are evaluated
- for each new request, and that might not always be acceptable. For example a
- rule might increment a counter on each evaluation. It would also be possible
- that a country is resolved by geolocation from the source IP address,
- assigned to a session-wide variable, then the source address rewritten from
- an HTTP header for all requests. If some contents need to be inspected in
- order to take the decision, the "tcp-request content" statements must be used
- instead.
+ http-request replace-header User-Agent curl foo
- The "tcp-request session" rules are evaluated in their exact declaration
- order. If no rule matches or if there is no rule, the default action is to
- accept the incoming session. There is no specific limit to the number of
- rules which may be inserted.
+ # applied to:
+ User-Agent: curl/7.47.0
- The first keyword is the rule's action. Several types of actions are
- supported:
- - accept
- - attach-srv <srv> [name <expr>]
- - reject
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - set-dst <expr>
- - set-dst-port <expr>
- - set-mark <mark>
- - set-src <expr>
- - set-src-port <expr>
- - set-tos <tos>
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - silent-drop [ rst-ttl <ttl> ]
- - track-sc0 <key> [table <table>]
- - track-sc1 <key> [table <table>]
- - track-sc2 <key> [table <table>]
- - unset-var(<var-name>)
-
- The supported actions are described below.
+ # outputs:
+ User-Agent: foo
- This directive is only available from named defaults sections, not anonymous
- ones. Rules defined in the defaults section are evaluated before ones in the
- associated proxy section. To avoid ambiguities, in this case the same
- defaults section cannot be used by proxies with the frontend capability and
- by proxies with the backend capability. It means a listen section cannot use
- a defaults section defining such rules.
+ Example:
+ http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
- Note that the "if/unless" condition is optional. If no condition is set on
- the action, it is simply performed unconditionally. That can be useful for
- "track-sc*" actions as well as for changing the default action to a reject.
+ # applied to:
+ Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
+
+ # outputs:
+ Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
+
+ # assuming the backend IP is 192.168.1.20.
- Example: track the original source address by default, or the one advertised
- in the PROXY protocol header for connection coming from the local
- proxies. The first connection-level rule enables receipt of the
- PROXY protocol for these ones, the second rule tracks whatever
- address we decide to keep after optional decoding.
- tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
- tcp-request session track-sc0 src
+replace-path <match-regex> <replace-fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- Example: accept all sessions from white-listed hosts, reject too fast
- sessions without counting them, and track accepted sessions.
- This results in session rate being capped from abusive sources.
+ This works like "replace-header" except that it works on the request's path
+ component instead of a header. The path component starts at the first '/'
+ after an optional scheme+authority and ends before the question mark. Thus,
+ the replacement does not modify the scheme, the authority and the
+ query-string.
- tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
- tcp-request session reject if { src_sess_rate gt 10 }
- tcp-request session track-sc0 src
+ It is worth noting that regular expressions may be more expensive to evaluate
+ than certain ACLs, so rare replacements may benefit from a condition to avoid
+ performing the evaluation at all if it does not match.
- Example: accept all sessions from white-listed hosts, count all other
- sessions and reject too fast ones. This results in abusive ones
- being blocked as long as they don't slow down.
+ Example:
+ # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
+ http-request replace-path (.*) /foo\1
- tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
- tcp-request session track-sc0 src
- tcp-request session reject if { sc0_sess_rate gt 10 }
+ # strip /foo : turn /foo/bar?q=1 into /bar?q=1
+ http-request replace-path /foo/(.*) /\1
+ # or more efficient if only some requests match :
+ http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ }
- See section 7 about ACL usage.
- See also : "tcp-request connection", "tcp-request content", "stick-table"
+replace-pathq <match-regex> <replace-fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
-tcp-request session accept [ { if | unless } <condition> ]
+ This does the same as "http-request replace-path" except that the path
+ contains the query-string if any is present. Thus, the path and the
+ query-string are replaced.
- This is used to accept the connection. No further "tcp-request session"
- rules are evaluated.
+ Example:
+ # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 :
+ http-request replace-pathq ([^?]*)(\?(.*))? \1/foo\2
-tcp-request session attach-srv <srv> [name <expr>]
- This is used to intercept the connection after proper HTTP/2 establishment.
- The connection is reversed to the backend side and inserted into the idle
- pool of <srv> server. This may only be used with servers having an 'rhttp@'
- address.
+replace-uri <match-regex> <replace-fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- An extra parameter <expr> can be specified. Its value is interpreted as a
- sample expression to name the connection inside the server idle pool. When
- routing an outgoing request through this server, this name will be matched
- against the 'sni' parameter of the server line. Otherwise, the connection
- will have no name and will only match requests without SNI.
+ This works like "replace-header" except that it works on the request's URI part
+ instead of a header. The URI part may contain an optional scheme, authority or
+ query string. These are considered to be part of the value that is matched
+ against.
- This rule is only valid for frontend in HTTP mode. Also all listeners must
- not require a protocol different from HTTP/2.
+ It is worth noting that regular expressions may be more expensive to evaluate
+ than certain ACLs, so rare replacements may benefit from a condition to avoid
+ performing the evaluation at all if it does not match.
-tcp-request session reject [ { if | unless } <condition> ]
+ IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent
+ by browsers use the "origin form", which differs from the "absolute form" in
+ that they do not contain a scheme nor authority in the URI portion. Mostly
+ only requests sent to proxies, those forged by hand and some emitted by
+ certain applications use the absolute form. As such, "replace-uri" usually
+ works fine most of the time in HTTP/1.x with rules starting with a "/". But
+ with HTTP/2, clients are encouraged to send absolute URIs only, which look
+ like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri
+ rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need
+ to be adapted to optionally match a scheme and authority, or replace-path
+ should be used.
- This is used to reject the connection. No further "tcp-request session" rules
- are evaluated.
+ Example:
+ # rewrite all "http" absolute requests to "https":
+ http-request replace-uri ^http://(.*) https://\1
-tcp-request session sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
+ http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2
- This action increments the General Purpose Counter according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-add-gpc" for
- a complete description.
-tcp-request session sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
-tcp-request session sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-tcp-request session sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
+replace-value <name> <match-regex> <replace-fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- These actions increment the General Purppose Counters according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-inc-gpc",
- "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete
- description.
+ This works like "replace-header" except that it matches the regex against
+ every comma-delimited value of the header field <name> instead of the
+ entire header. This is suited for all headers which are allowed to carry
+ more than one value. An example could be the Accept request header, or
+ Cache-Control for requests or responses.
-tcp-request session sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-tcp-request session sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+ Example:
+ http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
- These actions set the 32-bit unsigned General Purpose Tags according to the
- sticky counter designated by <sc-id>. Please refer to "tcp-request connection
- sc-set-gpt" and "tcp-request connection sc-set-gpt0" for a complete
- description.
+ # applied to:
+ X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
-tcp-request session set-dst <expr> [ { if | unless } <condition> ]
-tcp-request session set-dst-port <expr> [ { if | unless } <condition> ]
+ # outputs:
+ X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
- These actions are used to set the destination IP/Port address to the value of
- specified expression. Please refer to "http-request set-dst" and
- "http-request set-dst-port" for a complete description.
+ Example:
+ http-after-response replace-value Cache-control ^public$ private
-tcp-request session set-mark <mark> [ { if | unless } <condition> ]
+ # applied to:
+ Cache-Control: max-age=3600, public
- This action is used to set the Netfilter/IPFW MARK in all packets sent to the
- client to the value passed in <mark> on platforms which support it. Please
- refer to "http-request set-mark" for a complete description.
+ # outputs:
+ Cache-Control: max-age=3600, private
-tcp-request session set-src <expr> [ { if | unless } <condition> ]
-tcp-request session set-src-port <expr> [ { if | unless } <condition> ]
- These actions are used to set the source IP/Port address to the value of
- specified expression. Please refer to "http-request set-src" and
- "http-request set-src-port" for a complete description.
+return [ status <code> ] [ content-type <type> ]
+ [ { default-errorfiles | errorfile <file> | errorfiles <name> |
+ file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
+ [ hdr <name> <fmt> ]*
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
-tcp-request session set-tos <tos> [ { if | unless } <condition> ]
+ This stops the evaluation of the rules and immediately returns a response. The
+ default status code used for the response is 200. It can be optionally
+ specified as an arguments to "status". The response content-type may also be
+ specified as an argument to "content-type". Finally the response itself may
+ be defined. It can be a full HTTP response specifying the errorfile to use,
+ or the response payload specifying the file or the string to use. These rules
+ are followed to create the response :
- This is used to set the TOS or DSCP field value of packets sent to the client
- to the value passed in <tos> on platforms which support this. Please refer to
- "http-request set-tos" for a complete description.
+ * If neither the errorfile nor the payload to use is defined, a dummy
+ response is returned. Only the "status" argument is considered. It can be
+ any code in the range [200, 599]. The "content-type" argument, if any, is
+ ignored.
-tcp-request session set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-tcp-request session set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
+ * If "default-errorfiles" argument is set, the proxy's errorfiles are
+ considered. If the "status" argument is defined, it must be one of the
+ status code handled by HAProxy (200, 400, 403, 404, 405, 408, 410, 413,
+ 425, 429, 500, 501, 502, 503, and 504). The "content-type" argument, if
+ any, is ignored.
- This is used to set the contents of a variable. The variable is declared
- inline. Please refer to "http-request set-var" and "http-request set-var-fmt"
- for a complete description.
+ * If a specific errorfile is defined, with an "errorfile" argument, the
+ corresponding file, containing a full HTTP response, is returned. Only the
+ "status" argument is considered. It must be one of the status code handled
+ by HAProxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 501,
+ 502, 503, and 504). The "content-type" argument, if any, is ignored.
-tcp-request session silent-drop [ rst-ttl <ttl> ] [ { if | unless } <condition> ]
+ * If an http-errors section is defined, with an "errorfiles" argument, the
+ corresponding file in the specified http-errors section, containing a full
+ HTTP response, is returned. Only the "status" argument is considered. It
+ must be one of the status code handled by HAProxy (200, 400, 403, 404, 405,
+ 408, 410, 413, 425, 429, 500, 501, 502, 503, and 504). The "content-type"
+ argument, if any, is ignored.
- This stops the evaluation of the rules and makes the client-facing connection
- suddenly disappear using a system-dependent way that tries to prevent the
- client from being notified. Please refer to "http-request silent-drop" for a
- complete description.
+ * If a "file" or a "lf-file" argument is specified, the file's content is
+ used as the response payload. If the file is not empty, its content-type
+ must be set as argument to "content-type". Otherwise, any "content-type"
+ argument is ignored. With a "lf-file" argument, the file's content is
+ evaluated as a log-format string. With a "file" argument, it is considered
+ as a raw content.
-tcp-request session track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
-tcp-request session track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
-tcp-request session track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
+ * If a "string" or "lf-string" argument is specified, the defined string is
+ used as the response payload. The content-type must always be set as
+ argument to "content-type". With a "lf-string" argument, the string is
+ evaluated as a log-format string. With a "string" argument, it is
+ considered as a raw string.
- This enables tracking of sticky counters from current connection. Please
- refer to "http-request track-sc0", "http-request track-sc1" and "http-request
- track-sc2" for a complete description.
+ When the response is not based on an errorfile, it is possible to append HTTP
+ header fields to the response using "hdr" arguments. Otherwise, all "hdr"
+ arguments are ignored. For each one, the header name is specified in <name>
+ and its value is defined by <fmt> which follows the log-format rules.
-tcp-request session unset-var(<var-name>) [ { if | unless } <condition> ]
+ Note that the generated response must be smaller than a buffer. And to avoid
+ any warning, when an errorfile or a raw file is loaded, the buffer space
+ reserved for the headers rewriting should also be free.
- This is used to unset a variable. Please refer to "http-request set-var" for
- details about variables.
+ This action is final, i.e. no further rules from the same rule set are
+ evaluated for the current section.
+ Example:
+ http-request return errorfile /etc/haproxy/errorfiles/200.http \
+ if { path /ping }
-tcp-response content <action> [{if | unless} <condition>]
- Perform an action on a session response depending on a layer 4-7 condition
- May be used in sections : defaults | frontend | listen | backend
- yes(!) | no | yes | yes
- Arguments :
- <action> defines the action to perform if the condition applies. See
- below.
+ http-request return content-type image/x-icon file /var/www/favicon.ico \
+ if { path /favicon.ico }
- <condition> is a standard layer 4-7 ACL-based condition (see section 7).
+ http-request return status 403 content-type text/plain \
+ lf-string "Access denied. IP %[src] is blacklisted." \
+ if { src -f /etc/haproxy/blacklist.lst }
- Response contents can be analyzed at an early stage of response processing
- called "TCP content inspection". During this stage, ACL-based rules are
- evaluated every time the response contents are updated, until either an
- "accept", "close" or a "reject" rule matches, or a TCP response inspection
- delay is set and expires with no matching rule.
- Most often, these decisions will consider a protocol recognition or validity.
+sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
- Content-based rules are evaluated in their exact declaration order. If no
- rule matches or if there is no rule, the default action is to accept the
- contents. There is no specific limit to the number of rules which may be
- inserted.
+ This action increments the General Purpose Counter at the index <idx> of the
+ array associated to the sticky counter designated by <sc-id> by the value of
+ either integer <int> or the integer evaluation of expression <expr>. Integers
+ and expressions are limited to unsigned 32-bit values. If an error occurs,
+ this action silently fails and the actions evaluation continues. <idx> is an
+ integer between 0 and 99 and <sc-id> is an integer between 0 and 2. It also
+ silently fails if the there is no GPC stored at this index. The entry in the
+ table is refreshed even if the value is zero. The 'gpc_rate' is automatically
+ adjusted to reflect the average growth rate of the gpc value.
- The first keyword is the rule's action. Several types of actions are
- supported:
- - accept
- - close
- - reject
- - sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- - sc-inc-gpc(<idx>,<sc-id>)
- - sc-inc-gpc0(<sc-id>)
- - sc-inc-gpc1(<sc-id>)
- - sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- - sc-set-gpt0(<sc-id>) { <int> | <expr> }
- - send-spoe-group <engine-name> <group-name>
- - set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
- - set-log-level <level>
- - set-mark <mark>
- - set-nice <nice>
- - set-tos <tos>
- - set-var(<var-name>[,<cond>...]) <expr>
- - set-var-fmt(<var-name>[,<cond>...]) <fmt>
- - silent-drop [ rst-ttl <ttl> ]
- - unset-var(<var-name>)
-
- The supported actions are described below.
+ This action applies only to the 'gpc' and 'gpc_rate' array data_types (and
+ not to the legacy 'gpc0', 'gpc1', 'gpc0_rate' nor 'gpc1_rate' data_types).
+ There is no equivalent function for legacy data types, but if the value is
+ always 1, please see 'sc-inc-gpc()', 'sc-inc-gpc0()' and 'sc-inc-gpc1()'.
+ There is no way to decrement the value either, but it is possible to store
+ exact values in a General Purpose Tag using 'sc-set-gpt()' instead.
- This directive is only available from named defaults sections, not anonymous
- ones. Rules defined in the defaults section are evaluated before ones in the
- associated proxy section. To avoid ambiguities, in this case the same
- defaults section cannot be used by proxies with the frontend capability and
- by proxies with the backend capability. It means a listen section cannot use
- a defaults section defining such rules.
+ The main use of this action is to count scores or total volumes (e.g.
+ estimated danger per source IP reported by the server or a WAF, total
+ uploaded bytes, etc).
- Note that the "if/unless" condition is optional. If no condition is set on
- the action, it is simply performed unconditionally. That can be useful for
- for changing the default action to a reject.
- Several types of actions are supported :
+sc-inc-gpc(<idx>,<sc-id>)
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
- It is perfectly possible to match layer 7 contents with "tcp-response
- content" rules, but then it is important to ensure that a full response has
- been buffered, otherwise no contents will match. In order to achieve this,
- the best solution involves detecting the HTTP protocol during the inspection
- period.
+ This actions increments the General Purpose Counter at the index <idx> of the
+ array associated to the sticky counter designated by <sc-id>. If an error
+ occurs, this action silently fails and the actions evaluation continues.
+ <idx> is an integer between 0 and 99 and <sc-id> is an integer between 0 and
+ 2. It also silently fails if the there is no GPC stored at this index. This
+ action applies only to the 'gpc' and 'gpc_rate' array data_types (and not to
+ the legacy 'gpc0', 'gpc1', 'gpc0_rate' nor 'gpc1_rate' data_types).
- See section 7 about ACL usage.
- See also : "tcp-request content", "tcp-response inspect-delay"
+sc-inc-gpc0(<sc-id>)
+sc-inc-gpc1(<sc-id>)
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
-tcp-response content accept [ { if | unless } <condition> ]
+ This actions increments the GPC0 or GPC1 counter according with the sticky
+ counter designated by <sc-id>. If an error occurs, this action silently fails
+ and the actions evaluation continues.
- This is used to accept the response. No further "tcp-response content" rules
- are evaluated.
-tcp-response content close [ { if | unless } <condition> ]
+sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
- This is used to immediately closes the connection with the server. No further
- "tcp-response content" rules are evaluated. The main purpose of this action
- is to force a connection to be finished between a client and a server after
- an exchange when the application protocol expects some long time outs to
- elapse first. The goal is to eliminate idle connections which take
- significant resources on servers with certain protocols.
+ This action sets the 32-bit unsigned GPT at the index <idx> of the array
+ associated to the sticky counter designated by <sc-id> at the value of
+ <int>/<expr>. The expected result is a boolean.
-tcp-response content reject [ { if | unless } <condition> ]
+ If an error occurs, this action silently fails and the actions evaluation
+ continues. <idx> is an integer between 0 and 99 and <sc-id> is an integer
+ between 0 and 2. It also silently fails if the there is no GPT stored
+ at this index.
- This is used to reject the response. No further "tcp-response content" rules
- are evaluated.
+ This action applies only to the 'gpt' array data_type (and not to the
+ legacy 'gpt0' data-type).
-tcp-response content sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
- This action increments the General Purpose Counter according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-add-gpc" for
- a complete description.
+sc-set-gpt0(<sc-id>) { <int> | <expr> }
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
-tcp-response content sc-inc-gpc(<idx>,<sc-id>) [ { if | unless } <condition> ]
-tcp-response content sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
-tcp-response content sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
+ This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
+ designated by <sc-id> and the value of <int>/<expr>. The expected result is a
+ boolean. If an error occurs, this action silently fails and the actions
+ evaluation continues. This action is an alias for "sc-set-gpt(0,<sc-id>)".
+ See also the "sc-set-gpt" action.
- These actions increment the General Purppose Counters according to the sticky
- counter designated by <sc-id>. Please refer to "http-request sc-inc-gpc",
- "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete
- description.
-tcp-response content sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
-tcp-resposne content sc-set-gpt0(<sc-id>) { <int> | <expr> }
- [ { if | unless } <condition> ]
+send-spoe-group <engine-name> <group-name>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | X | X | X | -
- These actions set the 32-bit unsigned General Purpose Tags according to the
- sticky counter designated by <sc-id>. Please refer to "http-request
- sc-set-gpt" and "http-request sc-set-gpt0" for a complete description.
+ This action is used to trigger sending of a group of SPOE messages. To do so,
+ the SPOE engine used to send messages must be defined, as well as the SPOE
+ group to send. Of course, the SPOE engine must refer to an existing SPOE
+ filter. If not engine name is provided on the SPOE filter line, the SPOE
+ agent name must be used.
-tcp-response content send-spoe-group <engine-name> <group-name>
- [ { if | unless } <condition> ]
+ Arguments:
+ <engine-name> The SPOE engine name.
- This action is is used to trigger sending of a group of SPOE messages. Please
- refer to "http-request send-spoe-group" for a complete description.
+ <group-name> The SPOE group name as specified in the engine
+ configuration.
-tcp-response content set-bandwidth-limit <name> [limit { <expr> | <size> }]
- [period { <expr> | <time> }] [ { if | unless } <condition> ]
+set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | X | X | X | -
This action is used to enable the bandwidth limitation filter <name>, either
- on the upload or download direction depending on the filter type. Please
- refer to "http-request set-bandwidth-limit" for a complete description.
+ on the upload or download direction depending on the filter type. Custom
+ limit and period may be defined, if and only if <name> references a
+ per-stream bandwidth limitation filter. When a set-bandwidth-limit rule is
+ executed, it first resets all settings of the filter to their defaults prior
+ to enabling it. As a consequence, if several "set-bandwidth-limit" actions
+ are executed for the same filter, only the last one is considered. Several
+ bandwidth limitation filters can be enabled on the same stream.
+
+ Note that this action cannot be used in a defaults section because bandwidth
+ limitation filters cannot be defined in defaults sections. In addition, only
+ the HTTP payload transfer is limited. The HTTP headers are not considered.
+
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters. The result is converted to an integer. It is
+ interpreted as a size in bytes for the "limit" parameter and as a
+ duration in milliseconds for the "period" parameter.
+
+ <size> Is a number. It follows the HAProxy size format and is expressed in
+ bytes.
+
+ <time> Is a number. It follows the HAProxy time format and is expressed in
+ milliseconds.
+
+ Example:
+ http-request set-bandwidth-limit global-limit
+ http-request set-bandwidth-limit my-limit limit 1m period 10s
-tcp-response content set-log-level <level> [ { if | unless } <condition> ]
+ See section 9.7 about bandwidth limitation filter setup.
- This action is used to set the log level of the current session. Please refer
- to "http-request set-log-level". for a complete description.
-tcp-response content set-mark <mark> [ { if | unless } <condition> ]
+set-dst <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | - | X | - | -
- This action is used to set the Netfilter/IPFW MARK in all packets sent to the
- client to the value passed in <mark> on platforms which support it. Please
- refer to "http-request set-mark" for a complete description.
+ This is used to set the destination IP address to the value of specified
+ expression. Useful when a proxy in front of HAProxy rewrites destination IP,
+ but provides the correct IP in a HTTP header; or you want to mask the IP for
+ privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
+ server address in the backend.
-tcp-response content set-nice <nice> [ { if | unless } <condition> ]
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters.
- This sets the "nice" factor of the current request being processed. Please
- refer to "http-request set-nice" for a complete description.
+ Example:
+ http-request set-dst hdr(x-dst)
+ http-request set-dst dst,ipmask(24)
-tcp-response content set-tos <tos> [ { if | unless } <condition> ]
+ When possible, set-dst preserves the original destination port as long as the
+ address family allows it, otherwise the destination port is set to 0.
- This is used to set the TOS or DSCP field value of packets sent to the client
- to the value passed in <tos> on platforms which support this. Please refer to
- "http-request set-tos" for a complete description.
-tcp-response content set-var(<var-name>[,<cond>...]) <expr> [ { if | unless } <condition> ]
-tcp-response content set-var-fmt(<var-name>[,<cond>...]) <fmt> [ { if | unless } <condition> ]
+set-dst-port <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | - | X | - | -
- This is used to set the contents of a variable. The variable is declared
- inline. Please refer to "http-request set-var" and "http-request set-var-fmt"
- for a complete description.
+ This is used to set the destination port address to the value of specified
+ expression. If you want to connect to the new address/port, use '0.0.0.0:0'
+ as a server address in the backend.
-tcp-response content silent-drop [ rst-ttl <ttl> ] [ { if | unless } <condition> ]
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch
+ followed by some converters.
- This stops the evaluation of the rules and makes the client-facing connection
- suddenly disappear using a system-dependent way that tries to prevent the
- client from being notified. Please refer to "http-request silent-drop" for a
- complete description.
+ Example:
+ http-request set-dst-port hdr(x-port)
+ http-request set-dst-port int(4000)
-tcp-response content unset-var(<var-name>) [ { if | unless } <condition> ]
+ When possible, set-dst-port preserves the original destination address as
+ long as the address family supports a port, otherwise it forces the
+ destination address to IPv4 "0.0.0.0" before rewriting the port.
- This is used to unset a variable. Please refer to "http-request set-var" for
- details about variables.
+set-header <name> <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
-tcp-response inspect-delay <timeout>
- Set the maximum allowed time to wait for a response during content inspection
- May be used in sections : defaults | frontend | listen | backend
- yes(!) | no | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+ This does the same as the "add-header" action except that the header is first
+ removed if it existed. This is useful when passing security information to
+ the server, where the header must not be manipulated by external users, or to
+ force certain response headers such as "Server" to hide external information.
+ Note that the new value is computed before the removal so it is possible to
+ concatenate a value to an existing header.
- This directive is only available from named defaults sections, not anonymous
- ones. Proxies inherit this value from their defaults section.
+ Example:
+ http-request set-header X-Haproxy-Current-Date %T
+ http-request set-header X-SSL %[ssl_fc]
+ http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
+ http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
+ http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
+ http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
+ http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
+ http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
+ http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
- See also : "tcp-response content", "tcp-request inspect-delay".
+set-log-level <level>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | X | X | X | X
-timeout check <timeout>
- Set additional check timeout, but only after a connection has been already
- established.
+ This is used to change the log level of the current request when a certain
+ condition is met. Valid levels are the 8 syslog levels (see the "log"
+ keyword) plus the special level "silent" which disables logging for this
+ request. This rule is not final so the last matching rule wins. This rule
+ can be useful to disable health checks coming from another equipment.
- May be used in sections: defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments:
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
- If set, HAProxy uses min("timeout connect", "inter") as a connect timeout
- for check and "timeout check" as an additional read timeout. The "min" is
- used so that people running with *very* long "timeout connect" (e.g. those
- who needed this due to the queue or tarpit) do not slow down their checks.
- (Please also note that there is no valid reason to have such long connect
- timeouts, because "timeout queue" and "timeout tarpit" can always be used to
- avoid that).
+set-map(<file-name>) <key fmt> <value fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- If "timeout check" is not set HAProxy uses "inter" for complete check
- timeout (connect + read) exactly like all <1.3.15 version.
+ This is used to add a new entry into a map. The map must be loaded from a
+ file (even a dummy empty file). The file name of the map to be updated is
+ passed between parentheses. It takes 2 arguments: <key fmt>, which follows
+ log-format rules, used to collect map key, and <value fmt>, which follows
+ log-format rules, used to collect content for the new entry.
+ It performs a lookup in the map before insertion, to avoid duplicated (or
+ more) values. It is the equivalent of the "set map" command from the
+ stats socket, but can be triggered by an HTTP request.
- In most cases check request is much simpler and faster to handle than normal
- requests and people may want to kick out laggy servers so this timeout should
- be smaller than "timeout server".
- This parameter is specific to backends, but can be specified once for all in
- "defaults" sections. This is in fact one of the easiest solutions not to
- forget about it.
+set-mark <mark>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | -
- See also: "timeout connect", "timeout queue", "timeout server",
- "timeout tarpit".
+ This is used to set the Netfilter/IPFW MARK on all packets sent to the client
+ to the value passed in <mark> on platforms which support it. This value is an
+ unsigned 32 bit value which can be matched by netfilter/ipfw and by the
+ routing table or monitoring the packets through DTrace. It can be expressed
+ both in decimal or hexadecimal format (prefixed by "0x").
+ This can be useful to force certain packets to take a different route (for
+ example a cheaper network path for bulk downloads). This works on Linux
+ kernels 2.6.32 and above and requires admin privileges, as well on FreeBSD
+ and OpenBSD.
-timeout client <timeout>
- Set the maximum inactivity time on the client side.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+set-method <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- The inactivity timeout applies when the client is expected to acknowledge or
- send data. In HTTP mode, this timeout is particularly important to consider
- during the first phase, when the client sends the request, and during the
- response while it is reading data sent by the server. That said, for the
- first phase, it is preferable to set the "timeout http-request" to better
- protect HAProxy from Slowloris like attacks. The value is specified in
- milliseconds by default, but can be in any other unit if the number is
- suffixed by the unit, as specified at the top of this document. In TCP mode
- (and to a lesser extent, in HTTP mode), it is highly recommended that the
- client timeout remains equal to the server timeout in order to avoid complex
- situations to debug. It is a good practice to cover one or several TCP packet
- losses by specifying timeouts that are slightly above multiples of 3 seconds
- (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
- sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
- which overrides "timeout client" and "timeout server" for tunnels, as well as
- "timeout client-fin" for half-closed connections.
+ This rewrites the request method with the result of the evaluation of format
+ string <fmt>. There should be very few valid reasons for having to do so as
+ this is more likely to break something than to fix it.
- This parameter is specific to frontends, but can be specified once for all in
- "defaults" sections. This is in fact one of the easiest solutions not to
- forget about it. An unspecified timeout results in an infinite timeout, which
- is not recommended. Such a usage is accepted and works but reports a warning
- during startup because it may result in accumulation of expired sessions in
- the system if the system's timeouts are not configured either.
- See also : "timeout server", "timeout tunnel", "timeout http-request".
+set-nice <nice>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | X | X | X | -
+ This sets the "nice" factor of the current request/response being processed.
+ It only has effect against the other requests being processed at the same
+ time. The default value is 0, unless altered by the "nice" setting on the
+ "bind" line. The accepted range is -1024..1024. The higher the value, the
+ nicest the request will be. Lower values will make the request more important
+ than other ones. This can be useful to improve the speed of some requests, or
+ lower the priority of non-important requests. Using this setting without
+ prior experimentation can cause some major slowdown.
-timeout client-fin <timeout>
- Set the inactivity timeout on the client side for half-closed connections.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
- The inactivity timeout applies when the client is expected to acknowledge or
- send data while one direction is already shut down. This timeout is different
- from "timeout client" in that it only applies to connections which are closed
- in one direction. This is particularly useful to avoid keeping connections in
- FIN_WAIT state for too long when clients do not disconnect cleanly. This
- problem is particularly common long connections such as RDP or WebSocket.
- Note that this timeout can override "timeout tunnel" when a connection shuts
- down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
- frame was sent, often indicating an expectation that the connection quickly
- ends.
+set-path <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- This parameter is specific to frontends, but can be specified once for all in
- "defaults" sections. By default it is not set, so half-closed connections
- will use the other timeouts (timeout.client or timeout.tunnel).
+ This rewrites the request path with the result of the evaluation of format
+ string <fmt>. The query string, if any, is left intact. If a scheme and
+ authority is found before the path, they are left intact as well. If the
+ request doesn't have a path ("*"), this one is replaced with the format.
+ This can be used to prepend a directory component in front of a path for
+ example. See also "http-request set-query" and "http-request set-uri".
- See also : "timeout client", "timeout server-fin", and "timeout tunnel".
+ Example :
+ # prepend the host name before the path
+ http-request set-path /%[hdr(host)]%[path]
-timeout client-hs <timeout>
- Set the maximum time to wait for a client TLS handshake to complete. This is
- usable both for TCP and QUIC connections.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+set-pathq <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- If this handshake timeout is not set, this is the client timeout which is used
- in place.
+ This does the same as "http-request set-path" except that the query-string is
+ also rewritten. It may be used to remove the query-string, including the
+ question mark (it is not possible using "http-request set-query").
-timeout connect <timeout>
- Set the maximum time to wait for a connection attempt to a server to succeed.
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+set-priority-class <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | - | X | - | -
- If the server is located on the same LAN as HAProxy, the connection should be
- immediate (less than a few milliseconds). Anyway, it is a good practice to
- cover one or several TCP packet losses by specifying timeouts that are
- slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
- connect timeout also presets both queue and tarpit timeouts to the same value
- if these have not been specified.
+ This is used to set the queue priority class of the current request.
+ The value must be a sample expression which converts to an integer in the
+ range -2047..2047. Results outside this range will be truncated.
+ The priority class determines the order in which queued requests are
+ processed. Lower values have higher priority.
- This parameter is specific to backends, but can be specified once for all in
- "defaults" sections. This is in fact one of the easiest solutions not to
- forget about it. An unspecified timeout results in an infinite timeout, which
- is not recommended. Such a usage is accepted and works but reports a warning
- during startup because it may result in accumulation of failed sessions in
- the system if the system's timeouts are not configured either.
- See also: "timeout check", "timeout queue", "timeout server", "timeout tarpit".
+set-priority-offset <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | - | X | - | -
+ This is used to set the queue priority timestamp offset of the current
+ request. The value must be a sample expression which converts to an integer
+ in the range -524287..524287. Results outside this range will be truncated.
+ When a request is queued, it is ordered first by the priority class, then by
+ the current timestamp adjusted by the given offset in milliseconds. Lower
+ values have higher priority.
+ Note that the resulting timestamp is is only tracked with enough precision
+ for 524,287ms (8m44s287ms). If the request is queued long enough to where the
+ adjusted timestamp exceeds this value, it will be misidentified as highest
+ priority. Thus it is important to set "timeout queue" to a value, where when
+ combined with the offset, does not exceed this limit.
-timeout http-keep-alive <timeout>
- Set the maximum allowed time to wait for a new HTTP request to appear
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
- By default, the time to wait for a new request in case of keep-alive is set
- by "timeout http-request". However this is not always convenient because some
- people want very short keep-alive timeouts in order to release connections
- faster, and others prefer to have larger ones but still have short timeouts
- once the request has started to present itself.
+set-query <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- The "http-keep-alive" timeout covers these needs. It will define how long to
- wait for a new HTTP request to start coming after a response was sent. Once
- the first byte of request has been seen, the "http-request" timeout is used
- to wait for the complete request to come. Note that empty lines prior to a
- new request do not refresh the timeout and are not counted as a new request.
+ This rewrites the request's query string which appears after the first
+ question mark ("?") with the result of the evaluation of format string <fmt>.
+ The part prior to the question mark is left intact. If the request doesn't
+ contain a question mark and the new value is not empty, then one is added at
+ the end of the URI, followed by the new value. If a question mark was
+ present, it will never be removed even if the value is empty. This can be
+ used to add or remove parameters from the query string.
- There is also another difference between the two timeouts : when a connection
- expires during timeout http-keep-alive, no error is returned, the connection
- just closes. If the connection expires in "http-request" while waiting for a
- connection to complete, a HTTP 408 error is returned.
+ See also "http-request set-query" and "http-request set-uri".
- In general it is optimal to set this value to a few tens to hundreds of
- milliseconds, to allow users to fetch all objects of a page at once but
- without waiting for further clicks. Also, if set to a very small value (e.g.
- 1 millisecond) it will probably only accept pipelined requests but not the
- non-pipelined ones. It may be a nice trade-off for very large sites running
- with tens to hundreds of thousands of clients.
+ Example:
+ # replace "%3D" with "=" in the query string
+ http-request set-query %[query,regsub(%3D,=,g)]
- If this parameter is not set, the "http-request" timeout applies, and if both
- are not set, "timeout client" still applies at the lower level. It should be
- set in the frontend to take effect, unless the frontend is in TCP mode, in
- which case the HTTP backend's timeout will be used.
- See also : "timeout http-request", "timeout client".
+set-src <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | - | X | - | -
+ This is used to set the source IP address to the value of specified
+ expression. Useful when a proxy in front of HAProxy rewrites source IP, but
+ provides the correct IP in a HTTP header; or you want to mask source IP for
+ privacy. All subsequent calls to "src" fetch will return this value
+ (see example).
-timeout http-request <timeout>
- Set the maximum allowed time to wait for a complete HTTP request
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters.
- In order to offer DoS protection, it may be required to lower the maximum
- accepted time to receive a complete HTTP request without affecting the client
- timeout. This helps protecting against established connections on which
- nothing is sent. The client timeout cannot offer a good protection against
- this abuse because it is an inactivity timeout, which means that if the
- attacker sends one character every now and then, the timeout will not
- trigger. With the HTTP request timeout, no matter what speed the client
- types, the request will be aborted if it does not complete in time. When the
- timeout expires, an HTTP 408 response is sent to the client to inform it
- about the problem, and the connection is closed. The logs will report
- termination codes "cR". Some recent browsers are having problems with this
- standard, well-documented behavior, so it might be needed to hide the 408
- code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
- more details in the explanations of the "cR" termination code in section 8.5.
+ See also "option forwardfor".
- By default, this timeout only applies to the header part of the request,
- and not to any data. As soon as the empty line is received, this timeout is
- not used anymore. When combined with "option http-buffer-request", this
- timeout also applies to the body of the request..
- It is used again on keep-alive connections to wait for a second
- request if "timeout http-keep-alive" is not set.
+ Example:
+ http-request set-src hdr(x-forwarded-for)
+ http-request set-src src,ipmask(24)
- Generally it is enough to set it to a few seconds, as most clients send the
- full request immediately upon connection. Add 3 or more seconds to cover TCP
- retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
- generally work on local networks as long as there are no packet losses. This
- will prevent people from sending bare HTTP requests using telnet.
+ # After the masking this will track connections
+ # based on the IP address with the last byte zeroed out.
+ http-request track-sc0 src
- If this parameter is not set, the client timeout still applies between each
- chunk of the incoming request. It should be set in the frontend to take
- effect, unless the frontend is in TCP mode, in which case the HTTP backend's
- timeout will be used.
+ When possible, set-src preserves the original source port as long as the
+ address family allows it, otherwise the source port is set to 0.
- See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
- "timeout client", "option http-buffer-request".
+set-src-port <expr>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | - | X | - | -
-timeout queue <timeout>
- Set the maximum time to wait in the queue for a connection slot to be free
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+ This is used to set the source port address to the value of specified
+ expression.
- When a server's maxconn is reached, connections are left pending in a queue
- which may be server-specific or global to the backend. In order not to wait
- indefinitely, a timeout is applied to requests pending in the queue. If the
- timeout is reached, it is considered that the request will almost never be
- served, so it is dropped and a 503 error is returned to the client.
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters.
- The "timeout queue" statement allows to fix the maximum time for a request to
- be left pending in a queue. If unspecified, the same value as the backend's
- connection timeout ("timeout connect") is used, for backwards compatibility
- with older versions with no "timeout queue" parameter.
+ Example:
+ http-request set-src-port hdr(x-port)
+ http-request set-src-port int(4000)
- See also : "timeout connect".
+ When possible, set-src-port preserves the original source address as long as
+ the address family supports a port, otherwise it forces the source address to
+ IPv4 "0.0.0.0" before rewriting the port.
-timeout server <timeout>
- Set the maximum inactivity time on the server side.
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+set-status <status> [reason <str>]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | - | X | X
- The inactivity timeout applies when the server is expected to acknowledge or
- send data. In HTTP mode, this timeout is particularly important to consider
- during the first phase of the server's response, when it has to send the
- headers, as it directly represents the server's processing time for the
- request. To find out what value to put there, it's often good to start with
- what would be considered as unacceptable response times, then check the logs
- to observe the response time distribution, and adjust the value accordingly.
+ This replaces the response status code with <status> which must be an integer
+ between 100 and 999. Optionally, a custom reason text can be provided defined
+ by <str>, or the default reason for the specified code will be used as a
+ fallback. Note that the reason string only exists in HTTP/1.x and is ignored
+ by other versions of the protocol.
- The value is specified in milliseconds by default, but can be in any other
- unit if the number is suffixed by the unit, as specified at the top of this
- document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
- recommended that the client timeout remains equal to the server timeout in
- order to avoid complex situations to debug. Whatever the expected server
- response times, it is a good practice to cover at least one or several TCP
- packet losses by specifying timeouts that are slightly above multiples of 3
- seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
- with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
- "timeout tunnel", which overrides "timeout client" and "timeout server" for
- tunnels.
+ Example:
+ # return "431 Request Header Fields Too Large"
+ http-response set-status 431
+ # return "503 Slow Down", custom reason
+ http-response set-status 503 reason "Slow Down".
- This parameter is specific to backends, but can be specified once for all in
- "defaults" sections. This is in fact one of the easiest solutions not to
- forget about it. An unspecified timeout results in an infinite timeout, which
- is not recommended. Such a usage is accepted and works but reports a warning
- during startup because it may result in accumulation of expired sessions in
- the system if the system's timeouts are not configured either.
- See also : "timeout client" and "timeout tunnel".
+set-timeout { client | server | tunnel } { <timeout> | <expr> }
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
+ This action overrides the specified "client", "server" or "tunnel" timeout
+ for the current stream only. The timeout can be specified in milliseconds or
+ with any other unit if the number is suffixed by the unit as explained at the
+ top of this document. It is also possible to write an expression which must
+ return a number interpreted as a timeout in milliseconds.
-timeout server-fin <timeout>
- Set the inactivity timeout on the server side for half-closed connections.
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+ Note that the server/tunnel timeouts are only relevant on the backend side
+ and thus this rule is only available for the proxies with backend
+ capabilities. Likewise, client timeout is only relevant for frontend side.
+ Also the timeout value must be non-null to obtain the expected results.
- The inactivity timeout applies when the server is expected to acknowledge or
- send data while one direction is already shut down. This timeout is different
- from "timeout server" in that it only applies to connections which are closed
- in one direction. This is particularly useful to avoid keeping connections in
- FIN_WAIT state for too long when a remote server does not disconnect cleanly.
- This problem is particularly common long connections such as RDP or WebSocket.
- Note that this timeout can override "timeout tunnel" when a connection shuts
- down in one direction. This setting was provided for completeness, but in most
- situations, it should not be needed.
+ Example:
+ http-request set-timeout tunnel 5s
+ http-request set-timeout server req.hdr(host),map_int(host.lst)
- This parameter is specific to backends, but can be specified once for all in
- "defaults" sections. By default it is not set, so half-closed connections
- will use the other timeouts (timeout.server or timeout.tunnel).
+ Example:
+ http-response set-timeout tunnel 5s
+ http-response set-timeout server res.hdr(X-Refresh-Seconds),mul(1000)
- See also : "timeout client-fin", "timeout server", and "timeout tunnel".
+set-tos <tos>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | -
-timeout tarpit <timeout>
- Set the duration for which tarpitted connections will be maintained
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | yes
- Arguments :
- <timeout> is the tarpit duration specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
+ This is used to set the TOS or DSCP field value of packets sent to the client
+ to the value passed in <tos> on platforms which support this. This value
+ represents the whole 8 bits of the IP TOS field, and can be expressed both in
+ decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
+ bits are used in DSCP or TOS, and the two lower bits are always 0. This can
+ be used to adjust some routing behavior on border routers based on some
+ information from the request.
- When a connection is tarpitted using "http-request tarpit", it is maintained
- open with no activity for a certain amount of time, then closed. "timeout
- tarpit" defines how long it will be maintained open.
+ See RFC 2474, 2597, 3260 and 4594 for more information.
- The value is specified in milliseconds by default, but can be in any other
- unit if the number is suffixed by the unit, as specified at the top of this
- document. If unspecified, the same value as the backend's connection timeout
- ("timeout connect") is used, for backwards compatibility with older versions
- with no "timeout tarpit" parameter.
- See also : "timeout connect".
+set-uri <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
+ This rewrites the request URI with the result of the evaluation of format
+ string <fmt>. The scheme, authority, path and query string are all replaced
+ at once. This can be used to rewrite hosts in front of proxies, or to perform
+ complex modifications to the URI such as moving parts between the path and
+ the query string. If an absolute URI is set, it will be sent as is to
+ HTTP/1.1 servers. If it is not the desired behavior, the host, the path
+ and/or the query string should be set separately.
+ See also "http-request set-path" and "http-request set-query".
-timeout tunnel <timeout>
- Set the maximum inactivity time on the client and server side for tunnels.
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments :
- <timeout> is the timeout value specified in milliseconds by default, but
- can be in any other unit if the number is suffixed by the unit,
- as explained at the top of this document.
- The tunnel timeout applies when a bidirectional connection is established
- between a client and a server, and the connection remains inactive in both
- directions. This timeout supersedes both the client and server timeouts once
- the connection becomes a tunnel. In TCP, this timeout is used as soon as no
- analyzer remains attached to either connection (e.g. tcp content rules are
- accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
- when switching to the WebSocket protocol, or forwarding a CONNECT request
- to a proxy), or after the first response when no keepalive/close option is
- specified.
+set-var(<var-name>[,<cond>...]) <expr>
+set-var-fmt(<var-name>[,<cond>...]) <fmt>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
- Since this timeout is usually used in conjunction with long-lived connections,
- it usually is a good idea to also set "timeout client-fin" to handle the
- situation where a client suddenly disappears from the net and does not
- acknowledge a close, or sends a shutdown and does not acknowledge pending
- data anymore. This can happen in lossy networks where firewalls are present,
- and is detected by the presence of large amounts of sessions in a FIN_WAIT
- state.
+ This is used to set the contents of a variable. The variable is declared
+ inline.
- The value is specified in milliseconds by default, but can be in any other
- unit if the number is suffixed by the unit, as specified at the top of this
- document. Whatever the expected normal idle time, it is a good practice to
- cover at least one or several TCP packet losses by specifying timeouts that
- are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
+ Arguments:
+ <var-name> The name of the variable starts with an indication about its
+ scope. The scopes allowed are:
+ "proc" : the variable is shared with the whole process
+ "sess" : the variable is shared with the whole session
+ "txn" : the variable is shared with the transaction
+ (request and response)
+ "req" : the variable is shared only during request
+ processing
+ "res" : the variable is shared only during response
+ processing
+ This prefix is followed by a name. The separator is a '.'.
+ The name may only contain characters 'a-z', 'A-Z', '0-9'
+ and '_'.
- This parameter is specific to backends, but can be specified once for all in
- "defaults" sections. This is in fact one of the easiest solutions not to
- forget about it.
+ <cond> A set of conditions that must all be true for the variable to
+ actually be set (such as "ifnotempty", "ifgt" ...). See the
+ set-var converter's description for a full list of possible
+ conditions.
- Example :
- defaults http
- option http-server-close
- timeout connect 5s
- timeout client 30s
- timeout client-fin 30s
- timeout server 30s
- timeout tunnel 1h # timeout to use with WebSocket and CONNECT
+ <expr> Is a standard HAProxy expression formed by a sample-fetch
+ followed by some converters.
- See also : "timeout client", "timeout client-fin", "timeout server".
+ <fmt> This is the value expressed using log-format rules (see Custom
+ Log Format in section 8.2.4).
+ All scopes are usable for HTTP rules, but scopes "proc" and "sess" are the
+ only usable ones in rule sets which do not have access to contents such as
+ "tcp-request connection" and "tcp-request session".
-transparent (deprecated)
- Enable client-side transparent proxying
- May be used in sections : defaults | frontend | listen | backend
- yes | no | yes | yes
- Arguments : none
+ Example:
+ http-request set-var(req.my_var) req.fhdr(user-agent),lower
+ http-request set-var-fmt(txn.from) %[src]:%[src_port]
- This keyword was introduced in order to provide layer 7 persistence to layer
- 3 load balancers. The idea is to use the OS's ability to redirect an incoming
- connection for a remote address to a local process (here HAProxy), and let
- this process know what address was initially requested. When this option is
- used, sessions without cookies will be forwarded to the original destination
- IP address of the incoming request (which should match that of another
- equipment), while requests with cookies will still be forwarded to the
- appropriate server.
- The "transparent" keyword is deprecated, use "option transparent" instead.
+silent-drop [ rst-ttl <ttl> ]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | -
- Note that contrary to a common belief, this option does NOT make HAProxy
- present the client's IP to the server when establishing the connection.
+ This stops the evaluation of the rules and makes the client-facing connection
+ suddenly disappear using a system-dependent way that tries to prevent the
+ client from being notified. When called without the rst-ttl argument,
+ we try to prevent sending any FIN or RST packet back to the client by
+ using TCP_REPAIR. If this fails (mainly because of missing privileges),
+ we fall back to sending a RST packet with a TTL of 1.
- See also: "option transparent"
+ The effect is that the client still sees an established connection while
+ there is none on HAProxy, saving resources. However, stateful equipment
+ placed between the HAProxy and the client (firewalls, proxies,
+ load balancers) will also keep the established connection in their
+ session tables.
-unique-id-format <string>
- Generate a unique ID for each request.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <string> is a log-format string.
+ The optional rst-ttl changes this behaviour: TCP_REPAIR is not used, and an
+ RST packet with a configurable TTL is sent. When set to a reasonable value,
+ the RST packet travels through the local infrastructure, deleting the
+ connection in firewalls and other systems, but disappears before reaching
+ the client. Future packets from the client will then be dropped already by
+ front equipments. These local RSTs protect local resources, but not the
+ client's. This must not be used unless the consequences of doing this are
+ fully understood.
- This keyword creates a ID for each request using the custom log format. A
- unique ID is useful to trace a request passing through many components of
- a complex infrastructure. The newly created ID may also be logged using the
- %ID tag the log-format string.
- The format should be composed from elements that are guaranteed to be
- unique when combined together. For instance, if multiple HAProxy instances
- are involved, it might be important to include the node name. It is often
- needed to log the incoming connection's source and destination addresses
- and ports. Note that since multiple requests may be performed over the same
- connection, including a request counter may help differentiate them.
- Similarly, a timestamp may protect against a rollover of the counter.
- Logging the process ID will avoid collisions after a service restart.
+strict-mode { on | off }
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | X
- It is recommended to use hexadecimal notation for many fields since it
- makes them more compact and saves space in logs.
+ This enables or disables the strict rewriting mode for following rules. It
+ does not affect rules declared before it and it is only applicable on rules
+ performing a rewrite on the requests. When the strict mode is enabled, any
+ rewrite failure triggers an internal error. Otherwise, such errors are
+ silently ignored. The purpose of the strict rewriting mode is to make some
+ rewrites optional while others must be performed to continue the request
+ processing.
- Example:
+ By default, the strict rewriting mode is enabled. Its value is also reset
+ when a ruleset evaluation ends. So, for instance, if you change the mode on
+ the frontend, the default mode is restored when HAProxy starts the backend
+ rules evaluation.
- unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
- will generate:
+switch-mode http [ proto <name> ]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | - | - | - | -
- 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
+ This action is used to perform a connection upgrade. Only HTTP upgrades are
+ supported for now. The protocol may optionally be specified. This action is
+ only available for a proxy with the frontend capability. The connection
+ upgrade is immediately performed, following "tcp-request content" rules are
+ not evaluated. This upgrade method should be preferred to the implicit one
+ consisting to rely on the backend mode. When used, it is possible to set HTTP
+ directives in a frontend without any warning. These directives will be
+ conditionally evaluated if the HTTP upgrade is performed. However, an HTTP
+ backend must still be selected. It remains unsupported to route an HTTP
+ connection (upgraded or not) to a TCP server.
- See also: "unique-id-header"
+ See section 4 about Proxies for more details on HTTP upgrades.
-unique-id-header <name>
- Add a unique ID header in the HTTP request.
- May be used in sections : defaults | frontend | listen | backend
- yes | yes | yes | no
- Arguments :
- <name> is the name of the header.
- Add a unique-id header in the HTTP request sent to the server, using the
- unique-id-format. It can't work if the unique-id-format doesn't exist.
+tarpit [ { status | deny_status } <code>] [content-type <type>]
+ [ { default-errorfiles | errorfile <file> | errorfiles <name> |
+ file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
+ [ hdr <name> <fmt> ]*
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
- Example:
+ This stops the evaluation of the rules and immediately blocks the request
+ without responding for a delay specified by "timeout tarpit" or
+ "timeout connect" if the former is not set. After that delay, if the client
+ is still connected, a response is returned so that the client does not
+ suspect it has been tarpitted. Logs will report the flags "PT". The goal of
+ the tarpit rule is to slow down robots during an attack when they're limited
+ on the number of concurrent requests. It can be very efficient against very
+ dumb robots, and will significantly reduce the load on firewalls compared to
+ a "deny" rule. But when facing "correctly" developed robots, it can make
+ things worse by forcing HAProxy and the front firewall to support insane
+ number of concurrent connections. By default an HTTP error 500 is returned.
+ But the response may be customized using same syntax than
+ "http-request return" rules. Thus, see "http-request return" for details.
- unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
- unique-id-header X-Unique-ID
+ For compatibility purpose, when no argument is defined, or only "deny_status",
+ the argument "default-errorfiles" is implied. It means
+ "http-request tarpit [deny_status <status>]" is an alias of
+ "http-request tarpit [status <status>] default-errorfiles".
+ No further "http-request" rules are evaluated.
+ See also "http-request return" and "http-request silent-drop".
- will generate:
- X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
+track-sc0 <key> [table <table>]
+track-sc1 <key> [table <table>]
+track-sc2 <key> [table <table>]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | - | X | X | -
- See also: "unique-id-format"
+ This enables tracking of sticky counters from current request. These rules do
+ not stop evaluation and do not change default action. The number of counters
+ that may be simultaneously tracked by the same connection is set by the
+ global "tune.stick-counters" setting, which defaults to MAX_SESS_STKCTR if
+ set at build time (it is reported in haproxy -vv) and which defaults to 3,
+ so the track-sc number is between 0 and (tune.stick-counters-1). The first
+ "track-sc0" rule executed enables tracking of the counters of the specified
+ table as the first set. The first "track-sc1" rule executed enables tracking
+ of the counters of the specified table as the second set. The first
+ "track-sc2" rule executed enables tracking of the counters of the specified
+ table as the third set. It is a recommended practice to use the first set of
+ counters for the per-frontend counters and the second set for the per-backend
+ ones. But this is just a guideline, all may be used everywhere.
-use_backend <backend> [{if | unless} <condition>]
- Switch to a specific backend if/unless an ACL-based condition is matched.
- May be used in sections : defaults | frontend | listen | backend
- no | yes | yes | no
Arguments :
- <backend> is the name of a valid backend or "listen" section, or a
- "log-format" string resolving to a backend name.
- <condition> is a condition composed of ACLs, as described in section 7. If
- it is omitted, the rule is unconditionally applied.
+ <key> is mandatory, and is a sample expression rule as described in
+ section 7.3. It describes what elements of the incoming connection,
+ request or reponse will be analyzed, extracted, combined, and used
+ to select which table entry to update the counters.
- When doing content-switching, connections arrive on a frontend and are then
- dispatched to various backends depending on a number of conditions. The
- relation between the conditions and the backends is described with the
- "use_backend" keyword. While it is normally used with HTTP processing, it can
- also be used in pure TCP, either without content using stateless ACLs (e.g.
- source address validation) or combined with a "tcp-request" rule to wait for
- some payload.
+ <table> is an optional table to be used instead of the default one, which
+ is the stick-table declared in the current proxy. All the counters
+ for the matches and updates for the key will then be performed in
+ that table until the session ends.
- There may be as many "use_backend" rules as desired. All of these rules are
- evaluated in their declaration order, and the first one which matches will
- assign the backend.
+ Once a "track-sc*" rule is executed, the key is looked up in the table and if
+ it is not found, an entry is allocated for it. Then a pointer to that entry
+ is kept during all the session's life, and this entry's counters are updated
+ as often as possible, every time the session's counters are updated, and also
+ systematically when the session ends. Counters are only updated for events
+ that happen after the tracking has been started. As an exception, connection
+ counters and request counters are systematically updated so that they reflect
+ useful information.
- In the first form, the backend will be used if the condition is met. In the
- second form, the backend will be used if the condition is not met. If no
- condition is valid, the backend defined with "default_backend" will be used.
- If no default backend is defined, either the servers in the same section are
- used (in case of a "listen" section) or, in case of a frontend, no server is
- used and a 503 service unavailable response is returned.
+ If the entry tracks concurrent connection counters, one connection is counted
+ for as long as the entry is tracked, and the entry will not expire during
+ that time. Tracking counters also provides a performance advantage over just
+ checking the keys, because only one table lookup is performed for all ACL
+ checks that make use of it.
- Note that it is possible to switch from a TCP frontend to an HTTP backend. In
- this case, either the frontend has already checked that the protocol is HTTP,
- and backend processing will immediately follow, or the backend will wait for
- a complete HTTP request to get in. This feature is useful when a frontend
- must decode several protocols on a unique port, one of them being HTTP.
- When <backend> is a simple name, it is resolved at configuration time, and an
- error is reported if the specified backend does not exist. If <backend> is
- a log-format string instead, no check may be done at configuration time, so
- the backend name is resolved dynamically at run time. If the resulting
- backend name does not correspond to any valid backend, no other rule is
- evaluated, and the default_backend directive is applied instead. Note that
- when using dynamic backend names, it is highly recommended to use a prefix
- that no other backend uses in order to ensure that an unauthorized backend
- cannot be forced from the request.
+unset-var(<var-name>)
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ X | X | X | X | X | X | X
- It is worth mentioning that "use_backend" rules with an explicit name are
- used to detect the association between frontends and backends to compute the
- backend's "fullconn" setting. This cannot be done for dynamic names.
+ This is used to unset a variable. See the "set-var" action for details about
+ <var-name>.
- See also: "default_backend", "tcp-request", "fullconn", "log-format", and
- section 7 about ACLs.
+ Example:
+ http-request unset-var(req.my_var)
-use-fcgi-app <name>
- Defines the FastCGI application to use for the backend.
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
- Arguments :
- <name> is the name of the FastCGI application to use.
- See section 10.1 about FastCGI application setup for details.
+use-service <service-name>
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | X | - | X | - | -
+
+ This action executes the configured TCP or HTTP service to reply to the
+ request, depending on the rule set it's used in. The rule is final, i.e.
+ no further rules are evaluated in the same rule set.
+
+ A service may choose to reply by sending any valid response or it may
+ immediately close the connection without sending any response. For HTTP
+ services, a valid response requires a valid HTTP response. Outside natives
+ services, for instance the Prometheus exporter for HTTP services, it is
+ possible to write custom TCP and HTTP services in Lua.
-use-server <server> if <condition>
-use-server <server> unless <condition>
- Only use a specific server if/unless an ACL-based condition is matched.
- May be used in sections : defaults | frontend | listen | backend
- no | no | yes | yes
Arguments :
- <server> is the name of a valid server in the same backend section
- or a "log-format" string resolving to a server name.
+ <service-name> is mandatory. It is the service to call
- <condition> is a condition composed of ACLs, as described in section 7.
+ Example:
+ http-request use-service prometheus-exporter if { path /metrics }
- By default, connections which arrive to a backend are load-balanced across
- the available servers according to the configured algorithm, unless a
- persistence mechanism such as a cookie is used and found in the request.
- Sometimes it is desirable to forward a particular request to a specific
- server without having to declare a dedicated backend for this server. This
- can be achieved using the "use-server" rules. These rules are evaluated after
- the "redirect" rules and before evaluating cookies, and they have precedence
- on them. There may be as many "use-server" rules as desired. All of these
- rules are evaluated in their declaration order, and the first one which
- matches will assign the server.
+wait-for-body time <time> [ at-least <bytes> ]
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | X | -
- If a rule designates a server which is down, and "option persist" is not used
- and no force-persist rule was validated, it is ignored and evaluation goes on
- with the next rules until one matches.
+ This will delay the processing of the request or response waiting for the
+ payload for at most <time> milliseconds. if "at-least" argument is specified,
+ HAProxy stops waiting for the payload when the first <bytes> bytes are
+ received. 0 means no limit, it is the default value. Regardless the
+ "at-least" argument value, HAProxy stops to wait if the whole payload is
+ received or if the request buffer is full. This action may be used as a
+ replacement to "option http-buffer-request".
- In the first form, the server will be used if the condition is met. In the
- second form, the server will be used if the condition is not met. If no
- condition is valid, the processing continues and the server will be assigned
- according to other persistence mechanisms.
+ Arguments :
- Note that even if a rule is matched, cookie processing is still performed but
- does not assign the server. This allows prefixed cookies to have their prefix
- stripped.
+ <time> is mandatory. It is the maximum time to wait for the body. It
+ follows the HAProxy time format and is expressed in milliseconds.
- The "use-server" statement works both in HTTP and TCP mode. This makes it
- suitable for use with content-based inspection. For instance, a server could
- be selected in a farm according to the TLS SNI field when using protocols with
- implicit TLS (also see "req.ssl_sni"). And if these servers have their weight
- set to zero, they will not be used for other traffic.
+ <bytes> is optional. It is the minimum payload size to receive to stop to
+ wait. It follows the HAProxy size format and is expressed in
+ bytes.
- Example :
- # intercept incoming TLS requests based on the SNI field
- use-server www if { req.ssl_sni -i www.example.com }
- server www 192.168.0.1:443 weight 0
- use-server mail if { req.ssl_sni -i mail.example.com }
- server mail 192.168.0.1:465 weight 0
- use-server imap if { req.ssl_sni -i imap.example.com }
- server imap 192.168.0.1:993 weight 0
- # all the rest is forwarded to this server
- server default 192.168.0.2:443 check
+ Example:
+ http-request wait-for-body time 1s at-least 1k if METH_POST
- When <server> is a simple name, it is checked against existing servers in the
- configuration and an error is reported if the specified server does not exist.
- If it is a log-format, no check is performed when parsing the configuration,
- and if we can't resolve a valid server name at runtime but the use-server rule
- was conditioned by an ACL returning true, no other use-server rule is applied
- and we fall back to load balancing.
+ See also : "option http-buffer-request"
- See also: "use_backend", section 5 about server and section 7 about ACLs.
+
+wait-for-handshake
+ Usable in: TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft
+ - | - | - | - | X | - | -
+
+ This will delay the processing of the request until the SSL handshake
+ happened. This is mostly useful to delay processing early data until we're
+ sure they are valid.
5. Bind and server options
projects / thirdparty / haproxy.git / commitdiff
