doc: Add nghttpx-howto.rst

doc/nghttpx-howto.rst

@@ -0,0 +1 @@
+.. include:: ../doc/sources/nghttpx-howto.rst

doc/sources/index.rst

@@ -19,6 +19,7 @@ Contents:
    package_README
    tutorial-client
    tutorial-server
+   nghttpx-howto
    apiref
    nghttp2.h
    nghttp2ver.h

doc/sources/nghttpx-howto.rst

@@ -0,0 +1,232 @@
+nghttpx - HOW-TO
+================
+
+nghttpx is a proxy translating protocols between HTTP/2 and other
+protocols (e.g., HTTP/1, SPDY).  It operates in several modes and each
+mode may require additional programs to work with.  This article
+describes each operation mode and explains the intended use-cases.  It
+also covers some useful options later.
+
+Default mode
+------------
+
+If nghttpx is invoked without any ``-s``, ``-p`` and ``--client``, it
+operates in default mode.  In this mode, nghttpx frontend listens for
+HTTP/2 requests and translates them to HTTP/1 requests.  Thus it works
+as reverse proxy (gateway) for HTTP/2 clients to HTTP/1 web server.
+HTTP/1 requests are also supported in frontend as a fallback.  If
+nghttpx is linked with spdylay library and frontend connection is
+SSL/TLS, the frontend also supports SPDY protocol.
+
+By default, this mode's frontend connection is encrypted using
+SSL/TLS.  So server's private key and certificate must be supplied to
+the command line (or through configuration file).  In this case, the
+fontend protocol selection will is done via ALPN or NPN.
+
+With ``--frontend-no-tls`` option, user can turn off SSL/TLS in
+frontend connection.  In this case, SPDY protocol is not available
+even if spdylay library is liked to nghttpx.  HTTP/2 and HTTP/1 are
+available on the frontend and a HTTP/1 connection can be upgraded to
+HTTP/2 using HTTP Upgrade.  Starting HTTP/2 connection by sending
+HTTP/2 connection preface is also supported.
+
+The backend is supposed to be HTTP/1 Web server.  For example, to make
+nghttpx listen to encrypted HTTP/2 requests at port 8443, and a
+backend HTTP/1 web server is configured to listen to HTTP/1 request at
+port 8080 in the same host, run nghttpx command-line like this::
+
+    $ nghttpx -f0.0.0.0,8443 -b127.0.0.1,8080 /path/to/server.key /path/to/server.crt
+
+Then HTTP/2 enabled client can access to the nghttpx in HTTP/2.  For
+example, you can send GET request to the server using nghttp::
+
+    $ nghttp -nv https://localhost:8443/
+
+HTTP/2 proxy mode
+-----------------
+
+If nghttpx is invoked with ``-s`` option, it operates in HTTP/2 proxy
+mode.  The supported protocols in frontend and backend connections are
+the same in `default mode`_.  The difference is that this mode acts like
+forward proxy and assumes the backend is HTTP/1 proxy server (e.g.,
+squid).  So HTTP/1 request must include absolute URI in request line.
+
+By default, frontend connection is encrypted, this mode is also called
+secure proxy.  If nghttpx is linked with spdylay, it supports SPDY
+protocols and it works as so called SPDY proxy.
+
+With ``--frontend-no-tls`` option, SSL/TLS is turned off in frontend
+connection, so the connection gets insecure.
+
+The backend must be HTTP/1 proxy server.  nghttpx only supports 1
+backend server address.  It translates incoming requests to HTTP/1
+request to backend server.  The backend server performs real proxy
+work for each request, for example, dispatching requests to the origin
+server and caching contents.
+
+For example, to make nghttpx listen to encrypted HTTP/2 requests at
+port 8443, and a backend HTTP/1 proxy server is configured to listen
+to HTTP/1 request at port 3128 in the same host, run nghttpx
+command-line like this::
+
+    $ nghttpx -s -f0.0.0.0,8443 -b127.0.0.1,3128 /path/to/server.key /path/to/server.crt
+
+At the time of this writing, there is no known HTTP/2 client which
+supports HTTP/2 proxy in this fashion.  You can use Google Chrome to
+use this as secure (SPDY) proxy to test it out, though it does not use
+HTTP/2 at all.
+
+The one way to configure Google Chrome to use secure proxy is create
+proxy.pac script like this:
+
+.. code-block:: javascript
+
+    function FindProxyForURL(url, host) {
+        return "HTTPS SERVERADDR:PORT";
+    }
+
+``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
+machine nghttpx is running.  Please note that Google Chrome requires
+valid certificate for secure proxy.
+
+Then run Google Chrome with the following arguments::
+
+    $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
+
+Client mode
+-----------
+
+If nghttpx is invoked with ``--client`` option, it operates in client
+mode.  In this mode, nghttpx listens for plain, unencrypted HTTP/2 and
+HTTP/1 requests and translates them to encrypted HTTP/2 requests to
+the backend.  User cannot enable SSL/TLS in frontend connection.
+
+HTTP/1 frontend connection can be upgraded to HTTP/2 using HTTP
+Upgrade.  To disable SSL/TLS in backend connection, use
+``--backend-no-tls`` option.
+
+The backend connection is created one per worker (thread).
+
+The backend server is supporsed to be a HTTP/2 web server (e.g.,
+nghttpd).  The one use-case of this mode is utilize existing HTTP/1
+clients to test HTTP/2 deployment.  Suppose that HTTP/2 web server
+listens to port 80 without encryption.  Then run nghttpx as client
+mode to access to that web server::
+
+    $ nghttpx --client -f127.0.0.1,8080 -b127.0.0.1,80 --backend-no-tls
+
+.. note::
+
+    You may need ``-k`` option if HTTP/2 server enables SSL/TLS and
+    its certificate is self-signed. But please note that it is
+    insecure.
+
+Then you can use curl to access HTTP/2 server via nghttpx::
+
+    $ curl http://localhost:8080/
+
+Client proxy mode
+-----------------
+
+If nghttpx is invoked with ``-p`` option, it operates in client proxy
+mode.  This mode behaves like `client mode`_, but it works like
+forward proxy.  So HTTP/1 request must include absolute URI in request
+line.
+
+HTTP/1 frontend connection can be upgraded to HTTP/2 using HTTP
+Upgrade.  To disable SSL/TLS in backend connection, use
+``--backend-no-tls`` option.
+
+The backend connection is created one per worker (thread).
+
+The backend server must be a HTTP/2 proxy.  You can use nghttpx in
+`HTTP/2 proxy mode`_ as backend server.  The one use-case of this mode
+is utilize existing HTTP/1 clients to test HTTP/2 connections between
+2 proxies. The another use-case is use this mode to aggregate local
+HTTP/1 connections to one HTTP/2 backend encrypted connection.  This
+makes HTTP/1 clients which does not support secure proxy can use
+secure HTTP/2 proxy via nghttpx client mode.
+
+Suppose that HTTP/2 proxy listens to port 8443, just like we saw in
+`HTTP/2 proxy mode`_.  To run nghttpx in client proxy mode to access
+that server, invoke nghttpx like this::
+
+    $ nghttpx -p -f127.0.0.1,8080 -b127.0.0.1,8443
+
+.. note::
+
+    You may need ``-k`` option if HTTP/2 server'ss certificate is
+    self-signed. But please note that it is insecure.
+
+Then you can use curl to issue HTTP request via HTTP/2 proxy::
+
+    $ curl --http-proxy=http://localhost:8080 http://www.google.com/
+
+You can configure web browser to use localhost:8080 as forward
+proxy.
+
+HTTP/2 bridge mode
+------------------
+
+If nghttpx is invoked with ``--http2-bridge`` option, it operates in
+HTTP/2 bridge mode.  The supported protocols in frontend and backend
+connections are the same in `default mode`_.
+
+With ``--frontend-no-tls`` option, SSL/TLS is turned off in frontend
+connection, so the connection gets insecure.
+
+The backend server is supporsed to be a HTTP/2 web server or HTTP/2
+proxy.  Since HTTP/2 requests opaque between proxied and non-proxied
+request, the backend server may be proxy or just web server depending
+on the context of incoming requests.
+
+The use-case of this mode is aggregate the incoming connections to one
+HTTP/2 connection.  One backend HTTP/2 connection is created per
+worker (thread).
+
+Disable SSL/TLS
+---------------
+
+In `default mode`_, `HTTP/2 proxy mode`_ and `HTTP/2 bridge mode`_,
+frontend connections are encrypted with SSL/TLS by default.  To turn
+off SSL/TLS, use ``--frontend-no-tls`` option.  If this option is
+used, the private key and certificate are not required to run nghttpx.
+
+In `client mode`_, `client proxy mode`_ and `HTTP/2 bridge mode`_,
+backend connections are encrypted with SSL/TLS by default.  To turn
+off SSL/TLS, use ``--backend-no-tls`` option.
+
+Specifying additional CA certificate
+------------------------------------
+
+By default, nghttpx tries to read CA certificate from system.  But
+depending on the system you use, this may fail or is not supported.
+To specify CA certificate manually, use ``--cacert`` option.  The
+specified file must be PEM format and can contain multiple
+certificates.
+
+By default, nghttpx validates server's certificate.  If you want to
+turn off this validation, knowing this is really insecure and what you
+are doing, you can use ``-k`` option to disable certificate
+validation.
+
+Read/write rate limit
+---------------------
+
+nghttpx supports transfer rate limiting on frontend connections.  You
+can do rate limit per connection or per worker (thread) for reading
+and writeing individually.
+
+To rate limit per connection for reading, use ``--read-rate`` and
+``--read-burst`` options.  For writing, use ``--write-rate`` and
+``--write-burst`` options.
+
+To rate limit per worker (thread), use ``--worker-read-rate`` and
+``--worker-read-burst`` options.  For writing, use
+``--worker-write-rate`` and ``--worker-write-burst``.
+
+If both per connection and per worker rate limit configurations are
+specified, the lower rate is used.
+
+Please note that rate limit is performed on top of TCP and nothing to
+do with HTTP/2 flow control.