5.2. Server and default-server options

  1. The "server" and "default-server" keywords support a certain number of settings
  2. which are all passed as arguments on the server line. The order in which those
  3. arguments appear does not count, and they are all optional. Some of those
  4. settings are single words (booleans) while others expect one or several values
  5. after them. In this case, the values must immediately follow the setting name.
  6. Except default-server, all those settings must be specified after the server's
  7. address if they are used:
  8.  
  9.   server <name> <address>[:port] [settings ...]
  10.   default-server [settings ...]
  11.  
  12. Note that all these settings are supported both by "server" and "default-server"
  13. keywords, except "id" which is only supported by "server".
  14.  
  15. The currently supported settings are the following ones.

addr 

  1. Using the "addr" parameter, it becomes possible to use a different IP address
  2. to send health-checks or to probe the agent-check. On some servers, it may be
  3. desirable to dedicate an IP address to specific component able to perform
  4. complex tests which are more suitable to health-checks than the application.
  5. This parameter is ignored if the "check" parameter is not set. See also the
  6. "port" parameter.

agent-check

  1. Enable an auxiliary agent check which is run independently of a regular
  2. health check. An agent health check is performed by making a TCP connection
  3. to the port set by the "agent-port" parameter and reading an ASCII string
  4. terminated by the first '\r' or '\n' met. The string is made of a series of
  5. words delimited by spaces, tabs or commas in any order, each consisting of :
  6.  
  7. - An ASCII representation of a positive integer percentage, e.g. "75%".
  8.   Values in this format will set the weight proportional to the initial
  9.   weight of a server as configured when haproxy starts. Note that a zero
  10.   weight is reported on the stats page as "DRAIN" since it has the same
  11.   effect on the server (it's removed from the LB farm).
  12.  
  13. - The string "maxconn:" followed by an integer (no space between). Values
  14.   in this format will set the maxconn of a server. The maximum number of
  15.   connections advertised needs to be multiplied by the number of load
  16.   balancers and different backends that use this health check to get the
  17.   total number of connections the server might receive. Example: maxconn:30
  18.  
  19. - The word "ready". This will turn the server's administrative state to the
  20.   READY mode, thus canceling any DRAIN or MAINT state
  21.  
  22. - The word "drain". This will turn the server's administrative state to the
  23.   DRAIN mode, thus it will not accept any new connections other than those
  24.   that are accepted via persistence.
  25.  
  26. - The word "maint". This will turn the server's administrative state to the
  27.   MAINT mode, thus it will not accept any new connections at all, and health
  28.   checks will be stopped.
  29.  
  30. - The words "down", "failed", or "stopped", optionally followed by a
  31.   description string after a sharp ('#'). All of these mark the server's
  32.   operating state as DOWN, but since the word itself is reported on the stats
  33.   page, the difference allows an administrator to know if the situation was
  34.   expected or not : the service may intentionally be stopped, may appear up
  35.   but fail some validity tests, or may be seen as down (e.g. missing process,
  36.   or port not responding).
  37.  
  38. - The word "up" sets back the server's operating state as UP if health checks
  39.   also report that the service is accessible.
  40.  
  41. Parameters which are not advertised by the agent are not changed. For
  42. example, an agent might be designed to monitor CPU usage and only report a
  43. relative weight and never interact with the operating status. Similarly, an
  44. agent could be designed as an end-user interface with 3 radio buttons
  45. allowing an administrator to change only the administrative state. However,
  46. it is important to consider that only the agent may revert its own actions,
  47. so if a server is set to DRAIN mode or to DOWN state using the agent, the
  48. agent must implement the other equivalent actions to bring the service into
  49. operations again.
  50.  
  51. Failure to connect to the agent is not considered an error as connectivity
  52. is tested by the regular health check which is enabled by the "check"
  53. parameter. Warning though, it is not a good idea to stop an agent after it
  54. reports "down", since only an agent reporting "up" will be able to turn the
  55. server up again. Note that the CLI on the Unix stats socket is also able to
  56. force an agent's result in order to work around a bogus agent if needed.
  57.  
  58. Requires the "agent-port" parameter to be set. See also the "agent-inter"
  59. and "no-agent-check" parameters.

agent-send 

  1. If this option is specified, haproxy will send the given string (verbatim)
  2. to the agent server upon connection. You could, for example, encode
  3. the backend name into this string, which would enable your agent to send
  4. different responses based on the backend. Make sure to include a '\n' if
  5. you want to terminate your request with a newline.

agent-inter 

  1. The "agent-inter" parameter sets the interval between two agent checks
  2. to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
  3.  
  4. Just as with every other time-based parameter, it may be entered in any
  5. other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
  6. parameter also serves as a timeout for agent checks "timeout check" is
  7. not set. In order to reduce "resonance" effects when multiple servers are
  8. hosted on the same hardware, the agent and health checks of all servers
  9. are started with a small time offset between them. It is also possible to
  10. add some random noise in the agent and health checks interval using the
  11. global "spread-checks" keyword. This makes sense for instance when a lot
  12. of backends use the same servers.
  13.  
  14. See also the "agent-check" and "agent-port" parameters.

agent-addr 

  1. The "agent-addr" parameter sets address for agent check.
  2.  
  3. You can offload agent-check to another target, so you can make single place
  4. managing status and weights of servers defined in haproxy in case you can't
  5. make self-aware and self-managing services. You can specify both IP or
  6. hostname, it will be resolved.

agent-port 

  1. The "agent-port" parameter sets the TCP port used for agent checks.
  2.  
  3. See also the "agent-check" and "agent-inter" parameters.

allow-0rtt

  1. Allow sending early data to the server when using TLS 1.3.
  2. Note that early data will be sent only if the client used early data, or
  3. if the backend uses "retry-on" with the "0rtt-rejected" keyword.

alpn 

  1. This enables the TLS ALPN extension and advertises the specified protocol
  2. list as supported on top of ALPN. The protocol list consists in a comma-
  3. delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
  4. quotes). This requires that the SSL library is built with support for TLS
  5. extensions enabled (check with haproxy -vv). The ALPN extension replaces the
  6. initial NPN extension. ALPN is required to connect to HTTP/2 servers.
  7. Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
  8. now obsolete NPN extension.
  9. If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can
  10. be advertised, in order of preference, like below :
  11.  
  12.      server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1

