Accessing an Arvados VM with SSH - Unix Environments

This document is for accessing an Arvados VM using SSH keys in Unix environments (Linux, OS X, Cygwin). If you would like to access VM through your browser, please visit the Accessing an Arvados VM with Webshell page. If you are using a Windows environment, please visit the Accessing an Arvados VM with SSH – Windows 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:

Getting your SSH key
Adding your key to Arvados Workbench
Using SSH to log into an Arvados VM instance

Getting your SSH key

Generate a key using ssh-keygen

Start by opening a terminal window. Check if you have an existing public key:

$ ls ~/.ssh/id_rsa.pub

If the file id_rsa.pub exists, then you may use your existing key. Copy the contents of ~/.ssh/id_rsa.pub onto the clipboard (this is your public key). You can skip the rest of this section and proceed by adding your key to the Arvados Workbench.

If there is no file ~/.ssh/id_rsa.pub, you must generate a new key. Use ssh-keygen to do this:

$ ssh-keygen -t rsa -C "you@example.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/example/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

-t specifies the key type (must be “rsa”)
-C specifies a comment (to remember which account the key is associated with)

We strongly recommend that you protect your key with a passphrase. This means that when the key is used, you will be required to enter the passphrase. However, unlike logging into remote system using a password, the passphrase is never sent over the network, it is only used to decrypt your private key.

Display the contents of ~/.ssh/id_rsa.pub (this is your public key) using cat and then copy it onto the clipboard:

$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1ycEDoNotUseExampleKeyDoNotUseExampleKeyDoNotUseExampleKeyDoNotUse9lmzkpBq983bQradKGT3LuKda9QOGe8MatI6wzSrJLSGhHm3hk6D8OWWUG4SneuCtKIk2bH0pgBj1G29+uzDIez90WzfCTZKbz4RcVQmPkowSSUAQDwb0ffwvRDhCgcJ1loT1wQAJzqJmljQ7xEYaCOIMqnfYE0lX7B3MSvCV6Ie2rWL33YecLp48LVtqiCOZU4XRyO8RSDFRFLVW+mjkLirwtDHZCRtORScaIEN0jw51p+T+9X5iA9QH/Mn+xlgk7fCgH+JtpBj808N/Qds2Gpff+Kb6ulUrVVfMK6L you@example.com

Now you can set up ssh-agent (next) or proceed with adding your key to the Arvados Workbench.

Set up ssh-agent (recommended)

If you find you are entering your passphrase frequently, you can use ssh-agent to manage your credentials. Use ssh-add -l to test if you already have ssh-agent running:

$ ssh-add -l

If you get the error “Could not open a connection to your authentication agent” you will need to run ssh-agent with the following command:

$ eval $(ssh-agent -s)

ssh-agent -s prints out values for environment variables SSH_AUTH_SOCK and SSH_AGENT_PID and then runs in the background. Using “eval” on the output as shown here causes those variables to be set in the current shell environment so that subsequent calls to SSH can discover how to access the agent process.

After running ssh-agent, or if ssh-add -l prints “The agent has no identities”, add your key using the following command. The passphrase to decrypt the key is the same used to protect the key when it was created with ssh-keygen:

$ ssh-add
Enter passphrase for /home/example/.ssh/id_rsa:
Identity added: /home/example/.ssh/id_rsa (/home/example/.ssh/id_rsa)

When everything is set up, ssh-add -l should yield output that looks something like this:

$ ssh-add -l
2048 eb:fa:15:f2:44:26:95:58:37:37:f4:aa:ff:ee:c2:85 you@example.com (RSA)

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

Adding your key to Arvados Workbench

From the Workbench dashboard

In the Workbench top navigation menu, click on the dropdown menu icon to access the user settings menu and click on the menu item SSH keys to go to the SSH keys page. Click on the + Add new SSH key button in this page. This will open a popup as shown in this screenshot:

Paste your public key into the text area labeled Public Key, and click on the Submit button. You are now ready to log into an Arvados VM.

To see a list of virtual machines that you have access to and determine the name and login information, click on the dropdown menu icon in the upper right corner of the top navigation menu to access the user settings menu and click on the menu item Virtual machines to go to the Virtual machines page. This page lists the virtual machines you can access. The Host name column lists the name of each available VM. The Login name column will have a list of comma separated values of the form you. In this guide the hostname will be shell and the login will be you. Replace these with your hostname and login name as appropriate.

Connecting to the virtual machine

Use the following command to connect to the shell VM instance as you. Replace you@shell at the end of the following command with your login and hostname from Workbench:

$ ssh -o "ProxyCommand ssh -a -x -p2222 turnout@switchyard.pirca.arvadosapi.com shell" -A -x you@shell

This command does several things at once. You usually cannot log in directly to virtual machines over the public Internet. Instead, you log into a “switchyard” server and then tell the switchyard which virtual machine you want to connect to.

-o "ProxyCommand ..." configures SSH to run the specified command to create a proxy and route your connection through it.
-a tells SSH not to forward your ssh-agent credentials to the switchyard.
-x tells SSH not to forward your X session to the switchyard.
-p2222 specifies that the switchyard is running on non-standard port 2222.
turnout@switchyard.pirca.arvadosapi.com specifies the user (turnout) and hostname (switchyard.pirca.arvadosapi.com) of the switchyard server that will proxy our connection to the VM.
shell is the name of the VM that we want to connect to. This is sent to the switchyard server as if it were an SSH command, and the switchyard server connects to the VM on our behalf.
After the ProxyCommand section, we repeat -x to disable X session forwarding to the virtual machine.
-A specifies that we want to forward access to ssh-agent to the VM.
Finally, you@shell specifies your login name and repeats the hostname of the VM. The username can be found in the logins column in the VMs Workbench page, discussed in the previous section.

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

Configuration (recommended)

The command line above is cumbersome, but you can configure SSH to remember many of these settings. Add this text to the file .ssh/config in your home directory (create a new file if .ssh/config doesn’t exist):

Host *.arvados
  ProxyCommand ssh -a -x -p2222 turnout@switchyard.pirca.arvadosapi.com $SSH_PROXY_FLAGS %h
  User you
  ForwardAgent yes
  ForwardX11 no

This will recognize any host ending in “.arvados” and automatically apply the proxy, user and forwarding settings from the configuration file, allowing you to log in with a much simpler command:

$ ssh shell.arvados