So far in this series of posts on
ssh on macOS:
- Quick Introduction to SSH for Mac Admins
- SSH Keys, Part 1: Host Verification
- SSH Keys, Part 2: Client Verification
- Transferring files with SSH
- SSH Tunnels (this post)
Please consider supporting Scripting OS X by buying one of my books!
We have learned so far that
ssh is a really useful and flexible protocol. It can be used to connect securely to a remote shell, or to transfer files securely.
Rather than providing the shell itself,
ssh provides a secure way to transmit data to and from the remote shell. In a similar way,
ssh can be used to provide access to other remote services as well.
SSH Tunnels with Two Computers
Access to important services are usually blocked behind a firewall or router. Since
ssh, when setup correctly, is quite secure, you can usually get access to a server with
ssh even when other protocols are blocked. (Though some administrators move
ssh access to a different port than the default 22.)
You can use
ssh port forwarding or ‘tunneling’ to gain access to other services through
Imagine you want to use Screen Sharing to connect to a remote Mac (
remote.example.com). Screen Sharing on macOS uses the VNC port
5900 to connect to a remote Mac. Since VNC itself is inherently insecure, (mac Screen Sharing adds a few things to make it more secure) this port is blocked by many firewalls.
However, I do have
ssh access to
remote.example.com. So, how do I tell both systems to ‘tunnel’ the screen sharing traffic through
(When you test this, remember to enable either ‘Screen Sharing’ or ‘Remote Management’ (i.e Apple Remote Desktop) access in the ‘Sharing’ pane in System Preferences on the remote Mac.)
The tunnel starts on my local machine and ends on
remote.example.com at port 5900 (where the screen sharing service is listening on the remote Mac.)
The starting point also needs a port number, and I can basically choose freely. Port numbers under 1000 and over 49000 are reserved for the system and require root privileges. There are also many numbers that are commonly used by certain services (such as 5900 for VNC/Screen Sharing) and may already be in use. I will choose 5901 for the local port.
To connect the local port 5901 to port 5900 on the remote Mac use the following command:
$ ssh -N -L localhost:5901:localhost:5900 remote.example.com
(You can just try this with a second Mac or virtual machine in your network, even without a firewall.)
The syntax of this command is less than obvious. Let’s break it into pieces:
-N option tells
ssh that we do not want to invoke a remote shell or run a remote command.
-L option creates a local port forwarding setup. This option takes a parameter with three or four parts, separated by colons
:. The first pair (
localhost:5901) are the tunnel start point. The second pair (
localhost:5900) are the remote end point of the tunnel.
localhost is resolved on the remote host, so this means port
5900 on the remote host.
The last parameter states the remote host, to connect to,
This commands tell
ssh to connect to
remote.example.com and establish a tunnel that transfers traffic from port 5901 on my computer to port 5900 on the remote computer.
Since the origin of my tunnel is usually on my local computer, the first
localhost can be omitted, so you only see the origin port.
$ ssh -N -L 5901:localhost:5900 remote.example.com
When you execute the command nothing will happen. You will not even get a new prompt, because the
ssh process is running until you cancel it with ctrl-C. Don’t cancel it yet, however, since it needs to run to provide the tunnel.
So, when you open the Screen Sharing application (from
/System/Library/CoreServices/Applications/) and connect to
localhost:5901 all traffic will be forwarded by
sshto port 5900 on the remote Mac.
You can also use the
open command to connect with Screen Sharing:
$ open vnc://localhost:5901
You should be able connect with Screen Sharing, even when port 5900 is blocked by a Firewall.
When you are done with the Screen Sharing session, you can end the
ssh tunnel process in Terminal with ctrl-C.
You can also use
ssh port to use the remote host as a gateway or ‘jump host’ to a third computer. Imagine you want to use Screen Sharing to connect to
secundus.example.com behind a firewall and you only have
ssh connection to
primus.example.com available. You can tell
primus to point the endpoint of an
ssh tunnel at
$ ssh -N -L 5902:secundus.example.com:5900 primus.example.com
secundus.example.com or whatever host or IP address you enter there will be resolved on the remote host. So you can use NAT IP addresses or
.local host names here, even if they do not make sense in the network your work Mac is in. (They do have to make sense on the remote host, though, otherwise you will get an error.)
In the following examples the local IP address
192.168.1.200 or the Bonjour hostname
Secundus.local will be resolved on the remote host, even if they don’t work on my local computer:
$ ssh -N -L 5902:192.168.1.200:5900 primus.example.com $ ssh -N -L 5902:Secundus.local:5900 primus.example.com
Either way, you can then point Screen Sharing at
localhost:5902 and it will connect through
primus to Screen Sharing on
Keep in mind, that while the connection from the start point (on your Mac) to the host
primus is secured by
ssh the connection from
secundus is not.
Stumbling over HTTP hosts
In general you can use
ssh port forwarding (or tunnels) for any service. Some services however, may introduce extra pitfalls.
For example, I wanted to use
ssh port forwarding to gain access to my home router’s web interface. I can use ‘Back to My Mac’ to
ssh into one of the iMacs at home, and thought it should be easy to connect to the router with an
$ ssh -N -L 8080:192.168.1.1:80 mac.example.com
This seemed to work, but whenever I tried to point a browser to
localhost:8080 it couldn’t connect to the web page. The problem here is not the
ssh tunnel but the the web server on the router. As part of the
http request, the browser sends the name of the domain requested to the web server. This allows web servers to host different pages for different domains. With this request, the browser told the router it wanted the web page for
localhost and the router replied with “I don’t serve pages for that host”… (Your router might behave differently.)
curl I could convince the router to serve me the page with:
curl -H "Host: 192.168.1.1" http://localhost:8080
However, since navigating the web interface of the router with
curl is out of the question I had to find a different solution.
Tunnel All the Things!
What if I could send all traffic through the iMac at home?
With the command
$ ssh -N -D 9001 remote.example.com
I can create a tunnel from my computer (on port 9001) to the remote Mac that acts as a SOCKS proxy. Then I can set the Socks proxy to
localhost:9001 in the proxy tab in the Network pane in System Preferences. You probably want to create a new network location for this setup. Then all network traffic will be securely routed through the
ssh tunnel to my Mac at home where it can connect to the router.
This can also serve as a temporary VPN solution.
However it is somewhat painful to set up and maintain, so if you start using this more frequently, you probably need to look into a proper VPN service solution (some routers, ironically, provide one…).
- you can bypass firewalls and other network blocks by tunnel traffic for any service through a
- the command describes which local port to connect to which port on the remote host
- you can even tell the remote host to connect the end point to a third computer, behind the firewall
- you can also create a SOCKS proxy with
sshto tunnel all traffic
Previous Post: Transferring Files with