doc/_includes/_ssl_config_single.liquid

   1 {% comment %}
   2 Copyright (C) The Arvados Authors. All rights reserved.
   3
   4 SPDX-License-Identifier: CC-BY-SA-3.0
   5 {% endcomment %}
   6
   7 h2(#certificates). Choose the SSL configuration (SSL_MODE)
   8
   9 Arvados requires an SSL certificate to work correctly. This installer supports these options:
  10
  11 * @self-signed@: let the installer create a self-signed certificate
  12 * @lets-encrypt@: automatically obtain and install an SSL certificate for your hostname
  13 * @bring-your-own@: supply your own certificate in the `certs` directory
  14
  15 h3(#self-signed). Using a self-signed certificate
  16
  17 In the default configuration, this installer uses self-signed certificate(s):
  18
  19 <notextile>
  20 <pre><code>SSL_MODE="self-signed"
  21 </code></pre>
  22 </notextile>
  23
  24 This works everywhere and does not require that you have a domain name.  However, after installation, users will need to "install the self-signed root certificate in the browser.":#ca_root_certificate"
  25
  26 h3(#lets-encrypt). Using a Let's Encrypt certificate
  27
  28 To automatically get a valid certificate via Let's Encrypt, change the configuration like this:
  29
  30 <notextile>
  31 <pre><code>SSL_MODE="lets-encrypt"
  32 </code></pre>
  33 </notextile>
  34
  35 This requires that you have a "real" hostname that you control.  The hostname for your Arvados cluster must be defined in @HOSTNAME_EXT@ and resolve to the public IP address of your Arvados instance, so that Let's Encrypt can validate the domainname ownership and issue the certificate.
  36
  37 When using AWS, EC2 instances can have a default hostname that ends with <i>amazonaws.com</i>. Let's Encrypt has a blacklist of domain names for which it will not issue certificates, and that blacklist includes the <i>amazonaws.com</i> domain, which means the default hostname can not be used to get a certificate from Let's Encrypt.
  38
  39 h3(#bring-your-own). Bring your own certificate
  40
  41 To supply your own certificate, change the configuration like this:
  42
  43 <notextile>
  44 <pre><code>SSL_MODE="bring-your-own"
  45 </code></pre>
  46 </notextile>
  47
  48 Copy your certificate files to the directory specified with the variable @CUSTOM_CERTS_DIR@. The provision script will find it there. The certificate and its key need to be copied to a file named after @HOSTNAME_EXT@. For example, if @HOSTNAME_EXT@ is defined as @my-arvados.example.net@, the script will look for
  49
  50 <notextile>
  51 <pre><code>${CUSTOM_CERTS_DIR}/my-arvados.example.net.crt
  52 ${CUSTOM_CERTS_DIR}/my-arvados.example.net.key
  53 </code></pre>
  54 </notextile>
  55
  56 All certificate files will be used by nginx. You may need to include intermediate certificates in your certificate file. See "the nginx documentation":http://nginx.org/en/docs/http/configuring_https_servers.html#chains for more details.