Provided by: nghttp2-client_1.36.0-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

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

              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.   The   format  of the  string is described in OpenSSL
              ciphers(1).

              Default:
              ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-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=<N>
              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.

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

       -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