nghttp2/doc/nghttpx.h2r

FILES
-----

*/etc/nghttpx/nghttpx.conf*
  The default configuration file path nghttpx searches at startup.
  The configuration file path can be changed using :option:`--conf`
  option.

  Those lines which are staring ``#`` are treated as comment.

  The option name in the configuration file is the long command-line
  option name with leading ``--`` stripped (e.g., ``frontend``).  Put
  ``=`` between option name and value.  Don't put extra leading or
  trailing spaces.

  When specifying arguments including characters which have special
  meaning to a shell, we usually use quotes so that shell does not
  interpret them.  When writing this configuration file, quotes for
  this purpose must not be used.  For example, specify additional
  request header field, do this:

  .. code-block:: text

    add-request-header=foo: bar

  instead of:

  .. code-block:: text

    add-request-header="foo: bar"

  The options which do not take argument in the command-line *take*
  argument in the configuration file.  Specify ``yes`` as an argument
  (e.g., ``http2-proxy=yes``).  If other string is given, it is
  ignored.

  To specify private key and certificate file which are given as
  positional arguments in command-line, use ``private-key-file`` and
  ``certificate-file``.

  :option:`--conf` option cannot be used in the configuration file and
  will be ignored if specified.

Error log
  Error log is written to stderr by default.  It can be configured
  using :option:`--errorlog-file`.  The format of log message is as
  follows:

  <datetime> <master-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg>

  <datetime>
    It is a conbination of date and time when the log is written.  It
    is in ISO 8601 format.

  <master-pid>
    It is a master process ID.

  <current-pid>
    It is a process ID which writes this log.

  <thread-id>
    It is a thread ID which writes this log.  It would be unique
    within <current-pid>.

  <filename> and <line>
    They are source file name, and line number which produce this log.

  <msg>
    It is a log message body.

SIGNALS
-------

SIGQUIT
  Shutdown gracefully.  First accept pending connections and stop
  accepting connection.  After all connections are handled, nghttpx
  exits.

SIGHUP
  Reload configuration file given in :option:`--conf`.

SIGUSR1
  Reopen log files.

SIGUSR2
  Fork and execute nghttpx.  It will execute the binary in the same
  path with same command-line arguments and environment variables.
  After new process comes up, sending SIGQUIT to the original process
  to perform hot swapping.  The difference between SIGUSR2 + SIGQUIT
  and SIGHUP is that former is usually used to execute new binary, and
  the master process is newly spawned.  On the other hand, the latter
  just reloads configuration file, and the same master process
  continues to exist.

.. note::

  nghttpx consists of multiple processes: one process for processing
  these signals, and another one for processing requests.  The former
  spawns the latter.  The former is called master process, and the
  latter is called worker process.  If neverbleed is enabled, the
  worker process spawns neverbleed daemon process which does RSA key
  processing.  The above signal must be sent to the master process.
  If the other processes received one of them, it is ignored.  This
  behaviour of these processes may change in the future release.  In
  other words, in the future release, the processes other than master
  process may terminate upon the reception of these signals.
  Therefore these signals should not be sent to the processes other
  than master process.

SERVER PUSH
-----------

nghttpx supports HTTP/2 server push in default mode with Link header
field.  nghttpx looks for Link header field (`RFC 5988
<http://tools.ietf.org/html/rfc5988>`_) in response headers from
backend server and extracts URI-reference with parameter
``rel=preload`` (see `preload
<http://w3c.github.io/preload/#interoperability-with-http-link-header>`_)
and pushes those URIs to the frontend client. Here is a sample Link
header field to initiate server push:

.. code-block:: text

  Link: </fonts/font.woff>; rel=preload
  Link: </css/theme.css>; rel=preload

Currently, the following restriction is applied for server push:

1. The associated stream must have method "GET" or "POST".  The
   associated stream's status code must be 200.

This limitation may be loosened in the future release.

nghttpx also supports server push if both frontend and backend are
HTTP/2 in default mode.  In this case, in addition to server push via
Link header field, server push from backend is forwarded to frontend
HTTP/2 session.

HTTP/2 server push will be disabled if :option:`--http2-proxy` is
used.

UNIX DOMAIN SOCKET
------------------

nghttpx supports UNIX domain socket with a filename for both frontend
and backend connections.