backup

  1. When "backup" is present on a server line, the server is only used in load
  2. balancing when all other non-backup servers are unavailable. Requests coming
  3. with a persistence cookie referencing the server will always be served
  4. though. By default, only the first operational backup server is used, unless
  5. the "allbackups" option is set in the backend. See also the "no-backup" and
  6. "allbackups" options.

ca-file 

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

check

  1. This option enables health checks on the server. By default, a server is
  2. always considered available. If "check" is set, the server is available when
  3. accepting periodic TCP connections, to ensure that it is really able to serve
  4. requests. The default address and port to send the tests to are those of the
  5. server, and the default source is the same as the one defined in the
  6. backend. It is possible to change the address using the "addr" parameter, the
  7. port using the "port" parameter, the source address using the "source"
  8. address, and the interval and timers using the "inter", "rise" and "fall"
  9. parameters. The request method is define in the backend using the "httpchk",
  10. "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
  11. refer to those options and parameters for more information. See also
  12. "no-check" option.

check-send-proxy

  1. This option forces emission of a PROXY protocol line with outgoing health
  2. checks, regardless of whether the server uses send-proxy or not for the
  3. normal traffic. By default, the PROXY protocol is enabled for health checks
  4. if it is already enabled for normal traffic and if no "port" nor "addr"
  5. directive is present. However, if such a directive is present, the
  6. "check-send-proxy" option needs to be used to force the use of the
  7. protocol. See also the "send-proxy" option for more information.

check-alpn 

  1. Defines which protocols to advertise with ALPN. The protocol list consists in
  2. a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0"
  3. (without quotes). If it is not set, the server ALPN is used.

check-sni 

  1. This option allows you to specify the SNI to be used when doing health checks
  2. over SSL. It is only possible to use a string to set <sni>. If you want to
  3. set a SNI for proxied traffic, see "sni".

check-ssl

  1. This option forces encryption of all health checks over SSL, regardless of
  2. whether the server uses SSL or not for the normal traffic. This is generally
  3. used when an explicit "port" or "addr" directive is specified and SSL health
  4. checks are not inherited. It is important to understand that this option
  5. inserts an SSL transport layer below the checks, so that a simple TCP connect
  6. check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
  7. common use is to send HTTPS checks by combining "httpchk" with SSL checks.
  8. All SSL settings are common to health checks and traffic (e.g. ciphers).
  9. See the "ssl" option for more information and "no-check-ssl" to disable
  10. this option.

check-via-socks4

  1. This option enables outgoing health checks using upstream socks4 proxy. By
  2. default, the health checks won't go through socks tunnel even it was enabled
  3. for normal traffic.

ciphers 

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

ciphersuites 

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

cookie 

  1. The "cookie" parameter sets the cookie value assigned to the server to
  2. <value>. This value will be checked in incoming requests, and the first
  3. operational server possessing the same value will be selected. In return, in
  4. cookie insertion or rewrite modes, this value will be assigned to the cookie
  5. sent to the client. There is nothing wrong in having several servers sharing
  6. the same cookie value, and it is in fact somewhat common between normal and
  7. backup servers. See also the "cookie" keyword in backend section.

crl-file 

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

