Set up a shell node

  1. Introduction
  2. Install Dependecies and SDKs
  3. Install git and curl
  4. Update Git Config
  5. Create record for VM
  6. Create scoped token
  7. Install arvados-login-sync
  8. Confirm working installation


Arvados support for shell nodes allows you to use Arvados permissions to grant Linux shell accounts to users.

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.

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.

Install Dependecies and SDKs

  1. Install Ruby and Bundler
  2. Install the Python SDK
  3. Install the FUSE driver
  4. Install the CLI
  5. Install the R SDK (optional)
  6. Install Docker (optional)

Install git and curl

Red Hat and Centos

# yum install git curl

Debian and Ubuntu

# apt-get install git curl

Update Git Config

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.

# git config --system 'credential.' none
# git config --system 'credential.' '!cred(){ cat >/dev/null; if [ "$1" = get ]; then echo password=$ARVADOS_API_TOKEN; fi; };cred'

Create record for VM

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.

Create an Arvados virtual_machine object representing this shell server. This will assign a UUID.

apiserver:~$ arv --format=uuid virtual_machine create --virtual-machine '{"hostname":""}'

Create scoped token

As an Arvados admin user (such as the system root user), create a scoped token that is permits only reading login information for this VM. Setting a scope on the token means that even though a user with root access on the shell node can access the token, the token is not usable for admin actions on Arvados.

apiserver:~$ arv api_client_authorization create --api-client-authorization '{"scopes":["GET /arvados/v1/virtual_machines/zzzzz-2x53u-zzzzzzzzzzzzzzz/logins"]}'

Note the UUID and the API token output by the above commands: you will need them in a minute.

Install arvados-login-sync

Install the arvados-login-sync program from RubyGems.

shellserver:# gem install arvados-login-sync

Configure cron to run the arvados-login-sync program every 2 minutes.

shellserver:# umask 077; tee /etc/cron.d/arvados-login-sync <<EOF
*/2 * * * * root arvados-login-sync

Confirm working installation

A user should be able to log in to the shell server when the following conditions are satisfied:

  1. The user has uploaded an SSH public key: Workbench → Account menu → “SSH keys” item → “Add new SSH key” button.
  2. As an admin user, you have given the user permission to log in using the Workbench → Admin menu → “Users” item → “Show” button → “Admin” tab → “Setup account” button.
  3. The cron job has run.

See also how to add a VM login permission link at the command line

Previous: Install the Git server Next: Set up a compute node

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.