1H2LOAD(1)                           nghttp2                          H2LOAD(1)
2
3
4

NAME

6       h2load - HTTP/2 benchmarking tool
7

SYNOPSIS

9       h2load [OPTIONS]... [URI]...
10

DESCRIPTION

12       benchmarking tool for HTTP/2 server
13
14       <URI>  Specify  URI  to access.   Multiple URIs can be specified.  URIs
15              are used  in this order for each  client.  All  URIs  are  used,
16              then   first  URI  is  used  and then  2nd URI, and so  on.  The
17              scheme, host  and port  in the   subsequent  URIs,  if  present,
18              are  ignored.  Those in  the first URI are used solely.  Defini‐
19              tion of a base URI overrides all scheme, host or port values.
20

OPTIONS

22       -n, --requests=<N>
23              Number of  requests across all  clients.  If it   is  used  with
24              --timing-script-file  option,   this option specifies the number
25              of requests  each client performs rather than the number of  re‐
26              quests   across  all  clients.   This  option is ignored if tim‐
27              ing-based  benchmarking is enabled (see --duration option).
28
29              Default: 1
30
31       -c, --clients=<N>
32              Number  of concurrent  clients.   With  -r option,  this  speci‐
33              fies the maximum number of connections to be made.
34
35              Default: 1
36
37       -t, --threads=<N>
38              Number of native threads.
39
40              Default: 1
41
42       -i, --input-file=<PATH>
43              Path  of  a file with multiple URIs are separated by EOLs.  This
44              option will disable URIs getting from command-line.  If  '-'  is
45              given  as  <PATH>,  URIs will be read from stdin.  URIs are used
46              in this order for each  client.  All URIs are used, then   first
47              URI  is  used  and then  2nd URI, and so  on.  The  scheme, host
48              and port  in the  subsequent URIs,  if  present,   are  ignored.
49              Those  in   the first URI are used solely.  Definition of a base
50              URI overrides all scheme, host or port values.
51
52       -m, --max-concurrent-streams=<N>
53              Max   concurrent   streams   to  issue   per   session.     When
54              http/1.1   is  used,  this  specifies the  number of  HTTP pipe‐
55              lining requests in-flight.
56
57              Default: 1
58
59       -f, --max-frame-size=<SIZE>
60              Maximum frame size that the local endpoint  is  willing  to  re‐
61              ceive.
62
63              Default: 16K
64
65       -w, --window-bits=<N>
66              Sets  the  stream  level initial window size to (2**<N>)-1.  For
67              QUIC, <N> is capped to 26 (roughly 64MiB).
68
69              Default: 30
70
71       -W, --connection-window-bits=<N>
72              Sets   the   connection   level    initial   window   size    to
73              (2**<N>)-1.
74
75              Default: 30
76
77       -H, --header=<HEADER>
78              Add/Override a header to the requests.
79
80       --ciphers=<SUITE>
81              Set  allowed cipher  list  for TLSv1.2  or earlier.   The format
82              of the string is described in OpenSSL ciphers(1).
83
84              Default:
85              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
86
87       --tls13-ciphers=<SUITE>
88              Set allowed cipher list for  TLSv1.3.  The format of the  string
89              is described in OpenSSL ciphers(1).
90
91              Default:
92              TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
93
94       -p, --no-tls-proto=<PROTOID>
95              Specify ALPN identifier of the  protocol to be used when access‐
96              ing http URI without  SSL/TLS.   Available  protocols:  h2c  and
97              http/1.1
98
99              Default: h2c
100
101       -d, --data=<PATH>
102              Post  FILE  to  server.  The request method  is changed to POST.
103              For  http/1.1 connection,  if  -d  is used,  the maximum  number
104              of in-flight pipelined requests is set to 1.
105
106       -r, --rate=<N>
107              Specifies   the   fixed   rate  at  which  connections  are cre‐
108              ated.   The   rate  must   be  a   positive  integer, represent‐
109              ing  the   number  of   connections to be  made per rate period.
110              The maximum  number of connections  to be made   is   given   in
111              -c    option.    This  rate  will  be distributed among  threads
112              as  evenly as  possible.  For example,  with   -t2   and    -r4,
113              each  thread   gets  2 connections per period.  When the rate is
114              0, the program will run  as it  normally does, creating  connec‐
115              tions  at  whatever  variable rate it  wants.  The default value
116              for this option is 0.  -r and -D are mutually exclusive.
117
118       --rate-period=<DURATION>
119              Specifies the time  period between  creating  connections.   The
120              period   must  be a positive  number, representing the length of
121              the period in time.  This option is ignored if the  rate  option
122              is not used.  The default value for this option is 1s.
123
124       -D, --duration=<DURATION>
125              Specifies the main duration for the measurements in case of tim‐
126              ing-based  benchmarking.  -D  and -r  are mutually exclusive.
127
128       --warm-up-time=<DURATION>
129              Specifies the  time  period  before  starting  the  actual  mea‐
130              surements,  in   case   of  timing-based benchmarking.  Needs to
131              provided along with -D option.
132
133       -T, --connection-active-timeout=<DURATION>
134              Specifies  the maximum  time that  h2load is  willing to keep  a
135              connection  open,   regardless  of the  activity on said connec‐
136              tion.  <DURATION> must be a  positive  integer,  specifying  the
137              amount  of time  to wait.  When no timeout value is  set (either
138              active or inactive),  h2load will keep  a  connection  open  in‐
139              definitely,  waiting  for  a response.
140
141       -N, --connection-inactivity-timeout=<DURATION>
142              Specifies the amount  of time that h2load  is willing to wait to
143              see activity  on a given  connection.   <DURATION>  must   be  a
144              positive  integer,   specifying  the   amount  of time  to wait.
145              When no  timeout value  is set   (either  active  or  inactive),
146              h2load   will keep a connection open indefinitely, waiting for a
147              response.
148
149       --timing-script-file=<PATH>
150              Path of a file containing one or more lines separated  by  EOLs.
151              Each  script  line is composed of two tab-separated fields.  The
152              first field represents the time offset from the start of  execu‐
153              tion,  expressed  as  a positive value of milliseconds  with mi‐
154              crosecond  resolution.  The  second field  represents  the  URI.
155              This  option  will  disable URIs getting from  command-line.  If
156              '-' is  given as <PATH>, script lines will be read  from  stdin.
157              Script  lines  are  used  in  order  for each client.   If -n is
158              given, it must be less  than or  equal to the  number of  script
159              lines,  larger values are clamped to the number of script lines.
160              If -n is not given,  the number of requests will default to  the
161              number of  script lines.   The scheme,  host and port defined in
162              the first URI are  used solely.   Values  contained   in   other
163              URIs,   if   present,   are  ignored.  Definition of a  base URI
164              overrides    all     scheme,    host    or    port       values.
165              --timing-script-file   and  --rps   are mutually exclusive.
166
167       -B, --base-uri=(<URI>|unix:<PATH>)
168              Specify  URI  from  which the scheme, host and port will be used
169              for  all requests.   The  base  URI overrides  all  values   de‐
170              fined  either  at  the command  line or  inside input files.  If
171              argument  starts with "unix:", then the rest  of  the   argument
172              will   be treated  as UNIX  domain socket path.   The connection
173              is made  through that path  instead  of  TCP.    In  this  case,
174              scheme   is  inferred from the first  URI appeared  in the  com‐
175              mand line  or inside input files as usual.
176
177       --npn-list=<LIST>
178              Comma delimited list of  ALPN protocol identifier sorted in  the
179              order  of preference.  That  means most desirable protocol comes
180              first.  This  is used  in both  ALPN  and  NPN.   The  parameter
181              must be  delimited by a single comma only  and any  white spaces
182              are  treated as  a part  of protocol string.
183
184              Default: h2,h2-16,h2-14,http/1.1
185
186       --h1   Short          hand            for           --npn-list=http/1.1
187              --no-tls-proto=http/1.1,       which      effectively      force
188              http/1.1 for both http and https URI.
189
190       --header-table-size=<SIZE>
191              Specify decoder header table size.
192
193              Default: 4K
194
195       --encoder-header-table-size=<SIZE>
196              Specify encoder header table size.  The decoder (server)  speci‐
197              fies   the  maximum   dynamic table  size it  accepts.  Then the
198              negotiated dynamic table size is  the  minimum  of  this  option
199              value and the value which server specified.
200
201              Default: 4K
202
203       --log-file=<PATH>
204              Write  per-request  information  to a file as tab-separated col‐
205              umns: start  time as  microseconds  since   epoch;  HTTP  status
206              code;  microseconds until end of  response.  More columns may be
207              added later.  Rows are ordered by end-of-  response   time  when
208              using   one worker  thread, but  may appear slightly  out of or‐
209              der with  multiple threads due to buffering.  Status code is  -1
210              for failed streams.
211
212       --qlog-file-base=<PATH>
213              Enable  qlog  output and specify base file name for qlogs.  Qlog
214              is emitted   for  each  connection.   For   a  given  base  name
215              "base",       each      output      file       name      becomes
216              "base.M.N.sqlog" where M is worker ID and N is client  ID  (e.g.
217              "base.0.3.sqlog").  Only effective in QUIC runs.
218
219       --connect-to=<HOST>[:<PORT>]
220              Host  and  port  to  connect   instead of using the authority in
221              <URI>.
222
223       --rps=<N>
224              Specify  request   per  second  for  each   client.   --rps  and
225              --timing-script-file are mutually exclusive.
226
227       --groups=<GROUPS>
228              Specify the supported groups.
229
230              Default: X25519:P-256:P-384:P-521
231
232       --no-udp-gso
233              Disable UDP GSO.
234
235       --max-udp-payload-size=<SIZE>
236              Specify the maximum outgoing UDP datagram payload size.
237
238       --ktls Enable ktls.
239
240       -v, --verbose
241              Output debug information.
242
243       --version
244              Display version information and exit.
245
246       -h, --help
247              Display this help and exit.
248
249       The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
250       * 1024).  Units are K, M and G (powers of 1024).
251
252       The <DURATION> argument is an integer and an optional unit (e.g., 1s is
253       1  second  and  500ms  is  500  milliseconds).  Units are h, m, s or ms
254       (hours, minutes, seconds and milliseconds, respectively).  If a unit is
255       omitted, a second is used as unit.
256

