doc/nghttp.1

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