5.1. Bind options

  1. The "bind" keyword supports a certain number of settings which are all passed
  2. as arguments on the same line. The order in which those arguments appear makes
  3. no importance, provided that they appear after the bind address. All of these
  4. parameters are optional. Some of them consist in a single words (booleans),
  5. while other ones expect a value after them. In this case, the value must be
  6. provided immediately after the setting name.
  7.  
  8. The currently supported settings are the following ones.

accept-netscaler-cip 

  1. Enforces the use of the NetScaler Client IP insertion protocol over any
  2. connection accepted by any of the TCP sockets declared on the same line. The
  3. NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
  4. the incoming connection to be used everywhere an address is used, with the
  5. only exception of "tcp-request connection" rules which will only see the
  6. real connection address. Logs will reflect the addresses indicated in the
  7. protocol, unless it is violated, in which case the real  address will still
  8. be used. This keyword combined with support from external components can be
  9. used as an efficient and reliable alternative to the X-Forwarded-For
  10. mechanism which is not always reliable and not even always usable. See also
  11. "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
  12. which client is allowed to use the protocol.

accept-proxy

  1. Enforces the use of the PROXY protocol over any connection accepted by any of
  2. the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
  3. are supported and correctly detected. The PROXY protocol dictates the layer
  4. 3/4 addresses of the incoming connection to be used everywhere an address is
  5. used, with the only exception of "tcp-request connection" rules which will
  6. only see the real connection address. Logs will reflect the addresses
  7. indicated in the protocol, unless it is violated, in which case the real
  8. address will still be used. This keyword combined with support from external
  9. components can be used as an efficient and reliable alternative to the
  10. X-Forwarded-For mechanism which is not always reliable and not even always
  11. usable. See also "tcp-request connection expect-proxy" for a finer-grained
  12. setting of which client is allowed to use the protocol.

allow-0rtt

  1. Allow receiving early data when using TLSv1.3. This is disabled by default,
  2. due to security considerations. Because it is vulnerable to replay attacks,
  3. you should only allow if for requests that are safe to replay, i.e. requests
  4. that are idempotent. You can use the "wait-for-handshake" action for any
  5. request that wouldn't be safe with early data.

alpn 

  1. This enables the TLS ALPN extension and advertises the specified protocol
  2. list as supported on top of ALPN. The protocol list consists in a comma-
  3. delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
  4. quotes). This requires that the SSL library is built with support for TLS
  5. extensions enabled (check with haproxy -vv). The ALPN extension replaces the
  6. initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
  7. Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
  8. now obsolete NPN extension. At the time of writing this, most browsers still
  9. support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
  10. a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
  11. are expected to be supported, both versions can be advertised, in order of
  12. preference, like below :
  13.  
  14.      bind :443 ssl crt pub.pem alpn h2,http/1.1

backlog 

  1. Sets the socket's backlog to this value. If unspecified or 0, the frontend's
  2. backlog is used instead, which generally defaults to the maxconn value.

curves 

  1. This setting is only available when support for OpenSSL was built in. It sets
  2. the string describing the list of elliptic curves algorithms ("curve suite")
  3. that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
  4. string is a colon-delimited list of curve name.

Example:

  1. "X25519:P-256" (without quote)
    When "curves" is set, "ecdhe" parameter is ignored.

ecdhe 

  1. This setting is only available when support for OpenSSL was built in. It sets
  2. the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
  3. used named curve is prime256v1.

ca-file 

  1. This setting is only available when support for OpenSSL was built in. It
  2. designates a PEM file from which to load CA certificates used to verify
  3. client's certificate.

ca-ignore-err [all|,…]

  1. This setting is only available when support for OpenSSL was built in.
  2. Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
  3. If set to 'all', all errors are ignored. SSL handshake is not aborted if an
  4. error is ignored.

ca-sign-file 

  1. This setting is only available when support for OpenSSL was built in. It
  2. designates a PEM file containing both the CA certificate and the CA private
  3. key used to create and sign server's certificates. This is a mandatory
  4. setting when the dynamic generation of certificates is enabled. See
  5. 'generate-certificates' for details.

ca-sign-pass 

  1. This setting is only available when support for OpenSSL was built in. It is
  2. the CA private key passphrase. This setting is optional and used only when
  3. the dynamic generation of certificates is enabled. See
  4. 'generate-certificates' for details.

