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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install 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 Arvados support for shell nodes enables using Arvados permissions to grant shell accounts to users.
  13
  14 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.
  15
  16 h2. Install Dependecies and SDKs
  17
  18 # "Install the CLI":{{site.baseurl}}/sdk/cli/install.html
  19 # "Install the R SDK":{{site.baseurl}}/sdk/R/index.html (optional)
  20
  21 h2. Install Git and curl
  22
  23 {% include 'install_git_curl' %}
  24
  25 h2. Update Git Config
  26
  27 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.
  28
  29 <notextile>
  30 <pre>
  31 <code>~$ <span class="userinput">sudo git config --system 'credential.https://git.<b>uuid_prefix.your.domain</b>/.username' none</span></code>
  32 <code>~$ <span class="userinput">sudo git config --system 'credential.https://git.<b>uuid_prefix.your.domain</b>/.helper' '!cred(){ cat >/dev/null; if [ "$1" = get ]; then echo password=$ARVADOS_API_TOKEN; fi; };cred'</span></code>
  33 </pre>
  34 </notextile>
  35
  36 h2. Create database entry for VM
  37
  38 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.
  39
  40 Create an Arvados virtual_machine object representing this shell server. This will assign a UUID.
  41
  42 <notextile>
  43 <pre>
  44 <code>apiserver:~$ <span class="userinput">arv --format=uuid virtual_machine create --virtual-machine '{"hostname":"<b>your.shell.server.hostname.without.domain</b>"}'</span>
  45 zzzzz-2x53u-zzzzzzzzzzzzzzz</code>
  46 </pre>
  47 </notextile>
  48
  49 h2. Create token
  50
  51 As an admin arvados user (such as the system root user), create a token that is allowed to read login information for this VM.
  52
  53 <notextile>
  54 <pre>
  55 <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"]}'
  56 {
  57  ...
  58  "api_token":"zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
  59  ...
  60 }</code>
  61 </pre>
  62 </notextile>
  63
  64 Note the UUID and the API token output by the above commands: you will need them in a minute.
  65
  66 h2. Install arvados-login-sync
  67
  68 Install the arvados-login-sync program.
  69
  70 <notextile>
  71 <pre>
  72 <code>shellserver:# <span class="userinput">gem install arvados-login-sync</span></code>
  73 </pre>
  74 </notextile>
  75
  76 Configure cron to run the @arvados-login-sync@ program every 2 minutes.
  77
  78 <notextile>
  79 <pre>
  80 <code>shellserver:# <span class="userinput">umask 077; tee /etc/cron.d/arvados-login-sync &lt;&lt;EOF
  81 ARVADOS_API_HOST="<strong>uuid_prefix.your.domain</strong>"
  82 ARVADOS_API_TOKEN="<strong>the_token_you_created_above</strong>"
  83 ARVADOS_VIRTUAL_MACHINE_UUID="<strong>zzzzz-2x53u-zzzzzzzzzzzzzzz</strong>"
  84 */2 * * * * root arvados-login-sync
  85 EOF</span></code>
  86 </pre>
  87 </notextile>
  88
  89 A user should be able to log in to the shell server when the following conditions are satisfied:
  90 * The user has uploaded an SSH public key: Workbench &rarr; Account menu &rarr; "SSH keys" item &rarr; "Add new SSH key" button.
  91 * As an admin user, you have given the user permission to log in: Workbench &rarr; Admin menu &rarr; "Users" item &rarr; "Show" button &rarr; "Admin" tab &rarr; "Setup shell account" button.
  92 * Two minutes have elapsed since the above conditions were satisfied, and the cron job has had a chance to run.
  93
  94