crt 

  1. This setting is only available when support for OpenSSL was built in.
  2. It designates a PEM file from which to load both a certificate and the
  3. associated private key. This file can be built by concatenating both PEM
  4. files into one. This certificate will be sent if the server send a client
  5. certificate request.

disabled

  1. The "disabled" keyword starts the server in the "disabled" state. That means
  2. that it is marked down in maintenance mode, and no connection other than the
  3. ones allowed by persist mode will reach it. It is very well suited to setup
  4. new servers, because normal traffic will never reach them, while it is still
  5. possible to test the service by making use of the force-persist mechanism.
  6. See also "enabled" setting.

enabled

  1. This option may be used as 'server' setting to reset any 'disabled'
  2. setting which would have been inherited from 'default-server' directive as
  3. default value.
  4. It may also be used as 'default-server' setting to reset any previous
  5. 'default-server' 'disabled' setting.

error-limit 

  1. If health observing is enabled, the "error-limit" parameter specifies the
  2. number of consecutive errors that triggers event selected by the "on-error"
  3. option. By default it is set to 10 consecutive errors.
  4.  
  5. See also the "check", "error-limit" and "on-error".

fall 

  1. The "fall" parameter states that a server will be considered as dead after
  2. <count> consecutive unsuccessful health checks. This value defaults to 3 if
  3. unspecified. See also the "check", "inter" and "rise" parameters.

force-sslv3

  1. This option enforces use of SSLv3 only when SSL is used to communicate with
  2. the server. SSLv3 is generally less expensive than the TLS counterparts for
  3. high connection rates. This option is also available on global statement
  4. "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".

force-tlsv10

  1. This option enforces use of TLSv1.0 only when SSL is used to communicate with
  2. the server. This option is also available on global statement
  3. "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".

force-tlsv11

  1. This option enforces use of TLSv1.1 only when SSL is used to communicate with
  2. the server. This option is also available on global statement
  3. "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".

force-tlsv12

  1. This option enforces use of TLSv1.2 only when SSL is used to communicate with
  2. the server. This option is also available on global statement
  3. "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".

force-tlsv13

  1. This option enforces use of TLSv1.3 only when SSL is used to communicate with
  2. the server. This option is also available on global statement
  3. "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".

id 

  1. Set a persistent ID for the server. This ID must be positive and unique for
  2. the proxy. An unused ID will automatically be assigned if unset. The first
  3. assigned value will be 1. This ID is currently only returned in statistics.

init-addr {last | libc | none | },[…]*

  1. Indicate in what order the server's address should be resolved upon startup
  2. if it uses an FQDN. Attempts are made to resolve the address by applying in
  3. turn each of the methods mentioned in the comma-delimited list. The first
  4. method which succeeds is used. If the end of the list is reached without
  5. finding a working method, an error is thrown. Method "last" suggests to pick
  6. the address which appears in the state file (see "server-state-file"). Method
  7. "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
  8. depending on the operating system and build options). Method "none"
  9. specifically indicates that the server should start without any valid IP
  10. address in a down state. It can be useful to ignore some DNS issues upon
  11. startup, waiting for the situation to get fixed later. Finally, an IP address
  12. (IPv4 or IPv6) may be provided. It can be the currently known address of the
  13. server (e.g. filled by a configuration generator), or the address of a dummy
  14. server used to catch old sessions and present them with a decent error
  15. message for example. When the "first" load balancing algorithm is used, this
  16. IP address could point to a fake server used to trigger the creation of new
  17. instances on the fly. This option defaults to "last,libc" indicating that the
  18. previous address found in the state file (if any) is used first, otherwise
  19. the libc's resolver is used. This ensures continued compatibility with the
  20. historic behavior.

Example:

  1. defaults
  2.     # never fail on address resolution
  3.     default-server init-addr last,libc,none

inter

fastinter

downinter 

  1. The "inter" parameter sets the interval between two consecutive health checks
  2. to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
  3. It is also possible to use "fastinter" and "downinter" to optimize delays
  4. between checks depending on the server state :
Server stateInterval used
UP 100% (non-transitional)“inter“
Transitionally UP (going down “fall“),
Transitionally DOWN (going up “rise“),
or yet unchecked.		“fastinter“ if set,
“inter“ otherwise.
DOWN 100% (non-transitional)
“downinter“ if set,
“inter“ otherwise.
  1. Just as with every other time-based parameter, they can be entered in any
  2. other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
  3. serves as a timeout for health checks sent to servers if "timeout check" is
  4. not set. In order to reduce "resonance" effects when multiple servers are
  5. hosted on the same hardware, the agent and health checks of all servers
  6. are started with a small time offset between them. It is also possible to
  7. add some random noise in the agent and health checks interval using the
  8. global "spread-checks" keyword. This makes sense for instance when a lot
  9. of backends use the same servers.

