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.
  • 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. 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. 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. 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. 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), fastinter if set, "inter" otherwise.
Transitionally DOWN (going up),
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.

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

Share Button

3 thoughts on “5.2. Server and default-server options

  1. Pingback: DIESEL SHOES

  2. Pingback: cokolwiek

  3. Pingback: tier2 junk

Leave a Reply