Please note that current nghttpx implementation does not delete a
socket with a filename.  And on start up, if nghttpx detects that the
specified socket already exists in the file system, nghttpx first
deletes it.  However, if SIGUSR2 is used to execute new binary and
both old and new configurations use same filename, new binary does not
delete the socket and continues to use it.

OCSP STAPLING
-------------

OCSP query is done using external Python script
``fetch-ocsp-response``, which has been originally developed in Perl
as part of h2o project (https://github.com/h2o/h2o), and was
translated into Python.

The script file is usually installed under
``$(prefix)/share/nghttp2/`` directory.  The actual path to script can
be customized using :option:`--fetch-ocsp-response-file` option.

If OCSP query is failed, previous OCSP response, if any, is continued
to be used.

TLS SESSION RESUMPTION
----------------------

nghttpx supports TLS session resumption through both session ID and
session ticket.

SESSION ID RESUMPTION
~~~~~~~~~~~~~~~~~~~~~

By default, session ID is shared by all worker threads.

If :option:`--tls-session-cache-memcached` is given, nghttpx will
insert serialized session data to memcached with
``nghttpx:tls-session-cache:`` + lowercased hex string of session ID
as a memcached entry key, with expiry time 12 hours.  Session timeout
is set to 12 hours.

By default, connections to memcached server are not encrypted.  To
enable encryption, use ``tls`` keyword in
:option:`--tls-session-cache-memcached` option.

TLS SESSION TICKET RESUMPTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, session ticket is shared by all worker threads.  The
automatic key rotation is also enabled by default.  Every an hour, new
encryption key is generated, and previous encryption key becomes
decryption only key.  We set session timeout to 12 hours, and thus we
keep at most 12 keys.

If :option:`--tls-ticket-key-memcached` is given, encryption keys are
retrieved from memcached.  nghttpx just reads keys from memcached; one
has to deploy key generator program to update keys frequently (e.g.,
every 1 hour).  The example key generator tlsticketupdate.go is
available under contrib directory in nghttp2 archive.  The memcached
entry key is ``nghttpx:tls-ticket-key``.  The data format stored in
memcached is the binary format described below:

.. code-block:: text

    +--------------+-------+----------------+
    | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
    +--------------+-------+----------------+
                   ^                        |
		   |                        |
		   +------------------------+
                   (LEN, KEY) pair can be repeated

All numbers in the above figure is bytes.  All integer fields are
network byte order.

First 4 bytes integer VERSION field, which must be 1.  The 2 bytes
integer LEN field gives the length of following KEY field, which
contains key.  If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is
used, LEN must be 48.  If
:option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be
80.  LEN and KEY pair can be repeated multiple times to store multiple
keys.  The key appeared first is used as encryption key.  All the
remaining keys are used as decryption only.

By default, connections to memcached server are not encrypted.  To
enable encryption, use ``tls`` keyword in
:option:`--tls-ticket-key-memcached` option.

If :option:`--tls-ticket-key-file` is given, encryption key is read
from the given file.  In this case, nghttpx does not rotate key
automatically.  To rotate key, one has to restart nghttpx (see
SIGNALS).

CERTIFICATE TRANSPARENCY
------------------------

nghttpx supports TLS ``signed_certificate_timestamp`` extension (`RFC
6962 <https://tools.ietf.org/html/rfc6962>`_).  The relevant options
are :option:`--tls-sct-dir` and ``sct-dir`` parameter in
:option:`--subcert`.  They takes a directory, and nghttpx reads all
files whose extension is ``.sct`` under the directory.  The ``*.sct``
files are encoded as ``SignedCertificateTimestamp`` struct described
in `section 3.2 of RFC 69662
<https://tools.ietf.org/html/rfc6962#section-3.2>`_.  This format is
the same one used by `nginx-ct
<https://github.com/grahamedgecombe/nginx-ct>`_ and `mod_ssl_ct
<https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html>`_.
`ct-submit <https://github.com/grahamedgecombe/ct-submit>`_ can be
used to submit certificates to log servers, and obtain the
``SignedCertificateTimestamp`` struct which can be used with nghttpx.

MRUBY SCRIPTING
---------------

.. warning::

  The current mruby extension API is experimental and not frozen.  The
  API is subject to change in the future release.

nghttpx allows users to extend its capability using mruby scripts.
nghttpx has 2 hook points to execute mruby script: request phase and
response phase.  The request phase hook is invoked after all request
header fields are received from client.  The response phase hook is
invoked after all response header fields are received from backend
server.  These hooks allows users to modify header fields, or common
HTTP variables, like authority or request path, and even return custom
response without forwarding request to backend servers.

To specify mruby script file, use :option:`--mruby-file` option.  The
script will be evaluated once per thread on startup, and it must
instantiate object and evaluate it as the return value (e.g.,
``App.new``).  This object is called app object.  If app object
defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env`
object on request hook.  Similarly, if app object defines ``on_resp``
method, it is called with :rb:class:`Nghttpx::Env` object on response
hook.  For each method invocation, user can can access
:rb:class:`Nghttpx::Request` and :rb:class:`Nghttpx::Response` objects
via :rb:attr:`Nghttpx::Env#req` and :rb:attr:`Nghttpx::Env#resp`
respectively.

.. rb:module:: Nghttpx

.. rb:const:: REQUEST_PHASE

    Constant to represent request phase.

.. rb:const:: RESPONSE_PHASE

    Constant to represent response phase.

.. rb:class:: Env

    Object to represent current request specific context.

    .. rb:attr_reader:: req

        Return :rb:class:`Request` object.

    .. rb:attr_reader:: resp

        Return :rb:class:`Response` object.

    .. rb:attr_reader:: ctx

        Return Ruby hash object.  It persists until request finishes.
        So values set in request phase hoo can be retrieved in
        response phase hook.

    .. rb:attr_reader:: phase

        Return the current phase.

    .. rb:attr_reader:: remote_addr

        Return IP address of a remote client.  If connection is made
        via UNIX domain socket, this returns the string "localhost".

    .. rb:attr_reader:: server_addr

        Return address of server that accepted the connection.  This
	is a string which specified in :option:`--frontend` option,
	excluding port number, and not a resolved IP address.  For
	UNIX domain socket, this is a path to UNIX domain socket.

    .. rb:attr_reader:: server_port

        Return port number of the server frontend which accepted the
        connection from client.

    .. rb:attr_reader:: tls_used

        Return true if TLS is used on the connection.

    .. rb:attr_reader:: tls_sni

        Return the TLS SNI value which client sent in this connection.

.. rb:class:: Request

    Object to represent request from client.  The modification to
    Request object is allowed only in request phase hook.

    .. rb:attr_reader:: http_version_major

        Return HTTP major version.

    .. rb:attr_reader:: http_version_minor

        Return HTTP minor version.

    .. rb:attr_accessor:: method

        HTTP method.  On assignment, copy of given value is assigned.
        We don't accept arbitrary method name.  We will document them
        later, but well known methods, like GET, PUT and POST, are all
        supported.

    .. rb:attr_accessor:: authority

        Authority (i.e., example.org), including optional port
        component .  On assignment, copy of given value is assigned.

    .. rb:attr_accessor:: scheme

        Scheme (i.e., http, https).  On assignment, copy of given
        value is assigned.

    .. rb:attr_accessor:: path

        Request path, including query component (i.e., /index.html).
        On assignment, copy of given value is assigned.  The path does
        not include authority component of URI.  This may include
        query component.  nghttpx makes certain normalization for
        path.  It decodes percent-encoding for unreserved characters
        (see https://tools.ietf.org/html/rfc3986#section-2.3), and
        resolves ".." and ".".  But it may leave characters which
        should be percent-encoded as is. So be careful when comparing
        path against desired string.

    .. rb:attr_reader:: headers

        Return Ruby hash containing copy of request header fields.
        Changing values in returned hash does not change request
        header fields actually used in request processing.  Use
        :rb:meth:`Nghttpx::Request#add_header` or
        :rb:meth:`Nghttpx::Request#set_header` to change request
        header fields.

    .. rb:method:: add_header(key, value)

        Add header entry associated with key.  The value can be single
        string or array of string.  It does not replace any existing
        values associated with key.

    .. rb:method:: set_header(key, value)

        Set header entry associated with key.  The value can be single
        string or array of string.  It replaces any existing values
        associated with key.

    .. rb:method:: clear_headers

        Clear all existing request header fields.

    .. rb:method:: push(uri)

        Initiate to push resource identified by *uri*.  Only HTTP/2
        protocol supports this feature.  For the other protocols, this
        method is noop.  *uri* can be absolute URI, absolute path or
        relative path to the current request.  For absolute or
        relative path, scheme and authority are inherited from the
        current request.  Currently, method is always GET.  nghttpx
        will issue request to backend servers to fulfill this request.
        The request and response phase hooks will be called for pushed
        resource as well.

.. rb:class:: Response

    Object to represent response from backend server.

    .. rb:attr_reader:: http_version_major

        Return HTTP major version.

    .. rb:attr_reader:: http_version_minor

        Return HTTP minor version.

    .. rb:attr_accessor:: status

        HTTP status code.  It must be in the range [200, 999],
        inclusive.  The non-final status code is not supported in
        mruby scripting at the moment.

    .. rb:attr_reader:: headers

        Return Ruby hash containing copy of response header fields.
        Changing values in returned hash does not change response
        header fields actually used in response processing.  Use
        :rb:meth:`Nghttpx::Response#add_header` or
        :rb:meth:`Nghttpx::Response#set_header` to change response
        header fields.

    .. rb:method:: add_header(key, value)

        Add header entry associated with key.  The value can be single
        string or array of string.  It does not replace any existing
        values associated with key.

    .. rb:method:: set_header(key, value)

        Set header entry associated with key.  The value can be single
        string or array of string.  It replaces any existing values
        associated with key.

    .. rb:method:: clear_headers

        Clear all existing response header fields.

    .. rb:method:: return(body)

        Return custom response *body* to a client.  When this method
        is called in request phase hook, the request is not forwarded
        to the backend, and response phase hook for this request will
        not be invoked.  When this method is called in response phase
        hook, response from backend server is canceled and discarded.
        The status code and response header fields should be set
        before using this method.  To set status code, use :rb:meth To
        set response header fields, use
        :rb:attr:`Nghttpx::Response#status`.  If status code is not
        set, 200 is used.  :rb:meth:`Nghttpx::Response#add_header` and
        :rb:meth:`Nghttpx::Response#set_header`.  When this method is
        invoked in response phase hook, the response headers are
        filled with the ones received from backend server.  To send
        completely custom header fields, first call
        :rb:meth:`Nghttpx::Response#clear_headers` to erase all
        existing header fields, and then add required header fields.
        It is an error to call this method twice for a given request.

MRUBY EXAMPLES
~~~~~~~~~~~~~~

Modify request path:

.. code-block:: ruby

    class App
      def on_req(env)
        env.req.path = "/apps#{env.req.path}"
      end
    end

    App.new

Don't forget to instantiate and evaluate object at the last line.

Restrict permission of viewing a content to a specific client
addresses:

.. code-block:: ruby

    class App
      def on_req(env)
        allowed_clients = ["127.0.0.1", "::1"]

        if env.req.path.start_with?("/log/") &&
           !allowed_clients.include?(env.remote_addr) then
          env.resp.status = 404
          env.resp.return "permission denied"
        end
      end
    end

    App.new

API ENDPOINTS
-------------

nghttpx exposes API endpoints to manipulate it via HTTP based API.  By
default, API endpoint is disabled.  To enable it, add a dedicated
frontend for API using :option:`--frontend` option with "api"
parameter.  All requests which come from this frontend address, will
be treated as API request.

The response is normally JSON dictionary, and at least includes the
following keys:

status
  The status of the request processing.  The following values are
  defined:

  Success
    The request was successful.

  Failure
    The request was failed.  No change has been made.

code
  HTTP status code

We wrote "normally", since nghttpx may return ordinal HTML response in
some cases where the error has occurred before reaching API endpoint
(e.g., header field is too large).

The following section describes available API endpoints.

POST /api/v1beta1/backendconfig
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This API replaces the current backend server settings with the
requested ones.  The request method should be POST, but PUT is also
acceptable.  The request body must be nghttpx configuration file
format.  For configuration file format, see `FILES`_ section.  The
line separator inside the request body must be single LF (0x0A).
Currently, only :option:`backend <--backend>` option is parsed, the
others are simply ignored.  The semantics of this API is replace the
current backend with the backend options in request body.  Describe
the desired set of backend severs, and nghttpx makes it happen.  If
there is no :option:`backend <--backend>` option is found in request
body, the current set of backend is replaced with the :option:`backend
<--backend>` option's default value, which is ``127.0.0.1,80``.

The replacement is done instantly without breaking existing
connections or requests.  It also avoids any process creation as is
the case with hot swapping with signals.

The one limitation is that only numeric IP address is allowd in
:option:`backend <--backend>` in request body unless "dns" parameter
is used while non numeric hostname is allowed in command-line or
configuration file is read using :option:`--conf`.

SEE ALSO
--------

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