maxconn 

  1. The "maxconn" parameter specifies the maximal number of concurrent
  2. connections that will be sent to this server. If the number of incoming
  3. concurrent connections goes higher than this value, they will be queued,
  4. waiting for a slot to be released. This parameter is very important as it can
  5. save fragile servers from going down under extreme loads. If a "minconn"
  6. parameter is specified, the limit becomes dynamic. The default value is "0"
  7. which means unlimited. See also the "minconn" and "maxqueue" parameters, and
  8. the backend's "fullconn" keyword.
  9.  
  10. In HTTP mode this parameter limits the number of concurrent requests instead
  11. of the number of connections. Multiple requests might be multiplexed over a
  12. single TCP connection to the server. As an example if you specify a maxconn
  13. of 50 you might see between 1 and 50 actual server connections, but no more
  14. than 50 concurrent requests.

maxqueue 

  1. The "maxqueue" parameter specifies the maximal number of connections which
  2. will wait in the queue for this server. If this limit is reached, next
  3. requests will be redispatched to other servers instead of indefinitely
  4. waiting to be served. This will break persistence but may allow people to
  5. quickly re-log in when the server they try to connect to is dying. The
  6. default value is "0" which means the queue is unlimited. See also the
  7. "maxconn" and "minconn" parameters.

max-reuse 

  1. The "max-reuse" argument indicates the HTTP connection processors that they
  2. should not reuse a server connection more than this number of times to send
  3. new requests. Permitted values are -1 (the default), which disables this
  4. limit, or any positive value. Value zero will effectively disable keep-alive.
  5. This is only used to work around certain server bugs which cause them to leak
  6. resources over time. The argument is not necessarily respected by the lower
  7. layers as there might be technical limitations making it impossible to
  8. enforce. At least HTTP/2 connections to servers will respect it.

minconn 

  1. When the "minconn" parameter is set, the maxconn limit becomes a dynamic
  2. limit following the backend's load. The server will always accept at least
  3. <minconn> connections, never more than <maxconn>, and the limit will be on
  4. the ramp between both values when the backend has less than <fullconn>
  5. concurrent connections. This makes it possible to limit the load on the
  6. server during normal loads, but push it further for important loads without
  7. overloading the server during exceptional loads. See also the "maxconn"
  8. and "maxqueue" parameters, as well as the "fullconn" backend keyword.

namespace 

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

no-agent-check

  1. This option may be used as "server" setting to reset any "agent-check"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "agent-check" setting.

no-backup

  1. This option may be used as "server" setting to reset any "backup"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "backup" setting.

no-check

  1. This option may be used as "server" setting to reset any "check"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "check" setting.

no-check-ssl

  1. This option may be used as "server" setting to reset any "check-ssl"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "check-ssl" setting.

no-send-proxy

  1. This option may be used as "server" setting to reset any "send-proxy"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "send-proxy" setting.

no-send-proxy-v2

  1. This option may be used as "server" setting to reset any "send-proxy-v2"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "send-proxy-v2" setting.

no-send-proxy-v2-ssl

  1. This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "send-proxy-v2-ssl" setting.

no-send-proxy-v2-ssl-cn

  1. This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "send-proxy-v2-ssl-cn" setting.

no-ssl

  1. This option may be used as "server" setting to reset any "ssl"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "ssl" setting.

no-ssl-reuse

  1. This option disables SSL session reuse when SSL is used to communicate with
  2. the server. It will force the server to perform a full handshake for every
  3. new connection. It's probably only useful for benchmarking, troubleshooting,
  4. and for paranoid users.

no-sslv3

  1. This option disables support for SSLv3 when SSL is used to communicate with
  2. the server. Note that SSLv2 is disabled in the code and cannot be enabled
  3. using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
  4.  
  5. Supported in default-server: No

no-tls-tickets

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

no-tlsv10

  1. This option disables support for TLSv1.0 when SSL is used to communicate with
  2. the server. Note that SSLv2 is disabled in the code and cannot be enabled
  3. using any configuration option. TLSv1 is more expensive than SSLv3 so it
  4. often makes sense to disable it when communicating with local servers. This
  5. option is also available on global statement "ssl-default-server-options".
  6. Use "ssl-min-ver" and "ssl-max-ver" instead.
  7.  
  8. Supported in default-server: No

no-tlsv11

  1. This option disables support for TLSv1.1 when SSL is used to communicate with
  2. the server. Note that SSLv2 is disabled in the code and cannot be enabled
  3. using any configuration option. TLSv1 is more expensive than SSLv3 so it
  4. often makes sense to disable it when communicating with local servers. This
  5. option is also available on global statement "ssl-default-server-options".
  6. Use "ssl-min-ver" and "ssl-max-ver" instead.
  7.  
  8. Supported in default-server: No

