The nghttpx Reverse Proxy

I want to expose different containers on specific URL paths, possibly on different hosts, and nghttpx, from the nghttp2 library by Tatsuhiro Tsujikawa, does this in an intuitive way, and does a lot more besides.

    sudo apt-get install nghttp2-proxy

An example configuration is installed in /etc/nghttpx/nghttpx.conf, which configures nghttpx to listen for cleartext http on port localhost:3000 and proxies (e.g. forwards to) localhost:80.


The example includes a second configuration, shown below, that listens on port 3000 on all interfaces, forwarding again to localhost:80. The default behaviour of a frontend is to listen for both http and https traffic, and the latter requires that a certificate & key be specified. If these files cannot be read (e.g. missing either files, or required permissions), then the proxy will not start.



The backend entry specifies the IP and port number of the web server that will handle requests. You can specify one or more patterns that must match on the request URL for this particular back-end to match (and therefore receive traffic). So, the line: –


would send requests that match either of the two given patterns (separated by : colon ) to the back-end at, port 80 . Note however that nghttpx applies priorities when matching – a pattern that includes a host will match before one that has only a path. Wildcards can be used for hosts and paths, but more specific non-wildcard patterns will match first. Also, longer paths will match before shorter paths. You should check the man page to get a concise description of matching priorities.

The other option that’s likely to be useful is errorlog-syslog=yes, particularly when getting things up and running. By default, errors are written to /dev/stderr.

So realistically, we need our TLS/SSL keys and so we’ll use Let’s Encrypt via Neil Pang’s excellent script. My nghttpx configuration is shown below, and you can see I install my TLS certificate files right beside the reverse-proxy configuration file.

   # Define keys for frontend TLS

   # Two front ends, one http, the other https

   # Two backends, one for roundcube, and one catch-all

   # Logs are useful, and we don't need many workers

To solve the problem of issuing certificates for servers in multiple containers, I use standalone mode on port 88, and configure nghttpx to forward all traffic matching ‘/.well-known/’ to this port on localhost.

./ --issue --standalone -d -d -d -d --httpport 88

This is quite neat because it’s so simple, and because certificate issue and renewal does not interfere with any existing servers. All that’s required in nghttpx.conf in order to support the above issue command: –


The above line says that any request containing /.well-known/should be handled by port 88 on localhost (the standalone server).

However, where two possible back-ends can match, any rule with a specific host would take priority. Therefore, it’s more complete to include a backend for each host that will be challenged by the Let’ s Encrypt ACME protocol (as defined when we requested the certificate be issued).

# Each host in the issue command is defined here for completeness.

This way, regardless of what other back-ends are configured for the above hosts, anything with the /.well-known/ path will be handled by the right back-end.

A reload or restart is needed for changes to take effect. I haven’t noticed any way to test a configuration without applying it, so it’s probably worth having a failsafe copy of your configuration file to hand if you’re working on a production server.

Forward real IP address to back ends

With a reverse proxy, the connection to the back end web-server comes from the proxy process, not from the user’s client. Therefore, it’s our proxy server’s IP address that shows up in the logs, which is rarely useful.

To fix this, nghttpx can add extra headers to declare the original IP address for a request. The configuration options below tell nghttpx to strip out existing headers (giving us a ‘clean slate’), and to add headers to the request to declare the client’s IP address.

  # Add these to /etc/nghttpx/nghttpx.conf

Then, we need to modify the LogFormat definition in /etc/apache2/apache2.conf for the format named combined (assuming this is the log format you are using for your site).

If you modify that format string, changing ‘%h‘ to ‘%a‘, then Apache will log the address that nghttpx gives us in the ‘forwarded’ headers. Note that you need to enable mod_remoteip (e.g. sudo a2enmod remoteip) to use this feature. See the Apache mod_remoteip documentation for more detailed information.

LetsEncrypt for the host and containers.

Using a reverse proxy to direct traffic to containers complicates our certificate handling, since there may be multiple servers of different kinds that need to be kept up to date. The way I chose to address this, as mentioned above, is to use the standalone server option when issuing and renewing. This certificate is needed on the host for the proxy, but also for SMTP and IMAP servers.

So, here are the configuration files that define place to copy the certificate files when renewing. Note that there’s no longer a need to apply the certificate to Apache or Nginx – the proxy speaks cleartext to the back-ends.

  ssl_cert = </etc/ssl/certs/
  ssl_key = </etc/ssl/private/

   pki certificate "/etc/ssl/certs/"
   pki key "/etc/ssl/private/"

In any case, all installation can be handled by deployhooks that offers, or even just a custom script to handle installation via the reloadcmd parameter.


Leave a Reply

Your email address will not be published. Required fields are marked *