Provided by: nghttp2-client_1.55.1-1ubuntu0.2_amd64 bug

NAME

       h2load - HTTP/2 benchmarking tool

SYNOPSIS

       h2load [OPTIONS]... [URI]...

DESCRIPTION

       benchmarking tool for HTTP/2 server

       <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

       -n, --requests=<N>
              Number  of  requests across all  clients.  If it  is used with --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 --duration option).

              Default: 1

       -c, --clients=<N>
              Number  of concurrent  clients.   With  -r  option,   this  specifies  the  maximum
              number of connections to be made.

              Default: 1

       -t, --threads=<N>
              Number of native threads.

              Default: 1

       -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.

       -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

       -f, --max-frame-size=<SIZE>
              Maximum frame size that the local endpoint is willing to receive.

              Default: 16K

       -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

       -W, --connection-window-bits=<N>
              Sets  the  connection  level   initial  window  size  to (2**<N>)-1.

              Default: 30

       -H, --header=<HEADER>
              Add/Override a header to the requests.

       --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

       --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

       -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

       -d, --data=<PATH>
              Post  FILE  to   server.   The  request method  is changed to POST.   For  http/1.1
              connection,  if  -d  is used,  the maximum number of in-flight  pipelined  requests
              is set to 1.

       -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  -c   option.   This  rate  will  be distributed among  threads  as   evenly  as
              possible.  For example,  with   -t2  and   -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.  -r and -D are mutually exclusive.

       --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.

       -D, --duration=<DURATION>
              Specifies  the  main  duration  for  the  measurements  in  case  of   timing-based
              benchmarking.  -D  and -r  are mutually exclusive.

       --warm-up-time=<DURATION>
              Specifies the  time  period  before  starting the actual measurements, in  case  of
              timing-based benchmarking.  Needs to provided along with -D 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.

       -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.

       --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  -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 -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.   --timing-script-file   and  --rps    are  mutually
              exclusive.

       -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.

       --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

       --h1   Short         hand          for        --npn-list=http/1.1 --no-tls-proto=http/1.1,
              which   effectively    force http/1.1 for both http and https URI.

       --header-table-size=<SIZE>
              Specify decoder header table size.

              Default: 4K

       --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

       --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.

       --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.

       --connect-to=<HOST>[:<PORT>]
              Host and port to connect  instead of using the authority in <URI>.

       --rps=<N>
              Specify  request   per second for each  client.  --rps and --timing-script-file are
              mutually exclusive.

       --groups=<GROUPS>
              Specify the supported groups.

              Default: X25519:P-256:P-384:P-521

       --no-udp-gso
              Disable UDP GSO.

       --max-udp-payload-size=<SIZE>
              Specify the maximum outgoing UDP datagram payload size.

       --ktls Enable ktls.

       -v, --verbose
              Output debug information.

       --version
              Display version information and exit.

       -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.

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 -w
       and -W options.  For example, use -w16 -W16 to set default window size described in HTTP/2
       protocol specification.

SEE ALSO

       nghttp(1), nghttpd(1), nghttpx(1)

AUTHOR

       Tatsuhiro Tsujikawa

COPYRIGHT

       2012, 2015, 2016, Tatsuhiro Tsujikawa