diff --git a/doc/configuration.txt b/doc/configuration.txt index 2d514b754..daf02a4fb 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -16161,6 +16161,8 @@ keywords, except "id" which is only supported by "server". The currently supported settings are the following ones. addr + May be used in the following contexts: tcp, http, log + Using the "addr" parameter, it becomes possible to use a different IP address to send health-checks or to probe the agent-check. On some servers, it may be desirable to dedicate an IP address to specific component able to perform @@ -16169,6 +16171,8 @@ addr "port" parameter. agent-check + May be used in the following contexts: tcp, http, log + 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 @@ -16230,6 +16234,8 @@ agent-check and "no-agent-check" parameters. agent-send + May be used in the following contexts: tcp, http, log + If this option is specified, HAProxy will send the given string (verbatim) to the agent server upon connection. You could, for example, encode the backend name into this string, which would enable your agent to send @@ -16237,6 +16243,8 @@ agent-send you want to terminate your request with a newline. agent-inter + May be used in the following contexts: tcp, http, log + The "agent-inter" parameter sets the interval between two agent checks to milliseconds. If left unspecified, the delay defaults to 2000 ms. @@ -16253,6 +16261,8 @@ agent-inter See also the "agent-check" and "agent-port" parameters. agent-addr + May be used in the following contexts: tcp, http, log + The "agent-addr" parameter sets address for agent check. You can offload agent-check to another target, so you can make single place @@ -16261,16 +16271,22 @@ agent-addr hostname, it will be resolved. agent-port + May be used in the following contexts: tcp, http, log + The "agent-port" parameter sets the TCP port used for agent checks. See also the "agent-check" and "agent-inter" parameters. allow-0rtt + May be used in the following contexts: tcp, http, log, peers, ring + Allow sending early data to the server when using TLS 1.3. Note that early data will be sent only if the client used early data, or if the backend uses "retry-on" with the "0rtt-rejected" keyword. alpn + May be used in the following contexts: tcp, http + 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 @@ -16287,6 +16303,8 @@ alpn See also "ws" to use an alternative ALPN for websocket streams. backup + May be used in the following contexts: tcp, http, log + 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 @@ -16295,6 +16313,8 @@ backup "allbackups" options. ca-file + May be used in the following contexts: tcp, http, log, peers, ring + 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. It is possible to load a directory containing multiple @@ -16306,6 +16326,8 @@ ca-file overwritten by setting the SSL_CERT_DIR environment variable. check + May be used in the following contexts: tcp, http, log + This option enables health checks on a server: - when not set, no health checking is performed, and the server is always considered available. @@ -16363,6 +16385,8 @@ check server s1 192.168.0.1:443 ssl check check-send-proxy + May be used in the following contexts: tcp, http + 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 @@ -16372,11 +16396,15 @@ check-send-proxy protocol. See also the "send-proxy" option for more information. check-alpn + May be used in the following contexts: tcp, http + Defines which protocols to advertise with ALPN. The protocol list consists in a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0" (without quotes). If it is not set, the server ALPN is used. check-proto + May be used in the following contexts: tcp, http + Forces the multiplexer's protocol to use for the server's health-check connections. It must be compatible with the health-check type (TCP or HTTP). It must also be usable on the backend side. The list of available @@ -16400,11 +16428,15 @@ check-proto If not defined, the server one will be used, if set. check-sni + May be used in the following contexts: tcp, http, log + This option allows you to specify the SNI to be used when doing health checks over SSL. It is only possible to use a string to set . If you want to set a SNI for proxied traffic, see "sni". check-ssl + May be used in the following contexts: tcp, http, log + 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 @@ -16417,11 +16449,15 @@ check-ssl this option. check-via-socks4 + May be used in the following contexts: tcp, http, log + This option enables outgoing health checks using upstream socks4 proxy. By default, the health checks won't go through socks tunnel even it was enabled for normal traffic. ciphers + May be used in the following contexts: tcp, http, log, peers, ring + This setting is only available when support for OpenSSL was built in. This option sets the string describing the list of cipher algorithms that is negotiated during the SSL/TLS handshake with the server. The format of the @@ -16432,6 +16468,8 @@ ciphers cipher configuration, please check the "ciphersuites" keyword. ciphersuites + May be used in the following contexts: tcp, http, log, peers, ring + This setting is only available when support for OpenSSL was built in and OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string describing the list of cipher algorithms that is negotiated during the TLS @@ -16441,6 +16479,8 @@ ciphersuites keyword. client-sigalgs + May be used in the following contexts: tcp, http, log, peers, ring + This setting is only available when support for OpenSSL was built in. It sets the string describing the list of signature algorithms related to client authentication that are negotiated . The format of the string is defined in @@ -16448,6 +16488,8 @@ client-sigalgs recommended to use this setting if no specific usecase was identified. cookie + May be used in the following contexts: http + The "cookie" parameter sets the cookie value assigned to the server to . This value will be checked in incoming requests, and the first operational server possessing the same value will be selected. In return, in @@ -16457,11 +16499,15 @@ cookie backup servers. See also the "cookie" keyword in backend section. crl-file + May be used in the following contexts: tcp, http, log, peers, ring + 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. crt + May be used in the following contexts: tcp, http, log, peers, ring + 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 @@ -16473,6 +16519,8 @@ crt option is set accordingly). curves + May be used in the following contexts: tcp, http, log, peers, ring + This setting is only available when support for OpenSSL was built in. It sets the string describing the list of elliptic curves algorithms ("curve suite") that are negotiated during the SSL/TLS handshake with ECDHE. The format of the @@ -16480,6 +16528,8 @@ curves Example: "X25519:P-256" (without quote) disabled + May be used in the following contexts: tcp, http, log + 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 @@ -16488,6 +16538,8 @@ disabled See also "enabled" setting. enabled + May be used in the following contexts: tcp, http, log + This option may be used as 'server' setting to reset any 'disabled' setting which would have been inherited from 'default-server' directive as default value. @@ -16495,6 +16547,8 @@ enabled 'default-server' 'disabled' setting. error-limit + May be used in the following contexts: tcp, http, log + 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. @@ -16502,42 +16556,58 @@ error-limit See also the "check", "error-limit" and "on-error". fall + May be used in the following contexts: tcp, http, log + The "fall" parameter states that a server will be considered as dead after consecutive unsuccessful health checks. This value defaults to 3 if unspecified. See also the "check", "inter" and "rise" parameters. force-sslv3 + May be used in the following contexts: tcp, http, log, peers, ring + 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 "ssl-min-ver" and ssl-max-ver". force-tlsv10 + May be used in the following contexts: tcp, http, log, peers, ring + 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 "ssl-min-ver" and ssl-max-ver". force-tlsv11 + May be used in the following contexts: tcp, http, log, peers, ring + 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 "ssl-min-ver" and ssl-max-ver". force-tlsv12 + May be used in the following contexts: tcp, http, log, peers, ring + 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 "ssl-min-ver" and ssl-max-ver". force-tlsv13 + May be used in the following contexts: tcp, http, log, peers, ring + This option enforces use of TLSv1.3 only when SSL is used to communicate with the server. This option is also available on global statement "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver". id + May be used in the following contexts: tcp, http, log + 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. init-addr {last | libc | none | },[...]* + May be used in the following contexts: tcp, http, log + Indicate in what order the server's address should be resolved upon startup if it uses an FQDN. Attempts are made to resolve the address by applying in turn each of the methods mentioned in the comma-delimited list. The first @@ -16567,6 +16637,8 @@ init-addr {last | libc | none | },[...]* inter fastinter downinter + May be used in the following contexts: tcp, http, log + The "inter" parameter sets the interval between two consecutive health checks to milliseconds. If left unspecified, the delay defaults to 2000 ms. It is also possible to use "fastinter" and "downinter" to optimize delays @@ -16602,6 +16674,8 @@ downinter reduce the time spent in the queue. log-bufsize + May be used in the following contexts: log + The "log-bufsize" specifies the ring bufsize to use for the implicit ring that will be associated to the log server in a log backend. When not specified, this defaults to BUFSIZE. Use of a greater value will increase @@ -16610,12 +16684,16 @@ log-bufsize This keyword may only be used in log backend sections (with "mode log") log-proto + May be used in the following contexts: log, ring + The "log-proto" specifies the protocol used to forward event messages to a server configured in a log or ring section. Possible values are "legacy" and "octet-count" corresponding respectively to "Non-transparent-framing" and "Octet counting" in rfc6587. "legacy" is the default. maxconn + May be used in the following contexts: tcp, http + The "maxconn" parameter specifies the maximal number of concurrent connections that will be sent to this server. If the number of incoming concurrent connections goes higher than this value, they will be queued, @@ -16632,6 +16710,8 @@ maxconn than 50 concurrent requests. maxqueue + May be used in the following contexts: tcp, http + 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 @@ -16645,6 +16725,8 @@ maxqueue and "balance leastconn". max-reuse + May be used in the following contexts: http + The "max-reuse" argument indicates the HTTP connection processors that they should not reuse a server connection more than this number of times to send new requests. Permitted values are -1 (the default), which disables this @@ -16655,6 +16737,8 @@ max-reuse enforce. At least HTTP/2 connections to servers will respect it. minconn + May be used in the following contexts: tcp, http + 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 connections, never more than , and the limit will be on @@ -16665,12 +16749,16 @@ minconn and "maxqueue" parameters, as well as the "fullconn" backend keyword. namespace + May be used in the following contexts: tcp, http, log, peers, ring + On Linux, it is possible to specify which network namespace a socket will belong to. This directive makes it possible to explicitly bind a server to a namespace different from the default one. Please refer to your operating system's documentation to find more details about network namespaces. no-agent-check + May be used in the following contexts: tcp, http, log + This option may be used as "server" setting to reset any "agent-check" setting which would have been inherited from "default-server" directive as default value. @@ -16678,6 +16766,8 @@ no-agent-check "default-server" "agent-check" setting. no-backup + May be used in the following contexts: tcp, http, log + This option may be used as "server" setting to reset any "backup" setting which would have been inherited from "default-server" directive as default value. @@ -16685,6 +16775,8 @@ no-backup "default-server" "backup" setting. no-check + May be used in the following contexts: tcp, http, log + This option may be used as "server" setting to reset any "check" setting which would have been inherited from "default-server" directive as default value. @@ -16692,6 +16784,8 @@ no-check "default-server" "check" setting. no-check-ssl + May be used in the following contexts: tcp, http, log + This option may be used as "server" setting to reset any "check-ssl" setting which would have been inherited from "default-server" directive as default value. @@ -16699,6 +16793,8 @@ no-check-ssl "default-server" "check-ssl" setting. no-send-proxy + May be used in the following contexts: tcp, http + This option may be used as "server" setting to reset any "send-proxy" setting which would have been inherited from "default-server" directive as default value. @@ -16706,6 +16802,8 @@ no-send-proxy "default-server" "send-proxy" setting. no-send-proxy-v2 + May be used in the following contexts: tcp, http + This option may be used as "server" setting to reset any "send-proxy-v2" setting which would have been inherited from "default-server" directive as default value. @@ -16713,6 +16811,8 @@ no-send-proxy-v2 "default-server" "send-proxy-v2" setting. no-send-proxy-v2-ssl + May be used in the following contexts: tcp, http + This option may be used as "server" setting to reset any "send-proxy-v2-ssl" setting which would have been inherited from "default-server" directive as default value. @@ -16720,6 +16820,8 @@ no-send-proxy-v2-ssl "default-server" "send-proxy-v2-ssl" setting. no-send-proxy-v2-ssl-cn + May be used in the following contexts: tcp, http + This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn" setting which would have been inherited from "default-server" directive as default value. @@ -16727,6 +16829,8 @@ no-send-proxy-v2-ssl-cn "default-server" "send-proxy-v2-ssl-cn" setting. no-ssl + May be used in the following contexts: tcp, http, log, peers, ring + This option may be used as "server" setting to reset any "ssl" setting which would have been inherited from "default-server" directive as default value. @@ -16738,12 +16842,16 @@ no-ssl runtime API: see `set server` commands in management doc. no-ssl-reuse + May be used in the following contexts: tcp, http, log, peers, ring + This option disables SSL session reuse when SSL is used to communicate with the server. It will force the server to perform a full handshake for every new connection. It's probably only useful for benchmarking, troubleshooting, and for paranoid users. no-sslv3 + May be used in the following contexts: tcp, http, log, peers, ring + 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. Use "ssl-min-ver" and "ssl-max-ver" instead. @@ -16751,6 +16859,8 @@ no-sslv3 Supported in default-server: No no-tls-tickets + May be used in the following contexts: tcp, http, log, peers, ring + 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 @@ -16762,6 +16872,8 @@ no-tls-tickets See also "tls-tickets". no-tlsv10 + May be used in the following contexts: tcp, http, log, peers, ring + 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 @@ -16772,6 +16884,8 @@ no-tlsv10 Supported in default-server: No no-tlsv11 + May be used in the following contexts: tcp, http, log, peers, ring + 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 @@ -16782,6 +16896,8 @@ no-tlsv11 Supported in default-server: No no-tlsv12 + May be used in the following contexts: tcp, http, log, peers, ring + 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 @@ -16792,6 +16908,8 @@ no-tlsv12 Supported in default-server: No no-tlsv13 + May be used in the following contexts: tcp, http, log, peers, ring + This option disables support for TLSv1.3 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 @@ -16802,6 +16920,8 @@ no-tlsv13 Supported in default-server: No no-verifyhost + May be used in the following contexts: tcp, http, log, peers, ring + This option may be used as "server" setting to reset any "verifyhost" setting which would have been inherited from "default-server" directive as default value. @@ -16809,6 +16929,8 @@ no-verifyhost "default-server" "verifyhost" setting. no-tfo + May be used in the following contexts: tcp, http, log, peers, ring + This option may be used as "server" setting to reset any "tfo" setting which would have been inherited from "default-server" directive as default value. @@ -16816,11 +16938,15 @@ no-tfo "default-server" "tfo" setting. non-stick + May be used in the following contexts: tcp, http + 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. npn + May be used in the following contexts: tcp, http + 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). @@ -16830,6 +16956,8 @@ npn only available starting with OpenSSL 1.0.2. observe + May be used in the following contexts: tcp, http + 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 @@ -16841,6 +16969,8 @@ observe See also the "check", "on-error" and "error-limit". on-error + May be used in the following contexts: tcp, http, log + Select what should happen when enough consecutive errors are detected. Currently, four modes are available: - fastinter: force fastinter @@ -16852,6 +16982,8 @@ on-error See also the "check", "observe" and "error-limit". on-marked-down + May be used in the following contexts: tcp, http, log + Modify what occurs when a server is marked down. Currently one action is available: - shutdown-sessions: Shutdown peer streams. When this setting is enabled, @@ -16866,6 +16998,8 @@ on-marked-down Actions are disabled by default on-marked-up + May be used in the following contexts: tcp, http, log + Modify what occurs when a server is marked up. Currently one action is available: - shutdown-backup-sessions: Shutdown streams on all backup servers. This is @@ -16880,6 +17014,8 @@ on-marked-up Actions are disabled by default pool-low-conn + May be used in the following contexts: http + Set a low threshold on the number of idling connections for a server, below which a thread will not try to steal a connection from another thread. This can be useful to improve CPU usage patterns in scenarios involving many very @@ -16896,6 +17032,8 @@ pool-low-conn connection reuse rate will decrease as thread count increases. pool-max-conn + May be used in the following contexts: http + Set the maximum number of idling connections for a server. -1 means unlimited connections, 0 means no idle connections. The default is -1. When idle connections are enabled, orphaned idle connections which do not belong to any @@ -16904,11 +17042,15 @@ pool-max-conn according to the same principles as those applying to "http-reuse". pool-purge-delay + May be used in the following contexts: http + Sets the delay to start purging idle connections. Each interval, half of the idle connections are closed. 0 means we don't keep any idle connection. The default is 5s. port + May be used in the following contexts: tcp, http, log + Using the "port" parameter, it becomes possible to use a different port to send health-checks or to probe the agent-check. On some servers, it may be desirable to dedicate a port to a specific component able to perform complex @@ -16917,6 +17059,8 @@ port ignored if the "check" parameter is not set. See also the "addr" parameter. proto + May be used in the following contexts: tcp, http + Forces the multiplexer's protocol to use for the outgoing connections to this server. It must be compatible with the mode of the backend (TCP or HTTP). It must also be usable on the backend side. The list of available protocols is @@ -16941,6 +17085,8 @@ proto See also "ws" to use an alternative protocol for websocket streams. redir + May be used in the following contexts: http + 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 @@ -16959,11 +17105,15 @@ redir Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check rise + May be used in the following contexts: tcp, http, log + The "rise" parameter states that a server will be considered as operational after consecutive successful health checks. This value defaults to 2 if unspecified. See also the "check", "inter" and "fall" parameters. resolve-opts