Rôle Ansible : Certbot (pour Let's Encrypt)

Installe et configure Certbot (pour Let's Encrypt).

Exigences

Si vous installez depuis la source, Git est requis. Vous pouvez installer Git en utilisant le rôle geerlingguy.git.

En général, l'installation depuis la source (voir la section Installation depuis la source Git) offre une meilleure expérience avec Certbot et Let's Encrypt, surtout si vous utilisez une ancienne version de votre système d'exploitation.

Variables du Rôle

certbot_install_method: package

Contrôle comment Certbot est installé. Les options disponibles sont 'package', 'snap' et 'source'.

certbot_auto_renew: true
certbot_auto_renew_user: "{{ ansible_user | default(lookup('env', 'USER')) }}"
certbot_auto_renew_hour: "3"
certbot_auto_renew_minute: "30"
certbot_auto_renew_options: "--quiet"

Par défaut, ce rôle configure une tâche cron qui s'exécute sous le compte utilisateur fourni à l'heure et à la minute données, tous les jours. Les paramètres par défaut exécutent certbot renew (ou certbot-auto renew) via cron tous les jours à 03:30:00 avec l'utilisateur utilisé dans votre playbook Ansible. Il est recommandé de définir un utilisateur/heure/minute personnalisé afin que le renouvellement se fasse durant une période de faible trafic et soit exécuté par un compte utilisateur non-root.

Génération Automatique de Certificats

Actuellement, les méthodes standalone et webroot sont supportées pour générer de nouveaux certificats avec ce rôle.

Pour un exemple complet : voir le playbook de test fonctionnel dans molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false

Réglez certbot_create_if_missing sur yes ou True pour permettre à ce rôle de générer des certificats.

certbot_create_method: standalone

Définissez la méthode utilisée pour générer des certificats avec la variable certbot_create_method — les valeurs autorisées actuelles sont : standalone ou webroot.

certbot_testmode: false

Activez le mode test pour n'exécuter qu'une demande de test sans réellement créer de certificats.

certbot_hsts: false

Activez (HTTP Strict Transport Security) pour la génération de certificats.

certbot_admin_email: email@example.com

L'adresse email utilisée pour accepter les TOS de Let's Encrypt et s'abonner aux notifications liées aux certificats. Cela doit être personnalisé et configuré avec une adresse email que vous ou votre organisation surveillez régulièrement.

certbot_certs: []
  # - email: [email protected]
  #   webroot: "/var/www/html"
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

Une liste de domaines (et d'autres données) pour lesquels des certificats doivent être générés. Vous pouvez ajouter une clé email à tout élément de la liste pour remplacer certbot_admin_email. Lors de l'utilisation de la méthode de création webroot, un élément webroot doit être fourni, spécifiant quel répertoire utiliser pour l'authentification. Assurez-vous que votre serveur web délivre correctement le contenu de ce répertoire.

certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"

La commande certbot_create_command définit la commande utilisée pour générer le certificat. Voir la commande par défaut complète dans defaults/main.yml pour un exemple complet — et vous pouvez facilement ajouter des arguments supplémentaires qui ne figurent pas dans la commande par défaut avec la variable certbot_create_extra_args.

Génération de Certificats Standalone

certbot_create_standalone_stop_services:
  - nginx

Services qui doivent être arrêtés pendant que certbot exécute son propre serveur autonome sur les ports 80 et 443. Si vous utilisez Apache, réglez ceci sur apache2 (Ubuntu), ou httpd (RHEL), ou si vous avez Nginx sur le port 443 et autre chose sur le port 80 (par exemple Varnish, une application Java, ou autre), ajoutez-le à la liste afin qu'il soit arrêté lors de la génération du certificat.

Ces services ne seront arrêtés que la première fois qu'un nouveau certificat est généré.

Installation via Snap

Depuis décembre 2020, les mainteneurs de Certbot ont décidé de recommander l'installation de Certbot via Snap plutôt que de maintenir des scripts comme certbot-auto.

Régler certbot_install_method: snap configure ce rôle pour installer Certbot via Snap.

Cette méthode d’installation est actuellement expérimentale et peut ou non fonctionner à travers toutes les distributions Linux.

Génération de Certificats Webroot

Lors de l'utilisation de la méthode de création webroot, un élément webroot doit être fourni pour chaque élément certbot_certs, spécifiant quel répertoire utiliser pour l'authentification. Assurez-vous également que votre serveur web délivre correctement le contenu de ce répertoire.

Installation depuis la Source Git

Vous pouvez installer Certbot depuis son dépôt source Git si désiré avec certbot_install_method: source. Cela peut être utile dans plusieurs cas, mais surtout lorsque les anciennes distributions n'ont pas de paquets Certbot disponibles (par exemple, CentOS < 7, Ubuntu < 16.10 et Debian < 8).

certbot_repo: https://github.com/certbot/certbot.git
certbot_version: master
certbot_keep_updated: true

Options du dépôt Git de Certbot. Si vous installez depuis la source, le certbot_repo configuré sera cloné, en respectant le réglage certbot_version. Si certbot_keep_updated est réglé sur yes, le dépôt sera mis à jour chaque fois que ce rôle s'exécute.

certbot_dir: /opt/certbot

Le répertoire dans lequel Certbot sera cloné.

Certificats Wildcard

Let's Encrypt supporte la génération de certificats wildcard, mais le processus de génération et d'utilisation est légèrement plus complexe. Voir les commentaires dans cette pull request pour un exemple de la façon d'utiliser ce rôle pour maintenir des certificats wildcard.

Michael Porter a également un guide sur La création d'un certificat wildcard Let's Encrypt avec Ansible, en particulier avec Cloudflare.

Dépendances

Aucune.

Exemples de Playbook

- hosts: serveurs

  vars:
    certbot_auto_renew_user: votre_nom_d'utilisateur
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

Voir d'autres exemples dans le répertoire tests/.

Création Manuelle de Certificats avec Certbot

Remarque : Vous pouvez faire en sorte que ce rôle génère automatiquement des certificats ; voir la documentation sur "Génération Automatique de Certificats" ci-dessus.

Vous pouvez créer des certificats manuellement en utilisant le script certbot (ou certbot-auto) (utilisez letsencrypt sur Ubuntu 16.04, ou utilisez /opt/certbot/certbot-auto si vous installez depuis la source/Git). Voici quelques commandes d'exemple pour configurer des certificats avec Certbot :

# Ajouter automatiquement des certificats pour tous les hôtes virtuels Apache (à utiliser avec prudence !).
certbot --apache

# Générer des certificats, mais ne pas modifier la configuration d'Apache (plus sûr).
certbot --apache certonly

Si vous souhaitez automatiser entièrement le processus d'ajout d'un nouveau certificat, mais ne souhaitez pas utiliser la fonctionnalité intégrée de ce rôle, vous pouvez le faire en utilisant les options de ligne de commande pour s'enregistrer, accepter les conditions de service, puis générer un certificat en utilisant le serveur autonome :

1. Assurez-vous que tout service écoutant sur les ports 80 et 443 (Apache, Nginx, Varnish, etc.) est arrêté.
2. Enregistrez-vous avec quelque chose comme certbot register --agree-tos --email [[email protected]] - Remarque : Vous n'aurez pas besoin de faire cette étape à l'avenir, lors de la génération de certificats supplémentaires sur le même serveur.
3. Générez un certificat pour un domaine dont le DNS pointe vers ce serveur : certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Redémarrez tout ce qui écoutait sur les ports 80 et 443 auparavant.
5. Mettez à jour la configuration TLS de l'hôte virtuel de votre serveur web pour pointer vers le nouveau certificat (fullchain.pem) et la clé privée (privkey.pem) que Certbot vient de générer pour le domaine que vous avez passé dans la commande certbot.
6. Rechargez ou redémarrez votre serveur web afin qu'il utilise la nouvelle configuration d'hôte virtuel HTTPS.

Renouvellement Automatique des Certificats Certbot

Par défaut, ce rôle ajoute une tâche cron qui renouvellera tous les certificats installés une fois par jour à l'heure et à la minute de votre choix.

Vous pouvez tester le renouvellement automatique (sans réellement renouveler le certificat) avec la commande :

/opt/certbot/certbot-auto renew --dry-run

Voir la documentation complète et les options sur le site de Certbot.

Licence

MIT / BSD

Informations sur l'Auteur

Ce rôle a été créé en 2016 par Jeff Geerling, auteur de Ansible for DevOps.