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-10-20 00:22:03 +09:00
parent f0bf2233d2
commit 1fdf208a28
8 changed files with 224 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
doc/h2load.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "H2LOAD" "1" "September 25, 2015" "1.3.4" "nghttp2"
.TH "H2LOAD" "1" "October 20, 2015" "1.3.5-DEV" "nghttp2"
.SH NAME
h2load \- HTTP/2 benchmarking tool
.
@ -51,14 +51,18 @@ scheme, host or port values.
.INDENT 0.0
.TP
.B \-n, \-\-requests=<N>
Number of requests.
Number of requests across all clients. If it is used
with \fI\%\-\-timing\-script\-file\fP option, this option specifies
the number of requests each client performs rather than
the number of requests across all clients.
.sp
Default: \fB1\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-clients=<N>
Number of concurrent clients.
Number of concurrent clients. With \fI\%\-r\fP option, this
specifies the maximum number of connections to be made.
.sp
Default: \fB1\fP
.UNINDENT
@ -141,43 +145,43 @@ POST.
Specifies 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.
rate period. The maximum number of connections to be
made is given in \fI\%\-c\fP option. This rate will be
distributed among threads as evenly as possible. For
example, with \fB\-t2\fP and \fB\-r4\fP, each thread gets 2
connections per period. 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.
.B \-\-rate\-period=<DURATION>
Specifies the time period between creating connections.
The period must be a positive number, representing the
length of the period in time. This option is ignored if
the rate option is not used. The default value for this
option is 1s.
.UNINDENT
.INDENT 0.0
.TP
.B \-T, \-\-connection\-active\-timeout=<N>
.B \-T, \-\-connection\-active\-timeout=<DURATION>
Specifies the maximum time that h2load is willing to
keep a connection open, regardless of the activity on
said connection. <N> must be a positive integer,
specifying the number of seconds to wait. When no
timeout value is set (either active or inactive), h2load
will keep a connection open indefinitely, waiting for a
said connection. <DURATION> must be a positive integer,
specifying the amount of time to wait. When no timeout
value is set (either active or inactive), h2load will
keep a connection open indefinitely, waiting for a
response.
.UNINDENT
.INDENT 0.0
.TP
.B \-N, \-\-connection\-inactivity\-timeout=<N>
.B \-N, \-\-connection\-inactivity\-timeout=<DURATION>
Specifies the amount of time that h2load is willing to
wait to see activity on a given connection. <N> must be
a positive integer, specifying the number of seconds to
wait. When no timeout value is set (either active or
inactive), h2load will keep a connection open
wait to see activity on a given connection. <DURATION>
must be a positive integer, specifying the amount of
time to wait. When no timeout value is set (either
active or inactive), h2load will keep a connection open
indefinitely, waiting for a response.
.UNINDENT
.INDENT 0.0
@ -191,14 +195,15 @@ milliseconds with microsecond resolution. The second
field represents the URI. This option will disable URIs
getting from command\-line. If \(aq\-\(aq is given as <PATH>,
script lines will be read from stdin. Script lines are
used in order for each client. If \fI\%\-n\fP is given, it must be
less than or equal to the number of script lines, larger
values are clamped to the number of script lines. If \fI\%\-n\fP
is not given, the number of requests will default to the
number of script lines. The scheme, host and port defined
in the first URI are used solely. Values contained in
other URIs, if present, are ignored. Definition of a
base URI overrides all scheme, host or port values.
used in order for each client. If \fI\%\-n\fP is given, it must
be less than or equal to the number of script lines,
larger values are clamped to the number of script lines.
If \fI\%\-n\fP is not given, the number of requests will default
to the number of script lines. The scheme, host and
port defined in the first URI are used solely. Values
contained in other URIs, if present, are ignored.
Definition of a base URI overrides all scheme, host or
port values.
.UNINDENT
.INDENT 0.0
.TP
@ -235,6 +240,11 @@ Display version information and exit.
.B \-h, \-\-help
Display this help and exit.
.UNINDENT
.sp
The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively). If a unit
is omitted, a second is used as unit.
.SH OUTPUT
.INDENT 0.0
.TP

80
doc/h2load.1.rst
View File

@ -31,13 +31,17 @@ OPTIONS
.. option:: -n, --requests=<N>
Number of requests.
Number of requests across all clients. If it is used
with :option:`--timing-script-file` option, this option specifies
the number of requests each client performs rather than
the number of requests across all clients.
Default: ``1``
.. option:: -c, --clients=<N>
Number of concurrent clients.
Number of concurrent clients. With :option:`-r` option, this
specifies the maximum number of connections to be made.
Default: ``1``
@ -110,40 +114,40 @@ OPTIONS
Specifies 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.
rate period. The maximum number of connections to be
made is given in :option:`-c` option. This rate will be
distributed among threads as evenly as possible. For
example, with :option:`-t2` and :option:`\-r4`, each thread gets 2
connections per period. 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>
.. option:: --rate-period=<DURATION>
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.
Specifies the time period between creating connections.
The period must be a positive number, representing the
length of the period in time. This option is ignored if
the rate option is not used. The default value for this
option is 1s.
.. option:: -T, --connection-active-timeout=<N>
.. option:: -T, --connection-active-timeout=<DURATION>
Specifies the maximum time that h2load is willing to
keep a connection open, regardless of the activity on
said connection. <N> must be a positive integer,
specifying the number of seconds to wait. When no
timeout value is set (either active or inactive), h2load
will keep a connection open indefinitely, waiting for a
said connection. <DURATION> must be a positive integer,
specifying the amount of time to wait. When no timeout
value is set (either active or inactive), h2load will
keep a connection open indefinitely, waiting for a
response.
.. option:: -N, --connection-inactivity-timeout=<N>
.. option:: -N, --connection-inactivity-timeout=<DURATION>
Specifies the amount of time that h2load is willing to
wait to see activity on a given connection. <N> must be
a positive integer, specifying the number of seconds to
wait. When no timeout value is set (either active or
inactive), h2load will keep a connection open
wait to see activity on a given connection. <DURATION>
must be a positive integer, specifying the amount of
time to wait. When no timeout value is set (either
active or inactive), h2load will keep a connection open
indefinitely, waiting for a response.
.. option:: --timing-script-file=<PATH>
@ -156,14 +160,15 @@ OPTIONS
field represents the URI. This option will disable URIs
getting from command-line. If '-' is given as <PATH>,
script lines will be read from stdin. Script lines are
used in order for each client. If :option:`-n` is given, it must be
less than or equal to the number of script lines, larger
values are clamped to the number of script lines. If :option:`-n`
is not given, the number of requests will default to the
number of script lines. The scheme, host and port defined
in the first URI are used solely. Values contained in
other URIs, if present, are ignored. Definition of a
base URI overrides all scheme, host or port values.
used in order for each client. If :option:`-n` is given, it must
be less than or equal to the number of script lines,
larger values are clamped to the number of script lines.
If :option:`-n` is not given, the number of requests will default
to the number of script lines. The scheme, host and
port defined in the first URI are used solely. Values
contained in other URIs, if present, are ignored.
Definition of a base URI overrides all scheme, host or
port values.
.. option:: -B, --base-uri=<URI>
@ -195,6 +200,13 @@ OPTIONS
Display this help and exit.
The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively). If a unit
is omitted, a second is used as unit.
OUTPUT
------

