From 7b009edfb17684630028f2277efa5201f11350fa Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20B=C3=A9rtoli?= Date: Fri, 4 Dec 2020 09:17:34 -0300 Subject: [PATCH] fix(provision): Document CA certificate purpose and installation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit refs #17177 Arvados-DCO-1.1-Signed-off-by: Javier Bértoli --- doc/install/arvbox.html.textile.liquid | 19 +++++++-- .../salt-single-host.html.textile.liquid | 41 ++++++++++++++++++- doc/install/salt-vagrant.html.textile.liquid | 41 ++++++++++++++++++- tools/salt-install/provision.sh | 2 +- 4 files changed, 95 insertions(+), 8 deletions(-) diff --git a/doc/install/arvbox.html.textile.liquid b/doc/install/arvbox.html.textile.liquid index c01ec61fa0..3c77ade8da 100644 --- 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". -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: + + +
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 diff --git a/doc/install/salt-single-host.html.textile.liquid b/doc/install/salt-single-host.html.textile.liquid index fb41d59ee2..5bed6d05e7 100644 --- 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 -# "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 @@ -49,7 +51,9 @@ arvados: Failed: 0 -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. @@ -65,6 +69,39 @@ echo "${HOST_IP} api keep keep0 collections download ws workbench workbench2 ${C +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 → 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 @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: + + +
cp arvados-root-cert.pem /usr/local/share/ca-certificates/
+/usr/sbin/update-ca-certificates
+
+ + +* On CentOS: + + +
cp arvados-root-cert.pem /etc/pki/ca-trust/source/anchors/
+/usr/bin/update-ca-trust
+
+ + 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 d9aa791f0b..ed0d5bca62 100644 --- 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 -# "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 @@ -37,7 +39,9 @@ If you want to reconfigure the running box, you can just: -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. @@ -53,6 +57,39 @@ echo "${HOST_IP} api keep keep0 collections download ws workbench workbench2 ${C +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 → 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 @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: + + +
cp arvados-root-cert.pem /usr/local/share/ca-certificates/
+/usr/sbin/update-ca-certificates
+
+ + +* On CentOS: + + +
cp arvados-root-cert.pem /etc/pki/ca-trust/source/anchors/
+/usr/bin/update-ca-trust
+
+ + 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 9aa5f19b12..7b4fc9da36 100755 --- 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 -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 -- 2.30.2