5. Bind and Server options
--------------------------
The "bind", "server" and "default-server" keywords support a number of settings
depending on some build options and on the system HAProxy was built on. These
settings generally each consist in one word sometimes followed by a value,
written on the same line as the "bind" or "server" line. All these options are
described in this section.
5.1. Bind options
-----------------
The "bind" keyword supports a certain number of settings which are all passed
as arguments on the same line. The order in which those arguments appear makes
no importance, provided that they appear after the bind address. All of these
parameters are optional. Some of them consist in a single words (booleans),
while other ones expect a value after them. In this case, the value must be
provided immediately after the setting name.
The currently supported settings are the following ones.
accept-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 in alphabetic order 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 or to ensure that it will
always be the first one in the directory.
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. This option is also available on global statement
"ssl-default-bind-options". See also "no-tlsv*" and "no-sslv3".
force-tlsv10
This option enforces use of TLSv1.0 only on SSL connections instantiated from
this listener. This option is also available on global statement
"ssl-default-bind-options". See also "no-tlsv*" and "no-sslv3".
force-tlsv11
This option enforces use of TLSv1.1 only on SSL connections instantiated from
this listener. This option is also available on global statement
"ssl-default-bind-options". See also "no-tlsv*", and "no-sslv3".
force-tlsv12
This option enforces use of TLSv1.2 only on SSL connections instantiated from
this listener. This option is also available on global statement
"ssl-default-bind-options". See also "no-tlsv*", and "no-sslv3".
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. This option is also available on
global statement "ssl-default-bind-options". 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. This option is also
available on global statement "ssl-default-bind-options".
no-tlsv10
This setting is only available when support for OpenSSL was built in. It
disables support for TLSv1.0 on any sockets instantiated from the listener
when SSL is supported. Note that SSLv2 is forced disabled in the code and
cannot be enabled using any configuration option. This option is also
available on global statement "ssl-default-bind-options". See also
"force-tlsv*", 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. This option is also
available on global statement "ssl-default-bind-options". See also
"force-tlsv*", 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. This option is also
available on global statement "ssl-default-bind-options". See also
"force-tlsv*", 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'.
5.2. Server and default-server options
------------------------------------
The "server" and "default-server" keywords support a certain number of settings
which are all passed as arguments on the server line. The order in which those
arguments appear does not count, and they are all optional. Some of those
settings are single words (booleans) while others expect one or several values
after them. In this case, the values must immediately follow the setting name.
Except default-server, all those settings must be specified after the server's
address if they are used:
server <name> <address>[:port] [settings ...]
default-server [settings ...]
The currently supported settings are the following ones.
addr <ipv4|ipv6>
Using the "addr" parameter, it becomes possible to use a different IP address
to send health-checks. 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.
Supported in default-server: No
agent-check
Enable an auxiliary agent check which is run independently of a regular
health check. An agent health check is performed by making a TCP connection
to the port set by the "agent-port" parameter and reading an ASCII string.
The string is made of a series of words delimited by spaces, tabs or commas
in any order, optionally terminated by '\r' and/or '\n', each consisting of :
- An ASCII representation of a positive integer percentage, e.g. "75%".
Values in this format will set the weight proportional to the initial
weight of a server as configured when haproxy starts. Note that a zero
weight is reported on the stats page as "DRAIN" since it has the same
effect on the server (it's removed from the LB farm).
- The word "ready". This will turn the server's administrative state to the
READY mode, thus cancelling any DRAIN or MAINT state
- The word "drain". This will turn the server's administrative state to the
DRAIN mode, thus it will not accept any new connections other than those
that are accepted via persistence.
- The word "maint". This will turn the server's administrative state to the
MAINT mode, thus it will not accept any new connections at all, and health
checks will be stopped.
- The words "down", "failed", or "stopped", optionally followed by a
description string after a sharp ('#'). All of these mark the server's
operating state as DOWN, but since the word itself is reported on the stats
page, the difference allows an administrator to know if the situation was
expected or not : the service may intentionally be stopped, may appear up
but fail some validity tests, or may be seen as down (eg: missing process,
or port not responding).
- The word "up" sets back the server's operating state as UP if health checks
also report that the service is accessible.
Parameters which are not advertised by the agent are not changed. For
example, an agent might be designed to monitor CPU usage and only report a
relative weight and never interact with the operating status. Similarly, an
agent could be designed as an end-user interface with 3 radio buttons
allowing an administrator to change only the administrative state. However,
it is important to consider that only the agent may revert its own actions,
so if a server is set to DRAIN mode or to DOWN state using the agent, the
agent must implement the other equivalent actions to bring the service into
operations again.
Failure to connect to the agent is not considered an error as connectivity
is tested by the regular health check which is enabled by the "check"
parameter. Warning though, it is not a good idea to stop an agent after it
reports "down", since only an agent reporting "up" will be able to turn the
server up again. Note that the CLI on the Unix stats socket is also able to
force an agent's result in order to workaround a bogus agent if needed.
Requires the "agent-port" parameter to be set. See also the "agent-inter"
parameter.
Supported in default-server: No
agent-inter <delay>
The "agent-inter" parameter sets the interval between two agent checks
to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
Just as with every other time-based parameter, it may be entered in any
other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
parameter also serves as a timeout for agent checks "timeout check" is
not set. In order to reduce "resonance" effects when multiple servers are
hosted on the same hardware, the agent and health checks of all servers
are started with a small time offset between them. It is also possible to
add some random noise in the agent and health checks interval using the
global "spread-checks" keyword. This makes sense for instance when a lot
of backends use the same servers.
See also the "agent-check" and "agent-port" parameters.
Supported in default-server: Yes
agent-port <port>
The "agent-port" parameter sets the TCP port used for agent checks.
See also the "agent-check" and "agent-inter" parameters.
Supported in default-server: Yes
backup
When "backup" is present on a server line, the server is only used in load
balancing when all other non-backup servers are unavailable. Requests coming
with a persistence cookie referencing the server will always be served
though. By default, only the first operational backup server is used, unless
the "allbackups" option is set in the backend. See also the "allbackups"
option.
Supported in default-server: No
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
server's certificate.
Supported in default-server: No
check
This option enables health checks on the server. By default, a server is
always considered available. If "check" is set, the server is available when
accepting periodic TCP connections, to ensure that it is really able to serve
requests. The default address and port to send the tests to are those of the
server, and the default source is the same as the one defined in the
backend. It is possible to change the address using the "addr" parameter, the
port using the "port" parameter, the source address using the "source"
address, and the interval and timers using the "inter", "rise" and "fall"
parameters. The request method is define in the backend using the "httpchk",
"smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
refer to those options and parameters for more information.
Supported in default-server: No
check-send-proxy
This option forces emission of a PROXY protocol line with outgoing health
checks, regardless of whether the server uses send-proxy or not for the
normal traffic. By default, the PROXY protocol is enabled for health checks
if it is already enabled for normal traffic and if no "port" nor "addr"
directive is present. However, if such a directive is present, the
"check-send-proxy" option needs to be used to force the use of the
protocol. See also the "send-proxy" option for more information.
Supported in default-server: No
check-ssl
This option forces encryption of all health checks over SSL, regardless of
whether the server uses SSL or not for the normal traffic. This is generally
used when an explicit "port" or "addr" directive is specified and SSL health
checks are not inherited. It is important to understand that this option
inserts an SSL transport layer below the checks, so that a simple TCP connect
check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
common use is to send HTTPS checks by combining "httpchk" with SSL checks.
All SSL settings are common to health checks and traffic (eg: ciphers).
See the "ssl" option for more information.
Supported in default-server: No
ciphers <ciphers>
This option sets the string describing the list of cipher algorithms that is
is negotiated during the SSL/TLS handshake with the server. The format of the
string is defined in "man 1 ciphers". When SSL is used to communicate with
servers on the local network, it is common to see a weaker set of algorithms
than what is used over the internet. Doing so reduces CPU usage on both the
server and haproxy while still keeping it compatible with deployed software.
Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
is needed and just connectivity, using DES can be appropriate.
Supported in default-server: No
cookie <value>
The "cookie" parameter sets the cookie value assigned to the server to
<value>. This value will be checked in incoming requests, and the first
operational server possessing the same value will be selected. In return, in
cookie insertion or rewrite modes, this value will be assigned to the cookie
sent to the client. There is nothing wrong in having several servers sharing
the same cookie value, and it is in fact somewhat common between normal and
backup servers. See also the "cookie" keyword in backend section.
Supported in default-server: No
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 server's certificate.
Supported in default-server: No
crt <cert>
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.
Supported in default-server: No
disabled
The "disabled" keyword starts the server in the "disabled" state. That means
that it is marked down in maintenance mode, and no connection other than the
ones allowed by persist mode will reach it. It is very well suited to setup
new servers, because normal traffic will never reach them, while it is still
possible to test the service by making use of the force-persist mechanism.
Supported in default-server: No
error-limit <count>
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.
Supported in default-server: Yes
See also the "check", "error-limit" and "on-error".
fall <count>
The "fall" parameter states that a server will be considered as dead after
<count> consecutive unsuccessful health checks. This value defaults to 3 if
unspecified. See also the "check", "inter" and "rise" parameters.
Supported in default-server: Yes
force-sslv3
This option enforces use of SSLv3 only when SSL is used to communicate with
the server. SSLv3 is generally less expensive than the TLS counterparts for
high connection rates. This option is also available on global statement
"ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Supported in default-server: No
force-tlsv10
This option enforces use of TLSv1.0 only when SSL is used to communicate with
the server. This option is also available on global statement
"ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Supported in default-server: No
force-tlsv11
This option enforces use of TLSv1.1 only when SSL is used to communicate with
the server. This option is also available on global statement
"ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Supported in default-server: No
force-tlsv12
This option enforces use of TLSv1.2 only when SSL is used to communicate with
the server. This option is also available on global statement
"ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Supported in default-server: No
id <value>
Set a persistent ID for the server. This ID must be positive 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.
Supported in default-server: No
inter <delay>
fastinter <delay>
downinter <delay>
The "inter" parameter sets the interval between two consecutive health checks
to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
It is also possible to use "fastinter" and "downinter" to optimize delays
between checks depending on the server state :
Server state | Interval used
---------------------------------+-----------------------------------------
UP 100% (non-transitional) | "inter"
---------------------------------+-----------------------------------------
Transitionally UP (going down), |
Transitionally DOWN (going up), | "fastinter" if set, "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.
Supported in default-server: Yes
maxconn <maxconn>
The "maxconn" parameter specifies the maximal number of concurrent
connections that will be sent to this server. If the number of incoming
concurrent requests goes higher than this value, they will be queued, waiting
for a connection 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.
Supported in default-server: Yes
maxqueue <maxqueue>
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. The
default value is "0" which means the queue is unlimited. See also the
"maxconn" and "minconn" parameters.
Supported in default-server: Yes
minconn <minconn>
When the "minconn" parameter is set, the maxconn limit becomes a dynamic
limit following the backend's load. The server will always accept at least
<minconn> connections, never more than <maxconn>, and the limit will be on
the ramp between both values when the backend has less than <fullconn>
concurrent connections. This makes it possible to limit the load on the
server during normal loads, but push it further for important loads without
overloading the server during exceptional loads. See also the "maxconn"
and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Supported in default-server: Yes
no-sslv3
This option disables support for SSLv3 when SSL is used to communicate with
the server. Note that SSLv2 is disabled in the code and cannot be enabled
using any configuration option. See also "force-sslv3", "force-tlsv*".
Supported in default-server: No
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 for servers. This option
is also available on global statement "ssl-default-server-options".
Supported in default-server: No
no-tlsv10
This option disables support for TLSv1.0 when SSL is used to communicate with
the server. Note that SSLv2 is disabled in the code and cannot be enabled
using any configuration option. TLSv1 is more expensive than SSLv3 so it
often makes sense to disable it when communicating with local servers. This
option is also available on global statement "ssl-default-server-options".
See also "force-sslv3", "force-tlsv*".
Supported in default-server: No
no-tlsv11
This option disables support for TLSv1.1 when SSL is used to communicate with
the server. Note that SSLv2 is disabled in the code and cannot be enabled
using any configuration option. TLSv1 is more expensive than SSLv3 so it
often makes sense to disable it when communicating with local servers. This
option is also available on global statement "ssl-default-server-options".
See also "force-sslv3", "force-tlsv*".
Supported in default-server: No
no-tlsv12
This option disables support for TLSv1.2 when SSL is used to communicate with
the server. Note that SSLv2 is disabled in the code and cannot be enabled
using any configuration option. TLSv1 is more expensive than SSLv3 so it
often makes sense to disable it when communicating with local servers. This
option is also available on global statement "ssl-default-server-options".
See also "force-sslv3", "force-tlsv*".
Supported in default-server: No
non-stick
Never add connections allocated to this sever to a stick-table.
This may be used in conjunction with backup to ensure that
stick-table persistence is disabled for backup servers.
Supported in default-server: No
observe <mode>
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.
Supported in default-server: No
See also the "check", "on-error" and "error-limit".
on-error <mode>
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
Supported in default-server: Yes
See also the "check", "observe" and "error-limit".
on-marked-down <action>
Modify what occurs when a server is marked down.
Currently one action is available:
- shutdown-sessions: Shutdown peer sessions. 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
Supported in default-server: Yes
on-marked-up <action>
Modify what occurs when a server is marked up.
Currently one action is available:
- shutdown-backup-sessions: Shutdown sessions 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 (eg: LDAP, SQL, ...). Doing this can cause more trouble
than it tries to solve (eg: incomplete transactions), so use this feature
with extreme care. Sessions killed because a server comes up are logged
with an 'U' termination code (for "Up").
Actions are disabled by default
Supported in default-server: Yes
port <port>
Using the "port" parameter, it becomes possible to use a different port to
send health-checks. 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.
Supported in default-server: Yes
redir <prefix>
The "redir" parameter enables the redirection mode for all GET and HEAD
requests addressing this server. This means that instead of having HAProxy
forward the request to the server, it will send an "HTTP 302" response with
the "Location" header composed of this prefix immediately followed by the
requested URI beginning at the leading '/' of the path component. That means
that no trailing slash should be used after <prefix>. All invalid requests
will be rejected, and all non-GET or HEAD requests will be normally served by
the server. Note that since the response is completely forged, no header
mangling nor cookie insertion is possible in the response. However, cookies in
requests are still analysed, making this solution completely usable to direct
users to a remote location in case of local disaster. Main use consists in
increasing bandwidth for static servers by having the clients directly
connect to them. Note: never use a relative location here, it would cause a
loop between the client and HAProxy!
Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
Supported in default-server: No
rise <count>
The "rise" parameter states that a server will be considered as operational
after <count> consecutive successful health checks. This value defaults to 2
if unspecified. See also the "check", "inter" and "fall" parameters.
Supported in default-server: Yes
send-proxy
The "send-proxy" parameter enforces use of the PROXY protocol over any
connection established to this server. The PROXY protocol informs the other
end about the layer 3/4 addresses of the incoming connection, so that it can
know the client's address or the public address it accessed to, whatever the
upper layer protocol. For connections accepted by an "accept-proxy" listener,
the advertised address will be used. Only TCPv4 and TCPv6 address families
are supported. Other families such as Unix sockets, will report an UNKNOWN
family. Servers using this option can fully be chained to another instance of
haproxy listening with an "accept-proxy" setting. This setting must not be
used if the server isn't aware of the protocol. When health checks are sent
to the server, the PROXY protocol is automatically used when this option is
set, unless there is an explicit "port" or "addr" directive, in which case an
explicit "check-send-proxy" directive would also be needed to use the PROXY
protocol. See also the "accept-proxy" option of the "bind" keyword.
Supported in default-server: No
send-proxy-v2
The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
over any connection established to this server. The PROXY protocol informs
the other end about the layer 3/4 addresses of the incoming connection, so
that it can know the client's address or the public address it accessed to,
whatever the upper layer protocol. This setting must not be used if the
server isn't aware of this version of the protocol. See also the "send-proxy"
option of the "bind" keyword.
Supported in default-server: No
send-proxy-v2-ssl
The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
2 over any connection established to this server. The PROXY protocol informs
the other end about the layer 3/4 addresses of the incoming connection, so
that it can know the client's address or the public address it accessed to,
whatever the upper layer protocol. In addition, the SSL information extension
of the PROXY protocol is added to the PROXY protocol header. This setting
must not be used if the server isn't aware of this version of the protocol.
See also the "send-proxy-v2" option of the "bind" keyword.
Supported in default-server: No
send-proxy-v2-ssl-cn
The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
2 over any connection established to this server. The PROXY protocol informs
the other end about the layer 3/4 addresses of the incoming connection, so
that it can know the client's address or the public address it accessed to,
whatever the upper layer protocol. In addition, the SSL information extension
of the PROXY protocol, along along with the Common Name from the subject of
the client certificate (if any), is added to the PROXY protocol header. This
setting must not be used if the server isn't aware of this version of the
protocol. See also the "send-proxy-v2" option of the "bind" keyword.
Supported in default-server: No
slowstart <start_time_in_ms>
The "slowstart" parameter for a server accepts a value in milliseconds which
indicates after how long a server which has just come back up will run at
full speed. Just as with every other time-based parameter, it can be entered
in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
linearly from 0 to 100% during this time. The limitation applies to two
parameters :
- maxconn: the number of connections accepted by the server will grow from 1
to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
- weight: when the backend uses a dynamic weighted algorithm, the weight
grows linearly from 1 to 100%. In this case, the weight is updated at every
health-check. For this reason, it is important that the "inter" parameter
is smaller than the "slowstart", in order to maximize the number of steps.
The slowstart never applies when haproxy starts, otherwise it would cause
trouble to running servers. It only applies when a server has been previously
seen as failed.
Supported in default-server: Yes
source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
source <addr>[:<pl>[-<ph>]] [interface <name>] ...
The "source" parameter sets the source address which will be used when
connecting to the server. It follows the exact same parameters and principle
as the backend "source" keyword, except that it only applies to the server
referencing it. Please consult the "source" keyword for details.
Additionally, the "source" statement on a server line allows one to specify a
source port range by indicating the lower and higher bounds delimited by a
dash ('-'). Some operating systems might require a valid IP address when a
source port range is specified. It is permitted to have the same IP/range for
several servers. Doing so makes it possible to bypass the maximum of 64k
total concurrent connections. The limit will then reach 64k connections per
server.
Supported in default-server: No
ssl
This option enables SSL ciphering on outgoing connections to the server. It
is critical to verify server certificates using "verify" when using SSL to
connect to servers, otherwise the communication is prone to trivial man in
the-middle attacks rendering SSL useless. When this option is used, health
checks are automatically sent in SSL too unless there is a "port" or an
"addr" directive indicating the check should be sent to a different location.
See the "check-ssl" option to force SSL health checks.
Supported in default-server: No
track [<proxy>/]<server>
This option enables ability to set the current state of the server by tracking
another one. It is possible to track a server which itself tracks another
server, provided that at the end of the chain, a server has health checks
enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
used, it has to be enabled on both proxies.
Supported in default-server: No
verify [none|required]
This setting is only available when support for OpenSSL was built in. If set
to 'none', server certificate is not verified. In the other case, The
certificate provided by the server is verified using CAs from 'ca-file'
and optional CRLs from 'crl-file'. If 'ssl_server_verify' is not specified
in global section, this is the default. On verify failure the handshake
is aborted. It is critically important to verify server certificates when
using SSL to connect to servers, otherwise the communication is prone to
trivial man-in-the-middle attacks rendering SSL totally useless.
Supported in default-server: No
verifyhost <hostname>
This setting is only available when support for OpenSSL was built in, and
only takes effect if 'verify required' is also specified. When set, the
hostnames in the subject and subjectAlternateNames of the certificate
provided by the server are checked. If none of the hostnames in the
certificate match the specified hostname, the handshake is aborted. The
hostnames in the server-provided certificate may include wildcards.
Supported in default-server: No
weight <weight>
The "weight" parameter is used to adjust the server's weight relative to
other servers. All servers will receive a load proportional to their weight
relative to the sum of all weights, so the higher the weight, the higher the
load. The default weight is 1, and the maximal value is 256. A value of 0
means the server will not participate in load-balancing but will still accept
persistent connections. If this parameter is used to distribute the load
according to server's capacity, it is recommended to start with values which
can both grow and shrink, for instance between 10 and 100 to leave enough
room above and below for later adjustments.
Supported in default-server: Yes