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 to manage user accounts, and typically has Arvados utilities and SDKs pre-installed.  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 Arvados @config.yml@ _contains secrets_ it should not *not* be present on shell nodes.
  28
  29 Shell nodes should be separate virtual machines from the VMs running other Arvados services.  You may choose to grant root access to users so that they can customize the node, for example, installing new programs.  This has security considerations depending on whether a shell node is single-user or multi-user.
  30
  31 A single-user shell node should be set up so that it only stores Arvados access tokens that belong to that user.  In that case, that user can be safely granted root access without compromising other Arvados users.
  32
  33 In the multi-user shell node case, a malicious user with @root@ access could access other user's Arvados tokens.  Users should only be given @root@ access on a multi-user shell node if you would trust them them to be Arvados administrators.  Be aware that with access to the @docker@ daemon, it is trival to gain *root* access to any file on the system, so giving users @docker@ access should be considered equivalent to @root@ access.
  34
  35 h2(#dependencies). Install Dependecies and SDKs
  36
  37 # "Install Ruby and Bundler":ruby.html
  38 # "Install the Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html
  39 # "Install the FUSE driver":{{site.baseurl}}/sdk/python/arvados-fuse.html
  40 # "Install the CLI":{{site.baseurl}}/sdk/cli/install.html
  41 # "Install the R SDK":{{site.baseurl}}/sdk/R/index.html (optional)
  42 # "Install Docker":install-docker.html (optional)
  43
  44 {% assign arvados_component = 'git curl' %}
  45
  46 {% include 'install_packages' %}
  47
  48 h2(#config-git). Update Git Config
  49
  50 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.
  51
  52 <notextile>
  53 <pre>
  54 <code># <span class="userinput">git config --system 'credential.https://git.<b>ClusterID.example.com</b>/.username' none</span></code>
  55 <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>
  56 </pre>
  57 </notextile>
  58
  59 h2(#vm-record). Create record for VM
  60
  61 As an admin, create an Arvados virtual_machine object representing this shell server. This will return a uuid.
  62
  63 <notextile>
  64 <pre>
  65 <code>apiserver:~$ <span class="userinput">arv --format=uuid virtual_machine create --virtual-machine '{"hostname":"<b>shell.ClusterID.example.com</b>"}'</span>
  66 zzzzz-2x53u-zzzzzzzzzzzzzzz</code>
  67 </pre>
  68 </notextile>
  69
  70 h2(#arvados-login-sync). Install arvados-login-sync
  71
  72 The @arvados-login-sync@ service makes it possible for Arvados users to log in to the shell server.  It sets up login accounts, updates group membership, adds each user's SSH public keys to the @~/.ssh/authorized_keys@ file, and adds an Arvados token to @~/.config/arvados/settings.conf@ .
  73
  74 Install the @arvados-login-sync@ program from RubyGems.
  75
  76 <notextile>
  77 <pre>
  78 <code>shellserver:# <span class="userinput">gem install arvados-login-sync</span></code>
  79 </pre>
  80 </notextile>
  81
  82 h2(#arvados-login-sync). Run arvados-login-sync periodically
  83
  84 Create a cron job to run the @arvados-login-sync@ program every 2 minutes.  This will synchronize user accounts.
  85
  86 If this is a single-user shell node, then @ARVADOS_API_TOKEN@ should be a token for that user.  See "Create a token for a user":{{site.baseurl}}/admin/user-management-cli.html#create-token .
  87
  88 If this is a multi-user shell node, then @ARVADOS_API_TOKEN@ should be an administrator token such as the @SystemRootToken@.  See discussion in the "introduction":#introduction about security on multi-user shell nodes.
  89
  90 Set @ARVADOS_VIRTUAL_MACHINE_UUID@ to the UUID from "Create record for VM":#vm-record
  91
  92 h3. Standalone cluster
  93
  94 <notextile>
  95 <pre>
  96 <code>shellserver:# <span class="userinput">umask 0700; tee /etc/cron.d/arvados-login-sync &lt;&lt;EOF
  97 ARVADOS_API_HOST="<strong>ClusterID.example.com</strong>"
  98 ARVADOS_API_TOKEN="<strong>xxxxxxxxxxxxxxxxx</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 h3. Part of a LoginCLuster federation
 106
 107 If this cluster is part of a "federation with centralized user management":../admin/federation.html#LoginCluster , the login sync script also needs to be given the host and user token for the login cluster.
 108
 109 <notextile>
 110 <pre>
 111 <code>shellserver:# <span class="userinput">umask 0700; tee /etc/cron.d/arvados-login-sync &lt;&lt;EOF
 112 ARVADOS_API_HOST="<strong>ClusterID.example.com</strong>"
 113 ARVADOS_API_TOKEN="<strong>xxxxxxxxxxxxxxxxx</strong>"
 114 LOGINCLUSTER_ARVADOS_API_HOST="<strong>LoginClusterID.example.com</strong>"
 115 LOGINCLUSTER_ARVADOS_API_TOKEN="<strong>yyyyyyyyyyyyyyyyy</strong>"
 116 ARVADOS_VIRTUAL_MACHINE_UUID="<strong>zzzzz-2x53u-zzzzzzzzzzzzzzz</strong>"
 117 */2 * * * * root arvados-login-sync
 118 EOF</span></code>
 119 </pre>
 120 </notextile>
 121
 122
 123 h2(#confirm-working). Confirm working installation
 124
 125 A user should be able to log in to the shell server when the following conditions are satisfied:
 126
 127 # 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.
 128 # The cron job has run.
 129
 130 In order to log in via SSH, the user must also upload an SSH public key.  Alternately, if configured, users can log in using "Webshell":install-webshell.html .
 131
 132 See also "how to add a VM login permission link at the command line":../admin/user-management-cli.html