Other languages:

What is SSH tunneling?

SSH tunnelling is a method to use a gateway computer to connect two computers that cannot connect directly.

In the context of Compute Canada, SSH tunneling is necessary in certain cases, because compute nodes on Niagara and Graham do not have direct access to the internet, nor can the compute nodes be contacted directly from the internet.

The following use cases require SSH tunnels:

Running commercial software on a compute node that needs to contact a license server over the internet;
Running visualization software on a compute node that needs to be contacted by client software on a user's local computer;
Running a Jupyter Notebook on a compute node that needs to be contacted by the web browser on a user's local computer.
Connecting to the Cedar database server from somewhere other than the Cedar head node, e.g., your desktop

In the first case, the license server is outside of the compute cluster and is rarely under a user's control, whereas in the other cases, the server is on the compute node but the challenge is to connect to it from the outside. We will therefore consider these two situations.

Contacting a license server from a compute node

What's a port?

A port is a number used to distinguish streams of communication from one another. You can think of it as loosely analogous to a radio frequency or a channel. Many port numbers are reserved, by rule or by convention, for certain types of traffic. See List of TCP and UDP port numbers for more.

Certain commercially-licensed programs must connect to a license server machine somewhere on the internet via a predetermined port. If the compute node where the program is running has no access to the internet, then a gateway server which does have access must be used to forward communications on that port, from the compute node to the license server. To enable this, one must set up an SSH tunnel. Such an arrangement is also called port forwarding.

In most cases, creating an SSH tunnel in a batch job requires only two or three commands in your job script. You will need the following information:

The IP address or the name of the license server (here LICSERVER).
The port number of the license service (here LICPORT).

You should obtain this information from whoever maintains the license server. That server also must allow connections from the login nodes; for Niagara, the outgoing IP address will either be 142.150.188.131 or 142.150.188.132.

With this information, one can now setup the SSH tunnel. For Graham, an alternative resolution is to request a firewall exception for license server LICSERVER and its specific port LICPORT.

The gateway server on Niagara is nia-gw. On Graham, you need to pick one of the login nodes (gra-login1, 2, ...). Let us call the gateway node GATEWAY. You also need to choose the port number on the compute node to use (here COMPUTEPORT).

The SSH command to issue in the job script is then:

ssh GATEWAY -L COMPUTEPORT:LICSERVER:LICPORT -n -N -f

In this command, the string following the -L parameter specifies the port forwarding information.

-n prevents SSH from reading input (it couldn't in a compute job anyway)
-N tells SSH not to open a shell on the GATEWAY
-f tells SSH to run in the background, allowing the job script to proceed past this SSH command.

A further command to add to the job script should tell the software that the license server is on port COMPUTEPORT on the server 'localhost'. Here, 'localhost' is not a placeholder, rather, it is the literal name to use - 'localhost' is a standard hostname pseudonym by which a computer can refer to itself. Exactly how to inform your software to use this port on 'localhost' will depend on the specific application and the type of license server, but often it is simply a matter of setting an environment variable in the job script like

export MLM_LICENSE_FILE=COMPUTEPORT@localhost

Example job script

The following job script sets up an SSH tunnel to contact licenseserver.institution.ca at port 9999:

#!/bin/bash
#SBATCH --nodes 1
#SBATCH --ntasks 40
#SBATCH --time 3:00:00

ssh nia-gw -L 9999:licenseserver.institution.ca:9999 -N -f
export MLM_LICENSE_FILE=9999@localhost

module load thesoftware/2.0
mpirun thesoftware .....

Contacting a visualization, Jupyterhub, database or other server running on a compute node

SSH tunnelling can also be used in the context of Compute Canada to allow a user's computer to connect to a compute node on a cluster through an encrypted tunnel that is routed via the login node of this cluster. This technique allows graphical output of applications like a Jupyter Notebook or visualization software to be displayed transparently on the user's local workstation even while they are running on a cluster's compute node. When connecting to a database server where the connection is possible though the head node only, SSH tunneling can be used to move an arbitrary port number of a compute network to a cluster's head node and bind it to the database server.

Example for a job

# License
export LM_PROJECT=
export CDLMD_LICENSE_FILE=1999@localhost

# Start the SSH tunnel
ssh -n -N -L 1999:flex.cd-adapco.com:1999 gra-login1 &
SSH1=$!
ssh -n -N -L 2099:flex.cd-adapco.com:2099 gra-login1 &
SSH2=$!

# Launch the code
<whatever>

# Stop the SSH tunnel
kill -9 $SSH1
kill -9 $SSH2

There is NAT on both Graham and Cedar allowing users to access the internet from the compute nodes. On Graham however, access is blocked by default at the firewall. A user (or an analyst) would need to submit a request to have a specific port/IP open.

From Linux or MacOS X

On a Linux or MacOS X system, we recommend using the sshuttle Python package.

On your computer, open a new terminal window and run the following sshuttle command to create the tunnel.

[name@my_computer $] sshuttle --dns -Nr userid@machine_name

Then, copy and paste the provided URL into your browser. In the above example, this would be

 http://cdr544.int.cedar.computecanada.ca:8888/?token=7ed7059fad64446f837567e32af8d20efa72e72476eb72ca

From Windows

An SSH tunnel can be created from Windows using MobaXTerm as follows.

Open two sessions in MobaXTerm.

Session 1 should be a connection to a cluster. Follow the instructions in section Starting Jupyter Notebook.

Session 2 should be a local terminal in which we will set up the SSH tunnel. Run the following command, substituting the node name from the URL you received in Session 1. Follow the instructions in section Starting Jupyter Notebook.

[name@my_computer ]$  ssh -L 8888:cdr544.int.cedar.computecanada.ca:8888 someuser@cedar.computecanada.ca

This command performs local port forwarding (-L). It forwards local port 8888 to cdr544.int.cedar.computecanada.ca:8888, which is the host name given when Jupyter Notebook was started.

Open your browser and go to

 http://localhost:8888/?token=7ed7059fad64446f837567e32af8d20efa72e72476eb72ca

Replace the token in this example with the one given to you in Session 1. You can also type http://localhost:8888 and there will be a prompt asking you for the token, which you can then copy and paste.

Example for connecting to a database server on Cedar from your desktop

Commands to connect to PostgreSQL and MySQL respectively are:

 
ssh -2 -L 127.0.0.1:PORT:cedar-pgsql-vm.int.cedar.computecanada.ca:5432 someuser@cedar.computecanada.ca
ssh -2 -L 127.0.0.1:PORT:cedar-mysql-vm.int.cedar.computecanada.ca:3306 someuser@cedar.computecanada.ca

These commands move your localhost:PORT to cedar.computecanada.ca:PORT and bind it with cedar-pgsql-vm.int.cedar.computecanada.ca:5432. "someuser" in this example is your username on computecanada. By running one of these commands you will be connected to Cedar (like any other SSH connection). The only difference between this connection and an ordinary SSH connection is that you can now use another terminal to connect to the database server directly from your desktop. Here are the commands for PostgreSQL and MySQL connections:

 
psql -h 127.0.0.1 -P PORT -U <your username> -W
mysql -h 127.0.0.1 -P PORT -u <your username> -p

The connection requires a password for both MySQL and PostgreSQL. However, for PostgreSQL the password is your Compute Canada password and for MySQL the password is stored in your ".my.cnf" located in your home directory on Cedar. The connections will remain open as long as you have the SSH connection. In this example "PORT" is an arbitrary number and it should be opened in the firewall of Cedar's head node. Before running this command, please contact Technical support and we will assign a port number to you.