Update nghttpx documentation

doc/nghttpx.1.rst

@@ -1474,6 +1474,12 @@ addresses:
 
     App.new
 
+NOTES
+-----
+
+1. nghttpx - HTTP/2 proxy - HOW-TO
+   https://nghttp2.org/documentation/nghttpx-howto.html
+
 SEE ALSO
 --------
 

doc/sources/nghttpx-howto.rst

@@ -1,3 +1,5 @@
+.. program:: nghttpx
+
 nghttpx - HTTP/2 proxy - HOW-TO
 ===============================
 
@@ -10,21 +12,22 @@ also covers some useful options later.
 Default mode
 ------------
 
-If nghttpx is invoked without any ``-s``, ``-p`` and ``--client``, it
+If nghttpx is invoked without any :option:`--http2-proxy`,
-operates in default mode.  In this mode, nghttpx frontend listens for
+:option:`--client`, and :option:`--client-proxy`, it operates in
-HTTP/2 requests and translates them to HTTP/1 requests.  Thus it works
+default mode.  In this mode, nghttpx frontend listens for HTTP/2
-as reverse proxy (gateway) for HTTP/2 clients to HTTP/1 web server.
+requests and translates them to HTTP/1 requests.  Thus it works as
-This is also known as "HTTP/2 router".  HTTP/1 requests are also
+reverse proxy (gateway) for HTTP/2 clients to HTTP/1 web server.  This
-supported in frontend as a fallback.  If nghttpx is linked with
+is also known as "HTTP/2 router".  HTTP/1 requests are also supported
-spdylay library and frontend connection is SSL/TLS, the frontend also
+in frontend as a fallback.  If nghttpx is linked with spdylay library
-supports SPDY protocol.
+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
 frontend protocol selection will be done via ALPN or NPN.
 
-With ``--frontend-no-tls`` option, user can turn off SSL/TLS in
+With :option:`--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
@@ -32,8 +35,9 @@ HTTP/2 using HTTP Upgrade.  Starting HTTP/2 connection by sending
 HTTP/2 connection preface is also supported.
 
 By default, backend HTTP/1 connections are not encrypted.  To enable
-TLS on HTTP/1 backend connections, use ``--backend-http1-tls`` option.
+TLS on HTTP/1 backend connections, use :option:`--backend-http1-tls`
-This applies to all mode whose backend connections are HTTP/1.
+option.  This applies to all mode whose backend connections are
+HTTP/1.
 
 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
@@ -50,19 +54,19 @@ example, you can send GET request to the server using nghttp::
 HTTP/2 proxy mode
 -----------------
 
-If nghttpx is invoked with ``-s`` option, it operates in HTTP/2 proxy
+If nghttpx is invoked with :option:`--http2-proxy` (or its shorthand
-mode.  The supported protocols in frontend and backend connections are
+:option:`-s`) option, it operates in HTTP/2 proxy mode.  The supported
-the same in `default mode`_.  The difference is that this mode acts
+protocols in frontend and backend connections are the same in `default
-like forward proxy and assumes the backend is HTTP/1 proxy server
+mode`_.  The difference is that this mode acts like forward proxy and
-(e.g., squid, traffic server).  So HTTP/1 request must include
+assumes the backend is HTTP/1 proxy server (e.g., squid, traffic
-absolute URI in request line.
+server).  So HTTP/1 request must include absolute URI in request line.
 
 By default, frontend connection is encrypted.  So 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
+With :option:`--frontend-no-tls` option, SSL/TLS is turned off in
-connection, so the connection gets insecure.
+frontend connection, so the connection gets insecure.
 
 The backend must be HTTP/1 proxy server.  nghttpx supports multiple
 backend server addresses.  It translates incoming requests to HTTP/1
@@ -96,7 +100,9 @@ Chromium require valid certificate for secure proxy.
 For Firefox, open Preference window and select Advanced then click
 Network tab.  Clicking Connection Settings button will show the
 dialog.  Select "Automatic proxy configuration URL" and enter the path
-to proxy.pac file, something like this::
+to proxy.pac file, something like this:
+
+.. code-block:: text
 
     file:///path/to/proxy.pac
 
@@ -112,25 +118,27 @@ configuration items to edit::
     CONFIG proxy.config.url_remap.remap_required INT 0
 
 Consult Traffic server `documentation
-<https://docs.trafficserver.apache.org/en/latest/admin/forward-proxy.en.html>`_
+<http://trafficserver.readthedocs.org/en/latest/admin-guide/configuration/transparent-forward-proxying.en.html>`_
 to know how to configure traffic server as forward proxy and its
 security implications.
 
 Client mode
 -----------
 
