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. It is a replacement for the ecAccess SSH service
Warning |
---|
This service is feature complete, but not classed as operational (it is not monitored). ecAccess will continue to run in Shinfield, and this service only will be deployed in Bologna. |
...
Tip |
---|
Visit the Teams channel for this service to discuss and provide feedback! |
Overview
The Teleport used to access a number of services at ECMWF, including our Atos HPCF and ECS services. The 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 (usually once per working 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 . 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 |
---|
language | bash |
---|
theme | Midnight |
---|
|
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 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 |
---|
language | bash |
---|
theme | Midnight |
---|
|
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 |
---|
|
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 |
---|
language | bash |
---|
theme | Midnight |
---|
|
ssh -J ab0@shell.ecmwf.int ab0@ecgate |
The OpenSSH configuration setting for this is named ProxyJump
:
Code Block |
---|
|
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 |
---|
|
$ 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:
Show If |
---|
|
- Linux VDI (both legacy OpenSUSE and CENTOS 8 beta)
- Physical office workstations
|
- ECGATE (node ecgb11 only)
- HPC2020 TEMS
To access any other host, the ProxyJump
feature allows chaining by using a comma, like so:
Code Block |
---|
|
ssh -J ab0@shell.ecmwf.int,ab0@ecgate ab0@cca |
Configuring password-less login
...
Info |
---|
This configuration enables single-hop ssh to legacy OpenSuSE physical or virtual workstations, or any other host via ProxyJump. Not required for ECGATE, CENTOS 8 Linux VDI beta, or HPC2020 TEMS. |
...
Info |
---|
This configuration enables single-hop ssh to any host via ProxyJump. Not required for ECGATE or HPC2020 TEMS. |
Add the Teleport certificate authority to your ~/.ssh/authorized_keys
file:
Code Block |
---|
|
curl -fs https://nexus.ecmwf.int/repository/internal-teleport-configs/prod/teleport_user_ca.pub >> ~/.ssh/authorized_keys |
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.
Note |
---|
For hosts not supporting password-less login, you must first set up password-less login. |
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 |
---|
language | bash |
---|
theme | Midnight |
---|
|
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.
...
title | MobaXterm SSH from Windows 10 (ECMWF laptop) |
---|
- Install MobaXterm if it is not already on your system
- Download tsh (you may need to instruct antivirus software to ignore the file)
- Start MobaXterm
- Login using tsh (you will always need to specify the --proxy setting)
- Use the following in
$HOME/.ssh/config
(MobaXterm's home):
Code Block |
---|
|
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 |
...
title | Native SSH from Windows 10 (own machine) |
---|
- Start the Windows SSH Agent Service
- Download tsh (you may need to instruct antivirus software to ignore the file)
- Login using tsh (you will always need to specify the --proxy setting)
- Use an SSH config as below:
Code Block |
---|
|
# 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
|
...
The Windows 10 Terminal is a decent tabbed command line interface (albeit with no X11 support).
...
title | New sessions can be configured following this example |
---|
Here are the instructions on how to set it up depending on your platform:
Info |
---|
title | System Administrators |
---|
|
If you are a system administrator setting up access to teleport from your organisation, have a look at the Teleport SSH Access - Network requirements for additional information on how this system works and its network requirements. |
Warning |
---|
Please be aware that you must use a version of "tsh" equal to or lower than 13. We are working on removing this limitation in the very near future |
Code Block |
---|
|
{
"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 |
---|
|
eval $(ssh-agent -s)
tsh logout
tsh login |
And this will make sure the Agent continues to run in your environment:
Code Block |
---|
|
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.
X11 under macOS
Code Block |
---|
|
$ 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 |
---|
|
# ~/.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 |
---|
|
# ~/.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 |
...