doc/install/install-shell-server.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Set up a shell node
   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 # "Introduction":#introduction
  13 # "Install Dependecies and SDKs":#dependencies
  14 # "Install git and curl":#install-packages
  15 # "Update Git Config":#config-git
  16 # "Create record for VM":#vm-record
  17 # "Create scoped token":#scoped-token
  18 # "Install arvados-login-sync":#arvados-login-sync
  19 # "Confirm working installation":#confirm-working
  20
  21 h2(#introduction). Introduction
  22
  23 Arvados support for shell nodes allows you to use Arvados permissions to grant Linux shell accounts to users.
  24
  25 A shell node runs the @arvados-login-sync@ service, and has some additional configuration to make it convenient for users to use Arvados utilites and SDKs.  Users are allowed to log in and run arbitrary programs.  For optimal performance, the Arvados shell server should be on the same LAN as the Arvados cluster.
  26
  27 Because it _contains secrets_ shell nodes should *not* have a copy of the complete @config.yml@.  For example, if users have access to the @docker@ daemon, it is trival to gain *root* access to any file on the system.  Users sharing a shell node should be implicitly trusted, or not given access to Docker.  In more secure environments, the admin should allocate a separate VM for each user.
  28
  29 h2(#dependencies). Install Dependecies and SDKs
  30
  31 # "Install Ruby and Bundler":ruby.html
  32 # "Install the Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html
  33 # "Install the CLI":{{site.baseurl}}/sdk/cli/install.html
  34 # "Install the R SDK":{{site.baseurl}}/sdk/R/index.html (optional)
  35 # "Install Docker":install-docker.html (optional)
  36
  37 {% assign arvados_component = 'git curl' %}
  38
  39 {% include 'install_packages' %}
  40
  41 h2(#config-git). Update Git Config
  42
  43 Configure git to use the ARVADOS_API_TOKEN environment variable to authenticate to arv-git-httpd. We use the @--system@ flag so it takes effect for all current and future user accounts. It does not affect git's behavior when connecting to other git servers.
  44
  45 <notextile>
  46 <pre>
  47 <code># <span class="userinput">git config --system 'credential.https://git.<b>ClusterID.example.com</b>/.username' none</span></code>
  48 <code># <span class="userinput">git config --system 'credential.https://git.<b>ClusterID.example.com</b>/.helper' '!cred(){ cat >/dev/null; if [ "$1" = get ]; then echo password=$ARVADOS_API_TOKEN; fi; };cred'</span></code>
  49 </pre>
  50 </notextile>
  51
  52 h2(#vm-record). Create record for VM
  53
  54 This program makes it possible for Arvados users to log in to the shell server -- subject to permissions assigned by the Arvados administrator -- using the SSH keys they upload to Workbench. It sets up login accounts, updates group membership, and adds users' public keys to the appropriate @authorized_keys@ files.
  55
  56 Create an Arvados virtual_machine object representing this shell server. This will assign a UUID.
  57
  58 <notextile>
  59 <pre>
  60 <code>apiserver:~$ <span class="userinput">arv --format=uuid virtual_machine create --virtual-machine '{"hostname":"<b>your.shell.server.hostname.without.domain</b>"}'</span>
  61 zzzzz-2x53u-zzzzzzzzzzzzzzz</code>
  62 </pre>
  63 </notextile>
  64
  65 h2(#scoped-token). Create scoped token
  66
  67 As an admin arvados user (such as the system root user), create a token that is restricted to only reading login information for this VM.
  68
  69 <notextile>
  70 <pre>
  71 <code>apiserver:~$ <span class="userinput">arv api_client_authorization create --api-client-authorization '{"scopes":["GET /arvados/v1/virtual_machines/<b>zzzzz-2x53u-zzzzzzzzzzzzzzz</b>/logins"]}'
  72 {
  73  ...
  74  "api_token":"zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
  75  ...
  76 }</code>
  77 </pre>
  78 </notextile>
  79
  80 Note the UUID and the API token output by the above commands: you will need them in a minute.
  81
  82 h2(#arvados-login-sync). Install arvados-login-sync
  83
  84 Install the arvados-login-sync program from RubyGems.
  85
  86 <notextile>
  87 <pre>
  88 <code>shellserver:# <span class="userinput">gem install arvados-login-sync</span></code>
  89 </pre>
  90 </notextile>
  91
  92 Configure cron to run the @arvados-login-sync@ program every 2 minutes.
  93
  94 <notextile>
  95 <pre>
  96 <code>shellserver:# <span class="userinput">umask 077; tee /etc/cron.d/arvados-login-sync &lt;&lt;EOF
  97 ARVADOS_API_HOST="<strong>ClusterID.example.com</strong>"
  98 ARVADOS_API_TOKEN="<strong>the_token_you_created_above</strong>"
  99 ARVADOS_VIRTUAL_MACHINE_UUID="<strong>zzzzz-2x53u-zzzzzzzzzzzzzzz</strong>"
 100 */2 * * * * root arvados-login-sync
 101 EOF</span></code>
 102 </pre>
 103 </notextile>
 104
 105 h2(#confirm-working). Confirm working installation
 106
 107 A user should be able to log in to the shell server when the following conditions are satisfied:
 108
 109 # The user has uploaded an SSH public key: Workbench &rarr; Account menu &rarr; "SSH keys" item &rarr; "Add new SSH key" button.
 110 # As an admin user, you have given the user permission to log in using the Workbench &rarr; Admin menu &rarr; "Users" item &rarr; "Show" button &rarr; "Admin" tab &rarr; "Setup account" button.
 111 # The cron job has run.
 112
 113 See also "how to add a VM login permission link at the command line":../admin/user-management-cli.html