basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    ManualLinuxSSH

    SSH tunnels: a closed admin panel through localhost

    A panel, a database or a dashboard listens only on the server’s 127.0.0.1 and isn’t published. ssh -L opens it on your computer as http://127.0.0.1:8080 — over the SSH port that’s already open, with no exposed panel login and no new firewall rules.

    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

    1. 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:8080 means only the server itself sees the port. 0.0.0.0:8080 or *:8080 means 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).

    2. Open the tunnel

      ssh -N -L 8080:127.0.0.1:8080 web1

      The 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:8080 in the browser. Close it with Ctrl+C.

    3. 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 none

      Now ssh web1-admin opens both ports at once. ExitOnForwardFailure yes: if a local port is taken, ssh exits with an error instead of hanging around without a tunnel. SessionType none is the same as -N, available since OpenSSH 8.7.

    4. 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 -f from 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.target

      tunnel is a dedicated user, and db-internal comes from its ~/.ssh/config. It has a single key, and on the other side its line in authorized_keys starts with restrict,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 open http://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 localhost on the server became ::1.
    Fix
    On the server, ss -tlnp | grep 8080 shows which address and port the service listens on. Write the address as digits in the tunnel: 127.0.0.1, not localhost.

    channel 2: open failed: administratively prohibited: open failed

    Cause
    The server has AllowTcpForwarding no.
    Fix
    Put AllowTcpForwarding yes back in sshd_config.d (sshd_config) or allow tunnels only for your user with Match User example-user.

    A background tunnel stopped answering after an hour

    Cause
    The connection died, and the ssh process never found out.
    Fix
    ServerAliveInterval 30 and ExitOnForwardFailure yes; for a permanent tunnel, a systemd unit with Restart=always, or autossh.

    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.1 doesn’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