4
doc/nghttp.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NGHTTP" "1" "September 25, 2015" "1.3.4" "nghttp2"
.TH "NGHTTP" "1" "October 20, 2015" "1.3.5-DEV" "nghttp2"
.SH NAME
nghttp \- HTTP/2 experimental client
.
@ -35,7 +35,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
\fBnghttp\fP [OPTIONS]... <URI>...
.SH DESCRIPTION
.sp
HTTP/2 experimental client
HTTP/2 client
.INDENT 0.0
.TP
.B <URI>

2
doc/nghttp.1.rst
View File

@ -14,7 +14,7 @@ SYNOPSIS
DESCRIPTION
-----------
HTTP/2 experimental client
HTTP/2 client
.. describe:: <URI>

4
doc/nghttpd.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NGHTTPD" "1" "September 25, 2015" "1.3.4" "nghttp2"
.TH "NGHTTPD" "1" "October 20, 2015" "1.3.5-DEV" "nghttp2"
.SH NAME
nghttpd \- HTTP/2 experimental server
.
@ -35,7 +35,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
\fBnghttpd\fP [OPTION]... <PORT> [<PRIVATE_KEY> <CERT>]
.SH DESCRIPTION
.sp
HTTP/2 experimental server
HTTP/2 server
.INDENT 0.0
.TP
.B <PORT>

2
doc/nghttpd.1.rst
View File

@ -14,7 +14,7 @@ SYNOPSIS
DESCRIPTION
-----------
HTTP/2 experimental server
HTTP/2 server
.. describe:: <PORT>

