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