diff options
Diffstat (limited to 'doc/configuration.txt')
| -rw-r--r-- | doc/configuration.txt | 111 |
1 files changed, 104 insertions, 7 deletions
diff --git a/doc/configuration.txt b/doc/configuration.txt index 978d655..e1c5034 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -3,7 +3,7 @@ Configuration Manual ---------------------- version 2.9 - 2024/02/26 + 2024/04/05 This document covers the configuration language as implemented in the version @@ -1325,8 +1325,10 @@ The following keywords are supported in the "global" section : - tune.fd.edge-triggered - tune.h1.zero-copy-fwd-recv - tune.h1.zero-copy-fwd-send + - tune.h2.be.glitches-threshold - tune.h2.be.initial-window-size - tune.h2.be.max-concurrent-streams + - tune.h2.fe.glitches-threshold - tune.h2.fe.initial-window-size - tune.h2.fe.max-concurrent-streams - tune.h2.fe.max-total-streams @@ -1362,6 +1364,7 @@ The following keywords are supported in the "global" section : - tune.quic.frontend.max-idle-timeout - tune.quic.frontend.max-streams-bidi - tune.quic.max-frame-loss + - tune.quic.reorder-ratio - tune.quic.retry-threshold - tune.quic.socket-owner - tune.quic.zero-copy-fwd-send @@ -2228,8 +2231,26 @@ ssl-default-bind-ciphersuites <ciphersuites> theirs. The format of the string is defined in "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For cipher configuration for TLSv1.2 and earlier, please check the - "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more - information. + "ssl-default-bind-ciphers" keyword. This setting might accept TLSv1.2 + ciphersuites however this is an undocumented behavior and not recommended as + it could be inconsistent or buggy. + The default TLSv1.3 ciphersuites of OpenSSL are: + "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" + + TLSv1.3 only supports 5 ciphersuites: + + - TLS_AES_128_GCM_SHA256 + - TLS_AES_256_GCM_SHA384 + - TLS_CHACHA20_POLY1305_SHA256 + - TLS_AES_128_CCM_SHA256 + - TLS_AES_128_CCM_8_SHA256 + + Please check the "bind" keyword for more information. + + Example: + global + ssl-default-bind-ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256 + ssl-default-bind-ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 ssl-default-bind-client-sigalgs <sigalgs> This setting is only available when support for OpenSSL was built in. It sets @@ -3056,6 +3077,18 @@ tune.h1.zero-copy-fwd-send { on | off } See also: tune.disable-zero-copy-forwarding, tune.h1.zero-copy-fwd-recv +tune.h2.be.glitches-threshold <number> + Sets the threshold for the number of glitches on a backend connection, where + that connection will automatically be killed. This allows to automatically + kill misbehaving connections without having to write explicit rules for them. + The default value is zero, indicating that no threshold is set so that no + event will cause a connection to be closed. Beware that some H2 servers may + occasionally cause a few glitches over long lasting connection, so any non- + zero value here should probably be in the hundreds or thousands to be + effective without affecting slightly bogus servers. + + See also: tune.h2.fe.glitches-threshold, bc_glitches + tune.h2.be.initial-window-size <number> Sets the HTTP/2 initial window size for outgoing connections, which is the number of bytes the server can respond before waiting for an acknowledgment @@ -3081,6 +3114,18 @@ tune.h2.be.max-concurrent-streams <number> case). It is highly recommended not to increase this value; some might find it optimal to run at low values (1..5 typically). +tune.h2.fe.glitches-threshold <number> + Sets the threshold for the number of glitches on a frontend connection, where + that connection will automatically be killed. This allows to automatically + kill misbehaving connections without having to write explicit rules for them. + The default value is zero, indicating that no threshold is set so that no + event will cause a connection to be closed. Beware that some H2 clientss may + occasionally cause a few glitches over long lasting connection, so any non- + zero value here should probably be in the hundreds or thousands to be + effective without affecting slightly bogus clients. + + See also: tune.h2.be.glitches-threshold, fc_glitches + tune.h2.fe.initial-window-size <number> Sets the HTTP/2 initial window size for incoming connections, which is the number of bytes the client can upload before waiting for an acknowledgment @@ -5014,6 +5059,7 @@ balance url_param <param> [check_post] them off when unused, and regularly checks backend queue to turn new servers on when the queue inflates. Alternatively, using "http-check send-state" may inform servers on the load. + This algorithm is not usable in LOG mode. hash Takes a regular sample expression in argument. The expression is evaluated for each request and hashed according to the @@ -5296,10 +5342,12 @@ bind /<path> [, ...] [param*] listen on. If unset, all IPv4 addresses of the system will be listened on. The same will apply for '*' or the system's special address "0.0.0.0". The IPv6 equivalent is '::'. Note - that if you bind a frontend to multiple UDP addresses you have - no guarantee about the address which will be used to respond. - This is why "0.0.0.0" addresses and lists of comma-separated - IP addresses have been forbidden to bind QUIC addresses. + that for UDP, specific OS features are required when binding + on multiple addresses to ensure the correct network interface + and source address will be used on response. In other way, + for QUIC listeners only bind on multiple addresses if running + with a modern enough systems. + Optionally, an address family prefix may be used before the address to force the family regardless of the address format, which can be useful to specify a path to a unix socket with @@ -15370,6 +15418,22 @@ ciphersuites <ciphersuites> TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section. For cipher configuration for TLSv1.2 and earlier, please check the "ciphers" keyword. + This setting might accept TLSv1.2 ciphersuites however this is an + undocumented behavior and not recommended as it could be inconsistent or buggy. + The default TLSv1.3 ciphersuites of OpenSSL are: + "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" + + TLSv1.3 only supports 5 ciphersuites: + + - TLS_AES_128_GCM_SHA256 + - TLS_AES_256_GCM_SHA384 + - TLS_CHACHA20_POLY1305_SHA256 + - TLS_AES_128_CCM_SHA256 + - TLS_AES_128_CCM_8_SHA256 + + Example: + ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256 + ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 client-sigalgs <sigalgs> This setting is only available when support for OpenSSL was built in. It sets @@ -20670,6 +20734,7 @@ bc_dst ip bc_dst_port integer bc_err integer bc_err_str string +bc_glitches integer bc_http_major integer bc_src ip bc_src_port integer @@ -20696,6 +20761,7 @@ fc_dst_port integer fc_err integer fc_err_str string fc_fackets integer +fc_glitches integer fc_http_major integer fc_lost integer fc_pp_authority string @@ -20910,6 +20976,20 @@ bc_err_str : string "fc_err_str" fetch for a full list of error codes and their corresponding error message. +bc_glitches : integer + Returns the number of protocol glitches counted on the backend connection. + These generally cover protocol violations as well as small anomalies that + generally indicate a bogus or misbehaving server that may cause trouble in + the infrastructure (e.g. cause connections to be aborted early, inducing + frequent TLS renegotiations). These may also be caused by too large responses + that cannot fit into a single buffer, explaining HTTP 502 errors. Ideally + this number should remain zero, though it's generally fine if it remains very + low compared to the total number of requests. These values should normally + not be considered as alarming (especially small ones), though a sudden jump + may indicate an anomaly somewhere. Not all protocol multiplexers measure this + metric and the only way to get more details about the events is to enable + traces to capture all exchanges. + bc_http_major : integer Returns the backend connection's HTTP major version encoding, which may be 1 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire @@ -21121,6 +21201,23 @@ fc_fackets : integer not TCP or if the operating system does not support TCP_INFO, for example Linux kernels before 2.4, the sample fetch fails. +fc_glitches : integer + Returns the number of protocol glitches counted on the frontend connection. + These generally cover protocol violations as well as small anomalies that + generally indicate a bogus or misbehaving client that may cause trouble in + the infrastructure, such as excess of errors in the logs, or many connections + being aborted early, inducing frequent TLS renegotiations. These may also be + caused by too large requests that cannot fit into a single buffer, explaining + HTTP 400 errors. Ideally this number should remain zero, though it may be + possible that some browsers playing with the protocol boundaries trigger it + once in a while. These values should normally not be considered as alarming + (especially small ones), though a sudden jump may indicate an anomaly + somewhere. Large values (i.e. hundreds to thousands per connection, or as + many as the requests) may indicate a purposely built client that is trying to + fingerprint or attack the protocol stack. Not all protocol multiplexers + measure this metric, and the only way to get more details about the events is + to enable traces to capture all exchanges. + fc_http_major : integer Reports the front connection's HTTP major version encoding, which may be 1 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire |