SSH Access to Virtual Machines using the EIDF-Gateway Jump Host

The EIDF-Gateway is an SSH gateway suitable for accessing EIDF Services via a console or terminal. As the gateway cannot be 'landed' on, a user can only pass through it and so the destination (the VM IP) has to be known for the service to work. Users connect to their VM through the jump host using their given accounts. You will require three things to use the gateway:

1. A user within a project allowed to access the gateway and a password set.
2. An SSH-key linked to this account, used to authenticate against the gateway.
3. Have MFA setup with your project account via SAFE.

Steps to meet all of these requirements are explained below.

Generating and Adding an SSH Key

In order to make use of the EIDF-Gateway, your EIDF account needs an SSH-Key associated with it. If you added one while creating your EIDF account, you can skip this step.

Check for an existing SSH Key

To check if you have an SSH Key associated with your account:

1. Login to the Portal
2. Select 'Your Projects'
3. Select your project name
4. Select your username

If there is an entry under 'Credentials', then you're all setup. If not, you'll need to generate an SSH-Key, to do this:

Generate a new SSH Key

1. Open a new window of whatever terminal you will use to SSH to EIDF.

2. Generate a new SSH Key:

   ssh-keygen
   

3. It is fine to accept the default name and path for the key unless you manage a number of keys.

4. Press enter to finish generating the key

Adding the new SSH Key to your account via the Portal

1. Login into the Portal
2. Select 'Your Projects'
3. Select the relevant project
4. Select your username
5. Select the plus button under 'Credentials'
6. Select 'Choose File' to upload the PUBLIC (.pub) ssh key generated in the last step, or open the .pub file you just created and copy its contents into the text box.
7. Click 'Upload Credential' - it should look something like this:

Adding a new SSH Key via SAFE

This should not be necessary for most users, so only follow this process if you have an issue or have been told to by the EPCC Helpdesk. If you need to add an SSH Key directly to SAFE, you can follow this guide. However, select your '[username]@EIDF' login account, not 'Archer2' as specified in that guide.

Enabling MFA via the Portal

A multi-factor Time-Based One-Time Password is now required to access the SSH Gateway.

To enable this for your EIDF account:

1. Login to the portal.
2. Select 'Projects' then 'Your Projects'
3. Select the project containing the account you'd like to add MFA to.
4. Under 'Your Accounts', select the account you would like to add MFA to.
5. Select 'Set MFA Token'
6. Within your chosen MFA application, scan the QR Code or enter the key and add the token.
7. Enter the code displayed in the app into the 'Verification Code' box and select 'Set Token'
8. You will be redirected to the User Account page and a green 'Added MFA Token' message will confirm the token has been added successfully.

Note

TOTP is only required for the SSH Gateway, not to the VMs themselves, and not through the VDI.
An MFA token will have to be set for each account you'd like to use to access the EIDF SSH Gateway.

Using the SSH-Key and TOTP Code to access EIDF - Windows and Linux

1. From your local terminal, import the SSH Key you generated above:
   ssh-add /path/to/ssh-key

2. This should return "Identity added [Path to SSH Key]" if successful. You can then follow the steps below to access your VM.

Accessing From MacOS/Linux

OpenSSH is installed on Linux and MacOS usually by default, so you can access the gateway natively from the terminal.

Ensure you have created and added an ssh key as specified in the 'Generating and Adding an SSH Key' section above, then run the commands below:

ssh-add /path/to/ssh-key
ssh -J [username]@eidf-gateway.epcc.ed.ac.uk [username]@[vm_ip]

For example:

ssh-add ~/.ssh/keys/id_ed25519
ssh -J alice@eidf-gateway.epcc.ed.ac.uk alice@10.24.1.1

Info

If the ssh-add command fails saying the SSH Agent is not running, run the below command:

eval `ssh-agent`

Then re-run the ssh-add command above.

The -J flag is use to specify that we will access the second specified host by jumping through the first specified host.

You will be prompted for a 'TOTP' code upon successful public key authentication to the gateway. At the TOTP prompt, enter the code displayed in your MFA Application.

Accessing from Windows

Windows will require the installation of OpenSSH-Server to use SSH. Putty or MobaXTerm can also be used but won’t be covered in this tutorial.

Installing and using OpenSSH

1. Click the ‘Start’ button at the bottom of the screen
2. Click the ‘Settings’ cog icon
3. Select 'System'
4. Select the ‘Optional Features’ option at the bottom of the list
5. If ‘OpenSSH Client’ is not under ‘Installed Features’, click the ‘View Features’ button
6. Search ‘OpenSSH Client’
7. Select the check box next to ‘OpenSSH Client’ and click ‘Install’

Accessing EIDF via a Terminal

1. Open either Powershell or the Windows Terminal

2. Import the SSH Key you generated above:

   ssh-add \path\to\sshkey
   
   For Example:
   ssh-add .\.ssh\id_ed25519
   

3. This should return "Identity added [Path to SSH Key]" if successful. If it doesn't, run the following in Powershell:

   Get-Service -Name ssh-agent | Set-Service -StartupType Manual
   Start-Service ssh-agent
   ssh-add \path\to\sshkey
   

