---
title: "5. Bind and Server Options"
linkTitle: "5. Bind & Server Options"
weight: 160
description: "Listener, server, default-server, and DNS resolution options"
icon: fa-solid fa-network-wired
module: [HAPROXY]
categories: [Reference]
aliases:
- /haproxy/configuration/bind-and-server-options/
- /docs/haproxy/configuration/bind-and-server-options/
- /haproxy/bind-and-server-options/
upstream_link: "https://docs.haproxy.org/3.4/configuration.html"
upstream_name: "HAProxy 3.4 Configuration Manual"
upstream_ref: "v3.4.4, chapter 5"
---
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 {#section-5-1}
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.
`**
```haproxy
accept-netscaler-cip
```
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.
`**
```haproxy
alpn
```
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:
```text
bind:443 ssl crt pub.pem alpn h2 # explicitly disable HTTP/1.1
```
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 ). 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.
`**
```haproxy
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.
`**
```haproxy
ca-file
```
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.
,...]`**
```haproxy
ca-ignore-err [all|,...]
```
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:
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.
`**
```haproxy
ca-sign-file
```
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.
`**
```haproxy
ca-sign-pass
```
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.
`**
```haproxy
ca-verify-file
```
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.
`**
```haproxy
cc
```
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](/docs/haproxy/bind-and-server-options/#section-5-2)). Example:
```text
frontend public
bind:443 cc bbr # use the BBR algorithm for high bandwidths
```
`**
```haproxy
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.
() and
(`**
```haproxy
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:
```text
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_SHA256
```
`**
```haproxy
client-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.
`**
```haproxy
crl-file
```
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.
`**
```haproxy
crt
```
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](http://www.example.org) but not
[www.sub.example.org](http://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.pem` in the
configuration where the existing files are `foobar.pem.ecdsa` and `foobar.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".
`**
```haproxy
crt-ignore-err
```
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:
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.
`**
```haproxy
crt-list
```
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:
```text
[\[ ...\]] [[!] ...]
```
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:
```text
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 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 . HAProxy
will duplicate the crt-list line internally, adding an algorithm extension
(.rsa, .ecdsa, .dsa) when loading the file.
```
sslbindconf:
```text
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
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 , if none were
specified, the default options are inherited, the parameters specified in
overwrite those inherited settings.
```
snifilter:
```text
When the 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 is used instead.
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 . 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:
```shell
# 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.com
```
`**
```haproxy
default-crt
```
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:
```shell
# 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.ecdsa
```
See also the "crt" keyword.
`**
```haproxy
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.
`**
```haproxy
ecdhe
```
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.
[ EXPERIMENTAL ]`**
```haproxy
ech [ EXPERIMENTAL ]
```
Apply all ECH keys from `` to the bind line. The files must have the .ech extension and must
use the PEM file format for ECH. ( ), and HAProxy must be compiled with USE_ECH=1.
The ECH API of AWS-LC is not supported.
Example:
```shell
$ 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..9vYmFyLmNvbQAA
```
`**
```haproxy
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.
`**
```haproxy
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.
`**
```haproxy
guid-prefix
```
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".
`**
```haproxy
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.
`**
```haproxy
idle-ping
```
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.
`**
```haproxy
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.
[ EXPERIMENTAL ]`**
```haproxy
ktls [ 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".
`**
```haproxy
label
```
Sets an optional label for these sockets. It could be used group sockets by label, independently of
where the bind lines were declared.
`**
```haproxy
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. `` 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).
`**
```haproxy
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.
`**
```haproxy
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.
`**
```haproxy
mss
```
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.
`**
```haproxy
name
```
Sets an optional name for these sockets, which will be reported on the stats page.
`**
```haproxy
namespace
```
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.
[ EXPERIMENTAL ]`**
```haproxy
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.
`**
```haproxy
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.
`**
```haproxy
npn
```
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.
`**
```haproxy
proto
```
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:
```text
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_UPG
```
Idea 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
. It is considered experimental in
haproxy for now.
)]`**
```haproxy
quic-cc-algo { cubic | newreno | bbr | nocc }[()]
```
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:
```shell
# 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.
for more information about QUIC
retry.
`**
```haproxy
severity-output
```
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. `` 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.
| by-thread | by-group }`**
```haproxy
shards { | 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.
`**
```haproxy
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.
` 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".
` 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".
`**
```haproxy
tcp-md5sig
```
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, `` 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.
`**
```haproxy
tcp-ss
```
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".
`**
```haproxy
tcp-ut
```
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.
/][,...]`**
```haproxy
thread [/][,...]
```
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:
```text
"all" | "odd" | "even" | [number][-[number]]
```
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.
`**
```haproxy
tls-ticket-keys
```
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.
`**
```haproxy
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.
`**
```haproxy
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.
[:port] [settings ...]
default-server [settings ...]
```
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.
`**
```haproxy
addr
```
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.
`**
```haproxy
agent-send
```
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.
`**
```haproxy
agent-inter
```
May be used in the following contexts: tcp, http, log
The "agent-inter" parameter sets the interval between two agent checks to `` 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.
`**
```haproxy
agent-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.
`**
```haproxy
agent-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.
`**
```haproxy
alpn
```
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:
```text
server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1
```
See also "ws" to use an alternative ALPN for websocket streams.
`**
```haproxy
ca-file
```
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.
`**
```haproxy
cc
```
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](/docs/haproxy/bind-and-server-options/#section-5-1)).
`**
```haproxy
check-alpn
```
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.
`**
```haproxy
check-pool-conn-name
```
May be used in the following contexts: tcp, http
When connection reuse is performed for checks, uses `` 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"
`**
```haproxy
check-proto
```
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:
```text
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_UPG
```
Idea 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.
`**
```haproxy
check-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 ``. If you want to set a SNI for proxied traffic, see "sni".
`**
```haproxy
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.
() and
(`**
```haproxy
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.
`**
```haproxy
client-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.
`**
```haproxy
cookie
```
May be used in the following contexts: http
The "cookie" parameter sets the cookie value assigned to the server to ``. 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.
`**
```haproxy
crl-file
```
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.
`**
```haproxy
crt
```
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).
`**
```haproxy
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)
`**
```haproxy
error-limit
```
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".
`**
```haproxy
fall
```
May be used in the following contexts: tcp, http, log
The "fall" parameter states that a server will be considered as dead after `` consecutive
unsuccessful health checks. This value defaults to 3 if unspecified. See also the "check", "inter"
and "rise" parameters.
`**
```haproxy
guid
```
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".
`**
```haproxy
hash-key
```
May be used in the following contexts: tcp, http, log
Specify how "hash-type consistent" node keys are computed
Arguments:
```text
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.
`**
```haproxy
healthcheck
```
May be used in the following contexts: tcp, http
Specify the health-check section to use to perform check on the server.
Argument:
```text
is the health-check section name.
```
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".
`**
```haproxy
id
```
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.
`**
```haproxy
idle-ping
```
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.
},[...]*`**
```haproxy
init-addr {last | libc | none | },[...]*
```
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](/docs/haproxy/bind-and-server-options/#section-5-3) for more details).
Example 1:
```text
defaults
# never fail on address resolution
default-server init-addr last,libc,none
```
Example 2:
```text
defaults
# disable libc resolution in combination with resolvers
default-server init-addr last,none
```
`**
```haproxy
inter
fastinter
downinter
```
May be used in the following contexts: tcp, http, log
The "inter" parameter sets the interval between two consecutive health checks to ``
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:
```text
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.
[ EXPERIMENTAL ]`**
```haproxy
ktls [ 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".
`**
```haproxy
log-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")
`**
```haproxy
log-proto
```
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.
`**
```haproxy
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.
`**
```haproxy
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".
`**
```haproxy
max-reuse
```
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.
`**
```haproxy
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 `` connections, never more than
``, and the limit will be on the ramp between both values when the backend has less than
`` 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.
`**
```haproxy
namespace
```
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.
`**
```haproxy
npn
```
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.
`**
```haproxy
observe
```
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".
`**
```haproxy
on-error
```
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".
`**
```haproxy
on-marked-down
```
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
`**
```haproxy
on-marked-up
```
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
`**
```haproxy
pool-conn-name
```
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"
`**
```haproxy
pool-low-conn
```
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.
`**
```haproxy
pool-max-conn
```
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".
`**
```haproxy
pool-purge-delay
```
May be used in the following contexts: http
Sets the delay to start purging idle connections. Each `` interval, half of the idle
connections are closed. 0 means we don't keep any idle connection. The default is 5s.
`**
```haproxy
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.
`**
```haproxy
proto
```
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:
```text
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_UPG
```
Idea 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
. It is considered experimental in
haproxy for now.
)]`**
```haproxy
quic-cc-algo { cubic | newreno | bbr | nocc }[()]
```
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"
`**
```haproxy
redir
```
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 ``. 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 check
`**
```haproxy
rise
```
May be used in the following contexts: tcp, http, log
The "rise" parameter states that a server will be considered as operational after ``
consecutive successful health checks. This value defaults to 2 if unspecified. See also the "check",
"inter" and "fall" parameters.
resolve-opts ``,` `,... 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:
```text
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-ip
```
With 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
`**
```haproxy
resolve-prefer
```
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:
```text
server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
```
[,[,