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