From 02f2c38ee8f2a5d2e33a7bd2ff033303e6861aaf Mon Sep 17 00:00:00 2001 From: Peter Amstutz Date: Thu, 29 Sep 2022 17:05:49 -0400 Subject: [PATCH] 19215: Much installer documentation and reorganization Arvados-DCO-1.1-Signed-off-by: Peter Amstutz --- doc/_includes/_install_ca_cert.liquid | 18 +- ...ti_host_install_custom_certificates.liquid | 14 +- doc/_includes/_ssl_config_multi.liquid | 16 +- doc/_includes/_supportedlinux.liquid | 15 ++ doc/admin/upgrading.html.textile.liquid | 12 +- doc/install/arvbox.html.textile.liquid | 79 ++++---- ...gure-s3-object-storage.html.textile.liquid | 28 ++- doc/install/index.html.textile.liquid | 7 +- .../salt-multi-host.html.textile.liquid | 182 +++++++++--------- .../salt-single-host.html.textile.liquid | 8 + tools/salt-install/installer.sh | 10 +- 11 files changed, 207 insertions(+), 182 deletions(-) create mode 100644 doc/_includes/_supportedlinux.liquid diff --git a/doc/_includes/_install_ca_cert.liquid b/doc/_includes/_install_ca_cert.liquid index 522a63a032..279356a345 100644 --- a/doc/_includes/_install_ca_cert.liquid +++ b/doc/_includes/_install_ca_cert.liquid @@ -4,14 +4,6 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} -h2(#ca_root_certificate). Install the CA root certificate (SSL_MODE=self-signed only) - -*If you are not using self-signed certificates (you selected SSL_MODE=lets-encrypt or SSL_MODE=bring-your-own), skip this section.* - -Arvados uses SSL to encrypt communications. The web interface uses AJAX which will silently fail if the certificate is not valid or signed by an unknown Certification Authority. - -For this reason, the @arvados-formula@ has a helper state to create a root certificate to authorize Arvados services. The @provision.sh@ script will leave a copy of the generated CA's certificate (@arvados-snakeoil-ca.pem@) in the script's directory so you can add it to your workstation. - h3. Web Browser Installing the root certificate into your web browser will prevent security errors when accessing Arvados services with your web browser. @@ -21,7 +13,7 @@ h4. Chrome # Go to "Settings → Privacy and Security → Security → Manage Certificates" or enter @chrome://settings/certificates@ in the URL bar. # *Click on the "Authorities" tab* (it is not selected by default) # Click on the "Import" button -# Choose @arvados-snakeoil-ca.pem@ +# Choose @{{ca_cert_name}}@ # Tick the checkbox next to "Trust this certificate for identifying websites" # Hit OK # The certificate should appear in the list of Authorities under "Arvados" @@ -33,14 +25,14 @@ h4. Firefox # Click on the button "View Certificates...". # Make sure the "Authorities" tab is selected # Press the "Import..." button. -# Choose @arvados-snakeoil-ca.pem@ +# Choose @{{ca_cert_name}}@ # Tick the checkbox next to "Trust this CA to identify websites" # Hit OK # The certificate should appear in the list of Authorities under "Arvados" h4. Other browsers (Safari, etc) -The process will be similar to that of Chrome and Firefox, but the exact user interface will be different. If you can't figure it out, try searching for "how do I install a custom certificate authority in ". +The process will be similar to that of Chrome and Firefox, but the exact user interface will be different. If you can't figure it out, try searching for "how do I install a custom certificate authority in (my browser)". h3. Installation on Linux OS certificate storage @@ -51,7 +43,7 @@ h4. Debian/Ubuntu *Important* the certificate file added to @ca-certificates@ must have the extension @.crt@ or it won't be recognized. -
cp arvados-snakeoil-ca.pem /usr/local/share/ca-certificates/arvados-snakeoil-ca.crt
+
cp {{ca_cert_name}} /usr/local/share/ca-certificates/arvados-snakeoil-ca.crt
 /usr/sbin/update-ca-certificates
 

 
@@ -59,7 +51,7 @@ h4. Debian/Ubuntu
 h4. CentOS
 
 
-
cp arvados-snakeoil-ca.pem /etc/pki/ca-trust/source/anchors/
+
cp {{ca_cert_name}} /etc/pki/ca-trust/source/anchors/
 /usr/bin/update-ca-trust
 

 
diff --git a/doc/_includes/_multi_host_install_custom_certificates.liquid b/doc/_includes/_multi_host_install_custom_certificates.liquid
index 6c0207324c..7063eb28fb 100644
--- a/doc/_includes/_multi_host_install_custom_certificates.liquid
+++ b/doc/_includes/_multi_host_install_custom_certificates.liquid
@@ -4,9 +4,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-You will need certificates for each DNS name and DNS wildcard previously described in the "Hosts":#hosts .
+You will need certificates for each DNS name and DNS wildcard previously listed in the "DNS hostnames for each service":#DNS .
 
-To simplify certificate management, we recommend creating a single certificate with all of the hostnames, or creating a wildcard certificate that covers all possible hostnames (with the following patterns in subjectAltName):
+To simplify certificate management, we recommend creating a single certificate for all of the hostnames, or creating a wildcard certificate that covers all possible hostnames (with the following patterns in subjectAltName):
 
 
 xarv1.example.com
@@ -21,15 +21,15 @@ Copy your certificates to the directory specified with the variable @CUSTOM_CERT
 The script expects cert/key files with these basenames (matching the role except for keepweb, which is split in both download / collections):
 
 # @controller@
-# @websocket@        # note: corresponds to default domain @ws.${CLUSTER}.${DOMAIN}@
-# @keepproxy@        # note: corresponds to default domain @keep.${CLUSTER}.${DOMAIN}@
-# @download@         # Part of keepweb
-# @collections@      # Part of keepweb -- important note, this should be a wildcard for @*.collections.${CLUSTER}.${DOMAIN}@
+# @websocket@        -- note: corresponds to default domain @ws.${CLUSTER}.${DOMAIN}@
+# @keepproxy@        -- note: corresponds to default domain @keep.${CLUSTER}.${DOMAIN}@
+# @download@         -- Part of keepweb
+# @collections@      -- Part of keepweb, must be a wildcard for @*.collections.${CLUSTER}.${DOMAIN}@
 # @workbench@
 # @workbench2@
 # @webshell@
 
-For example, for the 'keepproxy' service the script will expect to find this certificate:
+For example, for the @keepproxy@ service the script will expect to find this certificate:
 
 
 
${CUSTOM_CERTS_DIR}/keepproxy.crt
diff --git a/doc/_includes/_ssl_config_multi.liquid b/doc/_includes/_ssl_config_multi.liquid
index d001a5f228..b4d6eff616 100644
--- a/doc/_includes/_ssl_config_multi.liquid
+++ b/doc/_includes/_ssl_config_multi.liquid
@@ -4,25 +4,13 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-h2(#certificates). Choose the SSL configuration (SSL_MODE)
+h2(#certificates). Choose the SSL/TLS configuration (SSL_MODE)
 
-Arvados requires an SSL certificate to work correctly. This installer supports these options:
+Arvados requires a valid TLS certificate to work correctly. This installer supports these options:
 
-# @self-signed@: "let the installer create self-signed certificates":#self-signed
 # @lets-encrypt@: "automatically obtain and install an SSL certificates for your hostnames":#lets-encrypt
 # @bring-your-own@: "supply your own certificates in the @certs@ directory":#bring-your-own
 
-h3(#self-signed). Using self-signed certificates
-
-To make the installer use self-signed certificates, change the configuration like this:
-
-
-
SSL_MODE="self-signed"
-

-
-
-Before connecting to the Arvados web interface for the first time, anyone accessing the instance will need to "install the self-signed root certificate in their browser.":#ca_root_certificate
-
 h3(#lets-encrypt). Using a Let's Encrypt certificate
 
 In the default configuration, this installer gets a valid certificate via Let's Encrypt. If you have the CLUSTER.DOMAIN domain in a route53 zone, you can set USE_LETSENCRYPT_ROUTE53 to YES and supply appropriate credentials so that Let's Encrypt can use dns-01 validation to get the appropriate certificates.
diff --git a/doc/_includes/_supportedlinux.liquid b/doc/_includes/_supportedlinux.liquid
new file mode 100644
index 0000000000..08a20750c7
--- /dev/null
+++ b/doc/_includes/_supportedlinux.liquid
@@ -0,0 +1,15 @@
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+table(table table-bordered table-condensed).
+|_. *Supported Linux Distributions*|
+|CentOS 7|
+|Debian 11 ("bullseye")|
+|Debian 10 ("buster")|
+|Ubuntu 20.04 ("focal")|
+|Ubuntu 18.04 ("bionic")|
+
+Arvados packages are published for current Debian releases (until the EOL date), current Ubuntu LTS releases (until the end of standard support), and the latest version of CentOS.
diff --git a/doc/admin/upgrading.html.textile.liquid b/doc/admin/upgrading.html.textile.liquid
index 7ee8fbb08a..cfdae50eb2 100644
--- a/doc/admin/upgrading.html.textile.liquid
+++ b/doc/admin/upgrading.html.textile.liquid
@@ -45,15 +45,9 @@ h2(#v2_4_3). v2.4.3 (2022-09-21)
 
 h3. Fixed PAM authentication security vulnerability
 
-In Arvados 2.4.2 and earlier, when using PAM authentication, if a user
-presented valid credentials but the account is disabled or otherwise
-not allowed to access the host, it would still be accepted for access
-to Arvados.  From 2.4.3 onwards, Arvados now also checks that the
-account is permitted to access the host before completing the PAM login
-process.
-
-Other authentication methods (LDAP, OpenID Connect) are not affected
-by this flaw.
+In Arvados 2.4.2 and earlier, when using PAM authentication, if a user presented valid credentials but the account is disabled or otherwise not allowed to access the host, it would still be accepted for access to Arvados.  From 2.4.3 onwards, Arvados now also checks that the account is permitted to access the host before completing the PAM login process.
+
+Other authentication methods (LDAP, OpenID Connect) are not affected by this flaw.
 
 h2(#v2_4_2). v2.4.2 (2022-08-09)
 
diff --git a/doc/install/arvbox.html.textile.liquid b/doc/install/arvbox.html.textile.liquid
index 378fcc8f8d..52dec90671 100644
--- a/doc/install/arvbox.html.textile.liquid
+++ b/doc/install/arvbox.html.textile.liquid
@@ -11,23 +11,50 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 
 Arvbox is a Docker-based self-contained development, demonstration and testing environment for Arvados.  It is not intended for production use.
 
+h2. Requirements
+
+* Linux 3.x+ and Docker 1.10+
+* Minimum of 4 GiB of RAM  + additional memory to run jobs
+* Minimum of 4 GiB of disk + storage for actual data
+
 h2. Quick start
 
+{% include 'branchname' %}
+
+
+
$ curl -O https://git.arvados.org/arvados.git/blob_plain/refs/heads/{{branchname}}:/tools/arvbox/bin/arvbox
+$ chmod +x arvbox
+$ ./arvbox start localdemo
+
+Arvados-in-a-box starting
+
+Waiting for workbench2 websockets workbench webshell keep-web controller keepproxy api keepstore1 arv-git-httpd keepstore0 sdk vm ...
+...
+
+Your Arvados-in-a-box is ready!
+
+$ ./arvbox adduser demouser demo@example.com
+Password for demouser:
+Added demouser
+

+
+
+You will then need to "install the arvbox root certificate":#root-cert .  After that, you can now log in to Workbench as @demouser@ with the password you selected.
+
+h2(#root-cert). Install root certificate
+
+Arvbox creates root certificate to authorize Arvbox services.  Installing the root certificate into your web browser will prevent security errors when accessing Arvbox services with your web browser.  Every  Arvbox instance generates a new root signing key.
+
+Export the root certificate with this command:
+
 
-$ curl -O https://git.arvados.org/arvados.git/blob_plain/refs/heads/{{ branchname }}:/tools/arvbox/bin/arvbox
-$ chmod +x arvbox
-$ ./arvbox start localdemo
 $ ./arvbox root-cert
-$ ./arvbox adduser demouser demo@example.com
+Certificate copied to /home/ubuntu/arvbox-root-cert.crt
 

 
-You will then need to "install the arvbox root certificate":#root-cert .  After that, you can now log in to Workbench as @demouser@ with the password you selected.
-
-h2. Requirements
+{% assign ca_cert_name = 'arvbox-root-cert.crt' %}
 
-* Linux 3.x+ and Docker 1.10+
-* Minimum of 3 GiB of RAM  + additional memory to run jobs
-* Minimum of 3 GiB of disk + storage for actual data
+{% include 'install_ca_cert' %}
 
 h2. Usage
 
@@ -62,43 +89,13 @@ pipe               run a bash script piped in from stdin
 sv  
                    change state of service inside arvbox
 clone    clone dev arvbox
-adduser  
+adduser   [password]
                    add a user login
 removeuser 
                    remove user login
 listusers          list user logins
 

 
-h2(#root-cert). Install root certificate
-
-Arvbox creates root certificate to authorize Arvbox services.  Installing the root certificate into your web browser will prevent security errors when accessing Arvbox services with your web browser.  Every  Arvbox instance generates a new root signing key.
-
-# Export the certificate using @arvbox root-cert@
-# Go to the certificate manager in your browser.
-#* In Chrome, this can be found under "Settings → Advanced → Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar.
-#* In Firefox, this can be found under "Preferences → Privacy & Security" or entering @about:preferences#privacy@ in the URL bar and then choosing "View Certificates...".
-# Select the "Authorities" tab, then press the "Import" button.  Choose @arvbox-root-cert.pem@
-
-The certificate will be added under the "Arvados testing" organization as "arvbox testing root CA".
-
-To access your Arvbox instance using command line clients (such as arv-get and arv-put) without security errors, install the certificate into the OS certificate storage.
-
-h3. On Debian/Ubuntu:
-
-
-
cp arvbox-root-cert.pem /usr/local/share/ca-certificates/
-/usr/sbin/update-ca-certificates
-

-
-
-h3. On CentOS:
-
-
-
cp arvbox-root-cert.pem /etc/pki/ca-trust/source/anchors/
-/usr/bin/update-ca-trust
-

-
-
 h2. Configs
 
 h3. dev
diff --git a/doc/install/configure-s3-object-storage.html.textile.liquid b/doc/install/configure-s3-object-storage.html.textile.liquid
index e9866d5103..6a10a39925 100644
--- a/doc/install/configure-s3-object-storage.html.textile.liquid
+++ b/doc/install/configure-s3-object-storage.html.textile.liquid
@@ -9,10 +9,15 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-Keepstore can store data in object storage compatible with the S3 API, such as Amazon S3, Google Cloud Storage, or Ceph RADOS.
+Keepstore can store data in object storage compatible with the S3 API, such as Amazon S3, Google Cloud Storage, Ceph RADOS, NetApp StorageGRID, and others.
 
 Volumes are configured in the @Volumes@ section of the cluster configuration file.
 
+# "Configuration example":#example
+# "IAM Policy":#IAM
+
+h2(#example). Configuration example
+
 {% include 'assign_volume_uuid' %}
 
 
    Volumes:
@@ -120,3 +125,24 @@ Two S3 drivers are available. Historically, Arvados has used the @goamz@ driver
 The @aws-sdk-go-v2@ does not support the old S3 v2 signing algorithm. This will not affect interacting with AWS S3, but it might be an issue when Keep is backed by a very old version of a third party S3-compatible service.
 
 The @aws-sdk-go-v2@ driver can improve read performance by 50-100% over the @goamz@ driver, but it has not had as much production use. See the "wiki":https://dev.arvados.org/projects/arvados/wiki/Keep_real_world_performance_numbers for details.
+
+h2(#IAM). IAM Policy
+
+On Amazon, VMs which will access the S3 bucket (these include keepstore and compute nodes) will need an IAM policy with "permission that can read, write, list and delete objects in the bucket":https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html .  Here is an example policy:
+
+
+
+{
+    "Id": "arvados-keepstore policy",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                  "s3:*"
+            ],
+            "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume"
+        }
+    ]
+}
+

+
diff --git a/doc/install/index.html.textile.liquid b/doc/install/index.html.textile.liquid
index eebc0ab7d3..b37ddc7484 100644
--- a/doc/install/index.html.textile.liquid
+++ b/doc/install/index.html.textile.liquid
@@ -13,13 +13,14 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 This section is about installing an Arvados cluster.  If you are just looking to install Arvados client tools and libraries, "go to the SDK section.":{{site.baseurl}}/sdk/
 {% include 'notebox_end' %}
 
-Arvados components run on GNU/Linux systems, and supports AWS, GCP and Azure cloud platforms as well as on-premises installs.  Arvados supports Debian and derivatives such as Ubuntu, as well as Red Hat and derivatives such as CentOS.  "Arvados is Free Software":{{site.baseurl}}/user/copying/copying.html and self-install installations are not limited in any way.  Commercial support and development are also available from "Curii Corporation.":mailto:info@curii.com
+Arvados components run on supported GNU/Linux distributions. The Arvados elastic compute management layer supports Amazon Web Services (AWS) and Microsoft Azure cloud platforms as well as on-premises installs using SLURM and IBM Spectrum LSF.  The Arvados storage layer supports filesystem storage (including NFS, such as IBM GPFS), Azure blob storage, Amazon S3, and systems that offer an S3-compatible API such as Ceph Object Gateway and NetApp StorageGRID.
+
+"Arvados is Free Software":{{site.baseurl}}/user/copying/copying.html and self-install installations are not limited in any way.  Commercial support and development are also available from "Curii Corporation.":https://www.curii.com/
 
 Arvados components can be installed and configured in a number of different ways.
 
 

 table(table table-bordered table-condensed).
-|||\5=. Appropriate for|
 ||_. Setup difficulty|_. Arvados Evaluation|_. Workflow Development|_. Production at Scale|
 |"Arvados-in-a-box":arvbox.html (arvbox)|Easy|yes|limited|no|
 |"Arados Installer":salt-single-host.html (single host)|Easy|yes|limited|no|
@@ -28,4 +29,4 @@ table(table table-bordered table-condensed).
 |"Cluster Operation Subscription supported by Curii":https://curii.com|N/A ^1^|yes|yes|yes|
 

 
-* ^1^ No user installation necessary, Curii run and managed
+^1^ No user installation necessary.  Curii engineers will install and configure Arvados in your own infrastructure.
diff --git a/doc/install/salt-multi-host.html.textile.liquid b/doc/install/salt-multi-host.html.textile.liquid
index fc432cb372..985161e480 100644
--- a/doc/install/salt-multi-host.html.textile.liquid
+++ b/doc/install/salt-multi-host.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: installguide
-title: Multi host Arvados
+title: Multi-Host Arvados
 ...
 {% comment %}
 Copyright (C) The Arvados Authors. All rights reserved.
@@ -17,17 +17,15 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 # "Edit local.params":#localparams
 # "Configure Keep storage":#keep
 # "Choose the SSL configuration":#certificates
-## "Using a self-signed certificates":#self-signed
 ## "Using a Let's Encrypt certificates":#lets-encrypt
 ## "Bring your own certificates":#bring-your-own
 # "Create a compute image":#create_a_compute_image
-# "Further customization of the installation":#further_customization
 # "Begin installation":#installation
+# "Further customization of the installation":#further_customization
 # "Confirm the cluster is working":#test-install
 ## "Debugging issues":#debugging
 ## "Iterating on config changes":#iterating
 ## "Common problems and solutions":#common-problems
-# "Install the CA root certificate":#ca_root_certificate
 # "Initial user and login":#initial_user
 # "After the installation":#post_install
 
@@ -57,26 +55,9 @@ When you do so, you need to configure a couple of additional things:
 
 h3(#keep-bucket). S3 Bucket (AWS specific)
 
-We recommend "creating an S3 bucket":https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html for data storage named @${CLUSTER}-nyw5e-000000000000000-volume@
-
-Then create an IAM role called @${CLUSTER}-keepstore-00-iam-role@ which has "permission to read and write the bucket":https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html .  Here is an example policy:
+We recommend "creating an S3 bucket":https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html for data storage named @${CLUSTER}-nyw5e-000000000000000-volume@.  We recommend creating an IAM role called @${CLUSTER}-keepstore-00-iam-role@ with a "policy that can read, write, list and delete objects in the bucket":configure-s3-object-storage.html#IAM .  With the example cluster id @xargv1@ the bucket would be called @xarv1-nyw5e-000000000000000-volume@ and the role would be called @xarv1-keepstore-00-iam-role@.
 
-
-
-{
-    "Id": "arvados-keepstore policy",
-    "Statement": [
-        {
-            "Effect": "Allow",
-            "Action": [
-                  "s3:*"
-            ],
-            "Resource": "arn:aws:s3:::xarv1-nyw5e-000000000000000-volume"
-        }
-    ]
-}
-

-
+These names are recommended because they are default names used in the configuration template.  If you use different names, you will need to edit the configuration template later.
 
 h2(#hosts). Required hosts
 
@@ -84,7 +65,7 @@ You will need to allocate several hosts (physical or virtual machines) for the f
 
 {% include 'supportedlinux' %}
 
-Allocate the following hosts as appropriate for your site.  On AWS you may choose to do it manually with the AWS console, or using a DevOps tool such as CloudFormation or Terraform.
+Allocate the following hosts as appropriate for your site.  On AWS you may choose to do it manually with the AWS console, or using a DevOps tool such as CloudFormation or Terraform.  With the exception of "keep0" and "keep1", all of these hosts should have external (public) IP addresses if you intend for them to be accessible outside of the private network or VPC.
 
 The installer will set up the Arvados services on your machines.  Here is the default assignment of services to machines:
 
@@ -107,28 +88,35 @@ The installer will set up the Arvados services on your machines.  Here is the de
 # SHELL node  (optional)
 ## arvados shell       (recommended hostname @shell.${CLUSTER}.${DOMAIN}@)
 
-Additional prerequisites when preparing machines to run the installer:
-
-# root or passwordless sudo access
-# from the account where you are performing the install, passwordless @ssh@ to each machine (meaning, the client's public key added to @~/.ssh/authorized_keys@ on each node)
+h3(#DNS). DNS hostnames for each service
+
+You will need a DNS entry for each service.  In the default configuration these are:
+
+# @controller.${CLUSTER}.${DOMAIN}@
+# @ws.${CLUSTER}.${DOMAIN}@
+# @keep0.${CLUSTER}.${DOMAIN}@
+# @keep1.${CLUSTER}.${DOMAIN}@
+# @keep.${CLUSTER}.${DOMAIN}@
+# @download.${CLUSTER}.${DOMAIN}@
+# @*.collections.${CLUSTER}.${DOMAIN}@  -- important note, this must be a wildcard DNS, resolving to the @keepweb@ service
+# @workbench.${CLUSTER}.${DOMAIN}@
+# @workbench2.${CLUSTER}.${DOMAIN}@
+# @webshell.${CLUSTER}.${DOMAIN}@
+# @shell.${CLUSTER}.${DOMAIN}@
+
+h3. Additional prerequisites when preparing machines to run the installer
+
+# from the account where you are performing the install, passwordless @ssh@ to each machine
+This means the client's public key should added to @~/.ssh/authorized_keys@ on each node.
+# passwordless @sudo@ access on the account on each machine you will @ssh@ in to
+This usually means adding the account to the @sudo@ group and having a rule like this in @/etc/sudoers.d/arvados_passwordless@ that allows members of group @sudo@ to execute any command without entering a password.
+
%sudo ALL=(ALL:ALL) NOPASSWD:ALL

 # @git@ installed on each machine
 # port 443 reachable by clients
-# DNS hostnames for each service
-## @controller.${CLUSTER}.${DOMAIN}@
-## @ws.${CLUSTER}.${DOMAIN}@
-## @keep0.${CLUSTER}.${DOMAIN}@
-## @keep1.${CLUSTER}.${DOMAIN}@
-## @keep.${CLUSTER}.${DOMAIN}@
-## @download.${CLUSTER}.${DOMAIN}@
-## @*.collections.${CLUSTER}.${DOMAIN}@  -- important note, this should be a wildcard DNS, going to the keepweb service
-## @workbench.${CLUSTER}.${DOMAIN}@
-## @workbench2.${CLUSTER}.${DOMAIN}@
-## @webshell.${CLUSTER}.${DOMAIN}@
-## @shell.${CLUSTER}.${DOMAIN}@
-
-(AWS specific) The machine that runs the arvados cloud dispatcher will need an "IAM role that allows it to create EC2 instances, see here for details .":{{site.baseurl}}/install/crunch2-cloud/install-dispatch-cloud.html
-
-If your infrastructure differs from the setup proposed above (ie, different hostnames, or using an external DB server such as AWS RDS), you can still use the installer, but "additional customization may be necessary":#further_customization .
+
+(AWS specific) The machine that runs the arvados cloud dispatcher will need an "IAM role that allows it to manage EC2 instances.":{{site.baseurl}}/install/crunch2-cloud/install-dispatch-cloud.html#IAM
+
+If your infrastructure differs from the setup proposed above (ie, different hostnames), you can still use the installer, but "additional customization may be necessary":#further_customization .
 
 h2(#download). Download the installer
 
@@ -142,7 +130,7 @@ This can be found wherever you choose to initialize the install files (@~/setup-
 
 # Set @CLUSTER@ to the 5-character cluster identifier (e.g "xarv1")
 # Set @DOMAIN@ to the base DNS domain of the environment, e.g. "example.com"
-# Edit Internal IP settings. Since services share hosts, some hosts are the same.
+# Edit Internal IP settings. Since services share hosts, some hosts are the same.  See "note about /etc/hosts":#etchosts
 # Edit @CLUSTER_INT_CIDR@, this should be the CIDR of the private network that Arvados is running on, e.g. the VPC.
 CIDR stands for "Classless Inter-Domain Routing" and describes which portion of the IP address that refers to the network.  For example 192.168.3.0/24 means that the first 24 bits are the network (192.168.3) and the last 8 bits are a specific host on that network.
 _AWS Specific: Go to the AWS console and into the VPC service, there is a column in this table view of the VPCs that gives the CIDR for the VPC (IPv4 CIDR)._
@@ -153,62 +141,46 @@ _AWS Specific: Go to the AWS console and into the VPC service, there is a column
   tr -dc A-Za-z0-9 

-# Set @DATABASE_PASSWORD@ to a random string
+# Set @DATABASE_PASSWORD@ to a random string (unless you "already have a database":#ext-database then you should set it to that database's password)
    Important! If this contains any non-alphanumeric characters, in particular ampersand ('&'), it is necessary to add backslash quoting.
-   For example, if the password is `Cq&WUDATABASE_PASSWORD="Cq\&WU\

+
DATABASE_PASSWORD="Lq\&MZ\

 
-h2(#keep). Configure Keep storage
+h3(#etchosts). Note on @/etc/hosts@
 
-The @multi_host/aws@ template uses S3 for storage.  Arvados also supports "filesystem storage":configure-fs-storage.html and "Azure blob storage":configure-azure-blob-storage.html .  Keep storage configuration can be found in in the section @arvados.cluster.Volumes@ of @local_config_dir/pillars/arvados.sls@.
+Because Arvados services are typically accessed by external clients, they are likely to have both a public IP address and a internal IP address.
 
-h3. Object storage in S3 (AWS Specific)
+On cloud providers such as AWS, sending internal traffic to a service's public IP address can incur egress costs and throttling.  Thus it is very important for internal traffic to stay on the internal network.  The installer implements this by updating @/etc/hosts@ on each node to associate each service's hostname with the internal IP address, so that when Arvados services communicate with one another, they always use the internal network address.  This is NOT a substitute for DNS, you still need to set up DNS names for all of the services that have public IP addresses (it does, however, avoid a complex "split-horizon" DNS configuration).
 
-Open @local_config_dir/pillars/arvados.sls@ and edit as follows:
+It is important to be aware of this because if you mistype the IP address for any of the @*_INT_IP@ variables, hosts may unexpectedly fail to be able to communicate with one another.  If this happens, check and edit as necessary the file @/etc/hosts@ on the host that is failing to make an outgoing connection.
 
-# In the @arvados.cluster.Volumes@ section, set @Region@ to the appropriate AWS region (e.g. 'us-east-1')
-# Set @Bucket@ to the value of "keepstore role you created earlier":#keep-bucket
-# Set @IAMRole@ to "keepstore role you created earlier":#keep-bucket
-
-{% include 'ssl_config_multi' %}
-
-h2(#create_a_compute_image). Create a compute image
-
-{% include 'branchname' %}
-
-On cloud installations, containers are dispatched in Docker daemons running in the _compute instances_, which need some additional setup.
+h2(#keep). Configure Keep storage
 
-*Start by following "the instructions build a cloud compute node image":{{site.baseurl}}/install/crunch2-cloud/install-compute-node.html using the "compute image builder script":https://github.com/arvados/arvados/tree/{{ branchname }}/tools/compute-images* .
+The @multi_host/aws@ template uses S3 for storage.  Arvados also supports "filesystem storage":configure-fs-storage.html and "Azure blob storage":configure-azure-blob-storage.html .  Keep storage configuration can be found in in the @arvados.cluster.Volumes@ section of @local_config_dir/pillars/arvados.sls@.
 
-Once you have that image created, Open @local_config_dir/pillars/arvados.sls@ and edit as follows (AWS specific settings described here, configuration for Azure is similar):
+h3. Object storage in S3 (AWS Specific)
 
-# In the @arvados.cluster.Containers.CloudVMs@ section:
-## Set @ImageID@ to the AMI produced by Packer
-## Set @Region@ to the appropriate AWS region
-## Set @AdminUsername@ to the admin user account on the image
-## Set the @SecurityGroupIDs@ list to the VPC security group which you set up to allow SSH connections to these nodes
-## Set @SubnetID@ to the value of SubnetId of your VPC
-# Update @arvados.cluster.Containers.DispatchPrivateKey@ and paste the contents of the @~/.ssh/id_dispatcher@ file you generated in an earlier step.
-# Update @arvados.cluster.InstanceTypes@ as necessary. If m5/c5 node types are not available, replace them with m4/c4. You'll need to double check the values for Price and IncludedScratch/AddedScratch for each type that is changed.
+Open @local_config_dir/pillars/arvados.sls@ and edit as follows:
 
-h2(#further_customization). Further customization of the installation (optional)
+# In the @arvados.cluster.Volumes.DriverParameters@ section, set @Region@ to the appropriate AWS region (e.g. 'us-east-1')
 
-If you are installing on AWS and following the naming conventions recommend in this guide, then likely no further configuration is necessary and you can begin installation.
+If you did not "follow the recommendend naming scheme":#keep-bucket for either the bucket or role, you'll need to update these parameters as well:
 
-A couple of common customizations are described here.  Other changes may require editing the Saltstack pillars and states files found in @local_config_dir@.  In particular, @local_config_dir/pillars/arvados.sls@ has the template used to produce the Arvados configuration file that is distributed to all the nodes.
+# Set @Bucket@ to the value of "keepstore bucket you created earlier":#keep-bucket
+# Set @IAMRole@ to "keepstore role you created earlier":#keep-bucket
 
-Any extra salt _state_ files you add under @local_config_dir/states@ will be added to the salt run and applied to the hosts.
+{% include 'ssl_config_multi' %}
 
-h3(#authentication). Using a different authentication provider
+h2(#authentication). Configure your authentication provider (optional, recommended)
 
 By default, the installer will use the "Test" provider, which is a list of usernames and cleartext passwords stored in the Arvados config file.  *This is low security configuration and you are strongly advised to configure one of the other "supported authentication methods":setup-login.html* .
 
-h3(#ext-database). Using an external database (optional)
+h2(#ext-database). Using an external database (optional)
 
-Arvados requires a database that is compatible with PostgreSQL 9.5 or later.
+The standard behavior of the installer is to install and configure PostgreSQL for use by Arvados.  You can optionally configure it to use a separately managed database instead.
 
-For example, Arvados is known to work with Amazon Aurora (note: even idle, Arvados constantly accesses the database, so we strongly advise using "provisioned" mode).
+Arvados requires a database that is compatible with PostgreSQL 9.5 or later.  For example, Arvados is known to work with Amazon Aurora (note: even idle, Arvados services will periodically poll the database, so we strongly advise using "provisioned" mode).
 
 # In @local.params@, remove 'database' from the list of roles assigned to the controller node:
 
NODES=(
@@ -222,19 +194,45 @@ For example, Arvados is known to work with Amazon Aurora (note: even idle, Arvad
 # In @local.params@, set @DATABASE_PASSWORD@ to the correct value.  "See the previous section describing correct quoting":#localparams
 # In @local_config_dir/pillars/arvados.sls@ you may need to adjust the database name and user.  This can be found in the section @arvados.cluster.database@.
 
+h2(#further_customization). Further customization of the installation (optional)
+
+If you are installing on AWS and have followed all of the naming conventions recommend in this guide, you probably don't need to do any further customization.
+
+If you are installing on a different cloud provider or on HPC, other changes may require editing the Saltstack pillars and states files found in @local_config_dir@.  In particular, @local_config_dir/pillars/arvados.sls@ contains the template (in the @arvados.cluster@ section) used to produce the Arvados configuration file that is distributed to all the nodes.  Consult the "Configuration reference":config.html for a comprehensive list of configuration keys.
+
+Any extra Salt "state" files you add under @local_config_dir/states@ will be added to the Salt run and applied to the hosts.
+
+h2(#create_a_compute_image). Create a compute image
+
+{% include 'branchname' %}
+
+On cloud installations, containers are dispatched in Docker daemons running in the _compute instances_, which need some additional setup.  If you will use a HPC scheduler such as SLURM you can skip this section.
+
+*Start by following "the instructions to build a cloud compute node image":{{site.baseurl}}/install/crunch2-cloud/install-compute-node.html using the "compute image builder script":https://github.com/arvados/arvados/tree/{{ branchname }}/tools/compute-images* .
+
+Once you have that image created, Open @local_config_dir/pillars/arvados.sls@ and edit as follows (AWS specific settings described here, other cloud providers will have similar settings in their respective configuration section):
+
+# In the @arvados.cluster.Containers.CloudVMs@ section:
+## Set @ImageID@ to the AMI produced by Packer
+## Set @DriverParameters.Region@ to the appropriate AWS region
+## Set @DriverParameters.AdminUsername@ to the admin user account on the image
+## Set the @DriverParameters.SecurityGroupIDs@ list to the VPC security group which you set up to allow SSH connections to these nodes
+## Set @DriverParameters.SubnetID@ to the value of SubnetId of your VPC
+# Update @arvados.cluster.Containers.DispatchPrivateKey@ and paste the contents of the @~/.ssh/id_dispatcher@ file you generated in an earlier step.
+# Update @arvados.cluster.InstanceTypes@ as necessary.  The example instance types are for AWS, other cloud providers will of course have different instance types with different names and specifications.
+(AWS specific) If m5/c5 node types are not available, replace them with m4/c4. You'll need to double check the values for Price and IncludedScratch/AddedScratch for each type that is changed.
+
 h2(#installation). Begin installation
 
 At this point, you are ready to run the installer script in deploy mode that will conduct all of the Arvados installation.
 
-Run this in @~/arvados-setup-xarv1@:
+Run this in the @~/arvados-setup-xarv1@ directory:
 
 
 ./installer.sh deploy
 

 
-This will deploy all the nodes.  It will take a while and produce a lot of logging.  If it runs into an error, it will stop.
-
-{% include 'install_ca_cert' %}
+This will install and configure Arvados on all the nodes.  It will take a while and produce a lot of logging.  If it runs into an error, it will stop.
 
 h2(#test-install). Confirm the cluster is working
 
@@ -242,9 +240,9 @@ When everything has finished, you can run the diagnostics.
 
 Depending on where you are running the installer, you need to provide @-internal-client@ or @-external-client@.
 
-If you are running the diagnostics from one of the Arvados machines inside the VPC, you want @-internal-client@ .
+If you are running the diagnostics from one of the Arvados machines inside the private network, you want @-internal-client@ .
 
-You are an "external client" if you running the diagnostics from your workstation outside of the VPC.
+You are an "external client" if you running the diagnostics from your workstation outside of the private network.
 
 
 ./installer.sh diagnostics (-internal-client|-external-client)
@@ -252,6 +250,8 @@ You are an "external client" if you running the diagnostics from your workstatio
 
 h3(#debugging). Debugging issues
 
+The installer records log files for each deployment.
+
 Most service logs go to @/var/log/syslog@.
 
 The logs for Rails API server and for Workbench can be found in
@@ -292,7 +292,7 @@ If this happens, you need to
 
 1. correct the database information
 2. run @./installer.sh deploy xarv1.example.com@ to update the configuration on the API/controller node
-3. On the API/controller server node, run this command to re-run the post-install script, which will set up the database:
+3. Log in to the API/controller server node, then run this command to re-run the post-install script, which will set up the database:
 
 
 dpkg-reconfigure arvados-api-server
@@ -310,9 +310,9 @@ At this point you should be able to log into the Arvados cluster. The initial UR
 
 https://workbench.${CLUSTER}.${DOMAIN}
 
-If you did not "configure a different authentication provider":#authentication you will be using the "Test" provider, and the provision script creates an initial user for testing purposes. This user is configured as administrator of the newly created cluster.  It uses the values of @INITIAL_USER@ and @INITIAL_USER_PASSWORD@ the @local.params@ file.
+If you did *not* "configure a different authentication provider":#authentication you will be using the "Test" provider, and the provision script creates an initial user for testing purposes. This user is configured as administrator of the newly created cluster.  It uses the values of @INITIAL_USER@ and @INITIAL_USER_PASSWORD@ the @local.params@ file.
 
-If you did configure a different authentication provider, the first user to log in will automatically be given Arvados admin privileges.
+If you *did* configure a different authentication provider, the first user to log in will automatically be given Arvados admin privileges.
 
 h2(#post_install). After the installation
 
@@ -320,6 +320,6 @@ As part of the operation of @installer.sh@, it automatically creates a @git@ rep
 
 As described in "Iterating on config changes":#iterating you may use @installer.sh deploy@ to re-run the Salt to deploy configuration changes and upgrades.  However, be aware that the configuration templates created for you by @installer.sh@ are a snapshot which are not automatically kept up to date.
 
-When deploying upgrades, consult the "Arvados upgrade notes":{{site.baseurl}}/admin/upgrading.html to see if changes need to be made to the configuration file template in @local_config_dir/pillars/arvados.sls@.
+When deploying upgrades, consult the "Arvados upgrade notes":{{site.baseurl}}/admin/upgrading.html to see if changes need to be made to the configuration file template in @local_config_dir/pillars/arvados.sls@.  To specify the version to upgrade to, set the @VERSION@ parameter in @local.params@.
 
 See also "Maintenance and upgrading":{{site.baseurl}}/admin/maintenance-and-upgrading.html for more information.
diff --git a/doc/install/salt-single-host.html.textile.liquid b/doc/install/salt-single-host.html.textile.liquid
index ef1633b340..aab2c9968e 100644
--- a/doc/install/salt-single-host.html.textile.liquid
+++ b/doc/install/salt-single-host.html.textile.liquid
@@ -85,6 +85,14 @@ arvados: Failed:      0
 

 
 
+h2(#ca_root_certificate). Install the CA root certificate (SSL_MODE=self-signed only)
+
+*If you are not using self-signed certificates (you selected SSL_MODE=lets-encrypt or SSL_MODE=bring-your-own), skip this section.*
+
+Arvados uses SSL to encrypt communications. The web interface uses AJAX which will silently fail if the certificate is not valid or signed by an unknown Certification Authority.
+
+For this reason, the @arvados-formula@ has a helper state to create a root certificate to authorize Arvados services. The @provision.sh@ script will leave a copy of the generated CA's certificate (@arvados-snakeoil-ca.pem@) in the script's directory so you can add it to your workstation.
+
 {% include 'install_ca_cert' %}
 
 h2(#initial_user). Initial user and login
diff --git a/tools/salt-install/installer.sh b/tools/salt-install/installer.sh
index e5ff7be4e7..91ade4212d 100755
--- a/tools/salt-install/installer.sh
+++ b/tools/salt-install/installer.sh
@@ -90,10 +90,12 @@ deploynode() {
 	exit 1
     fi
 
+    logfile=deploy-${NODE}-$(date -Iseconds).log
+
     if [[ "$NODE" = localhost ]] ; then
-	sudo ./provision.sh --config ${CONFIG_FILE} --roles ${ROLES}
+	sudo ./provision.sh --config ${CONFIG_FILE} --roles ${ROLES} 2>&1 | tee $logfile
     else
-	ssh $DEPLOY_USER@$NODE "cd ${GITTARGET} && sudo ./provision.sh --config ${CONFIG_FILE} --roles ${ROLES}"
+	ssh $DEPLOY_USER@$NODE "cd ${GITTARGET} && sudo ./provision.sh --config ${CONFIG_FILE} --roles ${ROLES}" 2>&1 | tee $logfile
     fi
 }
 
@@ -152,7 +154,9 @@ case "$subcmd" in
 	cp -r config_examples/$SLS $SETUPDIR/${CONFIG_DIR}
 
 	cd $SETUPDIR
-	git add *.sh ${CONFIG_FILE} ${CONFIG_DIR} tests
+	echo '*.log' > .gitignore
+
+	git add *.sh ${CONFIG_FILE} ${CONFIG_DIR} tests .gitignore
 	git commit -m"initial commit"
 
 	echo "setup directory initialized, now go to $SETUPDIR, edit '${CONFIG_FILE}' and '${CONFIG_DIR}' as needed, then run 'installer.sh deploy'"
-- 
2.30.2