Using Secure Shell on LRZ HPC Systems

Introduction

For access to the LRZ HPC systems from outside, public/private key encrypted communication ("secure shell") must be used; the variant described here deploys the portable openssh implementation for this purpose. Another variant, GSI-SSH, is described elsewhere.

The following features of secure shell are relevant for users of LRZ HPC systems:

  • encrypted transfer of passwords and data
  • tunneling of services (in particular X11 graphics display) over the secure shell network port
  • usage of version 2 protocol of ssh. Version 1 is not supported at LRZ, since not sufficiently secure.

Secure shell has superseded other, insecure protocols like rsh and telnet, which are not supported any more at LRZ.

Usage

Basic usage of ssh is very simple: Issue the command

ssh -l lrz_account target_system

and enter the password when prompted. If the authentication is successfully concluded, you have a login shell on the target system. The target system typically must be specified with its full domain name.

Before the first login to the target system, you need to enter the target system's public key into the ~/.ssh/known_hosts file (you may need to generate the .ssh directory if it does not exist yet). You can cut and paste the public key lines from the LRZ web server:

A secure copy mechanism is also provided:

scp my_file <my_lrz_account>@<target_lrz_system>:<remote_dir>

will, for example, copy the local file my_file to the directory ~/remote_dir on the remote system. This directory must exist prior to the copy attempt.

Installation

While secure shell is installed by default on LRZ systems, it may be necessary to install it on your system.

  • Linux Systems: Most distributions contain an ssh client, but it may not have been installed. Please use the distribution-specific installation program to install the client
  • Windows Systems: Various free implementations are available on the internet, for example PuTTY. Your system administrator may already have provided it. There also exists a description of its usage on the LRZ web site.
  • If you have a C compiler on your system, you can also install e.g. portable openssh from source.

Configuration for access to LRZ systems from outside

Before using secure shell, you will need to configure the software. The configuration starts on your own workstation/desktop (aka the client), other items need to be performed on the target LRZ system itself. While the ssh command will also work without these customization steps, usage is made easier by performing it. Here is the sequence of commands you need to perform; the leftmost column of the table indicates where the respective commands must be executed.

WhereCommandsRemarks
 Client system (your desktop) ssh-keygen -t rsa Generate an RSA key. The command will respond with
Generating public/private rsa key pair.
Enter file in which to save the key 
(/home/myaccount/.ssh/id_rsa)
to which you respond by typing the ENTER key. Next, you are prompted for a passphrase-
Enter passphrase (empty for no passphrase):
to which you should respond with a non-empty passphrase (a long sentence, but easy to remember for you). Once this is done, both the files ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub(the private and public keys, respectively) exist.

It is not allowed to use an empty passphrase. We consider an empty passphrase as a violation of elementary security policies and will shut out any user doing so from further usage of LRZ systems.

LRZ target system mkdir -p ~/.ssh
chgrp $(id -g -n) ~/.ssh
chmod o-rwx,g-w ~
chmod go-rwx ~/.ssh
Client system (your desktop)
LRZ target system vi ~/.ssh/config In the editor, enter the line
ForwardX11 yes

 

(if it not yet exists). This will activate X11 forwarding. Then, save and quit the editor.
Client system (your desktop) scp ~/.ssh/id_rsa.pub \
user@target:.ssh/id_rsa_local.pub
copy public key to remote system. Please insert correct LRZ user name and target system name, and enter password when prompted.
LRZ target system cd ~/.ssh
cat id_rsa_local.pub >> authorized_keys
rm id_rsa_local.pub
add public key to list of authorized keys.

Per-session activity

At the beginning of your day's session please perform the following on your desktop:

CommandsRemarks

eval $(ssh-agent -s)

or

eval `ssh-agent -c`

Starts the ssh agent for your shell. The first variant will work for bash/ksh/sh, the second one for csh/tcsh.

Note: modern Linux distributions already do this for you. So you can omit this step if you already see a ssh-agent process running on your system.

ssh-add You will be prompted for the passphrase(s) associated with your key(s). Please enter the value configured by you.

Subsequent ssh commands can then be executed in the same shell without needing to re-authenticate. For other shells, you need to set the environment variables SSH_AUTH_SOCK and SSH_AGENT_PID to the same values as in the shell that started the agent, and export them (this can be automated).

