Download and setup MobaXterm¶

Go to the MobaXterm website and download the free version. Make sure to select the from the download page. Create a MobaXterm folder on your Windows user Documents one and uncompress inside it the contents of the downloaded zip file. We chose to create the MobaXterm folder on that particular location and we will refer to that on this guide. You can, of course, select some other location of your preference if you wish. The steps showed here has been done with version 20.2 of MobaXterm. Some behaviors may change between version.

Configuration information¶

Clusters¶

All CÉCI users can connect to any of the following clusters:

Lemaitre4 (UCL): lemaitre4.cism.ucl.ac.be
NIC5 (ULiège) : nic5.uliege.be
Hercules2 (UNamur): hercules.ptci.unamur.be
Dragon1 (UMons): dragon1.umons.ac.be
Dragon2 (UMons): dragon2.umons.ac.be

We will use my-ceci-cluster.example.com as a generic dummy address throughout the guide. When trying to follow the steps on your machine replace that by a real remote host of the CÉCI cluster you wish to use.

To decide which cluster is better suited for your kind of jobs, please check the details about them in the CÉCI clusters page.

Gateways¶

orphan:

As the clusters are not accessible from outside the university networks, you will need to use a SSH gateway and the university VPN in some cases. Going through a SSH gateway can be entirely transparent provided your client is correctly configured. The CÉCI does not offer a centralized gateway service, so you will have to use the one provided by the University you belong to:

UCL: use gwceci.cism.ucl.ac.be as SSH gateway with your CÉCI account. See the CISM documentation.

ULB: use gwceci.ulb.ac.be as SSH gateway with your CÉCI account. You will need to use a VPN also if you are outside Belgium.

UMons: contact the local support team to learn how to setup the VPN, then use dragon2.umons.ac.be as gateway.

UNamur: use gwceci.unamur.be with your UNamur identity (eID)

ULiège: use gwceci.uliege.be with your CÉCI account AND use the ULiège VPN.

We will use my-univ-gateway.example.com as a generic dummy address throughout the guide. When following the steps on your machine replace it by the correct ssh gateway of your university of origin.

1. Get the private CÉCI key¶

To get the private key, you need to create or renew your CÉCI account

Note

Please note that since the moment you got the email with you key confirming your account is active, you might need to wait up to ~20 minutes maximum until the access is enabled in all the clusters.

For some Universities the ceci public key needs to be set in the gateway and this can take some hours.

Once you have received your private key by email, store it the Documents\MobaXterm folder. You should have this configuration.

2. Setup a remote session¶

Double click the MobaXterm_Personal_XX.X.exe executable file inside the Documents\MobaXterm folder. You should see the MobaXterm main window like this one:

Click on the Session icon on the top left corner.
The Session settings configuration panel will open, select the SSH session type and you should see a window like this:

In the Remote host field introduce the cluster remote address for your desired cluster
- Lemaitre4 (UCL): lemaitre4.cism.ucl.ac.be
- NIC5 (ULiège) : nic5.uliege.be
- Hercules2 (UNamur): hercules.ptci.unamur.be
- Dragon1 (UMons): dragon1.umons.ac.be
- Dragon2 (UMons): dragon2.umons.ac.be
Tick the Specify username box and introduce your CÉCI username. Click the Advanced SSH settings tab and you will see these extra options:

Tick the Use private key box and click on the icon on that field, a file browser will be opened, locate your id_rsa.ceci key file you received by e-mail. Take note that you should not change the location of the CÉCI key file. If you move it you will have to update its location in this setting section again, to allow MobaXterm to find it. Check that the SSH-browser type is set as SFTP protocol. The SSH settings tab should look like this at the end of the process:

Select Network settings tab.

For Mobaxterm version 20.6 or higher, click on “SSH gateway (jump host)”

Fill the Gateway host with the gateway from your university (see the list above). In Username add the login name to connect to the gateway. Tick the Use SSH key box and click on the icon on that field, and locate your id_rsa.ceci key file again.

For Mobaxterm version 20.5 or earlier, tick the Connect through SSH gateway box and for any cluster always use the ssh gateway from your university:

UCL: gwceci.cism.ucl.ac.be

ULB: gwceci.ulb.ac.be

UMons: dragon2.umons.ac.be

UNamur: gwceci.unamur.be

