How a tunnel works
computer server web1
browser sshd
│ http://127.0.0.1:8080 │
└─→ ssh listens 127.0.0.1:8080 │
└──── SSH connection, :22 ──┴─→ 127.0.0.1:8080 → panel
Read ssh -L 8080:127.0.0.1:8080 web1 as: “listen on port 8080 here, and send whatever arrives through the
server to 127.0.0.1:8080 as the server sees it”. The address on the right is resolved on the server: there,
127.0.0.1 is the server itself, not your computer.
From the outside the panel has no port at all. A scanner sees one open port — SSH — and that doesn’t let anyone in without a key.
Which tunnel when
| Flag | What it does | When to use |
|---|---|---|
-L 8080:127.0.0.1:8080 |
a port on your computer leads to an address as the server sees it | admin panels, databases, dashboards closed to the outside |
-R 9000:127.0.0.1:3000 |
a port on the server leads to an address as your computer sees it | show something running on your laptop from the server; receive a webhook while debugging |
-D 1080 |
a SOCKS proxy on your computer; requests leave from the server | several internal addresses of the server at once, without a separate -L for each |
-J web1 |
log in to the next server through this one | a server with no public address (~/.ssh/config) |
-N — no shell, just the tunnel. -f — go to the background after login.
Open a closed admin panel
Check that the service listens only on localhost
On the server:
ss -tlnp | grep 8080 # LISTEN 0 4096 127.0.0.1:8080 0.0.0.0:* users:(("docker-proxy",pid=1734,fd=7))127.0.0.1:8080means only the server itself sees the port.0.0.0.0:8080or*:8080means it’s open to the outside: you don’t need a tunnel, you need to close the port (A host-only port goes on 127.0.0.1, Docker ports bypass the input chain).Open the tunnel
ssh -N -L 8080:127.0.0.1:8080 web1The window prints nothing and doesn’t return a prompt — that’s expected; the tunnel lives as long as the command runs. Open
http://127.0.0.1:8080in the browser. Close it withCtrl+C.Save the tunnel in ~/.ssh/config
So you don’t have to remember ports, give it its own name:
Host web1-admin HostName 203.0.113.10 User example-user IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes LocalForward 8080 127.0.0.1:8080 LocalForward 8081 127.0.0.1:8081 ExitOnForwardFailure yes SessionType noneNow
ssh web1-adminopens both ports at once.ExitOnForwardFailure yes: if a local port is taken,sshexits with an error instead of hanging around without a tunnel.SessionType noneis the same as-N, available since OpenSSH 8.7.If you need the tunnel all the time
A tunnel from your computer only needs to be open while you work. A permanent tunnel between servers runs as a systemd unit, not
ssh -ffrom cron: the unit restarts a dropped connection.# /etc/systemd/system/tunnel-db.service [Unit] Description=SSH tunnel to the database on db-internal After=network-online.target Wants=network-online.target [Service] User=tunnel ExecStart=/usr/bin/ssh -N -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes -L 3306:127.0.0.1:3306 db-internal Restart=always RestartSec=10 [Install] WantedBy=multi-user.targettunnelis a dedicated user, anddb-internalcomes from its~/.ssh/config. It has a single key, and on the other side its line inauthorized_keysstarts withrestrict,port-forwarding,permitopen="127.0.0.1:3306"(SSH keys): that key can’t open a shell.
Reverse tunnels and SOCKS
-R opens a port on the server. By default only on its 127.0.0.1 (GatewayPorts no in sshd): from the
server, curl http://127.0.0.1:9000 reaches your laptop, but the internet can’t. You can make the port
reachable from outside, but then your laptop answers the whole internet — do that only through a proxy with a
password.
-D 1080 starts a SOCKS proxy on your computer. Requests from the browser or from
curl --socks5-hostname 127.0.0.1:1080 leave from the server, so every internal address opens at once, for
example http://172.18.0.5:3000 on a Docker network. --socks5-hostname also hands name resolution to the
server — container names still won’t resolve, because that’s Docker’s DNS, not the server’s.
If it doesn’t work
bind [127.0.0.1]:8080: Address already in use, the tunnel didn’t open
- Cause
- Port 8080 on your computer is taken — often by another tunnel or a local dev server.
- Fix
- Use another local port:
-L 18080:127.0.0.1:8080, and openhttp://127.0.0.1:18080.
The page doesn’t open, and the ssh window shows channel 2: open failed: connect failed: Connection refused
- Cause
- The tunnel to the server is up, but from the server’s side nothing listens at that address: wrong port, the service is down, or it listens on IPv4 only while
localhoston the server became::1. - Fix
- On the server,
ss -tlnp | grep 8080shows which address and port the service listens on. Write the address as digits in the tunnel:127.0.0.1, notlocalhost.
channel 2: open failed: administratively prohibited: open failed
- Cause
- The server has
AllowTcpForwarding no. - Fix
- Put
AllowTcpForwarding yesback insshd_config.d(sshd_config) or allow tunnels only for your user withMatch User example-user.
A background tunnel stopped answering after an hour
- Cause
- The connection died, and the
sshprocess never found out. - Fix
ServerAliveInterval 30andExitOnForwardFailure yes; for a permanent tunnel, a systemd unit withRestart=always, orautossh.
A container with no published port; the tunnel to 127.0.0.1:8080 doesn’t reach it
- Cause
- The container’s port isn’t published on the host, so the server’s
127.0.0.1doesn’t lead to it. - Fix
- Publish it on localhost:
ports: - "127.0.0.1:8080:8080"(A host-only port goes on 127.0.0.1). Or point the tunnel at the container’s address on the Docker network — it changes when the container is recreated.
How to check
The tunnel listens only on your computer, not on the whole home network:
netstat -an | grep 8080
# TCP 127.0.0.1:8080 0.0.0.0:0 LISTENING
The panel answers through the tunnel:
curl -sI http://127.0.0.1:8080 | head -1
# HTTP/1.1 200 OK
And doesn’t answer from outside — from a phone on mobile data, or from a computer without the tunnel:
curl -m 5 -s http://203.0.113.10:8080 || echo "closed"
# closed