diff options
Diffstat (limited to 'doc/h2load.1.rst')
| -rw-r--r-- | doc/h2load.1.rst | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst new file mode 100644 index 0000000..0f65849 --- /dev/null +++ b/doc/h2load.1.rst @@ -0,0 +1,435 @@ + +.. GENERATED by help2rst.py. DO NOT EDIT DIRECTLY. + +.. program:: h2load + +h2load(1) +========= + +SYNOPSIS +-------- + +**h2load** [OPTIONS]... [URI]... + +DESCRIPTION +----------- + +benchmarking tool for HTTP/2 server + +.. describe:: <URI> + + Specify URI to access. Multiple URIs can be specified. + 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 + URIs, if present, are ignored. Those in the first URI + are used solely. Definition of a base URI overrides all + scheme, host or port values. + +OPTIONS +------- + +.. option:: -n, --requests=<N> + + 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. This option + is ignored if timing-based benchmarking is enabled (see + :option:`--duration` option). + + Default: ``1`` + +.. option:: -c, --clients=<N> + + Number of concurrent clients. With :option:`-r` option, this + specifies the maximum number of connections to be made. + + Default: ``1`` + +.. option:: -t, --threads=<N> + + Number of native threads. + + Default: ``1`` + +.. 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 <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 + URIs, if present, are ignored. Those in the first URI + are used solely. Definition of a base URI overrides all + scheme, host or port values. + +.. option:: -m, --max-concurrent-streams=<N> + + Max concurrent streams to issue per session. When + http/1.1 is used, this specifies the number of HTTP + pipelining requests in-flight. + + Default: ``1`` + +.. option:: -f, --max-frame-size=<SIZE> + + Maximum frame size that the local endpoint is willing to + receive. + + Default: ``16K`` + +.. option:: -w, --window-bits=<N> + + Sets the stream level initial window size to (2\*\*<N>)-1. + For QUIC, <N> is capped to 26 (roughly 64MiB). + + Default: ``30`` + +.. option:: -W, --connection-window-bits=<N> + + Sets the connection level initial window size to + (2\*\*<N>)-1. + + Default: ``30`` + +.. option:: -H, --header=<HEADER> + + Add/Override a header to the requests. + +.. option:: --ciphers=<SUITE> + + Set allowed cipher list for TLSv1.2 or earlier. The + format of the string is described in OpenSSL ciphers(1). + + Default: ``ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384`` + +.. option:: --tls13-ciphers=<SUITE> + + Set allowed cipher list for TLSv1.3. The format of the + string is described in OpenSSL ciphers(1). + + Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256`` + +.. option:: -p, --no-tls-proto=<PROTOID> + + Specify ALPN identifier of the protocol to be used when + accessing http URI without SSL/TLS. + Available protocols: h2c and http/1.1 + + Default: ``h2c`` + +.. option:: -d, --data=<PATH> + + Post FILE to server. The request method is changed to + POST. For http/1.1 connection, if :option:`-d` is used, the + maximum number of in-flight pipelined requests is set to + 1. + +.. option:: -r, --rate=<N> + + 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 + 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:`-t`\2 and :option:`-r`\4, 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:`-r` and :option:`\-D` are mutually exclusive. + +.. option:: --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. + +.. option:: -D, --duration=<DURATION> + + Specifies the main duration for the measurements in case + of timing-based benchmarking. :option:`-D` and :option:`\-r` are mutually + exclusive. + +.. option:: --warm-up-time=<DURATION> + + Specifies the time period before starting the actual + measurements, in case of timing-based benchmarking. + Needs to provided along with :option:`-D` option. + +.. 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. <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=<DURATION> + + Specifies the amount of time that h2load is willing to + 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> + + 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 <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. :option:`--timing-script-file` and :option:`\--rps` are + mutually exclusive. + +.. option:: -B, --base-uri=(<URI>|unix:<PATH>) + + Specify URI from which the scheme, host and port will be + used for all requests. The base URI overrides all + values defined either at the command line or inside + input files. If argument starts with "unix:", then the + rest of the argument will be treated as UNIX domain + socket path. The connection is made through that path + instead of TCP. In this case, scheme is inferred from + the first URI appeared in the command line or inside + input files as usual. + +.. option:: --npn-list=<LIST> + + Comma delimited list of ALPN protocol identifier sorted + in the order of preference. That means most desirable + protocol comes first. This is used in both ALPN and + NPN. The parameter must be delimited by a single comma + only and any white spaces are treated as a part of + protocol string. + + Default: ``h2,h2-16,h2-14,http/1.1`` + +.. option:: --h1 + + Short hand for :option:`--npn-list`\=http/1.1 + :option:`--no-tls-proto`\=http/1.1, which effectively force + http/1.1 for both http and https URI. + +.. option:: --header-table-size=<SIZE> + + Specify decoder header table size. + + Default: ``4K`` + +.. option:: --encoder-header-table-size=<SIZE> + + Specify encoder header table size. The decoder (server) + specifies the maximum dynamic table size it accepts. + Then the negotiated dynamic table size is the minimum of + this option value and the value which server specified. + + Default: ``4K`` + +.. option:: --log-file=<PATH> + + Write per-request information to a file as tab-separated + columns: start time as microseconds since epoch; HTTP + status code; microseconds until end of response. More + columns may be added later. Rows are ordered by end-of- + response time when using one worker thread, but may + appear slightly out of order with multiple threads due + to buffering. Status code is -1 for failed streams. + +.. option:: --qlog-file-base=<PATH> + + Enable qlog output and specify base file name for qlogs. + Qlog is emitted for each connection. For a given base + name "base", each output file name becomes + "base.M.N.sqlog" where M is worker ID and N is client ID + (e.g. "base.0.3.sqlog"). Only effective in QUIC runs. + +.. option:: --connect-to=<HOST>[:<PORT>] + + Host and port to connect instead of using the authority + in <URI>. + +.. option:: --rps=<N> + + Specify request per second for each client. :option:`--rps` and + :option:`--timing-script-file` are mutually exclusive. + +.. option:: --groups=<GROUPS> + + Specify the supported groups. + + Default: ``X25519:P-256:P-384:P-521`` + +.. option:: --no-udp-gso + + Disable UDP GSO. + +.. option:: --max-udp-payload-size=<SIZE> + + Specify the maximum outgoing UDP datagram payload size. + +.. option:: --ktls + + Enable ktls. + +.. option:: -v, --verbose + + Output debug information. + +.. option:: --version + + Display version information and exit. + +.. option:: -h, --help + + Display this help and exit. + + + +The <SIZE> argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). + +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. + +.. _h2load-1-output: + +OUTPUT +------ + +requests + total + The number of requests h2load was instructed to make. + started + The number of requests h2load has started. + done + The number of requests completed. + succeeded + The number of requests completed successfully. Only HTTP status + code 2xx or3xx are considered as success. + failed + The number of requests failed, including HTTP level failures + (non-successful HTTP status code). + errored + The number of requests failed, except for HTTP level failures. + This is the subset of the number reported in ``failed`` and most + likely the network level failures or stream was reset by + RST_STREAM. + timeout + The number of requests whose connection timed out before they were + completed. This is the subset of the number reported in + ``errored``. + +status codes + The number of status code h2load received. + +traffic + total + The number of bytes received from the server "on the wire". If + requests were made via TLS, this value is the number of decrypted + bytes. + headers + The number of response header bytes from the server without + decompression. The ``space savings`` shows efficiency of header + compression. Let ``decompressed(headers)`` to the number of bytes + used for header fields after decompression. The ``space savings`` + is calculated by (1 - ``headers`` / ``decompressed(headers)``) * + 100. For HTTP/1.1, this is usually 0.00%, since it does not have + header compression. For HTTP/2, it shows some insightful numbers. + data + The number of response body bytes received from the server. + +time for request + min + The minimum time taken for request and response. + max + The maximum time taken for request and response. + mean + The mean time taken for request and response. + sd + The standard deviation of the time taken for request and response. + +/- sd + The fraction of the number of requests within standard deviation + range (mean +/- sd) against total number of successful requests. + +time for connect + min + The minimum time taken to connect to a server including TLS + handshake. + max + The maximum time taken to connect to a server including TLS + handshake. + mean + The mean time taken to connect to a server including TLS + handshake. + sd + The standard deviation of the time taken to connect to a server. + +/- sd + The fraction of the number of connections within standard + deviation range (mean +/- sd) against total number of successful + connections. + +time for 1st byte (of (decrypted in case of TLS) application data) + min + The minimum time taken to get 1st byte from a server. + max + The maximum time taken to get 1st byte from a server. + mean + The mean time taken to get 1st byte from a server. + sd + The standard deviation of the time taken to get 1st byte from a + server. + +/- sd + The fraction of the number of connections within standard + deviation range (mean +/- sd) against total number of successful + connections. + +req/s + min + The minimum request per second among all clients. + max + The maximum request per second among all clients. + mean + The mean request per second among all clients. + sd + The standard deviation of request per second among all clients. + server. + +/- sd + The fraction of the number of connections within standard + deviation range (mean +/- sd) against total number of successful + connections. + +FLOW CONTROL +------------ + +h2load sets large flow control window by default, and effectively +disables flow control to avoid under utilization of server +performance. To set smaller flow control window, use :option:`-w` and +:option:`-W` options. For example, use ``-w16 -W16`` to set default +window size described in HTTP/2 protocol specification. + +SEE ALSO +-------- + +:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)` |