ciphers 

  1. This setting is only available when support for OpenSSL was built in. It sets
  2. the string describing the list of cipher algorithms ("cipher suite") that are
  3. negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the
  4. string is defined in "man 1 ciphers" from OpenSSL man pages. For background
  5. information and recommendations see e.g.
  6. (https://wiki.mozilla.org/Security/Server_Side_TLS) and
  7. (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
  8. cipher configuration, please check the "ciphersuites" keyword.

ciphersuites 

  1. This setting is only available when support for OpenSSL was built in and
  2. OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
  3. the list of cipher algorithms ("cipher suite") that are negotiated during the
  4. TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
  5. OpenSSL man pages under the "ciphersuites" section. For cipher configuration
  6. for TLSv1.2 and earlier, please check the "ciphers" keyword.

crl-file 

  1. This setting is only available when support for OpenSSL was built in. It
  2. designates a PEM file from which to load certificate revocation list used
  3. to verify client's certificate.

crt 

  1. This setting is only available when support for OpenSSL was built in. It
  2. designates a PEM file containing both the required certificates and any
  3. associated private keys. This file can be built by concatenating multiple
  4. PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
  5. requires an intermediate certificate, this can also be concatenated into this
  6. file.
  7.  
  8. If the OpenSSL used supports Diffie-Hellman, parameters present in this file
  9. are loaded.
  10.  
  11. If a directory name is used instead of a PEM file, then all files found in
  12. that directory will be loaded in alphabetic order unless their name ends with
  13. '.issuer', '.ocsp' or '.sctl' (reserved extensions). This directive may be
  14. specified multiple times in order to load certificates from multiple files or
  15. directories. The certificates will be presented to clients who provide a
  16. valid TLS Server Name Indication field matching one of their CN or alt
  17. subjects. Wildcards are supported, where a wildcard character '*' is used
  18. instead of the first hostname component (e.g. *.example.org matches
  19. www.example.org but not www.sub.example.org).
  20.  
  21. If no SNI is provided by the client or if the SSL library does not support
  22. TLS extensions, or if the client provides an SNI hostname which does not
  23. match any certificate, then the first loaded certificate will be presented.
  24. This means that when loading certificates from a directory, it is highly
  25. recommended to load the default one first as a file or to ensure that it will
  26. always be the first one in the directory.
  27.  
  28. Note that the same cert may be loaded multiple times without side effects.
  29.  
  30. Some CAs (such as GoDaddy) offer a drop down list of server types that do not
  31. include HAProxy when obtaining a certificate. If this happens be sure to
  32. choose a web server that the CA believes requires an intermediate CA (for
  33. GoDaddy, selection Apache Tomcat will get the correct bundle, but many
  34. others, e.g. nginx, result in a wrong bundle that will not work for some
  35. clients).
  36.  
  37. For each PEM file, haproxy checks for the presence of file at the same path
  38. suffixed by ".ocsp". If such file is found, support for the TLS Certificate
  39. Status Request extension (also known as "OCSP stapling") is automatically
  40. enabled. The content of this file is optional. If not empty, it must contain
  41. a valid OCSP Response in DER format. In order to be valid an OCSP Response
  42. must comply with the following rules: it has to indicate a good status,
  43. it has to be a single response for the certificate of the PEM file, and it
  44. has to be valid at the moment of addition. If these rules are not respected
  45. the OCSP Response is ignored and a warning is emitted. In order to  identify
  46. which certificate an OCSP Response applies to, the issuer's certificate is
  47. necessary. If the issuer's certificate is not found in the PEM file, it will
  48. be loaded from a file at the same path as the PEM file suffixed by ".issuer"
  49. if it exists otherwise it will fail with an error.
  50.  
  51. For each PEM file, haproxy also checks for the presence of file at the same
  52. path suffixed by ".sctl". If such file is found, support for Certificate
  53. Transparency (RFC6962) TLS extension is enabled. The file must contain a
  54. valid Signed Certificate Timestamp List, as described in RFC. File is parsed
  55. to check basic syntax, but no signatures are verified.
  56.  
  57. There are cases where it is desirable to support multiple key types, e.g. RSA
  58. and ECDSA in the cipher suites offered to the clients. This allows clients
  59. that support EC certificates to be able to use EC ciphers, while
  60. simultaneously supporting older, RSA only clients.
  61.  
  62. In order to provide this functionality, multiple PEM files, each with a
  63. different key type, are required. To associate these PEM files into a
  64. "cert bundle" that is recognized by haproxy, they must be named in the
  65. following way: All PEM files that are to be bundled must have the same base
  66. name, with a suffix indicating the key type. Currently, three suffixes are
  67. supported: rsa, dsa and ecdsa. For example, if www.example.com has two PEM
  68. files, an RSA file and an ECDSA file, they must be named: "example.pem.rsa"
  69. and "example.pem.ecdsa". The first part of the filename is arbitrary; only the
  70. suffix matters. To load this bundle into haproxy, specify the base name only:

Example :

  1. bind :8443 ssl crt example.pem
  1. Note that the suffix is not given to haproxy; this tells haproxy to look for
  2. a cert bundle.
  3.  
  4. HAProxy will load all PEM files in the bundle at the same time to try to
  5. support multiple key types. PEM files are combined based on Common Name
  6. (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means
  7. that even if you give haproxy a cert bundle, if there are no shared CN/SAN
  8. entries in the certificates in that bundle, haproxy will not be able to
  9. provide multi-cert support.
  10.  
  11. Assuming bundle in the example above contained the following:
FilenameCNSAN
example.pem.rsawww.example.comrsa.example.com
example.pem.ecdsawww.example.comecdsa.example.com
  1. Users connecting with an SNI of "www.example.com" will be able
  2. to use both RSA and ECDSA cipher suites. Users connecting with an SNI of
  3. "rsa.example.com" will only be able to use RSA cipher suites, and users
  4. connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
  5. suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
  6. no need to bundle certificates. ECDSA certificate will be preferred if client
  7. support it.
  8.  
  9. If a directory name is given as the <cert> argument, haproxy will
  10. automatically search and load bundled files in that directory.
  11.  
  12. OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
  13. bundling. Each certificate can have its own .ocsp and .issuer file. At this
  14. time, sctl is not supported in multi-certificate bundling.

crt-ignore-err 

  1. This setting is only available when support for OpenSSL was built in. Sets a
  2. comma separated list of errorIDs to ignore during verify at depth == 0. If
  3. set to 'all', all errors are ignored. SSL handshake is not aborted if an error
  4. is ignored.

crt-list 

  1. This setting is only available when support for OpenSSL was built in. It
  2. designates a list of PEM file with an optional ssl configuration and a SNI
  3. filter per certificate, with the following format for each line :
  4.  
  5.       <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
  6.  
  7. sslbindconf support "npn", "alpn", "verify", "ca-file", "no-ca-names",
  8. crl-file", "ecdhe", "curves", "ciphers" configuration. With BoringSSL
  9. and Openssl >= 1.1.1 "ssl-min-ver" and "ssl-max-ver" are also supported.
  10. It override the configuration set in bind line for the certificate.
  11.  
  12. Wildcards are supported in the SNI filter. Negative filter are also supported,
  13. only useful in combination with a wildcard filter to exclude a particular SNI.
  14. The certificates will be presented to clients who provide a valid TLS Server
  15. Name Indication field matching one of the SNI filters. If no SNI filter is
  16. specified, the CN and alt subjects are used. This directive may be specified
  17. multiple times. See the "crt" option for more information. The default
  18. certificate is still needed to meet OpenSSL expectations. If it is not used,
  19. the 'strict-sni' option may be used.
  20.  
  21. Multi-cert bundling (see "crt") is supported with crt-list, as long as only
  22. the base name is given in the crt-list. SNI filter will do the same work on
  23. all bundled certificates. With BoringSSL and Openssl >= 1.1.1 multi-cert is
  24. natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
  25. be declared in a row, and set different ssl and filter parameter.
  26.  
  27. crt-list file example:
  28.       cert1.pem
  29.       cert2.pem [alpn h2,http/1.1]
  30.       certW.pem                   *.domain.tld !secure.domain.tld
  31.       certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld

defer-accept

  1. Is an optional keyword which is supported only on certain Linux kernels. It
  2. states that a connection will only be accepted once some data arrive on it,
  3. or at worst after the first retransmit. This should be used only on protocols
  4. for which the client talks first (e.g. HTTP). It can slightly improve
  5. performance by ensuring that most of the request is already available when
  6. the connection is accepted. On the other hand, it will not be able to detect
  7. connections which don't talk. It is important to note that this option is
  8. broken in all kernels up to 2.6.31, as the connection is never accepted until
  9. the client talks. This can cause issues with front firewalls which would see
  10. an established connection while the proxy will only see it in SYN_RECV. This
  11. option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.

expose-fd listeners

  1. This option is only usable with the stats socket. It gives your stats socket
  2. the capability to pass listeners FD to another HAProxy process.
  3. During a reload with the master-worker mode, the process is automatically
  4. reexecuted adding -x and one of the stats socket with this option.
  5. See also "-x" in the management guide.

force-sslv3

  1. This option enforces use of SSLv3 only on SSL connections instantiated from
  2. this listener. SSLv3 is generally less expensive than the TLS counterparts
  3. for high connection rates. This option is also available on global statement
  4. "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".

force-tlsv10

  1. This option enforces use of TLSv1.0 only on SSL connections instantiated from
  2. this listener. This option is also available on global statement
  3. "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".

force-tlsv11

  1. This option enforces use of TLSv1.1 only on SSL connections instantiated from
  2. this listener. This option is also available on global statement
  3. "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".

force-tlsv12

  1. This option enforces use of TLSv1.2 only on SSL connections instantiated from
  2. this listener. This option is also available on global statement
  3. "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".

force-tlsv13

  1. This option enforces use of TLSv1.3 only on SSL connections instantiated from
  2. this listener. This option is also available on global statement
  3. "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".

generate-certificates

  1. This setting is only available when support for OpenSSL was built in. It
  2. enables the dynamic SSL certificates generation. A CA certificate and its
  3. private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
  4. a transparent forward proxy, SSL requests generate errors because of a common
  5. name mismatch on the certificate presented to the client. With this option
  6. enabled, HAProxy will try to forge a certificate using the SNI hostname
  7. indicated by the client. This is done only if no certificate matches the SNI
  8. hostname (see 'crt-list'). If an error occurs, the default certificate is
  9. used, else the 'strict-sni' option is set.
  10. It can also be used when HAProxy is configured as a reverse proxy to ease the
  11. deployment of an architecture with many backends.
  12.  
  13. Creating a SSL certificate is an expensive operation, so a LRU cache is used
  14. to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
  15. increases the HAProxy's memory footprint to reduce latency when the same
  16. certificate is used many times.

gid 

  1. Sets the group of the UNIX sockets to the designated system gid. It can also
  2. be set by default in the global section's "unix-bind" statement. Note that
  3. some platforms simply ignore this. This setting is equivalent to the "group"
  4. setting except that the group ID is used instead of its name. This setting is
  5. ignored by non UNIX sockets.

group 

  1. Sets the group of the UNIX sockets to the designated system group. It can
  2. also be set by default in the global section's "unix-bind" statement. Note
  3. that some platforms simply ignore this. This setting is equivalent to the
  4. "gid" setting except that the group name is used instead of its gid. This
  5. setting is ignored by non UNIX sockets.

id 

  1. Fixes the socket ID. By default, socket IDs are automatically assigned, but
  2. sometimes it is more convenient to fix them to ease monitoring. This value
  3. must be strictly positive and unique within the listener/frontend. This
  4. option can only be used when defining only a single socket.

interface 

  1. Restricts the socket to a specific interface. When specified, only packets
  2. received from that particular interface are processed by the socket. This is
  3. currently only supported on Linux. The interface must be a primary system
  4. interface, not an aliased interface. It is also possible to bind multiple
  5. frontends to the same address if they are bound to different interfaces. Note
  6. that binding to a network interface requires root privileges. This parameter
  7. is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic
  8. uses the same interface as inbound traffic, and its associated routing table,
  9. even if there are explicit routes through different interfaces configured.
  10. This can prove useful to address asymmetric routing issues when the same
  11. client IP addresses need to be able to reach frontends hosted on different
  12. interfaces.

level 

  1. This setting is used with the stats sockets only to restrict the nature of
  2. the commands that can be issued on the socket. It is ignored by other
  3. sockets. <level> can be one of :
  4. - "user" is the least privileged level; only non-sensitive stats can be
  5.   read, and no change is allowed. It would make sense on systems where it
  6.   is not easy to restrict access to the socket.
  7. - "operator" is the default level and fits most common uses. All data can
  8.   be read, and only non-sensitive changes are permitted (e.g. clear max
  9.   counters).
  10. - "admin" should be used with care, as everything is permitted (e.g. clear
  11.   all counters).

severity-output 

  1. This setting is used with the stats sockets only to configure severity
  2. level output prepended to informational feedback messages. Severity
  3. level of messages can range between 0 and 7, conforming to syslog
  4. rfc5424. Valid and successful socket commands requesting data
  5. (i.e. "show map", "get acl foo" etc.) will never have a severity level
  6. prepended. It is ignored by other sockets. <format> can be one of :
  7. - "none" (default) no severity level is prepended to feedback messages.
  8. - "number" severity level is prepended as a number.
  9. - "string" severity level is prepended as a string following the
  10.   rfc5424 convention.

maxconn 

  1. Limits the sockets to this number of concurrent connections. Extraneous
  2. connections will remain in the system's backlog until a connection is
  3. released. If unspecified, the limit will be the same as the frontend's
  4. maxconn. Note that in case of port ranges or multiple addresses, the same
  5. value will be applied to each socket. This setting enables different
  6. limitations on expensive sockets, for instance SSL entries which may easily
  7. eat all memory.

mode 

  1. Sets the octal mode used to define access permissions on the UNIX socket. It
  2. can also be set by default in the global section's "unix-bind" statement.
  3. Note that some platforms simply ignore this. This setting is ignored by non
  4. UNIX sockets.

mss 

  1. Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
  2. connections. This can be used to force a lower MSS for certain specific
  3. ports, for instance for connections passing through a VPN. Note that this
  4. relies on a kernel feature which is theoretically supported under Linux but
  5. was buggy in all versions prior to 2.6.28. It may or may not work on other
  6. operating systems. It may also not change the advertised value but change the
  7. effective size of outgoing segments. The commonly advertised value for TCPv4
  8. over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
  9. positive, it will be used as the advertised MSS. If it is negative, it will
  10. indicate by how much to reduce the incoming connection's advertised MSS for
  11. outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.

name 

  1. Sets an optional name for these sockets, which will be reported on the stats
  2. page.

namespace 

  1. On Linux, it is possible to specify which network namespace a socket will
  2. belong to. This directive makes it possible to explicitly bind a listener to
  3. a namespace different from the default one. Please refer to your operating
  4. system's documentation to find more details about network namespaces.

nice 

  1. Sets the 'niceness' of connections initiated from the socket. Value must be
  2. in the range -1024..1024 inclusive, and defaults to zero. Positive values
  3. means that such connections are more friendly to others and easily offer
  4. their place in the scheduler. On the opposite, negative values mean that
  5. connections want to run with a higher priority than others. The difference
  6. only happens under high loads when the system is close to saturation.
  7. Negative values are appropriate for low-latency or administration services,
  8. and high values are generally recommended for CPU intensive tasks such as SSL
  9. processing or bulk transfers which are less sensible to latency. For example,
  10. it may make sense to use a positive value for an SMTP socket and a negative
  11. one for an RDP socket.

no-ca-names

  1. This setting is only available when support for OpenSSL was built in. It
  2. prevents from send CA names in server hello message when ca-file is used.

no-sslv3

  1. This setting is only available when support for OpenSSL was built in. It
  2. disables support for SSLv3 on any sockets instantiated from the listener when
  3. SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
  4. be enabled using any configuration option. This option is also available on
  5. global statement "ssl-default-bind-options". Use "ssl-min-ver" and
  6. "ssl-max-ver" instead.

no-tls-tickets

  1. This setting is only available when support for OpenSSL was built in. It
  2. disables the stateless session resumption (RFC 5077 TLS Ticket
  3. extension) and force to use stateful session resumption. Stateless
  4. session resumption is more expensive in CPU usage. This option is also
  5. available on global statement "ssl-default-bind-options".
  6. The TLS ticket mechanism is only used up to TLS 1.2.
  7. Forward Secrecy is compromised with TLS tickets, unless ticket keys
  8. are periodically rotated (via reload or by using "tls-ticket-keys").

no-tlsv10

  1. This setting is only available when support for OpenSSL was built in. It
  2. disables support for TLSv1.0 on any sockets instantiated from the listener
  3. when SSL is supported. Note that SSLv2 is forced disabled in the code and
  4. cannot be enabled using any configuration option. This option is also
  5. available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
  6. and "ssl-max-ver" instead.

no-tlsv11

  1. This setting is only available when support for OpenSSL was built in. It
  2. disables support for TLSv1.1 on any sockets instantiated from the listener
  3. when SSL is supported. Note that SSLv2 is forced disabled in the code and
  4. cannot be enabled using any configuration option. This option is also
  5. available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
  6. and "ssl-max-ver" instead.

no-tlsv12

  1. This setting is only available when support for OpenSSL was built in. It
  2. disables support for TLSv1.2 on any sockets instantiated from the listener
  3. when SSL is supported. Note that SSLv2 is forced disabled in the code and
  4. cannot be enabled using any configuration option. This option is also
  5. available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
  6. and "ssl-max-ver" instead.

no-tlsv13

  1. This setting is only available when support for OpenSSL was built in. It
  2. disables support for TLSv1.3 on any sockets instantiated from the listener
  3. when SSL is supported. Note that SSLv2 is forced disabled in the code and
  4. cannot be enabled using any configuration option. This option is also
  5. available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
  6. and "ssl-max-ver" instead.

npn 

  1. This enables the NPN TLS extension and advertises the specified protocol list
  2. as supported on top of NPN. The protocol list consists in a comma-delimited
  3. list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
  4. This requires that the SSL library is built with support for TLS extensions
  5. enabled (check with haproxy -vv). Note that the NPN extension has been
  6. replaced with the ALPN extension (see the "alpn" keyword), though this one is
  7. only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
  8. version of OpenSSL, NPN might still be used as most clients still support it
  9. at the time of writing this. It is possible to enable both NPN and ALPN
  10. though it probably doesn't make any sense out of testing.

prefer-client-ciphers

  1. Use the client's preference when selecting the cipher suite, by default
  2. the server's preference is enforced. This option is also available on
  3. global statement "ssl-default-bind-options".
  4. Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
  5. (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
  6. the client cipher list.

process [/]

  1. This restricts the list of processes or threads on which this listener is
  2. allowed to run. It does not enforce any process but eliminates those which do
  3. not match. If the frontend uses a "bind-process" setting, the intersection
  4. between the two is applied. If in the end the listener is not allowed to run
  5. on any remaining process, a warning is emitted, and the listener will either
  6. run on the first process of the listener if a single process was specified,
  7. or on all of its processes if multiple processes were specified. If a thread
  8. set is specified, it limits the threads allowed to process incoming
  9. connections for this listener, for the the process set. If multiple processes
  10. and threads are configured, a warning is emitted, as it either results from a
  11. configuration error or a misunderstanding of these models. For the unlikely
  12. case where several ranges are needed, this directive may be repeated.
  13. <process-set> and <thread-set> must use the format
  14.  
  15.     all | odd | even | number[-[number]]
  16.  
  17. Ranges can be partially defined. The higher bound can be omitted. In such
  18. case, it is replaced by the corresponding maximum value. The main purpose of
  19. this directive is to be used with the stats sockets and have one different
  20. socket per process. The second purpose is to have multiple bind lines sharing
  21. the same IP:port but not the same process in a listener, so that the system
  22. can distribute the incoming connections into multiple queues and allow a
  23. smoother inter-process load balancing. Currently Linux 3.9 and above is known
  24. for supporting this. See also "bind-process" and "nbproc".

proto 

  1. Forces the multiplexer's protocol to use for the incoming connections. It
  2. must be compatible with the mode of the frontend (TCP or HTTP). It must also
  3. be usable on the frontend side. The list of available protocols is reported
  4. in haproxy -vv.
  5. Idea behind this optipon is to bypass the selection of the best multiplexer's
  6. protocol for all connections instantiated from this listening socket. For
  7. instance, it is possible to force the http/2 on clear TCP by specifying "proto
  8. h2" on the bind line.

ssl

  1. This setting is only available when support for OpenSSL was built in. It
  2. enables SSL deciphering on connections instantiated from this listener. A
  3. certificate is necessary (see "crt" above). All contents in the buffers will
  4. appear in clear text, so that ACLs and HTTP processing will only have access
  5. to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
  6. to enable it.

ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

  1. This option enforces use of <version> or lower on SSL connections instantiated
  2. from this listener. This option is also available on global statement
  3. "ssl-default-bind-options". See also "ssl-min-ver".

ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]

  1. This option enforces use of <version> or upper on SSL connections instantiated
  2. from this listener. This option is also available on global statement
  3. "ssl-default-bind-options". See also "ssl-max-ver".

strict-sni

  1. This setting is only available when support for OpenSSL was built in. The
  2. SSL/TLS negotiation is allow only if the client provided an SNI which match
  3. a certificate. The default certificate is not used.
  4. See the "crt" option for more information.

tcp-ut 

  1. Sets the TCP User Timeout for all incoming connections instantiated from this
  2. listening socket. This option is available on Linux since version 2.6.37. It
  3. allows haproxy to configure a timeout for sockets which contain data not
  4. receiving an acknowledgment for the configured delay. This is especially
  5. useful on long-lived connections experiencing long idle periods such as
  6. remote terminals or database connection pools, where the client and server
  7. timeouts must remain high to allow a long period of idle, but where it is
  8. important to detect that the client has disappeared in order to release all
  9. resources associated with its connection (and the server's session). The
  10. argument is a delay expressed in milliseconds by default. This only works
  11. for regular TCP connections, and is ignored for other protocols.

tfo

  1. Is an optional keyword which is supported only on Linux kernels >= 3.7. It
  2. enables TCP Fast Open on the listening socket, which means that clients which
  3. support this feature will be able to send a request and receive a response
  4. during the 3-way handshake starting from second connection, thus saving one
  5. round-trip after the first connection. This only makes sense with protocols
  6. that use high connection rates and where each round trip matters. This can
  7. possibly cause issues with many firewalls which do not accept data on SYN
  8. packets, so this option should only be enabled once well tested. This option
  9. is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
  10. need to build HAProxy with USE_TFO=1 if your libc doesn't define
  11. TCP_FASTOPEN.

tls-ticket-keys 

  1. Sets the TLS ticket keys file to load the keys from. The keys need to be 48
  2. or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64
  3. with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo).
  4. The first key determines the key length used for next keys: you can't mix
  5. aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO
  6. build option (default 3) and at least as many keys need to be present in
  7. the file. Last TLS_TICKETS_NO keys will be used for decryption and the
  8. penultimate one for encryption. This enables easy key rotation by just
  9. appending new key to the file and reloading the process.  Keys must be
  10. periodically rotated (ex. every 12h) or Perfect Forward Secrecy is
  11. compromised. It is also a good idea to keep the keys off any permanent
  12. storage such as hard drives (hint: use tmpfs and don't swap those files).
  13. Lifetime hint can be changed using tune.ssl.timeout.

transparent

  1. Is an optional keyword which is supported only on certain Linux kernels. It
  2. indicates that the addresses will be bound even if they do not belong to the
  3. local machine, and that packets targeting any of these addresses will be
  4. intercepted just as if the addresses were locally configured. This normally
  5. requires that IP forwarding is enabled. Caution! do not use this with the
  6. default address '*', as it would redirect any traffic for the specified port.
  7. This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
  8. This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
  9. kernel version. Some distribution kernels include backports of the feature,
  10. so check for support with your vendor.

v4v6

  1. Is an optional keyword which is supported only on most recent systems
  2. including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
  3. and IPv6 when it uses the default address. Doing so is sometimes necessary
  4. on systems which bind to IPv6 only by default. It has no effect on non-IPv6
  5. sockets, and is overridden by the "v6only" option.

v6only

  1. Is an optional keyword which is supported only on most recent systems
  2. including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
  3. when it uses the default address. Doing so is sometimes preferred to doing it
  4. system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
  5. has precedence over the "v4v6" option.

uid 

  1. Sets the owner of the UNIX sockets to the designated system uid. It can also
  2. be set by default in the global section's "unix-bind" statement. Note that
  3. some platforms simply ignore this. This setting is equivalent to the "user"
  4. setting except that the user numeric ID is used instead of its name. This
  5. setting is ignored by non UNIX sockets.

user 

  1. Sets the owner of the UNIX sockets to the designated system user. It can also
  2. be set by default in the global section's "unix-bind" statement. Note that
  3. some platforms simply ignore this. This setting is equivalent to the "uid"
  4. setting except that the user name is used instead of its uid. This setting is
  5. ignored by non UNIX sockets.

verify [none|optional|required]

  1. This setting is only available when support for OpenSSL was built in. If set
  2. to 'none', client certificate is not requested. This is the default. In other
  3. cases, a client certificate is requested. If the client does not provide a
  4. certificate after the request and if 'verify' is set to 'required', then the
  5. handshake is aborted, while it would have succeeded if set to 'optional'. The
  6. certificate provided by the client is always verified using CAs from
  7. 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
  8. is aborted, regardless of the 'verify' option, unless the error code exactly
  9. matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.