SSH port forwarding: local, remote and dynamic tunnels

11 November 2026 · Daniel Bilsborough · Reviewed 11 November 2026

SSH port forwarding sends a TCP connection through an encrypted SSH connection. Three kinds:

The examples below use OpenSSH, and the option syntax was checked with ssh -G.

Local port forwarding (-L)

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.

Remote port forwarding (-R)

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.

Dynamic port forwarding (-D): a SOCKS proxy

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.

Tunnels without a shell, in the background

OptionWhat it does
-NRun no remote command; the connection only carries the forwards
-fGo to the background after logging in
-o ExitOnForwardFailure=yesExit if a forward can't be set up, instead of connecting without it
-o ServerAliveInterval=30Notice 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.

Port forwarding in ~/.ssh/config

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.

Server settings that control forwarding

These go in /etc/ssh/sshd_config on the server; restart the SSH service after changing them.

Common errors

MessageMeaning
bind [127.0.0.1]:8080: Address already in useSomething on your machine already uses that local port. Pick another, or find it with lsof.
channel 3: open failed: connect failed: Connection refusedThe 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 9000The server couldn't listen on that port: it's in use, or forwarding is disabled in sshd_config.
administratively prohibitedThe server's AllowTcpForwarding or PermitOpen settings refuse it.

Port forwarding and Shell Drop

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.

Questions

What is SSH 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.

What is the difference between ssh -L and ssh -R?

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

How do I keep an SSH tunnel open without a shell?

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.

Why does my remote forward only listen on localhost?

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.

Does Shell Drop support port forwarding?

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.

Get Shell Drop on the App Store QR code for Shell Drop on the App Store Reading on a computer? Scan the code with your iPhone camera.