From 0ee80be99525f0ba211a9e4eb7e3434d4f834b0f Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Fri, 29 Apr 2016 23:27:20 +0900 Subject: [PATCH] Update man pages --- doc/h2load.1 | 2 +- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 78 +++++++++++++++++++++++++++++++---------------- doc/nghttpx.1.rst | 72 ++++++++++++++++++++++++++++--------------- 5 files changed, 101 insertions(+), 55 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index 02f449c5..a7e45e99 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "April 25, 2016" "1.10.0" "nghttp2" +.TH "H2LOAD" "1" "April 29, 2016" "1.11.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 7db14304..468d05ea 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "April 25, 2016" "1.10.0" "nghttp2" +.TH "NGHTTP" "1" "April 29, 2016" "1.11.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 76aff653..cc8d6590 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "April 25, 2016" "1.10.0" "nghttp2" +.TH "NGHTTPD" "1" "April 29, 2016" "1.11.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 94d66615..4f9d2e9e 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "April 25, 2016" "1.10.0" "nghttp2" +.TH "NGHTTPX" "1" "April 29, 2016" "1.11.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -40,14 +40,14 @@ A reverse proxy for HTTP/2, HTTP/1 and SPDY. .TP .B Set path to server\(aqs private key. Required unless -"no\-tls" keyword is used in \fI\%\-\-frontend\fP option. +"no\-tls" parameter is used in \fI\%\-\-frontend\fP option. .UNINDENT .INDENT 0.0 .TP .B Set path to server\(aqs certificate. Required unless -"no\-tls" keyword is used in \fI\%\-\-frontend\fP option. To make -OCSP stapling work, this must be an absolute path. +"no\-tls" parameter is used in \fI\%\-\-frontend\fP option. To +make OCSP stapling work, this must be an absolute path. .UNINDENT .SH OPTIONS .sp @@ -119,16 +119,16 @@ together forming load balancing group. .sp Several parameters are accepted after . The parameters are delimited by ";". The available -parameters are: "proto=", "tls", "fall=", and -"rise=". 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. +parameters are: "proto=", "tls", +"sni=", "fall=", and "rise=". 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" keyword, and in the form of +optional "proto" parameter, and in the form of "proto=". All that share the same must have the same value if it is given. should be one of the following list without quotes: @@ -137,8 +137,12 @@ should be one of the following list without quotes: over TLS. But in this option, it may mean HTTP/2 over cleartext TCP unless "tls" keyword is used (see below). .sp -TLS can be enabled by specifying optional "tls" keyword. -TLS is not enabled by default. +TLS can be enabled by specifying optional "tls" +parameter. TLS is not enabled by default. +.sp +With "sni=" parameter, it can override the TLS +SNI field value with given . This will +default to the backend name .sp The feature to detect whether backend is online or offline can be enabled using optional "fall" and "rise" @@ -174,7 +178,7 @@ This option can be used multiple times to listen to multiple addresses. .sp Optionally, TLS can be disabled by specifying "no\-tls" -keyword. TLS is enabled by default. +parameter. TLS is enabled by default. .sp Default: \fB*,3000\fP .UNINDENT @@ -469,12 +473,6 @@ stapling work, must be absolute path. .UNINDENT .INDENT 0.0 .TP -.B \-\-backend\-tls\-sni\-field= -Explicitly set the content of the TLS SNI extension. -This will default to the backend HOST name. -.UNINDENT -.INDENT 0.0 -.TP .B \-\-dh\-param\-file= Path to file that contains DH parameters in PEM format. Without this option, DHE cipher suites are not @@ -570,7 +568,7 @@ ticket key generator to rotate keys frequently. See "TLS SESSION TICKET RESUMPTION" section in manual page to know the data format in memcached entry. Optionally, memcached connection can be encrypted with TLS by -specifying "tls" keyword. +specifying "tls" parameter. .UNINDENT .INDENT 0.0 .TP @@ -656,7 +654,7 @@ Specify address of memcached server to store session cache. This enables shared session cache between multiple nghttpx instances. Optionally, memcached connection can be encrypted with TLS by specifying "tls" -keyword. +parameter. .UNINDENT .INDENT 0.0 .TP @@ -796,8 +794,8 @@ does not support server push. .TP .B (default mode) Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. "no\-tls" -keyword is used in \fI\%\-\-frontend\fP option, accept HTTP/2 and -HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1 +parameter is used in \fI\%\-\-frontend\fP option, accept HTTP/2 +and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1 connection can be upgraded to HTTP/2 through HTTP Upgrade. .UNINDENT @@ -1430,7 +1428,27 @@ Return the current phase. .INDENT 7.0 .TP .B attribute [R] remote_addr -Return IP address of a remote client. +Return IP address of a remote client. If connection is made +via UNIX domain socket, this returns the string "localhost". +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] server_addr +Return address of server that accepted the connection. This +is a string which specified in \fI\%\-\-frontend\fP option, +excluding port number, and not a resolved IP address. For +UNIX domain socket, this is a path to UNIX domain socket. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] server_port +Return port number of the server frontend which accepted the +connection from client. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_used +Return true if TLS is used on the connection. .UNINDENT .UNINDENT .INDENT 0.0 @@ -1473,7 +1491,13 @@ value is assigned. .B attribute [R/W] path Request path, including query component (i.e., /index.html). On assignment, copy of given value is assigned. The path does -not include authority component of URI. +not include authority component of URI. This may include +query component. nghttpx makes certain normalization for +path. It decodes percent\-encoding for unreserved characters +(see \fI\%https://tools.ietf.org/html/rfc3986#section\-2.3\fP), and +resolves ".." and ".". But it may leave characters which +should be percent\-encoded as is. So be careful when comparing +path against desired string. .UNINDENT .INDENT 7.0 .TP diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index 50e7e635..79d65c3f 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -20,13 +20,13 @@ A reverse proxy for HTTP/2, HTTP/1 and SPDY. Set path to server's private key. Required unless - "no-tls" keyword is used in :option:`--frontend` option. + "no-tls" parameter is used in :option:`--frontend` option. .. describe:: Set path to server's certificate. Required unless - "no-tls" keyword is used in :option:`--frontend` option. To make - OCSP stapling work, this must be an absolute path. + "no-tls" parameter is used in :option:`--frontend` option. To + make OCSP stapling work, this must be an absolute path. OPTIONS @@ -103,16 +103,16 @@ Connections Several parameters are accepted after . The parameters are delimited by ";". The available - parameters are: "proto=", "tls", "fall=", and - "rise=". 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. + parameters are: "proto=", "tls", + "sni=", "fall=", and "rise=". 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" keyword, and in the form of + optional "proto" parameter, and in the form of "proto=". All that share the same must have the same value if it is given. should be one of the following list without quotes: @@ -121,8 +121,12 @@ Connections over TLS. But in this option, it may mean HTTP/2 over cleartext TCP unless "tls" keyword is used (see below). - TLS can be enabled by specifying optional "tls" keyword. - TLS is not enabled by default. + TLS can be enabled by specifying optional "tls" + parameter. TLS is not enabled by default. + + With "sni=" parameter, it can override the TLS + SNI field value with given . This will + default to the backend name The feature to detect whether backend is online or offline can be enabled using optional "fall" and "rise" @@ -158,7 +162,7 @@ Connections multiple addresses. Optionally, TLS can be disabled by specifying "no-tls" - keyword. TLS is enabled by default. + parameter. TLS is enabled by default. Default: ``*,3000`` @@ -426,11 +430,6 @@ SSL/TLS option can be used multiple times. To make OCSP stapling work, must be absolute path. -.. option:: --backend-tls-sni-field= - - Explicitly set the content of the TLS SNI extension. - This will default to the backend HOST name. - .. option:: --dh-param-file= Path to file that contains DH parameters in PEM format. @@ -519,7 +518,7 @@ SSL/TLS "TLS SESSION TICKET RESUMPTION" section in manual page to know the data format in memcached entry. Optionally, memcached connection can be encrypted with TLS by - specifying "tls" keyword. + specifying "tls" parameter. .. option:: --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6) @@ -594,7 +593,7 @@ SSL/TLS cache. This enables shared session cache between multiple nghttpx instances. Optionally, memcached connection can be encrypted with TLS by specifying "tls" - keyword. + parameter. .. option:: --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6) @@ -725,8 +724,8 @@ Mode Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. "no-tls" - keyword is used in :option:`--frontend` option, accept HTTP/2 and - HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1 + parameter is used in :option:`--frontend` option, accept HTTP/2 + and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1 connection can be upgraded to HTTP/2 through HTTP Upgrade. @@ -1306,7 +1305,24 @@ respectively. .. rb:attr_reader:: remote_addr - Return IP address of a remote client. + Return IP address of a remote client. If connection is made + via UNIX domain socket, this returns the string "localhost". + + .. rb:attr_reader:: server_addr + + Return address of server that accepted the connection. This + is a string which specified in :option:`--frontend` option, + excluding port number, and not a resolved IP address. For + UNIX domain socket, this is a path to UNIX domain socket. + + .. rb:attr_reader:: server_port + + Return port number of the server frontend which accepted the + connection from client. + + .. rb:attr_reader:: tls_used + + Return true if TLS is used on the connection. .. rb:class:: Request @@ -1342,7 +1358,13 @@ respectively. Request path, including query component (i.e., /index.html). On assignment, copy of given value is assigned. The path does - not include authority component of URI. + not include authority component of URI. This may include + query component. nghttpx makes certain normalization for + path. It decodes percent-encoding for unreserved characters + (see https://tools.ietf.org/html/rfc3986#section-2.3), and + resolves ".." and ".". But it may leave characters which + should be percent-encoded as is. So be careful when comparing + path against desired string. .. rb:attr_reader:: headers