..
  This file is part of GNU TALER.
  Copyright (C) 2014-2023 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Javier Sepulveda

.. image:: images/lego-logo.svg
   :width: 300
   :height: 150
   :alt: lego logo

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)


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. 


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.

Installation and deployment with a script
=========================================

#. Git clone migration-exercise-stable.git
#. Navigate to the folder taler.net/lego-certificates
#. Add your desired FQDNs in the "domains" text file
#. Execute the "main-certs.sh" file as ./main-certs.sh

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.

.. code-block:: console

   $ 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/ 

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

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/


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.

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. 

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:

.. code-block:: console

   $ # 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";


Presence of Lego in our servers
===============================

* TUE - University of Eindhoven