doc/nghttp.1.rst

   1
   2 .. GENERATED by help2rst.py.  DO NOT EDIT DIRECTLY.
   3
   4 .. program:: nghttp
   5
   6 nghttp(1)
   7 =========
   8
   9 SYNOPSIS
  10 --------
  11
  12 **nghttp** [OPTIONS]... <URI>...
  13
  14 DESCRIPTION
  15 -----------
  16
  17 HTTP/2 experimental client
  18
  19 .. describe:: <URI>
  20
  21     Specify URI to access.
  22
  23 OPTIONS
  24 -------
  25
  26 .. option:: -v, --verbose
  27
  28     Print   debug   information   such  as   reception   and
  29     transmission of frames and name/value pairs.  Specifying
  30     this option multiple times increases verbosity.
  31
  32 .. option:: -n, --null-out
  33
  34     Discard downloaded data.
  35
  36 .. option:: -O, --remote-name
  37
  38     Save  download  data  in  the  current  directory.   The
  39     filename is  dereived from URI.   If URI ends  with '*/*',
  40     'index.html'  is used  as a  filename.  Not  implemented
  41     yet.
  42
  43 .. option:: -t, --timeout=<DURATION>
  44
  45     Timeout each request after <DURATION>.  Set 0 to disable
  46     timeout.
  47
  48 .. option:: -w, --window-bits=<N>
  49
  50     Sets the stream level initial window size to 2\*\*<N>-1.
  51
  52 .. option:: -W, --connection-window-bits=<N>
  53
  54     Sets  the  connection  level   initial  window  size  to
  55     2\*\*<N>-1.
  56
  57 .. option:: -a, --get-assets
  58
  59     Download assets  such as stylesheets, images  and script
  60     files linked  from the downloaded resource.   Only links
  61     whose  origins are  the same  with the  linking resource
  62     will be downloaded.   nghttp prioritizes resources using
  63     HTTP/2 dependency  based priority.  The  priority order,
  64     from highest to lowest,  is html itself, css, javascript
  65     and images.
  66
  67 .. option:: -s, --stat
  68
  69     Print statistics.
  70
  71 .. option:: -H, --header=<HEADER>
  72
  73     Add a header to the requests.  Example: :option:`-H`\':method: PUT'
  74
  75 .. option:: --trailer=<HEADER>
  76
  77     Add a trailer header to the requests.  <HEADER> must not
  78     include pseudo header field  (header field name starting
  79     with ':').  To  send trailer, one must use  :option:`-d` option to
  80     send request body.  Example: :option:`--trailer` 'foo: bar'.
  81
  82 .. option:: --cert=<CERT>
  83
  84     Use  the specified  client certificate  file.  The  file
  85     must be in PEM format.
  86
  87 .. option:: --key=<KEY>
  88
  89     Use the  client private key  file.  The file must  be in
  90     PEM format.
  91
  92 .. option:: -d, --data=<FILE>
  93
  94     Post FILE to server. If '-'  is given, data will be read
  95     from stdin.
  96
  97 .. option:: -m, --multiply=<N>
  98
  99     Request each URI <N> times.  By default, same URI is not
 100     requested twice.  This option disables it too.
 101
 102 .. option:: -u, --upgrade
 103
 104     Perform HTTP Upgrade for HTTP/2.  This option is ignored
 105     if the request URI has https scheme.  If :option:`-d` is used, the
 106     HTTP upgrade request is performed with OPTIONS method.
 107
 108 .. option:: -p, --weight=<WEIGHT>
 109
 110     Sets priority group weight.  The valid value range is
 111     [1, 256], inclusive.
 112
 113     Default: ``16``
 114
 115 .. option:: -M, --peer-max-concurrent-streams=<N>
 116
 117     Use  <N>  as  SETTINGS_MAX_CONCURRENT_STREAMS  value  of
 118     remote endpoint as if it  is received in SETTINGS frame.
 119     The default is large enough as it is seen as unlimited.
 120
 121 .. option:: -c, --header-table-size=<SIZE>
 122
 123     Specify decoder header table size.
 124
 125 .. option:: -b, --padding=<N>
 126
 127     Add at  most <N>  bytes to a  frame payload  as padding.
 128     Specify 0 to disable padding.
 129
 130 .. option:: -r, --har=<FILE>
 131
 132     Output HTTP  transactions <FILE> in HAR  format.  If '-'
 133     is given, data is written to stdout.
 134
 135 .. option:: --color
 136
 137     Force colored log output.
 138
 139 .. option:: --continuation
 140
 141     Send large header to test CONTINUATION.
 142
 143 .. option:: --no-content-length
 144
 145     Don't send content-length header field.
 146
 147 .. option:: --no-dep
 148
 149     Don't send dependency based priority hint to server.
 150
 151 .. option:: --hexdump
 152
 153     Display the  incoming traffic in  hexadecimal (Canonical
 154     hex+ASCII display).  If SSL/TLS  is used, decrypted data
 155     are used.
 156
 157 .. option:: --no-push
 158
 159     Disable server push.
 160
 161 .. option:: --version
 162
 163     Display version information and exit.
 164
 165 .. option:: -h, --help
 166
 167     Display this help and exit.
 168
 169
 170
 171 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
 172 10 * 1024).  Units are K, M and G (powers of 1024).
 173
 174 The <DURATION> argument is an integer and an optional unit (e.g., 1s
 175 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
 176 (hours, minutes, seconds and milliseconds, respectively).  If a unit
 177 is omitted, a second is used as unit.
 178
 179 DEPENDENCY BASED PRIORITY
 180 -------------------------
 181
 182 nghttp sends priority hints to server by default unless
 183 :option:`--no-dep` is used.  nghttp mimics the way Firefox employs to
 184 manages dependency using idle streams.  We follows the behaviour of
 185 Firefox Nightly as of April, 2015, and nghttp's behaviour is very
 186 static and could be different from Firefox in detail.  But reproducing
 187 the same behaviour of Firefox is not our goal.  The goal is provide
 188 the easy way to test out the dependency priority in server
 189 implementation.
 190
 191 When connection is established, nghttp sends 5 PRIORITY frames to idle
 192 streams 3, 5, 7, 9 and 11 to create "anchor" nodes in dependency
 193 tree::
 194
 195                       +-----+
 196                       |id=0 |
 197                       +-----+
 198                      ^   ^   ^
 199               w=201 /    |    \ w=1
 200                    /     |     \
 201                   / w=101|      \
 202               +-----+ +-----+ +-----+
 203               |id=3 | |id=5 | |id=7 |
 204               +-----+ +-----+ +-----+
 205                  ^               ^
 206              w=1 |           w=1 |
 207                  |               |
 208               +-----+         +-----+
 209               |id=11|         |id=9 |
 210               +-----+         +-----+
 211
 212 In the above figure, ``id`` means stream ID, and ``w`` means weight.
 213 The stream 0 is non-existence stream, and forms the root of the tree.
 214 The stream 7 and 9 are not used for now.
 215
 216 The URIs given in the command-line depend on stream 11 with the weight
 217 given in :option:`-p` option, which defaults to 16.
 218
 219 If :option:`-a` option is used, nghttp parses the resource pointed by
 220 URI given in command-line as html, and extracts resource links from
 221 it.  When requesting those resources, nghttp uses dependency according
 222 to its resource type.
 223
 224 For CSS, and Javascript files inside "head" element, they depend on
 225 stream 3 with the weight 2.  The Javascript files outside "head"
 226 element depend on stream 5 with the weight 2.  The mages depend on
 227 stream 11 with the weight 12.  The other resources (e.g., icon) depend
 228 on stream 11 with the weight 2.
 229
 230 SEE ALSO
 231 --------
 232
 233 :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`, :manpage:`h2load(1)`