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. Alma/CentOS/Red Hat/Rocky
 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 # The first argument is the address of the API server.  The second
 163 # argument is this shell node's hostname.  The hostname must match the
 164 # "hostname" field of the virtual_machine record.
 165 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>
 166
 167 auth    requisite            pam_deny.so
 168 auth    required            pam_permit.so
 169
 170 auth       optional   pam_group.so
 171 session    required   pam_limits.so
 172 session    optional   pam_lastlog.so
 173 session    optional   pam_motd.so  motd=/run/motd.dynamic
 174 session    optional   pam_motd.so
 175 session    optional   pam_mail.so standard
 176
 177 @include common-account
 178 @include common-session
 179 @include common-password
 180
 181 session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open
 182 </pre></notextile>
 183
 184 h2(#confirm-working). Confirm working installation
 185
 186 We recommend using the "Cluster diagnostics tool.":diagnostics.html
 187
 188 Here are some other checks you can perform manually.
 189
 190 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":{{site.baseurl}}/user/getting_started/vm-login-with-webshell.html