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 Git) offre une meilleure expérience avec Certbot et Let's Encrypt, surtout si vous utilisez une version ancienne de l'OS.

Variables du rôle

La variable certbot_install_from_source contrôle si Certbot doit être installé depuis Git ou à partir de la gestion des paquets. Cette dernière est la méthode par défaut, donc la variable par défaut est non.

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 --no-self-upgrade"

Par défaut, ce rôle configure un travail cron pour s'exécuter sous le compte utilisateur fourni à l'heure et à la minute données, tous les jours. Les valeurs par défaut lancent certbot renew (ou certbot-auto renew) via cron tous les jours à 03:30:00 par l'utilisateur que vous utilisez dans votre playbook Ansible. Il est préférable de définir un utilisateur/personne/heure personnalisé pour que le renouvellement se fasse pendant une période de faible trafic et par un compte utilisateur non-root.

Génération automatique de certificats

Actuellement, il existe une méthode intégrée pour générer de nouveaux certificats avec ce rôle : standalone. D'autres méthodes (par exemple, en utilisant nginx ou apache et un webroot) pourraient être ajoutées à l'avenir.

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

certbot_create_if_missing: false
certbot_create_method: standalone

Réglez certbot_create_if_missing sur oui ou True pour permettre à ce rôle de générer des certificats. Définissez la méthode utilisée pour générer les certificats avec la variable certbot_create_method — les valeurs actuellement autorisées incluent : standalone.

certbot_admin_email: email@example.com

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

certbot_certs: []
  # - email: [email protected]
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

Une liste de domaines (et d'autres données) pour lesquels les certificats doivent être générés. Vous pouvez ajouter une clé email à tout élément de la liste pour remplacer certbot_admin_email.

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

La variable certbot_create_command définit la commande utilisée pour générer le certificat.

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, mettez ceci à apache2 (Ubuntu), ou httpd (RHEL), ou si vous avez Nginx sur le port 443 et quelque chose d'autre sur le port 80 (par exemple Varnish, une application Java, ou autre), ajoutez-le à la liste pour qu'il soit arrêté lors de la génération du certificat.

Ces services ne seront arrêtés que lors de la première génération d'un nouveau certificat.

Installation depuis Git

Vous pouvez installer Certbot depuis son dépôt source Git si vous le souhaitez. Cela peut être utile dans plusieurs cas, mais surtout lorsque des distributions plus anciennes ne disposent pas des paquets Certbot (par exemple, CentOS < 7, Ubuntu < 16.10 et Debian < 8).

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

Options du dépôt Git de Certbot. Pour installer depuis la source, réglez certbot_install_from_source sur oui. Cela clone le certbot_repo configuré, en respectant le paramètre certbot_version. Si certbot_keep_updated est défini sur oui, le dépôt est mis à jour chaque fois que ce rôle est exécuté.

certbot_dir: /opt/certbot

Le répertoire dans lequel Certbot sera cloné.

Certificats Wildcard

Let's Encrypt prend en charge la génération de certificats wildcard, mais le processus pour les générer et les utiliser est légèrement plus complexe. Consultez les commentaires dans cette demande de tirage pour un exemple d'utilisation de 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, spécifiquement avec Cloudflare.

Dépendances

Aucune.

Exemple de Playbook

- hosts: serveurs

  vars:
    certbot_auto_renew_user: votre_nom_utilisateur_ici
    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 "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 certs pour tous les hôtes virtuels Apache (à utiliser avec prudence !).
certbot --apache

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

Si vous souhaitez automatiser complètement le processus d'ajout d'un nouveau certificat, mais que vous 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 vous enregistrer, accepter les conditions d'utilisation, puis générer un certificat en utilisant le serveur autonome :

1. Assurez-vous que tous les services à l'écoute sur les ports 80 et 443 (Apache, Nginx, Varnish, etc.) sont arrêtés.
2. Inscrivez-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 les DNS pointent vers ce serveur : certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Redémarrez ce qui était à l'écoute 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 un travail 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

Consultez 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.