From 05e1fd5e772c5e5f6c1b12fc94f3bd0fca3e5a84 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 4 Nov 2017 17:53:51 +0900 Subject: [PATCH] Update manual pages --- doc/h2load.1 | 2 +- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 104 +++++++++++++++++++++++++++++++++++++++------- doc/nghttpx.1.rst | 88 ++++++++++++++++++++++++++++++++------- 5 files changed, 164 insertions(+), 34 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index 796b2b68..33f7a36c 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "Oct 24, 2017" "1.27.0" "nghttp2" +.TH "H2LOAD" "1" "Nov 04, 2017" "1.28.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 863dff9f..8517a634 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "Oct 24, 2017" "1.27.0" "nghttp2" +.TH "NGHTTP" "1" "Nov 04, 2017" "1.28.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 714c13d9..7aef0821 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "Oct 24, 2017" "1.27.0" "nghttp2" +.TH "NGHTTPD" "1" "Nov 04, 2017" "1.28.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 83824e7c..bb50b101 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "Oct 24, 2017" "1.27.0" "nghttp2" +.TH "NGHTTPX" "1" "Nov 04, 2017" "1.28.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -75,7 +75,7 @@ matches request path "\fI/foo\fP"). If it does not end with "\fI/\fP", it performs exact match against the request path. If host is given, it performs a match against the request host. For a request received on the frontend -lister with "sni\-fwd" parameter enabled, SNI host is +listener with "sni\-fwd" parameter enabled, SNI host is used instead of a request host. If host alone is given, "\fI/\fP" is appended to it, so that it matches all request paths under the host (e.g., specifying "nghttp2.org" @@ -180,16 +180,28 @@ state, and this is the default behaviour. The session affinity is enabled using "affinity=" parameter. If "ip" is given in , client IP based session affinity is enabled. -If "none" is given in , session affinity is -disabled, and this is the default. The session affinity -is enabled per . If at least one backend has -"affinity" parameter, and its is not "none", -session affinity is enabled for all backend servers -sharing the same . It is advised to set -"affinity" parameter to all backend explicitly if -session affinity is desired. The session affinity may -break if one of the backend gets unreachable, or backend -settings are reloaded or replaced by API. +If "cookie" is given in , cookie based session +affinity is enabled. If "none" is given in , +session affinity is disabled, and this is the default. +The session affinity is enabled per . If at +least one backend has "affinity" parameter, and its + is not "none", session affinity is enabled for +all backend servers sharing the same . It is +advised to set "affinity" parameter to all backend +explicitly if session affinity is desired. The session +affinity may break if one of the backend gets +unreachable, or backend settings are reloaded or +replaced by API. +.sp +If "affinity=cookie" is used, the additional +configuration is required. +"affinity\-cookie\-name=" must be used to specify a +name of cookie to use. Optionally, +"affinity\-cookie\-path=" can be used to specify a +path which cookie is applied. The Secure attribute of a +cookie is determined by a request scheme. If a request +scheme is "https", then Secure attribute is added. +Otherwise, it is not added. .sp By default, name resolution of backend host name is done at start up, or reloading configuration. If "dns" @@ -1184,6 +1196,15 @@ regardless of minor version. .IP \(bu 2 $tls_cipher: cipher used for SSL/TLS connection. .IP \(bu 2 +$tls_client_fingerprint_sha256: SHA\-256 fingerprint of +client certificate. +.IP \(bu 2 +$tls_client_fingerprint_sha1: SHA\-1 fingerprint of +client certificate. +.IP \(bu 2 +$tls_client_subject_name: subject name in client +certificate. +.IP \(bu 2 $tls_protocol: protocol for SSL/TLS connection. .IP \(bu 2 $tls_session_id: session ID for SSL/TLS connection. @@ -1634,7 +1655,7 @@ follows: .INDENT 7.0 .TP .B -It is a conbination of date and time when the log is written. It +It is a combination of date and time when the log is written. It is in ISO 8601 format. .TP .B @@ -1789,7 +1810,7 @@ By default, session ID is shared by all worker threads. .sp If \fI\%\-\-tls\-session\-cache\-memcached\fP is given, nghttpx will insert serialized session data to memcached with -\fBnghttpx:tls\-session\-cache:\fP + lowercased hex string of session ID +\fBnghttpx:tls\-session\-cache:\fP + lowercase hex string of session ID as a memcached entry key, with expiry time 12 hours. Session timeout is set to 12 hours. .sp @@ -1871,6 +1892,17 @@ API is subject to change in the future release. .UNINDENT .UNINDENT .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Almost all string value returned from method, or attribute is a +fresh new mruby string, which involves memory allocation, and +copies. Therefore, it is strongly recommended to store a return +value in a local variable, and use it, instead of calling method or +accessing attribute repeatedly. +.UNINDENT +.UNINDENT +.sp nghttpx allows users to extend its capability using mruby scripts. nghttpx has 2 hook points to execute mruby script: request phase and response phase. The request phase hook is invoked after all request @@ -1919,7 +1951,7 @@ Return \fI\%Response\fP object. .TP .B attribute [R] ctx Return Ruby hash object. It persists until request finishes. -So values set in request phase hoo can be retrieved in +So values set in request phase hook can be retrieved in response phase hook. .UNINDENT .INDENT 7.0 @@ -1957,6 +1989,46 @@ Return true if TLS is used on the connection. .B attribute [R] tls_sni Return the TLS SNI value which client sent in this connection. .UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_fingerprint_sha256 +Return the SHA\-256 fingerprint of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_fingerprint_sha1 +Return the SHA\-1 fingerprint of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_subject_name +Return the subject name of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_cipher +Return a TLS cipher negotiated in this connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_protocol +Return a TLS protocol version negotiated in this connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_session_id +Return a session ID for this connection in hex string. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_session_reused +Return true if, and only if a SSL/TLS session is reused. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] alpn +Return ALPN identifier negotiated in this connection. +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -2234,7 +2306,7 @@ The replacement is done instantly without breaking existing connections or requests. It also avoids any process creation as is the case with hot swapping with signals. .sp -The one limitation is that only numeric IP address is allowd in +The one limitation is that only numeric IP address is allowed in \fI\%backend\fP in request body unless "dns" parameter is used while non numeric hostname is allowed in command\-line or configuration file is read using \fI\%\-\-conf\fP\&. diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index 290034b5..c579be04 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -59,7 +59,7 @@ Connections "*/*", it performs exact match against the request path. If host is given, it performs a match against the request host. For a request received on the frontend - lister with "sni-fwd" parameter enabled, SNI host is + listener with "sni-fwd" parameter enabled, SNI host is used instead of a request host. If host alone is given, "*/*" is appended to it, so that it matches all request paths under the host (e.g., specifying "nghttp2.org" @@ -164,16 +164,28 @@ Connections The session affinity is enabled using "affinity=" parameter. If "ip" is given in , client IP based session affinity is enabled. - If "none" is given in , session affinity is - disabled, and this is the default. The session affinity - is enabled per . If at least one backend has - "affinity" parameter, and its is not "none", - session affinity is enabled for all backend servers - sharing the same . It is advised to set - "affinity" parameter to all backend explicitly if - session affinity is desired. The session affinity may - break if one of the backend gets unreachable, or backend - settings are reloaded or replaced by API. + If "cookie" is given in , cookie based session + affinity is enabled. If "none" is given in , + session affinity is disabled, and this is the default. + The session affinity is enabled per . If at + least one backend has "affinity" parameter, and its + is not "none", session affinity is enabled for + all backend servers sharing the same . It is + advised to set "affinity" parameter to all backend + explicitly if session affinity is desired. The session + affinity may break if one of the backend gets + unreachable, or backend settings are reloaded or + replaced by API. + + If "affinity=cookie" is used, the additional + configuration is required. + "affinity-cookie-name=" must be used to specify a + name of cookie to use. Optionally, + "affinity-cookie-path=" can be used to specify a + path which cookie is applied. The Secure attribute of a + cookie is determined by a request scheme. If a request + scheme is "https", then Secure attribute is added. + Otherwise, it is not added. By default, name resolution of backend host name is done at start up, or reloading configuration. If "dns" @@ -1078,6 +1090,12 @@ Logging the response. For HTTP/1, ALPN is always http/1.1, regardless of minor version. * $tls_cipher: cipher used for SSL/TLS connection. + * $tls_client_fingerprint_sha256: SHA-256 fingerprint of + client certificate. + * $tls_client_fingerprint_sha1: SHA-1 fingerprint of + client certificate. + * $tls_client_subject_name: subject name in client + certificate. * $tls_protocol: protocol for SSL/TLS connection. * $tls_session_id: session ID for SSL/TLS connection. * $tls_session_reused: "r" if SSL/TLS session was @@ -1490,7 +1508,7 @@ Error log (:) - It is a conbination of date and time when the log is written. It + It is a combination of date and time when the log is written. It is in ISO 8601 format. @@ -1641,7 +1659,7 @@ By default, session ID is shared by all worker threads. If :option:`--tls-session-cache-memcached` is given, nghttpx will insert serialized session data to memcached with -``nghttpx:tls-session-cache:`` + lowercased hex string of session ID +``nghttpx:tls-session-cache:`` + lowercase hex string of session ID as a memcached entry key, with expiry time 12 hours. Session timeout is set to 12 hours. @@ -1723,6 +1741,14 @@ MRUBY SCRIPTING The current mruby extension API is experimental and not frozen. The API is subject to change in the future release. +.. warning:: + + Almost all string value returned from method, or attribute is a + fresh new mruby string, which involves memory allocation, and + copies. Therefore, it is strongly recommended to store a return + value in a local variable, and use it, instead of calling method or + accessing attribute repeatedly. + nghttpx allows users to extend its capability using mruby scripts. nghttpx has 2 hook points to execute mruby script: request phase and response phase. The request phase hook is invoked after all request @@ -1769,7 +1795,7 @@ respectively. .. rb:attr_reader:: ctx Return Ruby hash object. It persists until request finishes. - So values set in request phase hoo can be retrieved in + So values set in request phase hook can be retrieved in response phase hook. .. rb:attr_reader:: phase @@ -1801,6 +1827,38 @@ respectively. Return the TLS SNI value which client sent in this connection. + .. rb:attr_reader:: tls_client_fingerprint_sha256 + + Return the SHA-256 fingerprint of a client certificate. + + .. rb:attr_reader:: tls_client_fingerprint_sha1 + + Return the SHA-1 fingerprint of a client certificate. + + .. rb:attr_reader:: tls_client_subject_name + + Return the subject name of a client certificate. + + .. rb:attr_reader:: tls_cipher + + Return a TLS cipher negotiated in this connection. + + .. rb:attr_reader:: tls_protocol + + Return a TLS protocol version negotiated in this connection. + + .. rb:attr_reader:: tls_session_id + + Return a session ID for this connection in hex string. + + .. rb:attr_reader:: tls_session_reused + + Return true if, and only if a SSL/TLS session is reused. + + .. rb:attr_reader:: alpn + + Return ALPN identifier negotiated in this connection. + .. rb:class:: Request Object to represent request from client. The modification to @@ -2045,7 +2103,7 @@ The replacement is done instantly without breaking existing connections or requests. It also avoids any process creation as is the case with hot swapping with signals. -The one limitation is that only numeric IP address is allowd in +The one limitation is that only numeric IP address is allowed in :option:`backend <--backend>` in request body unless "dns" parameter is used while non numeric hostname is allowed in command-line or configuration file is read using :option:`--conf`.