no-tlsv12

  1. This option disables support for TLSv1.2 when SSL is used to communicate with
  2. the server. Note that SSLv2 is disabled in the code and cannot be enabled
  3. using any configuration option. TLSv1 is more expensive than SSLv3 so it
  4. often makes sense to disable it when communicating with local servers. This
  5. option is also available on global statement "ssl-default-server-options".
  6. Use "ssl-min-ver" and "ssl-max-ver" instead.
  7.  
  8. Supported in default-server: No

no-tlsv13

  1. This option disables support for TLSv1.3 when SSL is used to communicate with
  2. the server. Note that SSLv2 is disabled in the code and cannot be enabled
  3. using any configuration option. TLSv1 is more expensive than SSLv3 so it
  4. often makes sense to disable it when communicating with local servers. This
  5. option is also available on global statement "ssl-default-server-options".
  6. Use "ssl-min-ver" and "ssl-max-ver" instead.
  7.  
  8. Supported in default-server: No

no-verifyhost

  1. This option may be used as "server" setting to reset any "verifyhost"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "verifyhost" setting.

no-tfo

  1. This option may be used as "server" setting to reset any "tfo"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "tfo" setting.

non-stick

  1. Never add connections allocated to this sever to a stick-table.
  2. This may be used in conjunction with backup to ensure that
  3. stick-table persistence is disabled for backup servers.

npn 

  1. This enables the NPN TLS extension and advertises the specified protocol list
  2. as supported on top of NPN. The protocol list consists in a comma-delimited
  3. list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
  4. This requires that the SSL library is built with support for TLS extensions
  5. enabled (check with haproxy -vv). Note that the NPN extension has been
  6. replaced with the ALPN extension (see the "alpn" keyword), though this one is
  7. only available starting with OpenSSL 1.0.2.

observe 

  1. This option enables health adjusting based on observing communication with
  2. the server. By default this functionality is disabled and enabling it also
  3. requires to enable health checks. There are two supported modes: "layer4" and
  4. "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
  5. significant. In layer7, which is only allowed for http proxies, responses
  6. received from server are verified, like valid/wrong http code, unparsable
  7. headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
  8.  
  9. See also the "check", "on-error" and "error-limit".

on-error 

  1. Select what should happen when enough consecutive errors are detected.
  2. Currently, four modes are available:
  3. - fastinter: force fastinter
  4. - fail-check: simulate a failed check, also forces fastinter (default)
  5. - sudden-death: simulate a pre-fatal failed health check, one more failed
  6.   check will mark a server down, forces fastinter
  7. - mark-down: mark the server immediately down and force fastinter
  8.  
  9. See also the "check", "observe" and "error-limit".

on-marked-down 

  1. Modify what occurs when a server is marked down.
  2. Currently one action is available:
  3. - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
  4.   all connections to the server are immediately terminated when the server
  5.   goes down. It might be used if the health check detects more complex cases
  6.   than a simple connection status, and long timeouts would cause the service
  7.   to remain unresponsive for too long a time. For instance, a health check
  8.   might detect that a database is stuck and that there's no chance to reuse
  9.   existing connections anymore. Connections killed this way are logged with
  10.   a 'D' termination code (for "Down").
  11.  
  12. Actions are disabled by default

on-marked-up 

  1. Modify what occurs when a server is marked up.
  2. Currently one action is available:
  3. - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
  4.   done only if the server is not in backup state and if it is not disabled
  5.   (it must have an effective weight > 0). This can be used sometimes to force
  6.   an active server to take all the traffic back after recovery when dealing
  7.   with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble
  8.   than it tries to solve (e.g. incomplete transactions), so use this feature
  9.   with extreme care. Sessions killed because a server comes up are logged
  10.   with an 'U' termination code (for "Up").
  11.  
  12. Actions are disabled by default

pool-max-conn 

  1. Set the maximum number of idling connections for a server. -1 means unlimited
  2. connections, 0 means no idle connections. The default is -1. When idle
  3. connections are enabled, orphaned idle connections which do not belong to any
  4. client session anymore are moved to a dedicated pool so that they remain
  5. usable by future clients. This only applies to connections that can be shared
  6. according to the same principles as those applying to "http-reuse".

pool-purge-delay 

  1. Sets the delay to start purging idle connections. Each <delay> interval, half
  2. of the idle connections are closed. 0 means we don't keep any idle connection.
  3. The default is 5s.

port 

  1. Using the "port" parameter, it becomes possible to use a different port to
  2. send health-checks. On some servers, it may be desirable to dedicate a port
  3. to a specific component able to perform complex tests which are more suitable
  4. to health-checks than the application. It is common to run a simple script in
  5. inetd for instance. This parameter is ignored if the "check" parameter is not
  6. set. See also the "addr" parameter.

proto 

  1. Forces the multiplexer's protocol to use for the outgoing connections to this
  2. server. It must be compatible with the mode of the backend (TCP or HTTP). It
  3. must also be usable on the backend side. The list of available protocols is
  4. reported in haproxy -vv.
  5. Idea behind this optipon is to bypass the selection of the best multiplexer's
  6. protocol for all connections established to this server.