83
doc/nghttpx.1
View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NGHTTPX" "1" "September 25, 2015" "1.3.4" "nghttp2"
.TH "NGHTTPX" "1" "October 20, 2015" "1.3.5-DEV" "nghttp2"
.SH NAME
nghttpx \- HTTP/2 experimental proxy
.
@ -307,6 +307,16 @@ Set buffer size used to store backend response.
.sp
Default: \fB16K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-fastopen=<N>
Enables "TCP Fast Open" for the listening socket and
limits the maximum length for the queue of connections
that have not yet completed the three\-way handshake. If
value is 0 then fast open is disabled.
.sp
Default: \fB0\fP
.UNINDENT
.SS Timeout
.INDENT 0.0
.TP
@ -321,7 +331,7 @@ Default: \fB3m\fP
.B \-\-frontend\-read\-timeout=<DURATION>
Specify read timeout for HTTP/1.1 frontend connection.
.sp
Default: \fB3m\fP
Default: \fB1m\fP
.UNINDENT
.INDENT 0.0
.TP
@ -351,7 +361,7 @@ Default: \fB0\fP
.B \-\-backend\-read\-timeout=<DURATION>
Specify read timeout for backend connection.
.sp
Default: \fB3m\fP
Default: \fB1m\fP
.UNINDENT
.INDENT 0.0
.TP
@ -473,7 +483,10 @@ 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.
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".
.sp
Default: \fBTLSv1.2,TLSv1.1\fP
.UNINDENT
@ -1007,15 +1020,18 @@ to perform hot swapping.
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
nghttpx consists of 2 processes: one process for processing these
signals, and another one for processing requests. The former spawns
the latter. The former is called master process, and the latter is
called worker process. The above signal must be sent to the master
process. If the worker process receives one of them, it is ignored.
This behaviour of worker process may change in the future release.
In other words, in the future release, worker process may terminate
upon the reception of these signals. Therefore these signals should
not be sent to the worker process.
nghttpx consists of multiple processes: one process for processing
these signals, and another one for processing requests. The former
spawns the latter. The former is called master process, and the
latter is called worker process. If neverbleed is enabled, the
worker process spawns neverbleed daemon process which does RSA key
processing. The above signal must be sent to the master process.
If the other processes received one of them, it is ignored. This
behaviour of these processes may change in the future release. In
other words, in the future release, the processes other than master
process may terminate upon the reception of these signals.
Therefore these signals should not be sent to the processes other
than master process.
.UNINDENT
.UNINDENT
.SH SERVER PUSH
@ -1150,21 +1166,17 @@ server. These hooks allows users to modify header fields, or common
HTTP variables, like authority or request path, and even return custom
response without forwarding request to backend servers.
.sp
To set request phase hook, use \fI\%\-\-request\-phase\-file\fP option.
To set response phase hook, use \fI\%\-\-response\-phase\-file\fP
option.
.sp
For request and response phase hook, user calls \fI\%Nghttpx.run\fP
with block. The \fI\%Nghttpx::Env\fP is passed to the block.
User can can access \fI\%Nghttpx::Request\fP and
\fI\%Nghttpx::Response\fP objects via \fI\%Nghttpx::Env#req\fP
and \fI\%Nghttpx::Env#resp\fP respectively.
.INDENT 0.0
.TP
.B classmethod .Nghttpx.run(&block)
Run request or response phase hook with given \fIblock\fP\&.
\fI\%Nghttpx::Env\fP object is passed to the given block.
.UNINDENT
To specify mruby script file, use \fB\-\-mruby\-file\fP option. The
script will be evaluated once per thread on startup, and it must
instantiate object and evaluate it as the return value (e.g.,
\fBApp.new\fP). This object is called app object. If app object
defines \fBon_req\fP method, it is called with \fI\%Nghttpx::Env\fP
object on request hook. Similarly, if app object defines \fBon_resp\fP
method, it is called with \fI\%Nghttpx::Env\fP object on response
hook. For each method invocation, user can can access
\fI\%Nghttpx::Request\fP and \fI\%Nghttpx::Response\fP objects
via \fI\%Nghttpx::Env#req\fP and \fI\%Nghttpx::Env#resp\fP
respectively.
.INDENT 0.0
.TP
.B Nghttpx::REQUEST_PHASE
@ -1372,16 +1384,19 @@ Modify requet path:
.sp
.nf
.ft C
Nghttpx.run do |env|
class App
def on_req(env)
env.req.path = "/apps#{env.req.path}"
end
end
App.new
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the file containing the above script must be set with
\fI\%\-\-request\-phase\-file\fP option since we modify request path.
Don\(aqt forget to instantiate and evaluate object at the last line.
.sp
Restrict permission of viewing a content to a specific client
addresses:
@ -1390,7 +1405,8 @@ addresses:
.sp
.nf
.ft C
Nghttpx.run do |env|
class App
def on_req(env)
allowed_clients = ["127.0.0.1", "::1"]
if env.req.path.start_with?("/log/") &&
@ -1399,6 +1415,9 @@ Nghttpx.run do |env|
env.resp.return "permission denied"
end
end
end
App.new
.ft P
.fi
.UNINDENT

78
doc/nghttpx.1.rst
View File

@ -272,6 +272,14 @@ Performance
Default: ``16K``
.. option:: --fastopen=<N>
Enables "TCP Fast Open" for the listening socket and
limits the maximum length for the queue of connections
that have not yet completed the three-way handshake. If
value is 0 then fast open is disabled.
Default: ``0``
Timeout
~~~~~~~
@ -287,7 +295,7 @@ Timeout
Specify read timeout for HTTP/1.1 frontend connection.
Default: ``3m``
Default: ``1m``
.. option:: --frontend-write-timeout=<DURATION>
@ -313,7 +321,7 @@ Timeout
Specify read timeout for backend connection.
Default: ``3m``
Default: ``1m``
.. option:: --backend-write-timeout=<DURATION>
@ -422,7 +430,10 @@ SSL/TLS
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.
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".
Default: ``TLSv1.2,TLSv1.1``
@ -911,15 +922,18 @@ SIGUSR2
.. note::
nghttpx consists of 2 processes: one process for processing these
signals, and another one for processing requests. The former spawns
the latter. The former is called master process, and the latter is
called worker process. The above signal must be sent to the master
process. If the worker process receives one of them, it is ignored.
This behaviour of worker process may change in the future release.
In other words, in the future release, worker process may terminate
upon the reception of these signals. Therefore these signals should
not be sent to the worker process.
nghttpx consists of multiple processes: one process for processing
these signals, and another one for processing requests. The former
spawns the latter. The former is called master process, and the
latter is called worker process. If neverbleed is enabled, the
worker process spawns neverbleed daemon process which does RSA key
processing. The above signal must be sent to the master process.
If the other processes received one of them, it is ignored. This
behaviour of these processes may change in the future release. In
other words, in the future release, the processes other than master
process may terminate upon the reception of these signals.
Therefore these signals should not be sent to the processes other
than master process.
SERVER PUSH
-----------
@ -1049,23 +1063,20 @@ server. These hooks allows users to modify header fields, or common
HTTP variables, like authority or request path, and even return custom
response without forwarding request to backend servers.
To set request phase hook, use :option:`--request-phase-file` option.
To set response phase hook, use :option:`--response-phase-file`
option.
For request and response phase hook, user calls :rb:meth:`Nghttpx.run`
with block. The :rb:class:`Nghttpx::Env` is passed to the block.
User can can access :rb:class:`Nghttpx::Request` and
:rb:class:`Nghttpx::Response` objects via :rb:attr:`Nghttpx::Env#req`
and :rb:attr:`Nghttpx::Env#resp` respectively.
To specify mruby script file, use :option:`--mruby-file` option. The
script will be evaluated once per thread on startup, and it must
instantiate object and evaluate it as the return value (e.g.,
``App.new``). This object is called app object. If app object
defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env`
object on request hook. Similarly, if app object defines ``on_resp``
method, it is called with :rb:class:`Nghttpx::Env` object on response
hook. For each method invocation, user can can access
:rb:class:`Nghttpx::Request` and :rb:class:`Nghttpx::Response` objects
via :rb:attr:`Nghttpx::Env#req` and :rb:attr:`Nghttpx::Env#resp`
respectively.
.. rb:module:: Nghttpx
.. rb:classmethod:: run(&block)
Run request or response phase hook with given *block*.
:rb:class:`Nghttpx::Env` object is passed to the given block.
.. rb:const:: REQUEST_PHASE
Constant to represent request phase.
@ -1243,19 +1254,23 @@ Modify requet path:
.. code-block:: ruby
Nghttpx.run do |env|
class App
def on_req(env)
env.req.path = "/apps#{env.req.path}"
end
end
Note that the file containing the above script must be set with
:option:`--request-phase-file` option since we modify request path.
App.new
Don't forget to instantiate and evaluate object at the last line.
Restrict permission of viewing a content to a specific client
addresses:
.. code-block:: ruby
Nghttpx.run do |env|
class App
def on_req(env)
allowed_clients = ["127.0.0.1", "::1"]
if env.req.path.start_with?("/log/") &&
@ -1264,6 +1279,9 @@ addresses:
env.resp.return "permission denied"
end
end
end
App.new
SEE ALSO
--------