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:: -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 261The <SIZE> argument is an integer and an optional unit (e.g., 10K is 26210 * 1024). Units are K, M and G (powers of 1024). 263 264The <DURATION> argument is an integer and an optional unit (e.g., 1s 265is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms 266(hours, minutes, seconds and milliseconds, respectively). If a unit 267is omitted, a second is used as unit. 268 269.. _h2load-1-output: 270 271OUTPUT 272------ 273 274requests 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 297status codes 298 The number of status code h2load received. 299 300traffic 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 316time 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 329time 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 346time 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 361req/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 376FLOW CONTROL 377------------ 378 379h2load sets large flow control window by default, and effectively 380disables flow control to avoid under utilization of server 381performance. To set smaller flow control window, use :option:`-w` and 382:option:`-W` options. For example, use ``-w16 -W16`` to set default 383window size described in HTTP/2 protocol specification. 384 385SEE ALSO 386-------- 387 388:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)` 389