redir 

  1. The "redir" parameter enables the redirection mode for all GET and HEAD
  2. requests addressing this server. This means that instead of having HAProxy
  3. forward the request to the server, it will send an "HTTP 302" response with
  4. the "Location" header composed of this prefix immediately followed by the
  5. requested URI beginning at the leading '/' of the path component. That means
  6. that no trailing slash should be used after <prefix>. All invalid requests
  7. will be rejected, and all non-GET or HEAD requests will be normally served by
  8. the server. Note that since the response is completely forged, no header
  9. mangling nor cookie insertion is possible in the response. However, cookies in
  10. requests are still analyzed, making this solution completely usable to direct
  11. users to a remote location in case of local disaster. Main use consists in
  12. increasing bandwidth for static servers by having the clients directly
  13. connect to them. Note: never use a relative location here, it would cause a
  14. loop between the client and HAProxy!

Example :

  1. server srv1 192.168.1.1:80 redir http://image1.mydomain.com check

rise 

  1. The "rise" parameter states that a server will be considered as operational
  2. after <count> consecutive successful health checks. This value defaults to 2
  3. if unspecified. See also the "check", "inter" and "fall" parameters.

resolve-opts 

  1. Comma separated list of options to apply to DNS resolution linked to this
  2. server.
  3.  
  4. Available options:
  5.  
  6. * allow-dup-ip
  7.   By default, HAProxy prevents IP address duplication in a backend when DNS
  8.   resolution at runtime is in operation.
  9.   That said, for some cases, it makes sense that two servers (in the same
  10.   backend, being resolved by the same FQDN) have the same IP address.
  11.   For such case, simply enable this option.
  12.   This is the opposite of prevent-dup-ip.
  13.  
  14. * prevent-dup-ip
  15.   Ensure HAProxy's default behavior is enforced on a server: prevent re-using
  16.   an IP address already set to a server in the same backend and sharing the
  17.   same fqdn.
  18.   This is the opposite of allow-dup-ip.

Example:

  1. backend b_myapp
  2.   default-server init-addr none resolvers dns
  3.   server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
  4.   server s2 myapp.example.com:81 check resolve-opts allow-dup-ip
  1. With the option allow-dup-ip set:
  2. * if the nameserver returns a single IP address, then both servers will use
  3.   it
  4. * If the nameserver returns 2 IP addresses, then each server will pick up a
  5.   different address
  6.  
  7. Default value: not set

resolve-prefer 

  1. When DNS resolution is enabled for a server and multiple IP addresses from
  2. different families are returned, HAProxy will prefer using an IP address
  3. from the family mentioned in the "resolve-prefer" parameter.
  4. Available families: "ipv4" and "ipv6"
  5.  
  6. Default value: ipv6

Example:

  1. server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6

resolve-net [,<network[,…]]

  1. This option prioritizes the choice of an ip address matching a network. This is
  2. useful with clouds to prefer a local ip. In some cases, a cloud high
  3. availability service can be announced with many ip addresses on many
  4. different datacenters. The latency between datacenter is not negligible, so
  5. this patch permits to prefer a local datacenter. If no address matches the
  6. configured network, another address is selected.

Example:

  1. server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8

resolvers 

  1. Points to an existing "resolvers" section to resolve current server's
  2. hostname.

Example:

  1. server s1 app1.domain.com:80 check resolvers mydns
  1. See also section 5.3

send-proxy

  1. The "send-proxy" parameter enforces use of the PROXY protocol over any
  2. connection established to this server. The PROXY protocol informs the other
  3. end about the layer 3/4 addresses of the incoming connection, so that it can
  4. know the client's address or the public address it accessed to, whatever the
  5. upper layer protocol. For connections accepted by an "accept-proxy" or
  6. "accept-netscaler-cip" listener, the advertised address will be used. Only
  7. TCPv4 and TCPv6 address families are supported. Other families such as
  8. Unix sockets, will report an UNKNOWN family. Servers using this option can
  9. fully be chained to another instance of haproxy listening with an
  10. "accept-proxy" setting. This setting must not be used if the server isn't
  11. aware of the protocol. When health checks are sent to the server, the PROXY
  12. protocol is automatically used when this option is set, unless there is an
  13. explicit "port" or "addr" directive, in which case an explicit
  14. "check-send-proxy" directive would also be needed to use the PROXY protocol.
  15. See also the "no-send-proxy" option of this section and "accept-proxy" and
  16. "accept-netscaler-cip" option of the "bind" keyword.

