Connection from Offsite

Remote Connection to Department Machines

CSSE offers access to linux.cosc.canterbury.ac.nz and some other resources from off campus over SSH (Secure SHell) via 2FA (Two Factor Authentication) or indirectly with the central IT Services MFA (Multi Factor Authentication) gateway.

Getting Setup

In order to connect to linux.cosc.canterbury.ac.nz or some other CSSE resource from off campus you need to have an SSH client installed on your computer. Computers running Linux or MacOS offer SSH capability by default, but Windows may not. It is easy enough to install it on Windows though, just follow these instructions to do it from the GUI or do the following from a PowerShell window as Administrator:

You should get this output, indicating it went well:

For students running Microsoft Windows, the University of Canterbury can provide the Education version of MobaXterm as an alternative to using SSH on the command prompt. You can download MobaXterm Education Edition from here, and you must login with your University credentials in order to download the installer file. Documentation for MobaXterm is available here.

If you would like to connect via your phone or tablet, JuiceSSH and ConnectBot are suggested for Android while you could consider Termius for iPhones/iPads.

Besides Having a Password

Off campus access to linux.cosc.canterbury.ac.nz is protected not only with your password but also a second factor. This combines something you know with something you have.

You may connect indirectly using central IT Services own SSH gateway (ssh.canterbury.ac.nz) and their MFA, and you may already be registered with this service. If you're not and you want to connect using this method from off campus, please follow the instructions here.

For a more direct connection to linux.cosc.canterbury.ac.nz you'll need to use 2FA with Google Authenticator. Despite the name you don't have to use Google at all. To get setup using this method please follow the instructions here.

First Time Connection

Once you have SSH on your computer and are setup using 2FA or MFA (or both!), you're now ready to make a test connection from a Terminal or Command Prompt. Substituting the psuedo usercode abc123 for your own, the following will get you logged into linux.cosc.canterbury.ac.nz with a shell prompt, using ssh.canterbury.ac.nz as a jump host/gateway. When you're asked if you want to continue the connection, answer 'yes'. Finally, be aware that when you enter your password it is normal not to see any characters appear as you type.

Make sure you have your phone handy when you do this with ssh.canterbury.ac.nz because there is no notification on the command line to remind you.

When connecting directly to linux.cosc.canterbury.ac.nz a jump host is unnecessary and connecting looks simpler:

Assuming your connection was successful we can move onto doing fancy things...

SSH Tunnels

The examples above are simple enough to get you a shell on a linux.cosc.canterbury.ac.nz node. With this foundation we can now leverage the power of SSH and create tunnels to access other resources such as databases, transferring of files and graphical desktop environments. If you're unfamiliar with the concept of tunnels one way to think of them is like a worm hole, or portal to another universe - you connect to the portal/wormhole at one end and pop out the other end somewhere else.

Let's play...

Connecting to a database

In our first example we will connect to a database server not normally available from off campus.

This creates a tunnel via linux.cosc.canterbury.ac.nz to a database server called db2.csse.canterbury.ac.nz on the official MySQL port 3306. If you wanted you could always use ssh.canterbury.ac.nz in place of linux.cosc.canterbury.ac.nz. This example also creates local port 1234 on your computer which we can use to access the database server or to use our analogy, the entry to the portal/wormhole. The local port doesn't have to be 1234 and can be some other number that isn't already used on your computer. Port 1234 on your local computer merely maps across to port 3306 on the database server. You could, for example use local port 8888. You can even have multiple tunnels at the same time, to the same, or different computers. You just run the ssh command again changing the hostname of the computer you want to connect to and use a different local port number as appropriate.

After executing this command and completing the authentication process you might think the connection has hung because you don't get a command prompt. The tunnel is indeed open but this effect is a result of the -N parameter. The tunnel will remain open until you type Control-C on the keyboard.

With the tunnel established we can now connect to the database server using the mysql client as an example:

DBUSER is the user to use to connect to the database server with, and DBNAME is the name of the database. You can use any database client you like so long as you use localhost as the server name with port 1234.

