SSL.txt

  ###
#-### Let's Encrypt free SSL certificates are supported directly in Aegir
  ###

  You can find these important Let's Encrypt topics discussed below:

  # Introduction
  # Before we begin... what is the most common mistake and how to avoid it?
  # How it works?
  # How to add Letsencrypt.org SSL certificate to hosted site?
  # How to add Letsencrypt.org SSL certificate to the Aegir Hostmaster site?
  # How to modify/renew Letsencrypt.org SSL certificate for SSL enabled site?
  # How to rename a site with SSL enabled?
  # Are there any requirements, limitations or exceptions?
  # How to enable live mode?
  # How to replace Let's Encrypt certificate with custom certificate?
  # How to replace existing custom certificates with Let's Encrypt certificates?
  # How to use Let's Encrypt certificate on the old, dedicated IP address?

BOA-3.1.0 release opens a new era in SSL support for all hosted Drupal sites.
The old method of creating SSL proxy vhosts is officially deprecated,
as explained in this document further below.

* Before we begin... what is the most common mistake and how to avoid it?

  Thinking that you don't need to actually read everything here, and instead
  quickly scanning this documentation, and assuming that you know it already.
  Specifically, people tend to ignore this line, listed in *requirements* below:

  * All aliases must have valid DNS names pointing to your server IP address

  Note that it says *ALL ALIASES* -- not just the aliases you have added!
  This means that also the "Auto Alias" Aegir generates for you -- like
  www.foo.com when your site's name is foo.com, or like foo.com when the main
  site name is www.foo.com -- these aliases also must have a valid DNS,
  already pointing to your Aegir default IP address.

* How it works?

  BOA leverages dehydrated utility to talk to Letsencrypt.org servers,
  and on the Aegir side it's using new `hosting_le` extension, which replaces
  self-signed SSL certificates generated by Aegir with Let's Encrypt ones.
  You can find more information on both at these URLs:

    https://github.com/lukas2511/dehydrated
    https://github.com/omega8cc/hosting_le

* How to add Letsencrypt.org SSL certificate to hosted site?

  In your Aegir control panel please go to the site's node Edit tab, then
  under `SSL Settings > Encryption` choose either `Enabled` or `Required`,
  if you want to enable HTTP->HTTPS redirection on the fly. Now click `Save`
  and wait until you will see the Verify task completed. Done!

  NOTE: SSL Settings are not available in the Add Site form, only in Edit.

* How to add Letsencrypt.org SSL certificate to the Aegir Hostmaster site?

  !!! WARNING
  !!! ###===>>> Don't enable SSL option for the Hostmaster site in Aegir
  !!! WARNING

  Let's Encrypt SSL for Aegir control panel is handled in BOA outside of
  the control panel, and you should never enable it within control panel.

  During octopus upgrade you will see this message, explaining what to do:

    BOA [02:44:59] ==> UPGRADE B: Letsencrypt SSL initial mode: DEMO
    BOA [02:44:59] ==> UPGRADE B: LE -- No real SSL certs will be generated
    BOA [02:44:59] ==> UPGRADE B: LE -- To enable live SSL mode, please delete file:
    BOA [02:44:59] ==> UPGRADE B: LE -- /data/disk/o1/tools/le/.ctrl/ssl-demo-mode.pid
    BOA [02:44:59] ==> UPGRADE B: LE -- Then run octopus forced upgrade

* How to modify/renew Letsencrypt.org SSL certificate for SSL enabled site?

  When you modify aliases or redirections, Aegir will re-create the SSL
  certificate on the fly, to match current settings and aliases to list.

  BOA runs auto-renewal checks for you weekly, and forces renewal if there is
  less than 30 days to the certificate expiration date (Let's Encrypt certs
  are valid for up to 90 days before they have to be renewed).

  Also every Verify task against SSL enabled site runs this check on the fly.

* How to rename a site with SSL enabled?

  If you need to rename a site, you must first disable SSL and alias redirection,
  run the migrate task to rename the site, then re-enable SSL and alias redirection.

  Owing to this requirement, workflows that require renaming sites often, e.g. for
  dev/staging/production environments, are usually better served by moving aliases
  between site clones per https://learn.omega8.cc/how-to-debug-failed-migrate-task-328.

* Are there any requirements, limitations or exceptions?

  Yes, there are some:

  * Let's Encrypt leverages TLS/SNI, which works only with modern browsers
  * Let's Encrypt doesn't support wildcard names
  * All aliases must have valid DNS names pointing to your server IP address
  * Even with aliases redirection enabled all aliases are listed as SAN names

  NOTE: The Subject Alternative Names (SAN) is a feature which allows to issue
  multi-domain / multi-subdomain SSL certificates -- it is automated in BOA.

  Let's Encrypt API for live, real certificates has its own requirements
  and limits you should be aware of. Please visit their website for details:

    https://letsencrypt.org/docs/rate-limits/

  To make this new BOA feature easy to test before you will be ready to
  generate real, live SSL certificates, BOA comes with Let's Encrypt demo
  mode enabled by default, so it will not hit limits enforced for live,
  real Let's Encrypt SSL certificates. It allows to generate "fake" certs,
  similar to self-signed certificate used in BOA by default.

  NOTE: All sites with one or more keywords (listed below) in the site's
  main name, or in their redirection target, if used, will be ignored,
  and they will receive only self-signed SSL certificates generated by Aegir,
  once you will switch their SSL settings to `Enabled` or `Required`.

    `.(dev|devel|temp|tmp|temporary|test|testing).`

  Examples: `foo.temp.bar.org`, `foo.test.bar.org`, `foo.dev.bar.org`

  NOTE: This exception rule doesn't apply to aliases which are not used
  as a redirection target. Even aliases with listed special keywords in their
  names will be listed as SAN entries, as long as they are valid DNS names.

