These are the instructions on how to install and configure your Teleport SSH access on Linux to connect to ECMWF services such as the Atos HPCF and ECS services.

Table of Contents

<script src="https://sites.ecmwf.int/public/sharebox/confluence-tabs-sync.js"></script>
<script src="https://sites.ecmwf.int/public/sharebox/fetch-teleport-versions-class.js"></script>

Demo

Here is a demonstration on how to set up Teleport to connect to our our Atos HPCF on Ubuntu. You can find the step by step guide below.

Installing the tsh client

The tsh application is required to perform user authentication. tsh is open source, very portable, and has minimal dependencies.

Here are the installation instructions, extracted from the official Teleport documentation:

  • In your terminal, assign environment variables that you will use to download your intended archive.
    <div class="preformatted panel conf-macro output-block" style="border-width: 1px;" data-hasbody="true" data-macro-name="noformat">
<div class="preformattedContent panelContent">
<pre data-bidi-marker="true" class="teleport17-version">TELEPORT_PKG=teleport
TELEPORT_VERSION=17.0.0
SYSTEM_ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')</pre>
</div>
</div>
  • Run the following commands to download the Teleport archive, unpack it, and install binaries:
    curl https://cdn.teleport.dev/${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz.sha256
# <checksum> <filename>
curl -O https://cdn.teleport.dev/${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
shasum -a 256 ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
# Verify that the checksums match
tar -xvf ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
cd ${TELEPORT_PKG?}
sudo ./install

Just skip the last step and place the tsh executable somewhere in your PATH

You will need a client that of the same major version or one behind the server's. With https://jump-17.ecmwf.int, running version 17 of the service, you may connect with clients of versions 16.x and 17.x. Other combinations might work, but they are not supported.

Authenticating yourself

Once every 12 hours, you will need to refresh your tokens with the tsh command. SSH connections may remain active for longer than 12 hours, but new connections will require re-authentication.

To authenticate yourself, run tsh, giving the location of our Teleport gateway:

tsh login --proxy=jump-17.ecmwf.int

Your default web browser will open. You should login with your email address, ECMWF password, and then the code from your Time-based One-Time-Password (TOTP) device.

If you're already logged in to the ECMWF website, or have recently logged in to this service, the password prompt might be skipped.

If your computer does not have a browser or cannot display one, you may use the Teleport SSH access - Browserless Login Python Module for the authentication.

If the process is successful, you will see an output such as:

> Profile URL:        https://jump-17.ecmwf.int:443
  Logged in as:       user.address@somewhere.com
  Cluster:            jump-17.ecmwf.int
  Roles:              access
  Logins:             ecmwfusername
  Kubernetes:         enabled
  Valid until:        2025-03-21 20:25:29 +0000 GMT [valid for 10h35m0s]
  Extensions:         login-ip, permit-X11-forwarding, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy


Once you have logged int at least once, tsh will save your proxy settings so you can skip the extra argument next time: 

tsh login



Setup your SSH config

We strongly recommend setting up all the SSH options needed for the connection in your local ssh config file, instead of passing them on the command line.

Edit the file ~/.ssh/config on your computer and add the snippet below. You may create it if it does not exist. You should replace ecmwfusername by your registered ECMWF user and user.address@somewhere.com  by your registered email address at ECMWF.

If you have some configuration for a previous jump service at ECMWF, make sure you remove it (or move it aside) and replace it by the new one to avoid conflicts. 

Host *.jump-17.ecmwf.int jump-17.ecmwf.int* a?-* a??-* hpc-* ecs-* hpc2020-* lfc?-* ecf?-* ecflow-* ecinteractive*
    User ecmwfusername
    UserKnownHostsFile ~/.tsh/known_hosts
    IdentityFile ~/.tsh/keys/jump-17.ecmwf.int/user.address@somewhere.com
    CertificateFile ~/.tsh/keys/jump-17.ecmwf.int/user.address@somewhere.com-ssh/jump-17.ecmwf.int-cert.pub 
    ServerAliveInterval 60
    TCPKeepAlive yes 

Host !jump-17.ecmwf.int *.jump-17.ecmwf.int
    ProxyCommand tsh proxy ssh --cluster=jump-17.ecmwf.int --proxy=jump-17.ecmwf.int:443 %r@%h

Host hpc-login ecs-login
    Hostname %h.jump-17.ecmwf.int
    ProxyCommand tsh proxy ssh --cluster=jump-17.ecmwf.int --proxy=jump-17.ecmwf.int:443 %r@%h

# Extra configuration for additional internal hosts through the main entry point
Host a?-* a??-* hpc-* hpc2020-* ecs-* lfc?-* ecf?-* ecflow-* ecinteractive* !hpc-login* !ecs-login* !*.jump-17.ecmwf.int*
    ProxyJump hpc-login.jump-17.ecmwf.int
    # Replace by ecs-login.jump-17.ecmwf.int if only ECS access

You can find the right values for those two parameters in the output of the tsh login command

SSH connection

Once you have configured the appropriate settings, any SSH-based tools such as ssh, scp or rsync should work out of the box without any additional options.

To test the connection you may ssh into hpc-login if you have access to ECMWF's HPCF:

ssh hpc-login

Or alternatively, if you only have access to ECMWF ECS service:

ssh ecs-login

Visit our HPCF User Guide for further information.

Remember you may need to redo the authentication step for any new ssh connections after 12 hours with:

tsh login

Optional: Automating the authentication step

You may instruct ssh to trigger a tsh login whenever required when establishing a new connection by adding the following line at the top of your ~/.ssh/config

Match host jump-17.ecmwf.int exec "tsh status --proxy %h >/dev/null 2>&1 || tsh --proxy %h login"

Optional: VSCode settings

For those using VSCode, you may need to set the  Remote.SSH: Use Local Server setting to false in the extension setting. You can search for  @ext:ms-vscode-remote.remote-ssh to find the plugin-specific settings.

Alternative connection method with tsh

You may use the tsh client to connect without any modifications to your ~/.ssh/config with:

tsh ssh hpc-login

or

tsh ssh ecs-login

The target platforms you can connect to can be listed with

tsh ls

scp file transfers through the tsh client are also possible. For example, to transfer a file from your computer to your HOME in hpc-login:

tsh scp myfile hpc-login:

If you choose this method and do not configure your ~/.ssh/config, you will not be able to use other tools that rely on a standard SSH connection, such as ssh itself, scp, rsync or VSCode.


Troubleshooting

If you cannot login to teleport or connect via SSH and you are not able to understand why, please raise an issue to our ECMWF Support portal and sending us the output of the commands:

tsh version
tsh login --proxy=jump-17.ecmwf.int
ssh -V
ssh -v ecs-login

You should also include information about your computer (Operating system) to help us narrow down the problem.