Rol de Ansible: Certbot (para Let's Encrypt)

Instala y configura Certbot (para Let's Encrypt).

Requisitos

Si instalas desde el código fuente, se requiere Git. Puedes instalar Git usando el rol geerlingguy.git.

En general, instalar desde el código fuente (ver sección Instalación desde Git) ofrece una mejor experiencia usando Certbot y Let's Encrypt, especialmente si usas una versión más antigua del sistema operativo.

Variables del Rol

certbot_install_method: package

Controla cómo se instala Certbot. Las opciones disponibles son 'package', 'snap' y '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"

Por defecto, este rol configura un trabajo cron que se ejecuta con la cuenta de usuario proporcionada a la hora y minuto dados, todos los días. Por defecto, ejecuta certbot renew (o certbot-auto renew) a través de cron todos los días a las 03:30:00 con el usuario que usas en tu playbook de Ansible. Se recomienda que configures un usuario/hora/minuto personalizado para que la renovación se realice en un período de bajo tráfico y se haga con una cuenta de usuario que no sea root.

Generación Automática de Certificados

Actualmente se admiten los métodos standalone y webroot para generar nuevos certificados utilizando este rol.

Para un ejemplo completo: consulta el playbook de prueba funcional en molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false

Establece certbot_create_if_missing a yes o True para permitir que este rol genere certificados.

certbot_create_method: standalone

Establece el método utilizado para generar certificados con la variable certbot_create_method — los valores permitidos actuales son: standalone o webroot.

certbot_testmode: false

Habilita el modo de prueba para realizar solo una solicitud de prueba sin crear realmente certificados.

certbot_hsts: false

Habilita (HTTP Strict Transport Security) para la generación del certificado.

certbot_admin_email: email@example.com

La dirección de correo electrónico utilizada para aceptar los TOS de Let's Encrypt y suscribirse a notificaciones relacionadas con los certificados. Esto debe personalizarse y establecerse en una dirección de correo electrónico que tú o tu organización monitorice regularmente.

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

Una lista de dominios (y otros datos) para los cuales se deben generar certificados. Puedes agregar una clave email a cualquier elemento de la lista para anular el certbot_admin_email. Al usar el método de creación webroot, es necesario proporcionar un elemento webroot, especificando qué directorio usar para la autenticación. Asegúrate de que tu servidor web entregue correctamente los contenidos de este directorio.

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

El certbot_create_command define el comando utilizado para generar el certificado. Consulta el comando completo por defecto dentro de defaults/main.yml para un ejemplo completo, y puedes agregar fácilmente argumentos adicionales que no estén en el comando por defecto con la variable certbot_create_extra_args.

Generación de Certificados Standalone

certbot_create_standalone_stop_services:
  - nginx

Servicios que deben detenerse mientras certbot ejecuta su propio servidor independiente en los puertos 80 y 443. Si estás ejecutando Apache, establece esto como apache2 (Ubuntu), o httpd (RHEL). Si tienes Nginx en el puerto 443 y algo más en el puerto 80 (por ejemplo, Varnish, una aplicación Java, o algo más), agrégalo a la lista para que se detenga cuando se genere el certificado.

Estos servicios solo se detendrán la primera vez que se genere un nuevo certificado.

Instalación de Snap

A partir de diciembre de 2020, los mantenedores de Certbot decidieron recomendar la instalación de Certbot desde Snap en lugar de mantener scripts como certbot-auto.

Establecer certbot_install_method: snap configura este rol para instalar Certbot a través de Snap.

Este método de instalación es actualmente experimental y puede que no funcione en todas las distribuciones de Linux.

Generación de Certificados Webroot

Al utilizar el método de creación webroot, es necesario proporcionar un elemento webroot para cada elemento de certbot_certs, especificando qué directorio usar para la autenticación. Además, asegúrate de que tu servidor web entregue correctamente los contenidos de este directorio.

Instalación desde Git

Puedes instalar Certbot desde su repositorio de código fuente en Git si lo deseas estableciendo certbot_install_method: source. Esto puede ser útil en varios casos, pero especialmente cuando las distribuciones más antiguas no tienen paquetes de Certbot disponibles (por ejemplo, CentOS < 7, Ubuntu < 16.10 y Debian < 8).

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

Opciones del repositorio Git de Certbot. Si instalas desde el código fuente, se clona el certbot_repo configurado, respetando la configuración de certbot_version. Si certbot_keep_updated está establecido en yes, el repositorio se actualiza cada vez que se ejecuta este rol.

certbot_dir: /opt/certbot

El directorio en el que se clonará Certbot.

Certificados Wildcard

Let's Encrypt admite la generación de certificados wildcard, pero el proceso para generarlos y utilizarlos es un poco más complicado. Consulta los comentarios en esta solicitud de extracción para un ejemplo de cómo usar este rol para mantener certificados wildcard.

Michael Porter también tiene una guía de Creación de un Certificado Wildcard de Let's Encrypt con Ansible, específicamente con Cloudflare.

Dependencias

Ninguna.

Ejemplo de Playbook

- hosts: servers

  vars:
    certbot_auto_renew_user: tu_nombre_de_usuario_aqui
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

Consulta otros ejemplos en el directorio tests/.

Creación manual de certificados con certbot

Nota: Puedes hacer que este rol genere certificados automáticamente; consulta la documentación de "Generación Automática de Certificados" arriba.

Puedes crear certificados manualmente utilizando el script certbot (o certbot-auto) (usa letsencrypt en Ubuntu 16.04, o utiliza /opt/certbot/certbot-auto si instalas desde el código fuente/Git). Aquí tienes algunos comandos de ejemplo para configurar certificados con Certbot:

# Agregar automáticamente certificados para todos los virtualhosts de Apache (¡usar con precaución!).
certbot --apache

# Generar certificados, pero no modificar la configuración de Apache (más seguro).
certbot --apache certonly

Si deseas automatizar completamente el proceso de agregar un nuevo certificado, pero no quieres usar la funcionalidad incorporada de este rol, puedes hacerlo utilizando las opciones de línea de comando para registrarte, aceptar los términos del servicio y luego generar un certificado usando el servidor independiente:

1. Asegúrate de que cualquier servicio que escuche en los puertos 80 y 443 (Apache, Nginx, Varnish, etc.) esté detenido.
2. Regístrate con algo como certbot register --agree-tos --email [[email protected]] - Nota: No necesitarás hacer este paso en el futuro, al generar certificados adicionales en el mismo servidor.
3. Genera un certificado para un dominio cuyo DNS apunte a este servidor: certbot certonly --noninteractive --standalone -d ejemplo.com -d www.ejemplo.com
4. Reinicia lo que estaba escuchando en los puertos 80 y 443 antes.
5. Actualiza la configuración TLS del virtualhost de tu servidor web para que apunte al nuevo certificado (fullchain.pem) y clave privada (privkey.pem) que Certbot acaba de generar para el dominio que pasaste en el comando certbot.
6. Recarga o reinicia tu servidor web para que use la nueva configuración de virtualhost HTTPS.

Auto-renovación de certificados con Certbot

Por defecto, este rol agrega un trabajo cron que renovará todos los certificados instalados una vez al día a la hora y minuto de tu elección.

Puedes probar la auto-renovación (sin renovar realmente el certificado) con el comando:

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

Consulta la documentación completa y las opciones en el sitio web de Certbot.

Licencia

MIT / BSD

Información del Autor

Este rol fue creado en 2016 por Jeff Geerling, autor de Ansible for DevOps.