SSH Port Forwarding Guide for Mac Users

SSH port forwarding (or SSH tunneling) is a method of transporting arbitrary networking data over an encrypted SSH connection. It allows you to access remote services that are blocked by firewalls, or expose local services to a remote network without public IPs.

On macOS, you can configure three types of tunnels: Local, Remote, and Dynamic.

1. Local Port Forwarding (-L)

Local port forwarding is used to redirect traffic from your local Mac to a remote server. This is commonly used to connect to database servers (like MySQL, PostgreSQL, or Redis) that only bind to localhost on the remote server for security.

The CLI command:

ssh -L 5432:127.0.0.1:5432 user@database-server

This tells your Mac: listen on local port 5432 and forward all traffic sent there to 127.0.0.1:5432 from the database server’s perspective. You can then connect your database client (like TablePlus) to 127.0.0.1:5432 on your Mac.

2. Remote Port Forwarding (-R)

Remote port forwarding redirects traffic from the remote server back to your local Mac. This is useful when you want to show a web server running locally on your Mac to someone outside, or give a remote server access to a local resource.

The CLI command:

ssh -R 8080:127.0.0.1:80 user@remote-server

This tells the remote server: listen on remote port 8080 and forward all incoming connections back to port 80 on my Mac.

[!WARNING] By default, sshd on the remote server only binds remote ports to 127.0.0.1. If you want the port to be open to the public internet, you must set GatewayPorts yes in /etc/ssh/sshd_config on the server.

3. Dynamic Port Forwarding (-D SOCKS5)

Dynamic port forwarding turns your SSH connection into a SOCKS5 proxy server. Instead of forwarding a single port to a single destination, it dynamically routes all traffic from a client (like a web browser) through the SSH server to the entire remote network.

The CLI command:

ssh -D 1080 user@secure-gateway

This spawns a local SOCKS5 proxy on port 1080. You can configure macOS System Settings ▸ Network ▸ Proxies to use SOCKS Proxy: 127.0.0.1:1080 to secure all your browser traffic over the remote gateway.

Managing Tunnels on macOS (Sandbox limits)

If you are running a sandboxed Mac App Store client like Upshell, there is one critical limitation: you cannot bind to privileged ports below 1024. This is a macOS security policy, not a limitation of the app. Tunnels must listen on ports 1024 or higher (e.g., 8080 instead of 80, 5432 instead of 543 for databases).

Upshell Pro provides a visual Port Forwarding rules editor in the host settings. When you connect to the host:

• The app automatically launches the local listener.
• It maps the connections using an asynchronous, non-blocking SwiftNIO pipeline.
• It displays the status and traffic throughput inside the rules status panel at the bottom of the session window.

Step by step in Upshell

1. Open the Host Editor — double-click or edit the host registry entry in Upshell.
2. Add a Port Forwarding Rule — choose between Local, Remote, or Dynamic (SOCKS5).
3. Configure Ports — set the local listener port (above 1024) and the destination parameters.
4. Connect to the Server — connect as usual. The rules status panel will light up showing active listeners.
5. Route traffic — point your local clients (database manager, web browser) to the configured ports.