-If nghttpx is invoked with ``--client`` option, it operates in client
+If nghttpx is invoked with :option:`--client` option, it operates in
-mode.  In this mode, nghttpx listens for plain, unencrypted HTTP/2 and
+client mode.  In this mode, nghttpx listens for plain, unencrypted
-HTTP/1 requests and translates them to encrypted HTTP/2 requests to
+HTTP/2 and HTTP/1 requests and translates them to encrypted HTTP/2
-the backend.  User cannot enable SSL/TLS in frontend connection.
+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.
+:option:`--backend-no-tls` option.
 
 By default, the number of backend HTTP/2 connections per worker
-(thread) is determined by number of ``-b`` option.  To adjust this
+(thread) is determined by number of :option:`--backend` option.  To
-value, use ``--backend-http2-connections-per-worker`` option.
+adjust this value, use
+:option:`--backend-http2-connections-per-worker` option.
 
 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
@@ -142,9 +150,10 @@ mode to access to that web server::
 
 .. note::
 
-    You may need ``-k`` option if HTTP/2 server enables SSL/TLS and
+    You may need :option:`--insecure` (or its shorthand :option:`-k`)
-    its certificate is self-signed. But please note that it is
+    option if HTTP/2 server enables SSL/TLS and its certificate is
-    insecure.
+    self-signed. But please note that it is insecure, and you should
+    know what you are doing.
 
 Then you can use curl to access HTTP/2 server via nghttpx::
 
@@ -153,18 +162,19 @@ Then you can use curl to access HTTP/2 server via nghttpx::
 Client proxy mode
 -----------------
 
-If nghttpx is invoked with ``-p`` option, it operates in client proxy
+If nghttpx is invoked with :option:`--client-proxy` (or its shorthand
-mode.  This mode behaves like `client mode`_, but it works like
+:option:`-p`) option, it operates in client proxy mode.  This mode
-forward proxy.  So HTTP/1 request must include absolute URI in request
+behaves like `client mode`_, but it works like forward proxy.  So
-line.
+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.
+:option:`--backend-no-tls` option.
 
 By default, the number of backend HTTP/2 connections per worker
-(thread) is determined by number of ``-b`` option.  To adjust this
+(thread) is determined by number of :option:`--backend` option.  To
-value, use ``--backend-http2-connections-per-worker`` option.
+adjust this value, use
+:option:`--backend-http2-connections-per-worker` option.
 
 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
@@ -182,8 +192,9 @@ that server, invoke nghttpx like this::
 
 .. note::
 
-    You may need ``-k`` option if HTTP/2 server's certificate is
+    You may need :option:`--insecure` (or its shorthand :option:`-k`)
-    self-signed. But please note that it is insecure.
+    option if HTTP/2 server's certificate is self-signed. But please
+    note that it is insecure, and you should know what you are doing.
 
 Then you can use curl to issue HTTP request via HTTP/2 proxy::
 
@@ -195,23 +206,24 @@ proxy.
 HTTP/2 bridge mode
 ------------------
 
-If nghttpx is invoked with ``--http2-bridge`` option, it operates in
+If nghttpx is invoked with :option:`--http2-bridge` option, it
-HTTP/2 bridge mode.  The supported protocols in frontend connections
+operates in HTTP/2 bridge mode.  The supported protocols in frontend
-are the same in `default mode`_.  The protocol in backend is HTTP/2
+connections are the same in `default mode`_.  The protocol in backend
-only.
+is HTTP/2 only.
 
-With ``--frontend-no-tls`` option, SSL/TLS is turned off in frontend
+With :option:`--frontend-no-tls` option, SSL/TLS is turned off in
-connection, so the connection gets insecure.  To disable SSL/TLS in
+frontend connection, so the connection gets insecure.  To disable
-backend connection, use ``--backend-no-tls`` option.
+SSL/TLS in backend connection, use :option:`--backend-no-tls` option.
 
 By default, the number of backend HTTP/2 connections per worker
-(thread) is determined by number of ``-b`` option.  To adjust this
+(thread) is determined by number of :option:`--backend` option.  To
-value, use ``--backend-http2-connections-per-worker`` option.
+adjust this value, use
+:option:`--backend-http2-connections-per-worker` option.
 
 The backend server is supporsed to be a HTTP/2 web server or HTTP/2
 proxy.  If backend server is HTTP/2 proxy, use
