lego-certificates.rst (5837B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Javier Sepulveda 17 18 .. image:: images/lego-logo.svg 19 :width: 300 20 :height: 150 21 :alt: lego logo 22 23 What is Lego 24 ############ 25 26 Let's Encrypt client and ACME library written in Go. 27 28 * You can request new certificates 29 * You can request new subdomain alt names for your current main certicate 30 * You can renew certificates 31 * You can revoke certificates 32 * You can request certificates by using dynamic DNS (API access, with multiple providers) 33 34 35 Why lego is better for managing certificates 36 ============================================ 37 38 * The process is not considered a live process, so in case something goes wrong your websites won't break. 39 * You can hook some actions after the renewal process, such as reloading Dovecot. 40 * The process of either obtaining or renewing new certicates, doesn't require you to stop NGINX. 41 * 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. 42 43 44 Requirements 45 ============ 46 - A fully automation of installing and deploying Lego can be found in migration-exercise-stable.git/taler.net/lego-certificates 47 - If you want to do things manually instead, you can execute the "install-lego.sh" file. 48 - To use our script simply execute the "main-certs.sh" file, which not only will install lego on your system, but 49 will try to obtain certificates for the ones listed on the "domains" text file. 50 - Lego can work with so many domain providers (dynamic DNS), so please make sure you have indicated the right 51 API credentials on the "envars" variables file for your domain provider. In our specific case, we use Joker. 52 - 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 53 the port 80. 54 55 Installation and deployment with a script 56 ========================================= 57 58 #. Git clone migration-exercise-stable.git 59 #. Navigate to the folder taler.net/lego-certificates 60 #. Add your desired FQDNs in the "domains" text file 61 #. Execute the "main-certs.sh" file as ./main-certs.sh 62 63 Manually installing Lego 64 =========================== 65 66 .. note :: 67 Just as an informative process, as this is fully automated by executing either the "install-lego.sh" or the "main-certs.sh" files. 68 69 .. code-block:: console 70 71 $ wget https://github.com/go-acme/lego/releases/download/v4.16.1/lego_v4.16.1_linux_amd64.tar.gz 72 $ tar -axf lego_v4.16.1_linux_amd64.tar.gz 73 $ # If moving directly to /usr/local/bin, just copy the lego binary file to /usr/local/bin 74 $ cp /tmp/lego /usr/local/bin/ 75 $ # If copying the binary to /opt/lego, make symbolic links to /usr/local/bin 76 $ cp /tmp/lego /opt/lego/ 77 $ ln -s /usr/local/bin /opt/lego/lego 78 79 Full documentation on how to use Lego can be found in: https://go-acme.github.io/lego/ 80 81 Usage of lego once it has been installed 82 ======================================== 83 84 * Each time you want to add an additional domain to your setup, just add the FQDN to the "domains" text file 85 * There is nothing else to do in your side now, the server itself will trigger automatically (systemd timer) the "renew-certs.service" 86 * We have implemented the use of lego with systemd timers, so there is not additional maintenance 87 88 Automatic renewal of certificates 89 ================================= 90 91 We use systemd timers do undertake this. 92 93 .. note :: 94 To check the systemd timer is running properly and "waiting", you can execute "systemctl status renew-certs.timer" 95 96 More information: https://go-acme.github.io/lego/usage/cli/renew-a-certificate/ 97 98 99 Email notifications 100 ==================== 101 102 * Let's encrypt notifications will arrive to your configured email address. 103 * You can specify your email address by editing the "envars" text file (variable "LEGO_ACCOUNT_EMAIL"). 104 * On each successful renewal, you will receive an email notification from the script. 105 106 Additional information for troubleshooting 107 ========================================== 108 109 Once you have the certificate generated files (/root/.lego/xxx.crt, /root/.lego/xxx.key) 110 they will be copied to /etc/ssl/certs and /etc/ssl/private, respectively. 111 112 How to configure NGINX to use your certificates 113 =============================================== 114 115 In the NGINX virtualhost configuration file just include "include conf.d/talerssl.conf;" line, and 116 make sure you have a file named "talerssl.conf" in the path: /etc/nginx/conf.d with the next content: 117 118 .. code-block:: console 119 120 $ # Taler SSL defaults 121 $ # We're using one certificate with taler.net as primary name 122 $ # and everything else as alt name. 123 $ # These 2 next lines are the important ones, which refer to the certificates file (.crt), and its private key (.key) 124 $ ssl_certificate /etc/ssl/certs/taler.net.crt; 125 $ ssl_certificate_key /etc/ssl/private/taler.net.key; 126 $ ssl_session_cache shared:SSL:10m; 127 $ ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; 128 $ add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"; 129 130 131 Presence of Lego in our servers 132 =============================== 133 134 * TUE - University of Eindhoven 135 136 137 138 139 140 141 142 143 144