From e6fdb3418df3d98cfb7a2c52f0435691b9450b63 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sun, 20 Apr 2014 23:35:07 +0900 Subject: [PATCH] doc: Add nghttpx-howto.rst --- doc/nghttpx-howto.rst | 1 + doc/sources/index.rst | 1 + doc/sources/nghttpx-howto.rst | 232 ++++++++++++++++++++++++++++++++++ 3 files changed, 234 insertions(+) create mode 100644 doc/nghttpx-howto.rst create mode 100644 doc/sources/nghttpx-howto.rst diff --git a/doc/nghttpx-howto.rst b/doc/nghttpx-howto.rst new file mode 100644 index 00000000..462a5ffb --- /dev/null +++ b/doc/nghttpx-howto.rst @@ -0,0 +1 @@ +.. include:: ../doc/sources/nghttpx-howto.rst diff --git a/doc/sources/index.rst b/doc/sources/index.rst index 65449b9f..821a24a5 100644 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -19,6 +19,7 @@ Contents: package_README tutorial-client tutorial-server + nghttpx-howto apiref nghttp2.h nghttp2ver.h diff --git a/doc/sources/nghttpx-howto.rst b/doc/sources/nghttpx-howto.rst new file mode 100644 index 00000000..dcd3582b --- /dev/null +++ b/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.