doc/h2load.1

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