doc/install/install-webshell.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Configure webshell
   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 # "Prerequisites":#prerequisites
  14 # "Update config.yml":#configure
  15 # "Update nginx configuration":#update-nginx
  16 # "Install packages":#install-packages
  17 # "Configure shellinabox":#config-shellinabox
  18 # "Configure pam":#config-pam
  19 # "Confirm working installation":#confirm-working
  20
  21 h2(#introduction). Introduction
  22
  23 Arvados supports @webshell@, which allows ssh access to shell nodes via the browser. This functionality is integrated in @Workbench@.
  24
  25 @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.
  26
  27 h2(#prerequisites). Prerequisites
  28
  29 # "Install workbench":{{site.baseurl}}/install/install-workbench-app.html
  30 # "Set up a shell node":{{site.baseurl}}/install/install-shell-server.html
  31
  32 h2(#configure). Update config.yml
  33
  34 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.
  35
  36 <notextile>
  37 <pre><code>    Services:
  38       WebShell:
  39         InternalURLs: {}
  40         ExternalURL: <span class="userinput">https://webshell.ClusterID.example.com/</span>
  41 </span></code></pre>
  42 </notextile>
  43
  44 h2(#update-nginx). Update Nginx configuration
  45
  46 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.
  47
  48 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 <span class="userinput">red</span>.
  49
  50 <notextile><pre>
  51 upstream arvados-webshell {
  52   server                <span class="userinput">shell.ClusterID.example.com</span>:<span class="userinput">4200</span>;
  53 }
  54
  55 server {
  56   listen                443 ssl;
  57   server_name           webshell.<span class="userinput">ClusterID.example.com</span>;
  58
  59   proxy_connect_timeout 90s;
  60   proxy_read_timeout    300s;
  61
  62   ssl                   on;
  63   ssl_certificate       <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
  64   ssl_certificate_key   <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
  65
  66   location /<span class="userinput">shell.ClusterID</span> {
  67     if ($request_method = 'OPTIONS') {
  68        add_header 'Access-Control-Allow-Origin' '*';
  69        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
  70        add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
  71        add_header 'Access-Control-Max-Age' 1728000;
  72        add_header 'Content-Type' 'text/plain charset=UTF-8';
  73        add_header 'Content-Length' 0;
  74        return 204;
  75     }
  76     if ($request_method = 'POST') {
  77        add_header 'Access-Control-Allow-Origin' '*';
  78        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
  79        add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
  80     }
  81     if ($request_method = 'GET') {
  82        add_header 'Access-Control-Allow-Origin' '*';
  83        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
  84        add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
  85     }
  86
  87     proxy_ssl_session_reuse off;
  88     proxy_read_timeout  90;
  89     proxy_set_header    X-Forwarded-Proto https;
  90     proxy_set_header    Host $http_host;
  91     proxy_set_header    X-Real-IP $remote_addr;
  92     proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
  93     proxy_pass          http://arvados-webshell;
  94   }
  95 }
  96 </pre></notextile>
  97
  98 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":{{site.baseurl}}/install/install-shell-server.html#vm-record instructions. It makes for a more user friendly experience in Workbench.
  99
 100 For additional shell nodes with @shell-in-a-box@, add @location@ and @upstream@ sections as needed.
 101
 102 {% assign arvados_component = 'shellinabox libpam-arvados-go' %}
 103
 104 {% include 'install_packages' %}
 105
 106 h2(#config-shellinabox). Configure shellinabox
 107
 108 h3. Red Hat and Centos
 109
 110 Edit @/etc/sysconfig/shellinaboxd@:
 111
 112 <notextile><pre>
 113 # TCP port that shellinboxd's webserver listens on
 114 PORT=4200
 115
 116 # SSL is disabled because it is terminated in Nginx. Adjust as needed.
 117 OPTS="--disable-ssl --no-beep --service=/<span class="userinput">shell.ClusterID.example.com</span>:AUTH:HOME:SHELL"
 118 </pre></notextile>
 119
 120 <notextile>
 121 <pre>
 122 <code># <span class="userinput">systemctl enable shellinabox</span></code>
 123 <code># <span class="userinput">systemctl start shellinabox</span></code>
 124 </pre>
 125 </notextile>
 126
 127 h3. Debian and Ubuntu
 128
 129 Edit @/etc/default/shellinabox@:
 130
 131 <notextile><pre>
 132 # TCP port that shellinboxd's webserver listens on
 133 SHELLINABOX_PORT=4200
 134
 135 # SSL is disabled because it is terminated in Nginx. Adjust as needed.
 136 SHELLINABOX_ARGS="--disable-ssl --no-beep --service=/<span class="userinput">shell.ClusterID.example.com</span>:AUTH:HOME:SHELL"
 137 </pre></notextile>
 138
 139 <notextile>
 140 <pre>
 141 <code># <span class="userinput">systemctl enable shellinabox</span></code>
 142 <code># <span class="userinput">systemctl start shellinabox</span></code>
 143 </pre>
 144 </notextile>
 145
 146
 147 h2(#config-pam). Configure pam
 148
 149 Use a text editor to create a new file @/etc/pam.d/shellinabox@ with the following configuration. Options that need attention are marked in <span class="userinput">red</span>.
 150
 151 <notextile><pre>
 152 # This example is a stock debian "login" file with pam_arvados
 153 # replacing pam_unix. It can be installed as /etc/pam.d/shellinabox .
 154
 155 auth       optional   pam_faildelay.so  delay=3000000
 156 auth [success=ok new_authtok_reqd=ok ignore=ignore user_unknown=bad default=die] pam_securetty.so
 157 auth       requisite  pam_nologin.so
 158 session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so close
 159 session       required   pam_env.so readenv=1
 160 session       required   pam_env.so readenv=1 envfile=/etc/default/locale
 161
 162 auth [success=1 default=ignore] /usr/lib/pam_arvados.so <span class="userinput">ClusterID.example.com</span> <span class="userinput">shell.ClusterID.example.com</span>
 163 auth    requisite            pam_deny.so
 164 auth    required            pam_permit.so
 165
 166 auth       optional   pam_group.so
 167 session    required   pam_limits.so
 168 session    optional   pam_lastlog.so
 169 session    optional   pam_motd.so  motd=/run/motd.dynamic
 170 session    optional   pam_motd.so
 171 session    optional   pam_mail.so standard
 172
 173 @include common-account
 174 @include common-session
 175 @include common-password
 176
 177 session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open
 178 </pre></notextile>
 179
 180 h2(#confirm-working). Confirm working installation
 181
 182 A user should be able to log in to the shell server, using webshell via workbench. Please refer to "Accessing an Arvados VM with Webshell":{{site.baseurl}}/user/getting_started/vm-login-with-webshell.html
 183