OUTPUT

258       requests
259
260              total  The number of requests h2load was instructed to make.
261
262              started
263                     The number of requests h2load has started.
264
265              done   The number of requests completed.
266
267              succeeded
268                     The number of requests completed successfully.  Only HTTP
269                     status code 2xx or3xx are considered as success.
270
271              failed The number of requests failed, including HTTP level fail‐
272                     ures (non-successful HTTP status code).
273
274              errored
275                     The  number  of  requests  failed,  except for HTTP level
276                     failures.  This is the subset of the number  reported  in
277                     failed  and  most  likely  the  network level failures or
278                     stream was reset by RST_STREAM.
279
280              timeout
281                     The number of requests whose connection timed out  before
282                     they  were  completed.    This  is  the  subset   of  the
283                     number  reported  in errored.
284
285       status codes
286              The number of status code h2load received.
287
288       traffic
289
290              total  The number of bytes received  from  the  server  "on  the
291                     wire".   If requests were made via TLS, this value is the
292                     number of decrypted bytes.
293
294              headers
295                     The  number  of response  header  bytes  from the  server
296                     without  decompression.   The   space savings shows effi‐
297                     ciency  of header compression.  Let decompressed(headers)
298                     to  the  number of bytes used for header fields after de‐
299                     compression.  The space savings is calculated   by  (1  -
300                     headers   /  decompressed(headers)) * 100.  For HTTP/1.1,
301                     this is usually  0.00%, since it  does  not  have  header
302                     compression.   For  HTTP/2, it shows some insightful num‐
303                     bers.
304
305              data   The number of  response  body  bytes  received  from  the
306                     server.
307
308       time for request
309
310              min    The minimum time taken for request and response.
311
312              max    The maximum time taken for request and response.
313
314              mean   The mean time taken for request and response.
315
316              sd     The  standard deviation of the time taken for request and
317                     response.
318
319              +/- sd The fraction of the number of  requests  within  standard
320                     deviation  range  (mean  +/-  sd) against total number of
321                     successful requests.
322
323       time for connect
324
325              min    The minimum time taken to connect to a  server  including
326                     TLS handshake.
327
328              max    The  maximum  time taken to connect to a server including
329                     TLS handshake.
330
331              mean   The mean time taken to connect to a server including  TLS
332                     handshake.
333
334              sd     The  standard deviation of the time taken to connect to a
335                     server.
336
337              +/- sd The  fraction  of  the   number  of  connections   within
338                     standard  deviation  range  (mean   +/- sd) against total
339                     number of successful connections.
340
341       time for 1st byte (of (decrypted in case of TLS) application data)
342
343              min    The minimum time taken to get 1st byte from a server.
344
345              max    The maximum time taken to get 1st byte from a server.
346
347              mean   The mean time taken to get 1st byte from a server.
348
349              sd     The standard deviation of the time taken to get 1st  byte
350                     from a server.
351
352              +/- sd The fraction of the number of connections within standard
353                     deviation range (mean +/- sd)  against  total  number  of
354                     successful connections.
355
356       req/s
357
358              min    The minimum request per second among all clients.
359
360              max    The maximum request per second among all clients.
361
362              mean   The mean request per second among all clients.
363
364              sd     The  standard  deviation  of request per second among all
365                     clients.  server.
366
367              +/- sd The fraction of the number of connections within standard
368                     deviation  range  (mean  +/-  sd) against total number of
369                     successful connections.
370

FLOW CONTROL

372       h2load sets large flow control window by default, and effectively  dis‐
373       ables  flow  control  to avoid under utilization of server performance.
374       To set smaller flow control window, use -w and -W options.   For  exam‐
375       ple,  use -w16 -W16 to set default window size described in HTTP/2 pro‐
376       tocol specification.
377

SEE ALSO

379       nghttp(1), nghttpd(1), nghttpx(1)
380

AUTHOR

382       Tatsuhiro Tsujikawa
383
385       2012, 2015, 2016, Tatsuhiro Tsujikawa
386
387
388
389
3901.55.1                           Jul 14, 2023                        H2LOAD(1)
Impressum