- Access
- Getting a JSC account
- Joining a compute time project
- Login procedure
- Generating a key pair with OpenSSH
- Generating a key pair with PuTTY
- Uploading the public key
- IPv6 connectivity update for JURECA login nodes
- Logging in with OpenSSH
- Logging in with PuTTY
- JupyterLab
- Checking System/Service Status
- Further reading
sidebar_position: 2
Access
This chapter will teach you how to log in to the systems at JSC.
Getting a JSC account
A basic prerequisite to get access to the HPC systems and other services at JSC is a JSC account.
If you do not already have an account (they have the form <family name><number>
, e.g. steinbusch1
), one can be created through JSC's user portal JuDoor (click the Register button).
Joining a compute time project
To be allowed to log in to an HPC system, your JSC account needs to be a member of a computing time project that has an active budget on the system. This is the case if
- you have successfully applied for test computing time for a test project and are now the principal investigator (PI) of your own project, or
- you have successfully applied for computing time during one of our calls for project proposals and are now the principal investigator (PI) of your own project, or
- you have gained access to a project either by being invited by the PI or project administrator (PA) or by being granted access upon requesting to join a project through JuDoor.
We have created a computing time project for this course with a project ID of trainingFIXME
.
To join the project, log in to JuDoor and click Join a project under the Projects heading.
Enter the project ID and, if you want to, a message to remind the PI/PA (one of the instructors) why you should be allowed to join the project.
Afterwards the PI/PA will be automatically informed about your join request and can add you to the different systems available in the project.
As soon as you are unlocked for the system, the system entry will be shown on your JuDoor main page.
You have to accept our Usage Agreement for the system you want to use before you can continue with the next step.
Login procedure
Logging in to our systems is usually done through the Secure Shell (SSH) mechanism, although there are alternatives such as UNICORE and JupyterLab. Our SSH configuration uses an authentication mechanism based on public and private keys rather than passwords. A pair of public and private keys has to be generated on your personal computer. The private key has to be protected by a passphrase. The public key is then registered for access to the system through JuDoor.
:::danger[CAUTION]
NEVER SHARE YOUR PRIVATE KEY!!!
:::
Several software packages can be used for logging in through SSH. The procedure is documented below for some popular choices:
- OpenSSH - a popular choice on GNU/Linux, macOS, and other Unix-like operating systems
- PuTTY - a popular choice on Windows
:::info[Multi-Factor Authentication]
JuDoor offers users the option to enable Multi-Factor Authentication (MFA), which adds an extra layer of security to your account. With MFA enabled, you'll be required to provide a secondary factor of authentication in addition to your password. For example, when logging in to JSC services, you'll be prompted to enter a time-based one-time password (TOTP) as the second factor. In addition, JuDoor allows users to enable MFA for SSH login. Once enabled, when accessing the ssh service on the login hosts of the JSC system, users will be prompted to enter a 6-digit token after successfully authenticating using the ssh public key.
To enable MFA in JuDoor please navigate to the "Account Security" page by clicking the fingerprint icon in the navigation bar or using the account dropdown menu. There you see a list of your accounts. You can start the setup process using the "Start MFA Setup" button. On this page you can find our recommendations for TOTP Apps to use, but any other TOTP App should probably work just as well. You will need to install a compatible App, scan the QR-Code with the App to add the account, and then insert into the form both your current password and the code the App generates. After pressing "Continue" you will be presented with 10 reset codes. These can be used to disable MFA again in case you lose access to your second factor. You should save these at a secure location or print them. MFA will be enabled for your account only after you have confirmed that you have saved these reset codes. MFA is now enabled. The Fingerprint Icon in the Navigation bar now shows your MFA authentication state. Because you have just entered a valid code, you are MFA authenticated and can continue to use JuDoor as normal. The MFA authentication expires after 24 hours or if you open JuDoor from a different browser/device or clear your cookies.
The following actions are secured by MFA in JuDoor and therefore a valid token is needed:
- Joining a project
- Adding an SSH Key
- Removing an SSH Key
- Changing someone's access in a project if you are a PI or PA
- Actions that require TOTP are marked with a fingerprint icon.
Currently, MFA is an opt-in feature (can be activated on demand). However, at some point in the future, it will become an opt-out feature (activated by default but can be deactivated if desired).
:::
Generating a key pair with OpenSSH
OpenSSH is a set of command line tools, so open up a terminal. We suggest you start by creating a fresh pair of public and private keys (a key pair). To generate a key pair enter the command shown in the code snippet below. The program asks for a passphrase. This passphrase is not used for authenticating to the remote system, but rather acts as an encryption key for the private part of the key pair stored on the local file system. In case the private key file is stolen by an attacker, they will not be able to use the key without knowing the passphrase, so make sure to use one that is hard to guess.
$ ssh-keygen -a 100 -t ed25519 -f ~/.ssh/id_ed25519
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/bsteinb/.ssh/id_ed25519.
Your public key has been saved in /Users/bsteinb/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:tHin8v4j4cyVVe2BEWAinq/vlhFExupY+37s94216uA bsteinb@zam478
The key's randomart image is:
+--[ED25519 256]--+
| .o+ o.o+. |
| . +oo ....|
| o+ . ..|
| =.o . .|
| = S.oo |
| . +o+o |
| .=oo+. .|
| o*+oo.. oo|
| .**+Eoo+o.|
+----[SHA256]-----+
If the designated output file (~/.ssh/id_ed25519
) already exists, the program asks to overwrite it.
This is probably not what you want, since you might be using the key contained therein.
Change the output name by using the arguments -f ~/.ssh/id_ed25519_jsc
instead of -f ~/.ssh/id_ed25519
.
If you do so, keep in mind that your keys are in a non-default location for the remainder of the course.
Print the contents of the public key to the terminal by entering:
$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1N [...] 6BRJMTyE4voyqJGm36P+ bsteinb@zam478
and copy it to the clipboard (do not copy the key above! This is only an example, The one you have generated will be different). Continue by uploading the public key to JuDoor.
Generating a key pair with PuTTY
Open puttygen.exe
to generate a key pair.
Select Ed25519 as the key type then click Generate and follow the instructions of the program.
Once the key has been generated, enter a strong passphrase that cannot be guessed easily.
This passphrase is used to encrypt the key while it is stored on disk so that it cannot be used if it is stolen.
Click Save private key to save the private key to a .ppk
file.
Now copy the contents of the field Public key for pasting into OpenSSH authorized_keys file to the clipboard.
:::info
There is a known issue currently with the Windows implementation of OpenSSH. If you see the error message
Corrupted MAC on input.
ssh_dispatch_run_fatal: Connection to x.x.x.x port 22: message authentication code incorrect
while trying to log in, please follow the guidance here.
:::
Uploading the public key
Navigate to JuDoor and click on Manage SSH-keys next to the entry for the system you want to use under the Systems heading.
Paste the public key into the form in the field labeled Your public key and options string, but do not submit yet.
As a further security measure, you have to specify the systems that your log in attempts will come from.
This is done via an additional from
-clause on your public key, that can contain single IP-addresses and address ranges as well as host names and even wildcard patterns based on either of these.
Specifying a from
-clause is relatively easy if you have access to a system with a fixed IP-address or an IP-address that changes dynamically, but comes from a range of addresses that can be specified concisely.
This is typically the case for systems which are connected to university or research centre networks (even via VPN when working from home).
For example, systems connected to the network of Forschungszentrum Jülich will be assigned an IP-address from the range 134.94.0.0/16
, so a valid from
-clause would be from="134.94.0.0/16"
.
Other institutions will use different address ranges, you should be able to find these out from your institutions network operations centre.
Sometimes, patterns based on host names will work better than those based on IP addresses.
For example, Forschungszentrum Jülich assigns host names that end in either fz-juelich.de
or kfa-juelich.de
, so a valid from
-clause could also be from="*.fz-juelich.de,*.kfa-juelich.de"
(notice how multiple patterns can be combined with a comma in between).
Once again, the host names assigned by other institutions will be different.
To some extent, this scheme also works for home internet access.
Internet providers typically assign IP addresses dynamically drawing from fragmented pools that are hard to specify completely in terms of address ranges, but they often assign host names which follow a pattern that can be found out.
The command nslookup <your IP>
will tell you the host name assigned to your system by the provider (find out your IP either from the JuDoor key upload form or by asking a search engine "what is my ip").
This host name might look something like 2909a2-ip.nrw.provider.net
.
Chop name components off the beginning and replace them with *
to come up with a pattern, e.g. *.nrw.provider.net
.
Add your from
-clause in front of the public key you already pasted into the form.
The result should be something like:
from="134.94.0.0/16" ssh-ed25519 AAAA [...]
Then click Start upload of SSH keys. It will take a little time for the key you uploaded to JuDoor to be synched to the actual system. Eventually though, you will be able to log in. Once again, we have instructions for
IPv6 connectivity update for JURECA login nodes
For users connecting from machines with a globally routed IPv6 address assigned to them, their SSH clients will favour IPv6. This can lead to issues for users who have uploaded SSH public keys with from=
clauses based solely on IPv4 addresses or using patterns based on host names which do not match the host names their internet provider assigns to IPv6 addresses.
The long term solution for these issues is to update your from=
clauses to include patterns based on IPv6 addresses (or host names matching the IPv6 addresses).
A short term solution can be to revert to IPv4 connectivity. This can be done by connecting to a new DNS name which will keep resolving to IPv4 addresses only: jureca-ipv4.fz-juelich.de
. Another option is to disallow IPv6 in your SSH client. For OpenSSH this can be done with the command line option -4
or the configuration setting AddressFamily inet
. In PuTTY the protocol can be overridden with the setting 'Internet protocol version' in the 'Connection' pane.
Logging in with OpenSSH
To log in with OpenSSH, enter the following command:
$ ssh -i ~/.ssh/id_ed25519 <account name>@<system name>.fz-juelich.de
(Remember to change the location of the key ~/.ssh/id_ed25519
if you saved it to a non-default location.)
For example, if I wanted to log in to JUWELS Cluster it would be:
$ ssh steinbusch1@juwels-cluster.fz-juelich.de
The following table lists the host names of login nodes for the different systems. Pick the one you want to use.
System | Login node host name |
---|---|
JURECA-DC | jureca.fz-juelich.de |
JUWELS Cluster | juwels-cluster.fz-juelich.de |
JUWELS Booster | juwels-booster.fz-juelich.de |
JUSUF | jusuf.fz-juelich.de |
When connecting for the first time, OpenSSH will prompt you to confirm the server key fingerprint:
The authenticity of host 'jusuf.fz-juelich.de (134.94.0.184)' can't be established.
ECDSA key fingerprint is SHA256:tuswM7JtVcWNS5wRCVIfv1h4uRHReHIN77C4zTYaPjs.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
JSC publishes SSH fingerprints for its systems through JuDoor. You can find them on the page you used to upload your public key. Either compare the keys or, in newer versions of OpenSSH, you can paste the fingerprint from JuDoor into the prompt to confirm it.
Then you should see an informational message (the message of the day, MOTD) followed by a shell prompt similar to the following:
********************************************************************************
* Welcome to *
* _ _ ___ _______ _ ____ *
* | | | | \ \ / / ____| | / ___| Juelich Wizard *
* _ | | | | |\ \ /\ / /| _| | | \___ \ for *
* | |_| | |_| | \ V V / | |___| |___ ___) | European Leadership *
* \___/ \___/ \_/\_/ |_____|_____|____/ Science *
* *
********************************************************************************
2020-11-19T14:00+0200
### Status information JUWELS ###
Known issues: https://apps.fz-juelich.de/jsc/hps/juwels/known-issues.html
********************************************************************************
steinbusch1@jwlogin01:~ $
Once you have logged in successfully, you can continue with Unix shell basics.
Logging in with PuTTY
Launch putty.exe
to log in.
Set the Host name for the system you want to connect to, e.g. juwels-cluster.fz-juelich.de
.
The following table lists the host names of login nodes for the different systems. Pick the one you want to use.
System | Login node host name |
---|---|
JURECA-DC | jureca.fz-juelich.de |
JUWELS Cluster | juwels-cluster.fz-juelich.de |
JUWELS Booster | juwels-booster.fz-juelich.de |
JUSUF | jusuf.fz-juelich.de |
Navigate to Connection > SSH > Auth > Credentials and under Private key file for authentication: select the key you just generated.
If you want to save this configuration, you can navigate back to the Session screen to give the session a name and save it. Now click Open to connect. When you connect for the first time, PuTTY will display a dialog like the following:
This is not an error, but a security feature. The server key fingerprint displayed in the dialog has to be verified by comparing it to the known good fingerprint. JSC publishes SSH fingerprints for its systems through JuDoor. You can find them on the page you used to upload your public key.
Once you have logged in successfully, you can continue with Unix shell basics.
JupyterLab
Alternatively, you can use JupyterLab to log in. The authentication credentials are the same as for JuDoor. Once you have logged in, you need to create a JupyterLab instance by clicking Add New JupyterLab. On the next screen you must select which system you want to log in to, what project to use for accounting and what part of the system you want to log in to (more about this later), login nodes are the right choice for the moment. Startup of JupyterLab may take a while, but once it is done, you can launch a terminal running a shell on the system of your choice inside the browser. To do so, click File > New > Terminal and you should see a shell prompt similar to this:
[steinbusch1@jrl06 ~]$
Checking System/Service Status
The root cause of many problems ("I cannot log in", "the system is slow") can be found by checking the JSC status webpage. Here you will find up-to-date status information on the services JSC provides, including upcoming planned maintenances. A traffic-light colour system is used to indicate the state of a system or service, with green systems functioning as expected for most or all users. Yellow systems are degraded, with issues that will impact many users. Red systems are strongly degraded which will impact most or all users. Finally, dark-red systems are unavailable. Do not fret that you see more systems than what you have access to, as this is a general landing page for all of our systems.
Below our cluster systems you can find information on our storage systems/tiers. If you cannot find files, a certain mount is unavailable or the system becomes unresponsive to filesystem commands like ls
this is the place to check. Even further down is the status of the services JSC provides, like JuDoor or Jupyter-JSC. Finally there is the status of JSC-support. Check here if you cannot reach JSC support or they do not respond in a timely fashion, if there is no reported issue try contacting them again using a different mode of communication, i.e. telephone or email. At the bottom of the page is a description of the traffic-light icons.
You can get further information on the degraded status of the systems and services by clicking on any of the system names, filesystem names or services. Give it a try! There you can also see older issues to help you diagnose problems that may have occured in the recent past.
Further reading
Our online documentation has more information on accessing the systems.
It provides further examples of from
-clauses, discusses configuration of SSH clients to set up short-cuts and gives hints for troubleshooting.
If you want more details, you can find the documentation for our various systems here: