Summary
This module replaces self-generated Aegir certificates with Let's Encrypt ones.
Initial version developed by @gboudrias
for Advisor Websites.
Improved by @omega8cc
and @helmo
.
Requirements
This module works with Apache and Nginx.
You must have the third-party dehydrated
library uploaded (see Usage).
Quick Start
While it is included in BOA by default, you should be able to add it easily on any Aegir 3.x vanilla system:
-
Upload hosting_le module to profiles/hostmaster/modules/contrib/
-
Create expected directory tree, download the script, and enable demo mode:
$ su -s /bin/bash - aegir
$ mkdir -p /var/aegir/tools/le/.ctrl
$ touch /var/aegir/tools/le/.ctrl/ssl-demo-mode.pid
$ cd /var/aegir/tools/le/
$ wget https://raw.githubusercontent.com/omega8cc/dehydrated/master/dehydrated
$ chmod 0700 dehydrated
-
Enable apache_ssl or nginx_ssl on the server node at /hosting/c/server_master
-
Enable "Hosting LE SSL" and "Hosting LE Vhost" at /admin/hosting (in Experimental)
-
Edit a hosted site node to set SSL to "Enabled" (NOT to "Required", until you enable live LE mode) and make sure to fill the "New encryption key" field with the name of your site, e.g. example.com
-
Wait for the Verify task to run. If it's not all-green, check the task log lines which start with
[hosting_le]
prefix for more information.
Usage
This module depends on the forked dehydrated script and automates almost everything:
- The dehydrated
script expected path is:
[aegir_root]/tools/le/dehydrated
- The
[aegir_root]/tools/le/
directory must be writable by your Aegir system user, typicallyaegir
- Aegir and its config may live in any non-standard directory
or in the canonical
/var/aegir
- The certificate's name in Aegir (and thus its directory) must be the same as the site's name
- Avoid renaming SSL-enabled sites; move aliases between site's clones instead
- Before you rename a site, disable SSL first; then re-enable once it's renamed
- Many useful details can be found also in the BOA specific docs
Caveats
- Let's Encrypt leverages TLS/SNI, which works only with modern browsers
- Let's Encrypt doesn't support wildcard names
- Let's Encrypt doesn't support IDN names (for now)
- All site's aliases must have valid DNS names pointing to your server IP address
Caveats for non-BOA Aegir systems only
- All site's aliases must have valid DNS names pointing to your server IP address, unless redirection is used, and the target has a valid DNS name
- Aliases redirection must be disabled if all aliases are expected to be included as SAN names
- If aliases redirection is enabled, the certificate created will list only the redirection target name
Caveats for BOA Aegir systems only
- This module will ignore sites with special keywords in their names, or in their redirection target (see Exceptions further below)
Let's Encrypt API limits
Let's Encrypt API for live, real certificates has its own requirements and limits you should be aware of.
Please visit Let's Encrypt website for details.
Demo mode
It is recommended to test this module in Let's Encrypt demo mode, so it will not
hit limits enforced for live, real Let's Encrypt SSL certificates. To enable
demo mode, please create an empty control file:
[aegir_root]/tools/le/.ctrl/ssl-demo-mode.pid
To switch the mode to live, delete [aegir_root]/tools/le/.ctrl/ssl-demo-mode.pid
and run Verify task on the SSL enabled site again.
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.
This module will create all required directories it needs to operate on the
first attempt to run site Verify task with SSL option enabled, but you may
want to create at least [aegir_root]/tools/le/.ctrl/
before running it for
the first time, so the demo mode will be active on the first attempt.
This is default behaviour in BOA, which always starts the integration in
demo mode, until the control file is removed.
Read the task log lines which start with [hosting_le]
prefix for more information.
Exceptions for BOA Aegir systems only
The list of keywords to use in the site's main name to have the site ignored by this module:
.(dev|devel|temp|tmp|temporary|test|testing|stage|staging).
Examples: foo.temp.bar.org
, foo.test.bar.org
, foo.dev.bar.org
Custom certificates
This module will regenerate existing symlinks and existing Let's Encrypt key and
certificate, if needed, like when you will update site's aliases or the certificate
will have less than 30 days to expiration date. However, you can safely use another
third-party's certificate if you choose so, replacing the key and certificates
created by Let's Encrypt integration library, if you will create an empty
control file: [aegir_root]/tools/le/.ctrl/dont-overwrite-example.com.pid
Likewise, you can simply put your custom, non-LE certificate in
[aegir_root]/tools/le/certs/example.com/
, though you should know that Aegir
expects openssl.key
and openssl.crt
(or symlinks with these filenames)
to exist, and this module will generate them for you.
Certificates updates and renewals
To renew or update the Let's Encrypt certificate, with all aliases added as Subject Alternative Names (SAN), it is enough to run the Verify task on the SSL enabled site. It's planned to automate this procedure using different methods (implemented in BOA via automated sites Verify tasks).
To know more about dehydrated
usage, please visit:
https://github.com/lukas2511/dehydrated
General Notes
The main important file here is drush/provision_hosting_le.drush.inc
,
which allows us to run code after the Verify as the Aegir user. The www-data
group must not be granted access to dehydrated
and its base directory
[aegir_root]/tools/le/
for security reasons.
The file hosting.feature.le.inc
must be present for Aegir to load
the Provision (Drush) extension, and will do so only if the module is enabled.
License
This project is licensed under the GNU GENERAL PUBLIC LICENSE Version 2, see LICENSE.txt for details.