ULiège: gwceci.uliege.be

In User add the login name to connect to the gateway. Tick the Use private key box and click on the icon on that field, and locate your id_rsa.ceci key file again.

Warning

If you are working at UMons use dragon2.umons.ac.be as gateway for all CÉCI clusters except for dragon2 itself. For this cluster do not fill the gateway tab contents.

Press the OK button and you should be prompted for your passphrase. Enter here the passphrase you chose while filling the CÉCI web application

You should connect to the cluster and be greeted by a screen similar to this one:

On the left sidebar you will see on the tab a file browser of your home directory in the cluster. You will see by default many files whose names start with a dot (.) symbol. These are hidden files of the Linux environment and you should not delete nor move them. You can edit and customize them if you are aware of what you are doing.

When you disconnect from the cluster (by typing exit or closing the terminal tab) you will find on the left sidebar on the Sessions tab a shortcut to the session you just setup. From now on, when you open MobaXterm, you can just double click that shortcut and you will start a remote session on my-ceci-cluster.example.com.

To create new sessions for other clusters:
- Right click the shortcut on the Sessions tab and select Duplicate session.
- Right click the shortcut of the new duplicated session and select Edit session
- Change the cluster remote address in Remote host field (the others parameters do not change) and press the OK button.
- Right click again in the shortcut and select Rename session to rename the session with the cluster name.

You can repeat step 9 for the rest of the CÉCI clusters you are planning to use.

If you wish you can also create a direct shortcut on your desktop. To do that, right click on the saved session name and choose Create a desktop shortcut, as shown below. An icon will appear on your Desktop which double clicking starts MobaXterm with a session on the cluster.

3. Copying files to and from the cluster¶

After you succeeded to setup the shortcut for connecting to a cluster, as we noted on the step 6 of the previous section, you will see on the left sidebar on the Sftp tab a file browser on the cluster you are connected to.

You can simply drag and drop files from your computer to that panel and they will be copied to the cluster. The same is valid for retrieving files from the cluster to your computer.

If you right click on that panel, you will see different options to interact with the browser (see the figure below). Remember always to press the Refresh current folder button after you copied something or a new file or folder is created on the cluster.

Note that you also have the right-click options directly available through the icons on the toolbar at the top of the panel.

4. Setup an SSH agent to avoid typing the passphrase at each login¶

After you successfully setup your cluster to connect by double clicking the shortcut, you will notice that you are prompted for the passphrase for each connection you make to a cluster. To avoid retyping it each time, you can setup an internal SSH agent in MobaXterm that will take care of unlocking the private key when you open the application.

Open the MobaXterm program and click to the Settings icon
You should see the MobaXterm Configuration panel. In the General tab choose the MobaXterm passwords management option, a new panel will be opened, make sure that Save sessions passwords has the options Always and Save SSH keys passphrases as well selected as shown below and click OK.
Now go in the same MobaXterm Configuration panel to the SSH tab. Make sure that all the options below the SSH agents section are ticked.
Press the + button in the Load following keys at MobAgent startup field and look for your id_rsa.ceci file, at the end the panel should like as this

Remember that you should not change the file location, otherwise you’ll have to come back to this settings to update it.
Press OK and you will be prompted for restarting MobaXterm, choose to do so.
When it is relaunched you will be asked for the private key passphrase at the beginning, after you introduced it correctly it will stay saved for all the forthcoming sessions. You should be able to double click in the shortcuts for the clusters and get connected directly.

Frequently encountered problems¶

You are using the wrong key¶

To ensure you are using the correct key we need to compare the finger print of your private key with the finger print of the public key on the CÈCI front-ends.

Open MobaXterm_Personal_XX.X.exe go to tools menu and select the ssh key generator. In Conversion tab, select Import key. and load your id_rsa.ceci key. You will be asked for the key passphrase.

The public key and the fingerprint will be displayed.

Key change after account renewal¶

After you have renewed your account, or requested a new key, you will have to replace the old key file with the new one you received by email. You can rename the old file to keep it rather than erasing it.

When that is done, you should be able to connect again using the configuration your previously set up.

There is one notable exception though, the SSH agent. You will have to replace the key in the agent with the new one.

Click ‘Settings’
Choose the SSH tab
Remove previous key by selecting it and hitting the - button, then click + and add the new file
Let MobaXTerm restart