doc/user/old/ssh-access.md

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Setting up SSH access (old)
   5 navorder: 2
   6 ---
   7
   8 # Setting up SSH access
   9
  10 Arvados uses SSH public key authentication for two things:
  11
  12 * logging in to a VM, and
  13 * pushing code to a git repository.
  14
  15 ### Generate a public/private SSH key pair
  16
  17 If you don't already have an SSH key pair (or you don't know whether
  18 you do), there are lots of tutorials out there to help you get
  19 started:
  20
  21 * [github SSH key
  22 tutorial](https://www.google.com/search?q=github+ssh+key+help)
  23
  24 ### Associate your SSH public key with your Arvados Workbench account
  25
  26 > Maybe mention that the "Add a new authorized key" button will be at the bottom of the page
  27
  28
  29 Go to the `Keys` page in Arvados Workbench (under the `Access` tab) and click the
  30
  31 <p style="margin-left: 4em"><span class="btn btn-primary disabled">Add a new authorized key</span></p>
  32
  33 button. Then click on 'none' in the public_key column, and copy and paste your public key:
  34
  35 ![Screen shot of the ssh public key box]({{ site.baseurl }}/images/ssh-adding-public-key.png)
  36
  37 Click on the checkmark button to save your public key.
  38
  39 ### Set up your ssh client (Unix-like systems only)
  40
  41 {% include notebox-begin.html %}
  42
  43 If you are using an Arvados site other than {{ site.arvados_api_host }}, replace "{{ site.arvados_api_host }}" with the appropriate Arvados API hostname in these examples.
  44
  45 {% include notebox-end.html %}
  46
  47 On your workstation, add the following section to your `~/.ssh/config`
  48 file:
  49
  50     Host *.arvados
  51       ProxyCommand ssh -p2222 turnout@switchyard.{{ site.arvados_api_host }} -x -a $SSH_PROXY_FLAGS %h
  52
  53 > This needs to be explained that it is adding an alias to make it easier to log into an
  54 > arvados server on port 2222.  This is not actually necessary if the user doesn't mind some typing.
  55 > Actually, it might make sense to show the regular command line first, and then mention later that
  56 > it can be shortened using ~/.ssh/config.
  57
  58 If you have access to an account `foo` on a VM called `blurfl` then
  59 you can log in like this:
  60
  61     ssh foo@blurfl.arvados
  62
  63 Some other convenient configuration options are `User` and
  64 `ForwardAgent`:
  65
  66     Host *.a
  67       ProxyCommand ssh -p2222 turnout@switchyard.{{ site.arvados_api_host }} -x -a $SSH_PROXY_FLAGS %h
  68       User foo
  69           ForwardAgent yes
  70
  71 > This shortened *.arvados to *.a
  72 > This should be consistent
  73
  74 Adding `User foo` will log you in to the VM as user `foo` by default,
  75 so you can just `ssh blurfl.a`. The `ForwardAgent yes` option turns on
  76 the `ssh -A` option to forward your SSH credentials (if you are
  77 using ssh-agent), which becomes important if you use git to
  78 synchronize files between your workstation and the VM.
  79
  80 Then you can log in to the `blurfl` VM as `foo` like this:
  81
  82     ssh blurfl.a
  83
  84 Arvados Workbench will show you a list of VMs you have access to and
  85 what your account name is for each one: click "VMs" in the "Access"
  86 menu.
  87
  88 ### Windows: Setup instructions for PuTTY
  89
  90 PuTTY 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.
  91
  92 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.
  93
  94 PuTTY is an open source project and you download it [here](http://www.putty.org/).
  95
  96 Arvados uses Public-key encryption to secure access to your virtual machines in the Arvados cloud. this is a very standard approach. It’s secure, and easy to use.
  97
  98 (Make sure to download the .zip file containing all the binaries, not each one individually)
  99
 100 __Step 1 - Adding PuTTY to the PATH__
 101
 102 1. After downloading PuTTY and unzipping it, you should have a PuTTY folder in C:\Program Files (x86)\ . If the folder is somewhere else, you can change the PATH in step X or move the folder to that directory.
 103
 104 2. In the Start menu, right click Windows and select Properties
 105
 106 3. Select Advanced System Settings, and choose Environment Variables
 107
 108 4. Under system variables, find and edit Path.
 109
 110 5. Add the following to the end of Path (make sure to include semi colon and quotation marks):
 111
 112         ;\"C:\Program Files (x86)\PuTTY\"
 113
 114 6. Click through the OKs to close all the dialogs you’ve opened
 115
 116 __Step 2 - Creating a Public Key__
 117
 118 1. Open PuTTYgen from the Start Menu
 119
 120 2. At the bottom of the window, make sure the ‘Number of bits in a generated key’ field is set to 4096
 121
 122 3. Click Generate and follow the instructions to generate a key
 123
 124 4. Click to save the Public Key
 125
 126 5. Click to save the Private Key (we recommend using a strong passphrase)
 127
 128 6. Select the Public Key text in the box and copy (for next step)
 129
 130 Now your key is successfully generated.
 131
 132 __Step 3 - Load Your Public Key in to your Arvados Account through Workbench__
 133
 134 1. Open Workbench on the cloud where you have an arvados account
 135
 136 2. Go to Access > Keys in the menu
 137
 138 3. Click to create a new key
 139
 140 4. In the last column “public key” click on the text that says “none” and paste the public key from PuTTYgen into the box.
 141
 142 Your public key is now registered with the Arvados cluster.
 143
 144 __Step 4 - Set up Pageant__
 145
 146 1. Start Pageant from the PuTTY folder in the start menu
 147
 148 2. Pageant will now be running in the system tray. Click the icon to configure.
 149
 150 3. Choose Add Key and add the private which corresponds with the public key you loaded in your Arvados account through work bench.
 151
 152 Pageant is now configured. It will run in the background as a system service.
 153
 154 Note: Pageant is a PuTTY utility that manages private keys which makes repeatedly logging in through SSH less of a hassle.
 155
 156 __Step 5 - Set up PuTTY__
 157
 158 1. Open PuTTY from the Start Menu
 159
 160 2. On the Session screen set the Host Name (or IP address) to “shell”
 161
 162 3. On the Session screen set the Port to “22”
 163
 164 4. On the Connection > Data screen set the Auto-login username to your VM’s Login,. You can find your login name in Workbench under Access > VMs last column on the table.
 165
 166 5. On the Connection > Proxy screen set the Proxy Type to “Local”
 167
 168 6. On the Connection > Proxy screen in the “Telnet command, or local proxy command” box enter “plink -P 2222 turnout@switchyard.qr1hi.arvadosapi.com %host”. Make sure you remove the “\n” from the end of the line.
 169
 170 7. Return to the Session screen. In the Saved Sessions box, enter a name for this configuration and hit Save.
 171
 172
 173 __Step 6 - Launch an SSH Session__
 174
 175 1. Open PuTTY
 176
 177 2. Click on the Saved Session name you created in Step 5
 178
 179 3. Click Load to load those saved session settings
 180
 181 4. Click Open and that will open the SSH window at the command prompt. You will now be logged in to your virtual machine.
 182
 183 _Note: We recommend you do not delete the “Default” Saved Session._
 184