fix(provision): Document CA certificate purpose and installation

refs #17177

Arvados-DCO-1.1-Signed-off-by: Javier Bértoli <jbertoli@curii.com>

diff --git a/doc/install/arvbox.html.textile.liquid b/doc/install/arvbox.html.textile.liquid
index c01ec61fa02248e59baaf1fa25ce30bde977b815..3c77ade8da5595fd4aff5886fafe0db046a9b97a 100644 (file)
--- a/doc/install/arvbox.html.textile.liquid
+++ b/doc/install/arvbox.html.textile.liquid
@@ -80,10 +80,23 @@ Arvbox creates root certificate to authorize Arvbox services.  Installing the ro
 
 The certificate will be added under the "Arvados testing" organization as "arvbox testing root CA".
 
 
 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 (instructions for Debian/Ubuntu):
+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.

 
 

-# copy @arvbox-root-cert.pem@ to @/usr/local/share/ca-certificates/@
-# run @/usr/sbin/update-ca-certificates@
+h3. On Debian/Ubuntu:
+
+<notextile>
+<pre><code>cp arvbox-root-cert.pem /usr/local/share/ca-certificates/
+/usr/sbin/update-ca-certificates
+</code></pre>
+</notextile>
+
+h3. On CentOS:
+
+<notextile>
+<pre><code>cp arvbox-root-cert.pem /etc/pki/ca-trust/source/anchors/
+/usr/bin/update-ca-trust
+</code></pre>
+</notextile>

 
 h2. Configs
 
 
 h2. Configs
 

diff --git a/doc/install/salt-single-host.html.textile.liquid b/doc/install/salt-single-host.html.textile.liquid
index fb41d59ee2a67745ecb2b1ef163f21a2b79cd44b..5bed6d05e77e8602319ef0f8dd1f8c12c3617dbc 100644 (file)
--- a/doc/install/salt-single-host.html.textile.liquid
+++ b/doc/install/salt-single-host.html.textile.liquid
@@ -11,7 +11,9 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 
 # "Install Saltstack":#saltstack
 # "Single host install using the provision.sh script":#single_host
 
 # "Install Saltstack":#saltstack
 # "Single host install using the provision.sh script":#single_host

-# "DNS configuration":#final_steps
+# "Final steps":#final_steps
+## "DNS configuration":#dns_configuration
+## "Install root certificate":#ca_root_certificate

 # "Initial user and login":#initial_user
 # "Test the installed cluster running a simple workflow":#test_install
 
 # "Initial user and login":#initial_user
 # "Test the installed cluster running a simple workflow":#test_install
 


@@ -49,7 +51,9 @@ arvados: Failed:      0
 </code></pre>
 </notextile>
 
 </code></pre>
 </notextile>
 

