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:: --alpn-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. The parameter must be delimited 221 by a single comma only and any white spaces are treated 222 as a part of protocol string. 223 224 Default: ``h2,h2-16,h2-14,http/1.1`` 225 226.. option:: --h1 227 228 Short hand for :option:`--alpn-list`\=http/1.1 229 :option:`--no-tls-proto`\=http/1.1, which effectively force 230 http/1.1 for both http and https URI. 231 232.. option:: --header-table-size=<SIZE> 233 234 Specify decoder header table size. 235 236 Default: ``4K`` 237 238.. option:: --encoder-header-table-size=<SIZE> 239 240 Specify encoder header table size. The decoder (server) 241 specifies the maximum dynamic table size it accepts. 242 Then the negotiated dynamic table size is the minimum of 243 this option value and the value which server specified. 244 245 Default: ``4K`` 246 247.. option:: --log-file=<PATH> 248 249 Write per-request information to a file as tab-separated 250 columns: start time as microseconds since epoch; HTTP 251 status code; microseconds until end of response. More 252 columns may be added later. Rows are ordered by end-of- 253 response time when using one worker thread, but may 254 appear slightly out of order with multiple threads due 255 to buffering. Status code is -1 for failed streams. 256 257.. option:: --qlog-file-base=<PATH> 258 259 Enable qlog output and specify base file name for qlogs. 260 Qlog is emitted for each connection. For a given base 261 name "base", each output file name becomes 262 "base.M.N.sqlog" where M is worker ID and N is client ID 263 (e.g. "base.0.3.sqlog"). Only effective in QUIC runs. 264 265.. option:: --connect-to=<HOST>[:<PORT>] 266 267 Host and port to connect instead of using the authority 268 in <URI>. 269 270.. option:: --rps=<N> 271 272 Specify request per second for each client. :option:`--rps` and 273 :option:`--timing-script-file` are mutually exclusive. 274 275.. option:: --groups=<GROUPS> 276 277 Specify the supported groups. 278 279 Default: ``X25519:P-256:P-384:P-521`` 280 281.. option:: --no-udp-gso 282 283 Disable UDP GSO. 284 285.. option:: --max-udp-payload-size=<SIZE> 286 287 Specify the maximum outgoing UDP datagram payload size. 288 289.. option:: --ktls 290 291 Enable ktls. 292 293.. option:: --sni=<DNSNAME> 294 295 Send <DNSNAME> in TLS SNI, overriding the host name 296 specified in URI. 297 298.. option:: -v, --verbose 299 300 Output debug information. 301 302.. option:: --version 303 304 Display version information and exit. 305 306.. option:: -h, --help 307 308 Display this help and exit. 309 310 311 312The <SIZE> argument is an integer and an optional unit (e.g., 10K is 31310 * 1024). Units are K, M and G (powers of 1024). 314 315The <DURATION> argument is an integer and an optional unit (e.g., 1s 316is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms 317(hours, minutes, seconds and milliseconds, respectively). If a unit 318is omitted, a second is used as unit. 319 320.. _h2load-1-output: 321 322OUTPUT 323------ 324 325requests 326 total 327 The number of requests h2load was instructed to make. 328 started 329 The number of requests h2load has started. 330 done 331 The number of requests completed. 332 succeeded 333 The number of requests completed successfully. Only HTTP status 334 code 2xx or3xx are considered as success. 335 failed 336 The number of requests failed, including HTTP level failures 337 (non-successful HTTP status code). 338 errored 339 The number of requests failed, except for HTTP level failures. 340 This is the subset of the number reported in ``failed`` and most 341 likely the network level failures or stream was reset by 342 RST_STREAM. 343 timeout 344 The number of requests whose connection timed out before they were 345 completed. This is the subset of the number reported in 346 ``errored``. 347 348status codes 349 The number of status code h2load received. 350 351traffic 352 total 353 The number of bytes received from the server "on the wire". If 354 requests were made via TLS, this value is the number of decrypted 355 bytes. 356 headers 357 The number of response header bytes from the server without 358 decompression. The ``space savings`` shows efficiency of header 359 compression. Let ``decompressed(headers)`` to the number of bytes 360 used for header fields after decompression. The ``space savings`` 361 is calculated by (1 - ``headers`` / ``decompressed(headers)``) * 362 100. For HTTP/1.1, this is usually 0.00%, since it does not have 363 header compression. For HTTP/2, it shows some insightful numbers. 364 data 365 The number of response body bytes received from the server. 366 367time for request 368 min 369 The minimum time taken for request and response. 370 max 371 The maximum time taken for request and response. 372 mean 373 The mean time taken for request and response. 374 sd 375 The standard deviation of the time taken for request and response. 376 +/- sd 377 The fraction of the number of requests within standard deviation 378 range (mean +/- sd) against total number of successful requests. 379 380time for connect 381 min 382 The minimum time taken to connect to a server including TLS 383 handshake. 384 max 385 The maximum time taken to connect to a server including TLS 386 handshake. 387 mean 388 The mean time taken to connect to a server including TLS 389 handshake. 390 sd 391 The standard deviation of the time taken to connect to a server. 392 +/- sd 393 The fraction of the number of connections within standard 394 deviation range (mean +/- sd) against total number of successful 395 connections. 396 397time for 1st byte (of (decrypted in case of TLS) application data) 398 min 399 The minimum time taken to get 1st byte from a server. 400 max 401 The maximum time taken to get 1st byte from a server. 402 mean 403 The mean time taken to get 1st byte from a server. 404 sd 405 The standard deviation of the time taken to get 1st byte from a 406 server. 407 +/- sd 408 The fraction of the number of connections within standard 409 deviation range (mean +/- sd) against total number of successful 410 connections. 411 412req/s 413 min 414 The minimum request per second among all clients. 415 max 416 The maximum request per second among all clients. 417 mean 418 The mean request per second among all clients. 419 sd 420 The standard deviation of request per second among all clients. 421 server. 422 +/- sd 423 The fraction of the number of connections within standard 424 deviation range (mean +/- sd) against total number of successful 425 connections. 426 427FLOW CONTROL 428------------ 429 430h2load sets large flow control window by default, and effectively 431disables flow control to avoid under utilization of server 432performance. To set smaller flow control window, use :option:`-w` and 433:option:`-W` options. For example, use ``-w16 -W16`` to set default 434window size described in HTTP/2 protocol specification. 435 436SEE ALSO 437-------- 438 439:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)` 440