{"article":{"slug":"self-hosted-http-tunnels-with-ssh-and-nginx","title":"Self-hosted HTTP tunnels with SSH and nginx","subtitle":null,"summary":"Vincent Bernat shows how to expose a localhost preview to a friend with only a plain SSH client and an nginx server you control: ssh -R with a dynamic port, an nginx server_name regex mapping per-port subdomains, wildcard TLS via ACME DNS-01, and a helper script plus NixOS module.","content_type":"tutorial","language":"en","canonical_url":"https://vincent.bernat.ch/en/blog/2026-http-over-ssh","author":{"name":"Vincent Bernat","url":"https://vincent.bernat.ch/","person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"vincent.bernat.ch","url":"https://vincent.bernat.ch/","listing_slug":null,"listing":null},"topics":[{"name":"Networking","slug":"networking","url":"https://listedarticles.com/topics/networking"},{"name":"Linux","slug":"linux","url":"https://listedarticles.com/topics/linux"},{"name":"DevOps","slug":"devops","url":"https://listedarticles.com/topics/devops"},{"name":"Tutorials","slug":"tutorials","url":"https://listedarticles.com/topics/tutorials"},{"name":"Infrastructure","slug":"infrastructure","url":"https://listedarticles.com/topics/infrastructure"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":998,"reading_minutes":4,"published_at":"2026-10-03T00:00:00.000Z","added_at":"2026-10-04T23:17:18.105Z","updated_at":"2026-10-04T23:17:18.105Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/self-hosted-http-tunnels-with-ssh-and-nginx","markdown_url":"https://listedarticles.com/articles/self-hosted-http-tunnels-with-ssh-and-nginx.md","example":false,"citation":"Vincent Bernat, vincent.bernat.ch. \"Self-hosted HTTP tunnels with SSH and nginx.\" 3 Oct 2026. https://vincent.bernat.ch/en/blog/2026-http-over-ssh (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://vincent.bernat.ch/en/blog/2026-http-over-ssh"},"body_markdown":"A friend wants to proofread your work-in-progress blog post, but its preview\nonly runs on `localhost:8080`. [Several tools](https://github.com/anderspitman/awesome-tunneling) can help. Some run as a\ncommercial service, like [ngrok](https://ngrok.com/) or [Cloudflare Quick Tunnels](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/). Some are\nself-hostable but require a specific client, like [frp](https://github.com/fatedier/frp) or [localtunnel](https://github.com/localtunnel/localtunnel).\nSome only require a plain SSH client but rely on a specific SSH server, like\n[sish](https://docs.ssi.sh/). Let’s implement a self-hosted solution with only *OpenSSH* and\n*nginx*!\n\n```\n$ ssh -R 0:localhost:8080 http-over-ssh\nAllocated port 41535 for remote forward to localhost:8080\nhttps://6J3jK1WmB15c6WmjW_X-Wg--1789928654@p41535.ssh.luffy.cx/\n```\n# Basic setup[#](https://vincent.bernat.ch#basic-setup)\n\nFirst, we forward connections from a port on a remote server to your local service:\n\n```\n$ ssh -N -R 0:localhost:8080 web02.luffy.cx\nAllocated port 41535 for remote forward to localhost:8080\n```\nWhen you specify `0` as the remote port, the server allocates a free port.\nThen, we configure nginx to proxy requests from `https://p41535.ssh.luffy.cx` to\n`http://127.0.0.1:41535`:\n\n```\nserver {\n listen 0.0.0.0:443 ssl ;\n listen [::0]:443 ssl ;\n server_name ~^p(?\\d\\d\\d\\d\\d)\\.ssh\\.luffy\\.cx$;\n location / {\n proxy_pass http://127.0.0.1:$port;\n }\n}\n```\nWe also need to add DNS records for `*.ssh.luffy.cx` and get a wildcard\ncertificate through [Let’s Encrypt](https://letsencrypt.org/):\n\n```\n*.ssh.luffy.cx. CNAME web02.luffy.cx.\nssh.luffy.cx. CAA 0 issuewild \"letsencrypt.org\"\n_acme-challenge.ssh.luffy.cx CNAME ssh.luffy.cx.acme.luffy.cx.\n```\n`acme.luffy.cx` is a zone hosted on Route 53. I use it for [ACME DNS-01\nchallenges](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge), both for wildcard certificates and for domains served by\nseveral web servers. In my case, NixOS [gets the certificates\nautomatically](https://wiki.nixos.org/wiki/ACME).\n\n# Access control[#](https://vincent.bernat.ch#access-control)\n\nThe port is the only “secret”[1](https://vincent.bernat.ch#sidenote-port) keeping the content confidential. Other\nforwarding solutions add a random string to the domain name to prevent an\nintruder from enumerating the possible values.\n\nThanks to [`ngx_http_secure_link_module`](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html), we can secure\nthis setup a bit. This module computes a hash[2](https://vincent.bernat.ch#sidenote-md5) over a set of values,\nincluding a secret, and compares it with the hash from the request. The hash is\nbase64-encoded, so we cannot put it in the domain name, which is\ncase-insensitive. Instead, we put it in the URL as a username, along with its\nexpiration timestamp:[3](https://vincent.bernat.ch#sidenote-expiration)\n\n```\nhttps://6J3jK1WmB15c6WmjW_X-Wg--1789928654@p41535.ssh.luffy.cx/en/blog\n ╰─────────┬──────────╯ ╰───┬────╯ ╰─┬─╯ ╰──┬───╯\n hash expires port path\n```\nThe client sends the username to the server with [HTTP basic\nauthentication](https://www.rfc-editor.org/rfc/rfc7617). This works with most HTTP clients, including `curl`.\nNginx exposes the username in the `$remote_user` variable. The module expects\nthe hash and the expiration timestamp separated by a comma. We use a `map`\ndirective to extract the two parts from `$remote_user` and join them with a\ncomma.[4](https://vincent.bernat.ch#sidenote-comma) We also give the module the string to hash. It contains the\nexpiration timestamp, the port, and a secret:\n\n```\nmap $remote_user $httpssh_link {\n \"~^([-_A-Za-z0-9]{22})--([0-9]+)$\" \"$1,$2\";\n}\nserver {\n # […]\n location / {\n secure_link $httpssh_link;\n secure_link_md5 \"$secure_link_expires $port ZuPerS3cr3!\";\n }\n}\n```\nThe module returns the status of the check in the `$secure_link` variable:\n\n- empty if the hashes do not match,\n- `\"0\"` if they match but the link has expired, or\n- `\"1\"` otherwise.\n\nIf the hash is incorrect or missing, we return a 401 error with a\n`WWW-Authenticate` header to ask for credentials. If the link has expired, we\nreturn a 410 error. We remove the `Authorization` header before forwarding the\nrequest and add a few directives to [proxy WebSocket connections](https://nginx.org/en/docs/http/websocket.html).\nHere is the complete configuration:[5](https://vincent.bernat.ch#sidenote-security)\n\n```\nmap $remote_user $httpssh_link {\n \"~^([-_A-Za-z0-9]{22})--([0-9]+)$\" \"$1,$2\";\n}\nserver {\n listen 0.0.0.0:443 ssl ;\n listen [::0]:443 ssl ;\n server_name ~^p(?\\d\\d\\d\\d\\d)\\.ssh\\.luffy\\.cx$;\n location / {\n secure_link $httpssh_link;\n secure_link_md5 \"$secure_link_expires $port ZuPerS3cr3!\";\n if ($secure_link = \"\") {\n add_header WWW-Authenticate 'Basic realm=\"tunnel\"' always;\n return 401;\n }\n if ($secure_link = \"0\") {\n return 410;\n }\n proxy_pass http://127.0.0.1:$port;\n proxy_set_header Host $host;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header Authorization \"\";\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_buffering off;\n proxy_read_timeout 30m;\n }\n}\n```\nI think you are now asking yourself the obvious question: “How should I generate the hash?” Easy peasy!\n\n```\n$ expires=$(( $(date +%s) + 86400 ))\n$ port=41535\n$ secret='ZuPerS3cr3!'\n$ printf '%s %s %s' \"$expires\" \"$port\" \"$secret\" \\\n> | openssl md5 -binary \\\n> | openssl base64 \\\n> | tr +/ -_ | tr -d =\n6J3jK1WmB15c6WmjW_X-Wg\n```\nWell, I suppose you are now saying: “Vincent, this is not very convenient! I’ll stick with ngrok if you don’t mind.” Okay, I hear you. Let’s write a helper script.\n\n# Helper script[#](https://vincent.bernat.ch#helper-script)\n\nThe main difficulty is finding the ephemeral port that OpenSSH allocates, as it\ndoes not appear in any environment variable.[6](https://vincent.bernat.ch#sidenote-env) To work around this obstacle,\nwe look for the ancestor `sshd-session` processes:[7](https://vincent.bernat.ch#sidenote-sshd-session)\n\n```\npids=$(\n pid=$$\n while [ \"$pid\" -gt 1 ]; do\n line=$(ps -o comm=,pid=,ppid= -p \"$pid\")\n echo \"$line\"\n pid=${line##* }\n done | awk '$1 == \"sshd-session\" { printf \"pid=%s,\\n\", $2 }'\n)\nif [ -z \"$pids\" ]; then\n echo \"not an ssh session\" >&2\n exit 1\nfi\n```\nThen, we get the listening ports associated with these `sshd-session`\nprocesses:[8](https://vincent.bernat.ch#sidenote-sudo)\n\n```\nports=$(sudo -n ss --listening --numeric --tcp --processes --no-header \\\n | grep -F \"$pids\" \\\n | awk '{ print $4 }' | awk -F: '{ print $NF }' \\\n | sort -un)\nif [ -z \"$ports\" ]; then\n echo \"no forwarded port, use ssh -R 0:localhost:PORT\" >&2\n exit 1\nfi\n```\nFinally, we display the URLs and keep the session open:\n\n```\nlifetime=86400\nsecret='ZuPerS3cr3!'\nexpires=$(( $(date +%s) + lifetime ))\nfor port in $ports; do\n token=$(printf '%s %s %s' \"$expires\" \"$port\" \"$secret\" \\\n | openssl md5 -binary \\\n | openssl base64 \\\n | tr +/ -_ | tr -d =)\n echo \"https://$token--$expires@p$port.ssh.luffy.cx/\"\ndone\nsleep infinity\n```\nI install this script as `http-over-ssh` on the server and add this entry to my\n`~/.ssh/config`:\n\n```\nHost http-over-ssh\n Hostname web02.luffy.cx\n RemoteCommand http-over-ssh\n ControlPath none\n```\nWith this solution, I only rely on OpenSSH and nginx, two pieces of software\nalready running on this server. One short command gives me a self-hosted tunnel\nand a URL to share. To try it, grab the [complete helper script](https://github.com/vincentbernat/nixops-take1/blob/master/tags/http-over-ssh.sh), which\nincludes a few minor improvements. If you run NixOS, as any person of taste\nwould, have a look at my [`http-over-ssh.nix`](https://github.com/vincentbernat/nixops-take1/blob/master/tags/http-over-ssh.nix) instead. ❄️\n","body_html":"

A friend wants to proofread your work-in-progress blog post, but its preview\nonly runs on localhost:8080. Several tools can help. Some run as a\ncommercial service, like ngrok or Cloudflare Quick Tunnels. Some are\nself-hostable but require a specific client, like frp or localtunnel.\nSome only require a plain SSH client but rely on a specific SSH server, like\nsish. Let’s implement a self-hosted solution with only OpenSSH and\nnginx!

\n
$ ssh -R 0:localhost:8080 http-over-ssh\nAllocated port 41535 for remote forward to localhost:8080\nhttps://6J3jK1WmB15c6WmjW_X-Wg--1789928654@p41535.ssh.luffy.cx/
\n

Basic setup#

\n

First, we forward connections from a port on a remote server to your local service:

\n
$ ssh -N -R 0:localhost:8080 web02.luffy.cx\nAllocated port 41535 for remote forward to localhost:8080
\n

When you specify 0 as the remote port, the server allocates a free port.\nThen, we configure nginx to proxy requests from https://p41535.ssh.luffy.cx to\nhttp://127.0.0.1:41535:

\n
server {\n  listen 0.0.0.0:443 ssl ;\n  listen [::0]:443 ssl ;\n  server_name ~^p(?<port>\\d\\d\\d\\d\\d)\\.ssh\\.luffy\\.cx$;\n  location / {\n    proxy_pass http://127.0.0.1:$port;\n  }\n}
\n

We also need to add DNS records for *.ssh.luffy.cx and get a wildcard\ncertificate through Let’s Encrypt:

\n
*.ssh.luffy.cx.               CNAME web02.luffy.cx.\nssh.luffy.cx.                 CAA   0 issuewild "letsencrypt.org"\n_acme-challenge.ssh.luffy.cx  CNAME ssh.luffy.cx.acme.luffy.cx.
\n

acme.luffy.cx is a zone hosted on Route 53. I use it for ACME DNS-01\nchallenges, both for wildcard certificates and for domains served by\nseveral web servers. In my case, NixOS gets the certificates\nautomatically.

\n

Access control#

\n

The port is the only “secret”<sup>1</sup> keeping the content confidential. Other\nforwarding solutions add a random string to the domain name to prevent an\nintruder from enumerating the possible values.

\n

Thanks to ngx_http_secure_link_module, we can secure\nthis setup a bit. This module computes a hash<sup>2</sup> over a set of values,\nincluding a secret, and compares it with the hash from the request. The hash is\nbase64-encoded, so we cannot put it in the domain name, which is\ncase-insensitive. Instead, we put it in the URL as a username, along with its\nexpiration timestamp:3

\n
https://6J3jK1WmB15c6WmjW_X-Wg--1789928654@p41535.ssh.luffy.cx/en/blog\n        ╰─────────┬──────────╯  ╰───┬────╯  ╰─┬─╯             ╰──┬───╯\n                hash             expires    port               path
\n

The client sends the username to the server with HTTP basic\nauthentication. This works with most HTTP clients, including curl.\nNginx exposes the username in the $remote_user variable. The module expects\nthe hash and the expiration timestamp separated by a comma. We use a map\ndirective to extract the two parts from $remote_user and join them with a\ncomma.<sup>4</sup> We also give the module the string to hash. It contains the\nexpiration timestamp, the port, and a secret:

\n
map $remote_user $httpssh_link {\n  "~^([-_A-Za-z0-9]{22})--([0-9]+)$" "$1,$2";\n}\nserver {\n  # […]\n  location / {\n    secure_link $httpssh_link;\n    secure_link_md5 "$secure_link_expires $port ZuPerS3cr3!";\n  }\n}
\n

The module returns the status of the check in the $secure_link variable:

\n\n

If the hash is incorrect or missing, we return a 401 error with a\nWWW-Authenticate header to ask for credentials. If the link has expired, we\nreturn a 410 error. We remove the Authorization header before forwarding the\nrequest and add a few directives to proxy WebSocket connections.\nHere is the complete configuration:5

\n
map $remote_user $httpssh_link {\n  "~^([-_A-Za-z0-9]{22})--([0-9]+)$" "$1,$2";\n}\nserver {\n  listen 0.0.0.0:443 ssl ;\n  listen [::0]:443 ssl ;\n  server_name ~^p(?<port>\\d\\d\\d\\d\\d)\\.ssh\\.luffy\\.cx$;\n  location / {\n    secure_link $httpssh_link;\n    secure_link_md5 "$secure_link_expires $port ZuPerS3cr3!";\n    if ($secure_link = "") {\n      add_header WWW-Authenticate 'Basic realm="tunnel"' always;\n      return 401;\n    }\n    if ($secure_link = "0") {\n      return 410;\n    }\n    proxy_pass http://127.0.0.1:$port;\n    proxy_set_header Host $host;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header Authorization "";\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection "upgrade";\n    proxy_buffering off;\n    proxy_read_timeout 30m;\n  }\n}
\n

I think you are now asking yourself the obvious question: “How should I generate the hash?” Easy peasy!

\n
$ expires=$(( $(date +%s) + 86400 ))\n$ port=41535\n$ secret='ZuPerS3cr3!'\n$ printf '%s %s %s' "$expires" "$port" "$secret" \\\n>   | openssl md5 -binary \\\n>   | openssl base64 \\\n>   | tr +/ -_ | tr -d =\n6J3jK1WmB15c6WmjW_X-Wg
\n

Well, I suppose you are now saying: “Vincent, this is not very convenient! I’ll stick with ngrok if you don’t mind.” Okay, I hear you. Let’s write a helper script.

\n

Helper script#

\n

The main difficulty is finding the ephemeral port that OpenSSH allocates, as it\ndoes not appear in any environment variable.<sup>6</sup> To work around this obstacle,\nwe look for the ancestor sshd-session processes:7

\n
pids=$(\n  pid=$$\n  while [ "$pid" -gt 1 ]; do\n    line=$(ps -o comm=,pid=,ppid= -p "$pid")\n    echo "$line"\n    pid=${line##* }\n  done | awk '$1 == "sshd-session" { printf "pid=%s,\\n", $2 }'\n)\nif [ -z "$pids" ]; then\n  echo "not an ssh session" >&2\n  exit 1\nfi
\n

Then, we get the listening ports associated with these sshd-session\nprocesses:8

\n
ports=$(sudo -n ss --listening --numeric --tcp --processes --no-header \\\n  | grep -F "$pids" \\\n  | awk '{ print $4 }' | awk -F: '{ print $NF }' \\\n  | sort -un)\nif [ -z "$ports" ]; then\n  echo "no forwarded port, use ssh -R 0:localhost:PORT" >&2\n  exit 1\nfi
\n

Finally, we display the URLs and keep the session open:

\n
lifetime=86400\nsecret='ZuPerS3cr3!'\nexpires=$(( $(date +%s) + lifetime ))\nfor port in $ports; do\n  token=$(printf '%s %s %s' "$expires" "$port" "$secret" \\\n            | openssl md5 -binary \\\n            | openssl base64 \\\n            | tr +/ -_ | tr -d =)\n  echo "https://$token--$expires@p$port.ssh.luffy.cx/"\ndone\nsleep infinity
\n

I install this script as http-over-ssh on the server and add this entry to my\n~/.ssh/config:

\n
Host http-over-ssh\n  Hostname web02.luffy.cx\n  RemoteCommand http-over-ssh\n  ControlPath none
\n

With this solution, I only rely on OpenSSH and nginx, two pieces of software\nalready running on this server. One short command gives me a self-hosted tunnel\nand a URL to share. To try it, grab the complete helper script, which\nincludes a few minor improvements. If you run NixOS, as any person of taste\nwould, have a look at my http-over-ssh.nix instead. ❄️

","headings":[{"level":1,"text":"Basic setup#","id":"basic-setup"},{"level":1,"text":"Access control#","id":"access-control"},{"level":1,"text":"Helper script#","id":"helper-script"}]}}