diff --git a/doc/h2load.1 b/doc/h2load.1 index c6559cb8..671ee865 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -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= -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= -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,64 +145,65 @@ 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= -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 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= +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= +.B \-T, \-\-connection\-active\-timeout= Specifies the maximum time that h2load is willing to keep a connection open, regardless of the activity on -said connection. 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. 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= +.B \-N, \-\-connection\-inactivity\-timeout= Specifies the amount of time that h2load is willing to -wait to see activity on a given connection. 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. +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 \-\-timing\-script\-file= -Path of a file containing one or more lines separated by -EOLs. Each script line is composed of two tab\-separated -fields. The first field represents the time offset from -the start of execution, expressed as a positive value of -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 , -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. +Path of a file containing one or more lines separated by +EOLs. Each script line is composed of two tab\-separated +fields. The first field represents the time offset from +the start of execution, expressed as a positive value of +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 , +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. .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 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 diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst index ae999c7f..0be0dff9 100644 --- a/doc/h2load.1.rst +++ b/doc/h2load.1.rst @@ -31,13 +31,17 @@ OPTIONS .. option:: -n, --requests= - 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= - 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,60 +114,61 @@ 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= +.. option:: --rate-period= - 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 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= +.. option:: -T, --connection-active-timeout= Specifies the maximum time that h2load is willing to keep a connection open, regardless of the activity on - said connection. 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. 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= +.. option:: -N, --connection-inactivity-timeout= Specifies the amount of time that h2load is willing to - wait to see activity on a given connection. 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. + 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 of a file containing one or more lines separated by - EOLs. Each script line is composed of two tab-separated - fields. The first field represents the time offset from - the start of execution, expressed as a positive value of - milliseconds with microsecond resolution. The second - field represents the URI. This option will disable URIs - getting from command-line. If '-' is given as , - 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. + Path of a file containing one or more lines separated by + EOLs. Each script line is composed of two tab-separated + fields. The first field represents the time offset from + the start of execution, expressed as a positive value of + milliseconds with microsecond resolution. The second + field represents the URI. This option will disable URIs + getting from command-line. If '-' is given as , + 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. .. option:: -B, --base-uri= @@ -195,6 +200,13 @@ OPTIONS Display this help and exit. + + +The 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 ------ diff --git a/doc/nghttp.1 b/doc/nghttp.1 index d3ff2fe3..c0f86b72 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -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]... ... .SH DESCRIPTION .sp -HTTP/2 experimental client +HTTP/2 client .INDENT 0.0 .TP .B diff --git a/doc/nghttp.1.rst b/doc/nghttp.1.rst index 71d4d3df..f76bc067 100644 --- a/doc/nghttp.1.rst +++ b/doc/nghttp.1.rst @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -HTTP/2 experimental client +HTTP/2 client .. describe:: diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index e4897359..f698535e 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -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]... [ ] .SH DESCRIPTION .sp -HTTP/2 experimental server +HTTP/2 server .INDENT 0.0 .TP .B diff --git a/doc/nghttpd.1.rst b/doc/nghttpd.1.rst index e9ac30df..29ba9724 100644 --- a/doc/nghttpd.1.rst +++ b/doc/nghttpd.1.rst @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -HTTP/2 experimental server +HTTP/2 server .. describe:: diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 207d0ad6..826e2721 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -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= +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= 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= 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| - env.req.path = "/apps#{env.req.path}" +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,15 +1405,19 @@ addresses: .sp .nf .ft C -Nghttpx.run do |env| - allowed_clients = ["127.0.0.1", "::1"] +class App + def on_req(env) + allowed_clients = ["127.0.0.1", "::1"] - if env.req.path.start_with?("/log/") && - !allowed_clients.include?(env.remote_addr) then - env.resp.status = 404 - env.resp.return "permission denied" + if env.req.path.start_with?("/log/") && + !allowed_clients.include?(env.remote_addr) then + env.resp.status = 404 + env.resp.return "permission denied" + end end end + +App.new .ft P .fi .UNINDENT diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index b2f6e834..0e86b6ac 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -272,6 +272,14 @@ Performance Default: ``16K`` +.. option:: --fastopen= + + 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= @@ -313,7 +321,7 @@ Timeout Specify read timeout for backend connection. - Default: ``3m`` + Default: ``1m`` .. option:: --backend-write-timeout= @@ -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,28 +1254,35 @@ Modify requet path: .. code-block:: ruby - Nghttpx.run do |env| - env.req.path = "/apps#{env.req.path}" + 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| - allowed_clients = ["127.0.0.1", "::1"] + class App + def on_req(env) + allowed_clients = ["127.0.0.1", "::1"] - if env.req.path.start_with?("/log/") && - !allowed_clients.include?(env.remote_addr) then - env.resp.status = 404 - env.resp.return "permission denied" + if env.req.path.start_with?("/log/") && + !allowed_clients.include?(env.remote_addr) then + env.resp.status = 404 + env.resp.return "permission denied" + end end end + App.new + SEE ALSO --------