-``--no-location-rewrite`` and ``--no-host-rewrite`` options to disable
+:option:`--no-location-rewrite` option to disable rewriting
-rewriting location, host and :authority header field.
+``Location`` header field.
 
 The use-case of this mode is aggregate the incoming connections to one
 HTTP/2 connection.  One backend HTTP/2 connection is created per
@@ -222,26 +234,42 @@ 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
+off SSL/TLS, use :option:`--frontend-no-tls` option.  If this option
-used, the private key and certificate are not required to run nghttpx.
+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.
+off SSL/TLS, use :option:`--backend-no-tls` option.
+
+Enable SSL/TLS on HTTP/1 backend
+--------------------------------
+
+In all modes which use HTTP/1 as backend protocol, backend HTTP/1
+connection is not encrypted by default.  To enable encryption, use
+:option:`--backend-http1-tls` option.
+
+Enable SSL/TLS on memcached connection
+--------------------------------------
+
+By default, memcached connection is not encrypted.  To enable
+encryption, use :option:`--tls-ticket-key-memcached-tls` for TLS
+ticket key, and use :option:`--tls-session-cache-memcached-tls` for
+TLS session cache.
 
 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
+To specify CA certificate manually, use :option:`--cacert` option.
-specified file must be PEM format and can contain multiple
+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
+are doing, you can use :option:`--insecure` option to disable
-validation.
+certificate validation.
 
 Read/write rate limit
 ---------------------
@@ -250,9 +278,9 @@ nghttpx supports transfer rate limiting on frontend connections.  You
 can do rate limit per frontend connection for reading and writing
 individually.
 
-To perform rate limit for reading, use ``--read-rate`` and
+To perform rate limit for reading, use :option:`--read-rate` and
-``--read-burst`` options.  For writing, use ``--write-rate`` and
+:option:`--read-burst` options.  For writing, use
-``--write-burst``.
+:option:`--write-rate` and :option:`--write-burst`.
 
 Please note that rate limit is performed on top of TCP and nothing to
 do with HTTP/2 flow control.
@@ -294,14 +322,64 @@ Re-opening log files
 When rotating log files, it is desirable to re-open log files after
 log rotation daemon renamed existing log files.  To tell nghttpx to
 re-open log files, send USR1 signal to nghttpx process.  It will
-re-open files specified by ``--accesslog-file`` and
+re-open files specified by :option:`--accesslog-file` and
-``--errorlog-file`` options.
+:option:`--errorlog-file` options.
 
 Multiple backend addresses
 --------------------------
 
 nghttpx supports multiple backend addresses.  To specify them, just
-use ``-b`` option repeatedly.  For example, to use backend1:8080 and
+use :option:`--backend` (or its shorthand :option:`-b`) option
-backend2:8080, use command-line like this: ``-bbackend1,8080
+repeatedly.  For example, to use ``192.168.0.10:8080`` and
--bbackend2,8080``.  For HTTP/2 backend, see also
+``192.168.0.11:8080``, use command-line like this:
-``--backend-http2-connections-per-worker`` option.
+``-b192.168.0.10,8080 -b192.168.0.11,8080``.  In configuration file,
+this looks like:
+
+.. code-block:: text
+
+   backend=192.168.0.10,8080
+   backend=192.168.0.11,8008
+
+nghttpx can route request to different backend according to request
+host and path.  For example, to route request destined to host
+``doc.example.com`` to backend server ``docserv:3000``, you can write
+like so:
+
+.. code-block:: text
+
+   backend=docserv,3000;doc.example.com/
+
+When you write this option in command-line, you should enclose
+argument with single or double quotes, since the character ``;`` has a
+special meaning in shell.
+
+To route, request to request path whose prefix is ``/foo`` to backend
+server ``[::1]:8080``, you can write like so:
+
+.. code-block:: text
+
+   backend=::1,8080;/foo
+
+Of course, you can specify both host and request path at the same
+time.
+
+One important thing you have to remember is that we have to specify
+default routing pattern for so called "catch all" pattern.  To write
+"catch all" pattern, just specify backend server address, without
+pattern.
+
+Usually, host is the value of ``Host`` header field.  In HTTP/2, the
+value of ``:authority`` pseudo header field is used.
+
+When you write multiple backend addresses sharing the same routing
+pattern, they are used as load balancing.  For example, to use 2
+servers ``serv1:3000`` and ``serv2:3000`` for request host
+``example.com`` and path ``/myservice``, you can write like so:
+
+.. code-block:: text
+
+   backend=serv1,3000;example.com/myservice
+   backend=serv2,3000;example.com/myservice
+
+For HTTP/2 backend, see also
+:option:`--backend-http2-connections-per-worker` option.