walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

nghttpx: Update doc

This commit is contained in:
Tatsuhiro Tsujikawa 2016-02-28 23:12:57 +09:00
parent 2326337d32
commit df6466cfbd
4 changed files with 112 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.rst
View File

@ -655,46 +655,38 @@ HTTP/2. ``nghttpx`` also offers the functionality to share session
cache and ticket keys among multiple ``nghttpx`` instances via cache and ticket keys among multiple ``nghttpx`` instances via
memcached. memcached.
``nghttpx`` has several operational modes: ``nghttpx`` has 2 operation modes:
================== ============================ ============== ============= ================== ====================== =================== =============
Mode option Frontend Backend Note Mode option Frontend Backend Note
================== ============================ ============== ============= ================== ====================== =================== =============
default mode HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1 Reverse proxy default mode HTTP/2, SPDY, HTTP/1.1 HTTP/1.1, HTTP/2 Reverse proxy
``--http2-proxy`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1 SPDY proxy ``--http2-proxy`` HTTP/2, SPDY, HTTP/1.1 HTTP/1.1, or HTTP/2 Forward proxy
``--http2-bridge`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/2 (TLS) ================== ====================== =================== =============
``--client`` HTTP/2, HTTP/1.1 HTTP/2 (TLS)
``--client-proxy`` HTTP/2, HTTP/1.1 HTTP/2 (TLS) Forward proxy
================== ============================ ============== =============
The interesting mode at the moment is the default mode. It works like The interesting mode at the moment is the default mode. It works like
a reverse proxy and listens for HTTP/2, SPDY and HTTP/1.1 and can be a reverse proxy and listens for HTTP/2, SPDY and HTTP/1.1 and can be
deployed as a SSL/TLS terminator for existing web server. deployed as a SSL/TLS terminator for existing web server.
The default mode, ``--http2-proxy`` and ``--http2-bridge`` modes use In all modes, the frontend connections are encrypted by SSL/TLS by
SSL/TLS in the frontend connection by default. To disable SSL/TLS, default. To disable encryption, use the ``--frontend-no-tls`` option.
use the ``--frontend-no-tls`` option. If that option is used, SPDY is If encryption is disabled, SPDY is disabled in the frontend and
disabled in the frontend and incoming HTTP/1.1 connections can be incoming HTTP/1.1 connections can be upgraded to HTTP/2 through HTTP
upgraded to HTTP/2 through HTTP Upgrade. In these modes, HTTP/1 Upgrade. On the other hard, backend connections are not encrypted by
backend connections are cleartext by default. To enable TLS, use default. To encrypt backend connections, use ``--backend-tls``
``--backend-http1-tls`` opiton. option.
The ``--http2-bridge``, ``--client`` and ``--client-proxy`` modes use
SSL/TLS in the backend connection by default. To disable SSL/TLS, use
the ``--backend-no-tls`` option.
``nghttpx`` supports a configuration file. See the ``--conf`` option and ``nghttpx`` supports a configuration file. See the ``--conf`` option and
sample configuration file ``nghttpx.conf.sample``. sample configuration file ``nghttpx.conf.sample``.
In the default mode, (without any of ``--http2-proxy``, In the default mode, ``nghttpx`` works as reverse proxy to the backend
``--http2-bridge``, ``--client-proxy`` and ``--client`` options), server::
``nghttpx`` works as reverse proxy to the backend server::
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Web Server Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1, HTTP/2) --> Web Server
[reverse proxy] [reverse proxy]
With the ``--http2-proxy`` option, it works as a so called secure proxy (aka With the ``--http2-proxy`` option, it works as forward proxy, and it
SPDY proxy):: is so called secure HTTP/2 proxy (aka SPDY proxy)::
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
[secure proxy] (e.g., Squid, ATS) [secure proxy] (e.g., Squid, ATS)
@ -702,9 +694,9 @@ SPDY proxy)::
The ``Client`` in the above example needs to be configured to use The ``Client`` in the above example needs to be configured to use
``nghttpx`` as secure proxy. ``nghttpx`` as secure proxy.
At the time of this writing, Chrome is the only browser which supports At the time of this writing, both Chrome and Firefox support secure
secure proxy. One way to configure Chrome to use a secure proxy is HTTP/2 proxy. One way to configure Chrome to use a secure proxy is to
to create a proxy.pac script like this: create a proxy.pac script like this:
.. code-block:: javascript .. code-block:: javascript
@ -720,37 +712,9 @@ Then run Chrome with the following arguments::
$ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
With ``--http2-bridge``, it accepts HTTP/2, SPDY and HTTP/1.1 The backend HTTP/2 connections can be tunneled through an HTTP proxy.
connections and communicates with the backend in HTTP/2::
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web or HTTP/2 Proxy etc
(e.g., nghttpx -s)
With ``--client-proxy``, it works as a forward proxy and expects
that the backend is an HTTP/2 proxy::
Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> HTTP/2 Proxy
[forward proxy] (e.g., nghttpx -s)
The ``Client`` needs to be configured to use nghttpx as a forward
proxy. The frontend HTTP/1.1 connection can be upgraded to HTTP/2
through HTTP Upgrade. With the above configuration, one can use
HTTP/1.1 client to access and test their HTTP/2 servers.
With ``--client``, it works as a reverse proxy and expects that
the backend is an HTTP/2 Web server::
Client <-- (HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) --> Web Server
[reverse proxy]
The frontend HTTP/1.1 connection can be upgraded to HTTP/2
through HTTP Upgrade.
For the operation modes which talk to the backend in HTTP/2 over
SSL/TLS, the backend connections can be tunneled through an HTTP proxy.
The proxy is specified using ``--backend-http-proxy-uri``. The The proxy is specified using ``--backend-http-proxy-uri``. The
following figure illustrates the example of the ``--http2-bridge`` and following figure illustrates how nghttpx talks to the outside HTTP/2
``--backend-http-proxy-uri`` options to talk to the outside HTTP/2
proxy through an HTTP proxy:: proxy through an HTTP proxy::
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) -- Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --

