doc/user/getting_started/ssh-access-unix.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Accessing an Arvados VM with SSH - Unix Environments
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 This document is for accessing an Arvados VM using SSH keys in Unix-like environments (Linux, macOS, Cygwin, Windows Subsystem for Linux). If you would like to access VM through your browser, please visit the "Accessing an Arvados VM with Webshell":vm-login-with-webshell.html page. If you are using a Windows environment, please visit the "Accessing an Arvados VM with SSH - Windows Environments":ssh-access-windows.html page.
  13
  14 {% include 'ssh_intro' %}
  15
  16 h1(#gettingkey). Getting your SSH key
  17
  18 h3(#unix). Generate a key using ssh-keygen
  19
  20 Start by opening a terminal window.  Check if you have an existing public key:
  21
  22 notextile. <pre><code>$ <span class="userinput">ls ~/.ssh/id_rsa.pub</span></code></pre>
  23
  24 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.":#workbench
  25
  26 If there is no file @~/.ssh/id_rsa.pub@, you must generate a new key.  Use @ssh-keygen@ to do this:
  27
  28 <notextile>
  29 <pre><code>$ <span class="userinput">ssh-keygen -t rsa -C "you@example.com"</span>
  30 Generating public/private rsa key pair.
  31 Enter file in which to save the key (/home/example/.ssh/id_rsa):
  32 Enter passphrase (empty for no passphrase):
  33 Enter same passphrase again:
  34 </code></pre>
  35 </notextile>
  36
  37 * @-t@ specifies the key type (must be "rsa")
  38 * @-C@ specifies a comment (to remember which account the key is associated with)
  39
  40 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.
  41
  42 Display the contents of @~/.ssh/id_rsa.pub@ (this is your public key) using @cat@ and then copy it onto the clipboard:
  43
  44 <notextile>
  45 <pre><code>$ <span class="userinput">cat ~/.ssh/id_rsa.pub</span>
  46 ssh-rsa AAAAB3NzaC1ycEDoNotUseExampleKeyDoNotUseExampleKeyDoNotUseExampleKeyDoNotUse9lmzkpBq983bQradKGT3LuKda9QOGe8MatI6wzSrJLSGhHm3hk6D8OWWUG4SneuCtKIk2bH0pgBj1G29+uzDIez90WzfCTZKbz4RcVQmPkowSSUAQDwb0ffwvRDhCgcJ1loT1wQAJzqJmljQ7xEYaCOIMqnfYE0lX7B3MSvCV6Ie2rWL33YecLp48LVtqiCOZU4XRyO8RSDFRFLVW+mjkLirwtDHZCRtORScaIEN0jw51p+T+9X5iA9QH/Mn+xlgk7fCgH+JtpBj808N/Qds2Gpff+Kb6ulUrVVfMK6L you@example.com
  47 </code></pre>
  48 </notextile>
  49
  50 Now you can set up @ssh-agent@ (next) or proceed with "adding your key to the Arvados Workbench.":#workbench
  51
  52 h3. Set up ssh-agent (optional)
  53
  54 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:
  55
  56 notextile. <pre><code>$ <span class="userinput">ssh-add -l</span></code></pre>
  57
  58 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:
  59
  60 notextile. <pre><code>$ <span class="userinput">eval $(ssh-agent -s)</span></code></pre>
  61
  62 @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.
  63
  64 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@:
  65
  66 <notextile>
  67 <pre><code>$ <span class="userinput">ssh-add</span>
  68 Enter passphrase for /home/example/.ssh/id_rsa:
  69 Identity added: /home/example/.ssh/id_rsa (/home/example/.ssh/id_rsa)
  70 </code></pre>
  71 </notextile>
  72
  73 When everything is set up, @ssh-add -l@ should yield output that looks something like this:
  74
  75 <notextile>
  76 <pre><code>$ <span class="userinput">ssh-add -l</span>
  77 2048 eb:fa:15:f2:44:26:95:58:37:37:f4:aa:ff:ee:c2:85 you@example.com (RSA)
  78 </code></pre>
  79 </notextile>
  80
  81 {% include 'ssh_addkey' %}
  82
  83 h3. Connecting directly
  84
  85 If the VM is available on the public Internet (or you are on the same private network as the VM) you can connect directly with @ssh@.  You can probably copy-and-paste the text from *Command line* column directly into a terminal.
  86
  87 Use the following example command to connect as _you_ to the _shell.ClusterID.example.com_ VM instance.  Replace *<code>you@shell.ClusterID.example.com</code>* at the end of the following command with your *login* and *hostname* from Workbench.
  88
  89 notextile. <pre><code>$ <span class="userinput">ssh <b>you@shell.ClusterID.example.com</b></span></code></pre>
  90
  91 h3. Connecting through switchyard
  92
  93 Some Arvados installations use "switchyard" to isolate shell VMs from the public Internet.
  94
  95 Use the following example command to connect to the _shell_ VM instance as _you_.  Replace *<code>you@shell</code>* at the end of the following command with your *login* and *hostname* from Workbench:
  96
  97 notextile. <pre><code>$ <span class="userinput">ssh -o "ProxyCommand ssh -p2222 turnout@switchyard.ClusterID.example.com -x -a <b>shell</b>" -x <b>you@shell</b></span></code></pre>
  98
  99 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.
 100
 101 * @-o "ProxyCommand ..."@ configures SSH to run the specified command to create a proxy and route your connection through it.
 102 * @-p2222@ specifies that the switchyard is running on non-standard port 2222.
 103 * <code>turnout@switchyard.{{ site.arvados_api_host }}</code> specifies the user (@turnout@) and hostname (@switchyard.{{ site.arvados_api_host }}@) of the switchyard server that will proxy our connection to the VM.
 104 * @-x@ tells SSH not to forward your X session to the switchyard.
 105 * @-a@ tells SSH not to forward your ssh-agent credentials to the switchyard.
 106 * *@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.
 107 * After the ProxyCommand section, we repeat @-x@ to disable X session forwarding to the virtual machine.
 108 * Finally, *<code>you@shell</code>* 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.
 109
 110 You should now be able to log into the Arvados VM and "check your environment.":check-environment.html
 111
 112 h4. Configuration (recommended)
 113
 114 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):
 115
 116 <notextile>
 117 <pre><code class="userinput">Host *.{{ site.arvados_cluster_uuid }}
 118   TCPKeepAlive yes
 119   ServerAliveInterval 60
 120   ProxyCommand ssh -p2222 turnout@switchyard.{{ site.arvados_api_host }} -x -a $SSH_PROXY_FLAGS %h
 121   User <b>you</b>
 122 </code></pre>
 123 </notextile>
 124
 125 This will recognize any host ending in ".{{ site.arvados_cluster_uuid }}" and automatically apply the proxy, user and forwarding settings from the configuration file, allowing you to log in with a much simpler command:
 126
 127 notextile. <pre><code>$ <span class="userinput">ssh <b>shell</b>.{{ site.arvados_cluster_uuid }}</span></code></pre>
 128
 129 You should now be able to log into the Arvados VM and "check your environment.":check-environment.html