Merge branch '20705-crunchstat-warn-missing-data'
[arvados.git] / 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