Accessing an Arvados VM with SSH - Windows Environments

This document is for accessing an Arvados VM using SSH keys in Windows environments using PuTTY. If you would like to use to access VM through your browser, please visit the Accessing an Arvados VM with Webshell page. If you are using a Unix-like environment (Linux, macOS, Cygwin, or Windows Subsystem for Linux), please visit the Accessing an Arvados VM with SSH – Unix Environments page.

Arvados requires a public SSH key in order to securely log in to an Arvados VM instance, or to access an Arvados Git repository. The three sections below help you get started:

1. Getting your SSH key
2. Adding your key to Arvados Workbench
3. Using SSH to log into an Arvados VM instance

Getting your SSH key

(Note: If you are using the SSH client that comes with Cygwin or Windows Subsystem for Linux (WSL) please use instructions found in the Accessing an Arvados VM with SSH – Unix Environments page.)

We will be using PuTTY to connect to Arvados. PuTTY is a free (MIT-licensed) Win32 Telnet and SSH client. PuTTY includes all the tools a Windows user needs to create private keys and make SSH connections to your virtual machines in the Arvados Cloud.

You can download PuTTY from its Web site. Note that you should download the installer or .zip file with all of the PuTTY tools (PuTTYtel is not required).

If you downloaded the zip file, extract it to the location you wish to install the PuTTY applications. This document assumes that you installed PuTTY in the default directory under C:\Program Files\ or C:\Program Files (x86)\ (if you are using a 64 bit operating system).

Step 1 – Adding PuTTY to the PATH

1. After downloading PuTTY and installing it, you should have a PuTTY folder in C:\Program Files\ or C:\Program Files (x86)\ (if you are using a 64 bit operating system).
2. Open the Control Panel.
3. Select Advanced System Settings, and choose Environment Variables.
   If you are using newer systems like Windows 10, you may use the following to open Advanced System Settings. Open Control Panel. Click on System and Security. Click on System. Click on Advanced system settings and choose Environment Variables…
4. Under system variables, find and edit PATH.
5. If you installed PuTTY in C:\Program Files\PuTTY\, add the following to the end of PATH:
   ;C:\Program Files\PuTTY
   If you installed PuTTY in C:\Program Files (x86)\PuTTY\, add the following to the end of PATH:
   ;C:\Program Files (x86)\PuTTY
6. Click through the OKs to close all the dialogs you’ve opened.

Step 2 – Creating a Public Key

1. Start PuTTYgen from the Start Menu or the folder where it was installed.
2. At the bottom of the window, make sure the ‘Number of bits in a generated key’ field is set to 4096.
3. Click Generate and follow the instructions to generate a key.
4. Click the Save public key button.
5. Click the Save private key button (we recommend using a strong passphrase).
6. Select the text of the Public Key and copy it to the clipboard.

Step 3 – Set up Pageant

Pageant is a PuTTY utility that manages your private keys so is not necessary to enter your private key passphrase every time you make a new SSH connection.

1. Start Pageant from the Start Menu or the folder where it was installed.
2. Pageant will now be running in the system tray. Click the Pageant icon to configure.
3. Choose Add Key and add the private key which you created in the previous step.

You may now proceed to adding your key to the Arvados Workbench.

Adding your key to Arvados Workbench

In the Workbench top navigation menu, click on the dropdown menu icon to access the Account Management menu. Then, click on the menu item Ssh keys to go to the SSH keys page. Click on the + ADD NEW SSH KEY button in the upper-right on that page. You will see a popup as shown in this screenshot:

Paste your public key into the text area labeled Public Key, and click on the ADD NEW SSH KEY button in lower-right. You are now ready to log into an Arvados VM.

Using SSH to log into an Arvados VM

To see a list of virtual machines that you have access to, click on the dropdown menu icon in the upper right corner of the top navigation menu to access the Account Management menu. Then, click on the menu item Virtual Machines.

You will then see a page that lists the virtual machines you can access. The Host name column lists the name of each available VM. The Login name column lists your login name on that VM. The Command line column provides a sample ssh command.

At the bottom of the page there may be additional instructions for connecting your specific Arvados instance. If so, follow your site-specific instructions. If there are no site-specific instructions, you can probably connect directly with ssh.

The following are generic instructions. In these examples, the login name will be you and the host domain will be ClusterID.example.com. Replace these with your login name and hostname as appropriate.

Initial configuration

Connecting directly

1. Open PuTTY from the Start Menu.
2. On the Session screen set the Host Name (or IP address) to “shell.ClusterID.example.com”, which is the hostname listed in the Virtual Machines page.
3. On the Session screen set the Port to “22”.
4. On the Connection → Data screen set the Auto-login username to the username listed in the Login name column on the Arvados Workbench Virtual machines_ page.
5. Return to the Session screen. In the Saved Sessions box, enter a name for this configuration and click Save.

Connecting through switchyard

1. Open PuTTY from the Start Menu.
2. On the Session screen set the Host Name (or IP address) to “shell”, which is the hostname listed in the Virtual Machines page.
3. On the Session screen set the Port to “22”.
4. On the Connection → Data screen set the Auto-login username to the username listed in the Login name column on the Arvados Workbench Virtual machines_ page.
5. On the Connection → Proxy screen set the Proxy Type to “Local”.
6. On the Connection → Proxy screen in the “Telnet command, or local proxy command” box enter:
   plink -P 2222 turnout@switchyard.pirca.arvadosapi.com %host
   Make sure there is no newline at the end of the text entry.
7. Return to the Session screen. In the Saved Sessions box, enter a name for this configuration and click Save.

Note: We recommend you do not delete the “Default” Saved Session.

Connecting to the VM

1. Open PuTTY from the Start Menu.
2. Click on the Saved Session name you created in the previous section.
3. Click Load to load those saved session settings.
4. Click Open to open the SSH window at the command prompt. You will now be logged into your virtual machine.

Note: If you see a hung PuTTY terminal window with no further action: open a new Command Prompt window using the Windows → Start menu and type plink -P 2222 turnout@switchyard.pirca.arvadosapi.com shell in it. Please make sure to replace shell with the hostname listed in the Virtual Machines page. Hit enter and type y when prompted to cache the session state. Go back and start PuTTY session using the start menu button.

You should now be able to log into the Arvados VM and check your environment.

---

Previous: Accessing an Arvados VM with SSH - Unix Environments Next: Workbench 2 migration