lego logo

12.1. What is Lego

Let’s Encrypt client and ACME library written in Go.

  • You can request new certificates

  • You can request new subdomain alt names for your current main certicate

  • You can renew certificates

  • You can revoke certificates

  • You can request certificates by using dynamic DNS (API access, with multiple providers)

12.1.1. Why lego is better for managing certificates

  • The process is not considered a live process, so in case something goes wrong your websites won’t break.

  • You can hook some actions after the renewal process, such as reloading Dovecot.

  • The process of either obtaining or renewing new certicates, doesn’t require you to stop NGINX.

  • Lego just helps you to obtain the certificates as text files, which you can copy afterwards to the right locations to be used by NGINX.

12.1.2. Requirements

  • A fully automation of installing and deploying Lego can be found in migration-exercise-stable.git/taler.net/lego-certificates

  • If you want to do things manually instead, you can execute the “install-lego.sh” file.

  • To use our script simply execute the “main-certs.sh” file, which not only will install lego on your system, but will try to obtain certificates for the ones listed on the “domains” text file.

  • Lego can work with so many domain providers (dynamic DNS), so please make sure you have indicated the right API credentials on the “envars” variables file for your domain provider. In our specific case, we use Joker.

  • Make sure either you are not using UFW or any firewall program, or that if you are using one, make sure you have opened beforehand the port 80.

12.1.3. Installation and deployment with a script

  1. Git clone migration-exercise-stable.git

  2. Navigate to the folder taler.net/lego-certificates

  3. Add your desired FQDNs in the “domains” text file

  4. Execute the “main-certs.sh” file as ./main-certs.sh

12.1.4. Manually installing Lego

Note

Just as an informative process, as this is fully automated by executing either the “install-lego.sh” or the “main-certs.sh” files.

$ wget https://github.com/go-acme/lego/releases/download/v4.16.1/lego_v4.16.1_linux_amd64.tar.gz
$ tar -axf lego_v4.16.1_linux_amd64.tar.gz
$ # If moving directly to /usr/local/bin, just copy the lego binary file to /usr/local/bin
$ cp /tmp/lego /usr/local/bin/
$ # If copying the binary to /opt/lego, make symbolic links to /usr/local/bin
$ cp /tmp/lego /opt/lego/
$ ln -s /usr/local/bin /opt/lego/lego

Full documentation on how to use Lego can be found in: https://go-acme.github.io/lego/

12.1.5. Usage of lego once it has been installed

  • Each time you want to add an additional domain to your setup, just add the FQDN to the “domains” text file

  • There is nothing else to do in your side now, the server itself will trigger automatically (systemd timer) the “renew-certs.service”

  • We have implemented the use of lego with systemd timers, so there is not additional maintenance

12.1.6. Automatic renewal of certificates

We use systemd timers do undertake this.

Note

To check the systemd timer is running properly and “waiting”, you can execute “systemctl status renew-certs.timer”

More information: https://go-acme.github.io/lego/usage/cli/renew-a-certificate/

12.1.7. Email notifications

  • Let’s encrypt notifications will arrive to your configured email address.

  • You can specify your email address by editing the “envars” text file (variable “LEGO_ACCOUNT_EMAIL”).

  • On each successful renewal, you will receive an email notification from the script.

12.1.8. Additional information for troubleshooting

Once you have the certificate generated files (/root/.lego/xxx.crt, /root/.lego/xxx.key) they will be copied to /etc/ssl/certs and /etc/ssl/private, respectively.

12.1.9. How to configure NGINX to use your certificates

In the NGINX virtualhost configuration file just include “include conf.d/talerssl.conf;” line, and make sure you have a file named “talerssl.conf” in the path: /etc/nginx/conf.d with the next content:

$ # Taler SSL defaults
$ # We're using one certificate with taler.net as primary name
$ # and everything else as alt name.
$ # These 2 next lines are the important ones, which refer to the certificates file (.crt), and its private key (.key)
$ ssl_certificate /etc/ssl/certs/taler.net.crt;
$ ssl_certificate_key /etc/ssl/private/taler.net.key;
$ ssl_session_cache shared:SSL:10m;
$ ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
$ add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";

12.1.10. Presence of Lego in our servers

  • TUE - University of Eindhoven