Browse Source

Add documentation for the web tunnels feature

Peter J. Jones 5 months ago
Signed by: Peter Jones <> GPG Key ID: 9DAFAA8D01941E49
1 changed files with 59 additions and 0 deletions
  1. 59

+ 59
- 0
modules/services/web/tunnels/ View File

@@ -0,0 +1,59 @@
Secure Public Tunnels to Private Services

Software developers sometimes need to provide public access to a
private resource such as web service running behind NAT or in a
virtual machine. In such situations we need a public web server with
a valid SSL/TLS certificate that forwards connections to a private
server that is using plain HTTP.

There are existing open and commercial solutions to this problem. For
example, [ngrok]( is a well-known commercial
service. However, a similar setup is fairly easy to create using

How This Works

* A public domain name points to a server you control running NixOS.

* This service starts nginx and creates the necessary SSL/TLS

* Connections on port 443 for the public domain are forwarded to a
configured port on the local system. For now let's assume we are
going to use port 9000.

* The software developer creates an SSH tunnel to the NixOS machine
running this service, forwarding remote port 9000 (or whatever
port you want) to a local host/port pair.

Example Configuration

The following NixOS configuration enables nginx for the ``
domain, requesting a SSL/TLS certificate for ``.

Requests to `` on port 443 are forwarded to port 9000.

```nix = {
enable = true;
hostName = "";

accounts = [{
authorizedKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG1g7KoenMd6JIWnIuOQOYAaPNk6rF+6vwXBqNic2Juk elphaba";
tunnels = [{subdomain = "webapp"; serverPort = 9000;}];

A software developer would take advantage of this configuration by
establishing an SSH tunnel to `` on port 9000. In this
example, let's assume the developer wants to have ``
requests sent to a local service running on port 3000:

ssh -R 9000:localhost:3000 -N