Versions Compared

Old Version 140

changes.mady.by.user Oliver Gorwits

Saved on

compared with

New Version 141

changes.mady.by.user Oliver Gorwits

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Teleport is software which provides an SSH Jump Host (or Bastion host) service in a secure, modern way, with support for role-based access control and single sign-on.

Warning

Teleport is meant to be the future replacement for the ecAccess SSH service. Both services are currently operational and can be widely used at this point, but note that only Teleport will be available for the new data centre in Bologna.


Note

Add the following to your "~/.ssh/known_hosts" file (all on one line):

@cert-authority shell.ecmwf.int ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCg7+Q3cfE2K+tuH+lWkT3qXoZAgk35ZSRvgMTDiOiIofKRTylC3lQLt8tTaS70iiqyATOMgZHEzcLRdIe3hfB5riWyCSxRGLYGEsUy+ESS7aFz54fPlFbu1hKt6cnTFRzWnTIiJ4Fcq3CYVh5XLQm/TNF4RxUwxgqkSV1hQitahtGcadlgjTCtiyIEOE3BkY9OBdsjulYGnVaq/ODkdkEcVof79gzS8iSn3eGMhiWpiXmd7F96o/2xtn2mpuC870Dc5PQekEmX+xo4MdlQMDrxPf2GZ9Z0JKaKR4+EGsHJab4X/LOL4B+2qT8wtmUKHqeKGNYhvtulVGOi88dUQs9t


Tip

Please report any feedback or issues to our servicedesk@ecmwf.int.

Table of Contents
maxLevel1

Overview

The Teleport service provides:

  • Single SSH hop from client systems anywhere on the internet to servers inside ECMWF (ecGate, HPC, etc)
  • Re-authentication required only every 12 hours (once per day)
  • Integration with standard tools such as the OpenSSH ssh client, scp, and ssh-agent
  • Web-SSH interface for in-browser terminal access, with scp
  • X11 and Port forwarding

The single sign-on step is performed using an application called "tsh", every 12 hours.

After that you use standard ssh or scp to connect to systems inside ECMWF.

Alternatively you can have simple terminal access in a web browser. 

Downloading tsh 

The tsh application is required to perform user authentication once every 12 hours.

tsh is open source, very portable, and has minimal dependencies.

The binary is available for Linux 32-bit, 64-bit, and ARM, as well as Windows 64-bit and a signed package for MacOS.

MacOS users can also use homebrew for installation (brew install teleport).

User Authentication

Once every 12 hours, you will need to refresh your tokens with the tsh command, through your web browser.

Info

SSH connections can remain active for longer than 12 hours, but new ones will require re-authentication.

First Time

Run tsh, giving the location of our gateway:

Code Block
languagebash
themeMidnight
tsh login --proxy=shell.ecmwf.int:443

Your default web browser will open and you should login with your email address, ECMWF password, and then HID (ActivID) Token code.

Info

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

Subsequent Occasions

Code Block
languagebash
themeMidnight
tsh login

Connecting to hosts through the gateway

Info

Windows users should skip to our Guide for Windows SSH to ECMWF.

OpenSSH 7.3 or later has a simple command line option to connect via our gateway (shell.ecmwf.int) to the destination-host:

Code Block
languageyml
ssh -J username@shell.ecmwf.int username@destination-host

For example, if your username is ab0 and you wish to connect to ecgate:

Code Block
languagebash
themeMidnight
ssh -J ab0@shell.ecmwf.int ab0@ecgate

The OpenSSH configuration setting for this is named ProxyJump:

Code Block
languagebash
Host ecgate
  User ab0
  ProxyJump ab0@shell.ecmwf.int

See the Legacy Configuration note below if your ssh client is older than 7.3.

If your connection fails after working for some time, it could be because your tokens have expired. You can check them:

Code Block
languagebash
$ tsh status
> Profile URL:  https://shell.ecmwf.int:443
  Logged in as: firstname.lastname@ecmwf.int
  Cluster:      shell.ecmwf.int
  Roles:        *
  Logins:       ab0
  Valid until:  2020-06-22 23:26:30 +0100 BST [EXPIRED]
  Extensions:   permit-X11-forwarding, permit-agent-forwarding, permit-port-forwarding, permit-pty

Destination Hosts available

The hosts directly available through the Teleport gateway are:

  • ECGATE (interactive node only)
  • CCA and CCB login nodes
  • HPC2020 TEMS
Show If
groupecmwf
  • Linux VDI (both legacy OpenSUSE and CENTOS 8 beta)
  • Physical office workstations

To access any other host, the ProxyJump feature allows chaining by using a comma, like so:

Code Block
languagebash
ssh -J ab0@shell.ecmwf.int,ab0@ecgate ab0@lxc

You can also set password-less login, as below.



Show If
groupecmwf

Configuring password-less login

Info

This configuration enables single-hop ssh (using ProxyJump) to LXC or any other host.

Not required for ECGATE, CCA/CCB login nodes, Linux physical workstations, Linux VDI, or HPC2020 TEMS.

Add the Teleport certificate authority to your ~/.ssh/authorized_keys file, on the relevant system at ECMWF, e.g. ecgate, cca:

Code Block
languagebash
curl -fs https://nexus.ecmwf.int/repository/internal-teleport-configs/prod/teleport_user_ca.pub >> ~/.ssh/authorized_keys


Note

On cca/ccb, you will need to load the curl module beforehand.


