Update manual pages

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
 .

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
 .

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
 .

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=<METHOD>"  parameter.   If  "ip" is  given  in
 <METHOD>, client  IP based session affinity  is enabled.
-If  "none" is  given  in <METHOD>,  session affinity  is
+If "cookie"  is given in <METHOD>,  cookie based session
-disabled, and this is the default.  The session affinity
+affinity is  enabled.  If  "none" is given  in <METHOD>,
-is enabled per  <PATTERN>.  If at least  one backend has
+session affinity  is disabled, and this  is the default.
-"affinity" parameter,  and its  <METHOD> is  not "none",
+The session  affinity is  enabled per <PATTERN>.   If at
-session  affinity is  enabled  for  all backend  servers
+least  one backend  has  "affinity"  parameter, and  its
-sharing  the  same  <PATTERN>.   It is  advised  to  set
+<METHOD> is not "none",  session affinity is enabled for
-"affinity"  parameter  to   all  backend  explicitly  if
+all backend  servers sharing the same  <PATTERN>.  It is
-session affinity  is desired.  The session  affinity may
+advised  to  set  "affinity" parameter  to  all  backend
-break if one of the backend gets unreachable, or backend
+explicitly if session affinity  is desired.  The session
-settings are reloaded or replaced by API.
+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=<NAME>" must be  used to specify a
+name     of     cookie      to     use.      Optionally,
+"affinity\-cookie\-path=<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 <datetime>
-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 <master\-pid>
@@ -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\&.

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=<METHOD>"  parameter.   If  "ip" is  given  in
     <METHOD>, client  IP based session affinity  is enabled.
-    If  "none" is  given  in <METHOD>,  session affinity  is
+    If "cookie"  is given in <METHOD>,  cookie based session
-    disabled, and this is the default.  The session affinity
+    affinity is  enabled.  If  "none" is given  in <METHOD>,
-    is enabled per  <PATTERN>.  If at least  one backend has
+    session affinity  is disabled, and this  is the default.
-    "affinity" parameter,  and its  <METHOD> is  not "none",
+    The session  affinity is  enabled per <PATTERN>.   If at
-    session  affinity is  enabled  for  all backend  servers
+    least  one backend  has  "affinity"  parameter, and  its
-    sharing  the  same  <PATTERN>.   It is  advised  to  set
+    <METHOD> is not "none",  session affinity is enabled for
-    "affinity"  parameter  to   all  backend  explicitly  if
+    all backend  servers sharing the same  <PATTERN>.  It is
-    session affinity  is desired.  The session  affinity may
+    advised  to  set  "affinity" parameter  to  all  backend
-    break if one of the backend gets unreachable, or backend
+    explicitly if session affinity  is desired.  The session
-    settings are reloaded or replaced by API.
+    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=<NAME>" must be  used to specify a
+    name     of     cookie      to     use.      Optionally,
+    "affinity-cookie-path=<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
   <datetime> <master-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg>
 
   <datetime>
-    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.
 
   <master-pid>
@@ -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`.