-h2(#final_steps). DNS configuration
+h2(#final_steps). Final configuration steps
+
+h3(#dns_configuration). DNS configuration

 
 After the setup is done, you need to set up your DNS to be able to access the cluster.
 
 
 After the setup is done, you need to set up your DNS to be able to access the cluster.
 


@@ -65,6 +69,39 @@ echo "${HOST_IP} api keep keep0 collections download ws workbench workbench2 ${C
 </code></pre>
 </notextile>
 
 </code></pre>
 </notextile>
 

+h3(#ca_root_certificate). Install root certificate
+
+Arvados uses SSL to encrypt communications. Its UI 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 ypu can add it to your workstation.
+
+Installing the root certificate into your web browser will prevent security errors when accessing Arvados services with your web browser.
+
+# Go to the certificate manager in your browser.
+#* In Chrome, this can be found under "Settings &rarr; Advanced &rarr; Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar.
+#* In Firefox, this can be found under "Preferences &rarr; 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 @arvados-snakeoil-ca.pem@
+
+The certificate will be added under the "Arvados Formula".
+
+To access your Arvados instance using command line clients (such as arv-get and arv-put) without security errors, install the certificate into the OS certificate storage.
+
+* On Debian/Ubuntu:
+
+<notextile>
+<pre><code>cp arvados-root-cert.pem /usr/local/share/ca-certificates/
+/usr/sbin/update-ca-certificates
+</code></pre>
+</notextile>
+
+* On CentOS:
+
+<notextile>
+<pre><code>cp arvados-root-cert.pem /etc/pki/ca-trust/source/anchors/
+/usr/bin/update-ca-trust
+</code></pre>
+</notextile>
+

 h2(#initial_user). Initial user and login
 
 At this point you should be able to log into the Arvados cluster.
 h2(#initial_user). Initial user and login
 
 At this point you should be able to log into the Arvados cluster.

diff --git a/doc/install/salt-vagrant.html.textile.liquid b/doc/install/salt-vagrant.html.textile.liquid
index d9aa791f0bad3a5173d6aa9762f2e56359534f5b..ed0d5bca62ed045d307caac880d644747a0141ae 100644 (file)
--- a/doc/install/salt-vagrant.html.textile.liquid
+++ b/doc/install/salt-vagrant.html.textile.liquid
@@ -10,7 +10,9 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
 # "Vagrant":#vagrant
 {% endcomment %}
 
 # "Vagrant":#vagrant

-# "DNS configuration":#final_steps
+# "Final steps":#final_steps
+## "DNS configuration":#dns_configuration
+## "Install root certificate":#ca_root_certificate

 # "Initial user and login":#initial_user
 # "Test the installed cluster running a simple workflow":#test_install
 
 # "Initial user and login":#initial_user
 # "Test the installed cluster running a simple workflow":#test_install
 


@@ -37,7 +39,9 @@ If you want to reconfigure the running box, you can just:
 </code></pre>
 </notextile>
 
 </code></pre>
 </notextile>
 

-h2(#final_steps). DNS configuration
+h2(#final_steps). Final configuration steps
+
+h3(#dns_configuration). DNS configuration

 
 After the setup is done, you need to set up your DNS to be able to access the cluster.
 
 
 After the setup is done, you need to set up your DNS to be able to access the cluster.
 


@@ -53,6 +57,39 @@ echo "${HOST_IP} api keep keep0 collections download ws workbench workbench2 ${C
 </code></pre>
 </notextile>
 
 </code></pre>
 </notextile>
 

+h3(#ca_root_certificate). Install root certificate
+
+Arvados uses SSL to encrypt communications. Its UI 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 ypu can add it to your workstation.
+
+Installing the root certificate into your web browser will prevent security errors when accessing Arvados services with your web browser.
+
+# Go to the certificate manager in your browser.
+#* In Chrome, this can be found under "Settings &rarr; Advanced &rarr; Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar.
+#* In Firefox, this can be found under "Preferences &rarr; 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 @arvados-snakeoil-ca.pem@
+
+The certificate will be added under the "Arvados Formula".
+
+To access your Arvados instance using command line clients (such as arv-get and arv-put) without security errors, install the certificate into the OS certificate storage.
+
+* On Debian/Ubuntu:
+
+<notextile>
+<pre><code>cp arvados-root-cert.pem /usr/local/share/ca-certificates/
+/usr/sbin/update-ca-certificates
+</code></pre>
+</notextile>
+
+* On CentOS:
+
+<notextile>
+<pre><code>cp arvados-root-cert.pem /etc/pki/ca-trust/source/anchors/
+/usr/bin/update-ca-trust
+</code></pre>
+</notextile>
+

 h2(#initial_user). Initial user and login
 
 At this point you should be able to log into the Arvados cluster.
 h2(#initial_user). Initial user and login
 
 At this point you should be able to log into the Arvados cluster.

diff --git a/tools/salt-install/provision.sh b/tools/salt-install/provision.sh
index 9aa5f19b123eb2894d275e1b05e3a78890dd2c15..7b4fc9da3679f48d440ce2c3d3accafe108ab8b3 100755 (executable)
--- a/tools/salt-install/provision.sh
+++ b/tools/salt-install/provision.sh
@@ -258,7 +258,7 @@ fi
 # END FIXME! #16992 Temporary fix for psql call in arvados-api-server
 
 # Leave a copy of the Arvados CA so the user can copy it where it's required
 # END FIXME! #16992 Temporary fix for psql call in arvados-api-server
 
 # Leave a copy of the Arvados CA so the user can copy it where it's required

-echo "Copying the Arvados CA file to the installer dir, so you can import it"
+echo "Copying the Arvados CA certificate to the installer dir, so you can import it"

 # If running in a vagrant VM, also add default user to docker group
 if [ "x${VAGRANT}" = "xyes" ]; then
   cp /etc/ssl/certs/arvados-snakeoil-ca.pem /vagrant
 # If running in a vagrant VM, also add default user to docker group
 if [ "x${VAGRANT}" = "xyes" ]; then
   cp /etc/ssl/certs/arvados-snakeoil-ca.pem /vagrant