These are the instructions on how to install and configure your Teleport SSH access on the native Windows Terminal or Powershell to connect to ECMWF services such as the Atos HPCF and ECS services.

Table of Contents

Demo

Here is a demonstration on how to set up Teleport to connect to our our Atos HPCF from your terminal on a Windows 10 or 11. You can find the step by step guide described below.

Installing the tsh client

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

First of all, you must download the appropriate Teleport client. We recommend using the latest Teleport service:

1. Open the zip file in your file browser
2. Drag the teleport folder inside the file and drop into the directory of your choice (the main directory for your user, for example)

3. Open a Powershell and add to the PATH variable the location of the teleport directory. For example, if you dropped it on your main user directory (C:\Users\yourusername):

   $p=[Environment]::ExpandEnvironmentVariables("%USERPROFILE%\teleport;"); if ([Environment]::GetEnvironmentVariable("Path","User") -notlike "*$p*") {setx PATH "%USERPROFILE%\teleport;%PATH%"}

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

tsh login --proxy=jump.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 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

> Profile URL:        https://jump.ecmwf.int:443
  Logged in as:       user.address@somewhere.com
  Cluster:            jump.ecmwf.int
  Roles:              
  Logins:             ecmwfusername
  Kubernetes:         disabled
  Valid until:        2022-12-13 20:54:18 +0000 GMT [valid for 4h37m0s]
  Extensions:         permit-X11-forwarding, permit-agent-forwarding, permit-port-forwarding, permit-pty

tsh login

Setup your SSH config

We strongly recommend setting up all the SSH options needed for the connection instead of passing them on the command line.

1. Open the File Explorer and navigate to C:\Users\yourwindowsuser\
2. If you have a directory called  ".ssh" directory, go inside. If not, you may create it with clicking on "New Folder"
3. Inside the .ssh directory, check if there is a file called "config".
   1. If config exist, open it with your favourite editor, such as notepad or vscode.
   2. If config does not exist, you can open your favourite editor such as notepad or vscode to create the file and save it later

4. Add the snipped below in the file you opened. You should replace ecmwfusername by your registered ECMWF user and user.address@somewhere.com  by your registered email address at ECMWF.
   

   Updating from a previous jump service

   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. 

   SSH config snippet

   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-* 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

   SSH config snippet

   Host jump.ecmwf.int a?-* a??-* hpc-* hpc2020-* ecs-* ecinteractive*
     User ecmwfusername 
     IdentityFile ~/.tsh/keys/jump.ecmwf.int/user.address@somewhere.com
     CertificateFile ~/.tsh/keys/jump.ecmwf.int/user.address@somewhere.com-ssh/jump.ecmwf.int-cert.pub
     HostKeyAlgorithms +ssh-rsa*,rsa-sha2-512
     PubkeyAcceptedKeyTypes +ssh-rsa*
     ServerAliveInterval 60
     TCPKeepAlive yes
   
   Host a?-* a??-* hpc-* hpc2020-* ecs-* ecinteractive*
     ProxyJump jump.ecmwf.int

   
   

   Not sure about username and email?

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

5. Save the file. If you are creating the file from scratch, make sure you save it under C:\Users\yourwindowsuser\.ssh and with the name "config", including the double quotes. The file must not have any extension.

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.

tsh login

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

tsh version
tsh login --proxy=jump.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.