10
doc/nghttpx.h2r
View File

@ -98,12 +98,12 @@ Currently, the following restriction is applied for server push:
This limitation may be loosened in the future release. This limitation may be loosened in the future release.
nghttpx also supports server push if both frontend and backend are nghttpx also supports server push if both frontend and backend are
HTTP/2 (which implies :option:`--http2-bridge` or :option:`--client`). HTTP/2 in default mode. In this case, in addition to server push via
In this case, in addition to server push via Link header field, server Link header field, server push from backend is forwarded to frontend
push from backend is relayed to frontend HTTP/2 session. HTTP/2 session.
HTTP/2 server push will be disabled if :option:`--http2-proxy` or HTTP/2 server push will be disabled if :option:`--http2-proxy` is
:option:`--client-proxy` is used. used.
UNIX DOMAIN SOCKET UNIX DOMAIN SOCKET
------------------ ------------------

223
doc/sources/nghttpx-howto.rst
View File

@ -12,37 +12,38 @@ use-cases. It also covers some useful options later.
Default mode Default mode
------------ ------------
If nghttpx is invoked without any :option:`--http2-proxy`, If nghttpx is invoked without :option:`--http2-proxy`, it operates in
:option:`--client`, and :option:`--client-proxy`, it operates in default mode. In this mode, it works as reverse proxy (gateway) for
default mode. In this mode, nghttpx frontend listens for HTTP/2 both HTTP/2 and HTTP/1 clients to backend servers. This is also known
requests and translates them to HTTP/1 requests. Thus it works as as "HTTP/2 router". If nghttpx is linked with spdylay library and
reverse proxy (gateway) for HTTP/2 clients to HTTP/1 web server. This frontend connection is SSL/TLS, the frontend also supports SPDY
is also known as "HTTP/2 router". 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. protocol.
By default, this mode's frontend connection is encrypted using By default, frontend connection is encrypted using SSL/TLS. So
SSL/TLS. So server's private key and certificate must be supplied to server's private key and certificate must be supplied to the command
the command line (or through configuration file). In this case, the line (or through configuration file). In this case, the frontend
frontend protocol selection will be done via ALPN or NPN. protocol selection will be done via ALPN or NPN.
With :option:`--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 frontend connection. In this case, SPDY protocol is not available
even if spdylay library is liked to nghttpx. HTTP/2 and HTTP/1 are 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 available on the frontend, and an HTTP/1 connection can be upgraded to
HTTP/2 using HTTP Upgrade. Starting HTTP/2 connection by sending HTTP/2 using HTTP Upgrade. Starting HTTP/2 connection by sending
HTTP/2 connection preface is also supported. HTTP/2 connection preface is also supported.
By default, backend HTTP/1 connections are not encrypted. To enable By default, backend connections are not encrypted. To enable TLS
TLS on HTTP/1 backend connections, use :option:`--backend-http1-tls` encryption on backend connections, use :option:`--backend-tls` option.
option. This applies to all mode whose backend connections are Using patterns and ``proto`` keyword in :option:`--backend` option,
HTTP/1. backend application protocol can be specified per host/request path
pattern. It means that you can use both HTTP/2 and HTTP/1 in backend
connections at the same time. Note that default backend protocol is
HTTP/1.1. To use HTTP/2 in backend, you have to specify ``h2`` in
``proto`` keyword in :option:`--backend` explicitly.
The backend is supposed to be HTTP/1 Web server. For example, to make The backend is supposed to be Web server. For example, to make
nghttpx listen to encrypted HTTP/2 requests at port 8443, and a 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 backend Web server is configured to listen to HTTP request at port
port 8080 in the same host, run nghttpx command-line like this:: 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 $ nghttpx -f0.0.0.0,8443 -b127.0.0.1,8080 /path/to/server.key /path/to/server.crt
@ -58,8 +59,8 @@ If nghttpx is invoked with :option:`--http2-proxy` (or its shorthand
:option:`-s`) option, it operates in HTTP/2 proxy mode. The supported :option:`-s`) option, it operates in HTTP/2 proxy mode. The supported
protocols in frontend and backend connections are the same in `default protocols in frontend and backend connections are the same in `default
mode`_. The difference is that this mode acts like forward proxy and mode`_. The difference is that this mode acts like forward proxy and
assumes the backend is HTTP/1 proxy server (e.g., squid, traffic assumes the backend is HTTP proxy server (e.g., Squid, Apache Traffic
server). So HTTP/1 request must include absolute URI in request line. Server). HTTP/1 request must include absolute URI in request line.
By default, frontend connection is encrypted. So this mode is also By default, frontend connection is encrypted. So this mode is also
called secure proxy. If nghttpx is linked with spdylay, it supports called secure proxy. If nghttpx is linked with spdylay, it supports
@ -68,16 +69,22 @@ SPDY protocols and it works as so called SPDY proxy.
With :option:`--frontend-no-tls` option, SSL/TLS is turned off in With :option:`--frontend-no-tls` option, SSL/TLS is turned off in
frontend connection, so the connection gets insecure. frontend connection, so the connection gets insecure.
The backend must be HTTP/1 proxy server. nghttpx supports multiple The backend must be HTTP proxy server. nghttpx supports multiple
backend server addresses. It translates incoming requests to HTTP/1 backend server addresses. It translates incoming requests to HTTP
request to backend server. The backend server performs real proxy request to backend server. The backend server performs real proxy
work for each request, for example, dispatching requests to the origin work for each request, for example, dispatching requests to the origin
server and caching contents. server and caching contents.
The backend connection is not encrypted by default. To enable
encryption, use :option:`--backend-tls` option. The default backend
protocol is HTTP/1.1. To use HTTP/2 in backend connection, use
:option:`--backend` option, and specify ``h2`` in ``proto`` keyword
explicitly.
For example, to make nghttpx listen to encrypted HTTP/2 requests at 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 port 8443, and a backend HTTP proxy server is configured to listen to
to HTTP/1 request at port 8080 in the same host, run nghttpx HTTP/1 request at port 8080 in the same host, run nghttpx command-line
command-line like this:: like this::
$ nghttpx -s -f'*,8443' -b127.0.0.1,8080 /path/to/server.key /path/to/server.crt $ nghttpx -s -f'*,8443' -b127.0.0.1,8080 /path/to/server.key /path/to/server.crt
@ -122,126 +129,19 @@ Consult Traffic server `documentation
to know how to configure traffic server as forward proxy and its to know how to configure traffic server as forward proxy and its
security implications. security implications.
Client mode Disable frontend SSL/TLS
----------- ------------------------
If nghttpx is invoked with :option:`--client` option, it operates in The frontend connections are encrypted with SSL/TLS by default. To
client mode. In this mode, nghttpx listens for plain, unencrypted turn off SSL/TLS, use :option:`--frontend-no-tls` option. If this
HTTP/2 and HTTP/1 requests and translates them to encrypted HTTP/2 option is used, the private key and certificate are not required to
requests to the backend. User cannot enable SSL/TLS in frontend run nghttpx.
connection.
HTTP/1 frontend connection can be upgraded to HTTP/2 using HTTP Enable backend SSL/TLS
Upgrade. To disable SSL/TLS in backend connection, use ----------------------
:option:`--backend-no-tls` option.
A single HTTP/2 backend connection is shared among multiple frontend The backend connections are not encrypted by default. To enable
connections. SSL/TLS encryption, :option:`--backend-tls` 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
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 :option:`--insecure` (or its shorthand :option:`-k`)
option if HTTP/2 server enables SSL/TLS and its 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 access HTTP/2 server via nghttpx::
$ curl http://localhost:8080/
Client proxy mode
-----------------
If nghttpx is invoked with :option:`--client-proxy` (or its shorthand
:option:`-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
:option:`--backend-no-tls` option.
A single HTTP/2 backend connection is shared among multiple frontend
connections.
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 :option:`--insecure` (or its shorthand :option:`-k`)
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::
$ 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 :option:`--http2-bridge` option, it
operates in HTTP/2 bridge mode. The supported protocols in frontend
connections are the same in `default mode`_. The protocol in backend
is HTTP/2 only.
With :option:`--frontend-no-tls` option, SSL/TLS is turned off in
frontend connection, so the connection gets insecure. To disable
SSL/TLS in backend connection, use :option:`--backend-no-tls` option.
A single HTTP/2 backend connection is shared among multiple frontend
connections.
The backend server is supporsed to be a HTTP/2 web server or HTTP/2
proxy. If backend server is HTTP/2 proxy, use
:option:`--no-location-rewrite` option to disable rewriting
``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
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 :option:`--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 :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 Enable SSL/TLS on memcached connection
-------------------------------------- --------------------------------------
@ -380,3 +280,38 @@ servers ``serv1:3000`` and ``serv2:3000`` for request host
backend=serv1,3000;example.com/myservice backend=serv1,3000;example.com/myservice
backend=serv2,3000;example.com/myservice backend=serv2,3000;example.com/myservice
You can also specify backend application protocol in
:option:`--backend` option using ``proto`` keyword after pattern.
Utilizing this allows ngttpx to route certain request to HTTP/2, other
requests to HTTP/1. For example, to route requests to ``/ws/`` in
backend HTTP/1.1 connection, and use backend HTTP/2 for other
requests, do this:
.. code-block:: text
backend=serv1,3000;/;proto=h2
backend=serv1,3000;/ws/;proto=http/1.1
Note that the backends share the same pattern must have the same
backend protocol. The default backend protocol is HTTP/1.1.
Deprecated modes
----------------
As of nghttpx 1.9.0, ``--http2-bridge``, ``--client`` and
``--client-proxy`` options were removed. These functionality can be
used using combinations of options.
* ``--http2-bridge``: Use
:option:`--backend`\='-b<ADDR>,<PORT>;;proto=h2', and
:option:`--backend-tls`.
* ``--client``: Use :option:`--frontend-no-tls`,
:option:`--backend`\='-b<ADDR>,<PORT>;;proto=h2', and
:option:`--backend-tls`.
* ``--client-proxy``: Use :option:`--http2-proxy`,
:option:`--frontend-no-tls`,
:option:`--backend`\='-b<ADDR>,<PORT>;;proto=h2', and
:option:`--backend-tls`.

8
src/shrpx.cc
View File

@ -1672,10 +1672,10 @@ HTTP/2 and SPDY:
Disable HTTP/2 server push. Server push is supported by Disable HTTP/2 server push. Server push is supported by
default mode and HTTP/2 frontend via Link header field. default mode and HTTP/2 frontend via Link header field.
It is also supported if both frontend and backend are It is also supported if both frontend and backend are
HTTP/2. In this case, server push from backend session HTTP/2 in default mode. In this case, server push from
is relayed to frontend, and server push via Link header backend session is relayed to frontend, and server push
field is also supported. SPDY frontend does not support via Link header field is also supported. SPDY frontend
server push. does not support server push.
Mode: Mode:
(default mode) (default mode)