Configure webshell

Introduction
Prerequisites
Update config.yml
Update nginx configuration
Install packages
Configure shellinabox
Configure pam
Confirm working installation

Introduction

Arvados supports webshell, which allows ssh access to shell nodes via the browser. This functionality is integrated in Workbench.

Webshell is provided by the shellinabox package which runs on each shell node for which webshell is enabled. For authentication, a supported pam library that allows authentication against Arvados is also required. One Nginx (or similar web server) virtualhost is also needed to expose all the shellinabox instances via https.

Prerequisites

Update config.yml

Edit the cluster config at config.yml and set Services.WebShell.ExternalURL. Replace zzzzz with your cluster id. Workbench will use this information to activate its support for webshell.

    Services:
      WebShell:
        InternalURLs: {}
        ExternalURL: https://webshell.ClusterID.example.com/

Update Nginx configuration

The arvados-webshell service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption. This Nginx virtualhost could live on your Workbench server, or any other server that is reachable by your Workbench users and can access the shell-in-a-box service on the shell node(s) on port 4200.

Use a text editor to create a new file /etc/nginx/conf.d/arvados-webshell.conf with the following configuration. Options that need attention are marked in red.

upstream arvados-webshell {
  server                shell.ClusterID.example.com:4200;
}

server {
  listen                443 ssl;
  server_name           webshell.ClusterID.example.com;

  proxy_connect_timeout 90s;
  proxy_read_timeout    300s;

  ssl                   on;
  ssl_certificate       /YOUR/PATH/TO/cert.pem;
  ssl_certificate_key   /YOUR/PATH/TO/cert.key;

  location /shell.ClusterID {
    if ($request_method = 'OPTIONS') {
       add_header 'Access-Control-Allow-Origin' '*';
       add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
       add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
       add_header 'Access-Control-Max-Age' 1728000;
       add_header 'Content-Type' 'text/plain charset=UTF-8';
       add_header 'Content-Length' 0;
       return 204;
    }
    if ($request_method = 'POST') {
       add_header 'Access-Control-Allow-Origin' '*';
       add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
       add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
    }
    if ($request_method = 'GET') {
       add_header 'Access-Control-Allow-Origin' '*';
       add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
       add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
    }

    proxy_ssl_session_reuse off;
    proxy_read_timeout  90;
    proxy_set_header    X-Forwarded-Proto https;
    proxy_set_header    Host $http_host;
    proxy_set_header    X-Real-IP $remote_addr;
    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass          http://arvados-webshell;
  }
}

Note that the location line in the nginx config matches your shell node hostname without domain, because that is how the shell node was defined in the Set up a shell node instructions. It makes for a more user friendly experience in Workbench.

For additional shell nodes with shell-in-a-box, add location and upstream sections as needed.

Install shellinabox and libpam-arvados-go

Red Hat, AlmaLinux, and Rocky Linux

# dnf install shellinabox libpam-arvados-go

Debian and Ubuntu

# apt install shellinabox libpam-arvados-go

Configure shellinabox

Red Hat, AlmaLinux, and Rocky Linux

Edit /etc/sysconfig/shellinaboxd:

# TCP port that shellinboxd's webserver listens on
PORT=4200

# SSL is disabled because it is terminated in Nginx. Adjust as needed.
OPTS="--disable-ssl --no-beep --service=/shell.ClusterID.example.com:AUTH:HOME:SHELL"

# systemctl enable shellinabox
# systemctl start shellinabox

Debian and Ubuntu

Edit /etc/default/shellinabox:

# TCP port that shellinboxd's webserver listens on
SHELLINABOX_PORT=4200

# SSL is disabled because it is terminated in Nginx. Adjust as needed.
SHELLINABOX_ARGS="--disable-ssl --no-beep --service=/shell.ClusterID.example.com:AUTH:HOME:SHELL"

# systemctl enable shellinabox
# systemctl start shellinabox

Configure pam

Use a text editor to create a new file /etc/pam.d/shellinabox with the following configuration. Options that need attention are marked in red.

# This example is a stock debian "login" file with pam_arvados
# replacing pam_unix. It can be installed as /etc/pam.d/shellinabox .

auth       optional   pam_faildelay.so  delay=3000000
auth [success=ok new_authtok_reqd=ok ignore=ignore user_unknown=bad default=die] pam_securetty.so
auth       requisite  pam_nologin.so
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so close
session       required   pam_env.so readenv=1
session       required   pam_env.so readenv=1 envfile=/etc/default/locale

# The first argument is the address of the API server.  The second
# argument is this shell node's hostname.  The hostname must match the
# "hostname" field of the virtual_machine record.
auth [success=1 default=ignore] /usr/lib/pam_arvados.so ClusterID.example.com shell.ClusterID.example.com

auth    requisite            pam_deny.so
auth    required            pam_permit.so

auth       optional   pam_group.so
session    required   pam_limits.so
session    optional   pam_lastlog.so
session    optional   pam_motd.so  motd=/run/motd.dynamic
session    optional   pam_motd.so
session    optional   pam_mail.so standard

@include common-account
@include common-session
@include common-password

session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open

Confirm working installation

We recommend using the Cluster diagnostics tool.

Here are some other checks you can perform manually.

A user should now be able to log in to the shell server, using webshell via workbench. Please refer to Accessing an Arvados VM with Webshell

Previous: Set up a shell node Next: Build a cloud compute node image