Tip

This configuration will allow access to any host which mounts the same $HOME directory.


Terminal Access in a Web Browser

You can open a tabbed terminal in the web browser, with support for SCP upload and download.

Show If
groupecmwf


Info

Only available for ECGATE, CCA/CCB login nodes, Linux physical workstations, Linux VDI, and HPC2020 TEMS.



Hide If
groupecmwf


Info

Only available for ECGATE, CCA/CCB login nodes, and HPC2020 TEMS.


Browse to  http://webshell.ecmwf.int/destination-host/username (replacing destination-host and username with your selection).

For example, if your username is ab0 and you wish to connect to ecgate:

Code Block
languagebash
themeMidnight
http://webshell.ecmwf.int/ecgate/ab0


Info

The destination host should be just the short name, without "ecmwf.int".

If you open another tab inside the web terminal, use the QUICK LAUNCH box and enter "username@destination-host:22", for example ab0@ecgate:22.

Tip

The web terminal works very well to access tmux or screen running on the destination host.

Windows Clients

There are various ways to initiate SSH from Windows 10, so it depends on your system and your preferences.

Tip

We recommend using the Windows Subsystem for Linux if you can (on your own machine), followed by starting the SSH Agent and then connecting as for Linux/MacOS systems.

Alternatively, you can use:

Expand
titleMobaXterm SSH from Windows 10 (ECMWF laptop)
  1. Install MobaXterm if it is not already on your system
  2. Download tsh (you may need to instruct antivirus software to ignore the file)
  3. Start MobaXterm
  4. Login using tsh (you will always need to specify the --proxy setting)
  5. Use the following in $HOME/.ssh/config (MobaXterm's home):
Code Block
languagebash
Host ecgate
  User ab0
  ProxyCommand ssh -q -i c:/users/ab0/.tsh/keys/shell.ecmwf.int/firstname.lastname@ecmwf.int -W %h:%p ab0@shell.ecmwf.int
  IdentityFile c:/users/ab0/.tsh/keys/shell.ecmwf.int/firstname.lastname@ecmwf.int



Expand
titleNative SSH from Windows 10 (own machine)
  1. Start the Windows SSH Agent Service
  2. Download tsh (you may need to instruct antivirus software to ignore the file)
  3. Login using tsh (you will always need to specify the --proxy setting)
  4. Use an SSH config as below:
Code Block
languagebash
# Windows currently has a bug, you need the full path to ssh or you will get:
# posix_spawn: No such file or directory

Host *.ecmwf.int
  User ab0
  ProxyCommand C:\Windows\System32\OpenSSH\ssh.exe -q -W %h:%p ab0@shell.ecmwf.int

# this assumes the SSH Agent is running, otherwise add:
# Host shell.ecmwf.int
#   IdentityFile ~/.tsh/keys/shell.ecmwf.int/firstname.lastname@ecmwf.int


Tip

The Windows 10 Terminal is a decent tabbed command line interface (albeit with no X11 support).

Expand
titleNew sessions can be configured following this example


Code Block
languagejs
{
  "guid": "{717406b0-06cb-454c-a0c4-875267fa373d}", # run "[guid]::NewGuid()" in a PowerShell to generate this
  "name": "ecGate",
  "commandline": "ssh ab0@ecgate.ecmwf.int"
  "suppressApplicationTitle": true,
  "hidden": false,
  "fontSize": 10,
  "fontFace": "Fira Code",
  "cursorShape": "filledBox",
  "cursorColor": "#073642",
  "colorScheme": "Solarized Dark",
},




Other Notes

SSH Agent is required

If you have logged in but ssh fails to connect, it may be that your SSH agent is not running.

The Agent can be started and tokens refreshed this way:

Code Block
languagebash
eval $(ssh-agent -s)
tsh logout
tsh login

And this will make sure the Agent continues to run in your environment:

Code Block
languagebash
echo 'eval $(ssh-agent -s)' >> ~/.bash_profile

SCP, X11, Agent, and Port Forwarding

SCP, Agent forwarding, X11 forwarding, and Port forwarding (including SOCKS proxy), all work through the Teleport gateway.

For scp you can use the -o option:

Code Block
languagebash
scp -o ProxyJump=ab0@shell.ecmwf.int ab0@ecgate:/remote/file/path /local/file/path

X11 under macOS

Code Block
languagebash
$ brew cask install xquartz
# start xquartz app
$ export DISPLAY=:0
$ ssh -X ....

Legacy Configuration

For OpenSSH clients older than 7.3, the following configuration can be used:

Code Block
languagebash
# ~/.ssh/config file:
Host ecgate
  User ab0
  ProxyCommand /usr/bin/ssh -q -W %h:%p ab0@shell.ecmwf.int

Difficult client environments

You might not be able to download and run tsh, or access our web login service, or run the SSH Agent, from where you wish to use ssh.

Instead you can use (or copy) the identity files which tsh stores in $HOME:

Code Block
languageyml
# ~/.ssh/config file:
Host ecgate
  User ab0
  IdentityFile ~/.tsh/keys/shell.ecmwf.int/firstname.lastname@ecmwf.int
  ProxyCommand /usr/bin/ssh -q -i ~/.tsh/keys/shell.ecmwf.int/firstname.lastname@ecmwf.int -W %h:%p ab0@shell.ecmwf.int

This is a good way to access Teleport credentials via a shared file system from any host.