send-proxy-v2

  1. The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
  2. over any connection established to this server. The PROXY protocol informs
  3. the other end about the layer 3/4 addresses of the incoming connection, so
  4. that it can know the client's address or the public address it accessed to,
  5. whatever the upper layer protocol. It also send ALPN information if an alpn
  6. have been negotiated. This setting must not be used if the server isn't aware
  7. of this version of the protocol. See also the "no-send-proxy-v2" option of
  8. this section and send-proxy" option of the "bind" keyword.

proxy-v2-options 

  1. The "proxy-v2-options" parameter add option to send in PROXY protocol version
  2. 2 when "send-proxy-v2" is used. Options available are "ssl" (see also
  3. send-proxy-v2-ssl), "cert-cn" (see also "send-proxy-v2-ssl-cn"), "ssl-cipher":
  4. name of the used cipher, "cert-sig": signature algorithm of the used
  5. certificate, "cert-key": key algorithm of the used certificate), "authority":
  6. host name value passed by the client (only sni from a tls connection is
  7. supported), "crc32c": checksum of the proxy protocol v2 header.

send-proxy-v2-ssl

  1. The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
  2. 2 over any connection established to this server. The PROXY protocol informs
  3. the other end about the layer 3/4 addresses of the incoming connection, so
  4. that it can know the client's address or the public address it accessed to,
  5. whatever the upper layer protocol. In addition, the SSL information extension
  6. of the PROXY protocol is added to the PROXY protocol header. This setting
  7. must not be used if the server isn't aware of this version of the protocol.
  8. See also the "no-send-proxy-v2-ssl" option of this section and the
  9. "send-proxy-v2" option of the "bind" keyword.

send-proxy-v2-ssl-cn

  1. The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
  2. 2 over any connection established to this server. The PROXY protocol informs
  3. the other end about the layer 3/4 addresses of the incoming connection, so
  4. that it can know the client's address or the public address it accessed to,
  5. whatever the upper layer protocol. In addition, the SSL information extension
  6. of the PROXY protocol, along along with the Common Name from the subject of
  7. the client certificate (if any), is added to the PROXY protocol header. This
  8. setting must not be used if the server isn't aware of this version of the
  9. protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and
  10. the "send-proxy-v2" option of the "bind" keyword.

slowstart 

  1. The "slowstart" parameter for a server accepts a value in milliseconds which
  2. indicates after how long a server which has just come back up will run at
  3. full speed. Just as with every other time-based parameter, it can be entered
  4. in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
  5. linearly from 0 to 100% during this time. The limitation applies to two
  6. parameters :
  7.  
  8. - maxconn: the number of connections accepted by the server will grow from 1
  9.   to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
  10.  
  11. - weight: when the backend uses a dynamic weighted algorithm, the weight
  12.   grows linearly from 1 to 100%. In this case, the weight is updated at every
  13.   health-check. For this reason, it is important that the "inter" parameter
  14.   is smaller than the "slowstart", in order to maximize the number of steps.
  15.  
  16. The slowstart never applies when haproxy starts, otherwise it would cause
  17. trouble to running servers. It only applies when a server has been previously
  18. seen as failed.

sni 

  1. The "sni" parameter evaluates the sample fetch expression, converts it to a
  2. string and uses the result as the host name sent in the SNI TLS extension to
  3. the server. A typical use case is to send the SNI received from the client in
  4. a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
  5. expression, though alternatives such as req.hdr(host) can also make sense. If
  6. "verify required" is set (which is the recommended setting), the resulting
  7. name will also be matched against the server certificate's names. See the
  8. "verify" directive for more details. If you want to set a SNI for health
  9. checks, see the "check-sni" directive for more details.

source [:[-]] [usesrc { [:] | client | clientip } ]

source [:] [usesrc { [:] | hdr_ip([,]) } ]

source [:[-]] [interface ] …

  1. The "source" parameter sets the source address which will be used when
  2. connecting to the server. It follows the exact same parameters and principle
  3. as the backend "source" keyword, except that it only applies to the server
  4. referencing it. Please consult the "source" keyword for details.
  5.  
  6. Additionally, the "source" statement on a server line allows one to specify a
  7. source port range by indicating the lower and higher bounds delimited by a
  8. dash ('-'). Some operating systems might require a valid IP address when a
  9. source port range is specified. It is permitted to have the same IP/range for
  10. several servers. Doing so makes it possible to bypass the maximum of 64k
  11. total concurrent connections. The limit will then reach 64k connections per
  12. server.
  13.  
  14. Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
  15. specifying the source address without port(s).

ssl

  1. This option enables SSL ciphering on outgoing connections to the server. It
  2. is critical to verify server certificates using "verify" when using SSL to
  3. connect to servers, otherwise the communication is prone to trivial man in
  4. the-middle attacks rendering SSL useless. When this option is used, health
  5. checks are automatically sent in SSL too unless there is a "port" or an
  6. "addr" directive indicating the check should be sent to a different location.
  7. See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
  8. SSL health checks.

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

  1. This option enforces use of <version> or lower when SSL is used to communicate
  2. with the server. This option is also available on global statement
  3. "ssl-default-server-options". See also "ssl-min-ver".

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

  1. This option enforces use of <version> or upper when SSL is used to communicate
  2. with the server. This option is also available on global statement
  3. "ssl-default-server-options". See also "ssl-max-ver".

