Instructions on installing and setting up an SSL certificate on a sub/domain with the excellent certbot by EFF.
Assumes you are on a Linux platform.
Download and install certbot
Check your package manager first as most distributions have a certbot package that can be installed directly. Certbot's home page provides an excellent and easy drop-down menu which can be used to find install instructions for your setup.
Alternatively, you can always download and install the latest version of certbot-auto as follows:
sudo wget https://dl.eff.org/certbot-auto
Install (note this is optional and you can run from where you downloaded if you want):
sudo cp certbot-auto /usr/bin/certbot-auto sudo chmod a+x /usr/bin/certbot-auto sudo certbot-auto
Wildcard certificates
certbot recently started providing wildcard SSL certificates (e.g. *.example.com).
Note, currently certbot wildcard certificates might not yet be available for your preferred OS or plug-in (e.g. Ubuntu / apache plug-in). You might still be able to obtain a wildcard SSL certificate manually until your OS/plug-in is supported (which shouldn't be long). The downside of manually obtaining a certificate (wildcard or otherwise) is that it's much harder to implement auto-renewals.
This is what I did recently for my domain registrar that doesn't support certbot directly (boo..). However, they very kindly offer to sell you a DV wildcard cert for only AUD$98.72 per annum (if you haven't noticed I'm using my sarcastic tone...). Thanks, but for a DV SSL and my own managed servers, I'd rather use certbot at no cost (other than my time in renewing quarterly).
In any case, currently (as of writing) to obtain a wildcard cert you'll need to use the --server argument as below
sudo certbot-auto certonly --manual --server https://acme-v02.api.letsencrypt.org/directory
The above command will start the process wherein you can enter your domain (with a wildcard).
NOTE: wildcard domains do NOT include the base domain. Hence, to obtain a SSL cert that covers your domain AND sub-domains enter both the domain and wildcard domain.
For example, I would enter the below for my example.com domain:
example.com *.example.com
With the manual process you'll also likely need to add a temporary (i.e. which you can remove after you've obtained your cert):
- TXT domain record;
- upload a text file for your base domain.
You'll need to ensure that the TXT domain record has been deployed (which can take some time to propagate through DNS servers). I found setting the TXT TTL to 300 seconds helps (my domain registrar had a default TTL of 1600) and means you should only need to wait approximately 5 minutes. You can confirm propagation of the TXT records with the very handy mxtoolbox TXT lookup.
Once certbot has verified you control your domain, it will generate your public and private keys which you can then install via you're domain registrars supported method (which usually means logging into your account and uploading the required information - which is contained in the files certbot generates).
certbot will inform you where your files are stored (generally /etc/letsencrypt). The files are locked own so you'll need to sudo to get them. For me, my domain registrar required the following (see table below with what they required and what certbot files contained that information):
| Certificate (CRT) | cert.pem |
| Private Key (KEY) | privkey.pem |
Certificate Authority Bundle (CABUNDLE) | chain.pem |
You should be all set once you've installed your certbot generated SSL certificate.
Obtain certbot-auto certificate
Apache method
This is my favourite method. It can only be used if your server uses apache reverse proxy setup (as outlined here). Once you've setup your reverse proxy (all excepting the SSL certs for said reverse proxy) simply call:
sudo certbot-auto --apache
Certbot-auto will then provide a menu of vhosts to obtain a certificate for. It will also add the certificate path to your vhost conf file (note it's always best to then double-check your apache conf files to make sure nothing is messed up).
If you would rather just get the certificate (and not have certbot-auto mess with any conf files), do:
sudo certbot-auto --apache certonly
Webroot method
Referenced from the excellent openproject download and configuration guide here.
This method is preferable since it seems 
you do not need to restart the server (apparently?). See below for an example for an OpenProject application sub-domain:
certbot-auto certonly --webroot --webroot-path /opt/openproject/public -d openproject.example.com
Above is example used for openproject where we know the webroot.
Standalone method
Use this method if having any issues (and will likely need to use this method for tomcat installs like Atlassian products).
I think you might have to stop apache2 (and maybe services listening on 443 - if you used this method then should just be apache2).
sudo service apache2 stop
sudo certbot-auto --no-bootstrap certonly --standalone --preferred-challenges tls-sni -d <sub.domain.com>
Note: you can request multiple domains certificates with ... -d sub1.domain.com -d sub2.domain.com etc.
Installs certificates to...
Certificates installed to:
/etc/letsencrypt/live/<sub.domain.com>
You'll likely need to reference this location (and the certs in there) in your application.
Renewing
If you installed using the guide (specific to your system) from https://certbot.eff.org/instructions then automatic renewals will most likely be enabled by default (the instructions at the previous link will state this).
Referenced from the excellent openproject download and configuration guide here.
A letsencryt certificate is only valid for 90 days. To renew call:
sudo certbot-auto renew
To test renewing (whether it would be successful if it was due) run:
sudo certbot-auto renew --dry-run
Apache method renewing
If you use an apache reverse proxy, and used the apache method above to obtain your certificate(s), simplhy add the following entry to your crontab (run 'sudo crontab -e' first):
0 1 * * 7 certbot-auto renew --quiet
Webroot method renewing
If you used the webroot method, to renew your certificate(s) automatically all you have to do is to add the following entry to your crontab (run 'sudo crontab -e' first):
0 1 * * * certbot-auto renew --no-self-upgrade --quiet --renew-hook "service apache2 restart"
This will execute certbot renew every day at 1am. The command checks if the certificate is expired and renews it if that is the case. The web server is restarted in a post hook in order for it to pick up the new certificate.
Standalone method renewing
If you used Standalone method then the above will likely fail due to apache listening to port 443 (which certbot-auto needs to listen to). In this case you'll need to stop apache, run the renewal, and then start apache again. You can handle this in crontab. The below example will run certbot-auto renew every Sunday at 1am. Note, that if the certificates are not due, then it will not run the pre and post hooks.
0 1 * * 7 certbot-auto renew --no-self-upgrade --quiet --pre-hook "service apache2 stop" --post-hook "service apache2 start"
Subscribing to get expiration notice emails etc.
It's worth subscribing to EFF so that they send expiration notifications to you. You can always resubscribe (and change email etc.) by:
sudo certbot-auto register --update-registration --email admin@example.com
Related articles