From ddfc40eabdbc59a607b568e946fb116dcd3439fd Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 14:20:30 +0200 Subject: Adding upstream version 2.9.7. Signed-off-by: Daniel Baumann --- doc/configuration.txt | 111 ++++++++++++++++++++++++++++++++++++++++++++++---- doc/lua-api/index.rst | 13 ++++-- doc/management.txt | 1 + 3 files changed, 115 insertions(+), 10 deletions(-) (limited to 'doc') 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 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 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 + 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 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 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 + 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 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 [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 / [, ...] [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 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 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 diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst index e8df63e..17927f3 100644 --- a/doc/lua-api/index.rst +++ b/doc/lua-api/index.rst @@ -159,6 +159,13 @@ Core class The "core" class is static, it is not possible to create a new object of this type. +.. js:attribute:: core.silent + + :returns: integer + + This attribute is an integer, it contains the value -1. It is a special value + used to disable logging. + .. js:attribute:: core.emerg :returns: integer @@ -2873,12 +2880,12 @@ TXN class .. js:function:: TXN.set_loglevel(txn, loglevel) Is used to change the log level of the current request. The "loglevel" must - be an integer between 0 and 7. + be an integer between 0 and 7 or the special value -1 to disable logging. :param class_txn txn: The class txn object containing the data. :param integer loglevel: The required log level. This variable can be one of - :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`, - :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`, + :see: :js:attr:`core.silent`, :js:attr:`core.emerg`, :js:attr:`core.alert`, + :js:attr:`core.crit`, :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`, :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions) .. js:function:: TXN.set_tos(txn, tos) diff --git a/doc/management.txt b/doc/management.txt index b1789db..9cbc772 100644 --- a/doc/management.txt +++ b/doc/management.txt @@ -1687,6 +1687,7 @@ add server / [args]* - check-via-socks4 - ciphers - ciphersuites + - cookie - crl-file - crt - disabled -- cgit v1.2.3