4. Proxies
Proxy configuration can be located in a set of sections:
- defaults [
<name>] [ from<defaults_name>] - frontend
<name>[ from<defaults_name>] - backend
<name>[ from<defaults_name>] - listen
<name>[ from<defaults_name>]
A “frontend” section describes a set of listening sockets accepting client connections.
A “backend” section describes a set of servers to which the proxy will connect to forward incoming connections.
A “listen” section defines a complete proxy with its frontend and backend parts combined in one section. It is generally useful for TCP-only traffic.
A “defaults” section resets all settings to the documented ones and presets new ones for use by subsequent sections. All of “frontend”, “backend” and “listen” sections always take their initial settings from a defaults section, by default the latest one that appears before the newly created section. It is possible to explicitly designate a specific “defaults” section to load the initial settings from by indicating its name on the section line after the optional keyword “from”. While “defaults” section do not impose a name, this use is encouraged for better readability. It is also the only way to designate a specific section to use instead of the default previous one. Since “defaults” section names are optional, by default a very permissive check is applied on their name and these are even permitted to overlap. However if a “defaults” section is referenced by any other section, its name must comply with the syntax imposed on all proxy names, and this name must be unique among the defaults sections. Please note that regardless of what is currently permitted, it is recommended to avoid duplicate section names in general and to respect the same syntax as for proxy names. This rule might be enforced in a future version. In addition, a warning is emitted if a defaults section is explicitly used by a proxy while it is also implicitly used by another one because it is the last one defined. It is highly encouraged to not mix both usages by always using explicit references or by adding a last common defaults section reserved for all implicit uses.
Note that it is even possible for a defaults section to take its initial settings from another one, and as such, inherit settings across multiple levels of defaults sections. This can be convenient to establish certain configuration profiles to carry groups of default settings (e.g. TCP vs HTTP or short vs long timeouts) but can quickly become confusing to follow.
By default, named defaults sections are preserved after configuration parsing. This allows to reuse them for dynamic backends creation. This behavior can be changed globally via “tune.defaults.purge” keyword.
All proxy names must be formed from upper and lower case letters, digits, ‘-’ (dash), ‘_’ (underscore) , ‘.’ (dot) and ‘:’ (colon). ACL names are case-sensitive, which means that “www” and “WWW” are two different proxies.
Historically, all proxy names could overlap when certain conditions were met (e.g. when not having the same frontend/backend capabilities), but it used to cause too many problems in the logs as well as confusion on CLI operations, stick-tables naming and stats retrieval. It is now mandatory that two proxies have different names, regardless of their respective capabilities.
Right now, two major proxy modes are supported: “tcp”, also known as layer 4, and “http”, also known as layer 7. In layer 4 mode, HAProxy simply forwards bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the protocol, and can interact with it by allowing, blocking, switching, adding, modifying, or removing arbitrary contents in requests or responses, based on arbitrary criteria.
In HTTP mode, the processing applied to requests and responses flowing over a connection depends in the combination of the frontend’s HTTP options and the backend’s. HAProxy supports 3 connection modes:
KAL: keep alive (“option http-keep-alive”) which is the default mode: all requests and responses are processed, and connections remain open but idle between responses and new requests.
SCL: server close (“option http-server-close”): the server-facing connection is closed after the end of the response is received, but the client-facing connection remains open.
CLO: close (“option httpclose”): the connection is closed after the end of the response and “Connection: close” appended in both directions.
The effective mode that will be applied to a connection passing through a frontend and a backend can be determined by both proxy modes according to the following matrix, but in short, the modes are symmetric, keep-alive is the weakest option and close is the strongest.
Backend mode
It is possible to chain a TCP frontend to an HTTP backend. It is pointless if only HTTP traffic is handled. But it may be used to handle several protocols within the same frontend. In this case, the client’s connection is first handled as a raw tcp connection before being upgraded to HTTP. Before the upgrade, the content processings are performed on raw data. Once upgraded, data is parsed and stored using an internal representation called HTX and it is no longer possible to rely on raw representation. There is no way to go back.
There are two kind of upgrades, in-place upgrades and destructive upgrades. The first ones involves a TCP to HTTP/1 upgrade. In HTTP/1, the request processings are serialized, thus the applicative stream can be preserved. The second one involves a TCP to HTTP/2 upgrade. Because it is a multiplexed protocol, the applicative stream cannot be associated to any HTTP/2 stream and is destroyed. New applicative streams are then created when HAProxy receives new HTTP/2 streams at the lower level, in the H2 multiplexer. It is important to understand this difference because that drastically changes the way to process data. When an HTTP/1 upgrade is performed, the content processings already performed on raw data are neither lost nor reexecuted while for an HTTP/2 upgrade, applicative streams are distinct and all frontend rules are evaluated systematically on each one. And as said, the first stream, the TCP one, is destroyed, but only after the frontend rules were evaluated.
There is another important point to understand when HTTP processings are performed from a TCP proxy. While HAProxy is able to parse HTTP/1 in-fly from tcp-request content rules, it is not possible for HTTP/2. Only the HTTP/2 preface can be parsed. This is a huge limitation regarding the HTTP content analysis in TCP. Concretely it is only possible to know if received data are HTTP. For instance, it is not possible to choose a backend based on the Host header value while it is trivial in HTTP/1. Hopefully, there is a solution to mitigate this drawback.
There are two ways to perform an HTTP upgrade. The first one, the historical method, is to select an HTTP backend. The upgrade happens when the backend is set. Thus, for in-place upgrades, only the backend configuration is considered in the HTTP data processing. For destructive upgrades, the applicative stream is destroyed, thus its processing is stopped. With this method, possibilities to choose a backend with an HTTP/2 connection are really limited, as mentioned above, and a bit useless because the stream is destroyed. The second method is to upgrade during the tcp-request content rules evaluation, thanks to the “switch-mode http” action. In this case, the upgrade is performed in the frontend context and it is possible to define HTTP directives in this frontend. For in-place upgrades, it offers all the power of the HTTP analysis as soon as possible. It is not that far from an HTTP frontend. For destructive upgrades, it does not change anything except it is useless to choose a backend on limited information. It is of course the recommended method. Thus, testing the request protocol from the tcp-request content rules to perform an HTTP upgrade is enough. All the remaining HTTP manipulation may be moved to the frontend http-request ruleset. But keep in mind that tcp-request content rules remains evaluated on each streams, that can’t be changed.
4.1. Proxy keywords matrix
The following list of keywords is supported. Most of them may only be used in a limited set of section types. Some of them are marked as “deprecated” because they are inherited from an old syntax which may be confusing or functionally limited, and there are new recommended keywords to replace them. Keywords marked with “(*)” can be optionally inverted using the “no” prefix, e.g. “no option contstats”. This makes sense when the option has been enabled by default and must be disabled for a specific instance. Such options may also be prefixed with “default” in order to restore default settings regardless of what has been specified in a previous “defaults” section. Keywords supported in defaults sections marked with “(!)” are only supported in named defaults sections, not anonymous ones.
Note: Some dangerous and not recommended directives are intentionnaly not listed in the following matrix. It is on purpose. These directives are documentated. But by not listing them below is one more way to discourage anyone to use it.
4.2. Alphabetically sorted keywords reference
This section provides a description of each keyword and its usage.
acl <aclname> <criterion> [flags] [operator] <value> ...
Declare or complete an access list.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | yes
This directive is only available from named defaults sections, not anonymous ones. ACLs defined in a defaults section are not visible from other sections using it.
Example:
See section 7 about ACL usage.
backlog <conns>
Give hints to the system about the approximate listen backlog desired size
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
This option is only meaningful for stream listeners, including QUIC ones. Its behavior however is not identical with QUIC instances.
For all listeners but QUIC, in order to protect against SYN flood attacks, one solution is to increase the system’s SYN backlog size. Depending on the system, sometimes it is just tunable via a system parameter, sometimes it is not adjustable at all, and sometimes the system relies on hints given by the application at the time of the listen() syscall. By default, HAProxy passes the frontend’s maxconn value to the listen() syscall. On systems which can make use of this value, it can sometimes be useful to be able to specify a different value, hence this backlog parameter.
On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is used as a hint and the system accepts up to the smallest greater power of two, and never more than some limits (usually 32768).
For QUIC listeners, backlog sets a shared limits for both the maximum count of active handshakes and connections waiting to be accepted. The handshake phase relies primarily of the network latency with the remote peer, whereas the second phase depends solely on haproxy load. When either one of this limit is reached, haproxy starts to drop reception of INITIAL packets, preventing any new connection allocation, until the connection excess starts to decrease. This situation may cause browsers to silently downgrade the HTTP versions and switching to TCP.
See also: “maxconn” and the target operating system’s tuning guide.
balance <algorithm> [ <arguments> ]
Define the load balancing algorithm to be used in a backend.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
The load balancing algorithm of a backend is set to “random” when no other algorithm, mode nor option have been set. The algorithm may only be set once for each backend.
With authentication schemes that require the same connection like NTLM, URI based algorithms must not be used, as they would cause subsequent requests to be routed to different backend servers, breaking the invalid assumptions NTLM relies on.
TCP/HTTP Examples:
LOG backend examples:
Note: the following caveats and limitations on using the “check_post” extension with “url_param” must be considered:
- all POST requests are eligible for consideration, because there is no way
to determine if the parameters will be found in the body or entity which
may contain binary data. Therefore another method may be required to
restrict consideration of POST requests that have no URL parameters in
the body. (see acl http_end)
- using a `<max_wait>` value larger than the request buffer size does not
make sense and is useless. The buffer size is set at build time, and
defaults to 16 kB.
- Content-Encoding is not supported, the parameter search will probably
fail; and load balancing will fall back to Round Robin.
- Expect: 100-continue is not supported, load balancing will fall back to
Round Robin.
- Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
If the entire parameter value is not present in the first chunk, the
selection of server is undefined (actually, defined by how little
actually appeared in the first chunk).
- This feature does not support generation of a 100, 411 or 501 response.
- In some cases, requesting "check_post" MAY attempt to scan the entire
contents of a message body. Scanning normally terminates when linear
white space or control characters are found, indicating the end of what
might be a URL parameter list. This is probably not a concern with SGML
type message bodies.
See also: “dispatch”, “cookie”, “transparent”, “hash-type”.
be-unpublished
Instructs the backend to start in the unpublished state.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
In effect, any use_backend and default_backend rules from another proxy which reference the current proxy are ignored and the next content switching rules are evaluated. This can be bypassed though via a “force-be-switch” rule.
This state is similar to the disabled one but with some differences. First, an unpublished backend will still be fully initialized, including the server health checks which remain active. Finally, a backend can be publicly exposed via the command “publish backend” on the CLI. See the management manual.
See also: “force-be-switch”
bind [<address>]:<port_range> [, ...] [param*]
Define one or several listening addresses and/or ports in a frontend.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
It is possible to specify a list of address:port combinations delimited by commas. The frontend will then listen on all of these addresses. There is no fixed limit to the number of addresses and ports which can be listened on in a frontend, as well as there is no limit to the number of “bind” statements in a frontend.
Example:
Note: regarding Linux’s abstract namespace sockets, “abns” HAProxy sockets 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, or use the “abnsz” HAProxy socket family instead.
See also: “source”, “option forwardfor”, “unix-bind” and the PROXY protocol documentation, and section 5 about bind options.
capture cookie <name> len <length>
Capture and log a cookie in the request and in the response.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
Only the first cookie is captured. Both the “cookie” request headers and the “set-cookie” response headers are monitored. This is particularly useful to check for application bugs causing session crossing or stealing between users, because generally the user’s cookies can only change on a login page.
When the cookie was not presented by the client, the associated log column will report “-”. When a request does not cause a cookie to be assigned by the server, a “-” is reported in the response column.
The capture is performed in the frontend only because it is necessary that the log format does not change for a given frontend depending on the backends. This may change in the future. Note that there can be only one “capture cookie” statement in a frontend. The maximum capture length is set by the global “tune.http.cookielen” setting and defaults to 63 characters. It is not possible to specify a capture in a “defaults” section.
Example:
See also: “capture request header”, “capture response header” as well as section 8 about logging.
capture request header <name> len <length>
Capture and log the last occurrence of the specified request header.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
The complete value of the last occurrence of the header is captured. The value will be added to the logs between braces (’{}’). If multiple headers are captured, they will be delimited by a vertical bar (’|’) and will appear in the same order they were declared in the configuration. Non-existent headers will be logged just as an empty string. Common uses for request header captures include the “Host” field in virtual hosting environments, the “Content-length” when uploads are supported, “User-agent” to quickly differentiate between real users and robots, and “X-Forwarded-For” in proxied environments to find where the request came from.
Note that when capturing headers such as “User-agent”, some spaces may be logged, making the log analysis more difficult. Thus be careful about what you log if you know your log parser is not smart enough to rely on the braces.
There is no limit to the number of captured request headers nor to their length, though it is wise to keep them low to limit memory usage per stream. In order to keep log format consistent for a same frontend, header captures can only be declared in a frontend. It is not possible to specify a capture in a “defaults” section.
Example:
See also: “capture cookie”, “capture response header” as well as section 8 about logging.
capture response header <name> len <length>
Capture and log the last occurrence of the specified response header.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
The complete value of the last occurrence of the header is captured. The result will be added to the logs between braces (’{}’) after the captured request headers. If multiple headers are captured, they will be delimited by a vertical bar (’|’) and will appear in the same order they were declared in the configuration. Non-existent headers will be logged just as an empty string. Common uses for response header captures include the “Content-length” header which indicates how many bytes are expected to be returned, the “Location” header to track redirections.
There is no limit to the number of captured response headers nor to their length, though it is wise to keep them low to limit memory usage per stream. In order to keep log format consistent for a same frontend, header captures can only be declared in a frontend. It is not possible to specify a capture in a “defaults” section.
Example:
See also: “capture cookie”, “capture request header” as well as section 8 about logging.
clitcpka-cnt <count>
Sets the maximum number of keepalive probes TCP should send before dropping the connection on the client side.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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 clitcpka”, “clitcpka-idle”, “clitcpka-intvl”.
clitcpka-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 client side.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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 clitcpka”, “clitcpka-cnt”, “clitcpka-intvl”.
clitcpka-intvl <timeout>
Sets the time between individual keepalive probes on the client side.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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.
See also: “option clitcpka”, “clitcpka-cnt”, “clitcpka-idle”.
compression algo <algorithm> ...
Enable HTTP compression.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
The currently supported algorithms are:
Compression will be activated depending on the Accept-Encoding request header. With identity, it does not take care of that header. If backend servers support HTTP compression, these directives will be no-op: HAProxy will see the compressed response and will not compress again. If backend servers do not support HTTP compression and there is Accept-Encoding header in request, HAProxy will compress the matching response.
Compression is disabled when: * the request does not advertise a supported compression algorithm in the “Accept-Encoding” header * the response message is not HTTP/1.1 or above * HTTP status code is not one of 200, 201, 202, or 203 * response contain neither a “Content-Length” header nor a “Transfer-Encoding” whose last value is “chunked” * response contains a “Content-Type” header whose first value starts with “multipart” * the response contains the “no-transform” value in the “Cache-control” header * User-Agent matches “Mozilla/4” unless it is MSIE 6 with XP SP2, or MSIE 7 and later * The response contains a “Content-Encoding” header, indicating that the response is already compressed (see compression offload) * The response contains an invalid “ETag” header or multiple ETag headers * The payload size is smaller than the minimum size (see compression minsize-res)
Note: The compression does not emit the Warning header.
Examples:
See also: “compression offload”, “compression direction”, “compression minsize-req” and “compression minsize-res”
compression minsize-req <size>
Sets the minimum payload size in bytes for compression to be applied.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Payloads smaller than this size will not be compressed, avoiding unnecessary CPU overhead for data that would not significantly benefit from compression. “minsize-req” applies on requests and “minsize-res” on responses. The default value is 0.
compression offload
Makes HAProxy work as a compression offloader only.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
The “offload” setting makes HAProxy remove the Accept-Encoding header to prevent backend servers from compressing responses. It is strongly recommended not to do this because this means that all the compression work will be done on the single point where HAProxy is located. However in some deployment scenarios, HAProxy may be installed in front of a buggy gateway with broken HTTP compression implementation which can’t be turned off. In that case HAProxy can be used to prevent that gateway from emitting invalid payloads. In this case, simply removing the header in the configuration does not work because it applies before the header is parsed, so that prevents HAProxy from compressing. The “offload” setting should then be used for such scenarios.
If this setting is used in a defaults section, a warning is emitted and the option is ignored.
See also: “compression type”, “compression algo”, “compression direction”
compression direction <direction> (deprecated)
Makes haproxy able to compress both requests and responses. Valid values are “request”, to compress only requests, “response”, to compress only responses, or “both”, when you want to compress both. The default value is “response”.
This directive is only relevant when legacy “filter compression” was enabled, as with explicit comp-req and comp-res filters compression direction is redundant.
May be used in the following contexts: http
See also: “compression type”, “compression algo”, “compression offload”
cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Enable cookie-based persistence in a backend.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
There can be only one persistence cookie per HTTP backend, and it can be declared in a defaults section. The value of the cookie will be the value indicated after the “cookie” keyword in a “server” statement. If no cookie is declared for a given server, the cookie is not set.
Examples:
See also: “balance source”, “capture cookie”, “server” and “ignore-persist”.
declare capture [ request | response ] len <length>
Declares a capture slot.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
This declaration is only available in the frontend or listen section, but the reserved slot can be used in the backends. The “request” keyword allocates a capture slot for use in the request, and “response” allocates a capture slot for use in the response.
See also: “capture-req”, “capture-res” (sample converters), “capture.req.hdr”, “capture.res.hdr” (sample fetches), “http-request capture” and “http-response capture”.
default-server [param*]
Change default options for a server in a backend
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Example:
See also: “server” and section 5 about server options
default_backend <backend>
Specify the backend to use when no “use_backend” rule has been matched.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
When doing content-switching between frontend and backends using the “use_backend” keyword, it is often useful to indicate which backend will be used when no rule has matched. It generally is the dynamic backend which will catch all undetermined requests.
If a backend is disabled or unpublished, default_backend rules targeting it will be ignored and stream processing will remain on the original proxy.
Example:
See also: “use_backend”
description <string>
Describe a listen, frontend or backend.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
Arguments: string
Allows to add a sentence to describe the related object in the HAProxy HTML stats page. The
description will be printed on the right of the object name it describes. No need to backslash
spaces in the <string> arguments.
disabled
Disable a proxy, frontend or backend.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
The “disabled” keyword is used to disable an instance, mainly in order to liberate a listening port or to temporarily disable a service. The instance will still be created and its configuration will be checked, but it will be created in the “stopped” state and will appear as such in the statistics. It will not receive any traffic nor will it send any health-checks or logs. It is possible to disable many instances at once by adding the “disabled” keyword in a “defaults” section.
By default, a disabled backend cannot be selected for content-switching. However, a portion of the traffic can ignore this when “force-be-switch” is used.
See also: “enabled”, “force-be-switch”
dispatch <address>:<port> (deprecated)
Set a default server address
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
The “dispatch” keyword designates a default server for use when no other server can take the connection. In the past it was used to forward non persistent connections to an auxiliary load balancer. Due to its simple syntax, it has also been used for simple TCP relays. It is recommended not to use it for more clarity, and to use the “server” directive instead.
This keyword has been deprecated in 3.3 and will be removed in 3.5 due to some internal limitations (no support for SSL nor idle connections etc). Using it will emit a warning that may be silenced by enabling directive “expose-deprecated-directives” in the global section.
The correct way to proceed without this directive is to simply declare a server with the same address and port. If the “dispatch” directive was mixed with other servers, then these servers should be configured with a weight of zero in order never to be elected by the load balancing algorithm.
Example:
See also: “server”
dynamic-cookie-key <string>
Set the dynamic cookie secret key for a backend.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: The secret key to be used.
When dynamic cookies are enabled (see the “dynamic” directive for cookie), a dynamic cookie is created for each server (unless one is explicitly specified on the “server” line), using a hash of the IP address of the server, the TCP port, and the secret key. That way, we can ensure session persistence across multiple load-balancers, even if servers are dynamically added or removed.
enabled
Enable a proxy, frontend or backend.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
The “enabled” keyword is used to explicitly enable an instance, when the defaults has been set to “disabled”. This is very rarely used.
See also: “disabled”
errorfile <code> <file>
Return a file contents instead of errors generated by HAProxy
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set.
Code 200 is emitted in response to requests matching a “monitor-uri” rule.
The files are parsed when HAProxy starts and must be valid according to the HTTP specification. They should not exceed the configured buffer size (BUFSIZE), which generally is 16 kB, otherwise an internal error will be returned. It is also wise not to put any reference to local contents (e.g. images) in order to avoid loops between the client and HAProxy when all servers are down, causing an error to be returned instead of an image. Finally, The response cannot exceed (tune.bufsize - tune.maxrewrite) so that “http-after-response” rules still have room to operate (see “tune.maxrewrite”).
The files are read at the same time as the configuration and kept in memory. For this reason, the errors continue to be returned even when the process is chrooted, and no file change is considered while the process is running. A simple method for developing those files consists in associating them to the 403 status code and interrogating a blocked URL.
See also: “http-error”, “errorloc”, “errorloc302”, “errorloc303”
Example:
errorfiles <name> [<code> ...]
Import, fully or partially, the error files defined in the <name> http-errors section.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
Errors defined in the http-errors section with the name <name> are imported in the current proxy.
If no status code is specified, all error files of the http-errors section are imported. Otherwise,
only error files associated to the listed status code are imported. Those error files override the
already defined custom errors for the proxy. And they may be overridden by following ones.
Functionally, it is exactly the same as declaring all error files by hand using “errorfile”
directives.
See also: “http-error”, “errorfile”, “errorloc”, “errorloc302” , “errorloc303” and section 12.4 about http-errors.
Example:
errorloc <code> <url>
Return an HTTP redirection to a URL instead of errors generated by HAProxy
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set.
Code 200 is emitted in response to requests matching a “monitor-uri” rule.
Note that both keyword return the HTTP 302 status code, which tells the client to fetch the designated URL using the same HTTP method. This can be quite problematic in case of non-GET methods such as POST, because the URL sent to the client might not be allowed for something other than GET. To work around this problem, please use “errorloc303” which send the HTTP 303 status code, indicating to the client that the URL must be fetched with a GET request.
See also: “http-error”, “errorfile”, “errorloc303”
errorloc303 <code> <url>
Return an HTTP redirection to a URL instead of errors generated by HAProxy
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set.
Code 200 is emitted in response to requests matching a “monitor-uri” rule.
Note that both keyword return the HTTP 303 status code, which tells the client to fetch the designated URL using the same HTTP GET method. This solves the usual problems associated with “errorloc” and the 302 code. It is possible that some very old browsers designed before HTTP/1.1 do not support it, but no such problem has been reported till now.
See also: “http-error”, “errorfile”, “errorloc”, “errorloc302”
email-alert from <emailaddr>
Declare the from email address to be used in both the envelope and header of email alerts. This is the address that email alerts are sent from.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
Also requires “email-alert mailers” and “email-alert to” to be set and if so sending email alerts is enabled for the proxy.
See also: “email-alert level”, “email-alert mailers”, “email-alert myhostname”, “email-alert to”, section 12.3 about mailers.
email-alert level <level>
Declare the maximum log level of messages for which email alerts will be sent. This acts as a filter on the sending of email alerts.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
By default level is alert
Also requires “email-alert from”, “email-alert mailers” and “email-alert to” to be set and if so sending email alerts is enabled for the proxy.
Alerts are sent when:
- An un-paused server is marked as down and
<level>is alert or lower - A paused server is marked as down and
<level>is notice or lower - A server is marked as up or enters the drain state and
<level>is notice or lower - “option log-health-checks” is enabled,
<level>is info or lower, and a health check status update occurs
See also: “email-alert from”, “email-alert mailers”, “email-alert myhostname”, “email-alert to”, section 12.3 about mailers.
email-alert mailers <mailersect>
Declare the mailers to be used when sending email alerts
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
Also requires “email-alert from” and “email-alert to” to be set and if so sending email alerts is enabled for the proxy.
See also: “email-alert from”, “email-alert level”, “email-alert myhostname”, “email-alert to”, section 12.3 about mailers.
email-alert myhostname <hostname>
Declare the to hostname address to be used when communicating with mailers.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
By default the systems hostname is used.
Also requires “email-alert from”, “email-alert mailers” and “email-alert to” to be set and if so sending email alerts is enabled for the proxy.
See also: “email-alert from”, “email-alert level”, “email-alert mailers”, “email-alert to”, section 12.3 about mailers.
email-alert to <emailaddr>
Declare both the recipient address in the envelope and to address in the header of email alerts. This is the address that email alerts are sent to.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
Also requires “email-alert mailers” and “email-alert to” to be set and if so sending email alerts is enabled for the proxy.
See also: “email-alert from”, “email-alert level”, “email-alert mailers”, “email-alert myhostname”, section 12.3 about mailers.
error-log-format <fmt>
Specifies the log format string to use in case of connection error on the frontend side.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
This directive specifies the log format string that will be used for logs containing information related to errors, timeouts, retries redispatches or HTTP status code 5xx. This format will in short be used for every log line that would be concerned by the “log-separate-errors” option, including connection errors described in section 8.2.5 .
If the directive is used in a defaults section, all subsequent frontends will use the same log format. Please see section 8.2.6 which covers the custom log format string in depth.
“error-log-format” directive overrides previous “error-log-format” directives.
force-persist { if | unless } <condition>
Declare a condition to force persistence on down servers
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
By default, requests are not dispatched to down servers. It is possible to force this using “option persist”, but it is unconditional and redispatches to a valid server if “option redispatch” is set. That leaves with very little possibilities to force some requests to reach a server which is artificially marked down for maintenance operations.
The “force-persist” statement allows one to declare various ACL-based conditions which, when met, will cause a request to ignore the down status of a server and still try to connect to it. That makes it possible to start a server, still replying an error to the health checks, and run a specially configured browser to test the service. Among the handy methods, one could use a specific source IP address, or a specific cookie. The cookie also has the advantage that it can easily be added/removed on the browser from a test page. Once the service is validated, it is then possible to open the service to the world by returning a valid response to health checks.
The forced persistence is enabled when an “if” condition is met, or unless an “unless” condition is met. The final redispatch is always disabled when this is used.
See also: “option redispatch”, “ignore-persist”, “persist”, and section 7 about ACL usage.
external-check command <command>
Executable to run when performing an external-check
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
The arguments passed 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:
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.
Example:
See also: “external-check”, “option external-check”, “external-check path”
external-check path <path>
The value of the PATH environment variable used when running an external-check
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
The default path is “”.
Example:
See also: “external-check”, “option external-check”, “external-check command”
force-be-switch { if | unless } <condition>
Allow content switching to select a backend instance even if it is disabled or unpublished. This rule can be used by admins to test traffic to services prior to expose them to the outside world.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
See also: “be-unpublished”, “disabled”
filter <name> [param*]
Add the filter <name> in the filter list attached to the proxy.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
Arguments:
Multiple occurrences of the filter line can be used for the same proxy. The same filter can be referenced many times if needed.
Example:
See also: section 9 ., “filter-sequence”
filter-sequence { request | response } <filter_list>
Specifies in which order filters declared on the proxy should be executed.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
Comma-separated list of filter names (<filter_list>) to specify in which order filters declared on
the proxy should be executed, for request or response path, respectively.
When filter-sequence is not specified for a given path (ie: request vs response), the order in which filters are declared on the proxy is used.
If filter-sequence omits some filters that were declared on the proxy, they will not be executed. This is an effective way of temporarily disabling a filter without removing it from the configuration.
Example:
See also: “filter”
fullconn <conns>
Specify at what backend load the servers will reach their maxconn
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
When a server has a “maxconn” parameter specified, it means that its number of concurrent
connections will never go higher. Additionally, if it has a “minconn” parameter, it indicates a
dynamic limit following the backend’s load. The server will then always accept at least <minconn>
connections, never more than <maxconn>, and the limit will be on the ramp between both values when
the backend has less than <conns> concurrent connections. This makes it possible to limit the load
on the servers during normal loads, but push it further for important loads without overloading the
servers during exceptional loads.
Since it’s hard to get this value right, HAProxy automatically sets it to 10% of the sum of the maxconns of all frontends that may branch to this backend (based on “use_backend” and “default_backend” rules). That way it’s safe to leave it unset. However, “use_backend” involving dynamic names are not counted since there is no way to know if they could match or not.
Example:
See also: “maxconn”, “server”
guid <string>
Specify a case-sensitive global unique ID for this proxy.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
<string> must be unique across all haproxy configuration on every object types. Format is left
unspecified to allow the user to select its naming policy. The only restriction is its length which
cannot be greater than 127 characters. All alphanumerical values and ‘.’, ‘:’, ‘-’ and ‘_’
characters are valid. See also “shm-stats-file”.
hash-balance-factor <factor>
Specify the balancing factor for bounded-load consistent hashing
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | no | yes
Arguments:
Specifying a “hash-balance-factor” for a server with “hash-type consistent” enables an algorithm
that prevents any one server from getting too many requests at once, even if some hash buckets
receive many more requests than others. Setting <factor> to 0 (the default) disables the feature.
Otherwise, <factor> is a percentage greater than 100. For example, if <factor> is 150, then no
server will be allowed to have a load more than 1.5 times the average. If server weights are used,
they will be respected.
If the first-choice server is disqualified, the algorithm will choose another server based on the
request hash, until a server with additional capacity is found. A higher <factor> allows more
imbalance between the servers, while a lower <factor> means that more servers will be checked on
average, affecting performance. Reasonable values are from 125 to 200.
This setting is also used by “balance random” which internally relies on the consistent hashing mechanism.
See also: “balance” and “hash-type”.
hash-preserve-affinity { always | maxconn | maxqueue }
Specify a method for assigning streams to servers with hash load balancing when servers are satured or have a full queue.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
The following values can be specified:
- "always" : this is the default strategy. A stream is assigned to a
server based on hashing irrespective of whether the server
is currently saturated.
- "maxconn" : when selected, servers that have "maxconn" set and are
currently saturated will be skipped. Another server will be
picked by following the hashing ring. This has no effect on
servers that do not set "maxconn". If all servers are
saturated, the request is enqueued to the last server in the
hash ring before the initially selected server.
- "maxqueue": when selected, servers that have "maxconn" set, "maxqueue"
set to a non-zero value (limited queue size) and currently
have a full queue will be skipped. Another server will be
picked by following the hashing ring. This has no effect on
servers that do not set both "maxconn" and "maxqueue".
See also: “maxconn”, “maxqueue”, “hash-balance-factor”
hash-type <method> <function> <modifier>
Specify a method to use for mapping hashes to servers
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
The default hash type is “map-based” and is recommended for most usages. The default function is “sdbm”, the selection of a function should be based on the range of the values being hashed.
See also: “balance”, “hash-balance-factor”, “hash-preserve-affinity”, “server”
http-after-response <action> <options...> [ { if | unless } <condition> ]
Access control for all Layer 7 responses (server, applet/service and internal ones).
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | yes
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. 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 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 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: Errors emitted in early stage of the request parsing are handled by the multiplexer at a lower level, before any http analysis. Thus no http-after-response ruleset is evaluated on these errors.
Example:
http-check comment <string>
Defines a comment for the following the http-check rule, reported in logs if it fails.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
It only works for connect, send and expect rules. It is useful to make user-friendly error reporting.
See also: “option httpchk”, “http-check connect”, “http-check send” and “http-check expect”.
http-check connect [default] [port <expr>] [addr <ip>] [send-proxy]
Opens a new connection to perform an HTTP health check
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Just like tcp-check health checks, it is possible to configure the connection to use to perform HTTP health check. This directive should also be used to describe a scenario involving several request/response exchanges, possibly on different ports or with different servers.
When there are no TCP port configured on the server line neither server port directive, then the first step of the http-check sequence must be to specify the port with a “http-check connect”.
In an http-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.
When a connect must start the ruleset, if may still be preceded by set-var, unset-var or comment rules.
Examples:
See also: “option httpchk”, “http-check send”, “http-check expect”
http-check disable-on-404
Enable a maintenance mode upon HTTP/404 response to health-checks
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
When this option is set, a server which returns an HTTP code 404 will be excluded from further load-balancing, but will still receive persistent connections. This provides a very convenient method for Web administrators to perform a graceful shutdown of their servers. It is also important to note that a server which is detected as failed while it was in this mode will not generate an alert, just a notice. If the server responds 2xx or 3xx again, it will immediately be reinserted into the farm. The status on the stats page reports “NOLB” for a server in this mode. It is important to note that this option only works in conjunction with the “httpchk” option. If this option is used with “http-check expect”, then it has precedence over it so that 404 responses will still be considered as soft-stop. Note also that a stopped server will stay stopped even if it replies 404s. This option is only evaluated for running servers.
See also: “option httpchk” and “http-check expect”.
http-check expect [min-recv <int>] [comment <msg>]
Make HTTP health checks consider response contents or specific status codes
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
By default, “option httpchk” considers that response statuses 2xx and 3xx are valid, and that others are invalid. When “http-check expect” is used, it defines what is considered valid or invalid. Only one “http-check” statement is supported in a backend. If a server fails to respond or times out, the check obviously fails. The available matches are:
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” or “rstring”. 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.
In an http-check ruleset, the last expect rule may be implicit. If no expect rule is specified after the last “http-check send”, an implicit expect rule is defined to match on 2xx or 3xx status codes. It means this rule is also defined if there is no “http-check” rule at all, when only “option httpchk” is set.
Last, if “http-check expect” is combined with “http-check disable-on-404”, then this last one has precedence when the server responds with 404.
Examples:
See also: “option httpchk”, “http-check connect”, “http-check disable-on-404” and “http-check send”.
http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
Add a possible list of headers and/or a body to the request sent during HTTP health checks.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
In addition to the request line defined by the “option httpchk” directive, this one is the valid way to add some headers and optionally a body to the request sent during HTTP health checks. If a body is defined, the associate “Content-Length” header is automatically added. Thus, this header or “Transfer-encoding” header should not be present in the request provided by “http-check send”. If so, it will be ignored. The old trick consisting to add headers after the version string on the “option httpchk” line is now deprecated.
Also “http-check send” doesn’t support HTTP keep-alive. Keep in mind that it will automatically append a “Connection: close” header, unless a Connection header has already already been configured via a hdr entry.
Note that the Host header and the request authority, when both defined, are automatically synchronized. It means when the HTTP request is sent, when a Host is inserted in the request, the request authority is accordingly updated. Thus, don’t be surprised if the Host header value overwrites the configured request authority.
Note also for now, no Host header is automatically added in HTTP/1.1 or above requests. You should add it explicitly.
See also: “option httpchk”, “http-check send-state” and “http-check expect”.
http-check send-state
Enable emission of a state header with HTTP health checks
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
When this option is set, HAProxy will systematically send a special header “X-Haproxy-Server-State” with a list of parameters indicating to each server how they are seen by HAProxy. This can be used for instance when a server is manipulated without access to HAProxy and the operator needs to know whether HAProxy still sees it up or not, or if the server is the last one in a farm.
The header is composed of fields delimited by semi-colons, the first of which is a word (“UP”,
“DOWN”, “NOLB”), possibly followed by a number of valid checks on the total number before
transition, just as appears in the stats interface. Next headers are in the form
“<variable>=<value>”, indicating in no specific order some values available in the stats
interface: - a variable “address”, containing the address of the backend server. This corresponds to
the <address> field in the server declaration. For unix domain sockets, it will read “unix”.
- a variable "port", containing the port of the backend server. This
corresponds to the `<port>` field in the server declaration. For unix
domain sockets, it will read "unix".
- a variable "name", containing the name of the backend followed by a slash
("/") then the name of the server. This can be used when a server is
checked in multiple backends.
- a variable "node" containing the name of the HAProxy node, as set in the
global "node" variable, otherwise the system's hostname if unspecified.
- a variable "weight" indicating the weight of the server, a slash ("/")
and the total weight of the farm (just counting usable servers). This
helps to know if other servers are available to handle the load when this
one fails.
- a variable "scur" indicating the current number of concurrent connections
on the server, followed by a slash ("/") then the total number of
connections on all servers of the same backend.
- a variable "qcur" indicating the current number of requests in the
server's queue.
Example of a header received by the application server:
See also: “option httpchk”, “http-check disable-on-404” and “http-check send”.
http-check set-var(<var-name>[,<cond>...]) <expr>
This operation sets the content of a variable. The variable is declared inline.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Examples:
http-check unset-var(<var-name>)
Free a reference to a variable within its scope.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Examples:
http-error status <code> [content-type <type>]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Defines a custom error message to use instead of errors generated by HAProxy.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
This directive may be used instead of “errorfile”, to define a custom error message. As “errorfile” directive, it is used for errors detected and returned by HAProxy. If an errorfile is defined, it is parsed when HAProxy starts and must be valid according to the HTTP standards. The generated response must not exceed the configured buffer size (BUFFSIZE), otherwise an internal error will be returned. Finally, if you consider to use some http-after-response rules to rewrite these errors, the reserved buffer space should be available (see “tune.maxrewrite”).
The files are read at the same time as the configuration and kept in memory. For this reason, the errors continue to be returned even when the process is chrooted, and no file change is considered while the process is running.
Note: 400/408/500 errors emitted in early stage of the request parsing are handled by the multiplexer at a lower level. No custom formatting is supported at this level. Thus only static error messages, defined with “errorfile” directive, are supported. However, this limitation only exists during the request headers parsing or between two transactions.
See also: “errorfile”, “errorfiles”, “errorloc”, “errorloc302”, “errorloc303” and section 12.4 about http-errors.
http-request <action> [options...] [ { if | unless } <condition> ]
Access control for Layer 7 requests
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | yes
The http-request 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 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 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:
Example:
Example:
See also: “stats http-request”, section 12.2 about userlists and section 7 about ACL usage.
http-response <action> <options...> [ { if | unless } <condition> ]
Access control for Layer 7 responses
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | yes
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 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:
Example:
See also: “http-request”, section 12.2 about userlists and section 7 about ACL usage.
http-reuse { never | safe | aggressive | always }
Declare how idle HTTP connections may be shared between requests
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
In order to avoid the cost of setting up new connections to backend servers for each HTTP request, HAProxy tries to keep such idle connections opened after being used. These connections are specific to a server and are stored in a list called a pool, and are grouped together by a set of common key properties. Subsequent HTTP requests will cause a lookup of a compatible connection sharing identical properties in the associated pool and result in this connection being reused instead of establishing a new one.
A limit on the number of idle connections to keep on a server can be specified via the “pool-max-conn” server keyword. Unused connections are periodically purged according to the “pool-purge-delay” interval.
The following connection properties are used to determine if an idle connection is eligible for reuse on a given request:
- source and destination addresses
- proxy protocol
- TOS and mark socket options
- connection name, determined either by the result of the evaluation of the “pool-conn-name” expression if present, otherwise by the “sni” expression, which defaults to “req.hdr(host),field(1,:)”, i.e. uses the incoming request’s “Host” header field without the colon nor the port number.
In some occasions, connection lookup or reuse is not performed due to extra restrictions. This is determined by the reuse strategy specified via the keyword argument:
- "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.
- "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.
- "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.
- "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".
Also note that connections with certain bogus authentication schemes (relying on the connection) like NTLM are marked private if possible and never shared. This won’t be the case however when using a protocol with multiplexing abilities and using reuse mode level value greater than the default “safe” strategy as in this case nothing prevents the connection from being already shared.
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.
In some rare cases, when the host name is used to distinguish outgoing TLS connections (e.g. forward proxy), where most request target different hosts, the reuse rate will be very low, and the automatic eviction of rarely used connections will kick in before connections have a chance to be reused, because the mechanism continuously measures the average number of connections needed to deliver the service without exhausting resources. In such situations, setting “pool-low-conn” to a value close to the average expected number of idle connections may help preserve more connections by encouraging threads to setup their own instead of trying to pick other threads’ and shrinking the pool of available connections.
If a locally hosted server uses a single certificate (with multiple host names or wildcards) and operates multiple sites, it may be more effective to just use “no-sni-auto” on the “server” line to avoid reserving a connection to a single Host name. This will significantly increase the reuse rate. Some servers might perform excessive checks between Host and SNI though, resulting in rejecting subsequent requests, so this option requires preliminary validation. The default behavior (“sni-auto”) is to be safe even with such servers.
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).
See also: “option http-keep-alive”, “pool-conn-name”, “pool-max-conn”, “pool-purge-delay”, “server maxconn”, “sni”, “thread-groups”, “tune.pool-high-fd-ratio”, “tune.pool-low-fd-ratio”
http-send-name-header [<header>]
Add the server name to a request. Use the header string given by <header>
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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. This is why following
header names are forbidden: host, content-length, transfer-encoding and connection.
See also: “server”
id <value>
Set a persistent ID to a proxy.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
Arguments: none
Set a persistent ID for the proxy. This ID must be unique and positive. An unused ID will automatically be assigned if unset. Due to an historical behavior, value 1 is not used unless explicitly set. Thus, the lowest value automatically assigned will be 2. This ID is currently only returned in statistics.
ignore-persist { if | unless } <condition>
Declare a condition to ignore persistence
May be used in the following contexts: tcp, http
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).
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).
The persistence is ignored when an “if” condition is met, or unless an “unless” condition is met.
Example:
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 the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
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 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).
Arguments:
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.
- server's weight is applied from previous running process unless it has
has changed between previous and new configuration files.
Example: Minimal configuration
global
stats socket /tmp/socket
server-state-file /tmp/server_state
defaults
load-server-state-from-file global
backend bk
server s1 127.0.0.1:22 check weight 11
server s2 127.0.0.1:22 check weight 12
Then one can run:
Content of the file /tmp/server_state would be like this:
Example: Minimal configuration
global
stats socket /tmp/socket
server-state-base /etc/haproxy/states
defaults
load-server-state-from-file local
backend bk
server s1 127.0.0.1:22 check weight 11
server s2 127.0.0.1:22 check weight 12
Then one can run:
Content of the file /etc/haproxy/states/bk would be like this:
See also: “server-state-file”, “server-state-file-name”, and “show servers state”
log global
Enable per-instance logging of events and traffic.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Prefix:
Arguments:
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.
Example:
log-format <fmt>
Specifies the custom log format string to use for traffic logs
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
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.6 which covers the custom 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.
“log-format” directive overrides previous “option tcplog”, “log-format”, “option httplog” and “option httpslog” directives.
log-format-sd <fmt>
Specifies the Custom log format string used to produce RFC5424 structured-data
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
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.6 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.
Note: This log format string will be used only for loggers that have set log format to “rfc5424”.
Example:
log-steps <steps>
Specifies at which steps during transaction processing logs should be generated.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
During tcp/http transaction processing, haproxy may produce logs at different steps during the processing (ie: accept, connect, request, response, close).
By default, HAProxy emits a single log per transaction, once all of the items used in the logformat expression could be satisfied, which means that in practice the log is usually emitted at the end of the transaction (after the end of the response for HTTP or end of connection for TCP), unless “option logasap” is used.
The “log-steps” directive allows to refine the precise instants where logs will be emitted, and even permits to emit multiple logs for a same transaction. Special value ‘all’ may be used to enable all available log origins, making it possible to track a transaction from accept to close. Individual log origins may also be specified using their names separated by commas to selectively enable when logs should be produced.
Common log origins are: accept, connect, request, response, close.
Example:
Log origins specified as “logging steps” (such as accept, close) can be used as-is in log-profiles (after ‘on’ directive). Combining “log-steps” with log-profiles is really interesting to have fine-grained control over logs automatically generated by haproxy during transaction processing.
This setting is only relevant on frontends, it is ignored on backends.
See also: “log-profile”
log-tag <string>
Specifies the log tag to use for all outgoing logs
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
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.
max-keep-alive-queue <value>
Set the maximum server queue size for maintaining keep-alive connections
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
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.
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.
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.
See also: “option http-server-close”, “option prefer-last-server”, server “maxconn” and cookie persistence.
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 the following contexts: tcp, http
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
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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.
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.
When this value is set to zero, which is the default, the global “maxconn” value is used.
See also: “server”, global section’s “maxconn”, “fullconn”
mode { tcp|http|log|spop }
Set the running mode or protocol of the instance May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes Arguments:
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.
Example:
monitor fail { if | unless } <condition>
Add a condition to report a failure to a monitor HTTP request.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
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:
See also: “monitor-uri”, “errorfile”, “errorloc”
monitor-uri <uri>
Intercept a URI used by external components’ monitor requests
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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:
See also: “monitor fail”
option abortonclose
Enable or disable early abortion of not started processing when client closes
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
TCP connections support being closed independently in each direction, and a connection with only one direction closed is often said to be “half-closed”. Originally when the HTTP ecosystem was mostly made of the “close mode”, with only one request and one response per connection before closing, it was pretty frequent to see scripted clients send their request, close the sending side, wait for the response, receive the close indication and be done with this. But with the arrival of keep-alive and more advanced protocols, this practice has practically disappeared and the only cases where a client closes before receiving its response is essentially when the user wants to abort a transfer, or when a timeout strikes and the connection is closed.
These two situations (half-closed vs abort) are undistinguishable from the server side (here the HAProxy listener). This is a problem because leaving the connection alive and continuing to process a request when clients abort can cost a lot of resources, particularly if the closure is the result of a user hitting the “reload” button, as it means new requests are queued without the previous ones being aborted. And conversely, systematically aborting when facing such a half-close situation would break a number of TCP applications and even some HTTP ones on internal networks interacting with legacy agents.
The “abortonclose” option permits to choose the desired behavior: - when present in a frontend, it will avoid processing TLS handshakes which are pending on a half-closed connection. This can be the result of a user hitting “reload” during an HTTPS request under high load such as a VRRP fail-over between an active HAProxy node and the backup one: all clients reconnect at the same time to the new node, and all have to perform a costly, full TLS handshake. If it takes more than a few seconds, it’s likely that some users will give up, and it’s pointless to waste CPU cycles on their handshakes. Given the CPU cost of TLS handshakes, it is recommended to leave this option enabled on internet-facing frontends. This is the default for incoming TLS connections.
- when present in a backend, it will cause half-closed connections to try
to abort a request that was not yet sent to a server (i.e. when it's
pending in the queue or when trying to connect). If the request is
already being served by a server, then the connection to the server is
in turn switched to half-close to indicate the same condition to the
server, which will then decide how to proceed. This is the default for
HTTP-mode backends.
The recommendation is to enable this option on internet-facing TLS endpoints and HTTP services, and to disable it for pure TCP ones as well as unexposed legacy environments. It is enabled by default in HTTP backends, and may be forcefully disabled by prepending the “no” keyword before it, either in the backend section itself, or in the “defaults” section it inherits from. It is also enabled by default for TLS listeners and may be forcefully disabled as well by specifying “no option abortonclose” in the frontend or in the “defaults” section it inherits from.
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
option accept-invalid-http-request (deprecated)
Enable or disable relaxing of HTTP request parsing
The “accept-invalid-http-request” keyword is deprecated, use “option accept-unsafe-violations-in-http-request” instead.
option accept-invalid-http-response (deprecated)
Enable or disable relaxing of HTTP response parsing
The “accept-invalid-http-response” keyword is deprecated, use “option accept-unsafe-violations-in-http-response” instead.
option accept-unsafe-violations-in-http-request
Enable or disable relaxing of HTTP request parsing
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
By default, HAProxy complies with the different HTTP RFCs in terms of message parsing. This means the message parsing is quite strict and causes an error to be returned to the client for malformed messages. This is the desired behavior as such malformed messages are essentially used to build attacks exploiting server weaknesses, and bypass security filtering. Sometimes, a buggy browser will not respect these RCFs for whatever reason (configuration, implementation…) and the issue will not be immediately fixed. In such case, it is possible to relax HAProxy’s parser to accept some invalid requests by specifying this option. Most of rules concern the H1 parsing for historical reason. Newer HTTP versions tends to be cleaner and applications follow more stickly these protocols.
When this option is set, the following rules are observed:
* In H1 only, invalid characters, including NULL character, in header name
will not be rejected; however the header will be dropped.
* In H1 only, NULL character in header value will be accepted;
* In H1 only, characters above 127 in the URI will be accepted. 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 normally not allowed. In H1, all character between (0..32) and
127 will always be blocked. All characters above 127 (excluded) will also
be blocked, except when this option is enabled. Other characters
(33..126) will not be checked at all.
* In H1 and H2, URLs containing fragment references ('#' after the path)
will be accepted;
* In H1 only, no check will be performed on the authority for CONNECT
requests;
* In H1 only, no check will be performed against the authority and the Host
header value.
* In H1 only, tests on the HTTP version will be relaxed. It will allow
HTTP/0.9 GET 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.
* In H1 only, WebSocket (RFC6455) requests failing to present a valid
"Sec-Websocket-Key" header field will be accepted.
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.
When this option is enabled, invalid but accepted H1 requests 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.
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-unsafe-violations-in-http-response” and “show errors” on the stats socket.
option accept-unsafe-violations-in-http-response
Enable or disable relaxing of HTTP response parsing
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
Similarly to “option accept-unsafe-violations-in-http-request”, this option may be used to relax parsing rules of HTTP responses. It should only be enabled for trusted legacy servers to accept some invalid responses. Most of rules concern the H1 parsing for historical reason. Newer HTTP versions tends to be cleaner and applications follow more stickly these protocols.
When this option is set, the following rules are observed:
* In H1 only, status codes longer than 3 digits but whose value fits in 16
bits are not rejected.
* In H1 only, invalid characters, including NULL character, in header name
will not be rejected; however the header will be dropped.
* In H1 only, NULL character in header value will be accepted;
* In H1 only, empty values or several "chunked" value occurrences for
Transfer-Encoding header will be accepted;
* In H1 only, no check will be performed against the authority and the Host
header value.
* In H1 only, tests on the HTTP version will be relaxed. It will allow
different protocol names (e.g. RTSP), and multiple digits for both the
major and the minor version.
* In H1 only, WebSocket (RFC6455) responses failing to present a valid
"Sec-Websocket-Accept" header field will be accepted.
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.
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.
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-unsafe-violations-in-http-request” and “show errors” on the stats socket.
option allbackups
Use either all backup servers at a time or only the first one
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend 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.
This option is mostly used with static server farms dedicated to return a “sorry” page when an application is completely offline.
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 checkcache
Analyze all server responses and block responses with cacheable cookies
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend 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
Enable or disable the sending of TCP keepalive packets on the client side
May be used in the following contexts: tcp, http
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.
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.
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.
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”
option contstats
Enable continuous traffic statistics updates
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
By default, counters used for statistics calculation are incremented only when a stream 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 stream, 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.
option disable-h2-upgrade
Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client connection.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
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”.
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 dontlog-normal
Enable or disable logging of normal, successful connections
May be used in the following contexts: tcp, http
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.
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.
See also: “log”, “dontlognull”, “log-separate-errors” and section 8 about logging.
option dontlognull
Enable or disable logging of null connections
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
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.
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.
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: “log”, “http-ignore-probes”, “monitor-uri”, and section 8 about logging.
option external-check
Use external processes for server health checks
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
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”.
Requires the “external-check” global to be set.
See also: “external-check”, “external-check command”, “external-check path”
option forwarded [ proto ]
Enable insertion of the rfc 7239 forwarded header in requests sent to servers
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Since HAProxy works in reverse-proxy mode, servers are losing some request context (request origin: client ip address, protocol used…)
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
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 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:
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”.
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”.
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”.
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”.
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.
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.
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.
Examples:
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 the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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”).
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.
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 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:
See also: “option httpclose”, “option http-server-close”, “option http-keep-alive”
option h1-case-adjust-bogus-client
Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
May be used in the following contexts: http
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.
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 h1-case-adjust-bogus-server”, “h1-case-adjust”, “h1-case-adjust-file”.
option h1-case-adjust-bogus-server
Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend 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.
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.
See also: “option h1-case-adjust-bogus-client”, “h1-case-adjust”, “h1-case-adjust-file”.
option http-buffer-request
Enable or disable waiting for whole HTTP request body before proceeding
May be used in the following contexts: http
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.
See also: “option http-no-delay”, “timeout http-request”, “http-request wait-for-body”
option http-drop-request-trailers
Drop the HTTP trailers from the request when sent to the server
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | no | no | yes
Arguments: none
When this option is enabled, any HTTP trailers found in a request will be dropped before sending it to the server.
RFC9110#section-6.5.1 stated that trailer fields could be merged into the header fields. It should be done on purpose, but it may be a problem for some applications, especially if malicious clients hide sensitive header fields in the trailers part and some intermediaries merge them with headers with no specific checks. In that case, this option can be enabled on the backend to drop any trailer fields found in requests before sending them to the 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 http-drop-response-trailers”
option http-drop-response-trailers
Drop the HTTP trailers from the response when sent to the client
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
This option is similar to “option http-drop-request-trailers” but it must be used to drop trailer fields from responses before sending them to clients.
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-drop-request-trailers”
option http-ignore-probes
Enable or disable logging of null connections and request timeouts
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
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
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.
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: “log”, “dontlognull”, “errorfile”, and section 8 about logging.
option http-keep-alive
Enable or disable HTTP keep-alive from client to server for HTTP/1.x connections
May be used in the following contexts: http
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”. This option allows to set back the keep-alive mode, which can be useful when another mode was used in a defaults section.
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:
- when the server is non-HTTP compliant and authenticates the connection
instead of requests (e.g. NTLM authentication)
- when the cost of establishing the connection to the server is significant
compared to the cost of retrieving the associated object from the server.
This last case can happen when the server is a fast static server of cache.
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 disables and replaces any previous “option httpclose” or “option http-server-close”.
See also: “option httpclose”,, “option http-server-close”, “option prefer-last-server” and “option http-pretend-keepalive”.
option http-no-delay
Instruct the system to favor low interactive delays over performance in HTTP
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
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.
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.
See also: “option http-buffer-request”
option http-pretend-keepalive
Define whether HAProxy will announce keepalive for HTTP/1.x connection to the server or not
May be used in the following contexts: http
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.
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.
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.
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.
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 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
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
Note this option is evaluated per proxy and after the http-request rules evaluation.
option http-server-close
Enable or disable HTTP/1.x connection closing on the server side
May be used in the following contexts: http
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.
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 httpclose”, “option http-pretend-keepalive” and “option http-keep-alive”.
option http-use-proxy-header
Make use of non-standard Proxy-Connection header instead of Connection
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
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.
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.
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.
This option should normally never be used, except in front of a proxy.
See also: “option httpclose”, and “option http-server-close”.
option httpchk
Enables HTTP protocol to check on the servers health
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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.
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.
“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.
Examples:
See also: “option ssl-hello-chk”, “option smtpchk”, “option mysql-check”, “option pgsql-check”, “http-check” and the “check”, “port” and “inter” server options.
option httpclose
Enable or disable HTTP/1.x connection closing
May be used in the following contexts: http
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”.
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.
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.
It disables and replaces any previous “option http-server-close” or “option http-keep-alive”.
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 httplog [ clf ]
Enable logging of HTTP request, stream state and timers
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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 stream 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.
“option httplog” overrides any previous “log-format” directive.
See also: section 8 about logging.
option httpslog
Enable logging of HTTPS request, stream state and timers
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
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 stream 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.
“option httpslog” overrides any previous “log-format” directive.
See also: section 8 about logging.
option idle-close-on-response
Avoid closing idle frontend connections if a soft stop is in progress
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
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”
option independent-streams
Enable or disable independent timeout processing for both directions
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
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.
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 streams 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.
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: “timeout client”, “timeout server” and “timeout tunnel”
option ldap-check
Use LDAPv3 health checks for server testing
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
The server is considered valid only when the LDAP response contains success resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9 ).
Logging of bind requests is server dependent see your documentation how to configure it.
Example:
See also: “option httpchk”
option log-health-checks
Enable or disable logging of health checks status updates
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
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.
Note that status changes not caused by health checks (e.g. enable/disable on the CLI) are intentionally not logged by this option.
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.
option log-separate-errors
Change log level for non-completely successful connections
May be used in the following contexts: tcp, http
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.
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.
See also: “log”, “dontlognull”, “dontlog-normal” and section 8 about logging.
option logasap
Enable or disable early logging.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
By default, logs are emitted when all the log format aliases and sample fetches used in the definition of the log-format string return a value, or when the stream is terminated. This allows the built in log-format strings to account for the transfer time, or the number of bytes in log messages.
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:
See also: “option httplog”, “capture response header”, and section 8 about logging.
option mysql-check [ user <username> [ { post-41 | pre-41 | post-80 } ] ]
Use MySQL health checks for server testing
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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:
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.
Remember that this does not check database presence nor database consistency. To do this, you can use an external check with xinetd for example.
The check requires MySQL >=3.22, for older version, please use TCP check.
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.
See also: “option httpchk”
option nolinger
Enable or disable immediate session resource cleaning after close
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
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.
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 the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
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.
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 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.
Examples:
See also: “option httpclose”, “option http-server-close”.
option persist
Enable or disable forced persistence on down servers
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
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 redispatch”, “retries”, “force-persist”
option pgsql-check user <username>
Use PostgreSQL health checks for server testing
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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”.
See also: “option httpchk”
option prefer-last-server
Allow multiple load balanced requests to remain on the same server
May be used in the following contexts: tcp, http
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.
It may be useful to precise here, which load balancing algorithms are considered deterministic. Deterministic algorithms will always select the same server for a given client data, assuming the set of available servers has not changed. In general, deterministic algorithms involve hashing or lookups on the incoming requests to choose the target server. However, this is not always the case; “static-rr”, for example, can be also considered as deterministic because the server choice is based on the server’s static weight, making the selection predictable. “sticky” algorithm provides deterministic routing for the returning clients.
As for non-deterministic algorithms, these algorithms select a server based on dynamic server state or simple rotation, so two consecutive requests are not guaranteed to land on the same server. option prefer-last-server is designed specifically for these. roundrobin, leastconn are examples of such algorithms.
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-keep-alive”
option redispatch
Enable or disable session redistribution in case of connection failure
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
In HTTP mode, if a server designated by a cookie is down, clients may definitely stick to it, for example when using “option persist” or “force-persist”, because they cannot flush the cookie, so they will not be able to access the service anymore.
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:
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: “option persist”, “force-persist”, “retries”
option redis-check
Use redis health checks for server testing
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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:
See also: “option httpchk”, “option tcp-check”, “tcp-check expect”
option smtpchk
Use SMTP health checks for server testing
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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:
See also: “option httpchk”, “source”
option socket-stats no option socket-stats
Enable or disable collecting & providing separate statistics for each socket.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
option splice-auto
Enable or disable automatic kernel acceleration on sockets in both directions
May be used in the following contexts: tcp, http
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.
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.
Example:
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-request”, “option splice-response”, and global options “nosplice” and “maxpipes”
option splice-request
Enable or disable automatic kernel acceleration on sockets for requests
May be used in the following contexts: tcp, http
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.
Important note: see “option splice-auto” for usage limitations.
Example:
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-response”, and global options “nosplice” and “maxpipes”
option splice-response
Enable or disable automatic kernel acceleration on sockets for responses
May be used in the following contexts: tcp, http
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 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.
Important note: see “option splice-auto” for usage limitations.
Example:
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”
option spop-check
Use SPOP health checks for server testing
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
Example:
See also: “option httpchk”
option srvtcpka
Enable or disable the sending of TCP keepalive packets on the server side
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
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.
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.
Please note that this has nothing to do with HTTP keep-alive.
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 clitcpka”, “option tcpka”
option ssl-hello-chk
Use SSLv3 client hello health checks for server testing
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
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.
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.
See also: “option httpchk”, “check-ssl”
option tcp-check
Perform health checks using tcp-check send/expect sequences
May be used in the following contexts: tcp, http, log
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.
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.
- "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.
- 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.
A fifth mode can be used to insert comments in different steps of the script.
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”.
Examples:
See also: “tcp-check connect”, “tcp-check expect” and “tcp-check send”.
option tcp-smart-accept
Enable or disable the saving of one ACK packet during the accept sequence
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments: none
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.
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.
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”.
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.
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”
option tcp-smart-connect
Enable or disable the saving of one ACK packet during the connect sequence
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
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.
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.
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 tcp-smart-accept”
option tcpka
Enable or disable the sending of TCP keepalive packets on both sides
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
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.
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.
Please note that this has nothing to do with HTTP keep-alive.
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 clitcpka”, “option srvtcpka”
option tcplog [clf]
Enable advanced logging of TCP connections with stream state and timers
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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 stream 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.
“option tcplog” overrides any previous “log-format” directive.
See also: “option httplog”, and section 8 about logging.
option transparent (deprecated)
Enable client-side transparent proxying
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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 that contrary to a common belief, this option does NOT make HAProxy present the client’s IP to the server when establishing the connection.
As of 3.3, this option is now deprecated because it used to suffer from a number of internal technical limitations. Using it will emit a warning, which can be avoided if really needed via the “expose-deprecated-directives” global keyword.
The correct approach is to declare a server on address 0.0.0.0, which will take care of connecting to the expected destination address. A server will also properly handle idle connections to the target servers.
Example:
See also: the “usesrc” argument of the “source” keyword, and the “transparent” option of the “bind” keyword.
option use-small-buffers [ queue | l7-retries | check ]*
Enable support for small buffers for the given categories.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
This option can be used to enable the small buffers support at different places to save memory. By default, with no parameter, small buffers are used as far as possible at all possible places. Otherwise, it is possible to limit it to following the places:
- queue: When set, small buffers will be used to store the requests, if small enough, when the connection is queued.
- l7-retries: When set, small buffers will be used to save the requests when L7 retries are enabled.
- check: When set, small buffers will be used for the health-checks requests.
When enabled, small buffers are used, but only if it is possible. Otherwise, when data are too large, a regular buffer is automatically used. The size of small buffers is configurable via the “tune.bufsize.small” global setting.
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: tune.bufsize.small
persist rdp-cookie
Enable RDP cookie-based persistence
May be used in the following contexts: tcp
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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.
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.
Example:
See also: “balance rdp-cookie”, “tcp-request” and the “req.rdp_cookie” ACL.
quic-initial <action> [ { if | unless } <condition> ]
Perform an action on an incoming QUIC Initial packet. Contrary to “tcp-request connection”, this is executed prior to any connection element instantiation and starting and completion of the SSL handshake, which is more efficient when wanting to reject connections attempts.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | no
Arguments:
This action is executed early during QUIC packet parsing. As such, only a minimal list of actions is supported: - accept - dgram-drop - reject - send-retry
rate-limit sessions <rate>
Set a limit on the number of new sessions accepted per second on a frontend
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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>]
Return an HTTP redirection if/unless a condition is matched
May be used in the following contexts: http
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:
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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:
See also: “retries”, “option redispatch”, “tune.bufsize”
server <name> <address>[:[port]] [param*]
Declare a server in a backend
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
Examples:
Note: regarding Linux’s abstract namespace sockets, “abns” HAProxy sockets 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, or use the “abnsz” HAProxy socket family instead.
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 the following contexts: tcp, http, log
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 the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
Examples:
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Set the source address for outgoing connections
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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.
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:
- 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.
- 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.
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.
In order to work, “usesrc” requires root privileges, or on supported systems, the “cap_net_raw” capability. See also the “setcap” global directive.
Examples:
See also: the “source” server option in section 5 , the Tproxy patches for the Linux kernel on www.balabit.com , the “bind” keyword.
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 the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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 srvtcpka”, “srvtcpka-idle”, “srvtcpka-intvl”.
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 the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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 srvtcpka”, “srvtcpka-cnt”, “srvtcpka-intvl”.
srvtcpka-intvl <timeout>
Sets the time between individual keepalive probes on the server side.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
See also: “option srvtcpka”, “srvtcpka-cnt”, “srvtcpka-idle”.
stats admin { if | unless } <cond>
Enable statistics admin level if/unless a condition is matched
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
This statement enables the statistics admin level if/unless a condition is matched.
The admin level allows to enable/disable servers from the web interface. By default, statistics page is read-only for security reasons. If “stats scope” directives are set in the section, then only proxies designated by these directives will accept state changes; access to other ones will be denied.
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.
Those admin POST requests are prone to CSRF attacks. This is partially mitigated by checking that the Origin (or Referer if no Origin is present) matches the Host header, but this is not enough to totally prevent the attack. There is no way to be completely protected from those. It is recommended to avoid exposing it on a public interface, and to restrict who can access it.
Example:
Example:
Example:
See also: “stats enable”, “stats auth”, “stats http-request”, “stats scope”, section 12.2 about userlists and section 7 about ACL usage.
ssl-f-use [<sslbindconf> ...]*
Assignate a certificate to the current frontend.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
Assignate a certificate <crtname> to a crt-list created automatically with the frontend name and
prefixed by @ (ex: ‘@frontend1’).
This implicit crt-list will be assigned to every “ssl” bind lines in the current frontend.
crt-list commands from the stats socket are effective with this crt-list, so one could replace, remove or add certificates and SSL options to it.
Example:
See also: “crt-list” and “crt”.
stats auth <user>:<passwd>
Enable statistics with authentication and grant access to an account
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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”.
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.
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.
Example:
See also: “stats enable”, “stats realm”, “stats scope”, “stats uri”
stats enable
Enable statistics reporting with default settings
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
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
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:
See also: “stats auth”, “stats realm”, “stats uri”
stats hide-version
Enable statistics and hide HAProxy version reporting
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
The stats page can report 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, and is the default.
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:
See also: “stats auth”, “stats enable”, “stats realm”, “stats uri”, “stats show-version”
stats http-request { allow | deny | auth [realm <realm>] }
Access control for statistics
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend no | 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.
There is no fixed limit to the number of http-request statements per instance.
See also: “http-request”, section 12.2 about userlists and section 7 about ACL usage.
stats realm <realm>
Enable statistics and set authentication realm
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
The realm is read as a single word, so any spaces in it should be escaped using a backslash (’\’).
This statement is useful only in conjunction with “stats auth” since it is only related to authentication.
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:
See also: “stats auth”, “stats enable”, “stats uri”
stats refresh <delay>
Enable statistics with automatic refresh
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
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:
See also: “stats auth”, “stats enable”, “stats realm”, “stats uri”
stats scope { <name> | "." }
Enable statistics and limit access scope
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
When this statement is specified, only the sections enumerated with this statement will appear in the report. All other ones will be hidden, and attempts to change their state in admin mode will be rejected. 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.
Example:
See also: “stats auth”, “stats enable”, “stats realm”, “stats uri” and “stats admin”
stats show-desc [ <desc> ]
Enable reporting of a description on the statistics page.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
`<desc>` is an optional description to be reported. If unspecified, the
description from global section is automatically used instead.
This statement is useful for users that offer shared services to their customers, where node or description should be different for each customer.
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:
See also: “show-node”, “stats enable”, “stats uri” and “description” in global section.
stats show-legends
Enable reporting additional information on the statistics page
May be used in the following contexts: http
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)
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”.
stats show-modules
Enable display of extra statistics module on the statistics page
May be used in the following contexts: http
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.
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”.
stats show-node [ <name> ]
Enable reporting of a host name on the statistics page.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
Example:
See also: “show-desc”, “stats enable”, “stats uri”, and “node” in global section.
stats show-version
Enable statistics and show HAProxy version reporting
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments: none
The stats page can report 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, and so is disabled by default. The “stats show-version” enables displaying those informations. This is not recommanded for public sites or any site with a weak login/password.
See also: “stats auth”, “stats enable”, “stats realm”, “stats uri”, “stats hide-version”
stats uri <prefix>
Enable statistics and define the URI prefix to access them
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
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.
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.
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:
See also: “stats auth”, “stats enable”, “stats realm”
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
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.
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 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.
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.
Example:
See also: “stick-table”, “stick on”, section 11 about stick-tables, and section 7 about ACLs and samples fetching.
stick on <pattern> [table <table>] [{if | unless} <condition>]
Define a request pattern to associate a user to a server
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
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.
Examples:
See also: “stick match”, “stick store-request”, and section 11 about stick-tables.
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
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.
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-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.
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.
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:
See also: “stick-table”, “stick on”, section 11 about stick-tables, and section 7 about ACLs and sample fetching.
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
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.
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.
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.
Example:
See also: “stick-table”, “stick on”, section 11 about stick-tables, and section 7 about ACLs and pattern extraction.
stick-table type <type> size <size> [expire <expire>] [args...]
Configure the stickiness table for the current section
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes
This is used to declare and configure a stick-table. Please refer to section 11.1 for the complete details and the list of supported arguments. Only the type and the size are mandatory.
tcp-check comment <string>
Defines a comment for the following the tcp-check rule, reported in logs if it fails.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
It only works for connect, send and expect rules. It is useful to make user-friendly error reporting.
See also: “option tcp-check”, “tcp-check connect”, “tcp-check send” and “tcp-check expect”.
tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
Opens a new connection
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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.
When a connect must start the ruleset, if may still be preceded by set-var, unset-var or comment rules.
Examples:
See also: “option tcp-check”, “tcp-check send”, “tcp-check expect”
tcp-check expect [min-recv <int>] [comment <msg>]
Specify data to be collected and analyzed during a generic health check
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
The available matches are intentionally similar to their http-check cousins:
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.
Examples:
See also: “option tcp-check”, “tcp-check connect”, “tcp-check send”, “tcp-check send-binary”, “http-check expect”, tune.bufsize
tcp-check send <data> [comment <msg>]
Specify a string or a Custom log format to be sent as a question during a generic health check
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Examples:
See also: “option tcp-check”, “tcp-check connect”, “tcp-check expect”, “tcp-check send-binary”, tune.bufsize
tcp-check send-binary <hexstring> [comment <msg>]
Specify an hex digits string or an hex digits Custom log format to be sent as a binary question during a raw tcp health check
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Examples:
See also: “option tcp-check”, “tcp-check connect”, “tcp-check expect”, “tcp-check send”, tune.bufsize
tcp-check set-var(<var-name>[,<cond>...]) <expr>
This operation sets the content of a variable. The variable is declared inline.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Examples:
tcp-check unset-var(<var-name>)
Free a reference to a variable within its scope.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
Examples:
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | no
Arguments:
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.
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.
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.
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”).
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.
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.
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.
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 }
Example: enable the PROXY protocol for traffic coming from all known proxies.
tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
See section 7 about ACL usage.
See also: “tcp-request session”, “tcp-request content”, “stick-table”
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | yes
Arguments:
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.
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.
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”).
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.
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.
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.
Example:
Example:
Example:
Example:
Example:
Example:
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 }
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
See section 7 about ACL usage.
See also: “tcp-request connection”, “tcp-request session”, “tcp-request inspect-delay”, and “http-request”.
tcp-request inspect-delay <timeout>
Set the maximum allowed time to wait for data during content inspection
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | yes
Arguments:
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.
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.
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.
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 directive is only available from named defaults sections, not anonymous ones. Proxies inherit this value from their defaults section.
See also: “tcp-request content accept”, “tcp-request content reject”, “timeout client”.
tcp-request session <action> [{if | unless} <condition>]
Perform an action on a validated session depending on a layer 5 condition
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | yes | yes | no
Arguments:
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.
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.
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”).
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.
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
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.
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
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.
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 }
See section 7 about ACL usage.
See also: “tcp-request connection”, “tcp-request content”, “stick-table”
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | no | yes | yes
Arguments:
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.
Most often, these decisions will consider a protocol recognition or validity.
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 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”).
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 for changing the default action to a reject.
Several types of actions are supported:
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.
See section 7 about ACL usage.
See also: “tcp-request content”, “tcp-response inspect-delay”
tcp-response inspect-delay <timeout>
Set the maximum allowed time to wait for a response during content inspection
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes(!) | no | yes | yes
Arguments:
This directive is only available from named defaults sections, not anonymous ones. Proxies inherit this value from their defaults section.
See also: “tcp-response content”, “tcp-request inspect-delay”.
timeout check <timeout>
Set additional check timeout, but only after a connection has been already established.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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).
If “timeout check” is not set HAProxy uses “inter” for complete check timeout (connect + read) exactly like all <1.3.15 version.
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.
See also: “timeout connect”, “timeout queue”, “timeout server”, “timeout tarpit”.
timeout client <timeout>
Set the maximum inactivity time on the client side.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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 streams are mixed with short-lived streams (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 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”.
timeout client-fin <timeout>
Set the inactivity timeout on the client side for half-closed connections.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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.
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).
See also: “timeout client”, “timeout server-fin”, and “timeout tunnel”.
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
If this handshake timeout is not set, this is the client timeout which is used in place.
timeout connect <timeout>
Set the maximum time to wait for a connection attempt to a server to succeed.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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 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”.
timeout http-keep-alive <timeout>
Set the maximum allowed time to wait for a new HTTP request to appear
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
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 request to complete, an HTTP 408 error is returned to the client before closing the connection, unless “option http-ignore-probes” is set in the frontend.
In general “timeout http-keep-alive” is best used to prevent clients from holding open an otherwise idle connection too long on sites seeing large amounts of short connections. This can be accomplished by setting the value to a few tens to hundreds of milliseconds in HTTP/1.1. This will close the connection after the client requests a page without having to hold that connection open to wait for more activity from the client. In that scenario, a new activity from the browser would result in a new handshake at the TCP and/or SSL layer. A common use case for this is HTTP sites serving only a redirect to the HTTPS page. Such connections are better not kept idle too long because they won’t be reused, unless maybe to fetch a favicon.
Another use case is the exact opposite: some sites want to permit clients to reuse idle connections for a long time (e.g. 30 seconds to one minute) but do not want to wait that long for the first request, in order to avoid a very inexpensive attack vector. In this case, the http-keep-alive timeout would be set to a large value, but http-request would remain low (a few seconds).
When set to a very small value additional requests that are not pipelined are likely going to be handled over another connection unless the requests are truly pipelined, which is very rare with HTTP/1.1 (requests being sent back-to-back without waiting for a response). Most HTTP/1.1 implementations send a request, wait for a response and then send another request. A small value here for HTTP/1.1 may be advantageous to use less memory and sockets for sites with hundreds of thousands of clients, at the expense of an increase in handshake computation costs.
Special care should be taken with small values when dealing with HTTP/2. The nature of HTTP/2 is to multiplex requests over a connection in order to save on the overhead of reconnecting the TCP and/or SSL layers. The protocol also uses control frames which cope poorly with early TCP connection closures, on very rare occasions this may result in truncated responses when data are destroyed in flight after leaving HAProxy (which then cannot even log an error). A suggested low starting value for HTTP/2 connections would be around 4 seconds. This would prevent most modern keep-alive implementations from needlessly holding open stale connections, and at the same time would allow subsequent requests to reuse the connection. However, this should be adjusted as needed and is simply a starting point.
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”.
timeout http-request <timeout>
Set the maximum allowed time to wait for a complete HTTP request
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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 .
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.
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.
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.
See also: “errorfile”, “http-ignore-probes”, “timeout http-keep-alive”, and “timeout client”, “option http-buffer-request”.
timeout queue <timeout>
Set the maximum time to wait in the queue for a connection slot to be free
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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.
See also: “timeout connect”.
timeout server <timeout>
Set the maximum inactivity time on the server side.
May be used in the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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 streams are mixed with short-lived streams (e.g. WebSocket and HTTP), it’s worth considering “timeout tunnel”, which overrides “timeout client” and “timeout server” for tunnels.
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 the following contexts: tcp, http, log
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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”.
timeout tarpit <timeout>
Set the duration for which tarpitted connections will be maintained
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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.
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”.
timeout tunnel <timeout>
Set the maximum inactivity time on the client and server side for tunnels.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments:
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.
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.
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).
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.
Example:
See also: “timeout client”, “timeout client-fin”, “timeout server”.
transparent (deprecated)
Enable client-side transparent proxying
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | no | yes | yes
Arguments: none
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.
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 transparent”
unique-id-format <fmt>
Generate a unique ID for each request.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | yes
Arguments:
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 alias in the Custom 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.
It is recommended to use hexadecimal notation for many fields since it makes them more compact and saves space in logs.
For regular connections the format configured in the frontend is used to generate the unique ID. For health checks the format of the backend is used when using the “unique-id” fetch within a tcp-check or an http-check ruleset.
Example:
See also: “unique-id-header”
unique-id-header <name>
Add a unique ID header in the HTTP request.
May be used in the following contexts: http
May be used in sections: defaults | frontend | listen | backend yes | yes | yes | no
Arguments:
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.
Example:
use_backend <backend> [{if | unless} <condition>]
Switch to a specific backend if/unless an ACL-based condition is matched.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | yes | yes | no
Arguments:
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.
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. This is even the case if the backend is considered as down. However, if a matching rule targets a disabled or unpublished backend, it is ignored instead and rules evaluation continue.
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 unless it is disabled or unpublished. If no default backend is available, 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.
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 Custom log format 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.
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 the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
See section 10.1 about FastCGI application setup for details.
use-server <server> if <condition>
Only use a specific server if/unless an ACL-based condition is matched.
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
Arguments:
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.
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.
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.
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.
Example:
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 Custom 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: “use_backend”, section 5 about server and section 7 about ACLs.
4.3. Actions keywords matrix
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:
- QUIC Ini: the action is valid for “quic-initial” rules
- 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.
4.4. Alphabetically sorted actions reference
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.
accept
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | X | X | X | X | - | - | -
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 and QUIC rules and “allow” for HTTP rules. See also the “allow” action below.
add-acl(<file-name>) <key fmt>
Usable in: QUIC Ini| 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 Custom log format rules described in section 8.2.6
, 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.
add-header <name> <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
This appends an HTTP header field whose name is specified in <name> and whose value is defined by
<fmt> which follows the Custom log format rules (see Custom log format in section 8.2.6
). 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.
add-headers-bin <expr> [ prefix <str> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
This is a variant of the “add-header” action where the header names and values are passed as a
varint encoded binary string. See the “req.hdrs_bin” sample fetch about the varint format. This is
useful when you want to set multiple headers at once, without having to know the header names in
advance. Note that these headers have not been validated by the HTTP parser and could lead to
emitting invalid messages and in worst cases lead to request smuggling attacks. The number of
headers inserted are also of importance, as that is limited by tune.http.maxhdr. Optional prefix
will only set the headers from the encoded string that start with <str>.
Example:
allow
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
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.
attach-srv <srv> [name <expr>] [ EXPERIMENTAL ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | X | - | - | - | - | -
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.
The connection is inserted into the server idle pool with a name defined by the result of the
<expr> evaluation. This is the name that will be matched against by requests subject to
“pool-conn-name” or “sni” parameter. See “http-reuse” for more details.
Reverse HTTP is currently still in active development. Configuration mechanism may change in the future. For this reason it is internally marked as experimental, meaning that “expose-experimental-directives” must appear on a line before this directive.
Note that a very similar but independent protocol is under development. See https://www.ietf.org/archive/id/draft-bt-httpbis-reverse-http-00.html .
auth [realm <realm>]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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).
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.
Example:
cache-store <name>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | - | X | -
Store an http-response within the cache. The storage of the response headers is done at this step, which means you can use others http-response actions to modify headers before or after the storage of the response. This action is responsible for the setup of the cache storage filter.
See section 6.2 about cache setup.
cache-use <name>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Try to deliver a cached object from the cache <name>. This directive is also mandatory to store
the cache as it calculates the cache hash. If you want to use a condition for both storage and
delivering that’s a good idea to put it after this one.
See section 6.2 about cache setup.
capture <sample> [ len <length> | id <id> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | X | X
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 response), 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 stream 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.
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.
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.
close
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | X | - | - | -
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.
del-acl(<file-name>) <key fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
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 Custom log format rules of section 8.2.6
, 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.
del-header <name> [ -m <meth> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
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.
del-headers-bin <expr> [ -m <meth> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
This removes all HTTP header fields whose names are specified in <expr>. <expr> must return a
varint encoded binary string of all header names that should be deleted. See “add-headers-bin” and
“set-headers-bin” for the description of encoding and examples. <meth> is the matching method,
applied on all the header names. Supported matching methods are “str” (exact match), “beg” (prefix
match), “end” (suffix match) and “sub” (substring match). The “reg” (regex match) is not supported
due to unpredictable performance during runtime. If not specified, exact matching method is used.
del-map(<map-name>) <key fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
This is used to delete an entry from a MAP. <map-name> must follow the format described in 2.7.
about name format for maps and ACLs. The name of the MAP to be updated is passed between
parentheses. It takes one argument: <key fmt>, which follows Custom log format rules of section
8.2.6
, 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.
deny [ { status | deny_status } <code> ] [ content-type <type> ]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
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.
dgram-drop
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | - | - | - | - | - | - | -
This silently ignores the reception of a QUIC initial packet which otherwise would have resulted in a new QUIC connection instantiation and its SSL handshake execution.
disable-l7-retry
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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.
do-log [profile <log_profile>]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | X | X | X | X | X | X | X
This action manually triggers a log emission on the proxy. This means log options on the proxy will be considered (including formatting options such as “log-format”), but it will not interfere with the logs automatically generated by the proxy during transaction handling.
Using “log-profile”, it is possible to precisely describe how the log should be emitted for each of the available contexts where the action may be used. That is, ‘on’ keyword followed by of the following values: ‘quic-init’, ’tcp-req-conn’, ’tcp-req-sess’, ’tcp-req-cont’, ’tcp-res-cont’, ‘http-req’, ‘http-res’, ‘http-after-res’.
Also, they will be properly reported when using “%OG” logformat alias.
Optional “profile” argument may be used to specify the name of a log-profile section that should be used for this do-log action specifically instead of the one associated to the current logger that applies by default.
Example:
do-resolve(<var>,<resolvers>[,ipv4|ipv6]) <expr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
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’. See also the global
“dns-accept-family” keyword to enforce strict usage of a specific family.
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:
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…
early-hint <name> <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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 Custom Log Format rules (see Custom log format in section 8.2.6
). This is
particularly useful to pass to the client some Link headers to preload resources required to render
the HTML documents.
See RFC 8297 for more information.
expect-netscaler-cip layer4
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | - | - | - | - | - | -
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.
expect-proxy layer4
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | - | - | - | - | - | -
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.
normalize-uri <normalizer>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
Performs normalization of the request’s URI.
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.
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.
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.
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.
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.
The following normalizers are available:
fragment-encode: Encodes “#” as “%23”.
The “fragment-strip” normalizer should be preferred, unless it is known that broken clients do not correctly encode ‘#’ within the path component.
Example:
- /#foo -> /%23foo
fragment-strip: Removes the URI’s “fragment” component.
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.
This normalizer should be applied first to ensure that the fragment is not interpreted as part of the request’s path component.
Example:
- /#foo -> /
path-strip-dot: Removes “/./” segments within the “path” component (RFC 3986#6.2.2.3).
Segments including percent encoded dots ("%2E”) will not be detected. Use the “percent-decode-unreserved” normalizer first if this is undesired.
Example:
- /. -> /
- /./bar/ -> /bar/
- /a/./a -> /a/a
- /.well-known/ -> /.well-known/ (no change)
path-strip-dotdot: Normalizes “/../” segments within the “path” component (RFC 3986#6.2.2.3).
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.
Segments including percent encoded dots ("%2E") will not be detected. Use the “percent-decode-unreserved” normalizer first if this is undesired.
Example:
- /foo/../ -> /
- /foo/../bar/ -> /bar/
- /foo/bar/../ -> /foo/
- /../bar/ -> /../bar/
- /bar/../../ -> /../
- /foo//../ -> /foo/
- /foo/%2E%2E/ -> /foo/%2E%2E/
If the “full” option is specified then “../” at the beginning will be removed as well:
Example:
- /../bar/ -> /bar/
- /bar/../../ -> /
path-merge-slashes: Merges adjacent slashes within the “path” component into a single slash.
Example:
- // -> /
- /foo//bar -> /foo/bar
percent-decode-unreserved: Decodes unreserved percent encoded characters to their representation as a regular character (RFC 3986#6.2.2.2).
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
If the “strict” option is specified then invalid sequences will result in a HTTP 400 Bad Request being returned.
Example:
- /%%36%36 -> HTTP 400
- /%ZZ -> HTTP 400
percent-to-uppercase: Uppercases letters within percent-encoded sequences (RFC 3986#6.2.2.1).
Example:
- /%6f -> /%6F
- /%zz -> /%zz
If the “strict” option is specified then invalid sequences will result in a HTTP 400 Bad Request being returned.
Example:
- /%zz -> HTTP 400
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.
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
pause { <timeout> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
This suspends the message analysis for the specified number of milliseconds. 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. If the expression evaluation fails or if it returns an invalid value, the action is ignored and the evaluation continues.
This action may be used for debugging purpose. But it could also be used to slow down some clients based on specific criteria. For instance, it is possible to slow down clients if their requests rate is too high, by tracking them via a “track-sc” rule.
redirect <rule>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
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 Custom log format. 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.
reject
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | X | X | X | X | X | - | -
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.
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.
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.
This action can also be used in “quic-initial” rules. The newly opened QUIC connection is immediately closed without any SSL handshake processing and the client is notified via a CONNECTION_REFUSED error code.
replace-header <name> <match-regex> <replace-fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
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 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.
Example:
Example:
replace-path <match-regex> <replace-fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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.
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:
replace-pathq <match-regex> <replace-fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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.
Example:
replace-uri <match-regex> <replace-fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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.
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.
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.
Example:
replace-value <name> <match-regex> <replace-fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
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.
Example:
Example:
return [ status <code> ] [ content-type <type> ]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
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:
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.
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, 414, 425, 429, 431, 500, 501, 502, 503, and 504). The “content-type” argument, if any, is ignored.
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, 414, 425, 429, 431, 500, 501, 502, 503, and 504). The “content-type” argument, if any, is ignored.
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, 414, 425, 429, 431, 500, 501, 502, 503, and 504). The “content-type” argument, if any, is ignored.
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 Custom log format (see section 8.2.6 ). 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 Custom log format (see section 8.2.6 ). With a “string” argument, it is considered as a raw string.
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 Custom log
format rules described in section 8.2.6
.
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 action is final, i.e. no further rules from the same rule set are evaluated for the current section.
Example:
sc-add-gpc(<idx>,<sc-id>) { <int> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
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.
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.
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).
sc-inc-gpc(<idx>,<sc-id>)
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
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).
sc-inc-gpc0(<sc-id>)
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
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.
sc-set-gpt(<idx>,<sc-id>) { <int> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
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).
sc-set-gpt0(<sc-id>) { <int> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
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.
send-retry
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft X | - | - | - | - | - | - | -
This action forces the emission of a Retry packet in response to a client Initial packet without token. This is useful to ensure client address is validated prior to instantiating any connection elements and starting the handshake.
send-spoe-group <engine-name> <group-name>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | X | X | X | -
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:
set-bandwidth-limit <name> [limit {<expr> | <size>}] [period {<expr> | <time>}]
Usable in: QUIC Ini| 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. 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:
Example:
See section 9.7 about bandwidth limitation filter setup.
set-bc-mark { <mark> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
This is used to set the Netfilter/IPFW MARK on the backend connection (all packets sent to the
server) to the value passed in <mark> or <expr> 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. <mark> can be expressed both in decimal or hexadecimal format
(prefixed by “0x”). Alternatively, <expr> can be used: it is a standard HAProxy expression formed
by a sample-fetch followed by some converters which must resolve to integer type. This action 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. The mark will be set for the whole duration of the backend/server connection
(from connect to close).
set-bc-tos { <tos> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
This is used to set the TOS or DSCP field value on the backend connection (all packets sent to the
server) to the value passed in <tos> or <expr> on platforms which support this. This value
represents the whole 8 bits of the IP TOS field. Note that only the 6 higher bits are used in DSCP
or TOS, and the two lower bits are always 0. Alternatively, <expr> can be used: it is a standard
HAProxy expression formed by a sample-fetch followed by some converters which must resolve to
integer type. This action can be used to adjust some routing behavior on inner routers based on some
information from the request. The tos will be set for the whole duration of the backend/server
connection (from connect to close).
See RFC 2474, 2597, 3260 and 4594 for more information.
set-dst <expr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
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.
Arguments:
Example:
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.
set-dst-port <expr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
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.
Arguments:
Example:
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.
set-fc-mark { <mark> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | -
This is used to set the Netfilter/IPFW MARK on all packets sent to the client to the value passed in
<mark> or <expr> 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.
<mark> can be expressed both in decimal or hexadecimal format (prefixed by “0x”). Alternatively,
<expr> can be used: it is a standard HAProxy expression formed by a sample-fetch followed by some
converters which must resolve to integer type. This action 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.
set-fc-tos { <tos | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | -
This is used to set the TOS or DSCP field value of packets sent to the client to the value passed in
<tos> or <expr> on platforms which support this. This value represents the whole 8 bits of the
IP TOS field. Note that only the 6 higher bits are used in DSCP or TOS, and the two lower bits are
always 0. Alternatively, <expr> can be used: it is a standard HAProxy expression formed by a
sample-fetch followed by some converters which must resolve to integer type. This action can be used
to adjust some routing behavior on border routers based on some information from the request.
See RFC 2474, 2597, 3260 and 4594 for more information.
set-header <name> <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
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.
Example:
set-headers-bin <expr> [ prefix <str> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
This is a variant of the “set-header” action where the header names and values are passed as a
varint encoded binary string. See the “req.hdrs_bin” sample fetch about the varint format. This is
useful when you want to set multiple headers at once, without having to know the header names in
advance. Note that these headers have not been validated by the HTTP parser and could lead to
emitting invalid messages and in worst cases lead to request smuggling attacks. The number of
headers inserted are also of importance, as that is limited by tune.http.maxhdr. Optional prefix
will only set the headers from the encoded string that start with <str>.
Example:
set-log-level <level>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | X | X | X | X
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.
set-map(<map-name>) <key fmt> <value fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
This is used to add a new entry into a map. <map-name> must follow the format described in 2.7.
about name format for maps and ACLs. The name of the MAP to be updated is passed between
parentheses. It takes 2 arguments: <key fmt>, which follows Custom log format rules described in
section 8.2.6
, used to collect map key, and <value fmt>, which follows Custom 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.
set-mark <mark> (deprecated)
This is an alias for “set-fc-mark” (which should be used instead).
set-method <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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.
set-nice <nice>
Usable in: QUIC Ini| 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.
set-path <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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:
set-pathq <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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”).
set-priority-class <expr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
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.
set-priority-offset <expr>
Usable in: QUIC Ini| 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.
set-query <fmt>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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.
See also “http-request set-query” and “http-request set-uri”.
Example:
set-retries <int> | <epxr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | X | - | -
This action overrides the specified “retries” value for the current stream only. It can be an integer value, in the range [0, 100], or an expression which must return a integer in the range [0, 100].
Note that this action is only relevant on the backend side and thus this rule is only available for the proxies with backend capability. It is also not allowed in “defaults” sections. When the action is used for a listener, it is evaluated in the frontend context. So retries value is conserved only if stream is not routed to a different backend, via a use-backend rule for instance. Otherwise the default retries value of the selected backend will be preset.
Example:
set-src <expr>
Usable in: QUIC Ini| 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).
Arguments:
See also “option forwardfor”.
Example:
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.
set-src-port <expr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | - | -
This is used to set the source port address to the value of specified expression.
Arguments:
Example:
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.
set-status <status> [reason <str>]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | - | X | X
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.
Example:
set-timeout { client | connect | queue | server | tarpit | tunnel } { <timeout> | <expr> }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
This action overrides the specified “client”, “connect”, “queue”, “server”, “tarpit” or “tunnel” timeout for the current stream only. Changing one timeout does not influence any other timeouts, even if they are inherited from each other during configuration parsing (see last example). 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.
Note that the connect, queue, server and 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. Tarpit timeout is available to both sides. The timeout value must be non-null to obtain the expected results. When the action is used for a listener, it is evaluated in the frontend context. So custom values for backend-side timeouts are conserved only if stream is not routed to a different backend, via a use-backend rule for instance. Otherwise the default values of the selected backend will be preset.
Example:
Example:
Example:
set-tos <tos> (deprecated)
This is an alias for “set-fc-tos” (which should be used instead).
set-uri <fmt>
Usable in: QUIC Ini| 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”.
set-var(<var-name>[,<cond>...]) <expr>
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
This is used to set the contents of a variable. The variable is declared inline.
Arguments:
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”.
Example:
silent-drop [ rst-ttl <ttl> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | 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. 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.
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.
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 equipment. 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.
strict-mode { on | off }
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | X
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.
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.
switch-mode http [ proto <name> ]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | X | - | - | - | -
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 section 4 about Proxies for more details on HTTP upgrades.
tarpit [ { status | deny_status } <code>] [content-type <type>]
file `<file>` | lf-file `<file>` | string `<str>` | lf-string `<fmt>` } ]
[ hdr `<name>` `<fmt>` ]*
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | - | -
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”.
track-sc0 <key> [table <table>]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | - | X | X | -
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.
Arguments:
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.
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.
unset-var(<var-name>)
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | X | X | X | X | X | X | X
This is used to unset a variable. See the “set-var” action for details about <var-name>.
Example:
use-service <service-name>
Usable in: QUIC Ini| 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.
Arguments:
Example:
wait-for-body time <time> [ at-least <bytes> ] [use-large-buffer]
Usable in: QUIC Ini| TCP RqCon| RqSes| RqCnt| RsCnt| HTTP Req| Res| Aft - | - | - | - | - | X | X | -
This will delay the processing of the request or response until one of the following conditions occurs:
- The full request body is received, in which case processing proceeds normally.
<bytes>bytes have been received, when the “at-least” argument is given and<bytes>is non-zero, in which case processing proceeds normally.- The request buffer is full, in which case processing proceeds normally. The size of this buffer is determined by the “tune.bufsize” option.
- The request has been waiting for more than
<time>milliseconds. In this case HAProxy will respond with a 408 “Request Timeout” error to the client and stop processing the request. Note that if any of the other conditions happens first, this timeout will not occur even if the full body has not yet been received.
“use-large-buffer” option may be set to allocate a large buffer if regular one is to small to store the message body. To be used, “tune.bufsize.large” global option must be defined.
This action may be used as a replacement for “option http-buffer-request”.
Arguments:
Example:
See also: “option http-buffer-request” and “tune.bufsize.large”
wait-for-handshake
Usable in: QUIC Ini| 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.