walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update man pages

This commit is contained in:
Tatsuhiro Tsujikawa 2015-07-29 00:01:12 +09:00
parent a73cfd5f7b
commit 58dd924343
8 changed files with 341 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/h2load.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "H2LOAD" "1" "July 18, 2015" "1.1.2" "nghttp2"
.TH "H2LOAD" "1" "July 28, 2015" "1.1.3-DEV" "nghttp2"
.SH NAME
h2load \- HTTP/2 benchmarking tool
.
@ -70,10 +70,10 @@ Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-i, \-\-input\-file=<FILE>
.B \-i, \-\-input\-file=<PATH>
Path of a file with multiple URIs are separated by EOLs.
This option will disable URIs getting from command\-line.
If \(aq\-\(aq is given as <FILE>, URIs will be read from stdin.
If \(aq\-\(aq is given as <PATH>, URIs will be read from stdin.
URIs are used in this order for each client. All URIs
are used, then first URI is used and then 2nd URI, and
so on. The scheme, host and port in the subsequent
@ -128,12 +128,36 @@ Default: \fBh2c\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-data=<FILE>
.B \-d, \-\-data=<PATH>
Post FILE to server. The request method is changed to
POST.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-rate=<N>
Specified the fixed rate at which connections are
created. The rate must be a positive integer,
representing the number of connections to be made per
second. When the rate is 0, the program will run as it
normally does, creating connections at whatever variable
rate it wants. The default value for this option is 0.
.UNINDENT
.INDENT 0.0
.TP
.B \-C, \-\-num\-conns=<N>
Specifies the total number of connections to create.
The total number of connections must be a positive
integer. On each connection, \fI\%\-m\fP requests are made. The
test stops once as soon as the N connections have either
completed or failed. When the number of connections is
0, the program will run as it normally does, creating as
many connections as it needs in order to make the \fI\%\-n\fP
requests specified. The default value for this option
is 0. The \fI\%\-n\fP option is not required if the \fI\%\-C\fP option is
being used.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Output debug information.
.UNINDENT

28
doc/h2load.1.rst
View File

@ -46,11 +46,11 @@ OPTIONS
Default: ``1``
.. option:: -i, --input-file=<FILE>
.. option:: -i, --input-file=<PATH>
Path of a file with multiple URIs are separated by EOLs.
This option will disable URIs getting from command-line.
If '-' is given as <FILE>, URIs will be read from stdin.
If '-' is given as <PATH>, URIs will be read from stdin.
URIs are used in this order for each client. All URIs
are used, then first URI is used and then 2nd URI, and
so on. The scheme, host and port in the subsequent
@ -97,11 +97,33 @@ OPTIONS
Default: ``h2c``
.. option:: -d, --data=<FILE>
.. option:: -d, --data=<PATH>
Post FILE to server. The request method is changed to
POST.
.. option:: -r, --rate=<N>
Specified the fixed rate at which connections are
created. The rate must be a positive integer,
representing the number of connections to be made per
second. When the rate is 0, the program will run as it
normally does, creating connections at whatever variable
rate it wants. The default value for this option is 0.
.. option:: -C, --num-conns=<N>
Specifies the total number of connections to create.
The total number of connections must be a positive
integer. On each connection, :option:`-m` requests are made. The
test stops once as soon as the N connections have either
completed or failed. When the number of connections is
0, the program will run as it normally does, creating as
many connections as it needs in order to make the :option:`-n`
requests specified. The default value for this option
is 0. The :option:`-n` option is not required if the :option:`\-C` option is
being used.
.. option:: -v, --verbose
Output debug information.

8
doc/nghttp.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NGHTTP" "1" "July 18, 2015" "1.1.2" "nghttp2"
.TH "NGHTTP" "1" "July 28, 2015" "1.1.3-DEV" "nghttp2"
.SH NAME
nghttp \- HTTP/2 experimental client
.
@ -122,7 +122,7 @@ PEM format.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-data=<FILE>
.B \-d, \-\-data=<PATH>
Post FILE to server. If \(aq\-\(aq is given, data will be read
from stdin.
.UNINDENT
@ -167,8 +167,8 @@ Specify 0 to disable padding.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-har=<FILE>
Output HTTP transactions <FILE> in HAR format. If \(aq\-\(aq
.B \-r, \-\-har=<PATH>
Output HTTP transactions <PATH> in HAR format. If \(aq\-\(aq
is given, data is written to stdout.
.UNINDENT
.INDENT 0.0

6
doc/nghttp.1.rst
View File

@ -89,7 +89,7 @@ OPTIONS
Use the client private key file. The file must be in
PEM format.
.. option:: -d, --data=<FILE>
.. option:: -d, --data=<PATH>
Post FILE to server. If '-' is given, data will be read
from stdin.
@ -127,9 +127,9 @@ OPTIONS
Add at most <N> bytes to a frame payload as padding.
Specify 0 to disable padding.
.. option:: -r, --har=<FILE>
.. option:: -r, --har=<PATH>
Output HTTP transactions <FILE> in HAR format. If '-'
Output HTTP transactions <PATH> in HAR format. If '-'
is given, data is written to stdout.
.. option:: --color

2
doc/nghttpd.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NGHTTPD" "1" "July 18, 2015" "1.1.2" "nghttp2"
.TH "NGHTTPD" "1" "July 28, 2015" "1.1.3-DEV" "nghttp2"
.SH NAME
nghttpd \- HTTP/2 experimental server
.

158
doc/nghttpx.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NGHTTPX" "1" "July 18, 2015" "1.1.2" "nghttp2"
.TH "NGHTTPX" "1" "July 28, 2015" "1.1.3-DEV" "nghttp2"
.SH NAME
nghttpx \- HTTP/2 experimental proxy
.
@ -475,22 +475,75 @@ Default: \fBTLSv1.2,TLSv1.1\fP
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-file=<PATH>
Path to file that contains 48 bytes random data to
construct TLS session ticket parameters. This options
can be used repeatedly to specify multiple ticket
parameters. If several files are given, only the first
key is used to encrypt TLS session tickets. Other keys
are accepted but server will issue new session ticket
with first key. This allows session key rotation.
Please note that key rotation does not occur
automatically. User should rearrange files or change
options values and restart nghttpx gracefully. If
opening or reading given file fails, all loaded keys are
discarded and it is treated as if none of this option is
given. If this option is not given or an error occurred
while opening or reading a file, key is generated
automatically and renewed every 12hrs. At most 2 keys
are stored in memory.
Path to file that contains random data to construct TLS
session ticket parameters. If aes\-128\-cbc is given in
\fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly
48 bytes. If aes\-256\-cbc is given in
\fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly
80 bytes. This options can be used repeatedly to
specify multiple ticket parameters. If several files
are given, only the first key is used to encrypt TLS
session tickets. Other keys are accepted but server
will issue new session ticket with first key. This
allows session key rotation. Please note that key
rotation does not occur automatically. User should
rearrange files or change options values and restart
nghttpx gracefully. If opening or reading given file
fails, all loaded keys are discarded and it is treated
as if none of this option is given. If this option is
not given or an error occurred while opening or reading
a file, key is generated every 1 hour internally and
they are valid for 12 hours. This is recommended if
ticket key sharing between nghttpx instances is not
required.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached=<HOST>,<PORT>
Specify address of memcached server to store session
cache. This enables shared TLS ticket key between
multiple nghttpx instances. nghttpx does not set TLS
ticket key to memcached. The external ticket key
generator is required. nghttpx just gets TLS ticket
keys from memcached, and use them, possibly replacing
current set of keys. It is up to extern TLS ticket key
generator to rotate keys frequently. See "TLS SESSION
TICKET RESUMPTION" section in manual page to know the
data format in memcached entry.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-interval=<DURATION>
Set interval to get TLS ticket keys from memcached.
.sp
Default: \fB10m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-max\-retry=<N>
Set maximum number of consecutive retries before
abandoning TLS ticket key retrieval. If this number is
reached, the attempt is considered as failure, and
"failure" count is incremented by 1, which contributed
to the value controlled
\fI\%\-\-tls\-ticket\-key\-memcached\-max\-fail\fP option.
.sp
Default: \fB3\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-max\-fail=<N>
Set maximum number of consecutive failure before
disabling TLS ticket until next scheduled key retrieval.
.sp
Default: \fB2\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-cipher=<CIPHER>
Specify cipher to encrypt TLS session ticket. Specify
either aes\-128\-cbc or aes\-256\-cbc. By default,
aes\-128\-cbc is used.
.UNINDENT
.INDENT 0.0
.TP
@ -512,6 +565,13 @@ Default: \fB4h\fP
.B \-\-no\-ocsp
Disable OCSP stapling.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-session\-cache\-memcached=<HOST>,<PORT>
Specify address of memcached server to store session
cache. This enables shared session cache between
multiple nghttpx instances.
.UNINDENT
.SS HTTP/2 and SPDY
.INDENT 0.0
.TP
@ -750,8 +810,8 @@ altered regardless of this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-host\-rewrite
Don\(aqt rewrite host and :authority header fields on
.B \-\-host\-rewrite
Rewrite host and :authority header fields on
\fI\%\-\-http2\-bridge\fP, \fI\%\-\-client\fP and default mode. For
\fI\%\-\-http2\-proxy\fP and \fI\%\-\-client\-proxy\fP mode, these headers
will not be altered regardless of this option.
@ -977,6 +1037,66 @@ translated into Python.
The script file is usually installed under
\fB$(prefix)/share/nghttp2/\fP directory. The actual path to script can
be customized using \fI\%\-\-fetch\-ocsp\-response\-file\fP option.
.SH TLS SESSION RESUMPTION
.sp
nghttpx supports TLS session resumption through both session ID and
session ticket.
.SS SESSION ID RESUMPTION
.sp
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
as a memcached entry key, with expiry time 12 hours. Session timeout
is set to 12 hours.
.SS TLS SESSION TICKET RESUMPTION
.sp
By default, session ticket is shared by all worker threads. The
automatic key rotation is also enabled by default. Every an hour, new
encryption key is generated, and previous encryption key becomes
decryption only key. We set session timeout to 12 hours, and thus we
keep at most 12 keys.
.sp
If \fI\%\-\-tls\-ticket\-key\-memcached\fP is given, encryption keys are
retrieved from memcached. nghttpx just reads keys from memcached; one
has to deploy key generator program to update keys frequently (e.g.,
every 1 hour). The memcached entry key is \fBnghttpx:tls\-ticket\-key\fP\&.
The data format stored in memcached is the binary format described
below:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| VERSION (4) |LEN (2)|KEY(48 or 80) ...
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
^ |
| |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
(LEN, KEY) pair can be repeated
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All numbers in the above figure is bytes. All integer fields are
network byte order.
.sp
First 4 bytes integer VERSION field, which must be 1. The 2 bytes
integer LEN field gives the length of following KEY field, which
contains key. If \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-128\-cbc is
used, LEN must be 48. If
\fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-256\-cbc is used, LEN must be
80. LEN and KEY pair can be repeated multiple times to store multiple
keys. The key appeared first is used as encryption key. All the
remaining keys are used as decryption only.
.sp
If \fI\%\-\-tls\-ticket\-key\-file\fP is given, encryption key is read
from the given file. In this case, nghttpx does not rotate key
automatically. To rotate key, one has to restart nghttpx (see
SIGNALS).
.SH SEE ALSO
.sp
\fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP

148
doc/nghttpx.1.rst
View File

@ -424,22 +424,70 @@ SSL/TLS
.. option:: --tls-ticket-key-file=<PATH>
Path to file that contains 48 bytes random data to
construct TLS session ticket parameters. This options
can be used repeatedly to specify multiple ticket
parameters. If several files are given, only the first
key is used to encrypt TLS session tickets. Other keys
are accepted but server will issue new session ticket
with first key. This allows session key rotation.
Please note that key rotation does not occur
automatically. User should rearrange files or change
options values and restart nghttpx gracefully. If
opening or reading given file fails, all loaded keys are
discarded and it is treated as if none of this option is
given. If this option is not given or an error occurred
while opening or reading a file, key is generated
automatically and renewed every 12hrs. At most 2 keys
are stored in memory.
Path to file that contains random data to construct TLS
session ticket parameters. If aes-128-cbc is given in
:option:`--tls-ticket-key-cipher`\, the file must contain exactly
48 bytes. If aes-256-cbc is given in
:option:`--tls-ticket-key-cipher`\, the file must contain exactly
80 bytes. This options can be used repeatedly to
specify multiple ticket parameters. If several files
are given, only the first key is used to encrypt TLS
session tickets. Other keys are accepted but server
will issue new session ticket with first key. This
allows session key rotation. Please note that key
rotation does not occur automatically. User should
rearrange files or change options values and restart
nghttpx gracefully. If opening or reading given file
fails, all loaded keys are discarded and it is treated
as if none of this option is given. If this option is
not given or an error occurred while opening or reading
a file, key is generated every 1 hour internally and
they are valid for 12 hours. This is recommended if
ticket key sharing between nghttpx instances is not
required.
.. option:: --tls-ticket-key-memcached=<HOST>,<PORT>
Specify address of memcached server to store session
cache. This enables shared TLS ticket key between
multiple nghttpx instances. nghttpx does not set TLS
ticket key to memcached. The external ticket key
generator is required. nghttpx just gets TLS ticket
keys from memcached, and use them, possibly replacing
current set of keys. It is up to extern TLS ticket key
generator to rotate keys frequently. See "TLS SESSION
TICKET RESUMPTION" section in manual page to know the
data format in memcached entry.
.. option:: --tls-ticket-key-memcached-interval=<DURATION>
Set interval to get TLS ticket keys from memcached.
Default: ``10m``
.. option:: --tls-ticket-key-memcached-max-retry=<N>
Set maximum number of consecutive retries before
abandoning TLS ticket key retrieval. If this number is
reached, the attempt is considered as failure, and
"failure" count is incremented by 1, which contributed
to the value controlled
:option:`--tls-ticket-key-memcached-max-fail` option.
Default: ``3``
.. option:: --tls-ticket-key-memcached-max-fail=<N>
Set maximum number of consecutive failure before
disabling TLS ticket until next scheduled key retrieval.
Default: ``2``
.. option:: --tls-ticket-key-cipher=<CIPHER>
Specify cipher to encrypt TLS session ticket. Specify
either aes-128-cbc or aes-256-cbc. By default,
aes-128-cbc is used.
.. option:: --fetch-ocsp-response-file=<PATH>
@ -458,6 +506,12 @@ SSL/TLS
Disable OCSP stapling.
.. option:: --tls-session-cache-memcached=<HOST>,<PORT>
Specify address of memcached server to store session
cache. This enables shared session cache between
multiple nghttpx instances.
HTTP/2 and SPDY
~~~~~~~~~~~~~~~
@ -665,9 +719,9 @@ HTTP
:option:`--client-proxy` mode, location header field will not be
altered regardless of this option.
.. option:: --no-host-rewrite
.. option:: --host-rewrite
Don't rewrite host and :authority header fields on
Rewrite host and :authority header fields on
:option:`--http2-bridge`\, :option:`--client` and default mode. For
:option:`--http2-proxy` and :option:`\--client-proxy` mode, these headers
will not be altered regardless of this option.
@ -889,6 +943,64 @@ The script file is usually installed under
``$(prefix)/share/nghttp2/`` directory. The actual path to script can
be customized using :option:`--fetch-ocsp-response-file` option.
TLS SESSION RESUMPTION
----------------------
nghttpx supports TLS session resumption through both session ID and
session ticket.
SESSION ID RESUMPTION
~~~~~~~~~~~~~~~~~~~~~
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
as a memcached entry key, with expiry time 12 hours. Session timeout
is set to 12 hours.
TLS SESSION TICKET RESUMPTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, session ticket is shared by all worker threads. The
automatic key rotation is also enabled by default. Every an hour, new
encryption key is generated, and previous encryption key becomes
decryption only key. We set session timeout to 12 hours, and thus we
keep at most 12 keys.
If :option:`--tls-ticket-key-memcached` is given, encryption keys are
retrieved from memcached. nghttpx just reads keys from memcached; one
has to deploy key generator program to update keys frequently (e.g.,
every 1 hour). The memcached entry key is ``nghttpx:tls-ticket-key``.
The data format stored in memcached is the binary format described
below::
+--------------+-------+----------------+
| VERSION (4) |LEN (2)|KEY(48 or 80) ...
+--------------+-------+----------------+
^ |
| |
+------------------------+
(LEN, KEY) pair can be repeated
All numbers in the above figure is bytes. All integer fields are
network byte order.
First 4 bytes integer VERSION field, which must be 1. The 2 bytes
integer LEN field gives the length of following KEY field, which
contains key. If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is
used, LEN must be 48. If
:option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be
80. LEN and KEY pair can be repeated multiple times to store multiple
keys. The key appeared first is used as encryption key. All the
remaining keys are used as decryption only.
If :option:`--tls-ticket-key-file` is given, encryption key is read
from the given file. In this case, nghttpx does not rotate key
automatically. To rotate key, one has to restart nghttpx (see
SIGNALS).
SEE ALSO
--------

20
doc/nghttpx.h2r
View File

@ -108,9 +108,10 @@ SESSION ID RESUMPTION
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 session ID as a part
of the key, with expiry time 12 hours. Session timeout is set to 12
hours.
insert serialized session data to memcached with
``nghttpx:tls-session-cache:`` + lowercased hex string of session ID
as a memcached entry key, with expiry time 12 hours. Session timeout
is set to 12 hours.
TLS SESSION TICKET RESUMPTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -121,11 +122,12 @@ encryption key is generated, and previous encryption key becomes
decryption only key. We set session timeout to 12 hours, and thus we
keep at most 12 keys.
If :option:`--tls-session-key-memcached` is given, encryption keys are
If :option:`--tls-ticket-key-memcached` is given, encryption keys are
retrieved from memcached. nghttpx just reads keys from memcached; one
has to deploy key generator program to update keys frequently (e.g.,
every 1 hour). The data format stored in memcached is the binary
format described below::
every 1 hour). The memcached entry key is ``nghttpx:tls-ticket-key``.
The data format stored in memcached is the binary format described
below::
+--------------+-------+----------------+
| VERSION (4) |LEN (2)|KEY(48 or 80) ...
@ -140,14 +142,14 @@ network byte order.
First 4 bytes integer VERSION field, which must be 1. The 2 bytes
integer LEN field gives the length of following KEY field, which
contains key. If :option:`--tls-session-key-cipher`=aes-128-cbc is
contains key. If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is
used, LEN must be 48. If
:option:`--tls-session-key-cipher`=aes-256-cbc is used, LEN must be
:option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be
80. LEN and KEY pair can be repeated multiple times to store multiple
keys. The key appeared first is used as encryption key. All the
remaining keys are used as decryption only.
If :option:`--tls-session-key-file` is given, encryption key is read
If :option:`--tls-ticket-key-file` is given, encryption key is read
from the given file. In this case, nghttpx does not rotate key
automatically. To rotate key, one has to restart nghttpx (see
SIGNALS).