Adding upstream version 1.59.0.upstream/1.59.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 434 insertions, 0 deletions

diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst
new file mode 100644
index 0000000..85ed651
--- /dev/null
+++ b/doc/h2load.1.rst
@@ -0,0 +1,434 @@
+
+.. 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:: --alpn-list=<LIST>
+
+    Comma delimited list of  ALPN protocol identifier sorted
+    in the  order of preference.  That  means most desirable
+    protocol comes  first.  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:`--alpn-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)`