HAProxy 3.4.4
5. Bind and Server Options
Complete English Markdown edition of the HAProxy 3.4 Starter, Configuration, and Management manuals
The “bind”, “server” and “default-server” keywords support a number of settings depending on some build options and on the system HAProxy was built on. These settings generally each consist in one word sometimes followed by a value, written on the same line as the “bind” or “server” line. All these options are described in this section.
5.1. Bind options
The “bind” keyword supports a certain number of settings which are all passed as arguments on the same line. The order in which those arguments appear makes no importance, provided that they appear after the bind address. All of these parameters are optional. Some of them consist in a single words (booleans), while other ones expect a value after them. In this case, the value must be provided immediately after the setting name.
The currently supported settings are the following ones.
accept-netscaler-cip <magic number>
Enforces the use of the NetScaler Client IP insertion protocol over any connection accepted by any of the TCP sockets declared on the same line. The NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of the incoming connection to be used everywhere an address is used, with the only exception of “tcp-request connection” rules which will only see the real connection address. Logs will reflect the addresses indicated in the protocol, unless it is violated, in which case the real address will still be used. This keyword combined with support from external components can be used as an efficient and reliable alternative to the X-Forwarded-For mechanism which is not always reliable and not even always usable. See also “tcp-request connection expect-netscaler-cip” for a finer-grained setting of which client is allowed to use the protocol.
accept-proxy
Enforces the use of the PROXY protocol over any connection accepted by any of the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol are supported and correctly detected. The PROXY protocol dictates the layer 3/4 addresses of the incoming connection to be used everywhere an address is used, with the only exception of “tcp-request connection” rules which will only see the real connection address. Logs will reflect the addresses indicated in the protocol, unless it is violated, in which case the real address will still be used. This keyword combined with support from external components can be used as an efficient and reliable alternative to the X-Forwarded-For mechanism which is not always reliable and not even always usable. See also “tcp-request connection expect-proxy” for a finer-grained setting of which client is allowed to use the protocol.
allow-0rtt
Allow receiving early data when using TLSv1.3. This is disabled by default, due to security considerations. Because it is vulnerable to replay attacks, you should only allow if for requests that are safe to replay, i.e. requests that are idempotent. You can use the “wait-for-handshake” action for any request that wouldn’t be safe with early data. With QUIC, 0rtt is supported with QuicTLS, OpenSSL >= 3.5.2 and AWS-LC. With TCP/TLS, 0rtt is only supported with OpenSSL, and requires that the client sends an ALPN, otherwise the early data won’t be considered before the handshake happens.
alpn <protocols>
This enables the TLS ALPN extension and advertises the specified protocol list as supported on top of ALPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). This requires that the SSL library is built with support for TLS extensions enabled (check with haproxy -vv). The ALPN extension replaces the initial NPN extension. At the protocol layer, ALPN is required to enable HTTP/2 on an HTTPS frontend and HTTP/3 on a QUIC frontend. However, when such frontends have none of “npn”, “alpn” and “no-alpn” set, a default value of “h2,http/1.1” will be used for a regular HTTPS frontend, and “h3” for a QUIC frontend. Versions of OpenSSL prior to 1.0.2 didn’t support ALPN and only supposed the now obsolete NPN extension. At the time of writing this, most browsers still support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for a while. But ALPN must be used whenever possible. Protocols not advertised are not negotiated. For example it is possible to only accept HTTP/2 connections with this:
QUIC supports only h3 and hq-interop as ALPN. h3 is for HTTP/3 and hq-interop is used for http/0.9 and QUIC interop runner (see https://interop.seemann.io ). Each “alpn” statement will replace a previous one. In order to remove them, use “no-alpn”.
Note that some old browsers such as Firefox 88 used to experience issues with WebSocket over H2, and in case such a setup is encountered, it may be needed to either explicitly disable HTTP/2 in the “alpn” string by forcing it to “http/1.1” or “no-alpn”, or to enable “h2-workaround-bogus-websocket-clients” globally.
backlog <backlog>
Sets the socket’s backlog to this value. If unspecified or 0, the frontend’s backlog is used instead, which generally defaults to the maxconn value.
ca-file <cafile>
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load CA certificates used to verify client’s certificate. It is possible to load a directory containing multiple CAs, in this case HAProxy will try to load every “.pem”, “.crt”, “.cer”, and .crl" available in the directory, files starting with a dot are ignored.
Warning: The “@system-ca” parameter could be used in place of the cafile in order to use the trusted CAs of your system, like its done with the server directive. But you mustn’t use it unless you know what you are doing. Configuring it this way basically mean that the bind will accept any client certificate generated from one of the CA present on your system, which is extremely insecure.
ca-ignore-err [all|<errorID>,...]
This setting is only available when support for OpenSSL was built in. Sets a comma separated list of errorIDs to ignore during verify at depth > 0. It could be a numerical ID, or the constant name (X509_V_ERR) which is available in the OpenSSL documentation: https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get_error.html#ERROR-CODES It is recommended to use the constant name as the numerical value can change in new version of OpenSSL. If set to ‘all’, all errors are ignored. SSL handshake is not aborted if an error is ignored.
ca-sign-file <cafile>
This setting is only available when support for OpenSSL was built in. It designates a PEM file containing both the CA certificate and the CA private key used to create and sign server’s certificates. This is a mandatory setting when the dynamic generation of certificates is enabled. See ‘generate-certificates’ for details.
ca-sign-pass <passphrase>
This setting is only available when support for OpenSSL was built in. It is the CA private key passphrase. This setting is optional and used only when the dynamic generation of certificates is enabled. See ‘generate-certificates’ for details.
ca-verify-file <cafile>
This setting designates a PEM file from which to load CA certificates used to verify client’s certificate. It designates CA certificates which must not be included in CA names sent in server hello message. Typically, “ca-file” must be defined with intermediate certificates, and “ca-verify-file” with certificates to ending the chain, like root CA.
cc <algo>
This setting is only available on systems which define TCP_CONGESTION, and was validated on Linux and FreeBSD. It takes the name of a TCP congestion control algorithm and configures the listener to use this algorithm on all connections that are accepted from this listener. Typical names include “reno”, “cubic” and will depend on the operating system. On some systems, special permissions may be required to configure certain algorithms. On Linux, the list of available algorithms may be found in the sysctl “net.ipv4.tcp_available_congestion_control”, and the list of those permitted without privileges is in “net.ipv4.tcp_allowed_congestion_control”. In order to access algorithms requiring extra permissions, the “cap_net_admin” capability might be required (see “setcap” in the global section). In case of failure to configure a specific congestion control algorithm, the default one will remain unchanged and a warning will be emitted to report the problem. See also: the “cc” server keyword (section 5.2 ). Example:
ciphers <ciphers>
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of cipher algorithms (“cipher suite”) that are negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the string is defined in “man 1 ciphers” from OpenSSL man pages. For background information and recommendations see e.g. (https://wiki.mozilla.org/Security/Server_Side_TLS ) and (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). For TLSv1.3 cipher configuration, please check the “ciphersuites” keyword.
ciphersuites <ciphersuites>
This setting is only available when support for OpenSSL was built in and OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing the list of cipher algorithms (“cipher suite”) that are negotiated during the TLSv1.3 handshake. The format of the string is defined in “man 1 ciphers” from OpenSSL man pages under the “ciphersuites” section. For cipher configuration for TLSv1.2 and earlier, please check the “ciphers” keyword. This setting might accept TLSv1.2 ciphersuites however this is an undocumented behavior and not recommended as it could be inconsistent or buggy. The default TLSv1.3 ciphersuites of OpenSSL are: “TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256”
TLSv1.3 only supports 5 ciphersuites:
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_AES_128_CCM_SHA256
- TLS_AES_128_CCM_8_SHA256
Example:
ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256client-sigalgs <sigalgs>
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of signature algorithms related to client authentication that are negotiated . The format of the string is defined in “man 3 SSL_CTX_set1_client_sigalgs” from the OpenSSL man pages. It is not recommended to use this setting if no specific usecase was identified.
crl-file <crlfile>
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load certificate revocation list used to verify client’s certificate. You need to provide a certificate revocation list for every certificate of your certificate authority chain.
crt <cert>
This setting is only available when support for OpenSSL was built in.
HAProxy uses a cache system, the files are loaded only once in the certificate storage, and each next “crt” keyword will use this cached version. When the certificate was declared in a “crt-store”, the certificate storage is populated from there and don’t try to load additional files by detecting file extensions.
It designates a PEM file containing both the required certificates and any associated private keys. This file can be built by concatenating multiple PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA requires an intermediate certificate, this can also be concatenated into this file. Intermediate certificate can also be shared in a directory via “issuers-chain-path” directive.
If the file does not contain a private key, HAProxy will try to load the key at the same path suffixed by a “.key”.
If the OpenSSL used supports Diffie-Hellman, parameters present in this file are loaded.
If a directory name is used instead of a PEM file, then all files found in that directory will be loaded in alphabetic order unless their name ends with ‘.key’, ‘.issuer’, ‘.ocsp’ or ‘.sctl’ (reserved extensions). Files starting with a dot are also ignored. This directive may be specified multiple times in order to load certificates from multiple files or directories. The certificates will be presented to clients who provide a valid TLS Server Name Indication field matching one of their CN or alt subjects. Wildcards are supported, where a wildcard character ‘*’ is used instead of the first hostname component (e.g. *.example.org matches www.example.org but not www.sub.example.org ). If an empty directory is used, HAProxy will not start unless the “strict-sni” keyword is used.
If no SNI is provided by the client or if the SSL library does not support TLS extensions, or if the client provides an SNI hostname which does not match any certificate, then the first loaded certificate will be presented. This means that when loading certificates from a directory, it is highly recommended to load the default one first as a file or to ensure that it will always be the first one in the directory. In order to chose multiple default certificates (1 rsa and 1 ecdsa), there are 3 options:
- A multi-cert bundle can be configured as the first certificate (
crt foobar.pemin the configuration where the existing files arefoobar.pem.ecdsaandfoobar.pem.rsa. - Or a ‘*’ filter for each certificate in a crt-list line.
- The ‘default-crt’ keyword can be used.
Note that the same cert may be loaded multiple times without side effects.
Some CAs (such as GoDaddy) offer a drop down list of server types that do not include HAProxy when obtaining a certificate. If this happens be sure to choose a web server that the CA believes requires an intermediate CA (for GoDaddy, selection Apache Tomcat will get the correct bundle, but many others, e.g. nginx, result in a wrong bundle that will not work for some clients).
For each PEM file, HAProxy checks for the presence of file at the same path suffixed by “.ocsp”. If such file is found, support for the TLS Certificate Status Request extension (also known as “OCSP stapling”) is automatically enabled. The content of this file is optional. If not empty, it must contain a valid OCSP Response in DER format. In order to be valid an OCSP Response must comply with the following rules: it has to indicate a good status, it has to be a single response for the certificate of the PEM file, and it has to be valid at the moment of addition. If these rules are not respected the OCSP Response is ignored and a warning is emitted. In order to identify which certificate an OCSP Response applies to, the issuer’s certificate is necessary. If the issuer’s certificate is not found in the PEM file, it will be loaded from a file at the same path as the PEM file suffixed by “.issuer” if it exists otherwise it will fail with an error.
For each PEM file, HAProxy also checks for the presence of file at the same path suffixed by “.sctl”. If such file is found, support for Certificate Transparency (RFC6962) TLS extension is enabled. The file must contain a valid Signed Certificate Timestamp List, as described in RFC. File is parsed to check basic syntax, but no signatures are verified.
There are cases where it is desirable to support multiple key types, e.g. RSA and ECDSA in the cipher suites offered to the clients. This allows clients that support EC certificates to be able to use EC ciphers, while simultaneously supporting older, RSA only clients.
To achieve this, OpenSSL 1.1.1 is required, you can configure this behavior by providing one crt entry per certificate type, or by configuring a “cert bundle” like it was required before HAProxy 1.8. See “ssl-load-extra-files”.
crt-ignore-err <errors>
This setting is only available when support for OpenSSL was built in. Sets a comma separated list of errorIDs to ignore during verify at depth == 0. It could be a numerical ID, or the constant name (X509_V_ERR) which is available in the OpenSSL documentation: https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get_error.html#ERROR-CODES It is recommended to use the constant name as the numerical value can change in new version of OpenSSL. If set to ‘all’, all errors are ignored. SSL handshake is not aborted if an error is ignored.
crt-list <file>
This setting is only available when support for OpenSSL was built in. It designates a list of PEM file with an optional ssl configuration and a SNI filter per certificate, with the following format for each line:
Empty lines as well as lines beginning with a hash (’#’) will be ignored.
The crt-list can be manipulated dynamically over the stats socket. (See “add ssl crt-list”, “del ssl crt-list”, “show ssl crt-list” in the management guide).
crt-list are usually dedicated files, however a directory loaded with the “crt” directive is represented internally as a crt-list. The “ssl-f-use” directive in a frontend also declares a crt-list linked to this frontend.
crtfile:
This is the filename of the certificate, or an identifier if it was declared
elsewhere (over the CLI or in a crt-store with an alias for example).
It is possible to use the same <crtfile> on multiple lines with different
options and filters.
Multi-cert bundling (see "ssl-load-extra-files") is supported in a
crt-list, as long as only the base name is given in <crtfile>. HAProxy
will duplicate the crt-list line internally, adding an algorithm extension
(.rsa, .ecdsa, .dsa) when loading the file.sslbindconf:
<sslbindconf> supports the following keywords from the bind line (see
Section 5.1. Bind options):
- allow-0rtt
- alpn
- ca-file
- ca-verify-file
- ciphers
- ciphersuites
- client-sigalgs
- crl-file
- curves
- ecdhe
- no-alpn
- no-ca-names
- npn
- sigalgs
- ssl-min-ver
- ssl-max-ver
- verify
<sslbindconf> also supports the following keywords from the crt-store load
keyword (see Section 12.7.1. Load options):
- crt
- key
- ocsp
- issuer
- sctl
- ocsp-update
Parameters from the bind line are inherited in <sslbindconf>, if none were
specified, the default options are inherited, the parameters specified in
<sslbindconf> overwrite those inherited settings.snifilter:
When the <snifilter> parameter is used on a crt-list line, the CN and SAN
are not used anymore to select the certificate on this line during the
handshake but the <snifilter> is used instead.
<snifilter> is a list of entries separated by spaces. This list can contain
domains, or wildcards. The wildcards are in wildcard DNS format, using a
single asterisk as the first character of the entry. It is possible to
exclude a domain from a wildcard with a negative filter by specifying a '!'
in front of a single domain. Having a ! in front of a * is ignored. Having
negative filters without a wildcard on the same line is not supported as
well. The special entry '*' is used to specify default certificates, which
are used as fallback when no domain matched.
The certificates will be presented to clients who provide a valid TLS
Server Name Indication field matching one of the SNI filters, or the CN and
SAN of a <crtfile>. The matching algorithm first looks for a positive domain
entry in the list, if not found it will try to look for a wildcard in the
list. If a wildcard match, haproxy checks for a negative filter from the
same line and unmatch if necessary. In case of multiple key algorithms
(RSA,ECDSA,DSA), HAProxy will try to match one certificate per type and
chose the right one depending on what is supported by the client.
If no SNI is presented by the client or if no certificate matched, this
will fallback to one of the default certificate. To disable the default
certificate fallback, the 'strict-sni' option may be used.
When multiple default certificates are defined, HAProxy is able to chose
the right ECDSA or RSA one depending on what the client supports.
The first declared certificate of a bind line is used as a default
certificate, either from crt or crt-list option.
It is also possible to declare a '*' filter, which will add this
certificate to the list of default certificates. To clarify the
configuration, the default certificates could be explicit (with a '*'
filter) at the beginning of the list, so an implicit default is not added
before.
Due to multi-cert bundles being duplicated for each algorithm in the
crt-list, only one algorithm will occupy the first line in the crt-list and
be considered as default. Either specify the entire bundle as default by
declaring '*' as the filter or setting it on the bind line.
The "show ssl sni" command on the stats socket could be used to debug your
configuration. (See "show ssl sni" in the management guide)Example:
# comment
default.pem.rsa *
default.pem.ecdsa *
cert2.pem [alpn h2,http/1.1]
certW.pem *.domain.tld !secure.domain.tld
certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
foo.crt [key bar.pem ocsp foo.ocsp ocsp-update on] foo.bar.comdefault-crt <cert>
This option does the same as the “crt” option, with the difference that this certificate will be used as a default one as well. It is possible to add multiple default certificates to have an ECDSA and an RSA one, having more is not really useful.
This option does not disable implicit default certificates, if a ‘crt’ certificate is declared first before any ‘default-crt’ or other ‘crt’ it will still be used as a default certificate.
A default certificate is used when no “strict-sni” option is used on the bind line. A default certificate is provided when the servername extension was not used by the client, or when the servername does not match any configured certificate.
Example:
# this bind line has 2 default certificates
bind *:443 default-crt foobar.pem.rsa default-crt foobar.pem.ecdsa crt website.pem.rsa
# this bind line has 3 default certificates
bind *:443 crt website.pem.rsa default-crt foobar.pem.rsa default-crt foobar.pem.ecdsaSee also the “crt” keyword.
curves <curves>
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of elliptic curves algorithms (“curve suite”) that are negotiated during the SSL/TLS handshake with ECDHE. The format of the string is a colon-delimited list of curve name. Example: “X25519:P-256” (without quote) When “curves” is set, “ecdhe” parameter is ignored.
defer-accept
Is an optional keyword which is supported only on certain Linux kernels. It states that a connection will only be accepted once some data arrive on it, or at worst after the first retransmit. This should be used only on protocols for which the client talks first (e.g. HTTP). It can slightly improve performance by ensuring that most of the request is already available when the connection is accepted. On the other hand, it will not be able to detect connections which don’t talk. It is important to note that this option is broken in all kernels up to 2.6.31, as the connection is never accepted until the client talks. This can cause issues with front firewalls which would see an established connection while the proxy will only see it in SYN_RECV. This option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
ecdhe <named curve>
This setting is only available when support for OpenSSL was built in. It sets the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default, used named curve is prime256v1.
ech <dir> [ EXPERIMENTAL ]
Apply all ECH keys from <dir> to the bind line. The files must have the .ech extension and must
use the PEM file format for ECH. ( https://datatracker.ietf.org/doc/draft-farrell-tls-pemesni/
)
This keyword enables ECH in shared-mode. with HAProxy acting as both the TLS endpoint and the ECH endpoint. See https://datatracker.ietf.org/doc/draft-ietf-tls-esni/
This is an experimental feature, which requires the “expose-experimental-directives” option in the global section. It also necessitates an OpenSSL version that supports ECH ( https://github.com/openssl/openssl/tree/feature/ech ), and HAProxy must be compiled with USE_ECH=1. The ECH API of AWS-LC is not supported.
Example:
$ openssl ech -public_name foobar.com -out /etc/haproxy/echkeydir/foobar.com.ech
$ cat haproxy.cfg
[...]
bind:443 ech /etc/haproxy/echkeydir/ ssl crt example.com.pem
// Use the ECHCONFIG section of your .ech file
$ openssl s_client -tls1_3 -connect example.com:443 -servername example.com \
-ech_config_list AD3+DQA5cwAgACB6ybtgtFYoM5r8nJSotus4c7K0EG..9vYmFyLmNvbQAAexpose-fd listeners
This option is only usable with the stats socket. It gives your stats socket the capability to pass listeners FD to another HAProxy process. In master-worker mode, this is not required anymore, the listeners will be passed using the internal socketpairs between the master and the workers. See also “-x” in the management guide.
force-sslv3
This option enforces use of SSLv3 only on SSL connections instantiated from this listener. SSLv3 is generally less expensive than the TLS counterparts for high connection rates. This option is also available on global statement “ssl-default-bind-options”. See also “ssl-min-ver” and “ssl-max-ver”.
force-tlsv10
This option enforces use of TLSv1.0 only on SSL connections instantiated from this listener. This option is also available on global statement “ssl-default-bind-options”. See also “ssl-min-ver” and “ssl-max-ver”.
force-tlsv11
This option enforces use of TLSv1.1 only on SSL connections instantiated from this listener. This option is also available on global statement “ssl-default-bind-options”. See also “ssl-min-ver” and “ssl-max-ver”.
force-tlsv12
This option enforces use of TLSv1.2 only on SSL connections instantiated from this listener. This option is also available on global statement “ssl-default-bind-options”. See also “ssl-min-ver” and “ssl-max-ver”.
force-tlsv13
This option enforces use of TLSv1.3 only on SSL connections instantiated from this listener. This option is also available on global statement “ssl-default-bind-options”. See also “ssl-min-ver” and “ssl-max-ver”.
generate-certificates
This setting is only available when support for OpenSSL was built in. It enables the dynamic SSL certificates generation. A CA certificate and its private key are necessary (see ‘ca-sign-file’). When HAProxy is configured as a transparent forward proxy, SSL requests generate errors because of a common name mismatch on the certificate presented to the client. With this option enabled, HAProxy will try to forge a certificate using the SNI hostname indicated by the client. This is done only if no certificate matches the SNI hostname (see ‘crt-list’).
In the event of a certificate generation error, the connection will fall back on the default certificate. When using ‘strict-sni’, the default certificate will not be used and the connection will result in a handshake failure.
It can also be used when HAProxy is configured as a reverse proxy to ease the deployment of an architecture with many backends.
Creating a SSL certificate is an expensive operation, so a LRU cache is used to store forged certificates (see ’tune.ssl.ssl-ctx-cache-size’). It increases the HAProxy’s memory footprint to reduce latency when the same certificate is used many times.
gid <gid>
Sets the group of the UNIX sockets to the designated system gid. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “group” setting except that the group ID is used instead of its name. This setting is ignored by non UNIX sockets.
group <group>
Sets the group of the UNIX sockets to the designated system group. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “gid” setting except that the group name is used instead of its gid. This setting is ignored by non UNIX sockets.
guid-prefix <string>
Generate case-sensitive global unique IDs for each listening sockets allocated on this bind line. Prefix will be concatenated to listeners position index on the current bind line, with character ‘-’ as separator. See “guid” proxy keyword description for more information on its format. See also “shm-stats-file”.
id <id>
Fixes the socket ID. By default, socket IDs are automatically assigned, but sometimes it is more convenient to fix them to ease monitoring. This value must be strictly positive and unique within the listener/frontend. This option can only be used when defining only a single socket.
idle-ping <delay>
May be used in the following contexts: tcp, http, log
Define an interval for periodic liveliness on idle frontend connections. If the peer is unable to respond before the next scheduled test, the connection is closed. Else, the client timeout is refreshed and the connection is kept. Note that http-request/http-keep-alive timers run in parallel and are not refreshed by idle-ping.
This feature relies on specific underlying protocol support. For now, only H2 mux implements it. Idle-ping is simply ignored by other protocols.
This option is particularly useful when using reverse HTTP. Setting it on the bind line is useful for the peer which is responsible to actively initiate connections and will then receive incoming traffic through them.
interface <interface>
Restricts the socket to a specific interface. When specified, only packets received from that particular interface are processed by the socket. This is currently only supported on Linux. The interface must be a primary system interface, not an aliased interface. It is also possible to bind multiple frontends to the same address if they are bound to different interfaces. Note that binding to a network interface requires root privileges. This parameter is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic uses the same interface as inbound traffic, and its associated routing table, even if there are explicit routes through different interfaces configured. This can prove useful to address asymmetric routing issues when the same client IP addresses need to be able to reach frontends hosted on different interfaces.
ktls <on|off> [ EXPERIMENTAL ]
Enables or disables ktls for those sockets. If enabled, kTLS will be used if the kernel supports it and the cipher is compatible. This is only available on Linux kernel 4.17 and above. Please note that some network drivers and/or TLS stacks might restrict kTLS usage to TLS v1.2 only. See also “force-tlsv12”.
label <label>
Sets an optional label for these sockets. It could be used group sockets by label, independently of where the bind lines were declared.
level <level>
This setting is used with the stats sockets only to restrict the nature of the commands that can be
issued on the socket. It is ignored by other sockets. <level> can be one of:
- “user” is the least privileged level; only non-sensitive stats can be read, and no change is allowed. It would make sense on systems where it is not easy to restrict access to the socket.
- “operator” is the default level and fits most common uses. All data can be read, and only non-sensitive changes are permitted (e.g. clear max counters).
- “admin” should be used with care, as everything is permitted (e.g. clear all counters).
maxconn <maxconn>
Limits the sockets to this number of concurrent connections. Extraneous connections will remain in the system’s backlog until a connection is released. If unspecified, the limit will be the same as the frontend’s maxconn. Note that in case of port ranges or multiple addresses, the same value will be applied to each socket. This setting enables different limitations on expensive sockets, for instance SSL entries which may easily eat all memory.
mode <mode>
Sets the octal mode used to define access permissions on the UNIX socket. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is ignored by non UNIX sockets.
mss <maxseg>
Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming connections. This can be used to force a lower MSS for certain specific ports, for instance for connections passing through a VPN. Note that this relies on a kernel feature which is theoretically supported under Linux but was buggy in all versions prior to 2.6.28. It may or may not work on other operating systems. It may also not change the advertised value but change the effective size of outgoing segments. The commonly advertised value for TCPv4 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is positive, it will be used as the advertised MSS. If it is negative, it will indicate by how much to reduce the incoming connection’s advertised MSS for outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
name <name>
Sets an optional name for these sockets, which will be reported on the stats page.
namespace <name>
On Linux, it is possible to specify which network namespace a socket will belong to. This directive makes it possible to explicitly bind a listener to a namespace different from the default one. Please refer to your operating system’s documentation to find more details about network namespaces.
nbconn <nbconn> [ EXPERIMENTAL ]
This setting is only valid for listener instances which uses reverse HTTP. This will define the count of connections which will be mounted in parallel. If not specified, a default value of 1 is used.
Reverse HTTP is currently still in active development. Configuration mechanism may change in the future. For this reason it is internally marked as expirmental, meaning that “expose-experimental-directives” must appear on a line before this directive.
nice <nice>
Sets the ’niceness’ of connections initiated from the socket. Value must be in the range -1024..1024 inclusive, and defaults to zero. Positive values means that such connections are more friendly to others and easily offer their place in the scheduler. On the opposite, negative values mean that connections want to run with a higher priority than others. The difference only happens under high loads when the system is close to saturation. Negative values are appropriate for low-latency or administration services, and high values are generally recommended for CPU intensive tasks such as SSL processing or bulk transfers which are less sensible to latency. For example, it may make sense to use a positive value for an SMTP socket and a negative one for an RDP socket.
no-alpn
Disables ALPN processing (technically speaking this sets the ALPN string to an empty string that will not be advertised). It permits to cancel a previous occurrence of an “alpn” setting and to disable application protocol negotiation. It may also be used to prevent a listener from negotiating ALPN with a client on an HTTPS or QUIC listener; by default, HTTPS listeners will advertise “h2,http/1.1” and QUIC listeners will advertise “h3”. See also “alpn” bove. Note that when using “crt-list”, a certificate may override the “alpn” setting and re-enable its processing.
no-ca-names
This setting is only available when support for OpenSSL was built in. It prevents from send CA names in server hello message when ca-file is used. Use “ca-verify-file” instead of “ca-file” with “no-ca-names”.
no-sslv3
This setting is only available when support for OpenSSL was built in. It disables support for SSLv3 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. This option is also available on global statement “ssl-default-bind-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
no-strict-sni
This setting is only available when support for OpenSSL was built in. It disables strict-sni enforcement from a previous “strict-sni” directive. It may be needed in order to selectively disable strict-sni usage on a “bind” line when it was already globally enforced via “ssl-default-bind-options”. See also the “strict-sni” bind option.
no-tls-tickets
This setting is only available when support for OpenSSL was built in. It disables the stateless session resumption (RFC 5077 TLS Ticket extension) and force to use stateful session resumption. Stateless session resumption is more expensive in CPU usage. This option is also available on global statement “ssl-default-bind-options”. The TLS ticket mechanism is only used up to TLS 1.2. Forward Secrecy is compromised with TLS tickets, unless ticket keys are periodically rotated (via reload or by using “tls-ticket-keys”).
no-tlsv10
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.0 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. This option is also available on global statement “ssl-default-bind-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
no-tlsv11
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.1 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. This option is also available on global statement “ssl-default-bind-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
no-tlsv12
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.2 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. This option is also available on global statement “ssl-default-bind-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
no-tlsv13
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.3 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. This option is also available on global statement “ssl-default-bind-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
npn <protocols>
This enables the NPN TLS extension and advertises the specified protocol list as supported on top of NPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). This requires that the SSL library is built with support for TLS extensions enabled (check with haproxy -vv). Note that the NPN extension has been replaced with the ALPN extension (see the “alpn” keyword), though this one is only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older version of OpenSSL, NPN might still be used as most clients still support it at the time of writing this. It is possible to enable both NPN and ALPN though it probably doesn’t make any sense out of testing.
prefer-client-ciphers
Use the client’s preference when selecting the cipher suite, by default the server’s preference is enforced. This option is also available on global statement “ssl-default-bind-options”.
Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of the client cipher list.
When using a dual algorithms setup (RSA + ECDSA), the selection algorithm will chose between RSA and ECDSA and will always prioritize ECDSA. Once the right certificate is chosen, it will let the SSL library prioritize ciphers, curves etc. Meaning this option can’t be used to prioritize an RSA certificate over an ECDSA one.
proto <name>
Forces the multiplexer’s protocol to use for the incoming connections. It must be compatible with the mode of the frontend (TCP or HTTP). It must also be usable on the frontend side. The list of available protocols is reported in haproxy -vv. The protocols properties are reported: the mode (TCP/HTTP), the side (FE/BE), the mux name and its flags.
Some protocols are subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally some protocols don’t support upgrades (flag=NO_UPG). The HTX compatibility is also reported (flag=HTX).
Here are the protocols that may be used as argument to a “proto” directive on a bind line:
quic: mode=HTTP side=FE|BE mux=QUIC flags=HTX|NO_UPG|FRAMED
qmux: mode=HTTP side=FE|BE mux=QMUX flags=HTX|NO_UPG
h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|HOL_RISK|NO_UPG
h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG
none: mode=TCP side=FE|BE mux=PASS flags=NO_UPGIdea behind this option is to bypass the selection of the best multiplexer’s protocol for all connections instantiated from this listening socket. For instance, it is possible to force the http/2 on clear TCP by specifying “proto h2” on the bind line.
If the ALPN or the NPN settings are configured, the specified protocols should be compatible with the multiplexer’s protocol to avoid any issue. For instance, if “proto h1” is set, the ALPN should not be set to “h2”.
QMux is a subset of QUIC which runs over TCP. It corresponds to the following draft protocol https://www.ietf.org/archive/id/draft-ietf-quic-qmux-01.html . It is considered experimental in haproxy for now.
quic-cc-algo { cubic | newreno | bbr | nocc }[(<args,...>)]
This is a QUIC specific setting to select the congestion control algorithm for any connection attempts to the configured QUIC listeners. They are similar to those used by TCP.
Pacing is activated on top of the congestion algorithm to reduce loss and improve throughput. It can be turned off via “tune.quic.fe.tx.pacing” global keyword. In most cases, pacing should remain activated, especially when using BBR as it relies on it to work as expected. Using BBR without pacing may cause slowdowns or high loss rates during transfers.
Default value: cubic
For further customization, a list of parameters can be specified after the algorithm token. It must be written between parenthesis, separated by a comma. Each argument is optional and can be empty if needed. Here is the mandatory order of each parameters:
- maximum window size in bytes. It must be greater than 10k and smaller than 4g. By default “tune.quic.fe.cc.max-win-size” value is used.
Example:
# newreno congestion control algorithm
quic-cc-algo newreno
# cubic congestion control algorithm with one megabytes as window
quic-cc-algo cubic(1m)A special value “nocc” may be used to force a fixed congestion window always set at the maximum size. It is reserved for debugging scenarios to remove any side effects caused by the congestion controller. It must not be used in production as it can quickly lead to network issues such as a high loss rate.
quic-force-retry
This is a QUIC specific setting which forces the use of the QUIC Retry feature for all the connection attempts to the configured QUIC listeners. It consists in verifying the peers are able to receive packets at the transport address they used to initiate a new connection, sending them a Retry packet which contains a token. This token must be sent back to the Retry packet sender, this latter being the only one to be able to validate the token. Note that QUIC Retry will always be used even if a Retry threshold was set (see “tune.quic.fe.sec.retry-threshold” setting).
This setting requires the cluster secret to be set or else an error will be reported on startup (see “cluster-secret”).
See https://www.rfc-editor.org/rfc/rfc9000.html#section-8.1.2 for more information about QUIC retry.
quic-socket [ connection | listener ]
This QUIC specific setting allows to define the socket allocation mode for the specific listeners. See “tune.quic.fe.sock-per-conn” for a full description of the pros and cons of each mode.
This setting is applied in conjunction with the global “tune.quic.fe.sock-per-conn” option. If “default-on” mode is active on the global tuning (this is the default value), each QUIC connection will use its owned socket, except for listeners with “quic-socket listener”. However, if the global mode is set to “force-off”, individual listener configuration will be ignored.
severity-output <format>
This setting is used with the stats sockets only to configure severity level output prepended to
informational feedback messages. Severity level of messages can range between 0 and 7, conforming to
syslog rfc5424. Valid and successful socket commands requesting data (i.e. “show map”, “get acl foo”
etc.) will never have a severity level prepended. It is ignored by other sockets. <format> can be
one of:
- “none” (default) no severity level is prepended to feedback messages.
- “number” severity level is prepended as a number.
- “string” severity level is prepended as a string following the rfc5424 convention.
shards { <number> | by-thread | by-group }
In multi-threaded mode, on operating systems supporting multiple listeners on the same IP:port, this will automatically create this number of multiple identical listeners for the same line, all bound to a fair share of the number of the threads attached to this listener. This can sometimes be useful when using very large thread counts where the in-kernel locking on a single socket starts to cause a significant overhead. In this case the incoming traffic is distributed over multiple sockets and the contention is reduced. Note that doing this can easily increase the CPU usage by making more threads work a little bit.
If the number of shards is higher than the number of available threads, it will automatically be trimmed to the number of threads (i.e. one shard per thread). The special “by-thread” value also creates as many shards as there are threads on the “bind” line. Since the system will evenly distribute the incoming traffic between all these shards, it is important that this number is an integral divisor of the number of threads. Alternately, the other special value “by-group” will create one shard per thread group. This can be useful when dealing with many threads and not wanting to create too many sockets. The load distribution will be a bit less optimal but the contention (especially in the system) will still be lower than with a single socket.
On operating systems that do not support multiple sockets bound to the same address, “by-thread” and “by-group” will automatically fall back to a single shard. For “by-group” this is done without any warning since it doesn’t change anything for a single group, and will result in sockets being duplicated for each group anyway. However, for “by-thread”, a diagnostic warning will be emitted if this happens since the resulting number of listeners will not be the expected one.
sigalgs <sigalgs>
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of signature algorithms that are negotiated during the TLSv1.2 and TLSv1.3 handshake. The format of the string is defined in “man 3 SSL_CTX_set1_sigalgs” from the OpenSSL man pages. It is not recommended to use this setting unless compatibility with a middlebox is required.
ssl
This setting is only available when support for OpenSSL was built in. It enables SSL deciphering on connections instantiated from this listener. A certificate is necessary (see “crt” above). All contents in the buffers will appear in clear text, so that ACLs and HTTP processing will only have access to deciphered contents. SSLv3 is disabled per default, use “ssl-min-ver SSLv3” to enable it.
ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
This option enforces use of <version> or lower on SSL connections instantiated from this listener.
Using this setting without “ssl-min-ver” can be ambiguous because the default ssl-min-ver value
could change in future HAProxy versions. This option is also available on global statement
“ssl-default-bind-options”. See also “ssl-min-ver”.
ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
This option enforces use of <version> or upper on SSL connections instantiated from this listener.
The default value is “TLSv1.2”. This option is also available on global statement
“ssl-default-bind-options”. See also “ssl-max-ver”.
strict-sni
This setting is only available when support for OpenSSL was built in. The SSL/TLS negotiation is allowed only if the client provided an SNI that matches a certificate. The default certificate is not used. This option also allows starting without any certificate on a bind line, so an empty directory could be used and filled later from the stats socket. This option is also available on global statement “ssl-default-bind-options”, and may be selectively disabled on a “bind” line using “no-strict-sni”. See the “crt” option for more information. See “add ssl crt-list” command in the management guide.
tcp-md5sig <password>
Enables the TCP MD5 signature (RFC 2385 Protection of BGP Sessions via the TCP MD5 Signature Option)
for all incoming connections instantiated from this listening socket. This option is only available
on Linux. When enabled, <password> string is used to sign every TCP segments with a 16-byte MD5
digest. This will protect the TCP connection against spoofing. The primary use case for this option
is to allow BGP to protect itself against the introduction of spoofed TCP segments into the
connection stream. But it can be useful for any very long-lived TCP connections.
tcp-ss <mode>
Sets the TCP Save SYN option for all incoming connections instantiated from this listening socket. This option is available on Linux since version 4.3. It instructs the kernel to try to keep a copy of the incoming IP packet containing the TCP SYN flag, for later inspection via the “fc_saved_syn” sample fetch function. The option knows 3 modes: - 0 SYN packet saving is disabled, this is the default - 1 SYN packet saving is enabled, and contains IP and TCP headers - 2 SYN packet saving is enabled, and contains ETH, IP and TCP headers
This only works for regular TCP connections, and is ignored for other protocols (e.g. UNIX sockets). See also “fc_saved_syn”.
tcp-ut <delay>
Sets the TCP User Timeout for all incoming connections instantiated from this listening socket. This option is available on Linux since version 2.6.37. It allows HAProxy to configure a timeout for sockets which contain data not receiving an acknowledgment for the configured delay. This is especially useful on long-lived connections experiencing long idle periods such as remote terminals or database connection pools, where the client and server timeouts must remain high to allow a long period of idle, but where it is important to detect that the client has disappeared in order to release all resources associated with its connection (and the server’s session). The argument is a delay expressed in milliseconds by default. This only works for regular TCP connections, and is ignored for other protocols.
tfo
Is an optional keyword which is supported only on Linux kernels >= 3.7. It enables TCP Fast Open on the listening socket, which means that clients which support this feature will be able to send a request and receive a response during the 3-way handshake starting from second connection, thus saving one round-trip after the first connection. This only makes sense with protocols that use high connection rates and where each round trip matters. This can possibly cause issues with many firewalls which do not accept data on SYN packets, so this option should only be enabled once well tested. This option is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may need to build HAProxy with USE_TFO=1 if your libc doesn’t define TCP_FASTOPEN.
thread [<thread-group>/]<thread-set>[,...]
This restricts the list of threads on which this listener is allowed to run. It does not enforce any of them but eliminates those which do not match. It limits the threads allowed to process incoming connections for this listener.
There are two numbering schemes. By default, thread numbers are absolute in the process, comprised between 1 and the value specified in global.nbthread. It is also possible to designate a thread number using its relative number inside its thread group, by specifying the thread group number first, then a slash (’/’) and the relative thread number(s). In this case thread numbers also start at 1 and end at 32 or 64 depending on the platform. When absolute thread numbers are specified, they will be automatically translated to relative numbers once thread groups are known. Usually, absolute numbers are preferred for simple configurations, and relative ones are preferred for complex configurations where CPU arrangement matters for performance.
After the optional thread group number, the “thread-set” specification must use the following format:
As their names imply, “all” validates all threads within the set (either all of the group’s when a group is specified, or all of the process’ threads), “odd” validates all odd-numberred threads (every other thread starting at 1) either for the process or the group, and “even” validates all even-numberred threads (every other thread starting at 2). If instead thread number ranges are used, then all threads included in the range from the first to the last thread number are validated. The numbers are either relative to the group or absolute depending on the presence of a thread group number. If the first thread number is omitted, “1” is used, representing either the first thread of the group or the first thread of the process. If the last thread number is omitted, either the last thread number of the group (32 or 64) is used, or the last thread number of the process (global.nbthread).
These ranges may be repeated and delimited by a comma, so that non-contiguous thread sets can be specified, and the group, if present, must be specified again for each new range. Note that it is not permitted to mix group-relative and absolute specifications because the whole “bind” line must use either an absolute notation or a relative one, as those not set will be resolved at the end of the parsing.
It is important to know that each listener described by a “bind” line creates at least one socket represented by at least one file descriptor. Since file descriptors cannot span multiple thread groups, if a “bind” line specifies a thread range that covers more than one group, several file descriptors will automatically be created so that there is at least one per group. Technically speaking they all refer to the same socket in the kernel, but they will get a distinct identifier in haproxy and will even have a dedicated stats entry if “option socket-stats” is used.
The main purpose is to have multiple bind lines sharing the same IP:port but not the same thread in a listener, so that the system can distribute the incoming connections into multiple queues, bypassing haproxy’s internal queue load balancing. Currently Linux 3.9 and above is known for supporting this. See also the “shards” keyword above that automates duplication of “bind” lines and their assignment to multiple groups of threads.
This keyword is compatible with reverse HTTP binds. However, it is forbidden to specify a thread set which spans across several thread groups for such a listener as this may caused “nbconn” to not work as intended.
tls-tickets
This setting is only available when support for OpenSSL was built in. It enables the stateless session resumption (RFC 5077 TLS Ticket extension). It is the default, but it may be needed to selectively re-enable the feature on a “bind” line if it had been globally disabled via “no-tls-tickets” mentioned in “ssl-default-bind-options”. See also the “no-tls-tickets” bind keyword.
tls-ticket-keys <keyfile>
Sets the TLS ticket keys file to load the keys from. The keys need to be 48 or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64 with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo). The first key determines the key length used for next keys: you can’t mix aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO build option (default 3) and at least as many keys need to be present in the file. Last TLS_TICKETS_NO keys will be used for decryption and the penultimate one for encryption. This enables easy key rotation by just appending new key to the file and reloading the process. Keys must be periodically rotated (ex. every 12h) or Perfect Forward Secrecy is compromised. It is also a good idea to keep the keys off any permanent storage such as hard drives (hint: use tmpfs and don’t swap those files). Lifetime hint can be changed using tune.ssl.timeout.
transparent
Is an optional keyword which is supported only on certain Linux kernels. It indicates that the addresses will be bound even if they do not belong to the local machine, and that packets targeting any of these addresses will be intercepted just as if the addresses were locally configured. This normally requires that IP forwarding is enabled. Caution! do not use this with the default address ‘*’, as it would redirect any traffic for the specified port. This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1. This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on kernel version. Some distribution kernels include backports of the feature, so check for support with your vendor.
uid <uid>
Sets the owner of the UNIX sockets to the designated system uid. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “user” setting except that the user numeric ID is used instead of its name. This setting is ignored by non UNIX sockets.
user <user>
Sets the owner of the UNIX sockets to the designated system user. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “uid” setting except that the user name is used instead of its uid. This setting is ignored by non UNIX sockets.
v4v6
Is an optional keyword which is supported only on most recent systems including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4 and IPv6 when it uses the default address. Doing so is sometimes necessary on systems which bind to IPv6 only by default. It has no effect on non-IPv6 sockets, and is overridden by the “v6only” option.
v6only
Is an optional keyword which is supported only on most recent systems including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only when it uses the default address. Doing so is sometimes preferred to doing it system-wide as it is per-listener. It has no effect on non-IPv6 sockets and has precedence over the “v4v6” option.
verify [none|optional|required]
This setting is only available when support for OpenSSL was built in. If set to ’none’, client certificate is not requested. This is the default. In other cases, a client certificate is requested. If the client does not provide a certificate after the request and if ‘verify’ is set to ‘required’, then the handshake is aborted, while it would have succeeded if set to ‘optional’. The certificate provided by the client is always verified using CAs from ‘ca-file’ and optional CRLs from ‘crl-file’. On verify failure the handshake is aborted, regardless of the ‘verify’ option, unless the error code exactly matches one of those listed with ‘ca-ignore-err’ or ‘crt-ignore-err’.
5.2. Server and default-server options
The “server” and “default-server” keywords support a certain number of settings which are all passed as arguments on the server line. The order in which those arguments appear does not count, and they are all optional. Some of those settings are single words (booleans) while others expect one or several values after them. In this case, the values must immediately follow the setting name. Except default-server, all those settings must be specified after the server’s address if they are used:
Note that all these settings are supported both by “server” and “default-server” keywords, except “id” which is only supported by “server”.
The currently supported settings are the following ones.
addr <ipv4|ipv6>
May be used in the following contexts: tcp, http, log
Using the “addr” parameter, it becomes possible to use a different IP address to send health-checks or to probe the agent-check. On some servers, it may be desirable to dedicate an IP address to specific component able to perform complex tests which are more suitable to health-checks than the application. This parameter is ignored if the “check” parameter is not set. See also the “port” parameter.
agent-check
May be used in the following contexts: tcp, http, log
Enable an auxiliary agent check which is run independently of a regular health check. An agent health check is performed by making a TCP connection to the port set by the “agent-port” parameter and reading an ASCII string terminated by the first ‘\r’ or ‘\n’ met. The string is made of a series of words delimited by spaces, tabs or commas in any order, each consisting of:
-
An ASCII representation of a positive integer percentage, e.g. “75%”. Values in this format will set the weight proportional to the initial weight of a server as configured when HAProxy starts. Note that a zero weight is reported on the stats page as “DRAIN” since it has the same effect on the server (it’s removed from the LB farm). It is the legacy way to set the weight of a server. Setting it with the “weight:” prefix is preferred.
-
The string “weight:” following by an positive integer or a positive integer percentage, with no space. If the value ends with the ‘%’ sign, then the new weight will be proportional to the initially weight of the server. Otherwise, the value is considered as an absolute weight and must be between 0 and 256. Servers which are part of a farm running a static load-balancing algorithm have stricter limitations because the weight cannot change once set. Thus for these servers, the only accepted values are 0 and 100% (or 0 and the initial weight). Changes take effect immediately, though certain LB algorithms require a certain amount of requests to consider changes. Note that a zero weight is reported on the stats page as “DRAIN” since it has the same effect on the server (it’s removed from the LB farm).
-
The string “maxconn:” followed by an integer (no space between). Values in this format will set the maxconn of a server. The maximum number of connections advertised needs to be multiplied by the number of load balancers and different backends that use this health check to get the total number of connections the server might receive. Example: maxconn:30
-
The word “ready”. This will turn the server’s administrative state to the READY mode, thus canceling any DRAIN or MAINT state
-
The word “drain”. This will turn the server’s administrative state to the DRAIN mode, thus it will not accept any new connections other than those that are accepted via persistence.
-
The word “maint”. This will turn the server’s administrative state to the MAINT mode, thus it will not accept any new connections at all, and health checks will be stopped.
-
The words “down”, “fail”, or “stopped”, optionally followed by a description string after a sharp (’#’). All of these mark the server’s operating state as DOWN, but since the word itself is reported on the stats page, the difference allows an administrator to know if the situation was expected or not: the service may intentionally be stopped, may appear up but fail some validity tests, or may be seen as down (e.g. missing process, or port not responding).
-
The word “up” sets back the server’s operating state as UP if health checks also report that the service is accessible.
Parameters which are not advertised by the agent are not changed. For example, an agent might be designed to monitor CPU usage and only report a relative weight and never interact with the operating status. Similarly, an agent could be designed as an end-user interface with 3 radio buttons allowing an administrator to change only the administrative state. However, it is important to consider that only the agent may revert its own actions, so if a server is set to DRAIN mode or to DOWN state using the agent, the agent must implement the other equivalent actions to bring the service into operations again.
Failure to connect to the agent is not considered an error as connectivity is tested by the regular health check which is enabled by the “check” parameter. Warning though, it is not a good idea to stop an agent after it reports “down”, since only an agent reporting “up” will be able to turn the server up again. Note that the CLI on the Unix stats socket is also able to force an agent’s result in order to work around a bogus agent if needed.
Requires the “agent-port” parameter to be set. See also the “agent-inter” and “no-agent-check” parameters.
agent-send <string>
May be used in the following contexts: tcp, http, log
If this option is specified, HAProxy will send the given string (verbatim) to the agent server upon connection. You could, for example, encode the backend name into this string, which would enable your agent to send different responses based on the backend. Make sure to include a ‘\n’ if you want to terminate your request with a newline.
agent-inter <delay>
May be used in the following contexts: tcp, http, log
The “agent-inter” parameter sets the interval between two agent checks to <delay> milliseconds. If
left unspecified, the delay defaults to 2000 ms.
Just as with every other time-based parameter, it may be entered in any other explicit unit among { us, ms, s, m, h, d }. The “agent-inter” parameter also serves as a timeout for agent checks “timeout check” is not set. In order to reduce “resonance” effects when multiple servers are hosted on the same hardware, the agent and health checks of all servers are started with a small time offset between them. It is also possible to add some random noise in the agent and health checks interval using the global “spread-checks” keyword. This makes sense for instance when a lot of backends use the same servers.
See also the “agent-check” and “agent-port” parameters.
agent-addr <addr>
May be used in the following contexts: tcp, http, log
The “agent-addr” parameter sets address for agent check.
You can offload agent-check to another target, so you can make single place managing status and weights of servers defined in HAProxy in case you can’t make self-aware and self-managing services. You can specify both IP or hostname, it will be resolved.
agent-port <port>
May be used in the following contexts: tcp, http, log
The “agent-port” parameter sets the TCP port used for agent checks.
See also the “agent-check” and “agent-inter” parameters.
allow-0rtt
May be used in the following contexts: tcp, http, log, peers, ring
Allow sending early data to the server when using TLS 1.3. Note that early data will be sent only if the client used early data, or if the backend uses “retry-on” with the “0rtt-rejected” keyword. With QUIC, 0rtt is supported with QuicTLS, OpenSSL >= 3.5.2 and AWS-LC. With TCP/TLS, 0rtt is only supported with OpenSSL.
alpn <protocols>
May be used in the following contexts: tcp, http
This enables the TLS ALPN extension and advertises the specified protocol list as supported on top of ALPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). This requires that the SSL library is built with support for TLS extensions enabled (check with haproxy -vv). The ALPN extension replaces the initial NPN extension. ALPN is required to connect to HTTP/2 servers. It is also required to be able to use HTTP/3 via a QUIC server, “h3” serves as a default value for QUIC servers without “alpn” setting. Versions of OpenSSL prior to 1.0.2 didn’t support ALPN and only supposed the now obsolete NPN extension. If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can be advertised, in order of preference, like below:
See also “ws” to use an alternative ALPN for websocket streams.
backup
May be used in the following contexts: tcp, http, log
When “backup” is present on a server line, the server is only used in load balancing when all other non-backup servers are unavailable. Requests coming with a persistence cookie referencing the server will always be served though. By default, only the first operational backup server is used, unless the “allbackups” option is set in the backend. See also the “no-backup” and “allbackups” options.
ca-file <cafile>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load CA certificates used to verify server’s certificate. It is possible to load a directory containing multiple CAs, in this case HAProxy will try to load every “.pem”, “.crt”, “.cer”, and .crl" available in the directory, files starting with a dot are ignored.
In order to use the trusted CAs of your system, the “@system-ca” parameter could be used in place of the cafile. The location of this directory could be overwritten by setting the SSL_CERT_DIR environment variable.
cc <algo>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available on systems which define TCP_CONGESTION, and was validated on Linux and FreeBSD. It takes the name of a TCP congestion control algorithm and configures outgoing connections to use this algorithm. Typical names include “reno” or “cubic” and will depend on the operating system. On some systems, special permissions may be required to configure certain algorithms. On Linux, available algorithms are listed in sysctl “net.ipv4.tcp_available_congestion_control”, and those permitted without privileges are in “net.ipv4.tcp_allowed_congestion_control”. In order to access algorithms requiring extra permissions, the “cap_net_admin” capability might be required (see “setcap” in the global section). In case of failure to configure a specific congestion control algorithm, the default one remains unchanged. See also: the “cc” bind keyword (section 5.1 ).
check
May be used in the following contexts: tcp, http, log
This option enables health checks on a server: - when not set, no health checking is performed, and the server is always considered available. - when set and no other check method is configured, the server is considered available when a connection can be established at the highest configured transport layer. This means TCP by default, or SSL/TLS when “ssl” or “check-ssl” are set, both possibly combined with connection prefixes such as a PROXY protocol header when “send-proxy” or “check-send-proxy” are set. This behavior is slightly different for dynamic servers, read the following paragraphs for more details. - when set and an application-level health check is defined, the application-level exchanges are performed on top of the configured transport layer and the server is considered available if all of the exchanges succeed.
By default, health checks are performed on the same address and port as configured on the server, using the same encapsulation parameters (SSL/TLS, proxy-protocol header, etc… ). It is possible to change the destination address using “addr” and the port using “port”. When done, it is assumed the server isn’t checked on the service port, and configured encapsulation parameters are not reused. One must explicitly set “check-send-proxy” to send connection headers, “check-ssl” to use SSL/TLS.
Note that the implicit configuration of ssl and PROXY protocol is not performed for dynamic servers. In this case, it is required to explicitly use “check-ssl” and “check-send-proxy” when wanted, even if the check port is not overridden.
When “sni” or “alpn” are set on the server line, their value is not used for health checks and one must use “check-sni” or “check-alpn”.
The default source address for health check traffic is the same as the one defined in the backend. It can be changed with the “source” keyword.
The interval between checks can be set using the “inter” keyword, and the “rise” and “fall” keywords can be used to define how many successful or failed health checks are required to flag a server available or not available.
Optional application-level health checks can be configured with “option httpchk”, “option mysql-check” “option smtpchk”, “option pgsql-check”, “option ldap-check”, or “option redis-check”.
Example:
# simple tcp check
backend foo
server s1 192.168.0.1:80 check
# this does a tcp connect + tls handshake
backend foo
server s1 192.168.0.1:443 ssl check
# simple tcp check is enough for check success
backend foo
option tcp-check
tcp-check connect
server s1 192.168.0.1:443 ssl checkcheck-reuse-pool
May be used in the following contexts: tcp, http
This option permits checks to reuse idle connections if available instead of opening a dedicated one. The connection is reinserted in the pool on check completion. The main objective is to limit the number of connections opening and closure on a specific server. This feature is compatible only with http-check rulesets. It is silently ignored for other check types. Furthermore, reuse policy should be set to aggressive on the backend as each check attempt is performed over a dedicated session.
For configuration simplicity, this option is silently ignored if any specific check connect option is defined, either on the server line or via a custom tcp-check connect rule.
This option is automatically enabled for servers acting as passive reverse HTTP gateway, as for those servers connect is only supported through reuse.
See also: “check-pool-conn-name”
check-send-proxy
May be used in the following contexts: tcp, http
This option forces emission of a PROXY protocol line with outgoing health checks, regardless of whether the server uses send-proxy or not for the normal traffic. By default, the PROXY protocol is enabled for health checks if it is already enabled for normal traffic and if no “port” nor “addr” directive is present. However, if such a directive is present, the “check-send-proxy” option needs to be used to force the use of the protocol. See also the “send-proxy” option for more information.
check-alpn <protocols>
May be used in the following contexts: tcp, http
Defines which protocols to advertise with ALPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). If it is not set, the server ALPN is used.
check-pool-conn-name <name>
May be used in the following contexts: tcp, http
When connection reuse is performed for checks, uses <name> if set as a connection identifier to
match a corresponding connection in the pool. This serves as the equivalent to the “pool-conn-name”
server keyword. “check-sni” will also be used as a fallback if the current option is not used.
See also: “check-reuse-pool”
check-proto <name>
May be used in the following contexts: tcp, http
Forces the multiplexer’s protocol to use for the server’s health-check connections. It must be compatible with the health-check type (TCP or HTTP). It must also be usable on the backend side. The list of available protocols is reported in haproxy -vv. The protocols properties are reported: the mode (TCP/HTTP), the side (FE/BE), the mux name and its flags.
Some protocols are subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally some protocols don’t support upgrades (flag=NO_UPG). The HTX compatibility is also reported (flag=HTX).
Here are the protocols that may be used as argument to a “check-proto” directive on a server line:
h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|HOL_RISK|NO_UPG
fcgi: mode=HTTP side=BE mux=FCGI flags=HTX|HOL_RISK|NO_UPG
h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG
none: mode=TCP side=FE|BE mux=PASS flags=NO_UPG
quic: mode=HTTP side=FE|BE mux=QUIC flags=HTX|NO_UPG|FRAMED
spop: mode=SPOP side=BE mux=SPOP flags=HOL_RISK|NO_UPGIdea behind this option is to bypass the selection of the best multiplexer’s protocol for health-check connections established to this server. If not defined, the server one will be used, if set.
If the ALPN or the NPN settings are configured, the specified protocols should be compatible with the multiplexer’s protocol to avoid any issue. For instance, if “proto h1” is set, the ALPN should not be set to “h2”.
QUIC check configuration is not fully implemented yet. First, QUIC checks may only be performed for QUIC servers. Second, if one or more check specific connection parameters is specified on a QUIC server, check protocol will fallback to TCP usage.
check-sni-auto
May be used in the following contexts: tcp, http, log
This option enables the automatic SNI selection when doing health checks over SSL, if no value was already set. It is enabled by default but this parameter may be used as “server” setting to reset any “no-check-sni-auto” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “no-check-sni-auto” setting.
For HTTPS connections, the SNI is automatically selected but only if there is no “http-check connect” rule. In that case, the selected SNI is based on the host header value, specified via the “option httpchk” directive or a “http-check send” rule. There is no automatic selection for “http-check connect” rules. For other protocols, the option is ignored.
If the automatic selection of the SNI is used for health-checks, the value is assigned to the connection name if “check-reuse-pool” setting is set, unless overridden by the “check-pool-conn-name” server keyword.
See “sni-auto” option to enable automatic SNI selection for proxied traffic.
check-sni <sni>
May be used in the following contexts: tcp, http, log
This option allows you to specify the SNI to be used when doing health checks over SSL. It is only
possible to use a string to set <sni>. If you want to set a SNI for proxied traffic, see “sni”.
check-ssl
May be used in the following contexts: tcp, http, log
This option forces encryption of all health checks over SSL, regardless of whether the server uses SSL or not for the normal traffic. This is generally used when an explicit “port” or “addr” directive is specified and SSL health checks are not inherited. It is important to understand that this option inserts an SSL transport layer below the checks, so that a simple TCP connect check becomes an SSL connect, which replaces the old ssl-hello-chk. The most common use is to send HTTPS checks by combining “httpchk” with SSL checks. All SSL settings are common to health checks and traffic (e.g. ciphers). See the “ssl” option for more information and “no-check-ssl” to disable this option.
check-via-socks4
May be used in the following contexts: tcp, http, log
This option enables outgoing health checks using upstream socks4 proxy. By default, the health checks won’t go through socks tunnel even it was enabled for normal traffic.
ciphers <ciphers>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. This option sets the string describing the list of cipher algorithms that is negotiated during the SSL/TLS handshake with the server. The format of the string is defined in “man 1 ciphers” from OpenSSL man pages. For background information and recommendations see e.g. (https://wiki.mozilla.org/Security/Server_Side_TLS ) and (https://mozilla.github.io/server-side-tls/ssl-config-generator/ ). For TLSv1.3 cipher configuration, please check the “ciphersuites” keyword.
ciphersuites <ciphersuites>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in and OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string describing the list of cipher algorithms that is negotiated during the TLS 1.3 handshake with the server. The format of the string is defined in “man 1 ciphers” from OpenSSL man pages under the “ciphersuites” section. For cipher configuration for TLSv1.2 and earlier, please check the “ciphers” keyword.
client-sigalgs <sigalgs>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of signature algorithms related to client authentication that are negotiated . The format of the string is defined in “man 3 SSL_CTX_set1_client_sigalgs” from the OpenSSL man pages. It is not recommended to use this setting if no specific usecase was identified.
cookie <value>
May be used in the following contexts: http
The “cookie” parameter sets the cookie value assigned to the server to <value>. This value will be
checked in incoming requests, and the first operational server possessing the same value will be
selected. In return, in cookie insertion or rewrite modes, this value will be assigned to the cookie
sent to the client. There is nothing wrong in having several servers sharing the same cookie value,
and it is in fact somewhat common between normal and backup servers. See also the “cookie” keyword
in backend section.
crl-file <crlfile>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load certificate revocation list used to verify server’s certificate.
crt <cert>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load both a certificate and the associated private key. This file can be built by concatenating both PEM files into one. This certificate will be sent if the server send a client certificate request.
If the file does not contain a private key, HAProxy will try to load the key at the same path suffixed by a “.key” (provided the “ssl-load-extra-files” option is set accordingly).
curves <curves>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of elliptic curves algorithms (“curve suite”) that are negotiated during the SSL/TLS handshake with ECDHE. The format of the string is a colon-delimited list of curve name. Example: “X25519:P-256” (without quote)
disabled
May be used in the following contexts: tcp, http, log
The “disabled” keyword starts the server in the “disabled” state. That means that it is marked down in maintenance mode, and no connection other than the ones allowed by persist mode will reach it. It is very well suited to setup new servers, because normal traffic will never reach them, while it is still possible to test the service by making use of the force-persist mechanism. See also “enabled” setting.
enabled
May be used in the following contexts: tcp, http, log
This option may be used as ‘server’ setting to reset any ‘disabled’ setting which would have been inherited from ‘default-server’ directive as default value. It may also be used as ‘default-server’ setting to reset any previous ‘default-server’ ‘disabled’ setting.
error-limit <count>
May be used in the following contexts: tcp, http, log
If health observing is enabled, the “error-limit” parameter specifies the number of consecutive errors that triggers event selected by the “on-error” option. By default it is set to 10 consecutive errors.
See also the “check”, “error-limit” and “on-error”.
fall <count>
May be used in the following contexts: tcp, http, log
The “fall” parameter states that a server will be considered as dead after <count> consecutive
unsuccessful health checks. This value defaults to 3 if unspecified. See also the “check”, “inter”
and “rise” parameters.
force-sslv3
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of SSLv3 only when SSL is used to communicate with the server. SSLv3 is generally less expensive than the TLS counterparts for high connection rates. This option is also available on global statement “ssl-default-server-options”. See also “ssl-min-ver” and ssl-max-ver".
force-tlsv10
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of TLSv1.0 only when SSL is used to communicate with the server. This option is also available on global statement “ssl-default-server-options”. See also “ssl-min-ver” and ssl-max-ver".
force-tlsv11
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of TLSv1.1 only when SSL is used to communicate with the server. This option is also available on global statement “ssl-default-server-options”. See also “ssl-min-ver” and ssl-max-ver".
force-tlsv12
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of TLSv1.2 only when SSL is used to communicate with the server. This option is also available on global statement “ssl-default-server-options”. See also “ssl-min-ver” and ssl-max-ver".
force-tlsv13
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of TLSv1.3 only when SSL is used to communicate with the server. This option is also available on global statement “ssl-default-server-options”. See also “ssl-min-ver” and ssl-max-ver".
guid <string>
May be used in the following contexts: tcp, http, log
Specify a case-sensitive global unique ID for this server. This must be unique across all haproxy configuration on every object types. See “guid” proxy keyword description for more information on its format. See also “shm-stats-file”.
hash-key <key>
May be used in the following contexts: tcp, http, log
Specify how “hash-type consistent” node keys are computed
Arguments:
<key> <key> may be one of the following:
id The node keys will be derived from the server's numeric
identifier as set from "id" or which defaults to its position
in the server list. This is the default. Note that only the 28
lowest bits of the ID will be used (i.e. (id % 268435456)), so
better only use values comprised between 1 and this value to
avoid overlap.
id32 The node keys will be derived from the server's numeric
identifier as set from "id" or which defaults to its position
in the server list, but the full 32 bits of the ID will be
used so that there is no collision. This one is not scaled
like "id" is, so it is recommended to either always use it
with a hash function (see "hash-key") or with explicitly
assigned ID values that are evenly distributed over the 32-bit
space.
guid The node keys will be derived from the server's guid, when
available, otherwise they will fall back on "id". The benefit
is that it does not depend on ordering at all, only on an
internal stable identifier that can be replicated across many
load balancers.
addr The node keys will be derived from the server's address, when
available, or else fall back on "id".
addr-port The node keys will be derived from the server's address and
port, when available, or else fall back on "id".The “addr” and “addr-port” options may be useful in scenarios where multiple HAProxy processes are balancing traffic to the same set of servers. If the server order of each process is different (because, for example, DNS records were resolved in different orders) then this will allow each independent HAProxy processes to agree on routing decisions. Note: “balance random” also uses “hash-type consistent”, and the quality of the distribution will depend on the quality of the keys.
healthcheck <name>
May be used in the following contexts: tcp, http
Specify the health-check section to use to perform check on the server.
Argument:
Thanks to this option, it is possible to use a pre-server health-check configuration instead of using the proxy configuration. See also “healthcheck section”.
id <value>
May be used in the following contexts: tcp, http, log
Set a persistent ID for the server. This ID must be a 32-bit positive number and unique for the proxy. An unused ID will automatically be assigned if unset. The first assigned value will be 1. This ID is currently only returned in statistics, and is used to place LB nodes when using consistent hash algorithms when “hash-key” is set to “id” (the default). In this case, only the 28 lowest bits of the value are used (i.e. (id % 268435356)), so better only use values comprised between 1 and this value to avoid overlap.
idle-ping <delay>
May be used in the following contexts: tcp, http, log
Define an interval for periodic liveliness on idle backend connections. If the peer is unable to respond before the next scheduled test, the connection is closed. This keyword refers to the backend side, so it is useful to check that idle connections are still usable. Note that this won’t prevent the connection from being destroyed on idle pool purge.
This feature relies on specific underlying protocol support. For now, only H2 mux implements it. Idle-ping is simply ignored by other protocols.
This option is particularly useful when using reverse HTTP. Setting it on the server line is useful for the peer which listen for incoming connections and attach them to a corresponding server to be able to reuse later on traffic forwarding.
init-addr {last | libc | none | <ip>},[...]*
May be used in the following contexts: tcp, http, log
Indicate in what order the server’s address should be resolved upon startup if it uses an FQDN. Attempts are made to resolve the address by applying in turn each of the methods mentioned in the comma-delimited list. The first method which succeeds is used. If the end of the list is reached without finding a working method, an error is thrown. Method “last” suggests to pick the address which appears in the state file (see “server-state-file”). Method “libc” uses the libc’s internal resolver (gethostbyname() or getaddrinfo() depending on the operating system and build options). Method “none” specifically indicates that the server should start without any valid IP address in a down state. It can be useful to ignore some DNS issues upon startup, waiting for the situation to get fixed later. Finally, an IP address (IPv4 or IPv6) may be provided. It can be the currently known address of the server (e.g. filled by a configuration generator), or the address of a dummy server used to catch old sessions and present them with a decent error message for example. When the “first” load balancing algorithm is used, this IP address could point to a fake server used to trigger the creation of new instances on the fly. This option defaults to “last,libc” indicating that the previous address found in the state file (if any) is used first, otherwise the libc’s resolver is used. This ensures continued compatibility with the historic behavior. When using internal resolvers, it is generally recommended to either disable libc-based resolution, or make it explicit (see section 5.3 for more details).
Example 1:
Example 2:
inter <delay>
May be used in the following contexts: tcp, http, log
The “inter” parameter sets the interval between two consecutive health checks to <delay>
milliseconds. If left unspecified, the delay defaults to 2000 ms. It is also possible to use
“fastinter” and “downinter” to optimize delays between checks depending on the server state:
Server state | Interval used
----------------------------------------+----------------------------------
UP 100% (non-transitional) | "inter"
----------------------------------------+----------------------------------
Transitionally UP (going down "fall"), | "fastinter" if set,
Transitionally DOWN (going up "rise"), | "inter" otherwise.
or yet unchecked. |
----------------------------------------+----------------------------------
DOWN 100% (non-transitional) | "downinter" if set,
| "inter" otherwise.
----------------------------------------+----------------------------------Just as with every other time-based parameter, they can be entered in any other explicit unit among { us, ms, s, m, h, d }. The “inter” parameter also serves as a timeout for health checks sent to servers if “timeout check” is not set. In order to reduce “resonance” effects when multiple servers are hosted on the same hardware, the agent and health checks of all servers are started with a small time offset between them. It is also possible to add some random noise in the agent and health checks interval using the global “spread-checks” keyword. This makes sense for instance when a lot of backends use the same servers. The global “tune.max-checks-per-thread” setting, if defined to a non-nul value, will limit the number of concurrent checks being performed at once on any given thread. In order to achieve this, haproxy will put in a queue the checks that were about to start on a thread that has reached this limit, until another check finishes. This will have for effect to extend the effective check interval. In such a case, reducing the “inter” setting will have a very limited effect as it will not be able to reduce the time spent in the queue.
init-state { fully-up | up | down | fully-down | none }
May be used in the following contexts: tcp, http
May be used in sections: defaults | frontend | listen | backend no | no | yes | yes
The “init-state” option sets the initial state of the server: - when set to ‘fully-up’, the server is considered immediately available and, if health checks are enabled for this server, it will be turned to the DOWN state when ALL health checks fail. - when set to ‘up’, the server is considered immediately available and, if health checks are enabled for this server, it will be turned to the DOWN state immediately if the next health check fails. - when set to ‘down’, the server initially is considered unavailable and, if health checks are enabled for this server, it can be turned to the UP state if the next health check succeeds. - when set to ‘fully-down’, the server is initially considered unavailable and, if health checks are enabled for this server, it will turned to the UP state when ALL health checks succeed. - when set to ’none’ (the default value), init-state management is disabled. It can be used to restore the default behavior when this parameter was inherited from a ‘default-server’ directive.
The server’s init-state is considered when the HAProxy instance is (re)started, a new server is detected (for example via service discovery / DNS resolution), a dynamic server is inlived, a server exits maintenance, etc. This directive cannot be used when the server is tracking another one.
Examples:
# pass client traffic ONLY to Redis "master" node
backend redis-master
mode tcp
balance first
option tcp-check
tcp-check send role\r\n
tcp-check expect string master
server-template redis 3 _redis._tcp.redis-headless-service.sandbox.svc.cluster.local:6379 check ... init-state down
# pass traffic to the server only after 3 successful health checks
backend google-backend
mode http
server srv1 google.com:80 check init-state fully-down rise 3
server srv2 google.com:80 check init-state fully-down rise 3See also: “option tcp-check”, “option httpchk”
ktls <on|off> [ EXPERIMENTAL ]
May be used in the following contexts: tcp, http, log, peers, ring
Enables or disables ktls for those sockets. If enabled, kTLS will be used if the kernel supports it and the cipher is compatible. This is only available on Linux 4.17 and above. Please note that some network drivers and/or TLS stacks might restrict kTLS usage to TLS v1.2 only. See also “force-tlsv12”.
log-bufsize <bufsize>
May be used in the following contexts: log
The “log-bufsize” specifies the ring bufsize to use for the implicit ring that will be associated to the log server in a log backend. When not specified, this defaults to BUFSIZE. Use of a greater value will increase memory usage but can help to prevent the loss of log messages with slow servers since the buffer will be able to hold more pending messages. This keyword may only be used in log backend sections (with “mode log”)
log-proto <logproto>
May be used in the following contexts: log, ring
The “log-proto” specifies the protocol used to forward event messages to a server configured in a log or ring section. Possible values are “legacy” and “octet-count” corresponding respectively to “Non-transparent-framing” and “Octet counting” in rfc6587. “legacy” is the default.
maxconn <maxconn>
May be used in the following contexts: tcp, http
The “maxconn” parameter specifies the maximal number of concurrent connections that will be sent to this server. If the number of incoming concurrent connections goes higher than this value, they will be queued, waiting for a slot to be released. This parameter is very important as it can save fragile servers from going down under extreme loads. If a “minconn” parameter is specified, the limit becomes dynamic. The default value is “0” which means unlimited. See also the “minconn” and “maxqueue” parameters, and the backend’s “fullconn” keyword.
In HTTP mode this parameter limits the number of concurrent requests instead of the number of connections. Multiple requests might be multiplexed over a single TCP connection to the server. As an example if you specify a maxconn of 50 you might see between 1 and 50 actual server connections, but no more than 50 concurrent requests.
maxqueue <maxqueue>
May be used in the following contexts: tcp, http
The “maxqueue” parameter specifies the maximal number of connections which will wait in the queue for this server. If this limit is reached, next requests will be redispatched to other servers instead of indefinitely waiting to be served. This will break persistence but may allow people to quickly re-log in when the server they try to connect to is dying. Some load balancing algorithms such as leastconn take this into account and accept to add requests into a server’s queue up to this value if it is explicitly set to a value greater than zero, which often allows to better smooth the load when dealing with single-digit maxconn values. The default value is “0” which means the queue is unlimited. See also the “maxconn” and “minconn” parameters and “balance leastconn”.
max-reuse <count>
May be used in the following contexts: http, ring
When used under http context:
The “max-reuse” argument indicates the HTTP connection processors that they should not reuse a server connection more than this number of times to send new requests. Permitted values are -1 (the default), which disables this limit, or any positive value. Value zero will effectively disable keep-alive. This is only used to work around certain server bugs which cause them to leak resources over time. The argument is not necessarily respected by the lower layers as there might be technical limitations making it impossible to enforce. At least HTTP/2 connections to servers will respect it.
When used under ring context:
The “max-reuse” argument indicates that the sink TCP connection processors that they should not reuse a server connection more than this number of times to send messages. It means that the connection to the server will be forcefully destroyed once at least “max-reuse + 1” messages were handled on the same connection. The connection to the server will then be automatically re-created. When dealing with a large amount of messages in multithreading context, this can help to better distribute the ring’s load over multiple threads. Indeed, each connection is bound to the same CPU thread for its entire duration: unlike HTTP, there is no thing like syslog transaction, so the server connection could live indefinitely as long as the server doesn’t close the connection or no network error occurs. By destroying connections from time to time we give the opportunity to other threads to pick-up some messages in turn. It may also help gracefully rotate log servers in contexts where there is an extra load-balancing layer between haproxy and the log servers. However, keep in mind that each connection recycling will leave an outgoing port in TIME_WAIT state that will not be reusable for around one minute on modern operating systems, and that as such, one must be careful not to use too low values to prevent rapid source port exhaustion. As a rule of thumb, make sure never to close more than a few times per second, and preferably much less often. Permitted values are -1 (the default), which disables this limit, or any positive value. Unlike under HTTP context, when used with sink servers “max-reuse” is a best-effort: ring messages are batched, so the limit is checked between each batch.
minconn <minconn>
May be used in the following contexts: tcp, http
When the “minconn” parameter is set, the maxconn limit becomes a dynamic limit following the
backend’s load. The server will 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
<fullconn> concurrent connections. This makes it possible to limit the load on the server during
normal loads, but push it further for important loads without overloading the server during
exceptional loads. See also the “maxconn” and “maxqueue” parameters, as well as the “fullconn”
backend keyword.
namespace <name>
May be used in the following contexts: tcp, http, log, peers, ring
On Linux, it is possible to specify which network namespace a socket will belong to. This directive makes it possible to explicitly bind a server to a namespace different from the default one. Please refer to your operating system’s documentation to find more details about network namespaces.
no-agent-check
May be used in the following contexts: tcp, http, log
This option may be used as “server” setting to reset any “agent-check” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “agent-check” setting.
no-backup
May be used in the following contexts: tcp, http, log
This option may be used as “server” setting to reset any “backup” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “backup” setting.
no-check
May be used in the following contexts: tcp, http, log
This option may be used as “server” setting to reset any “check” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “check” setting.
no-check-reuse-pool
May be used in the following contexts: tcp, http
This option reverts any previous “check-reuse-pool” possibly inherited from a “default-server”. Any checks will be conducted on its dedicated connection.
no-check-sni-auto
May be used in the following contexts: tcp, http, log
This option may be used as “server” setting to disable the automatic SNI selection for SSL health checks which is enabled by default.
See “no-sni-auto” option to disable automatic SNI selection for proxied traffic.
no-check-ssl
May be used in the following contexts: tcp, http, log
This option may be used as “server” setting to reset any “check-ssl” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “check-ssl” setting.
no-renegotiate
May be used in the following contexts: tcp, http, log
This setting is only available when support for OpenSSL was built in. It disables the renegotiation mechanisms, be it the legacy unsafe one or the more recent “secure renegotiation” one (RFC 5746 TLS Renegotiation Indication Extension) for the given SSL backend. This option is also available on global statement “ssl-default-server-options”. Renegotiation is not possible anymore in TLS 1.3. If neither “renegotiate” nor “no-renegotiate” is specified, the SSL library’s default behavior is kept. Note that for instance OpenSSL library enables secure renegotiation by default while AWS-LC disable it. See also “renegotiate”.
no-send-proxy
May be used in the following contexts: tcp, http
This option may be used as “server” setting to reset any “send-proxy” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “send-proxy” setting.
no-send-proxy-v2
May be used in the following contexts: tcp, http
This option may be used as “server” setting to reset any “send-proxy-v2” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “send-proxy-v2” setting.
no-send-proxy-v2-ssl
May be used in the following contexts: tcp, http
This option may be used as “server” setting to reset any “send-proxy-v2-ssl” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “send-proxy-v2-ssl” setting.
no-send-proxy-v2-ssl-cn
May be used in the following contexts: tcp, http
This option may be used as “server” setting to reset any “send-proxy-v2-ssl-cn” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “send-proxy-v2-ssl-cn” setting.
no-sni-auto
May be used in the following contexts: tcp, http, log, peers, ring
This option may be used as “server” setting to disable the automatic SNI selection which is enabled by default.
See “no-check-sni-auto” option to disable automatic SNI selection for SSL health checks.
no-ssl
May be used in the following contexts: tcp, http, log, peers, ring
This option may be used as “server” setting to reset any “ssl” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “ssl” setting.
Note that using default-server ssl setting and no-ssl on server will however init SSL
connection, so it can be later be enabled through the runtime API: see set server commands in
management doc.
no-ssl-reuse
May be used in the following contexts: tcp, http, log, peers, ring
This option disables SSL session reuse when SSL is used to communicate with the server. It will force the server to perform a full handshake for every new connection. It’s probably only useful for benchmarking, troubleshooting, and for paranoid users.
no-sslv3
May be used in the following contexts: tcp, http, log, peers, ring
This option disables support for SSLv3 when SSL is used to communicate with the server. Note that SSLv2 is disabled in the code and cannot be enabled using any configuration option. Use “ssl-min-ver” and “ssl-max-ver” instead.
Supported in default-server: No
no-tls-tickets
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It disables the stateless session resumption (RFC 5077 TLS Ticket extension) and force to use stateful session resumption. Stateless session resumption is more expensive in CPU usage for servers. This option is also available on global statement “ssl-default-server-options”. The TLS ticket mechanism is only used up to TLS 1.2. Forward Secrecy is compromised with TLS tickets, unless ticket keys are periodically rotated (via reload or by using “tls-ticket-keys”). See also “tls-tickets”.
no-tlsv10
May be used in the following contexts: tcp, http, log, peers, ring
This option disables support for TLSv1.0 when SSL is used to communicate with the server. Note that SSLv2 is disabled in the code and cannot be enabled using any configuration option. TLSv1 is more expensive than SSLv3 so it often makes sense to disable it when communicating with local servers. This option is also available on global statement “ssl-default-server-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
Supported in default-server: No
no-tlsv11
May be used in the following contexts: tcp, http, log, peers, ring
This option disables support for TLSv1.1 when SSL is used to communicate with the server. Note that SSLv2 is disabled in the code and cannot be enabled using any configuration option. TLSv1 is more expensive than SSLv3 so it often makes sense to disable it when communicating with local servers. This option is also available on global statement “ssl-default-server-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
Supported in default-server: No
no-tlsv12
May be used in the following contexts: tcp, http, log, peers, ring
This option disables support for TLSv1.2 when SSL is used to communicate with the server. Note that SSLv2 is disabled in the code and cannot be enabled using any configuration option. TLSv1 is more expensive than SSLv3 so it often makes sense to disable it when communicating with local servers. This option is also available on global statement “ssl-default-server-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
Supported in default-server: No
no-tlsv13
May be used in the following contexts: tcp, http, log, peers, ring
This option disables support for TLSv1.3 when SSL is used to communicate with the server. Note that SSLv2 is disabled in the code and cannot be enabled using any configuration option. TLSv1 is more expensive than SSLv3 so it often makes sense to disable it when communicating with local servers. This option is also available on global statement “ssl-default-server-options”. Use “ssl-min-ver” and “ssl-max-ver” instead.
Supported in default-server: No
no-verifyhost
May be used in the following contexts: tcp, http, log, peers, ring
This option may be used as “server” setting to reset any “verifyhost” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “verifyhost” setting.
no-tfo
May be used in the following contexts: tcp, http, log, peers, ring
This option may be used as “server” setting to reset any “tfo” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “tfo” setting.
non-stick
May be used in the following contexts: tcp, http
Never add connections allocated to this sever to a stick-table. This may be used in conjunction with backup to ensure that stick-table persistence is disabled for backup servers.
npn <protocols>
May be used in the following contexts: tcp, http
This enables the NPN TLS extension and advertises the specified protocol list as supported on top of NPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). This requires that the SSL library is built with support for TLS extensions enabled (check with haproxy -vv). Note that the NPN extension has been replaced with the ALPN extension (see the “alpn” keyword), though this one is only available starting with OpenSSL 1.0.2.
observe <mode>
May be used in the following contexts: tcp, http
This option enables health adjusting based on observing communication with the server. By default this functionality is disabled and enabling it also requires to enable health checks. There are two supported modes: “layer4” and “layer7”. In layer4 mode, only successful/unsuccessful tcp connections are significant. In layer7, which is only allowed for http proxies, responses received from server are verified, like valid/wrong http code, unparsable headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
See also the “check”, “on-error” and “error-limit”.
on-error <mode>
May be used in the following contexts: tcp, http, log
Select what should happen when enough consecutive errors are detected. Currently, four modes are available:
- fastinter: force fastinter
- fail-check: simulate a failed check, also forces fastinter (default)
- sudden-death: simulate a pre-fatal failed health check, one more failed check will mark a server down, forces fastinter
- mark-down: mark the server immediately down and force fastinter
See also the “check”, “observe” and “error-limit”.
on-marked-down <action>
May be used in the following contexts: tcp, http, log
Modify what occurs when a server is marked down. Currently one action is available:
- shutdown-sessions: Shutdown peer streams. When this setting is enabled, all connections to the server are immediately terminated when the server goes down. It might be used if the health check detects more complex cases than a simple connection status, and long timeouts would cause the service to remain unresponsive for too long a time. For instance, a health check might detect that a database is stuck and that there’s no chance to reuse existing connections anymore. Connections killed this way are logged with a ‘D’ termination code (for “Down”).
Actions are disabled by default
on-marked-up <action>
May be used in the following contexts: tcp, http, log
Modify what occurs when a server is marked up. Currently one action is available:
- shutdown-backup-sessions: Shutdown streams on all backup servers. This is done only if the server is not in backup state and if it is not disabled (it must have an effective weight > 0). This can be used sometimes to force an active server to take all the traffic back after recovery when dealing with long sessions (e.g. LDAP, SQL, …). Doing this can cause more trouble than it tries to solve (e.g. incomplete transactions), so use this feature with extreme care. Streams killed because a server comes up are logged with an ‘U’ termination code (for “Up”).
Actions are disabled by default
pool-conn-name <expr>
May be used in the following contexts: http
When a backend connection is established, this expression is evaluated to generate the connection name. This name is one of the key properties of the connection in the idle server pool. See the “http-reuse” keyword. When a request looks up an existing idle connection, this expression is evaluated to match an identical connection.
In context where SSL SNI is used for backend connection, the connection name is automatically assigned to the result of the “sni” expression. This suits the most common usage. For more advanced setup, “pool-conn-name” may be used to override this.
See also: “http-reuse”, “sni”
pool-low-conn <max>
May be used in the following contexts: http
Set a low threshold on the number of idling connections for a server, below which a thread will not try to steal a connection from another thread. This can be useful to improve CPU usage patterns in scenarios involving many very fast servers, in order to ensure all threads will keep a few idle connections all the time instead of letting them accumulate over one thread and migrating them from thread to thread. Typical values of twice the number of threads seem to show very good performance already with sub-millisecond response times. The default is zero, indicating that any idle connection can be used at any time. It is the recommended setting for normal use. This only applies to connections that can be shared according to the same principles as those applying to “http-reuse”. In case connection sharing between threads would be disabled via “tune.idle-pool.shared”, it can become very important to use this setting to make sure each thread always has a few connections, or the connection reuse rate will decrease as thread count increases.
pool-max-conn <max>
May be used in the following contexts: http
Set the maximum number of idling connections for a server. -1 means unlimited connections, 0 means no idle connections. The default is -1. When idle connections are enabled, orphaned idle connections which do not belong to any client session anymore are moved to a dedicated pool so that they remain usable by future clients. This only applies to connections that can be shared according to the same principles as those applying to “http-reuse”.
pool-purge-delay <delay>
May be used in the following contexts: http
Sets the delay to start purging idle connections. Each <delay> interval, half of the idle
connections are closed. 0 means we don’t keep any idle connection. The default is 5s.
port <port>
May be used in the following contexts: tcp, http, log
Using the “port” parameter, it becomes possible to use a different port to send health-checks or to probe the agent-check. On some servers, it may be desirable to dedicate a port to a specific component able to perform complex tests which are more suitable to health-checks than the application. It is common to run a simple script in inetd for instance. This parameter is ignored if the “check” parameter is not set. See also the “addr” parameter.
proto <name>
May be used in the following contexts: tcp, http
Forces the multiplexer’s protocol to use for the outgoing connections to this server. It must be compatible with the mode of the backend (TCP or HTTP). It must also be usable on the backend side. The list of available protocols is reported in haproxy -vv.The protocols properties are reported: the mode (TCP/HTTP), the side (FE/BE), the mux name and its flags.
Some protocols are subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally some protocols don’t support upgrades (flag=NO_UPG). The HTX compatibility is also reported (flag=HTX).
Here are the protocols that may be used as argument to a “proto” directive on a server line:
quic: mode=HTTP side=FE|BE mux=QUIC flags=HTX|NO_UPG|FRAMED
qmux: mode=HTTP side=FE|BE mux=QMUX flags=HTX|NO_UPG
h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|HOL_RISK|NO_UPG
fcgi: mode=HTTP side=BE mux=FCGI flags=HTX|HOL_RISK|NO_UPG
h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG
none: mode=TCP side=FE|BE mux=PASS flags=NO_UPG
spop: mode=SPOP side=BE mux=SPOP flags=HOL_RISK|NO_UPGIdea behind this option is to bypass the selection of the best multiplexer’s protocol for all connections established to this server.
If the ALPN or the NPN settings are configured, the specified protocols should be compatible with the multiplexer’s protocol to avoid any issue. For instance, if “proto h1” is set, the ALPN should not be set to “h2”.
See also “ws” to use an alternative protocol for websocket streams.
QMux is a subset of QUIC which runs over TCP. It corresponds to the following draft protocol https://www.ietf.org/archive/id/draft-ietf-quic-qmux-01.html . It is considered experimental in haproxy for now.
quic-cc-algo { cubic | newreno | bbr | nocc }[(<args,...>)]
This is a QUIC specific setting to select the congestion control algorithm for any connection targeting this server. They are similar to those used by TCP. See the bind option with a similar name for a complete description of all customization options.
Default value: cubic
See also: “tune.quic.be.tx.pacing” and “tune.quic.be.cc.max-win-size”
redir <prefix>
May be used in the following contexts: http
The “redir” parameter enables the redirection mode for all GET and HEAD requests addressing this
server. This means that instead of having HAProxy forward the request to the server, it will send an
“HTTP 302” response with the “Location” header composed of this prefix immediately followed by the
requested URI beginning at the leading ‘/’ of the path component. That means that no trailing slash
should be used after <prefix>. All invalid requests will be rejected, and all non-GET or HEAD
requests will be normally served by the server. Note that since the response is completely forged,
no header mangling nor cookie insertion is possible in the response. However, cookies in requests
are still analyzed, making this solution completely usable to direct users to a remote location in
case of local disaster. Main use consists in increasing bandwidth for static servers by having the
clients directly connect to them. Note: never use a relative location here, it would cause a loop
between the client and HAProxy!
Example: server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
renegotiate
May be used in the following contexts: tcp, http, log
This option enables the secure renegotiation mechanism (RFC 5746 TLS Renegotiation Indication Extension) for a given SSL backend. It does not mean that renegotiation requests will be sent by the SSL client, it only allows backends to renegotiate when servers request it. It still requires that the underlying SSL library actually supports renegotiation. This option is also available on global statement “ssl-default-server-options”. Renegotiation is not possible anymore in TLS 1.3. If neither “renegotiate” nor “no-renegotiate” is specified, the SSL library’s default behavior is kept. Note that for instance OpenSSL library enables secure renegotiation by default while AWS-LC disable it.
rise <count>
May be used in the following contexts: tcp, http, log
The “rise” parameter states that a server will be considered as operational after <count>
consecutive successful health checks. This value defaults to 2 if unspecified. See also the “check”,
“inter” and “fall” parameters.
resolve-opts <option>,<option>,… May be used in the following contexts: tcp, http, log
Comma separated list of options to apply to DNS resolution linked to this server.
Available options:
-
allow-dup-ip By default, HAProxy prevents IP address duplication in a backend when DNS resolution at runtime is in operation. That said, for some cases, it makes sense that two servers (in the same backend, being resolved by the same FQDN) have the same IP address. For such case, simply enable this option. This is the opposite of prevent-dup-ip.
-
ignore-weight Ignore any weight that is set within an SRV record. This is useful when you would like to control the weights using an alternate method, such as using an “agent-check” or through the runtime api.
-
prevent-dup-ip Ensure HAProxy’s default behavior is enforced on a server: prevent reusing an IP address already set to a server in the same backend and sharing the same fqdn. This is the opposite of allow-dup-ip.
Example:
backend b_myapp
default-server init-addr none resolvers dns
server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
server s2 myapp.example.com:81 check resolve-opts allow-dup-ipWith the option allow-dup-ip set:
- if the nameserver returns a single IP address, then both servers will use it
- If the nameserver returns 2 IP addresses, then each server will pick up a different address
Default value: not set
resolve-prefer <family>
May be used in the following contexts: tcp, http, log
When DNS resolution is enabled for a server and multiple IP addresses from different families are returned, HAProxy will prefer using an IP address from the family mentioned in the “resolve-prefer” parameter. See also the global “dns-accept-family” keyword to enforce strict usage of a specific family. Available families: “ipv4” and “ipv6”.
Default value: ipv6
Example:
resolve-net <network>[,<network[,...]]
May be used in the following contexts: tcp, http, log
This option prioritizes the choice of an ip address matching a network. This is useful with clouds to prefer a local ip. In some cases, a cloud high availability service can be announced with many ip addresses on many different datacenters. The latency between datacenter is not negligible, so this patch permits to prefer a local datacenter. If no address matches the configured network, another address is selected.
Example:
resolvers <id>
May be used in the following contexts: tcp, http, log
Points to an existing “resolvers” section to resolve current server’s hostname. It is often recommended to disable libc-based resolution when using resolvers, though exceptions exist (see section 5.3.1 ). In any case it is a good practice to explicitly specify “init-addr” when using resolvers in order not to overlook this element.
Example:
See also section 5.3 for implementation details and traps to be aware of.
send-proxy
May be used in the following contexts: tcp, http
The “send-proxy” parameter enforces use of the PROXY protocol over any connection established to this server. The PROXY protocol informs the other end about the layer 3/4 addresses of the incoming connection, so that it can know the client’s address or the public address it accessed to, whatever the upper layer protocol. For connections accepted by an “accept-proxy” or “accept-netscaler-cip” listener, the advertised address will be used. Only TCPv4 and TCPv6 address families are supported. Other families such as Unix sockets, will report an UNKNOWN family. Servers using this option can fully be chained to another instance of HAProxy listening with an “accept-proxy” setting. This setting must not be used if the server isn’t aware of the protocol. When health checks are sent to the server, the PROXY protocol is automatically used when this option is set, unless there is an explicit “port” or “addr” directive, in which case an explicit “check-send-proxy” directive would also be needed to use the PROXY protocol. See also the “no-send-proxy” option of this section and “accept-proxy” and “accept-netscaler-cip” option of the “bind” keyword.
send-proxy-v2
May be used in the following contexts: tcp, http
The “send-proxy-v2” parameter enforces use of the PROXY protocol version 2 over any connection established to this server. The PROXY protocol informs the other end about the layer 3/4 addresses of the incoming connection, so that it can know the client’s address or the public address it accessed to, whatever the upper layer protocol. It also send ALPN information if an alpn have been negotiated. This setting must not be used if the server isn’t aware of this version of the protocol. See also the “no-send-proxy-v2” option of this section and send-proxy" option of the “bind” keyword.
set-proxy-v2-tlv-fmt(<id>) <fmt>
May be used in the following contexts: tcp, http
The “set-proxy-v2-tlv-fmt” parameter is used to send arbitrary PROXY protocol version 2 TLVs. For
the type (<id>) range of the defined TLV type please refer to section 2.2.8. of the proxy protocol
specification. However, the value can be chosen freely as long as it does not exceed the maximum
length of 65,535 bytes. It can also be used for forwarding TLVs by using the fetch “fc_pp_tlv” to
retrieve a received TLV from the frontend. It may be used as a server or a default-server option. It
must be used in combination with send-proxy-v2 such that PPv2 TLVs are actually sent out.
Example: server srv1 192.168.1.1:80 send-proxy-v2 set-proxy-v2-tlv-fmt(0x20) %[fc_pp_tlv(0x20)]
In this case, we fetch the TLV with the type 0x20 as a string and set as the value of a newly created TLV that also has the type 0x20.
proxy-v2-options <option>[,<option>]*
May be used in the following contexts: tcp, http
The “proxy-v2-options” parameter add options to send in PROXY protocol version 2 when “send-proxy-v2” is used. Options available are:
- ssl : See also “send-proxy-v2-ssl”.
- cert-cn : See also “send-proxy-v2-ssl-cn”.
- ssl-cipher: Name of the used cipher.
- cert-sig : Signature algorithm of the used certificate.
- cert-key : Key algorithm of the used certificate
- authority: Host name value passed by the client (only SNI from a TLS connection is supported).
- crc32c : Checksum of the PROXYv2 header.
- unique-id: Send a unique ID generated using the frontend’s “unique-id-format” within the PROXYv2 header. This unique-id is primarily meant for “mode tcp”. It can lead to unexpected results in “mode http”, because the generated unique ID is also used for the first HTTP request within a Keep-Alive connection.
send-proxy-v2-ssl
May be used in the following contexts: tcp, http
The “send-proxy-v2-ssl” parameter enforces use of the PROXY protocol version 2 over any connection established to this server. The PROXY protocol informs the other end about the layer 3/4 addresses of the incoming connection, so that it can know the client’s address or the public address it accessed to, whatever the upper layer protocol. In addition, the SSL information extension of the PROXY protocol is added to the PROXY protocol header. This setting must not be used if the server isn’t aware of this version of the protocol. See also the “no-send-proxy-v2-ssl” option of this section and the “send-proxy-v2” option of the “bind” keyword.
send-proxy-v2-ssl-cn
May be used in the following contexts: tcp, http
The “send-proxy-v2-ssl” parameter enforces use of the PROXY protocol version 2 over any connection established to this server. The PROXY protocol informs the other end about the layer 3/4 addresses of the incoming connection, so that it can know the client’s address or the public address it accessed to, whatever the upper layer protocol. In addition, the SSL information extension of the PROXY protocol, along along with the Common Name from the subject of the client certificate (if any), is added to the PROXY protocol header. This setting must not be used if the server isn’t aware of this version of the protocol. See also the “no-send-proxy-v2-ssl-cn” option of this section and the “send-proxy-v2” option of the “bind” keyword.
shard <shard>
May be used in the following contexts: peers
This parameter in used only in the context of stick-tables synchronisation with peers protocol. The “shard” parameter identifies the peers which will receive all the stick-table updates for keys with this shard as distribution hash. The accepted values are 0 up to “shards” parameter value specified in the “peers” section. 0 value is the default value meaning that the peer will receive all the key updates. Greater values than “shards” will be ignored. This is also the case for any value provided to the local peer.
Example:
peers mypeers shards 3 peer A 127.0.0.1:40001 # local peer without shard value (0 internally) peer B 127.0.0.1:40002 shard 1 peer C 127.0.0.1:40003 shard 2 peer D 127.0.0.1:40004 shard 3
sigalgs <sigalgs>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of signature algorithms that are negotiated during the TLSv1.2 and TLSv1.3 handshake. The format of the string is defined in “man 3 SSL_CTX_set1_sigalgs” from the OpenSSL man pages. It is not recommended to use this setting unless compatibility with a middlebox is required.
slowstart <start_time_in_ms>
May be used in the following contexts: tcp, http
The “slowstart” parameter for a server accepts a value in milliseconds which indicates after how long a server which has just come back up will run at full speed. Just as with every other time-based parameter, it can be entered in any other explicit unit among { us, ms, s, m, h, d }. The speed grows linearly from 0 to 100% during this time. The limitation applies to two parameters:
-
maxconn: the number of connections accepted by the server will grow from 1 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
-
weight: when the backend uses a dynamic weighted algorithm, the weight grows linearly from 1 to 100%. In this case, the weight is updated at every health-check. For this reason, it is important that the “inter” parameter is smaller than the “slowstart”, in order to maximize the number of steps.
The slowstart never applies when HAProxy starts, otherwise it would cause trouble to running servers. It only applies when a server has been previously seen as failed.
sni <expression>
May be used in the following contexts: tcp, http, log, peers, ring
The “sni” parameter evaluates the sample fetch expression, converts it to a string and uses the result as the host name sent in the SNI TLS extension to the server. A typical use case is to send the SNI received from the client in a bridged TCP/SSL scenario, using the “ssl_fc_sni” sample fetch for the expression. THIS MUST NOT BE USED FOR HTTPS, where req.hdr(host) should be used instead, since SNI in HTTPS must always match the Host field and clients are allowed to use different host names over the same connection). If “verify required” is set (which is the recommended setting), the resulting name will also be matched against the server certificate’s names. See the “verify” directive for more details. If you want to set a SNI for health checks, see the “check-sni” directive for more details.
By default, the SNI is assigned to the connection name for “http-reuse”, unless overridden by the “pool-conn-name” server keyword.
sni-auto
May be used in the following contexts: tcp, http, log, peers, ring
The “sni-auto” parameter enables the automatic SNI selection, if no value was already set. It sets the “sni” expression to “req.hdr(host),field(1,:)”, which means that an SNI will be presented with the Host name of the request that is being sent to the server, but dropping the port number. It is enabled by default but this parameter may be used as “server” setting to reset any “no-sni-auto” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “no-sni-auto” setting.
For HTTPS connections, the selected SNI is based on the request host header value, if found. Otherwise it remains unset. For other protocols, the option is ignored.
If the automatic selection of the SNI is used, the value is assigned to the connection name for “http-reuse”, unless overridden by the “pool-conn-name” server keyword.
See “check-sni-auto” option to enable automatic SNI selection for SSL health checks.
source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
source <addr>[:<pl>[-<ph>]] [interface <name>] ...May be used in the following contexts: tcp, http, log, peers, ring
The “source” parameter sets the source address which will be used when connecting to the server. It follows the exact same parameters and principle as the backend “source” keyword, except that it only applies to the server referencing it. Please consult the “source” keyword for details.
Additionally, the “source” statement on a server line allows one to specify a source port range by indicating the lower and higher bounds delimited by a dash (’-’). Some operating systems might require a valid IP address when a source port range is specified. It is permitted to have the same IP/range for several servers. Doing so makes it possible to bypass the maximum of 64k total concurrent connections. The limit will then reach 64k connections per server.
Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections specifying the source address without port(s).
ssl
May be used in the following contexts: tcp, http, log, peers, ring
This option enables SSL ciphering on outgoing connections to the server. It is critical to verify server certificates using “verify” when using SSL to connect to servers, otherwise the communication is prone to trivial man in the-middle attacks rendering SSL useless. When this option is used, health checks are automatically sent in SSL too unless there is a “port” or an “addr” directive indicating the check should be sent to a different location. See the “no-ssl” to disable “ssl” option and “check-ssl” option to force SSL health checks.
ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of <version> or lower when SSL is used to communicate with the server.
This option is also available on global statement “ssl-default-server-options”. See also
“ssl-min-ver”.
ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
May be used in the following contexts: tcp, http, log, peers, ring
This option enforces use of <version> or upper when SSL is used to communicate with the server.
This option is also available on global statement “ssl-default-server-options”. See also
“ssl-max-ver”.
ssl-reuse
May be used in the following contexts: tcp, http, log, peers, ring
This option may be used as “server” setting to reset any “no-ssl-reuse” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “no-ssl-reuse” setting.
stick
May be used in the following contexts: tcp, http
This option may be used as “server” setting to reset any “non-stick” setting which would have been inherited from “default-server” directive as default value. It may also be used as “default-server” setting to reset any previous “default-server” “non-stick” setting.
strict-maxconn
May be used in the following contexts: tcp, http
maxconn to servers is a bit of a misnomer, it actually configure the maximum number of requests we send to a server, but with idle connections, we may have more total connections to the server. If a strict limit of connections to a server is required, then adding strict-maxconn can be used. We will then never establish more connections to a server than maxconn, and try to reuse or kill connections if needed. Please note, however, than it may lead to failed requests in case we can’t establish a new connection, and no idle connection is available. This can happen when “private” connections are established, connections tied only to a session, because authentication happened.
socks4 <addr>:<port>
May be used in the following contexts: tcp, http, log, peers, ring
This option enables upstream socks4 tunnel for outgoing connections to the server. Using this option won’t force the health check to go via socks4 by default. You will have to use the keyword “check-via-socks4” to enable it.
tcp-md5sig <password>
May be used in the following contexts: tcp, http, log, peers, ring
Enables the TCP MD5 signature (RFC 2385 Protection of BGP Sessions via the TCP MD5 Signature Option)
for all outgoing connections to this server. This option is only available on Linux. When enabled,
<password> string is used to sign every TCP segments with a 16-byte MD5 digest. This will protect
the TCP connection against spoofing. The primary use case for this option is to allow BGP to protect
itself against the introduction of spoofed TCP segments into the connection stream. But it can be
useful for any very long-lived TCP connections.
tcp-ut <delay>
May be used in the following contexts: tcp, http, log, peers, ring
Sets the TCP User Timeout for all outgoing connections to this server. This option is available on Linux since version 2.6.37. It allows HAProxy to configure a timeout for sockets which contain data not receiving an acknowledgment for the configured delay. This is especially useful on long-lived connections experiencing long idle periods such as remote terminals or database connection pools, where the client and server timeouts must remain high to allow a long period of idle, but where it is important to detect that the server has disappeared in order to release all resources associated with its connection (and the client’s session). One typical use case is also to force dead server connections to die when health checks are too slow or during a soft reload since health checks are then disabled. The argument is a delay expressed in milliseconds by default. This only works for regular TCP connections, and is ignored for other protocols.
tfo
May be used in the following contexts: tcp, http, log, peers, ring
This option enables using TCP fast open when connecting to servers, on systems that support it (currently only the Linux kernel >= 4.11). See the “tfo” bind option for more information about TCP fast open. Please note that when using tfo, you should also use the “conn-failure”, “empty-response” and “response-timeout” keywords for “retry-on”, or HAProxy won’t be able to retry the connection on failure. See also “no-tfo”.
track [<backend>/]<server>
May be used in the following contexts: tcp, http, log
This option enables ability to set the current state of the server by tracking another one. It is
possible to track a server which itself tracks another server, provided that at the end of the
chain, a server has health checks enabled. If <backend> is omitted the current one is used. If
disable-on-404 is used, it has to be enabled on both proxies.
Example:
backend A
server a1 1.1.1.1:80 track B/b1
server a2 1.1.1.2:80 track B/b1
backend B
server b1 2.2.2.2:80 checktls-tickets
May be used in the following contexts: tcp, http, log, peers, ring
This option may be used as “server” setting to reset any “no-tls-tickets” setting which would have been inherited from “default-server” directive as default value. The TLS ticket mechanism is only used up to TLS 1.2. Forward Secrecy is compromised with TLS tickets, unless ticket keys are periodically rotated (via reload or by using “tls-ticket-keys”). It may also be used as “default-server” setting to reset any previous “default-server” “no-tls-tickets” setting.
verify [none|required]
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in. If set to ’none’, server certificate is not verified. In the other case, The certificate provided by the server is verified using CAs from ‘ca-file’ and optional CRLs from ‘crl-file’ after having checked that the names provided in the certificate’s subject and subjectAlternateNames attributes match either the name passed using the “sni” directive, or if not provided, the static host name passed using the “verifyhost” directive. When no name is found, the certificate’s names are ignored. For this reason, without SNI it’s important to use “verifyhost”. On verification failure the handshake is aborted. It is critically important to verify server certificates when using SSL to connect to servers, otherwise the communication is prone to trivial man-in-the-middle attacks rendering SSL totally useless. Unless “ssl_server_verify” appears in the global section, “verify” is set to “required” by default.
verifyhost <hostname>
May be used in the following contexts: tcp, http, log, peers, ring
This setting is only available when support for OpenSSL was built in, and only takes effect if ‘verify required’ is also specified. This directive sets a default static hostname to check the server’s certificate against when no SNI was used to connect to the server. If SNI is not used, this is the only way to enable hostname verification. This static hostname, when set, will also be used for health checks (which cannot provide an SNI value). If none of the hostnames in the certificate match the specified hostname, the handshake is aborted. The hostnames in the server-provided certificate may include wildcards. See also “verify”, “sni” and “no-verifyhost” options.
weight <weight>
May be used in the following contexts: tcp, http
The “weight” parameter is used to adjust the server’s weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights, so the higher the weight, the higher the load. The default weight is 1, and the maximal value is 256. A value of 0 means the server will not participate in load-balancing but will still accept persistent connections. If this parameter is used to distribute the load according to server’s capacity, it is recommended to start with values which can both grow and shrink, for instance between 10 and 100 to leave enough room above and below for later adjustments.
ws { auto | h1 | h2 }
May be used in the following contexts: http
This option allows to configure the protocol used when relaying websocket streams. This is most notably useful when using an HTTP/2 backend without the support for H2 websockets through the RFC8441.
The default mode is “auto”. This will reuse the same protocol as the main one. The only difference is when using ALPN. In this case, it can try to downgrade the ALPN to “http/1.1” only for websocket streams if the configured server ALPN contains it.
The value “h1” is used to force HTTP/1.1 for websockets streams, through ALPN if SSL ALPN is activated for the server. Similarly, “h2” can be used to force HTTP/2.0 websockets. Use this value with care: the server must support RFC8441 or an error will be reported by haproxy when relaying websockets.
Note that NPN is not taken into account as its usage has been deprecated in favor of the ALPN extension.
See also “alpn” and “proto”.
5.3. Server IP address resolution using DNS
HAProxy allows using a host name on the server line to retrieve its IP address using name servers. By default, HAProxy resolves the name when parsing the configuration file, at startup and cache the result for the process’s life. This is not sufficient in some cases, such as in Amazon where a server’s IP can change after a reboot or an ELB Virtual IP can change based on current workload.
This chapter describes how HAProxy can be configured to process server’s name resolution at run time.
Whether run time server name resolution has been enable or not, by default HAProxy will do the first resolution at startup during configuration parsing via libc unless disabled by the “init-addr” parameter.
5.3.1. Global overview
As we’ve seen in introduction, name resolution in HAProxy occurs at two different steps of the process life:
1. when starting up, HAProxy parses the server line definition and matches a
host name. It uses libc functions to get the host name resolved. This
resolution relies on /etc/resolv.conf file.
2. at run time, HAProxy performs periodically name resolutions for servers
requiring DNS resolutions.A few other events can trigger a name resolution at run time:
- when a server’s health check ends up in a connection timeout: this may be because the server has a new IP address. So we need to trigger a name resolution to know this new IP.
When using resolvers, the server name can either be a hostname, or a SRV label. HAProxy considers anything that starts with an underscore as a SRV label. If a SRV label is specified, then the corresponding SRV records will be retrieved from the DNS server, and the provided hostnames will be used. The SRV label will be checked periodically, and if any server are added or removed, HAProxy will automatically do the same.
A few things important to notice:
-
all the name servers are queried in the meantime. HAProxy will process the first valid response.
-
a resolution is considered as invalid (NX, timeout, refused), when all the servers return an error.
-
The DNS client implemented in HAProxy is very basic and will not understand the vast number of options and advanced setups that an operating system’s resolver can deal with. As such, except for really trivial setups where a server known by its FQDN only has exactly one IP address at a time and might occasionally renew it (e.g. a reboot), it is highly recommended to avoid mixing libc-based init-time resolution with DNS-based runtime resolution, as such setups are known to cause failures upon address renewal. As a conclusion, unless you know exactly what you are doing, you should always exclude “libc” from “init-addr” when using “resolvers” on a server line.
5.3.2. The resolvers section
This section is dedicated to host information related to name resolution in HAProxy. There can be as many as resolvers section as needed. Each section can contain many name servers.
At startup, HAProxy tries to generate a resolvers section named “default”, if no section was named this way in the configuration. This section is used by default by the httpclient and uses the parse-resolv-conf keyword. If HAProxy failed to generate automatically this section, no error or warning are emitted.
When multiple name servers are configured in a resolvers section, then HAProxy uses the first valid response. In case of invalid responses, only the last one is treated. Purpose is to give the chance to a slow server to deliver a valid answer after a fast faulty or outdated server.
When each server returns a different error type, then only the last error is used by HAProxy. The following processing is applied on this error:
1. HAProxy retries the same DNS query with a new query type. The A queries are
switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
errors are also excluded.
2. When the fallback on the query type was done (or not applicable), HAProxy
retries the original DNS query, with the preferred query type.
3. HAProxy retries previous steps <resolve_retries> times. If no valid
response is received after that, it stops the DNS resolution and reports
the error.For example, with 2 name servers configured in a resolvers section, the following scenarios are possible:
-
First response is valid and is applied directly, second response is ignored
-
First response is invalid and second one is valid, then second response is applied
-
First response is a NX domain and second one a truncated response, then HAProxy retries the query with a new type
-
First response is a NX domain and second one is a timeout, then HAProxy retries the query with a new type
-
Query timed out for both name servers, then HAProxy retries it with the same query type
As a DNS server may not answer all the IPs in one DNS request, HAProxy keeps a cache of previous
answers, an answer will be considered obsolete after <hold obsolete> seconds without the IP
returned.
resolvers <resolvers id>
Creates a new name server list labeled <resolvers id>. As mentioned above, the special name
“default” always exists and will be automatically created if not explicitly declared; this will be
the one internal services such as httpclient rely on. Declaring a “default” entry will affect how
such services perform their name resolution.
A resolvers section accept the following parameters:
accepted_payload_size <nb>
Defines the maximum payload size accepted by HAProxy and announced to all the name servers
configured in this resolvers section. <nb> is in bytes. If not set, HAProxy announces 512.
(minimal value defined by RFC 6891)
Note: the maximum allowed value is 65535. Recommended value for UDP is 4096 and it is not recommended to exceed 8192 except if you are sure that your system and network can handle this (over 65507 makes no sense since is the maximum UDP payload size). If you are using only TCP nameservers to handle huge DNS responses, you should put this value to the max: 65535.
nameserver <name> <address>[:port] [param*]
Used to configure a nameserver. <name> of the nameserver should ne unique. By default the
<address> is considered of type datagram. This means if an IPv4 or IPv6 is configured without
special address prefixes (paragraph 11.) the UDP protocol will be used. If an stream protocol
address prefix is used, the nameserver will be considered as a stream server (TCP for instance) and
“server” parameters found in 5.2 paragraph which are relevant for DNS resolving will be considered.
Note: currently, in TCP mode, 4 queries are pipelined on the same connections. A batch of idle
connections are removed every 5 seconds. “maxconn” can be configured to limit the amount of those
concurrent connections and TLS should also usable if the server supports.
parse-resolv-conf
Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers list. Ordered as if each nameserver in /etc/resolv.conf was individually placed in the resolvers section in place of this directive.
hold <status> <period>
Upon receiving the DNS response <status>, determines whether a server’s state should change from
UP to DOWN. To make that determination, it checks whether any valid status has been received during
the past <period> in order to counteract the just received invalid status.
`<status>`: last name resolution status.
nx After receiving an NXDOMAIN status, check for any valid
status during the concluding period.
refused After receiving a REFUSED status, check for any valid
status during the concluding period.
timeout After the "timeout retry" has struck, check for any
valid status during the concluding period.
other After receiving any other invalid status, check for any
valid status during the concluding period.
valid Applies only to "http-request do-resolve" and
"tcp-request content do-resolve" actions. It defines the
period for which the server will maintain a valid response
before triggering another resolution. It does not affect
dynamic resolution of servers.
obsolete Defines how long to wait before removing obsolete DNS
records after an updated answer record is received. It
applies to SRV records.
`<period>`: Amount of time into the past during which a valid response must
have been received. It follows the HAProxy time format and is in
milliseconds by default.
For a server that relies on dynamic DNS resolution to determine its IP address, receiving an invalid
DNS response, such as NXDOMAIN, will lead to changing the server’s state from UP to DOWN. The hold
directives define how far into the past to look for a valid response. If a valid response has been
received within <period>, the just received invalid status will be ignored.
Unless a valid response has been receiving during the concluding period, the server will be marked as DOWN. For example, if “hold nx 30s” is set and the last received DNS response was NXDOMAIN, the server will be marked DOWN unless a valid response has been received during the last 30 seconds.
A server in the DOWN state will be marked UP immediately upon receiving a valid status from the DNS server.
A separate behavior exists for “hold valid” and “hold obsolete”.
Default value is 10s for “valid”, 0s for “obsolete” and 30s for others.
resolve_retries <nb>
Defines the number <nb> of queries to send to resolve a server name before giving up. Default
value: 3
A retry occurs on name server timeout or when the full sequence of DNS query type failover is over and we need to start up from the default ANY query type.
timeout <event> <time>
Defines timeouts related to name resolution <event>: the event on which the <time> timeout
period applies to. events available are: - resolve: default time to trigger name resolutions when no
other time applied. Default value: 1s - retry : time between two DNS queries, when no valid response
have been received. Default value: 1s <time> : time related to the event. It follows the HAProxy
time format. <time> is expressed in milliseconds.
Example:
Source and license
Documentation imported from pig.center · Upstream documentation
- Version
- 3.4.4
- License
- GPL-2.0-only
- Source revision
c88f04bf458bba252baf739fd65c4f81e9f4167aaf78c0d4d3960e5d416c8f7b