cd2af2179d4b874b60a9fe11723685917b24a046
[arvados.git] / doc / user / ssh-access.textile
1 ---
2 layout: default
3 navsection: userguide
4 title: Accessing Arvados over ssh
5 navorder: 2
6 ---
7
8 h1. Accessing Arvados over ssh
9
10 Arvados requires a public @ssh@ key in order to securely log in to an Arvados VM instance, or to access an Arvados @git@ repository.
11
12 This document is divided up into three sections.
13
14 # "Getting your ssh key":#gettingkey
15 # "Adding your key to Arvados Workbench":#workbench
16 # "Using ssh to log into an Arvados VM instance":#login
17
18 h1(#gettingkey). Getting your ssh key
19
20 This section consists of two sets of instructions, depending on whether you will be logging in using a "Unix":#unix (Linux, OS X, Cygwin) or "Windows":#windows client.
21
22 h2(#unix). Unix: Using ssh-keygen
23
24 Start by opening a terminal window.  Check if you have an existing public key:
25
26 <pre>
27  $ ls ~/.ssh/id_rsa.pub
28 </pre>
29
30 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 and proceed to "adding your key to the Arvados Workbench":#workbench .
31
32 If there is no file @~/.ssh/id_rsa.pub@, you must generate a new key.  Use ssh-keygen to do this:
33
34 <pre>
35  $ ssh-keygen -t rsa -C "you@example.com"
36  Generating public/private rsa key pair.
37  Enter file in which to save the key (/home/example/.ssh/id_rsa):
38  Enter passphrase (empty for no passphrase):
39  Enter same passphrase again:
40 </pre>
41
42 * @-t@ specifies the key type (must be "rsa")
43 * @-C@ specifies a comment (to remember which account the key is associated with)
44
45 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.
46
47 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:
48
49 <pre>
50  $ ssh-add -l
51 </pre>
52
53 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:
54
55 <pre>
56  $ eval $(ssh-agent -s)
57 </pre>
58
59 * @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 @ssh-agent@ daemon.
60
61 After running @ssh-agent@, or if @ssh-add -l@ prints "The agent has no identities", then you will need to 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@: 
62
63 <pre>
64  $ ssh-add
65  Enter passphrase for /home/example/.ssh/id_rsa:
66  Identity added: /home/example/.ssh/id_rsa (/home/example/.ssh/id_rsa)
67 </pre>
68
69 When everything is set up, @ssh-add -l@ should yield output that looks something like this:
70
71 <pre>
72  $ ssh-add -l
73  2048 eb:fa:15:f2:44:26:95:58:37:37:f4:aa:ff:ee:c2:85 you@example.com (RSA)
74 </pre>
75
76 Copy the contents of @~/.ssh/id_rsa.pub@ onto the clipboard and proceed to "adding your key to the Arvados Workbench":#workbench .
77
78 h2(#windows). Windows: Using PuTTY
79
80 (Note: if you are using the ssh client that comes with "Cygwin":http://cygwin.com you should follow the "Unix":#unix instructions).
81
82 "PuTTY":http://www.putty.org/ is a free (MIT-licensed) Win32 Telnet and SSH client. PuTTy includes all the tools a windows user needs to set up Private Keys and to set up and use SSH connections to your virtual machines in the Arvados Cloud. 
83
84 You can use PuTTY to create public/private keys, which are how you’ll ensure that that access to Arvados cloud is secure. You can also use PuTTY as an SSH client to access your virtual machine in an Arvados cloud and work with the Arvados Command Line Interface (CLI) client. 
85
86 You may download putty from "http://www.putty.org/":http://www.putty.org/ .
87
88 Note that you should download the installer or .zip file with all of the PuTTY tools (PuTTYtel is not required).
89
90 h3. Step 1 - Adding PuTTY to the PATH
91
92 # 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).  If you downloaded a zip file, extract it to the location you wish to install the PuTTY applications.
93 # Open the Control Panel.
94 # Select _Advanced System Settings_, and choose _Environment Variables_.
95 # Under system variables, find and edit @PATH@.
96 # Add the following to the end of PATH (make sure to include semi colon and quotation marks):
97 <pre>
98 ;\"C:\Program Files (x86)\PuTTY\"
99 </pre>
100 # Click through the OKs to close all the dialogs you’ve opened.
101
102 h3. Step 2 - Creating a Public Key
103
104 # Start PuTTYgen from the Start Menu or the folder where it was installed.
105 # At the bottom of the window, make sure the ‘Number of bits in a generated key’ field is set to 4096.
106 # Click Generate and follow the instructions to generate a key.
107 # Click to save the Public Key.
108 # Click to save the Private Key (we recommend using a strong passphrase) .
109 # Select the text of the Public Key and copy it to the clipboard.
110
111 h3. Step 3 - Set up Pageant
112
113 Note: Pageant is a PuTTY utility that manages your private keys so is not necessary to enter your private key passphrase every time you need to make a new ssh connection.
114
115 # Start Pageant from the Start Menu or the folder where it was installed.
116 # Pageant will now be running in the system tray. Click the Pageant icon to configure.
117 # Choose _Add Key_ and add the private key which you created in the previous step.
118
119 You are now ready to proceed to "adding your key to the Arvados Workbench":#workbench .
120
121 _Note: We recommend you do not delete the “Default” Saved Session._
122
123 h1(#workbench). Adding your key to Arvados Workbench
124
125 Open the Workbench dashboard (in this guide, this is "https://workbench.{{ site.arvados_api_host }}/":https://workbench.{{ site.arvados_api_host }}/ ) and look at the *Configuration* box.  If you do not have any ssh keys added, it will show:
126
127 <pre>
128  SSH keys   0
129 </pre>
130
131 This indicates that you have not yet provided Arvados with your public @ssh@ key.  Click on "SSH keys" or use the menu item _Access %(rarr)&rarr;% Keys_ to add an authorized ssh key to your account.
132
133 Click on the button <span class="btn btn-primary disabled">Add a new authorized key</span>.
134
135 This will reload the page, and should now show a row of information.  Click on the cell _none_ under the *public_key* column heading.  This should open up an editing popup as shown in this screenshot:
136
137 !{{ site.baseurl }}/images/ssh-adding-public-key.png!
138
139 Paste the public key that you copied to the clipboard in the previous section into the popup text box and click on the check mark to save it.  This should refresh the page with the public key that you just added now listed under the *public_key* column.  You are now ready to "log into an Arvados VM":#login.
140
141 h1(#login). Using ssh to log into an Arvados VM
142
143 First you must find determine the name and login information of the VM instance that you will connect to.  On the Arvados workbench, click on "Virtual machines" under *Configuration* or use the menu item _Access %(rarr)&rarr;% VMs_ to see a list of virtual machines that you have access to.  Make a note of the values in the *hostname* and *logins* columns.  In this guide the hostname will be _shell_ and the login will be _you_.  
144
145 This section consists of two sets of instructions, depending on whether you will be logging in using a "Unix":#unixvm (Linux, OS X, Cygwin) or "Windows":#windowsvm client.
146
147 h2. Logging in using command line ssh (Unix)
148
149 h3(#unixvm). Connecting to the VM
150
151 Use the following command to connect to the "shell" VM instance as "you":
152
153 <pre>
154  $ ssh -o "ProxyCommand ssh -a -x -p2222 turnout@switchyard.{{ site.arvados_api_host }} shell" -A -x you@shell 
155 </pre>
156
157 There are several things going on here:
158
159 The VMs typically have addresses that are not globally routable, so you cannot log in directly.  Instead, you log into a "switchyard" server and then tell it what VM you want to connect to.
160
161 * @-o "ProxyCommand ..."@ option instructs ssh to run the specified command and then tunnel your ssh connection over the proxy.
162 * @-a@ tells ssh not to forward your ssh-agent credentials to the switchyard
163 * @-x@ tells ssh not to forward your X session to the switchyard
164 * @-p2222@ specifies that the switchyard is running on non-standard port 2222
165 * <code>turnout@switchyard.{{ site.arvados_api_host }}</code> specifies the user (@turnout@) and hostname (@switchyard.{{ site.arvados_api_host }}@) of the switchboard server that will proxy our connection to the VM.
166 * @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.
167 * After the ProxyCommand section, the @-x@ must be repeated because it applies to the connection to VM instead of the switchyard.
168 * @-A@ specifies that we want to forward access to @ssh-agent@ to the VM.
169 * Finally, <code>you@shell</code> specifies your username and repeats the hostname of the VM.  The username can be found in the *logins* column in the VMs Workbench page, discussed above.
170
171 You should now be able to log into the Arvados VM and start working on the "first Arvados tutorial":tutorial-job1.html .
172
173 h3. Configuration (optional)
174
175 Since the above command line is cumbersome, it can be greatly simplfied by adding the following section your @~/.ssh/config@ file:
176
177 <pre>
178 Host *.qr1hi
179   ProxyCommand ssh -a -x -p2222 turnout@switchyard.{{ site.arvados_api_host }} $SSH_PROXY_FLAGS %h
180   User you
181   ForwardAgent yes
182   ForwardX11 no
183 </pre>
184
185 This will recognize any host ending in ".qr1hi" and automatically apply the proxy, user and forwarding settings discussed previously.  For example:
186
187 <pre>
188  $ ssh shell.qr1hi
189 </pre>
190
191 h2(#windowsvm). Logging in using PuTTY (Windows)
192
193 h3. Initial configuration
194
195 # Open PuTTY from the Start Menu.
196 # On the Session screen set the Host Name (or IP address) to “shell”.
197 # On the Session screen set the Port to “22”.
198 # On the Connection %(rarr)&rarr;% Data screen set the Auto-login username to the username listed in the *logins* column on the Arvados Workbench _Access %(rarr)&rarr;% VMs_ page.
199 # On the Connection %(rarr)&rarr;% Proxy screen set the Proxy Type to “Local”.
200 # On the Connection %(rarr)&rarr;% Proxy screen in the “Telnet command, or local proxy command” box enter:
201 <pre>plink -P 2222 turnout@switchyard.qr1hi.arvadosapi.com %host</pre>  Make sure there is no newline at the end of the text entry.
202 # Return to the Session screen. In the Saved Sessions box, enter a name for this configuration and hit Save. 
203
204 h3. Connecting to the VM
205
206 # Open PuTTY 
207 # Click on the Saved Session name you created in the previous section.
208 # Click Load to load those saved session settings.
209 # Click Open and that will open the SSH window at the command prompt. You will now be logged in to your virtual machine.
210
211 You should now be able to log into the Arvados VM and start working on the "first Arvados tutorial":tutorial-job1.html .