From 79ae5aed673df298ad3f3d36d097dcf2de8693e6 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Tue, 14 Feb 2017 22:35:54 +0900 Subject: [PATCH] Update man pages --- doc/h2load.1 | 2 +- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 113 ++++++++++++++++++++++++++++++++-------------- doc/nghttpx.1.rst | 104 +++++++++++++++++++++++++++++------------- 5 files changed, 156 insertions(+), 67 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index 02e65b40..8076a058 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "Jan 25, 2017" "1.19.0" "nghttp2" +.TH "H2LOAD" "1" "Feb 14, 2017" "1.20.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 71e401d6..4d022aed 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "Jan 25, 2017" "1.19.0" "nghttp2" +.TH "NGHTTP" "1" "Feb 14, 2017" "1.20.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 7d79782b..f21ffd36 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "Jan 25, 2017" "1.19.0" "nghttp2" +.TH "NGHTTPD" "1" "Feb 14, 2017" "1.20.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index bcd1d5d7..bee66bd5 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "Jan 25, 2017" "1.19.0" "nghttp2" +.TH "NGHTTPX" "1" "Feb 14, 2017" "1.20.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -121,12 +121,12 @@ Several parameters are accepted after . The parameters are delimited by ";". The available parameters are: "proto=", "tls", "sni=", "fall=", "rise=", -"affinity=", and "dns". 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. +"affinity=", "dns", and "frontend\-tls". 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 @@ -183,6 +183,17 @@ frequently. If "dns" is given, name resolution of backend host name at start up, or reloading configuration is skipped. .sp +If "frontend\-tls" parameter is used, the matched backend +requires frontend TLS connection. In other words, even +if pattern is matched, frontend connection is not TLS +protected, the request is forwarded to one of catch\-all +backends. For this reason, catch\-all backend cannot +have "frontend\-tls" parameter. If at least one backend +has "frontend\-tls" parameter, this feature is enabled +for all backend servers sharing the same . It +is advised to set "frontend\-tls" parameter to all +backends explicitly if this feature is desired. +.sp Since ";" and ":" are used as delimiter, must not contain these characters. Since ";" has special meaning in shell, the option value must be quoted. @@ -579,9 +590,14 @@ password protected it\(aqll be requested interactively. .B \-\-subcert=:[[;]...] Specify additional certificate and private key file. nghttpx will choose certificates based on the hostname -indicated by client using TLS SNI extension. This -option can be used multiple times. To make OCSP -stapling work, must be absolute path. +indicated by client using TLS SNI extension. If nghttpx +is built with OpenSSL >= 1.0.2, signature algorithms +(e.g., ECDSA+SHA256, RSA+SHA256) presented by client are +also taken into consideration. This allows nghttpx to +send ECDSA certificate to modern clients, while sending +RSA based certificate to older clients. This option can +be used multiple times. To make OCSP stapling work, + must be absolute path. .sp Additional parameter can be specified in . The available is "sct\-dir=". @@ -637,18 +653,29 @@ backend client authentication. .UNINDENT .INDENT 0.0 .TP -.B \-\-tls\-proto\-list= -Comma delimited list of SSL/TLS protocol to be enabled. -The following protocols are available: TLSv1.2, TLSv1.1 -and TLSv1.0. The name matching is done in -case\-insensitive manner. The parameter must be -delimited by a single comma only and any white spaces -are treated as a part of protocol string. If the -protocol list advertised by client does not overlap this -list, you will receive the error message "unknown -protocol". +.B \-\-tls\-min\-proto\-version= +Specify minimum SSL/TLS protocol. The following +protocols are available: TLSv1.2, TLSv1.1 and TLSv1.0. +The name matching is done in case\-insensitive manner. +The versions between \fI\%\-\-tls\-min\-proto\-version\fP and +\fI\%\-\-tls\-max\-proto\-version\fP are enabled. If the protocol +list advertised by client does not overlap this range, +you will receive the error message "unknown protocol". .sp -Default: \fBTLSv1.2,TLSv1.1\fP +Default: \fBTLSv1.1\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-max\-proto\-version= +Specify maximum SSL/TLS protocol. The following +protocols are available: TLSv1.2, TLSv1.1 and TLSv1.0. +The name matching is done in case\-insensitive manner. +The versions between \fI\%\-\-tls\-min\-proto\-version\fP and +\fI\%\-\-tls\-max\-proto\-version\fP are enabled. If the protocol +list advertised by client does not overlap this range, +you will receive the error message "unknown protocol". +.sp +Default: \fBTLSv1.2\fP .UNINDENT .INDENT 0.0 .TP @@ -1313,7 +1340,7 @@ backend server, the custom error pages are not used. .B \-\-server\-name= Change server response header field value to . .sp -Default: \fBnghttpx nghttp2/1.19.0\fP +Default: \fBnghttpx nghttp2/1.20.0\-DEV\fP .UNINDENT .INDENT 0.0 .TP @@ -1538,16 +1565,23 @@ Reload configuration file given in \fI\%\-\-conf\fP\&. .TP .B SIGUSR1 Reopen log files. -.TP -.B SIGUSR2 +.UNINDENT +.sp +SIGUSR2 +.INDENT 0.0 +.INDENT 3.5 Fork and execute nghttpx. It will execute the binary in the same -path with same command\-line arguments and environment variables. -After new process comes up, sending SIGQUIT to the original process -to perform hot swapping. The difference between SIGUSR2 + SIGQUIT -and SIGHUP is that former is usually used to execute new binary, and -the master process is newly spawned. On the other hand, the latter -just reloads configuration file, and the same master process -continues to exist. +path with same command\-line arguments and environment variables. As +of nghttpx version 1.20.0, the new master process sends SIGQUIT to +the original master process when it is ready to serve requests. For +the earlier versions of nghttpx, user has to send SIGQUIT to the +original master process. +.sp +The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former +is usually used to execute new binary, and the master process is +newly spawned. On the other hand, the latter just reloads +configuration file, and the same master process continues to exist. +.UNINDENT .UNINDENT .sp \fBNOTE:\fP @@ -1968,6 +2002,19 @@ completely custom header fields, first call existing header fields, and then add required header fields. It is an error to call this method twice for a given request. .UNINDENT +.INDENT 7.0 +.TP +.B send_info(status, headers) +Send non\-final (informational) response to a client. \fIstatus\fP +must be in the range [100, 199], inclusive. \fIheaders\fP is a +hash containing response header fields. Its key must be a +string, and the associated value must be either string or +array of strings. Since this is not a final response, even if +this method is invoked, request is still forwarded to a +backend unless \fI\%Nghttpx::Response#return\fP is called. +This method can be called multiple times. It cannot be called +after \fI\%Nghttpx::Response#return\fP is called. +.UNINDENT .UNINDENT .SS MRUBY EXAMPLES .sp @@ -2048,10 +2095,10 @@ some cases where the error has occurred before reaching API endpoint (e.g., header field is too large). .sp The following section describes available API endpoints. -.SS PUT /api/v1beta1/backendconfig +.SS POST /api/v1beta1/backendconfig .sp This API replaces the current backend server settings with the -requested ones. The request method should be PUT, but POST is also +requested ones. The request method should be POST, but PUT is also acceptable. The request body must be nghttpx configuration file format. For configuration file format, see \fI\%FILES\fP section. The line separator inside the request body must be single LF (0x0A). diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index 5e7ad45f..cf1b541f 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -105,12 +105,12 @@ Connections The parameters are delimited by ";". The available parameters are: "proto=", "tls", "sni=", "fall=", "rise=", - "affinity=", and "dns". 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. + "affinity=", "dns", and "frontend-tls". 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 @@ -167,6 +167,17 @@ Connections backend host name at start up, or reloading configuration is skipped. + If "frontend-tls" parameter is used, the matched backend + requires frontend TLS connection. In other words, even + if pattern is matched, frontend connection is not TLS + protected, the request is forwarded to one of catch-all + backends. For this reason, catch-all backend cannot + have "frontend-tls" parameter. If at least one backend + has "frontend-tls" parameter, this feature is enabled + for all backend servers sharing the same . It + is advised to set "frontend-tls" parameter to all + backends explicitly if this feature is desired. + Since ";" and ":" are used as delimiter, must not contain these characters. Since ";" has special meaning in shell, the option value must be quoted. @@ -532,9 +543,14 @@ SSL/TLS Specify additional certificate and private key file. nghttpx will choose certificates based on the hostname - indicated by client using TLS SNI extension. This - option can be used multiple times. To make OCSP - stapling work, must be absolute path. + indicated by client using TLS SNI extension. If nghttpx + is built with OpenSSL >= 1.0.2, signature algorithms + (e.g., ECDSA+SHA256, RSA+SHA256) presented by client are + also taken into consideration. This allows nghttpx to + send ECDSA certificate to modern clients, while sending + RSA based certificate to older clients. This option can + be used multiple times. To make OCSP stapling work, + must be absolute path. Additional parameter can be specified in . The available is "sct-dir=". @@ -582,19 +598,29 @@ SSL/TLS Path to file that contains client certificate used in backend client authentication. -.. option:: --tls-proto-list= +.. option:: --tls-min-proto-version= - Comma delimited list of SSL/TLS protocol to be enabled. - The following protocols are available: TLSv1.2, TLSv1.1 - and TLSv1.0. The name matching is done in - case-insensitive manner. The parameter must be - delimited by a single comma only and any white spaces - are treated as a part of protocol string. If the - protocol list advertised by client does not overlap this - list, you will receive the error message "unknown - protocol". + Specify minimum SSL/TLS protocol. The following + protocols are available: TLSv1.2, TLSv1.1 and TLSv1.0. + The name matching is done in case-insensitive manner. + The versions between :option:`--tls-min-proto-version` and + :option:`--tls-max-proto-version` are enabled. If the protocol + list advertised by client does not overlap this range, + you will receive the error message "unknown protocol". - Default: ``TLSv1.2,TLSv1.1`` + Default: ``TLSv1.1`` + +.. option:: --tls-max-proto-version= + + Specify maximum SSL/TLS protocol. The following + protocols are available: TLSv1.2, TLSv1.1 and TLSv1.0. + The name matching is done in case-insensitive manner. + The versions between :option:`--tls-min-proto-version` and + :option:`--tls-max-proto-version` are enabled. If the protocol + list advertised by client does not overlap this range, + you will receive the error message "unknown protocol". + + Default: ``TLSv1.2`` .. option:: --tls-ticket-key-file= @@ -1188,7 +1214,7 @@ HTTP Change server response header field value to . - Default: ``nghttpx nghttp2/1.19.0`` + Default: ``nghttpx nghttp2/1.20.0-DEV`` .. option:: --no-server-rewrite @@ -1405,14 +1431,18 @@ SIGUSR1 Reopen log files. SIGUSR2 + Fork and execute nghttpx. It will execute the binary in the same - path with same command-line arguments and environment variables. - After new process comes up, sending SIGQUIT to the original process - to perform hot swapping. The difference between SIGUSR2 + SIGQUIT - and SIGHUP is that former is usually used to execute new binary, and - the master process is newly spawned. On the other hand, the latter - just reloads configuration file, and the same master process - continues to exist. + path with same command-line arguments and environment variables. As + of nghttpx version 1.20.0, the new master process sends SIGQUIT to + the original master process when it is ready to serve requests. For + the earlier versions of nghttpx, user has to send SIGQUIT to the + original master process. + + The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former + is usually used to execute new binary, and the master process is + newly spawned. On the other hand, the latter just reloads + configuration file, and the same master process continues to exist. .. note:: @@ -1804,6 +1834,18 @@ respectively. existing header fields, and then add required header fields. It is an error to call this method twice for a given request. + .. rb:method:: send_info(status, headers) + + Send non-final (informational) response to a client. *status* + must be in the range [100, 199], inclusive. *headers* is a + hash containing response header fields. Its key must be a + string, and the associated value must be either string or + array of strings. Since this is not a final response, even if + this method is invoked, request is still forwarded to a + backend unless :rb:meth:`Nghttpx::Response#return` is called. + This method can be called multiple times. It cannot be called + after :rb:meth:`Nghttpx::Response#return` is called. + MRUBY EXAMPLES ~~~~~~~~~~~~~~ @@ -1871,11 +1913,11 @@ some cases where the error has occurred before reaching API endpoint The following section describes available API endpoints. -PUT /api/v1beta1/backendconfig -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +POST /api/v1beta1/backendconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This API replaces the current backend server settings with the -requested ones. The request method should be PUT, but POST is also +requested ones. The request method should be POST, but PUT is also acceptable. The request body must be nghttpx configuration file format. For configuration file format, see `FILES`_ section. The line separator inside the request body must be single LF (0x0A).