5.1. Bind options



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

The currently supported settings are the following ones.

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

alpn <protocols>
This enables the TLS ALPN extension and advertises the specified protocol list as supported on top of ALPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). This requires that the SSL library is build with support for TLS extensions enabled (check with haproxy -vv). The ALPN extension replaces the initial NPN extension.

backlog <backlog>
Sets the socket’s backlog to this value. If unspecified, the frontend’s backlog is used instead, which generally defaults to the maxconn value.

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

ca-file <cafile>
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load CA certificates used to verify client’s certificate.

ca-ignore-err [all|<errorID>,…]
This setting is only available when support for OpenSSL was built in. Sets a comma separated list of errorIDs to ignore during verify at depth > 0. If set to ‘all’, all errors are ignored. SSL handshake is not aborted if an error is ignored.

ciphers <ciphers>
This setting is only available when support for OpenSSL was built in. It sets the string describing the list of cipher algorithms (“cipher suite”) that are negotiated during the SSL/TLS handshake. The format of the string is defined in “man 1 ciphers” from OpenSSL man pages, and can be for instance a string such as “AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH” (without quotes).

crl-file <crlfile>
This setting is only available when support for OpenSSL was built in. It designates a PEM file from which to load certificate revocation list used to verify client’s certificate.

crt <cert>
This setting is only available when support for OpenSSL was built in. 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.

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 unless their name ends with ‘.issuer’ or ‘.ocsp’ (reserved extensions). 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 (eg: *.example.org matches www.example.org but not www.sub.example.org).

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.

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 webserver 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.

crt-ignore-err <errors>
This setting is only available when support for OpenSSL was built in. Sets a comma separated list of errorIDs to ignore during verify at depth == 0. If set to ‘all’, all errors are ignored. SSL handshake is not aborted if an error is ignored.

crt-list <file>
This setting is only available when support for OpenSSL was built in. It designates a list of PEM file with an optional list of SNI filter per certificate, with the following format for each line :

<crtfile> [[!]<snifilter> …]

Wildcards are supported in the SNI filter. Negative filter are also supported, only useful in combination with a wildcard filter to exclude a particular SNI. The certificates will be presented to clients who provide a valid TLS Server Name Indication field matching one of the SNI filters. If no SNI filter is specified, the CN and alt subjects are used. This directive may be specified multiple times. See the “crt” option for more information. The default certificate is still needed to meet OpenSSL expectations. If it is not used, the ‘strict-sni’ option may be used.

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

force-sslv3
This option enforces use of SSLv3 only on SSL connections instantiated from this listener. SSLv3 is generally less expensive than the TLS counterparts for high connection rates. See also “force-tls*”, “no-sslv3”, and “no-tls*”.

force-tlsv10
This option enforces use of TLSv1.0 only on SSL connections instantiated from this listener. See also “force-tls*”, “no-sslv3”, and “no-tls*”.

force-tlsv11
This option enforces use of TLSv1.1 only on SSL connections instantiated from this listener. See also “force-tls*”, “no-sslv3”, and “no-tls*”.

force-tlsv12
This option enforces use of TLSv1.2 only on SSL connections instantiated from this listener. See also “force-tls*”, “no-sslv3”, and “no-tls*”.

gid <gid>
Sets the group of the UNIX sockets to the designated system gid. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “group” setting except that the group ID is used instead of its name. This setting is ignored by non UNIX sockets.

group <group>
Sets the group of the UNIX sockets to the designated system group. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “gid” setting except that the group name is used instead of its gid. This setting is ignored by non UNIX sockets.

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

interface <interface>
Restricts the socket to a specific interface. When specified, only packets received from that particular interface are processed by the socket. This is currently only supported on Linux. The interface must be a primary system interface, not an aliased interface. It is also possible to bind multiple frontends to the same address if they are bound to different interfaces. Note that binding to a network interface requires root privileges. This parameter is only compatible with TCPv4/TCPv6 sockets.

level <level>
This setting is used with the stats sockets only to restrict the nature of the commands that can be issued on the socket. It is ignored by other sockets.
<level> can be one of :

  • user” is the least privileged level ; only non-sensitive stats can be read, and no change is allowed. It would make sense on systems where it is not easy to restrict access to the socket.
  • operator” is the default level and fits most common uses. All data can be read, and only non-sensitive changes are permitted (eg: clear max counters).
  • admin” should be used with care, as everything is permitted (eg: clear all counters).

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

mode <mode>
Sets the octal mode used to define access permissions on the UNIX socket. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is ignored by non UNIX sockets.

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

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

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

no-sslv3
This setting is only available when support for OpenSSL was built in. It disables support for SSLv3 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. See also “force-tls*”, and “force-sslv3”.

no-tls-tickets
This setting is only available when support for OpenSSL was built in. It disables the stateless session resumption (RFC 5077 TLS Ticket extension) and force to use stateful session resumption. Stateless session resumption is more expensive in CPU usage.

no-tlsv10
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.0 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. See also “force-tls*”, and “force-sslv3”.

no-tlsv11
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.1 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. See also “force-tls*”, and “force-sslv3”.

no-tlsv12
This setting is only available when support for OpenSSL was built in. It disables support for TLSv1.2 on any sockets instantiated from the listener when SSL is supported. Note that SSLv2 is forced disabled in the code and cannot be enabled using any configuration option. See also “force-tls*”, and “force-sslv3”.

npn <protocols>
This enables the NPN TLS extension and advertises the specified protocol list as supported on top of NPN. The protocol list consists in a comma-delimited list of protocol names, for instance: “http/1.1,http/1.0” (without quotes). This requires that the SSL library is build 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).

process [ all | odd | even | <number 1-64>[-<number 1-64>] ]
This restricts the list of processes on which this listener is allowed to run. It does not enforce any process but eliminates those which do not match.
If the frontend uses a “bind-process” setting, the intersection between the two is applied.
If in the end the listener is not allowed to run on any remaining process, a warning is emitted, and the listener will either run on the first process of the listener if a single process was specified, or on all of its processes if multiple processes were specified. For the unlikely case where several ranges are needed, this directive may be repeated.
The main purpose of this directive is to be used with the stats sockets and have one different socket per process.
The second purpose is to have multiple bind lines sharing the same IP:port but not the same process in a listener, so that the system can distribute the incoming connections into multiple queues and allow a smoother inter-process load balancing.
Currently Linux 3.9 and above is known for supporting this. See also “bind-process” and “nbproc”.

ssl
This setting is only available when support for OpenSSL was built in. It enables SSL deciphering on connections instantiated from this listener. A certificate is necessary (see “crt” above). All contents in the buffers will appear in clear text, so that ACLs and HTTP processing will only have access to deciphered contents.

strict-sni
This setting is only available when support for OpenSSL was built in. The SSL/TLS negotiation is allow only if the client provided an SNI which match a certificate. The default certificate is not used. See the “crt” option for more information.

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

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

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

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

uid <uid>
Sets the owner of the UNIX sockets to the designated system uid. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “user” setting except that the user numeric ID is used instead of its name. This setting is ignored by non UNIX sockets.

user <user>
Sets the owner of the UNIX sockets to the designated system user. It can also be set by default in the global section’s “unix-bind” statement. Note that some platforms simply ignore this. This setting is equivalent to the “uid” setting except that the user name is used instead of its uid. This setting is ignored by non UNIX sockets.

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

Share Button

3 thoughts on “5.1. Bind options

  1. Pingback: 3.1. Process management and security | Haproxy.doc

  2. Pingback: 5. Bind and Server options | Haproxy.doc

Leave a Reply