LRZ internal configuration

This section is only relevant for setting ssh up to work without passwords (and without ssh agent) inside the cluster. This is needed for e.g. batch process startup in some MPI implementations). None of the keys (public or private) generated here should be transferred outside the cluster, since this may incur security problems. The following commands must therefore be executed on the LRZ target system.

CommandsRemarks
ssh-keygen -t rsa Generate an RSA key. The command will respond with
Generating public/private rsa key pair.
Enter file in which to save the key (/home/myaccount/.ssh/id_rsa)
to which you respond by typing the ENTER key. Next, you are prompted for a passphrase-
Enter passphrase (empty for no passphrase):
to which you should respond by typing ENTER (no passphrase).
cd ~/.ssh
cat id_rsa.pub >> authorized_keys
add internal public key to list of authorized keys.

Special topics

This section discusses special usage patterns that are relevant if a system only allows one-way connections (such as the SuperMUC, which does not allow outgoing traffic). As a consequence, tools (such as distributed source control packages) which use ssh as the underlying transport protocol may fail.

Port forwarding

If outgoing traffic is disallowed, you can set up port forwarding using an incoming connection e.g.,

ssh -R <NEW_PORT>:<URL>:<PORT> <Your Login>@<Login Node>.lrz.de

the shell generated on the target system will then allow you to specify localhost:<NEW_PORT> in place of the original <URL>:<PORT> because the ssh connection forwards the former to the latter through a tunnel connection.

Note that <NEW_PORT> must not be in use by someone else; you will see a ssh-generated error message if this is the case. If your software stores <NEW_PORT> away somewhere, you will need to do additional configuration changes if you need to change the value of <NEW_PORT>.

If incoming traffic is disallowed for a <PORT>, the following command can be used:

ssh -L <NEW_PORT>:localhost:<PORT> <Your Login>@<Login Node>.lrz.de

On a separate local shell, it is then possible to access the service running on <PORT> of the remote machine via localhost:<NEW_PORT>.

Data access via sshfs

If port forwarding fails and your software only requires access to data on disk, using a ssh-tunnelled mount may be sufficient. The sshfs command, which typically is delivered with modern Linux distributions can be used for this purpose:

sshfs [-o workaround=rename]  <Your Login>@<Login Node>.lrz.de:<Path name> <Mount Point>

will mount a path on the remote system to a local mount point; if the remote path is omitted the HOME directory will be used. File access permissions should be taken over from the remote system. Once the mount is established, you can run your software locally and access data via the mount; note that some packages may need additional workaround options such as the one optionally specified above. You can remove the mount via the command

fusermount -u <Mount Point>

Troubleshooting

Login fails

If for some reason the secure shell commands do not work, please

  • Try a ping command to the target system
  • Try a host command with the target system as the argument (local DNS configuration).
  • Check whether any maintenance measures have been announced for the target system.
  • Check whether suitably restrictive permissions are set on your $HOME as well as your $HOME/.ssh directory (see above).
  • Finally, try the -v (verbose) option on the ssh command. If you then decide to contact LRZ HPC support, the information contained in the verbose output may be very helpful

X11 does not work

If opening new X windows does not work, please check the following:

  • You may need to specify the -Y switch in your ssh command line; alternatively, an entry of the form

            ForwardX11Trusted yes

    in your .ssh/config file should achieve the same effect. Note that this setting assumes that you trust our administrators as well as our security procedures, since technically this opens a tunnel that allows an attack on your X11 display. You can consider using the -X switch (or the ForwardX11 configuration file setting) instead, but a great many X11 clients will not work at all then.
  • If you have a Microsoft Windows client, you need to activate X11 tunnelling in the PuTTY configuration, as well as have a X Window server (e.g. Xming) running locally.
  • If you got an error message like
    error in locking authority file
    /home/cluster/.../.Xauthority
    
    at login, please check your HOME filesystem quota. If this command indicates an overflow, you need to delete files from your HOME directory. Multiple simultaneous logins to the target system may also provoke the above error message (in this case due to file locking). In the latter case, please exit the failed shell and start a new one.