Reenvisioning SSH with ShellHub

21st Century SSH

Article from Issue 235/2020

Author(s): Chris Binnie

ShellHub offers an innovative approach to remote access with minimal reconfiguration of a firewall.

Secure Shell (SSH) is one of the most popular Linux services. With the global IPv4 address space shortage, it often becomes necessary to SSH into machines that are sitting behind a NAT-enabled router.

Rather than opening up network ports and then forwarding traffic individually to all your specific LAN devices, clearly it would be much better to access devices via a centralized point.

A new, natty piece of software called ShellHub [1] solves this headache nicely. ShellHub creates an SSH server inside your local network, allowing you to forward inbound SSH traffic to your other machines without having to mess around with the individual port forwarding settings for all your devices. Think of ShellHub as an alternative to the popular sshd daemon (OpenSSH) on your LAN.

In Closer

Figure 1 is a simple schematic showing the ShellHub architecture. From outside the LAN, you connect to the ShellHub server, either from the command line or a browser window. The firewall/router is configured to pass traffic to the predefined static IP address and port number of the ShellHub server on the LAN, performing network address translation as required.

Figure 1: A remote user just has to access the ShellHub server to obtain access to other devices on the LAN.

A user who is connected to the ShellHub server can then use the ShellHub web interface (or a command-line interface) to initiate connections with other devices on the LAN. The remote user can thus connect with all devices even though the ShellHub server itself is the only system requiring special firewall attention.

On Your Marks

The excellent ShellHub uses Docker Engine and Docker Compose, taking a microservices approach to make the software easier to develop and maintain. Consult your package manager's documentation for more on how to set up ShellHub for your Linux distro. I'm using Linux Mint atop Ubuntu 18.04.

The first step is to set up Docker:

$ apt install docker.io docker-compose

To make sure that Docker Engine starts when the machine reboots, run the following command:

$ systemctl enable docker

The next task is cloning ShellHub's GitHub repository [2] and selecting the correct branch (and therefore version):

$ git clone -b v0.0.4 https://github.com/shellhub-io/shellhub.git shellhub-v0.0.4

ShellHub development is proceeding quickly, but be aware that ShellHub is still in Beta. I was running version 0.0.2 just a couple of weeks ago and already it is at version 0.04, so make sure you get the latest and most stable version.

Go to the cloned directory next by using this command:

$ cd shellhub-v0.0.4

Before proceeding, fire up the excellent keygen tool, which is included in the repository's bin/ directory:

$ ./bin/keygen

and create an RSA key pair.

Docker Inside

The ShellHub service is built on Docker; you'll need a working Docker [3] configuration to set up ShellHub. You're advised to exercise some patience (anything up to 15 minutes apparently) when running Docker Compose to bring up ShellHub.

Try the following command:

$ docker-compose up -d

If this command doesn't immediately work, see the box entitled "Docker Hub Login." For more help with Docker Compose issues, see "There May Be Trouble Ahead."

There May Be Trouble Ahead

If you receive an error when Docker Compose tries to start up, you might need to get the Docker Compose version required by your ShellHub version. On the Docker website, the compatibility matrix [4] mentions that, for version 3.7 to be used in the Docker Compose file (v3.7 is the version that my ShellHub uses), you need the following:

Docker Compose (version in the docker-compose.yml file): version 3.7
Docker Engine: 18.06.0+

To check your Docker Engine version, you can run the following command:

$ docker version

And, for the Docker Compose version, use this command:

$ docker-compose version

As ShellHub is up-to-date, I took the following steps to update Docker Compose. First run the following command to remove the old version:

$ apt purge docker-compose

From the Docker Compose GitHub repository [5], download the source code for the latest version (version 1.25.4 at the time I wrote this article):

$ curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/bin/docker-compose

The eagle-eyed among you will see from the long, somewhat unwieldy command that the resulting Docker Compose release is saved within the directory /usr/bin on my local machine (adjust this location to your needs). Once it's been downloaded, you can make the file executable with:

$ chmod +x /usr/bin/docker-compose

Now, from inside the shellhub-v0.0.4 directory in the cloned GitHub repository file path, run the following command to bring Docker Compose up again (you might have to run the docker login command first) :

$ docker-compose up -d

Ta-da! The screeds of output as our ShellHub server is brought up confirm that Docker Compose is happy.

Docker Hub Login

If you haven't logged into Docker Hub for a while, you may have missed a slight change in policy over the last few months.

Docker now places more emphasis on regular logins (even for public images). As a result, you may need to login again. Reset your password online if required, and then run the login command: