Skip to main content
Download

How to set up an SSH tunnel on a Mac

By Lucas Russo, developer of SSHive · Updated

Local, remote and SOCKS5 SSH tunnels on macOS, on the command line and in SSHive's profile editor, where they come back every time you connect.

Estimated time: 5 minutes

An SSH tunnel carries a network port inside an encrypted SSH connection, and there are three kinds. Local (-L) brings a port of the remote network to your Mac: a database, an admin page, anything only the server can reach. Remote (-R) does the opposite and opens a port on the server that leads back to your Mac. Dynamic (-D) turns the connection into a SOCKS5 proxy for your browser, which has its own SOCKS5 guide. With OpenSSH, built into macOS, each is one line: ssh -L 5433:db.internal:5432 user@bastion or ssh -R 8080:localhost:3000 user@server. The steps below build the same tunnels in SSHive, attached to a profile. The free version includes 1 local tunnel; remote tunnels and SOCKS5 need Pro, which allows up to 10 local tunnels, 5 remote ones and 1 SOCKS port per profile on the Mac.

Step-by-step

  1. Open a profile and expand "Advanced options"

    Sidebar › + (new connection), or right-click an existing profile › Edit. Fill in host, port, username and authentication as usual, then click Advanced options at the bottom of the dialog. Among the blocks it unfolds are the three kinds of tunnel: Local Tunnels (-L), Remote Tunnels (-R) and SOCKS5 Proxy (-D).

  2. Add a local tunnel (-L), the most common case

    Under Local Tunnels (-L) click + Add. Three fields appear on one line: local port (5433, say; anything from 1024 up avoids sudo), remote host (db.internal, as the SSH server sees it; localhost if the service runs on the server itself) and remote port (5432). Save. The tunnel comes up every time you connect with this profile, bound to 127.0.0.1 only: there is no bind-address field, so nothing else on your network can use it. The free version allows 1 local tunnel; Pro allows 10 per profile.

  3. Add a remote tunnel (-R), Pro

    Under Remote Tunnels (-R) click + Add. Fields: remote port (the one that opens on the SSH server, 8080), local host (localhost) and local port (3000). On the server, curl localhost:8080 now reaches port 3000 on your Mac. In the free version the block is dimmed, and a click on its PRO badge opens the upgrade window. Pro allows 5 remote tunnels per profile.

  4. Read the ⇄ indicator in the status bar

    Once connected, the status bar shows ⇄ N, where N is the number of active tunnels (local, remote and SOCKS together). Click it to open the Tunnel Status panel: each tunnel is listed with its type, local port, target and live state, plus a button to close it. If a tunnel cannot bind (port already in use), the SSH session stays connected and the failure is logged; N simply does not count that one.

  5. Auto-reconnect: tunnels come back with the session

    When the SSH session drops (a Wi-Fi change, sleep and wake, a server restart), every tunnel closes with it, since they live inside the connection. SSHive's auto-reconnect then brings the session back and reopens each tunnel of the profile in turn, with nothing for you to do. If one tunnel keeps failing on reconnect, check the remote sshd: AllowTcpForwarding yes for local and remote tunnels, plus GatewayPorts yes if a remote tunnel must be reachable from outside the server.

Frequently asked questions

Does the tunnel die when my SSH session ends?+
Yes, tunnels live with the SSH connection. When the connection drops unexpectedly, SSHive reconnects on its own and reopens the profile's tunnels with it. For long-running tunnels, set ServerAliveInterval 60 in OpenSSH, or rely on SSHive's built-in keepalive (every 30 s by default).
Can I tunnel through a chain of jump hosts?+
Yes. On the command line, ssh -J bastion1,bastion2 -L 5432:db:5432 user@target goes through both bastions. In SSHive, add both bastions, in order, to the Jump Chain of the target profile, as the jump host guide shows; the tunnels defined on that profile then run through the whole chain. Jump chains are Pro.

Related SSHive features

SSH Tunnels

Local, remote & SOCKS5 proxy

SSH Terminal

GPU-accelerated terminal

See also

Try SSHive Free for macOS

Get the all-in-one SSH, SFTP, RDP and VNC client for Mac. Free download, no signup required.

Download SSHive Free