From 002073ef57d9b5bcc369ac074e487d2306adef3c Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Tue, 31 Aug 2021 19:21:15 +0900 Subject: [PATCH] Update manual pages --- doc/h2load.1 | 37 +++++++++++-- doc/h2load.1.rst | 31 ++++++++++- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 129 +++++++++++++++++++++++++++++++++++++++++----- doc/nghttpx.1.rst | 119 +++++++++++++++++++++++++++++++++++++----- 6 files changed, 288 insertions(+), 32 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index 7dd7f630..eb8d7b43 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "Jul 18, 2021" "1.45.0-DEV" "nghttp2" +.TH "H2LOAD" "1" "Aug 31, 2021" "1.45.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . @@ -101,6 +101,7 @@ Default: \fB1\fP .TP .B \-w, \-\-window\-bits= Sets the stream level initial window size to (2**)\-1. +For QUIC, is capped to 26 (roughly 64MiB). .sp Default: \fB30\fP .UNINDENT @@ -120,13 +121,21 @@ Add/Override a header to the requests. .INDENT 0.0 .TP .B \-\-ciphers= -Set allowed cipher list. The format of the string is -described in OpenSSL ciphers(1). +Set allowed cipher list for TLSv1.2 or ealier. The +format of the string is described in OpenSSL ciphers(1). .sp Default: \fBECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-SHA384:ECDHE\-RSA\-AES256\-SHA384:ECDHE\-ECDSA\-AES128\-SHA256:ECDHE\-RSA\-AES128\-SHA256\fP .UNINDENT .INDENT 0.0 .TP +.B \-\-tls13\-ciphers= +Set allowed cipher list for TLSv1.3. The format of the +string is described in OpenSSL ciphers(1). +.sp +Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256\fP +.UNINDENT +.INDENT 0.0 +.TP .B \-p, \-\-no\-tls\-proto= Specify ALPN identifier of the protocol to be used when accessing http URI without SSL/TLS. @@ -285,6 +294,16 @@ to buffering. Status code is \-1 for failed streams. .UNINDENT .INDENT 0.0 .TP +.B \-\-qlog\-file\-base= +Enable qlog output and specify base file name for qlogs. +Qlog is emitted for each connection. +For a given base name "base", each output file name +becomes "base.M.N.qlog" where M is worker ID and N is +client ID (e.g. "base.0.3.qlog"). +Only effective in QUIC runs. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-connect\-to=[:] Host and port to connect instead of using the authority in . @@ -297,6 +316,18 @@ Specify request per second for each client. \fI\%\-\-rps\fP and .UNINDENT .INDENT 0.0 .TP +.B \-\-groups= +Specify the supported groups. +.sp +Default: \fBX25519:P\-256:P\-384:P\-521\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-udp\-gso +Disable UDP GSO. +.UNINDENT +.INDENT 0.0 +.TP .B \-v, \-\-verbose Output debug information. .UNINDENT diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst index 24036c6a..c4e733f2 100644 --- a/doc/h2load.1.rst +++ b/doc/h2load.1.rst @@ -76,6 +76,7 @@ OPTIONS .. option:: -w, --window-bits= Sets the stream level initial window size to (2\*\*)-1. + For QUIC, is capped to 26 (roughly 64MiB). Default: ``30`` @@ -92,11 +93,18 @@ OPTIONS .. option:: --ciphers= - Set allowed cipher list. The format of the string is - described in OpenSSL ciphers(1). + Set allowed cipher list for TLSv1.2 or ealier. The + format of the string is described in OpenSSL ciphers(1). Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256`` +.. option:: --tls13-ciphers= + + Set allowed cipher list for TLSv1.3. The format of the + string is described in OpenSSL ciphers(1). + + Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256`` + .. option:: -p, --no-tls-proto= Specify ALPN identifier of the protocol to be used when @@ -240,6 +248,15 @@ OPTIONS appear slightly out of order with multiple threads due to buffering. Status code is -1 for failed streams. +.. option:: --qlog-file-base= + + Enable qlog output and specify base file name for qlogs. + Qlog is emitted for each connection. + For a given base name "base", each output file name + becomes "base.M.N.qlog" where M is worker ID and N is + client ID (e.g. "base.0.3.qlog"). + Only effective in QUIC runs. + .. option:: --connect-to=[:] Host and port to connect instead of using the authority @@ -250,6 +267,16 @@ OPTIONS Specify request per second for each client. :option:`--rps` and :option:`--timing-script-file` are mutually exclusive. +.. option:: --groups= + + Specify the supported groups. + + Default: ``X25519:P-256:P-384:P-521`` + +.. option:: --no-udp-gso + + Disable UDP GSO. + .. option:: -v, --verbose Output debug information. diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 14e04fa5..72f579b8 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "Jul 18, 2021" "1.45.0-DEV" "nghttp2" +.TH "NGHTTP" "1" "Aug 31, 2021" "1.45.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index f1e1093a..9a4efc7b 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "Jul 18, 2021" "1.45.0-DEV" "nghttp2" +.TH "NGHTTPD" "1" "Aug 31, 2021" "1.45.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 42191ec2..2be0a35b 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "Jul 18, 2021" "1.45.0-DEV" "nghttp2" +.TH "NGHTTPX" "1" "Aug 31, 2021" "1.45.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -140,12 +140,13 @@ parameters are: "proto=", "tls", "affinity=", "dns", "redirect\-if\-not\-tls", "upgrade\-scheme", "mruby=", "read\-timeout=", "write\-timeout=", -"group=", "group\-weight=", and "weight=". -The parameter consists of keyword, and optionally -followed by "=" and value. For example, the parameter -"proto=h2" consists of the keyword "proto" and value -"h2". The parameter "tls" consists of the keyword "tls" -without value. Each parameter is described as follows. +"group=", "group\-weight=", "weight=", and +"dnf". The parameter consists of keyword, and +optionally followed by "=" and value. For example, the +parameter "proto=h2" consists of the keyword "proto" and +value "h2". The parameter "tls" consists of the keyword +"tls" without value. Each parameter is described as +follows. .sp The backend application protocol can be specified using optional "proto" parameter, and in the form of @@ -276,6 +277,13 @@ weight than weight 2. If this parameter is omitted, weight becomes 1. "weight" is ignored if session affinity is enabled. .sp +If "dnf" parameter is specified, an incoming request is +not forwarded to a backend and just consumed along with +the request body (actually a backend server never be +contacted). It is expected that the HTTP response is +generated by mruby script (see "mruby=" parameter +above). "dnf" is an abbreviation of "do not forward". +.sp Since ";" and ":" are used as delimiter, must not contain these characters. In order to include ":" in , one has to specify "%3A" (which is @@ -323,6 +331,12 @@ To accept PROXY protocol version 1 and 2 on frontend connection, specify "proxyproto" parameter. This is disabled by default. .sp +To receive HTTP/3 (QUIC) traffic, specify "quic" +parameter. It makes nghttpx listen on UDP port rather +than TCP port. UNIX domain socket, "api", and +"healthmon" parameters cannot be used with "quic" +parameter. +.sp Default: \fB*,3000\fP .UNINDENT .INDENT 0.0 @@ -528,6 +542,13 @@ Default: \fB3m\fP .UNINDENT .INDENT 0.0 .TP +.B \-\-frontend\-http3\-read\-timeout= +Specify read timeout for HTTP/3 frontend connection. +.sp +Default: \fB3m\fP +.UNINDENT +.INDENT 0.0 +.TP .B \-\-frontend\-read\-timeout= Specify read timeout for HTTP/1.1 frontend connection. .sp @@ -1478,13 +1499,21 @@ not be altered regardless of this option. .UNINDENT .INDENT 0.0 .TP -.B \-\-altsvc= +.B \-\-altsvc= Specify protocol ID, port, host and origin of -alternative service. and are optional. -They are advertised in alt\-svc header field only in -HTTP/1.1 frontend. This option can be used multiple -times to specify multiple alternative services. -Example: \fI\%\-\-altsvc\fP=h2,443 +alternative service. , and are +optional. Empty and are allowed and +they are treated as nothing is specified. They are +advertised in alt\-svc header field only in HTTP/1.1 +frontend. This option can be used multiple times to +specify multiple alternative services. +Example: \fI\%\-\-altsvc\fP="h2,443,,,ma=3600; persist=1\(aq +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-http2\-altsvc= +Just like \fI\%\-\-altsvc\fP option, but this altsvc is only sent +in HTTP/2 frontend. .UNINDENT .INDENT 0.0 .TP @@ -1688,6 +1717,80 @@ Ignore mruby compile error for per\-pattern mruby script file. If error occurred, it is treated as if no mruby file were specified for the pattern. .UNINDENT +.SS HTTP/3 and QUIC +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-idle\-timeout= +Specify an idle timeout for QUIC connection. +.sp +Default: \fB30s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-debug\-log +Output QUIC debug log to \fI/dev/stderr.\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-quic\-bpf\-program\-file= +Specify a path to eBPF program file reuseport_kern.o to +direct an incoming QUIC UDP datagram to a correct +socket. +.sp +Default: \fB/usr/local/lib/nghttp2/reuseport_kern.o\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-quic\-bpf +Disable eBPF. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-window\-size= +Sets the per\-stream initial window size of HTTP/3 +frontend connection. +.sp +Default: \fB256K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-connection\-window\-size= +Sets the per\-connection window size of HTTP/3 frontend +connection. +.sp +Default: \fB1M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-max\-window\-size= +Sets the maximum per\-stream window size of HTTP/3 +frontend connection. The window size is adjusted based +on the receiving rate of stream data. The initial value +is the value specified by \fI\%\-\-frontend\-http3\-window\-size\fP +and the window size grows up to bytes. +.sp +Default: \fB6M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-max\-connection\-window\-size= +Sets the maximum per\-connection window size of HTTP/3 +frontend connection. The window size is adjusted based +on the receiving rate of stream data. The initial value +is the value specified by +\fI\%\-\-frontend\-http3\-connection\-window\-size\fP and the window +size grows up to bytes. +.sp +Default: \fB8M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-max\-concurrent\-streams= +Set the maximum number of the concurrent streams in one +frontend HTTP/3 connection. +.sp +Default: \fB100\fP +.UNINDENT .SS Misc .INDENT 0.0 .TP diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index 50df24f3..fb4a0a92 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -124,12 +124,13 @@ Connections "affinity=", "dns", "redirect-if-not-tls", "upgrade-scheme", "mruby=", "read-timeout=", "write-timeout=", - "group=", "group-weight=", and "weight=". - The parameter consists of keyword, and optionally - followed by "=" and value. For example, the parameter - "proto=h2" consists of the keyword "proto" and value - "h2". The parameter "tls" consists of the keyword "tls" - without value. Each parameter is described as follows. + "group=", "group-weight=", "weight=", and + "dnf". The parameter consists of keyword, and + optionally followed by "=" and value. For example, the + parameter "proto=h2" consists of the keyword "proto" and + value "h2". The parameter "tls" consists of the keyword + "tls" without value. Each parameter is described as + follows. The backend application protocol can be specified using optional "proto" parameter, and in the form of @@ -260,6 +261,13 @@ Connections weight becomes 1. "weight" is ignored if session affinity is enabled. + If "dnf" parameter is specified, an incoming request is + not forwarded to a backend and just consumed along with + the request body (actually a backend server never be + contacted). It is expected that the HTTP response is + generated by mruby script (see "mruby=" parameter + above). "dnf" is an abbreviation of "do not forward". + Since ";" and ":" are used as delimiter, must not contain these characters. In order to include ":" in , one has to specify "%3A" (which is @@ -307,6 +315,12 @@ Connections connection, specify "proxyproto" parameter. This is disabled by default. + To receive HTTP/3 (QUIC) traffic, specify "quic" + parameter. It makes nghttpx listen on UDP port rather + than TCP port. UNIX domain socket, "api", and + "healthmon" parameters cannot be used with "quic" + parameter. + Default: ``*,3000`` @@ -495,6 +509,12 @@ Timeout Default: ``3m`` +.. option:: --frontend-http3-read-timeout= + + Specify read timeout for HTTP/3 frontend connection. + + Default: ``3m`` + .. option:: --frontend-read-timeout= Specify read timeout for HTTP/1.1 frontend connection. @@ -1338,14 +1358,21 @@ HTTP mode. When :option:`--http2-proxy` is used, these headers will not be altered regardless of this option. -.. option:: --altsvc= +.. option:: --altsvc= Specify protocol ID, port, host and origin of - alternative service. and are optional. - They are advertised in alt-svc header field only in - HTTP/1.1 frontend. This option can be used multiple - times to specify multiple alternative services. - Example: :option:`--altsvc`\=h2,443 + alternative service. , and are + optional. Empty and are allowed and + they are treated as nothing is specified. They are + advertised in alt-svc header field only in HTTP/1.1 + frontend. This option can be used multiple times to + specify multiple alternative services. + Example: :option:`--altsvc`\="h2,443,,,ma=3600; persist=1' + +.. option:: --http2-altsvc= + + Just like :option:`--altsvc` option, but this altsvc is only sent + in HTTP/2 frontend. .. option:: --add-request-header=
@@ -1541,6 +1568,74 @@ Scripting file were specified for the pattern. +HTTP/3 and QUIC +~~~~~~~~~~~~~~~ + +.. option:: --frontend-quic-idle-timeout= + + Specify an idle timeout for QUIC connection. + + Default: ``30s`` + +.. option:: --frontend-quic-debug-log + + Output QUIC debug log to */dev/stderr.* + +.. option:: --quic-bpf-program-file= + + Specify a path to eBPF program file reuseport_kern.o to + direct an incoming QUIC UDP datagram to a correct + socket. + + Default: ``/usr/local/lib/nghttp2/reuseport_kern.o`` + +.. option:: --no-quic-bpf + + Disable eBPF. + +.. option:: --frontend-http3-window-size= + + Sets the per-stream initial window size of HTTP/3 + frontend connection. + + Default: ``256K`` + +.. option:: --frontend-http3-connection-window-size= + + Sets the per-connection window size of HTTP/3 frontend + connection. + + Default: ``1M`` + +.. option:: --frontend-http3-max-window-size= + + Sets the maximum per-stream window size of HTTP/3 + frontend connection. The window size is adjusted based + on the receiving rate of stream data. The initial value + is the value specified by :option:`--frontend-http3-window-size` + and the window size grows up to bytes. + + Default: ``6M`` + +.. option:: --frontend-http3-max-connection-window-size= + + Sets the maximum per-connection window size of HTTP/3 + frontend connection. The window size is adjusted based + on the receiving rate of stream data. The initial value + is the value specified by + :option:`--frontend-http3-connection-window-size` and the window + size grows up to bytes. + + Default: ``8M`` + +.. option:: --frontend-http3-max-concurrent-streams= + + Set the maximum number of the concurrent streams in one + frontend HTTP/3 connection. + + Default: ``100`` + + Misc ~~~~