4. Login by jumping through the gateway.

   ssh -J [EIDF username]@eidf-gateway.epcc.ed.ac.uk [EIDF username]@[vm_ip]
   
   For Example:
   ssh -J alice@eidf-gateway.epcc.ed.ac.uk alice@10.24.1.1
   

You will be prompted for a 'TOTP' code upon successful public key authentication to the gateway. At the TOTP prompt, enter the code displayed in your MFA Application.

Accessing with PuTTY

Creating the Gateway Config

1. Install PuTTY v0.81 or greater and launch it
2. From the default 'Session' menu, input the gateway URL: eidf-gateway.epcc.ed.ac.uk
3. Set the port to 22
4. Naviagte to 'Connection' > 'SSH' > 'Auth' > 'Credentials'
5. Specify your gateway private key by selecting the 'Browse' button next to 'Private key file for authentication'
6. Select the path to your SSH key for your gateway account
7. Return to the main 'Session' tab and in the empty box under 'Saved Sessions' input a memorable name, for example 'eidf-gateway'
8. Click Save

Adding a client/VM config

Now we can create a config session for a VM which can be connected to through the gateway

1. From the 'Sessions' tab, select 'Default Settings' in the 'Saved Settings' box and select 'Load'
2. Input the hostname/IP of the VM, e.g. 10.24.X.Y.
3. Ensure the port is 22
4. From the navigation menu, move to 'Connection' > 'Proxy'
5. Select 'Proxy Type' at the top to 'SSH to proxy and use port forward'. Note this doesn't exist in older versions of PuTTY
6. Under 'Proxy Hostname', set the name of the gateway session you created above. In the SOP this was called 'eidf-gateway'
7. Set the Port to 22
8. Put your eidf-gateway username into the 'Username' box
9. Set 'Do DNS name lookup at proxy end' to 'Yes'
10. Navigate to 'Connection' > 'SSH' > 'Auth' > 'Credentials' and select 'Browse' next to the 'Private key file for authentication' box
11. Select your private key for your VM account (this may be the same as the gateway)
12. Navigate to 'Connection' > 'Data'
13. Put your VM username into the 'Auto-Login username' box
14. Return to the original 'Sesstion' tab
15. Put the VM name or a nickname into the 'Saved Settings' name box
16. Select 'Save'
17. Select 'Open' and you should connect to your VM.

SSH Aliases

You can use SSH Aliases to access your VMs with a single command.

1. Create a new entry for the EIDF-Gateway in your ~/.ssh/config file. Using the text editor of your choice (vi used as an example), edit the .ssh/config file:

   vi ~/.ssh/config
   

2. Insert the following lines:

   Host eidf-gateway
     Hostname eidf-gateway.epcc.ed.ac.uk
     User <eidf project username>
     IdentityFile /path/to/ssh/key
   

   For example:

   Host eidf-gateway
     Hostname eidf-gateway.epcc.ed.ac.uk
     User alice
     IdentityFile ~/.ssh/id_ed25519
   

3. Save and quit the file.

4. Now you can ssh to your VM using the below command:

   ssh -J eidf-gateway [EIDF username]@[vm_ip] -i /path/to/ssh/key
   

   For Example:

   ssh -J eidf-gateway alice@10.24.1.1 -i ~/.ssh/id_ed25519
   

5. You can add further alias options to make accessing your VM quicker. For example, if you use the below template to create an entry below the EIDF-Gateway entry in ~/.ssh/config, you can use the alias name to automatically jump through the EIDF-Gateway and onto your VM:

   Host <vm name/alias>
     HostName 10.24.VM.IP
     User <vm username>
     IdentityFile /path/to/ssh/key
     ProxyCommand ssh eidf-gateway -W %h:%p
   

   For Example:

   Host demo
     HostName 10.24.1.1
     User alice
     IdentityFile ~/.ssh/id_ed25519
     ProxyCommand ssh eidf-gateway -W %h:%p
   

6. Now, by running ssh demo your ssh agent will automatically follow the 'ProxyCommand' section in the 'demo' alias and jump through the gateway before following its own instructions to reach your VM.
   
   Note for this setup, if your key is RSA, you will need to add the following line to the bottom of the 'demo' alias: HostKeyAlgorithms +ssh-rsa

Info

This has added an 'Alias' entry to your ssh config, so whenever you ssh to 'eidf-gateway' your ssh agent will automatically fill the hostname, your username and ssh key. This method allows for a much less complicated ssh command to reach your VMs.
You can replace the alias name with whatever you like, just change the 'Host' line from saying 'eidf-gateway' to the alias you would like.
The -J flag is use to specify that we will access the second specified host by jumping through the first specified host.

sudo, Password Setting and Password Resets

You do not have to set a password to log into virtual machines. However, if you have been given sudo permission, you will need to set a password to be able to make use of sudo. You can set (or reset) a password using the web form in the EIDF Portal following the instructions in Set or change the password for a user account.