nghttpx: Update doc
This commit is contained in:
Tatsuhiro Tsujikawa
parent
2326337d32
commit
df6466cfbd
84
README.rst
84
README.rst
|
|
@ -655,46 +655,38 @@ HTTP/2. ``nghttpx`` also offers the functionality to share session
|
|||
cache and ticket keys among multiple ``nghttpx`` instances via
|
||||
memcached.
|
||||
|
||||
``nghttpx`` has several operational modes:
|
||||
``nghttpx`` has 2 operation modes:
|
||||
|
||||
================== ============================ ============== =============
|
||||
Mode option Frontend Backend Note
|
||||
================== ============================ ============== =============
|
||||
default mode HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1 Reverse proxy
|
||||
``--http2-proxy`` HTTP/2, SPDY, HTTP/1.1 (TLS) HTTP/1.1 SPDY 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
|
||||
================== ============================ ============== =============
|
||||
================== ====================== =================== =============
|
||||
Mode option Frontend Backend Note
|
||||
================== ====================== =================== =============
|
||||
default mode HTTP/2, SPDY, HTTP/1.1 HTTP/1.1, HTTP/2 Reverse proxy
|
||||
``--http2-proxy`` HTTP/2, SPDY, HTTP/1.1 HTTP/1.1, or HTTP/2 Forward proxy
|
||||
================== ====================== =================== =============
|
||||
|
||||
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
|
||||
deployed as a SSL/TLS terminator for existing web server.
|
||||
|
||||
The default mode, ``--http2-proxy`` and ``--http2-bridge`` modes use
|
||||
SSL/TLS in the frontend connection by default. To disable SSL/TLS,
|
||||
use the ``--frontend-no-tls`` option. If that option is used, SPDY is
|
||||
disabled in the frontend and incoming HTTP/1.1 connections can be
|
||||
upgraded to HTTP/2 through HTTP Upgrade. In these modes, HTTP/1
|
||||
backend connections are cleartext by default. To enable TLS, use
|
||||
``--backend-http1-tls`` opiton.
|
||||
|
||||
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.
|
||||
In all modes, the frontend connections are encrypted by SSL/TLS by
|
||||
default. To disable encryption, use the ``--frontend-no-tls`` option.
|
||||
If encryption is disabled, SPDY is disabled in the frontend and
|
||||
incoming HTTP/1.1 connections can be upgraded to HTTP/2 through HTTP
|
||||
Upgrade. On the other hard, backend connections are not encrypted by
|
||||
default. To encrypt backend connections, use ``--backend-tls``
|
||||
option.
|
||||
|
||||
``nghttpx`` supports a configuration file. See the ``--conf`` option and
|
||||
sample configuration file ``nghttpx.conf.sample``.
|
||||
|
||||
In the default mode, (without any of ``--http2-proxy``,
|
||||
``--http2-bridge``, ``--client-proxy`` and ``--client`` options),
|
||||
``nghttpx`` works as reverse proxy to the backend server::
|
||||
In the default mode, ``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]
|
||||
|
||||
With the ``--http2-proxy`` option, it works as a so called secure proxy (aka
|
||||
SPDY proxy)::
|
||||
With the ``--http2-proxy`` option, it works as forward proxy, and it
|
||||
is so called secure HTTP/2 proxy (aka SPDY proxy)::
|
||||
|
||||
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy
|
||||
[secure proxy] (e.g., Squid, ATS)
|
||||
|
|
@ -702,9 +694,9 @@ SPDY proxy)::
|
|||
The ``Client`` in the above example needs to be configured to use
|
||||
``nghttpx`` as secure proxy.
|
||||
|
||||
At the time of this writing, Chrome is the only browser which supports
|
||||
secure proxy. One way to configure Chrome to use a secure proxy is
|
||||
to create a proxy.pac script like this:
|
||||
At the time of this writing, both Chrome and Firefox support secure
|
||||
HTTP/2 proxy. One way to configure Chrome to use a secure proxy is to
|
||||
create a proxy.pac script like this:
|
||||
|
||||
.. 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
|
||||
|
||||
With ``--http2-bridge``, it accepts HTTP/2, SPDY and HTTP/1.1
|
||||
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 backend HTTP/2 connections can be tunneled through an HTTP proxy.
|
||||
The proxy is specified using ``--backend-http-proxy-uri``. The
|
||||
following figure illustrates the example of the ``--http2-bridge`` and
|
||||
``--backend-http-proxy-uri`` options to talk to the outside HTTP/2
|
||||
following figure illustrates how nghttpx talks to the outside HTTP/2
|
||||
proxy through an HTTP proxy::
|
||||
|
||||
Client <-- (HTTP/2, SPDY, HTTP/1.1) --> nghttpx <-- (HTTP/2) --
|
||||
|
|
|
|||
|
|
@ -98,12 +98,12 @@ Currently, the following restriction is applied for server push:
|
|||
This limitation may be loosened in the future release.
|
||||
|
||||
nghttpx also supports server push if both frontend and backend are
|
||||
HTTP/2 (which implies :option:`--http2-bridge` or :option:`--client`).
|
||||
In this case, in addition to server push via Link header field, server
|
||||
push from backend is relayed to frontend HTTP/2 session.
|
||||
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` or
|
||||
:option:`--client-proxy` is used.
|
||||
HTTP/2 server push will be disabled if :option:`--http2-proxy` is
|
||||
used.
|
||||
|
||||
UNIX DOMAIN SOCKET
|
||||
------------------
|
||||
|
|
|
|||
|
|
@ -12,37 +12,38 @@ use-cases. It also covers some useful options later.
|
|||
Default mode
|
||||
------------
|
||||
|
||||
If nghttpx is invoked without any :option:`--http2-proxy`,
|
||||
:option:`--client`, and :option:`--client-proxy`, 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. This
|
||||
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
|
||||
If nghttpx is invoked without :option:`--http2-proxy`, it operates in
|
||||
default mode. In this mode, it works as reverse proxy (gateway) for
|
||||
both HTTP/2 and HTTP/1 clients to backend servers. This is also known
|
||||
as "HTTP/2 router". 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
|
||||
frontend protocol selection will be done via ALPN or NPN.
|
||||
By default, 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 :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
|
||||
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 connection preface is also supported.
|
||||
|
||||
By default, backend HTTP/1 connections are not encrypted. To enable
|
||||
TLS on HTTP/1 backend connections, use :option:`--backend-http1-tls`
|
||||
option. This applies to all mode whose backend connections are
|
||||
HTTP/1.
|
||||
By default, backend connections are not encrypted. To enable TLS
|
||||
encryption on backend connections, use :option:`--backend-tls` option.
|
||||
Using patterns and ``proto`` keyword in :option:`--backend` option,
|
||||
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
|
||||
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::
|
||||
backend Web server is configured to listen to HTTP 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
|
||||
|
||||
|
|
@ -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
|
||||
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, traffic
|
||||
server). So HTTP/1 request must include absolute URI in request line.
|
||||
assumes the backend is HTTP proxy server (e.g., Squid, Apache Traffic
|
||||
Server). 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
|
||||
|
|
@ -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
|
||||
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
|
||||
The backend must be HTTP proxy server. nghttpx supports multiple
|
||||
backend server addresses. It translates incoming requests to HTTP
|
||||
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.
|
||||
|
||||
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
|
||||
port 8443, and a backend HTTP/1 proxy server is configured to listen
|
||||
to HTTP/1 request at port 8080 in the same host, run nghttpx
|
||||
command-line like this::
|
||||
port 8443, and a backend HTTP proxy server is configured to listen to
|
||||
HTTP/1 request at port 8080 in the same host, run nghttpx command-line
|
||||
like this::
|
||||
|
||||
$ 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
|
||||
security implications.
|
||||
|
||||
Client mode
|
||||
-----------
|
||||
Disable frontend SSL/TLS
|
||||
------------------------
|
||||
|
||||
If nghttpx is invoked with :option:`--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.
|
||||
The 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.
|
||||
|
||||
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.
|
||||
Enable backend SSL/TLS
|
||||
----------------------
|
||||
|
||||
A single HTTP/2 backend connection is shared among multiple frontend
|
||||
connections.
|
||||
|
||||
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.
|
||||
The backend connections are not encrypted by default. To enable
|
||||
SSL/TLS encryption, :option:`--backend-tls` option.
|
||||
|
||||
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=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`.
|
||||
|
|
|
|||
|
|
@ -1672,10 +1672,10 @@ HTTP/2 and SPDY:
|
|||
Disable HTTP/2 server push. Server push is supported by
|
||||
default mode and HTTP/2 frontend via Link header field.
|
||||
It is also supported if both frontend and backend are
|
||||
HTTP/2. In this case, server push from backend session
|
||||
is relayed to frontend, and server push via Link header
|
||||
field is also supported. SPDY frontend does not support
|
||||
server push.
|
||||
HTTP/2 in default mode. In this case, server push from
|
||||
backend session is relayed to frontend, and server push
|
||||
via Link header field is also supported. SPDY frontend
|
||||
does not support server push.
|
||||
|
||||
Mode:
|
||||
(default mode)
|
||||
|
|
|
|||
Loading…
Reference in New Issue