summaryrefslogtreecommitdiffstats
path: root/doc/nghttp.1
blob: 332d9c68164a50d070094a72bacd7ba7dc418ff0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "NGHTTP" "1" "Jan 21, 2024" "1.59.0" "nghttp2"
.SH NAME
nghttp \- HTTP/2 client
.SH SYNOPSIS
.sp
\fBnghttp\fP [OPTIONS]... <URI>...
.SH DESCRIPTION
.sp
HTTP/2 client
.INDENT 0.0
.TP
.B <URI>
Specify URI to access.
.UNINDENT
.SH OPTIONS
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Print   debug   information   such  as   reception   and
transmission of frames and name/value pairs.  Specifying
this option multiple times increases verbosity.
.UNINDENT
.INDENT 0.0
.TP
.B \-n, \-\-null\-out
Discard downloaded data.
.UNINDENT
.INDENT 0.0
.TP
.B \-O, \-\-remote\-name
Save  download  data  in  the  current  directory.   The
filename is  derived from  URI.  If  URI ends  with \(aq\fI/\fP\(aq,
\(aqindex.html\(aq  is used  as a  filename.  Not  implemented
yet.
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-timeout=<DURATION>
Timeout each request after <DURATION>.  Set 0 to disable
timeout.
.UNINDENT
.INDENT 0.0
.TP
.B \-w, \-\-window\-bits=<N>
Sets the stream level initial window size to 2**<N>\-1.
.UNINDENT
.INDENT 0.0
.TP
.B \-W, \-\-connection\-window\-bits=<N>
Sets  the  connection  level   initial  window  size  to
2**<N>\-1.
.UNINDENT
.INDENT 0.0
.TP
.B \-a, \-\-get\-assets
Download assets  such as stylesheets, images  and script
files linked  from the downloaded resource.   Only links
whose  origins are  the same  with the  linking resource
will be downloaded.   nghttp prioritizes resources using
HTTP/2 dependency  based priority.  The  priority order,
from highest to lowest,  is html itself, css, javascript
and images.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-stat
Print statistics.
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-header=<HEADER>
Add a header to the requests.  Example: \fI\%\-H\fP\(aq:method: PUT\(aq
.UNINDENT
.INDENT 0.0
.TP
.B \-\-trailer=<HEADER>
Add a trailer header to the requests.  <HEADER> must not
include pseudo header field  (header field name starting
with \(aq:\(aq).  To  send trailer, one must use  \fI\%\-d\fP option to
send request body.  Example: \fI\%\-\-trailer\fP \(aqfoo: bar\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cert=<CERT>
Use  the specified  client certificate  file.  The  file
must be in PEM format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-key=<KEY>
Use the  client private key  file.  The file must  be in
PEM format.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-data=<PATH>
Post FILE to server. If \(aq\-\(aq  is given, data will be read
from stdin.
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-multiply=<N>
Request each URI <N> times.  By default, same URI is not
requested twice.  This option disables it too.
.UNINDENT
.INDENT 0.0
.TP
.B \-u, \-\-upgrade
Perform HTTP Upgrade for HTTP/2.  This option is ignored
if the request URI has https scheme.  If \fI\%\-d\fP is used, the
HTTP upgrade request is performed with OPTIONS method.
.UNINDENT
.INDENT 0.0
.TP
.B \-p, \-\-weight=<WEIGHT>
Sets  weight of  given  URI.  This  option  can be  used
multiple times, and  N\-th \fI\%\-p\fP option sets  weight of N\-th
URI in the command line.  If  the number of \fI\%\-p\fP option is
less than the number of URI, the last \fI\%\-p\fP option value is
repeated.  If there is no \fI\%\-p\fP option, default weight, 16,
is assumed.  The valid value range is
[1, 256], inclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \-M, \-\-peer\-max\-concurrent\-streams=<N>
Use  <N>  as  SETTINGS_MAX_CONCURRENT_STREAMS  value  of
remote endpoint as if it  is received in SETTINGS frame.
.sp
Default: \fB100\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-header\-table\-size=<SIZE>
Specify decoder  header table  size.  If this  option is
used  multiple times,  and the  minimum value  among the
given values except  for last one is  strictly less than
the last  value, that minimum  value is set  in SETTINGS
frame  payload  before  the   last  value,  to  simulate
multiple header table size change.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-encoder\-header\-table\-size=<SIZE>
Specify encoder header table size.  The decoder (server)
specifies  the maximum  dynamic table  size it  accepts.
Then the negotiated dynamic table size is the minimum of
this option value and the value which server specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-b, \-\-padding=<N>
Add at  most <N>  bytes to a  frame payload  as padding.
Specify 0 to disable padding.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-har=<PATH>
Output HTTP  transactions <PATH> in HAR  format.  If \(aq\-\(aq
is given, data is written to stdout.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-color
Force colored log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-continuation
Send large header to test CONTINUATION.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-content\-length
Don\(aqt send content\-length header field.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-dep
Don\(aqt send dependency based priority hint to server.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-hexdump
Display the  incoming traffic in  hexadecimal (Canonical
hex+ASCII display).  If SSL/TLS  is used, decrypted data
are used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-push
Disable server push.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-concurrent\-streams=<N>
The  number of  concurrent  pushed  streams this  client
accepts.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-expect\-continue
Perform an Expect/Continue handshake:  wait to send DATA
(up to  a short  timeout)  until the server sends  a 100
Continue interim response. This option is ignored unless
combined with the \fI\%\-d\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-y, \-\-no\-verify\-peer
Suppress  warning  on  server  certificate  verification
failure.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ktls
Enable ktls.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-rfc7540\-pri
Disable RFC7540 priorities.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Display version information and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Display this help and exit.
.UNINDENT
.sp
The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024).  Units are K, M and G (powers of 1024).
.sp
The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively).  If a unit
is omitted, a second is used as unit.
.SH DEPENDENCY BASED PRIORITY
.sp
nghttp sends priority hints to server by default unless
\fI\%\-\-no\-dep\fP is used.  nghttp mimics the way Firefox employs to
manages dependency using idle streams.  We follows the behaviour of
Firefox Nightly as of April, 2015, and nghttp\(aqs behaviour is very
static and could be different from Firefox in detail.  But reproducing
the same behaviour of Firefox is not our goal.  The goal is provide
the easy way to test out the dependency priority in server
implementation.
.sp
When connection is established, nghttp sends 5 PRIORITY frames to idle
streams 3, 5, 7, 9 and 11 to create \(dqanchor\(dq nodes in dependency
tree:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
         +\-\-\-\-\-+
         |id=0 |
         +\-\-\-\-\-+
        ^   ^   ^
 w=201 /    |    \e w=1
      /     |     \e
     / w=101|      \e
 +\-\-\-\-\-+ +\-\-\-\-\-+ +\-\-\-\-\-+
 |id=3 | |id=5 | |id=7 |
 +\-\-\-\-\-+ +\-\-\-\-\-+ +\-\-\-\-\-+
    ^               ^
w=1 |           w=1 |
    |               |
 +\-\-\-\-\-+         +\-\-\-\-\-+
 |id=11|         |id=9 |
 +\-\-\-\-\-+         +\-\-\-\-\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above figure, \fBid\fP means stream ID, and \fBw\fP means weight.
The stream 0 is non\-existence stream, and forms the root of the tree.
The stream 7 and 9 are not used for now.
.sp
The URIs given in the command\-line depend on stream 11 with the weight
given in \fI\%\-p\fP option, which defaults to 16.
.sp
If \fI\%\-a\fP option is used, nghttp parses the resource pointed by
URI given in command\-line as html, and extracts resource links from
it.  When requesting those resources, nghttp uses dependency according
to its resource type.
.sp
For CSS, and Javascript files inside \(dqhead\(dq element, they depend on
stream 3 with the weight 2.  The Javascript files outside \(dqhead\(dq
element depend on stream 5 with the weight 2.  The mages depend on
stream 11 with the weight 12.  The other resources (e.g., icon) depend
on stream 11 with the weight 2.
.SH SEE ALSO
.sp
\fBnghttpd(1)\fP, \fBnghttpx(1)\fP, \fBh2load(1)\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2012, 2015, 2016, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.