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 ssh
.
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 ssh
?
(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:
The -N
option tells ssh
that we do not want to invoke a remote shell or run a remote command.
The -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.
The second 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, remote.example.com
.
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 ssh
to 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.
SSH triangle
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 secundus
with:
$ ssh -N -L 5902:secundus.example.com:5900 primus.example.com
Note: 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 secundus
.
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 primus
to 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
tunnel:
$ 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.)
With 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…).
Summary
- you can bypass firewalls and other network blocks by tunnel traffic for any service through a
ssh
tunnel - 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
ssh
to tunnel all traffic
Previous Post: Transferring Files with ssh
But for me using sshuttle was significantly slower than a simple ssh tunnel. If you run into this problem, try to run sshuttle with the option `–no-latency-control`.