SSH port forwarding sends a TCP connection through an encrypted SSH connection. Three kinds:
-L: a port on your machine reaches something on the server's side. ssh -L 8080:localhost:80 user@host, then open http://localhost:8080.-R: a port on the server reaches something on your side. ssh -R 9000:localhost:3000 user@host.-D: a SOCKS proxy on your machine that sends traffic out through the server. ssh -D 1080 user@host.The examples below use OpenSSH, and the option syntax was checked with ssh -G.
The form is -L [bind_address:]port:host:hostport. SSH listens on port on your machine, and each connection to it is carried to the server, which then connects to host:hostport. The host is looked up from the server, so localhost there means the server itself.
Reach a database that only listens on the server's loopback:
ssh -L 5432:localhost:5432 user@db-server
psql -h localhost -p 5432 mydb
Reach a machine that only the server can see, such as an admin page on a private network:
ssh -L 8443:10.0.0.5:443 user@bastion
Then https://localhost:8443 on your machine is 10.0.0.5:443 as the bastion sees it.
By default the local port only listens on your own loopback address, so other machines on your network can't use it. -L 0.0.0.0:8080:localhost:80 listens on every interface, which shares the tunnel with your whole network; use it deliberately. Ports below 1024 need root on your machine, so pick a higher local port.
The mirror image: -R [bind_address:]port:host:hostport. The server listens on port, and connections to it come back through SSH to your machine, which connects to host:hostport.
Show a server a development app running on your laptop:
ssh -R 9000:localhost:3000 user@server
On the server, curl http://localhost:9000 now reaches port 3000 on your laptop. By default the server binds that port to its own loopback only; see server settings to change it.
ssh -D 1080 user@server
This runs a SOCKS proxy on port 1080 of your machine. Any program pointed at it sends its connections out through the server, to any destination, as if it were running there. Point a browser's SOCKS5 proxy setting at localhost:1080, or test with curl:
curl --socks5-hostname localhost:1080 https://example.com
--socks5-hostname makes DNS lookups happen on the server too, so internal names resolve.
| Option | What it does |
|---|---|
-N | Run no remote command; the connection only carries the forwards |
-f | Go to the background after logging in |
-o ExitOnForwardFailure=yes | Exit if a forward can't be set up, instead of connecting without it |
-o ServerAliveInterval=30 | Notice a dead connection instead of hanging |
ssh -fN -o ExitOnForwardFailure=yes -L 5432:localhost:5432 user@db-server
To stop a background tunnel, end that ssh process. To see what's listening on a port: lsof -iTCP:5432 -sTCP:LISTEN on macOS, ss -tlnp on Linux.
Forwards you use often belong in the ssh config file. Note the space, not a colon, between the listening port and the destination:
Host db-tunnel
HostName db-server.example.com
User deploy
LocalForward 5432 localhost:5432
RemoteForward 9000 localhost:3000
DynamicForward 1080
ExitOnForwardFailure yes
ssh -N db-tunnel then opens all three.
These go in /etc/ssh/sshd_config on the server; restart the SSH service after changing them.
AllowTcpForwarding: yes by default. no turns off -L, -R and -D; local or remote allows only one direction.GatewayPorts: no by default, so remote forwards listen on the server's loopback only. yes listens on all interfaces; clientspecified lets the client choose with -R 0.0.0.0:9000:localhost:3000.PermitOpen and PermitListen: restrict which destinations and listening ports forwards may use.| Message | Meaning |
|---|---|
bind [127.0.0.1]:8080: Address already in use | Something on your machine already uses that local port. Pick another, or find it with lsof. |
channel 3: open failed: connect failed: Connection refused | The tunnel works, but nothing is listening at the destination as the server sees it. Check the host and port after the first colon. |
Warning: remote port forwarding failed for listen port 9000 | The server couldn't listen on that port: it's in use, or forwarding is disabled in sshd_config. |
administratively prohibited | The server's AllowTcpForwarding or PermitOpen settings refuse it. |
Shell Drop, the SSH client for iPhone, iPad and iPhone Duo, doesn't do port forwarding; there is no setting for it. From a phone, a private network such as Tailscale on both the phone and the server is often the simpler route to a web app or dashboard on that server: the phone reaches the server's private address directly, as long as the service listens on that interface. The best SSH client for iPhone and iPad roundup notes which iOS apps include port forwarding.
It carries a TCP connection through an SSH connection. Local forwarding (-L) makes a port on your machine reach something on the server's side, remote forwarding (-R) does the reverse, and dynamic forwarding (-D) runs a SOCKS proxy through the server.
-L opens a port on your machine and connects out from the server. -R opens a port on the server and connects back out from your machine. Use -L to reach a service behind the server; use -R to let the server reach a service on your side.
Add -N so SSH runs no remote command, and -f to send it to the background: ssh -fN -L 8080:localhost:80 user@host. Add -o ExitOnForwardFailure=yes so it exits if the forward can't be set up.
By default the SSH server binds remote forwards to its loopback address. To make one reachable from other machines, set GatewayPorts yes or clientspecified in the server's sshd_config and restart the SSH service.
No. Shell Drop has no port forwarding setting. On a phone, a private network such as Tailscale is often the simpler way to reach a service on the server directly.