* How to enable live mode?

  It is enough to delete the `[aegir_root]/tools/le/.ctrl/ssl-demo-mode.pid`
  control file and run Verify task on any SSL enabled site again.

  NOTE: If you are on hosted BOA, please create an empty control file instead:
  ~/static/control/ssl-live-mode.info and then wait a few minutes before
  running Verify task. It is a one-time operation, and even if you will delete
  this control file later, the system will not switch your instance back to
  Let's Encrypt demo mode.

  You could switch it back and forth to demo/live mode by adding and deleting
  the control file, and it will re-register your system via Let's Encrypt API,
  but we have not tested how it may affect already generated live certificates
  once you will run the switch many times, so please try not to abuse
  this feature.

  It is important to remember that once you will switch the Let's Encrypt mode
  to demo from live, or from live to demo, by adding or removing the
  `[aegir_root]/tools/le/.ctrl/ssl-demo-mode.pid` control file, it will not
  replace all previously issued certificates instantly, because certificates
  are updated, if needed, only when you (or the BOA system for you during its
  daily maintenance, if used) will run Verify tasks on SSL enabled sites.

  These BOA specific Verify tasks are normally scheduled to run weekly,
  between Monday and Sunday, depending on the first character in the site's
  main name, so both live and demo certificates may still work in parallel
  for SSL enabled sites until it will be their turn to run Verify and update
  the certificate according to currently set Let's Encrypt mode.

  NOTE: You may find some helpful details in the Verify task log -- look for
  lines with `[hosting_le]` prefix.

* How to replace Let's Encrypt certificate with custom certificate?

  1. Create an empty control file (replace `example.com` with your site name):

     `[aegir_root]/tools/le/.ctrl/dont-overwrite-example.com.pid`

  2. Replace `privkey.pem` symlink with single file containing your custom
     certificate key -- use `privkey.pem` as a filename in the directory:

     `[aegir_root]/tools/le/certs/example.com/`

  3. Replace `fullchain.pem` symlink with single file containing your custom
     certificate and all intermediate certificates beneath it -- use
     `fullchain.pem` as a filename in the same directory:

     `[aegir_root]/tools/le/certs/example.com/`

  4. Replace `chain.pem` symlink with single file containing your custom
     intermediate certificates only -- use `chain.pem` as a filename
     in the same directory:

     `[aegir_root]/tools/le/certs/example.com/`

  5. Run Verify task for your site in the Aegir control panel. Done!

  NOTE: If you are on hosted BOA, you don't have an access to this location
  on your system, so please open a ticket at: https://omega8.cc/support

* How to replace existing custom certificates with Let's Encrypt certificates?

  Here are the steps to start using Let's Encrypt certificates on sites
  previously running SSL on dedicated IP as well as shared (default) IP via
  legacy `xboa ssl-gen` command:

  1. Disable all HTTPS redirects, if configured within these sites.

  2. Update DNS for domains using custom certificates to point them to default
     instance/server IP address, if they have used dedicated IP before,
     and run the `service nginx reload` command once DNS update is propagated.

  3. Move away previous HTTP/HTTPS proxy vhosts for those sites, if they
     still exist in the /var/aegir/config/server_master/nginx/pre.d/ directory,
     but only if they already use the default IP address, and reload nginx.

  4. Create an empty ~/static/control/ssl-live-mode.info file and wait 5 min.

  5. Enable SSL in Aegir for those sites.

  NOTE: If you are on hosted BOA, all you need to do are steps: 1, 2, 4 and 5
  from the list above. You don't need to reload nginx, move vhosts, etc.

* How to use Let's Encrypt certificate on the old, dedicated IP address?

  If your old dedicated IP address is still configured within the same system,
  you can still use it like before, because HTTPS vhosts managed by Aegir use
  the wildcard "listen" directive, which enables you to use any active IP
  address available within the same system.

  However, if you have configured the previous dedicated IP within different
  system, like Omega8.cc was doing for its deprecated SSL add-on, so the old
  IP address was used in the remote proxy mode, you can't use it any longer,
  because it will not be managed via Aegir, and we don't offer ability to use
  dedicated IP addresses with Let's Encrypt certificates. You need to migrate
  to the built-in Let's Encrypt support mode, as explained in previous section
  above.