Fully automate Let’s Encrypt certificate on Debian using central webroot Folder

By | 9. January 2016

Let’s Encrypt is a relatively new Certificate Authority sponsored by multiple large companies such as Mozilla, Cisco, Akamai, Facebook, OVH and many others. Let’s Encrypt provides free SSL certificates for anyone which are trusted by all major browsers. The key benefit is that the complete issuing process including domain validation is done automatically using the ACME protocol. You currently get a certificate which is valid for 90 days and it is recommended to renew it 30 days before it actually becomes invalid. This gives you plenty of time to react in case something goes wrong. While issuing is widely automated, the renewal currently is not. I am going to show in this article how to setup an environment that updates its SSL certificates completely automatically and hence you should not need to touched it again. In case something goes wrong, an email is sent and you can investigate on the issue.

To validate domain ownership, the Let’s Encrpyt client can use several methods, which are out of scope of this article. Look at the pretty good online documentation for more details. One method however is the “webroot” plugin. The client generates some secret data (a challenge) and places them in a directory accessible using the respective domain (the webroot of the domain). The exact protocol specifications are out of scope here. Then the Let’s Encrypt server connects to the domain and validates that the correct data has been placed there. In this article I’ll cover two things. First of all, a common webroot for all domains only for the purpose of domain validation is established. This has the major benefit that the users on your webhost are not bothered with this mysterious “.well-known/acme-challenge” directory and that the user can use directory protection or whatever and cannot accidentally prohibit access to the challenge required for certificate renewal.

Common Let’s Encrypt Webroot

First of all, let us configure this common webroot directory. Therefore, create a directory among with your other customers (in my example they are located in /var/www/) and assign proper permissions. Set the permissions as restrictive as possible, but root needs to be able to write and your webserver needs to be able to read and search the directory (read and execute flag). In my example this looks as follows:

Next, we need to create rules for the webserver to search this directory when ACME challenges are requested. In my setup, I have many virtual hosts, at least one per customer. I prefer to create snippets and include them in the virtual hosts instead of having tremendeously large configuration files. For apache2, create the following file: /etc/apache2/snippets/letsencrypt-webroot.conf and insert the following content:

Next, import this line at every virtual host you have, and possibly also add it to your skeleton virtual host configuration you use when creating new users:

Next, restart apache2. For Nginx, there is a great post in the Let’s Encrypt community forums, check it out!

Automate the Certificate Renewal Process

After having configured the webroot, we can now start to automate the certificate renewal process. First of all and if not already done, create a CLI configuration file for Let’s Encrypt by creating or modifying /etc/letsencrypt/cli.ini

Make sure that the highlighted line matches your chosen path for the common webroot as described above. The script which will be introduced below can send mails when certificate renewal fails. While the mail heading line contains the domain of the certificate whose renewal has failed, the actual content of the mail can be defined entirely by you. Therefore create a text file which contains the message that should be contained in the error email. Note that there is no variable substitution, the content is used as is. In my case, I created the file in /etc/letsencrypt/email_alert_body.txt:

The next step is to download the actual script which is doing the work for you, which has been written by acetylator and originally has been posted in their forums. You can use the script from there or download it from my GitHub repository, where I have placed the script for the records. Open the script and have a look at the configuration section and adjust the settings as needed. The script is very well documented and the configuration variables should be self-explanatory.

The final step is to call the script with the –renew-all every day or so be cron or your favorite other tool. Now you should have an environment which automatically renews the used certificates, without bothering the users and using a central webroot. It even emails you if there are any problems, so have fun with it!

Thanks to the Let’s Encrypt community and the people behind for their great effort in making SSL encryption available for everyone! Many thanks also to acetylator who originally wrote and published this script. I just wrote down the complete process behind, as I had to search for some pieces and just wanted to have everything at one place whenever I have to re-setup my server or a new one.

One thought on “Fully automate Let’s Encrypt certificate on Debian using central webroot Folder

  1. Pingback: Let’s Encrypt (LE) | Ma Vie de Linuxien, dans les Nuages!

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload the CAPTCHA.