nghttp2/doc/nghttp.1.rst

.. program:: nghttp

nghttp(1)
=========

SYNOPSIS
--------

**nghttp** [OPTIONS]... <URI>...

DESCRIPTION
-----------

HTTP/2 experimental client

.. describe:: <URI>

    Specify URI to access.

OPTIONS
-------

.. option:: -v, --verbose

    Print   debug   information   such  as   reception   and
    transmission of frames and name/value pairs.  Specifying
    this option multiple times increases verbosity.

.. option:: -n, --null-out

    Discard downloaded data.

.. option:: -O, --remote-name

    Save  download  data  in  the  current  directory.   The
    filename is  dereived from URI.   If URI ends  with '*/*',
    'index.html'  is used  as a  filename.  Not  implemented
    yet.

.. option:: -t, --timeout=<SEC>

    Timeout each request after <SEC> seconds.

.. option:: -w, --window-bits=<N>

    Sets the stream level initial window size to 2\*\*<N>-1.

.. option:: -W, --connection-window-bits=<N>

    Sets  the  connection  level   initial  window  size  to
    2\*\*<N>-1.

.. option:: -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.

.. option:: -s, --stat

    Print statistics.

.. option:: -H, --header=<HEADER>

    Add a header to the requests.  Example: :option:`-H`\':method: PUT'

.. option:: --trailer=<HEADER>

    Add a trailer header to the requests.  <HEADER> must not
    include pseudo header field  (header field name starting
    with ':').  To  send trailer, one must use  :option:`-d` option to
    send request body.  Example: :option:`--trailer` 'foo: bar'.

.. option:: --cert=<CERT>

    Use  the specified  client certificate  file.  The  file
    must be in PEM format.

.. option:: --key=<KEY>

    Use the  client private key  file.  The file must  be in
    PEM format.

.. option:: -d, --data=<FILE>

    Post FILE to server. If '-'  is given, data will be read
    from stdin.

.. option:: -m, --multiply=<N>

    Request each URI <N> times.  By default, same URI is not
    requested twice.  This option disables it too.

.. option:: -u, --upgrade

    Perform HTTP Upgrade for HTTP/2.  This option is ignored
    if the request URI has https scheme.  If :option:`-d` is used, the
    HTTP upgrade request is performed with OPTIONS method.

.. option:: -p, --weight=<WEIGHT>

    Sets priority group weight.  The valid value range is
    [1, 256], inclusive.

    Default: ``16``

.. option:: -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.
    The default is large enough as it is seen as unlimited.

.. option:: -c, --header-table-size=<SIZE>

    Specify decoder header table size.

.. option:: -b, --padding=<N>

    Add at  most <N>  bytes to a  frame payload  as padding.
    Specify 0 to disable padding.

.. option:: -r, --har=<FILE>

    Output HTTP  transactions <FILE> in HAR  format.  If '-'
    is given, data is written to stdout.

.. option:: --color

    Force colored log output.

.. option:: --continuation

    Send large header to test CONTINUATION.

.. option:: --no-content-length

    Don't send content-length header field.

.. option:: --no-dep

    Don't send dependency based priority hint to server.

.. option:: --hexdump

    Display the  incoming traffic in  hexadecimal (Canonical
    hex+ASCII display).  If SSL/TLS  is used, decrypted data
    are used.

.. option:: --no-push

    Disable server push.

.. option:: --version

    Display version information and exit.

.. option:: -h, --help

    Display this help and exit.



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).

DEPENDENCY BASED PRIORITY
-------------------------

nghttp sends priority hints to server by default unless
:option:`--no-dep` 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's 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.

When connection is established, nghttp sends 5 PRIORITY frames to idle
streams 3, 5, 7, 9 and 11 to create "anchor" nodes in dependency
tree::

                      +-----+
                      |id=0 |
                      +-----+
                     ^   ^   ^
              w=201 /    |    \ w=1
                   /     |     \
                  / w=101|      \
              +-----+ +-----+ +-----+
              |id=3 | |id=5 | |id=7 |
              +-----+ +-----+ +-----+
                 ^               ^
             w=1 |           w=1 |
                 |               |
              +-----+         +-----+
              |id=11|         |id=9 |
              +-----+         +-----+

In the above figure, ``id`` means stream ID, and ``w`` 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.

The URIs given in the command-line depend on stream 11 with the weight
given in :option:`-p` option, which defaults to 16.

If :option:`-a` 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.

For CSS, and Javascript files inside "head" element, they depend on
stream 3 with the weight 2.  The Javascript files outside "head"
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.

SEE ALSO
--------

:manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`, :manpage:`h2load(1)`