Connecting from UNIX-like environment (Linux, Mac OS X, Cygwin/MingW)¶
This short tutorial describes how to connect to a CÉCI cluster from a terminal application, such as XTerm, Gnome Terminal, Konsole, iTerm, Linux running on Windows Subsytem For Linux, etc.
All CÉCI users can connect to any of the following clusters:
- Lemaitre3 (UCL):
- NIC4 (ULiège) :
- NIC5 (ULiège) :
- Hercules2 (UNamur):
- Dragon1 (UMons):
- Dragon2 (UMons):
To decide which cluster is better suited for your kind of jobs, please check the details about them in the CÉCI clusters page.
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.beas SSH gateway with your CÉCI account. See the CISM documentation.
- ULB: use
gwceci.ulb.ac.beas 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
- UNamur: use
gwceci.unamur.bewith your UNamur identity (eID)
- ULiège: use
gwceci.uliege.bewith your CÉCI account AND use the ULiège VPN.
Choose your favorite terminal application to follow the steps below.
1. Get the private CÉCI key¶
To get the private key, you need to create or renew your CÉCI account
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 in a safe location. The most rational place to store it is in your
.sshfolder in your home directory, along with other SSH keys you may have. In case the file was downloaded in the
Downloadsfolder in your home, move it with the command:
mv ~/Downloads/id_rsa.ceci ~/.ssh
Change the permissions of the file so that only you can read it:
chmod 600 ~/.ssh/id_rsa.ceci
If you don’t do this your SSH client will refuse to use the key giving an error which mentions
Permisions 0644 for... are too open.
Create your public key:
ssh-keygen -yf ~/.ssh/id_rsa.ceci > ~/.ssh/id_rsa.ceci.pub
You will be asked by the passphrase you chose on the CÉCI account creation form.
2. Connect to a cluster¶
Even if you are used to use
ssh on the command line, the fact of having to
go through a gateway makes the command to connect too cumbersome to type it
every time. So we will instruct you on how to create a
ssh_config file to
ease with this.
Go to our ssh_config wizard that will aid in creating the configuration depending on your University.
Choose which is your University and provide the required information.
Use your favorite text editor on the terminal (nano, vim, emacs ...) to create or edit the configuration file
and copy-paste the contents provided by the wizard. If you already have contents there, keep it and paste this block below it, save the changes. Make sure the file has correct permissions:
chmod 600 ~/.ssh/config
Now everything is set, you can do your first connection using the command:
Where you should replace
clustername by one of the Host alias for the CÉCI
If it is the first time you use the private key and/or your agent is not running you will be asked for the key passphrase twice. One for the gateway connexion and another for the cluster connexion.
If everything worked properly, you should be greeted by a message similar to
Welcome to ██╗ ███████╗███╗ ███╗ █████╗ ██╗████████╗██████╗ ███████╗██████╗ ██║ ██╔════╝████╗ ████║██╔══██╗██║╚══██╔══╝██╔══██╗██╔════╝╚════██╗ ██║ █████╗ ██╔████╔██║███████║██║ ██║ ██████╔╝█████╗ █████╔╝ ██║ ██╔══╝ ██║╚██╔╝██║██╔══██║██║ ██║ ██╔══██╗██╔══╝ ╚═══██╗ ███████╗███████╗██║ ╚═╝ ██║██║ ██║██║ ██║ ██║ ██║███████╗██████╔╝ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚═════╝ Massively parallel CISM-CECI cluster 80 nodes: 2 x 12-core Intel Skylake firstname.lastname@example.orgGHz, 96GB RAM 1:3-blocking OmniPath Architecture network contact, support: email@example.com ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CÉCI clusters: Hmem - Lemaitre3 - Dragon1 - Dragon2 - Hercules - Vega - NIC4 You currently have 0 job running, 0 pending. Don't know where to start? --> http://www.ceci-hpc.be/install_software.html --> http://www.ceci-hpc.be/slurm_tutorial.html
Upon your very first connection to each CÉCI cluster, you will be greeted by a warning such as:
The authenticity of host 'my-ceci-cluster.example.com (XXX.XXX.XX.XX)' can't be established. RSA key fingerprint is SHA256:aqUPC4C8gkBjgCUMpHt3kzpciSkQcKR2gNOahnbZN3c. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'ceci-cluster.ac.be,XXX.XXX.XX.XX' (RSA) to the list of known hosts.
This warning is normal, the SSH program warns that it is the first time it sees this computer. To make sure you are actually connecting to the right machine, you should compare the RSA key fingerprint shown in the message with the fingerprint announced on the Access section of the CÉCI cluster page. The fingerprint can be based on hash function MD5 or SHA-256.
If they match, you are safe to proceed and enter yes. That hostname key will be stored and used to check in every subsquent SSH connection that the server is indeed always the same.
If you hit an error that mentions something as:
line 12: Bad configuration option: proxyjump
Then change the line with the
ProxyJump option in the
to read instead:
ProxyCommand ssh gwceci -W %h:%p
3. Using an SSH agent to avoid typing the passphrase at each login¶
You can further ease the process by using an SSH agent which will remember the passphrase so you do not have to type it each time you issue the SSH command. In any modern Mac OS or Linux distribution is quite certain that you have an agent already running, if the command:
The agent has no identities or a line like
2048 SHA256:1S30t9SSWSd2PIF0QVAPj1Xhtnj2UYqPw32ZIAu0MkI ~/.ssh/id_rsa.ceci (RSA)
you don’t have anything else to do, your agent is running. Please, check the notes at the bottom of this section if you are still being requested the passphrase at each cluster login.
If the command responds
Could not open a connection to your authentication
agent, you can start an agent with:
Then, load the CÉCI key with the command:
you’ll be prompted once for your passphrase. From now on, in the current terminal, all ssh commands will be handled by the agent and you won’t have to type your passphrase again.
With the agent running, you can use the
-A option of
ssh to forward
your agent from one computer to another (you don’t need this if you are using
ForwardAgent option in a
.ssh/config as explained in the section
above). This allows you to connect, or copy files, from one cluster to another
In Mac OS, after Sierra update 10.12.2, in order to automatically unlock
your keys these extra options are required on top of your
Host * AddKeysToAgent yes UseKeychain yes
Step 1. Make sure that your key file has the correct permissions:
ls -l ~/.ssh/id_rsa.ceci
should output something that starts with
Step 2. Make sure your key and your passphrase match by issuing the following command:
ssh-keygen -yf ~/.ssh/id_rsa.ceci
If the output is ‘load failed’ you either have a wrong passphrase or your key file has been corrupted.
Step 4. Make sure the ssh client is asking for a passphrase and not a password. Otherwise, it means you are not correctly instructing your ssh client to use the private key.
Run the ssh command with the
-v option. You should find a line
debug1: Offering RSA public key: .ssh/id_rsa.ceci
The line immediately following that one should be something like:
debug1: Server accepts key: pkalg ssh-rsa blen 277
otherwise it means the key your are using does not correspond to the one stored on the cluster. If this happens while you just updated or renewed your account, it may indicate that your new key is not fully propagated yet. Try again later.
Frequently encountered problems¶
Here are some frequent errors you should avoid.
The permissions on your key file are not correct¶
If, after running
ssh clustername, for instance, you see something like:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: UNPROTECTED PRIVATE KEY FILE! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Permissions 0644 for '/home/dfr/.ssh/id_rsa.ceci' are too open. It is recommended that your private key files are NOT accessible by others. This private key will be ignored. bad permissions: ignore key: /home/dfr/.ssh/id_rsa.ceci firstname.lastname@example.org's password:
it means that Permissions 0644 for the
are too open. Change them to 600 as explained in the first section of this
You did not specify the correct path to your SSH private key¶
If, after running ssh, you are being asked for a password directly,
$ ssh clustername email@example.com's password:
it means that your SSH client did not try to use the SSH key. Make sure
you either used the
-i option or that your
~/.ssh/config file is
properly configured and contains no typos.
You used a wrong username or tried to connect before your keys are synchronised¶
If, after running ssh, you are being asked for a passphrase, then a password,
$ ssh clustername Enter passphrase for key '/home/dfr/.ssh/id_rsa.ceci': firstname.lastname@example.org's password:
it often means that the user name you are using is not the correct one.
If you just requested or renewed your account, it could also mean that you are using the new private key while it has not been synchronized to that cluster yet (keep in mind that the clusters are not synchronized simultaneously). Wait about 15 minutes and try again.
You have too many SSH keys lying around¶
If the server responds with
$ ssh clustername Received disconnect from host: 2: Too many authentication failures for dfr
that means that your client offered the server too many keys to try and access
it. To make sure the client uses only the correct key (i.e. the one
specified by the
IdentityFile option,) you will need to add
IdentitiesOnly yes at the top of your
~/.ssh/config file, or pass it as
$ ssh -o 'IdentitiesOnly yes' clustername
Note that for the SSH-agent to continue working properly when this option is
added, you will need the public SSH key to be present in the
You can generate the public SSH key from the private key (the one you received from the CÉCI with the following command:
ssh-keygen -yf ~/.ssh/id_rsa.ceci > ~/.ssh/id_rsa.ceci.pub