SSHing to linux.cosc.canterbury.ac.nz with a tunnel

We can modify our ssh command to not only get a terminal to the remote computer, but use a tunnel where files from your department home directory can be transferred. Let's set that up with ssh.canterbury.ac.nz and then the same thing using linux.cosc.canterbury.ac.nz:

Now achieving the same thing directly with linux.cosc.canterbury.ac.nz...

Either of these techniques will result in you getting a command prompt on a linux.cosc.canterbury.ac.nz node and will allocate the local port 1234 on your computer as the entry point to this tunnel. This means we can connect to it for other purposes such as transferring files or a graphical connection with X2Go.

If you need to connect to another computer using Remote Desktop Protocol (RDP) for example, it can be done like this:

This will create a tunnel via ssh.canterbury.ac.nz to ucremote.canterbury.ac.nz on the standard RDP port 3389 and will keep the connection until you press Control-C. Once this tunnel is made you can connect to localhost on port 8888 in order to connect to ucremote.

The linux.cosc.canterbury.ac.nz version looks very similar:

Preventing SSH connection dropouts

If you leave your SSH connection open and don't use it for a period of time, the server may eventally drop the connection due to inactivity. You can configure your computer to keep the connection alive by adding the following to the .ssh/config file on your computer:

This will cause your SSH client to send a null packet to the server every 5 minutes to keep the connection up and if after 2 attempts it fails it will give up, at which point the connection may have died some other way already.

Graphical Connections

Remote Desktop Protocol (RDP) is no longer a supported method of graphically connecting. Alternatively please use one of the two methods outlined below.

X2Go

While a little more initial setup is usually required with X2Go, it is worth using this over the older Remote Desktop method. Instructions for setting up X2Go are on a separate page.

Running Applications Remotely - X11 Forwarding

There might be circumstances where you want to run an application on linux.cosc.canterbury.ac.nz but have the output of that application appear on your computer. This process is known as X11 forwarding.

Linux

With Linux this is easy to do because the software is already there. From a terminal window use the same ssh command as described above for Basic SSH Access, but add in the -Y parameter like this:

This will connect to the remote server the same as before, but this time you'll be able to run applications. e.g

The xeyes application will run on the remote computer but you'll see the graphical output on your desktop. You'll also get back control of the terminal - the effect of the & at the end. If you find your connection is slow, change the -Y to -YC which will turn on compression.

MacOS

To use X11 forwarding on a Mac you first need to install XQuartz. Once installed, keep it running at the same time as you run the ssh -Y ... command above.

Windows

For Windows users, MobaXTerm includes a built-in XServer and will by default automatically forward X11 applications to your client.

Remote Access to Files

You can access and edit files that are in your CSSE home directory over a command line SSH connection as described above in Getting Started and use text editors such as nano and vi for editing. But you can also access and edit files by remotely mounting your CSSE home directory on your computer. Depending on how good your internet connection is this technique may only be good for working with smaller files.

Linux and MacOS

The method for Linux and a Mac is the same, but on a Mac you first need to install FUSE and SSHFS, or if you have Homebrew installed this will get it too:

On Linux make sure the package sshfs is installed.

By using SSH examples previously covered, we can create a tunnel to linux.cosc.canterbury.ac.nz, have a terminal session on that computer, and mount our CSSE home directory making it locally available.

Or instead with linux.cosc.canterbury.ac.nz:

The mkdir command only needs to be done the first time you set this connection up. Then in a new terminal window we can make remote files locally accessible in a directory calledremotefiles, like this:

When you have finished with the mount you can disconnect it with one of the following two commands:

Windows

For Windows you still need to create the SSH tunnel as described for Linux and MacOS above, but after that there are a few options available for accessing files.

You can access files by mapping a network drive. First though you need to install a couple of support programs called WinFSP and SSHFS-Win.

There is good documentation for showing you how to map a drive graphically or via a command prompt once you have WinFSP and SSHFS-Win installed.

Alternatively, MobaXTerm will by default start a SFTP or SCP connection when you connect to an SSH session. Your files will be shown in the side-bar beside the Terminal window.