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 fontend 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 only supports
  63 multiple backend server addresses.  It translates incoming requests to
  64 HTTP/1 request to backend server.  The backend server performs real
  65 proxy work for each request, for example, dispatching requests to the
  66 origin 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 The backend connection is created one per worker (thread).
 128
 129 The backend server is supporsed to be a HTTP/2 web server (e.g.,
 130 nghttpd).  The one use-case of this mode is utilize existing HTTP/1
 131 clients to test HTTP/2 deployment.  Suppose that HTTP/2 web server
 132 listens to port 80 without encryption.  Then run nghttpx as client
 133 mode to access to that web server::
 134
 135     $ nghttpx --client -f127.0.0.1,8080 -b127.0.0.1,80 --backend-no-tls
 136
 137 .. note::
 138
 139     You may need ``-k`` option if HTTP/2 server enables SSL/TLS and
 140     its certificate is self-signed. But please note that it is
 141     insecure.
 142
 143 Then you can use curl to access HTTP/2 server via nghttpx::
 144
 145     $ curl http://localhost:8080/
 146
 147 Client proxy mode
 148 -----------------
 149
 150 If nghttpx is invoked with ``-p`` option, it operates in client proxy
 151 mode.  This mode behaves like `client mode`_, but it works like
 152 forward proxy.  So HTTP/1 request must include absolute URI in request
 153 line.
 154
 155 HTTP/1 frontend connection can be upgraded to HTTP/2 using HTTP
 156 Upgrade.  To disable SSL/TLS in backend connection, use
 157 ``--backend-no-tls`` option.
 158
 159 The backend connection is created one per worker (thread).
 160
 161 The backend server must be a HTTP/2 proxy.  You can use nghttpx in
 162 `HTTP/2 proxy mode`_ as backend server.  The one use-case of this mode
 163 is utilize existing HTTP/1 clients to test HTTP/2 connections between
 164 2 proxies. The another use-case is use this mode to aggregate local
 165 HTTP/1 connections to one HTTP/2 backend encrypted connection.  This
 166 makes HTTP/1 clients which does not support secure proxy can use
 167 secure HTTP/2 proxy via nghttpx client mode.
 168
 169 Suppose that HTTP/2 proxy listens to port 8443, just like we saw in
 170 `HTTP/2 proxy mode`_.  To run nghttpx in client proxy mode to access
 171 that server, invoke nghttpx like this::
 172
 173     $ nghttpx -p -f127.0.0.1,8080 -b127.0.0.1,8443
 174
 175 .. note::
 176
 177     You may need ``-k`` option if HTTP/2 server's certificate is
 178     self-signed. But please note that it is insecure.
 179
 180 Then you can use curl to issue HTTP request via HTTP/2 proxy::
 181
 182     $ curl --http-proxy=http://localhost:8080 http://www.google.com/
 183
 184 You can configure web browser to use localhost:8080 as forward
 185 proxy.
 186
 187 HTTP/2 bridge mode
 188 ------------------
 189
 190 If nghttpx is invoked with ``--http2-bridge`` option, it operates in
 191 HTTP/2 bridge mode.  The supported protocols in frontend connections
 192 are the same in `default mode`_.  The protocol in backend is HTTP/2
 193 only.
 194
 195 With ``--frontend-no-tls`` option, SSL/TLS is turned off in frontend
 196 connection, so the connection gets insecure.  To disable SSL/TLS in
 197 backend connection, use ``--backend-no-tls`` option.
 198
 199 The backend server is supporsed to be a HTTP/2 web server or HTTP/2
 200 proxy.  If backend server is HTTP/2 proxy, use
 201 ``--no-location-rewrite`` and ``--no-host-rewrite`` options to disable
 202 rewriting location, host and :authority header field.
 203
 204 The use-case of this mode is aggregate the incoming connections to one
 205 HTTP/2 connection.  One backend HTTP/2 connection is created per
 206 worker (thread).
 207
 208 Disable SSL/TLS
 209 ---------------
 210
 211 In `default mode`_, `HTTP/2 proxy mode`_ and `HTTP/2 bridge mode`_,
 212 frontend connections are encrypted with SSL/TLS by default.  To turn
 213 off SSL/TLS, use ``--frontend-no-tls`` option.  If this option is
 214 used, the private key and certificate are not required to run nghttpx.
 215
 216 In `client mode`_, `client proxy mode`_ and `HTTP/2 bridge mode`_,
 217 backend connections are encrypted with SSL/TLS by default.  To turn
 218 off SSL/TLS, use ``--backend-no-tls`` option.
 219
 220 Specifying additional CA certificate
 221 ------------------------------------
 222
 223 By default, nghttpx tries to read CA certificate from system.  But
 224 depending on the system you use, this may fail or is not supported.
 225 To specify CA certificate manually, use ``--cacert`` option.  The
 226 specified file must be PEM format and can contain multiple
 227 certificates.
 228
 229 By default, nghttpx validates server's certificate.  If you want to
 230 turn off this validation, knowing this is really insecure and what you
 231 are doing, you can use ``-k`` option to disable certificate
 232 validation.
 233
 234 Read/write rate limit
 235 ---------------------
 236
 237 nghttpx supports transfer rate limiting on frontend connections.  You
 238 can do rate limit per frontend connection for reading and writeing
 239 individually.
 240
 241 To perform rate limit for reading, use ``--read-rate`` and
 242 ``--read-burst`` options.  For writing, use ``--write-rate`` and
 243 ``--write-burst``.
 244
 245 Please note that rate limit is performed on top of TCP and nothing to
 246 do with HTTP/2 flow control.
 247
 248 Rewriting location header field
 249 -------------------------------
 250
 251 nghttpx automatically rewrites location response header field if the
 252 following all conditions satisfy:
 253
 254 * URI in location header field is not absolute URI or is not https URI.
 255 * URI in location header field includes non empty host component.
 256 * host (without port) in URI in location header field must match the
 257   host appearing in :authority or host header field.
 258
 259 When rewrite happens, URI scheme and port are replaced with the ones
 260 used in frontend, and host is replaced with which appears in
 261 :authority or host request header field.  :authority header field has
 262 precedence.  If the above conditions are not met with the host value
 263 in :authority header field, rewrite is retried with the value in host
 264 header field.
 265
 266 Hot swapping
 267 ------------
 268
 269 nghttpx supports hot swapping using signals.  The hot swapping in
 270 nghttpx is multi step process.  First send USR2 signal to nghttpx
 271 process.  It will do fork and execute new executable, using same
 272 command-line arguments and environment variables.  At this point, both
 273 current and new processes can accept requests.  To gracefully shutdown
 274 current process, send QUIT signal to current nghttpx process.  When
 275 all existing frontend connections are done, the current process will
 276 exit.  At this point, only new nghttpx process exists and serves
 277 incoming requests.
 278
 279 Re-opening log files
 280 --------------------
 281
 282 When rotating log files, it is desirable to re-open log files after
 283 log rotation daemon renamed existing log files.  To tell nghttpx to
 284 re-open log files, send USR1 signal to nghttpx process.  It will
 285 re-open files specified by ``--accesslog-file`` and
 286 ``--errorlog-file`` options.
 287
 288 Multiple HTTP/1 backend addresses
 289 ---------------------------------
 290
 291 nghttpx supports multiple HTTP/1 backend addresses.  To specify them,
 292 just use ``-b`` option repeatedly.  For example, to use backend1:8080
 293 and backend2:8080, use command-line like this: ``-bbackend1,8080
 294 -bbackend2,8080``.  Please note that HTTP/2 backend only supports 1
 295 backend address.