SSH access to ITA systems

Updated November 2024

Changes

• SSH port changed to port 4000 instead of port 22
• Public key necessary
• Provided more comprehensive config example
• All connections must go through the gateway computer.

For security reasons, access to ITA compute servers is restricted and only possible via a gateway computer named:

welcome.ita.uni-heidelberg.de 

Note that this is also true if you are connected via the university VPN or inside the wired ZAH network.

You need a current operating system that is not out of support and an installation of OpenSSH. Operating systems that are out of vendor suppport are not allowed to connect to the ZAH systems and no effort will be invested to get them working. To check if your OS release is supported, please see https://endoflife.date

Examples for EOL systems (as of October 2024):

• All versions of Windows before Windows 10 (and also some releases of Windows 10 and 11, see the link above).
• All versions of MacOS before Version 13 (Ventura)
• Debian 10 and earlier
• All versions of Ubuntu before 24.04 except the LTS releases 22.04 and 20.04

To connect to an interactive terminal session,you need a recent version of OpenSSH. Other SSH implementations might work but might require additional steps like key format conversions. Please see the documentation of the software. This is especially true for Putty, which used to be a popular SSH implementation on Windows that is no longer required as all supported Windows 10 versions offer the option to install OpenSSH instead.

To remotely copy/edit files, you will need an SFTP client that can work with SSH keys. Examples are Cyberduck on Windows and MacOS or Transmit on MacOS (most Linux desktops should have a file manager with SFTP features installed by default).

Note: in the following you may have to replace the ~ by the full path of your ssh config file! (e.g. /home/xxx/.ssh/config ), where xxx is your local path to the home dir on your home computer (or ITA desktop computer).

Configuration

Edit the ~/.ssh/config file (create it if not already there) on your home/desktop computer. It should contain the lines:

## Set special rules for the gateway machine
Host welcome.ita.uni-heidelberg.de 
    # set the port to connect to 
    Port 4000
    # Replace with your actual ITA username 
    User <itausername>  
    # Replace with the name of your actual private key file if different (e.g. id_ed25519)
    IdentityFile ~/.ssh/id_rsa
    ForwardAgent yes
    AddKeysToAgent yes
    
    # Uncomment this line on MacOS to integrate your SSH agent with the systemwide keychain. 
    # This only works on MacOS and will generate an error elsewhere. 
    #UseKeychain yes

# Set rules for all ita/zah.uni-heidelberg.de machines except the SSH gateway
Host !welcome.ita.uni-heidelberg.de *.ita.uni-heidelberg.de *.zah.uni-heidelberg.de
    ProxyCommand ssh -q -a  -x welcome.ita.uni-heidelberg.de -W %h:%p
    IdentityFile ~/.ssh/id_rsa
    ForwardAgent yes
    AddKeysToAgent yes
    
    # Uncomment this line on MacOS to integrate your SSH agent with the systemwide keychain. 
    # This only works on MacOS and will generate an error elsewhere. 
    #UseKeychain yes

Convenient login

ssh -X username@hostname.ita.uni-heidelberg.de 

Please substitute username with your ITA username, and hostname with the computer of your choice, e.g. your desktop machin (NB: Some ITA machines have local users with different usernames. Use this where applicable).

After that, you are logged in through the gateway in one transparent step, and X-forwarding works, i.e. you can start an xterm and it will open on your home computer.

Most CLI applications that make internal use of SSH (as e.g. scp, rsync or git) will use the SSH config file as prepared above and implicitly use the SSH gateway. The same is true for some graphical programs and IDEs.

Others can be configured to use a tunnel themselve if they don't rely on the system SSH client or to at least import the system SSH config. How this is done varies wildly and is best looked up in your tools documentation.

But unfortunately, there exists a number of mostly graphical tools that can't be configured to use an SSH tunnel and that would not work in our environment out of the box. However, there is an easy way around this. SSH has a feature called tunneling, where you make a network service only available behind an SSH connection to appear locally on your machine.

If you want to access machine example.ita.uni-heidelberg.de from such a program, you would first establish a tunnel in a shell like so:

ssh welcome.ita.uni-heidelberg.de -L 2022:example.ita.uni-heidelberg.de:22

This makes the SSH service that is listening on port 22 on example.ari.uni-heidelberg.de available on port 2022 on your local machine and while this connection is open, you can configure your tool to connect to port 2022 on localhost instead of example.ita.uni-heidelberg.de.