ssl-reuse

  1. This option may be used as "server" setting to reset any "no-ssl-reuse"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "no-ssl-reuse" setting.

stick

  1. This option may be used as "server" setting to reset any "non-stick"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. It may also be used as "default-server" setting to reset any previous
  5. "default-server" "non-stick" setting.

socks4 :

  1. This option enables upstream socks4 tunnel for outgoing connections to the
  2. server. Using this option won't force the health check to go via socks4 by
  3. default. You will have to use the keyword "check-via-socks4" to enable it.

tcp-ut 

  1. Sets the TCP User Timeout for all outgoing connections to this server. This
  2. option is available on Linux since version 2.6.37. It allows haproxy to
  3. configure a timeout for sockets which contain data not receiving an
  4. acknowledgment for the configured delay. This is especially useful on
  5. long-lived connections experiencing long idle periods such as remote
  6. terminals or database connection pools, where the client and server timeouts
  7. must remain high to allow a long period of idle, but where it is important to
  8. detect that the server has disappeared in order to release all resources
  9. associated with its connection (and the client's session). One typical use
  10. case is also to force dead server connections to die when health checks are
  11. too slow or during a soft reload since health checks are then disabled. The
  12. argument is a delay expressed in milliseconds by default. This only works for
  13. regular TCP connections, and is ignored for other protocols.

tfo

  1. This option enables using TCP fast open when connecting to servers, on
  2. systems that support it (currently only the Linux kernel >= 4.11).
  3. See the "tfo" bind option for more information about TCP fast open.
  4. Please note that when using tfo, you should also use the "conn-failure",
  5. "empty-response" and "response-timeout" keywords for "retry-on", or haproxy
  6. won't be able to retry the connection on failure. See also "no-tfo".

track [/]

  1. This option enables ability to set the current state of the server by tracking
  2. another one. It is possible to track a server which itself tracks another
  3. server, provided that at the end of the chain, a server has health checks
  4. enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
  5. used, it has to be enabled on both proxies.

tls-tickets

  1. This option may be used as "server" setting to reset any "no-tls-tickets"
  2. setting which would have been inherited from "default-server" directive as
  3. default value.
  4. The TLS ticket mechanism is only used up to TLS 1.2.
  5. Forward Secrecy is compromised with TLS tickets, unless ticket keys
  6. are periodically rotated (via reload or by using "tls-ticket-keys").
  7. It may also be used as "default-server" setting to reset any previous
  8. "default-server" "no-tls-tickets" setting.

verify [none|required]

  1. This setting is only available when support for OpenSSL was built in. If set
  2. to 'none', server certificate is not verified. In the other case, The
  3. certificate provided by the server is verified using CAs from 'ca-file' and
  4. optional CRLs from 'crl-file' after having checked that the names provided in
  5. the certificate's subject and subjectAlternateNames attributes match either
  6. the name passed using the "sni" directive, or if not provided, the static
  7. host name passed using the "verifyhost" directive. When no name is found, the
  8. certificate's names are ignored. For this reason, without SNI it's important
  9. to use "verifyhost". On verification failure the handshake is aborted. It is
  10. critically important to verify server certificates when using SSL to connect
  11. to servers, otherwise the communication is prone to trivial man-in-the-middle
  12. attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
  13. the global section, "verify" is set to "required" by default.

verifyhost 

  1. This setting is only available when support for OpenSSL was built in, and
  2. only takes effect if 'verify required' is also specified. This directive sets
  3. a default static hostname to check the server's certificate against when no
  4. SNI was used to connect to the server. If SNI is not used, this is the only
  5. way to enable hostname verification. This static hostname, when set, will
  6. also be used for health checks (which cannot provide an SNI value). If none
  7. of the hostnames in the certificate match the specified hostname, the
  8. handshake is aborted. The hostnames in the server-provided certificate may
  9. include wildcards. See also "verify", "sni" and "no-verifyhost" options.

weight 

  1. The "weight" parameter is used to adjust the server's weight relative to
  2. other servers. All servers will receive a load proportional to their weight
  3. relative to the sum of all weights, so the higher the weight, the higher the
  4. load. The default weight is 1, and the maximal value is 256. A value of 0
  5. means the server will not participate in load-balancing but will still accept
  6. persistent connections. If this parameter is used to distribute the load
  7. according to server's capacity, it is recommended to start with values which
  8. can both grow and shrink, for instance between 10 and 100 to leave enough
  9. room above and below for later adjustments.