doc/sources/nghttpx-howto.rst

   1 nghttpx - HTTP/2 proxy - HOW-TO
   2 ===============================
   3
   4 nghttpx is a proxy translating protocols between HTTP/2 and other
   5 protocols (e.g., HTTP/1, SPDY).  It operates in several modes and each
   6 mode may require additional programs to work with.  This article
   7 describes each operation mode and explains the intended use-cases.  It
   8 also covers some useful options later.
   9
  10 Default mode
  11 ------------
  12
  13 If nghttpx is invoked without any ``-s``, ``-p`` and ``--client``, it
  14 operates in default mode.  In this mode, nghttpx frontend listens for
  15 HTTP/2 requests and translates them to HTTP/1 requests.  Thus it works
  16 as reverse proxy (gateway) for HTTP/2 clients to HTTP/1 web server.
  17 HTTP/1 requests are also supported in frontend as a fallback.  If
  18 nghttpx is linked with spdylay library and frontend connection is
  19 SSL/TLS, the frontend also supports SPDY protocol.
  20
  21 By default, this mode's frontend connection is encrypted using
  22 SSL/TLS.  So server's private key and certificate must be supplied to
  23 the command line (or through configuration file).  In this case, the
  24 frontend protocol selection will is done via ALPN or NPN.
  25
  26 With ``--frontend-no-tls`` option, user can turn off SSL/TLS in
  27 frontend connection.  In this case, SPDY protocol is not available
  28 even if spdylay library is liked to nghttpx.  HTTP/2 and HTTP/1 are
  29 available on the frontend and a HTTP/1 connection can be upgraded to
  30 HTTP/2 using HTTP Upgrade.  Starting HTTP/2 connection by sending
  31 HTTP/2 connection preface is also supported.
  32
  33 The backend is supposed to be HTTP/1 Web server.  For example, to make
  34 nghttpx listen to encrypted HTTP/2 requests at port 8443, and a
  35 backend HTTP/1 web server is configured to listen to HTTP/1 request at
  36 port 8080 in the same host, run nghttpx command-line like this::
  37
  38     $ nghttpx -f0.0.0.0,8443 -b127.0.0.1,8080 /path/to/server.key /path/to/server.crt
  39
  40 Then HTTP/2 enabled client can access to the nghttpx in HTTP/2.  For
  41 example, you can send GET request to the server using nghttp::
  42
  43     $ nghttp -nv https://localhost:8443/
  44
  45 HTTP/2 proxy mode
  46 -----------------
  47
  48 If nghttpx is invoked with ``-s`` option, it operates in HTTP/2 proxy
  49 mode.  The supported protocols in frontend and backend connections are
  50 the same in `default mode`_.  The difference is that this mode acts
  51 like forward proxy and assumes the backend is HTTP/1 proxy server
  52 (e.g., squid, traffic server).  So HTTP/1 request must include
  53 absolute URI in request line.
  54
  55 By default, frontend connection is encrypted.  So this mode is also
  56 called secure proxy.  If nghttpx is linked with spdylay, it supports
  57 SPDY protocols and it works as so called SPDY proxy.
  58
  59 With ``--frontend-no-tls`` option, SSL/TLS is turned off in frontend
  60 connection, so the connection gets insecure.
  61
  62 The backend must be HTTP/1 proxy server.  nghttpx supports multiple
  63 backend server addresses.  It translates incoming requests to HTTP/1
  64 request to backend server.  The backend server performs real proxy
  65 work for each request, for example, dispatching requests to the origin
  66 server and caching contents.
  67
  68 For example, to make nghttpx listen to encrypted HTTP/2 requests at
  69 port 8443, and a backend HTTP/1 proxy server is configured to listen
  70 to HTTP/1 request at port 8080 in the same host, run nghttpx
  71 command-line like this::
  72
  73     $ nghttpx -s -f'*,8443' -b127.0.0.1,8080 /path/to/server.key /path/to/server.crt
  74
  75 At the time of this writing, Firefox nightly supports HTTP/2 proxy.
  76 Chromium can use nghttpx as secure (SPDY) proxy and will support
  77 HTTP/2 proxy in the near future.
  78
  79 To make Firefox nightly or Chromium use nghttpx as HTTP/2 or SPDY
  80 proxy, user has to create proxy.pac script file like this:
  81
  82 .. code-block:: javascript
  83
  84     function FindProxyForURL(url, host) {
  85         return "HTTPS SERVERADDR:PORT";
  86     }
  87
  88 ``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
  89 machine nghttpx is running.  Please note that both Firefox nightly and
  90 Chromium require valid certificate for secure proxy.
  91
  92 For Firefox nightly, open Preference window and select Advanced then
  93 click Network tab.  Clicking Connection Settings button will show the
  94 dialog.  Select "Automatic proxy configuration URL" and enter the path
  95 to proxy.pac file, something like this::
  96
  97     file:///path/to/proxy.pac
  98
  99 For Chromium, use following command-line::
 100
 101     $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
 102
 103 As HTTP/1 proxy server, Squid may work as out-of-box.  Traffic server
 104 requires to be configured as forward proxy.  Here is the minimum
 105 configuration items to edit::
 106
 107     CONFIG proxy.config.reverse_proxy.enabled INT 0
 108     CONFIG proxy.config.url_remap.remap_required INT 0
 109
 110 Consult Traffic server `documentation
 111 <https://docs.trafficserver.apache.org/en/latest/admin/forward-proxy.en.html>`_
 112 to know how to configure traffic server as forward proxy and its
 113 security implications.
 114
 115 Client mode
 116 -----------
 117
 118 If nghttpx is invoked with ``--client`` option, it operates in client
 119 mode.  In this mode, nghttpx listens for plain, unencrypted HTTP/2 and
 120 HTTP/1 requests and translates them to encrypted HTTP/2 requests to
 121 the backend.  User cannot enable SSL/TLS in frontend connection.
 122
 123 HTTP/1 frontend connection can be upgraded to HTTP/2 using HTTP
 124 Upgrade.  To disable SSL/TLS in backend connection, use
 125 ``--backend-no-tls`` option.
 126
 127 By default, the number of backend HTTP/2 connections per worker
 128 (thread) is determined by number of ``-b`` option.  To adjust this
 129 value, use ``--backend-http2-connections-per-worker`` option.
 130
 131 The backend server is supporsed to be a HTTP/2 web server (e.g.,
 132 nghttpd).  The one use-case of this mode is utilize existing HTTP/1
 133 clients to test HTTP/2 deployment.  Suppose that HTTP/2 web server
 134 listens to port 80 without encryption.  Then run nghttpx as client
 135 mode to access to that web server::
 136
 137     $ nghttpx --client -f127.0.0.1,8080 -b127.0.0.1,80 --backend-no-tls
 138
 139 .. note::
 140
 141     You may need ``-k`` option if HTTP/2 server enables SSL/TLS and
 142     its certificate is self-signed. But please note that it is
 143     insecure.
 144
 145 Then you can use curl to access HTTP/2 server via nghttpx::
 146
 147     $ curl http://localhost:8080/
 148
 149 Client proxy mode
 150 -----------------
 151
 152 If nghttpx is invoked with ``-p`` option, it operates in client proxy
 153 mode.  This mode behaves like `client mode`_, but it works like
 154 forward proxy.  So HTTP/1 request must include absolute URI in request
 155 line.
 156
 157 HTTP/1 frontend connection can be upgraded to HTTP/2 using HTTP
 158 Upgrade.  To disable SSL/TLS in backend connection, use
 159 ``--backend-no-tls`` option.
 160
 161 By default, the number of backend HTTP/2 connections per worker
 162 (thread) is determined by number of ``-b`` option.  To adjust this
 163 value, use ``--backend-http2-connections-per-worker`` option.
 164
 165 The backend server must be a HTTP/2 proxy.  You can use nghttpx in
 166 `HTTP/2 proxy mode`_ as backend server.  The one use-case of this mode
 167 is utilize existing HTTP/1 clients to test HTTP/2 connections between
 168 2 proxies. The another use-case is use this mode to aggregate local
 169 HTTP/1 connections to one HTTP/2 backend encrypted connection.  This
 170 makes HTTP/1 clients which does not support secure proxy can use
 171 secure HTTP/2 proxy via nghttpx client mode.
 172
 173 Suppose that HTTP/2 proxy listens to port 8443, just like we saw in
 174 `HTTP/2 proxy mode`_.  To run nghttpx in client proxy mode to access
 175 that server, invoke nghttpx like this::
 176
 177     $ nghttpx -p -f127.0.0.1,8080 -b127.0.0.1,8443
 178
 179 .. note::
 180
 181     You may need ``-k`` option if HTTP/2 server's certificate is
 182     self-signed. But please note that it is insecure.
 183
 184 Then you can use curl to issue HTTP request via HTTP/2 proxy::
 185
 186     $ curl --http-proxy=http://localhost:8080 http://www.google.com/
 187
 188 You can configure web browser to use localhost:8080 as forward
 189 proxy.
 190
 191 HTTP/2 bridge mode
 192 ------------------
 193
 194 If nghttpx is invoked with ``--http2-bridge`` option, it operates in
 195 HTTP/2 bridge mode.  The supported protocols in frontend connections
 196 are the same in `default mode`_.  The protocol in backend is HTTP/2
 197 only.
 198
 199 With ``--frontend-no-tls`` option, SSL/TLS is turned off in frontend
 200 connection, so the connection gets insecure.  To disable SSL/TLS in
 201 backend connection, use ``--backend-no-tls`` option.
 202
 203 By default, the number of backend HTTP/2 connections per worker
 204 (thread) is determined by number of ``-b`` option.  To adjust this
 205 value, use ``--backend-http2-connections-per-worker`` option.
 206
 207 The backend server is supporsed to be a HTTP/2 web server or HTTP/2
 208 proxy.  If backend server is HTTP/2 proxy, use
 209 ``--no-location-rewrite`` and ``--no-host-rewrite`` options to disable
 210 rewriting location, host and :authority header field.
 211
 212 The use-case of this mode is aggregate the incoming connections to one
 213 HTTP/2 connection.  One backend HTTP/2 connection is created per
 214 worker (thread).
 215
 216 Disable SSL/TLS
 217 ---------------
 218
 219 In `default mode`_, `HTTP/2 proxy mode`_ and `HTTP/2 bridge mode`_,
 220 frontend connections are encrypted with SSL/TLS by default.  To turn
 221 off SSL/TLS, use ``--frontend-no-tls`` option.  If this option is
 222 used, the private key and certificate are not required to run nghttpx.
 223
 224 In `client mode`_, `client proxy mode`_ and `HTTP/2 bridge mode`_,
 225 backend connections are encrypted with SSL/TLS by default.  To turn
 226 off SSL/TLS, use ``--backend-no-tls`` option.
 227
 228 Specifying additional CA certificate
 229 ------------------------------------
 230
 231 By default, nghttpx tries to read CA certificate from system.  But
 232 depending on the system you use, this may fail or is not supported.
 233 To specify CA certificate manually, use ``--cacert`` option.  The
 234 specified file must be PEM format and can contain multiple
 235 certificates.
 236
 237 By default, nghttpx validates server's certificate.  If you want to
 238 turn off this validation, knowing this is really insecure and what you
 239 are doing, you can use ``-k`` option to disable certificate
 240 validation.
 241
 242 Read/write rate limit
 243 ---------------------
 244
 245 nghttpx supports transfer rate limiting on frontend connections.  You
 246 can do rate limit per frontend connection for reading and writing
 247 individually.
 248
 249 To perform rate limit for reading, use ``--read-rate`` and
 250 ``--read-burst`` options.  For writing, use ``--write-rate`` and
 251 ``--write-burst``.
 252
 253 Please note that rate limit is performed on top of TCP and nothing to
 254 do with HTTP/2 flow control.
 255
 256 Rewriting location header field
 257 -------------------------------
 258
 259 nghttpx automatically rewrites location response header field if the
 260 following all conditions satisfy:
 261
 262 * URI in location header field is not absolute URI or is not https URI.
 263 * URI in location header field includes non empty host component.
 264 * host (without port) in URI in location header field must match the
 265   host appearing in :authority or host header field.
 266
 267 When rewrite happens, URI scheme and port are replaced with the ones
 268 used in frontend, and host is replaced with which appears in
 269 :authority or host request header field.  :authority header field has
 270 precedence.  If the above conditions are not met with the host value
 271 in :authority header field, rewrite is retried with the value in host
 272 header field.
 273
 274 Hot swapping
 275 ------------
 276
 277 nghttpx supports hot swapping using signals.  The hot swapping in
 278 nghttpx is multi step process.  First send USR2 signal to nghttpx
 279 process.  It will do fork and execute new executable, using same
 280 command-line arguments and environment variables.  At this point, both
 281 current and new processes can accept requests.  To gracefully shutdown
 282 current process, send QUIT signal to current nghttpx process.  When
 283 all existing frontend connections are done, the current process will
 284 exit.  At this point, only new nghttpx process exists and serves
 285 incoming requests.
 286
 287 Re-opening log files
 288 --------------------
 289
 290 When rotating log files, it is desirable to re-open log files after
 291 log rotation daemon renamed existing log files.  To tell nghttpx to
 292 re-open log files, send USR1 signal to nghttpx process.  It will
 293 re-open files specified by ``--accesslog-file`` and
 294 ``--errorlog-file`` options.
 295
 296 Multiple backend addresses
 297 --------------------------
 298
 299 nghttpx supports multiple backend addresses.  To specify them, just
 300 use ``-b`` option repeatedly.  For example, to use backend1:8080 and
 301 backend2:8080, use command-line like this: ``-bbackend1,8080
 302 -bbackend2,8080``.  For HTTP/2 backend, see also
 303 ``--backend-http2-connections-per-worker`` option.