30
May
2016
LetsEncrypt free SSL certificates
### #-### 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 letsencrypt.sh 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/letsencrypt.sh 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|stage|staging).` 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.