doc/nghttp.1

   1 .\" Man page generated from reStructuredText.
   2 .
   3 .TH "NGHTTP" "1" "May 16, 2015" "1.0.0" "nghttp2"
   4 .SH NAME
   5 nghttp \- HTTP/2 experimental 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 experimental 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  dereived 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=<FILE>
 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 priority group weight.  The valid value range is
 146 [1, 256], inclusive.
 147 .sp
 148 Default: \fB16\fP
 149 .UNINDENT
 150 .INDENT 0.0
 151 .TP
 152 .B \-M, \-\-peer\-max\-concurrent\-streams=<N>
 153 Use  <N>  as  SETTINGS_MAX_CONCURRENT_STREAMS  value  of
 154 remote endpoint as if it  is received in SETTINGS frame.
 155 The default is large enough as it is seen as unlimited.
 156 .UNINDENT
 157 .INDENT 0.0
 158 .TP
 159 .B \-c, \-\-header\-table\-size=<SIZE>
 160 Specify decoder header table size.
 161 .UNINDENT
 162 .INDENT 0.0
 163 .TP
 164 .B \-b, \-\-padding=<N>
 165 Add at  most <N>  bytes to a  frame payload  as padding.
 166 Specify 0 to disable padding.
 167 .UNINDENT
 168 .INDENT 0.0
 169 .TP
 170 .B \-r, \-\-har=<FILE>
 171 Output HTTP  transactions <FILE> in HAR  format.  If \(aq\-\(aq
 172 is given, data is written to stdout.
 173 .UNINDENT
 174 .INDENT 0.0
 175 .TP
 176 .B \-\-color
 177 Force colored log output.
 178 .UNINDENT
 179 .INDENT 0.0
 180 .TP
 181 .B \-\-continuation
 182 Send large header to test CONTINUATION.
 183 .UNINDENT
 184 .INDENT 0.0
 185 .TP
 186 .B \-\-no\-content\-length
 187 Don\(aqt send content\-length header field.
 188 .UNINDENT
 189 .INDENT 0.0
 190 .TP
 191 .B \-\-no\-dep
 192 Don\(aqt send dependency based priority hint to server.
 193 .UNINDENT
 194 .INDENT 0.0
 195 .TP
 196 .B \-\-hexdump
 197 Display the  incoming traffic in  hexadecimal (Canonical
 198 hex+ASCII display).  If SSL/TLS  is used, decrypted data
 199 are used.
 200 .UNINDENT
 201 .INDENT 0.0
 202 .TP
 203 .B \-\-no\-push
 204 Disable server push.
 205 .UNINDENT
 206 .INDENT 0.0
 207 .TP
 208 .B \-\-version
 209 Display version information and exit.
 210 .UNINDENT
 211 .INDENT 0.0
 212 .TP
 213 .B \-h, \-\-help
 214 Display this help and exit.
 215 .UNINDENT
 216 .sp
 217 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
 218 10 * 1024).  Units are K, M and G (powers of 1024).
 219 .sp
 220 The <DURATION> argument is an integer and an optional unit (e.g., 1s
 221 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
 222 (hours, minutes, seconds and milliseconds, respectively).  If a unit
 223 is omitted, a second is used as unit.
 224 .SH DEPENDENCY BASED PRIORITY
 225 .sp
 226 nghttp sends priority hints to server by default unless
 227 \fI\%\-\-no\-dep\fP is used.  nghttp mimics the way Firefox employs to
 228 manages dependency using idle streams.  We follows the behaviour of
 229 Firefox Nightly as of April, 2015, and nghttp\(aqs behaviour is very
 230 static and could be different from Firefox in detail.  But reproducing
 231 the same behaviour of Firefox is not our goal.  The goal is provide
 232 the easy way to test out the dependency priority in server
 233 implementation.
 234 .sp
 235 When connection is established, nghttp sends 5 PRIORITY frames to idle
 236 streams 3, 5, 7, 9 and 11 to create "anchor" nodes in dependency
 237 tree:
 238 .INDENT 0.0
 239 .INDENT 3.5
 240 .sp
 241 .nf
 242 .ft C
 243          +\-\-\-\-\-+
 244          |id=0 |
 245          +\-\-\-\-\-+
 246         ^   ^   ^
 247  w=201 /    |    \e w=1
 248       /     |     \e
 249      / w=101|      \e
 250  +\-\-\-\-\-+ +\-\-\-\-\-+ +\-\-\-\-\-+
 251  |id=3 | |id=5 | |id=7 |
 252  +\-\-\-\-\-+ +\-\-\-\-\-+ +\-\-\-\-\-+
 253     ^               ^
 254 w=1 |           w=1 |
 255     |               |
 256  +\-\-\-\-\-+         +\-\-\-\-\-+
 257  |id=11|         |id=9 |
 258  +\-\-\-\-\-+         +\-\-\-\-\-+
 259 .ft P
 260 .fi
 261 .UNINDENT
 262 .UNINDENT
 263 .sp
 264 In the above figure, \fBid\fP means stream ID, and \fBw\fP means weight.
 265 The stream 0 is non\-existence stream, and forms the root of the tree.
 266 The stream 7 and 9 are not used for now.
 267 .sp
 268 The URIs given in the command\-line depend on stream 11 with the weight
 269 given in \fI\%\-p\fP option, which defaults to 16.
 270 .sp
 271 If \fI\%\-a\fP option is used, nghttp parses the resource pointed by
 272 URI given in command\-line as html, and extracts resource links from
 273 it.  When requesting those resources, nghttp uses dependency according
 274 to its resource type.
 275 .sp
 276 For CSS, and Javascript files inside "head" element, they depend on
 277 stream 3 with the weight 2.  The Javascript files outside "head"
 278 element depend on stream 5 with the weight 2.  The mages depend on
 279 stream 11 with the weight 12.  The other resources (e.g., icon) depend
 280 on stream 11 with the weight 2.
 281 .SH SEE ALSO
 282 .sp
 283 \fInghttpd(1)\fP, \fInghttpx(1)\fP, \fIh2load(1)\fP
 284 .SH AUTHOR
 285 Tatsuhiro Tsujikawa
 286 .SH COPYRIGHT
 287 2012, 2015, Tatsuhiro Tsujikawa
 288 .\" Generated by docutils manpage writer.
 289 .