doc/h2load.1.rst

   1
   2 .. GENERATED by help2rst.py.  DO NOT EDIT DIRECTLY.
   3
   4 .. program:: h2load
   5
   6 h2load(1)
   7 =========
   8
   9 SYNOPSIS
  10 --------
  11
  12 **h2load** [OPTIONS]... [URI]...
  13
  14 DESCRIPTION
  15 -----------
  16
  17 benchmarking tool for HTTP/2 server
  18
  19 .. describe:: <URI>
  20
  21     Specify URI to access.   Multiple URIs can be specified.
  22     URIs are used  in this order for each  client.  All URIs
  23     are used, then  first URI is used and then  2nd URI, and
  24     so  on.  The  scheme, host  and port  in the  subsequent
  25     URIs, if present,  are ignored.  Those in  the first URI
  26     are used solely.  Definition of a base URI overrides all
  27     scheme, host or port values.
  28
  29 OPTIONS
  30 -------
  31
  32 .. option:: -n, --requests=<N>
  33
  34     Number of  requests across all  clients.  If it  is used
  35     with :option:`--timing-script-file` option,  this option specifies
  36     the number of requests  each client performs rather than
  37     the number of requests  across all clients.  This option
  38     is ignored if timing-based  benchmarking is enabled (see
  39     :option:`--duration` option).
  40
  41     Default: ``1``
  42
  43 .. option:: -c, --clients=<N>
  44
  45     Number  of concurrent  clients.   With  :option:`-r` option,  this
  46     specifies the maximum number of connections to be made.
  47
  48     Default: ``1``
  49
  50 .. option:: -t, --threads=<N>
  51
  52     Number of native threads.
  53
  54     Default: ``1``
  55
  56 .. option:: -i, --input-file=<PATH>
  57
  58     Path of a file with multiple URIs are separated by EOLs.
  59     This option will disable URIs getting from command-line.
  60     If '-' is given as <PATH>, URIs will be read from stdin.
  61     URIs are used  in this order for each  client.  All URIs
  62     are used, then  first URI is used and then  2nd URI, and
  63     so  on.  The  scheme, host  and port  in the  subsequent
  64     URIs, if present,  are ignored.  Those in  the first URI
  65     are used solely.  Definition of a base URI overrides all
  66     scheme, host or port values.
  67
  68 .. option:: -m, --max-concurrent-streams=<N>
  69
  70     Max  concurrent  streams  to issue  per  session.   When
  71     http/1.1  is used,  this  specifies the  number of  HTTP
  72     pipelining requests in-flight.
  73
  74     Default: ``1``
  75
  76 .. option:: -w, --window-bits=<N>
  77
  78     Sets the stream level initial window size to (2\*\*<N>)-1.
  79     For QUIC, <N> is capped to 26 (roughly 64MiB).
  80
  81     Default: ``30``
  82
  83 .. option:: -W, --connection-window-bits=<N>
  84
  85     Sets  the  connection  level   initial  window  size  to
  86     (2\*\*<N>)-1.
  87
  88     Default: ``30``
  89
  90 .. option:: -H, --header=<HEADER>
  91
  92     Add/Override a header to the requests.
  93
  94 .. option:: --ciphers=<SUITE>
  95
  96     Set  allowed cipher  list  for TLSv1.2  or ealier.   The
  97     format of the string is described in OpenSSL ciphers(1).
  98
  99     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``
 100
 101 .. option:: --tls13-ciphers=<SUITE>
 102
 103     Set allowed cipher list for  TLSv1.3.  The format of the
 104     string is described in OpenSSL ciphers(1).
 105
 106     Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256``
 107
 108 .. option:: -p, --no-tls-proto=<PROTOID>
 109
 110     Specify ALPN identifier of the  protocol to be used when
 111     accessing http URI without SSL/TLS.
 112     Available protocols: h2c and http/1.1
 113
 114     Default: ``h2c``
 115
 116 .. option:: -d, --data=<PATH>
 117
 118     Post FILE to  server.  The request method  is changed to
 119     POST.   For  http/1.1 connection,  if  :option:`-d`  is used,  the
 120     maximum number of in-flight pipelined requests is set to
 121     1.
 122
 123 .. option:: -r, --rate=<N>
 124
 125     Specifies  the  fixed  rate  at  which  connections  are
 126     created.   The   rate  must   be  a   positive  integer,
 127     representing the  number of  connections to be  made per
 128     rate period.   The maximum  number of connections  to be
 129     made  is  given  in  :option:`-c`   option.   This  rate  will  be
 130     distributed among  threads as  evenly as  possible.  For
 131     example,  with   :option:`-t`\2  and   :option:`-r`\4,  each  thread   gets  2
 132     connections per period.  When the rate is 0, the program
 133     will run  as it  normally does, creating  connections at
 134     whatever variable rate it  wants.  The default value for
 135     this option is 0.  :option:`-r` and :option:`\-D` are mutually exclusive.
 136
 137 .. option:: --rate-period=<DURATION>
 138
 139     Specifies the time  period between creating connections.
 140     The period  must be a positive  number, representing the
 141     length of the period in time.  This option is ignored if
 142     the rate option is not used.  The default value for this
 143     option is 1s.
 144
 145 .. option:: -D, --duration=<DURATION>
 146
 147     Specifies the main duration for the measurements in case
 148     of timing-based  benchmarking.  :option:`-D`  and :option:`\-r`  are mutually
 149     exclusive.
 150
 151 .. option:: --warm-up-time=<DURATION>
 152
 153     Specifies the  time  period  before  starting the actual
 154     measurements, in  case  of  timing-based benchmarking.
 155     Needs to provided along with :option:`-D` option.
 156
 157 .. option:: -T, --connection-active-timeout=<DURATION>
 158
 159     Specifies  the maximum  time that  h2load is  willing to
 160     keep a  connection open,  regardless of the  activity on
 161     said connection.  <DURATION> must be a positive integer,
 162     specifying the amount of time  to wait.  When no timeout
 163     value is  set (either  active or inactive),  h2load will
 164     keep  a  connection  open indefinitely,  waiting  for  a
 165     response.
 166
 167 .. option:: -N, --connection-inactivity-timeout=<DURATION>
 168
 169     Specifies the amount  of time that h2load  is willing to
 170     wait to see activity  on a given connection.  <DURATION>
 171     must  be a  positive integer,  specifying the  amount of
 172     time  to wait.   When no  timeout value  is set  (either
 173     active or inactive), h2load  will keep a connection open
 174     indefinitely, waiting for a response.
 175
 176 .. option:: --timing-script-file=<PATH>
 177
 178     Path of a file containing one or more lines separated by
 179     EOLs.  Each script line is composed of two tab-separated
 180     fields.  The first field represents the time offset from
 181     the start of execution, expressed as a positive value of
 182     milliseconds  with microsecond  resolution.  The  second
 183     field represents the URI.  This option will disable URIs
 184     getting from  command-line.  If '-' is  given as <PATH>,
 185     script lines will be read  from stdin.  Script lines are
 186     used in order for each client.   If :option:`-n` is given, it must
 187     be less  than or  equal to the  number of  script lines,
 188     larger values are clamped to the number of script lines.
 189     If :option:`-n` is not given,  the number of requests will default
 190     to the  number of  script lines.   The scheme,  host and
 191     port defined in  the first URI are  used solely.  Values
 192     contained  in  other  URIs,  if  present,  are  ignored.
 193     Definition of a  base URI overrides all  scheme, host or
 194     port   values.   :option:`--timing-script-file`   and  :option:`\--rps`   are
 195     mutually exclusive.
 196
 197 .. option:: -B, --base-uri=(<URI>|unix:<PATH>)
 198
 199     Specify URI from which the scheme, host and port will be
 200     used  for  all requests.   The  base  URI overrides  all
 201     values  defined either  at  the command  line or  inside
 202     input files.  If argument  starts with "unix:", then the
 203     rest  of the  argument will  be treated  as UNIX  domain
 204     socket path.   The connection is made  through that path
 205     instead of TCP.   In this case, scheme  is inferred from
 206     the first  URI appeared  in the  command line  or inside
 207     input files as usual.
 208
 209 .. option:: --npn-list=<LIST>
 210
 211     Comma delimited list of  ALPN protocol identifier sorted
 212     in the  order of preference.  That  means most desirable
 213     protocol comes  first.  This  is used  in both  ALPN and
 214     NPN.  The parameter must be  delimited by a single comma
 215     only  and any  white spaces  are  treated as  a part  of
 216     protocol string.
 217
 218     Default: ``h2,h2-16,h2-14,http/1.1``
 219
 220 .. option:: --h1
 221
 222     Short        hand         for        :option:`--npn-list`\=http/1.1
 223     :option:`--no-tls-proto`\=http/1.1,    which   effectively    force
 224     http/1.1 for both http and https URI.
 225
 226 .. option:: --header-table-size=<SIZE>
 227
 228     Specify decoder header table size.
 229
 230     Default: ``4K``
 231
 232 .. option:: --encoder-header-table-size=<SIZE>
 233
 234     Specify encoder header table size.  The decoder (server)
 235     specifies  the maximum  dynamic table  size it  accepts.
 236     Then the negotiated dynamic table size is the minimum of
 237     this option value and the value which server specified.
 238
 239     Default: ``4K``
 240
 241 .. option:: --log-file=<PATH>
 242
 243     Write per-request information to a file as tab-separated
 244     columns: start  time as  microseconds since  epoch; HTTP
 245     status code;  microseconds until end of  response.  More
 246     columns may be added later.  Rows are ordered by end-of-
 247     response  time when  using  one worker  thread, but  may
 248     appear slightly  out of order with  multiple threads due
 249     to buffering.  Status code is -1 for failed streams.
 250
 251 .. option:: --qlog-file-base=<PATH>
 252
 253     Enable qlog output and specify base file name for qlogs.
 254     Qlog  is emitted  for each connection.
 255     For  a  given  base  name "base", each  output file name
 256     becomes  "base.M.N.qlog"  where M is worker ID  and N is
 257     client ID (e.g. "base.0.3.qlog").
 258     Only effective in QUIC runs.
 259
 260 .. option:: --connect-to=<HOST>[:<PORT>]
 261
 262     Host and port to connect  instead of using the authority
 263     in <URI>.
 264
 265 .. option:: --rps=<N>
 266
 267     Specify request  per second for each  client.  :option:`--rps` and
 268     :option:`--timing-script-file` are mutually exclusive.
 269
 270 .. option:: --groups=<GROUPS>
 271
 272     Specify the supported groups.
 273
 274     Default: ``X25519:P-256:P-384:P-521``
 275
 276 .. option:: --no-udp-gso
 277
 278     Disable UDP GSO.
 279
 280 .. option:: --max-udp-payload-size=<SIZE>
 281
 282     Specify the maximum outgoing UDP datagram payload size.
 283
 284 .. option:: -v, --verbose
 285
 286     Output debug information.
 287
 288 .. option:: --version
 289
 290     Display version information and exit.
 291
 292 .. option:: -h, --help
 293
 294     Display this help and exit.
 295
 296
 297
 298 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
 299 10 * 1024).  Units are K, M and G (powers of 1024).
 300
 301 The <DURATION> argument is an integer and an optional unit (e.g., 1s
 302 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
 303 (hours, minutes, seconds and milliseconds, respectively).  If a unit
 304 is omitted, a second is used as unit.
 305
 306 .. _h2load-1-output:
 307
 308 OUTPUT
 309 ------
 310
 311 requests
 312   total
 313     The number of requests h2load was instructed to make.
 314   started
 315     The number of requests h2load has started.
 316   done
 317     The number of requests completed.
 318   succeeded
 319     The number of requests completed successfully.  Only HTTP status
 320     code 2xx or3xx are considered as success.
 321   failed
 322     The number of requests failed, including HTTP level failures
 323     (non-successful HTTP status code).
 324   errored
 325     The number of requests failed, except for HTTP level failures.
 326     This is the subset of the number reported in ``failed`` and most
 327     likely the network level failures or stream was reset by
 328     RST_STREAM.
 329   timeout
 330     The number of requests whose connection timed out before they were
 331     completed.   This  is  the  subset   of  the  number  reported  in
 332     ``errored``.
 333
 334 status codes
 335   The number of status code h2load received.
 336
 337 traffic
 338   total
 339     The number of bytes received from the server "on the wire".  If
 340     requests were made via TLS, this value is the number of decrypted
 341     bytes.
 342   headers
 343     The  number  of response  header  bytes  from the  server  without
 344     decompression.  The  ``space savings`` shows efficiency  of header
 345     compression.  Let ``decompressed(headers)`` to the number of bytes
 346     used for header fields after decompression.  The ``space savings``
 347     is calculated  by (1 - ``headers``  / ``decompressed(headers)``) *
 348     100.  For HTTP/1.1, this is usually  0.00%, since it does not have
 349     header compression.  For HTTP/2, it shows some insightful numbers.
 350   data
 351     The number of response body bytes received from the server.
 352
 353 time for request
 354   min
 355     The minimum time taken for request and response.
 356   max
 357     The maximum time taken for request and response.
 358   mean
 359     The mean time taken for request and response.
 360   sd
 361     The standard deviation of the time taken for request and response.
 362   +/- sd
 363     The fraction of the number of requests within standard deviation
 364     range (mean +/- sd) against total number of successful requests.
 365
 366 time for connect
 367   min
 368     The minimum time taken to connect to a server including TLS
 369     handshake.
 370   max
 371     The maximum time taken to connect to a server including TLS
 372     handshake.
 373   mean
 374     The mean time taken to connect to a server including TLS
 375     handshake.
 376   sd
 377     The standard deviation of the time taken to connect to a server.
 378   +/- sd
 379     The  fraction  of  the   number  of  connections  within  standard
 380     deviation range (mean  +/- sd) against total  number of successful
 381     connections.
 382
 383 time for 1st byte (of (decrypted in case of TLS) application data)
 384   min
 385     The minimum time taken to get 1st byte from a server.
 386   max
 387     The maximum time taken to get 1st byte from a server.
 388   mean
 389     The mean time taken to get 1st byte from a server.
 390   sd
 391     The standard deviation of the time taken to get 1st byte from a
 392     server.
 393   +/- sd
 394     The fraction of the number of connections within standard
 395     deviation range (mean +/- sd) against total number of successful
 396     connections.
 397
 398 req/s
 399   min
 400     The minimum request per second among all clients.
 401   max
 402     The maximum request per second among all clients.
 403   mean
 404     The mean request per second among all clients.
 405   sd
 406     The standard deviation of request per second among all clients.
 407     server.
 408   +/- sd
 409     The fraction of the number of connections within standard
 410     deviation range (mean +/- sd) against total number of successful
 411     connections.
 412
 413 FLOW CONTROL
 414 ------------
 415
 416 h2load sets large flow control window by default, and effectively
 417 disables flow control to avoid under utilization of server
 418 performance.  To set smaller flow control window, use :option:`-w` and
 419 :option:`-W` options.  For example, use ``-w16 -W16`` to set default
 420 window size described in HTTP/2 protocol specification.
 421
 422 SEE ALSO
 423 --------
 424
 425 :manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`