Cliente ACME Lego - WildCard SSL

Una guía detallada para desplegar un certificado SSL WildCard tipo estrella mediante el cliente ACME Lego y la validación API DNS con el hosting web VEDOS. El procedimiento está pensado para certificados del tipo example.com y *.example.com, donde la renovación debe ser automática sin introducir manualmente los registros TXT. La guía usa un certificado ACME de la autoridad de certificación Certum. El certificado utilizado sirve solo como ejemplo – el principio de funcionamiento y el procedimiento de despliegue ACME son los mismos para todas las autoridades de certificación.

La guía usa una sintaxis verificada en Lego 5.2.2. Lego v5 cambió algunos parámetros respecto a versiones anteriores, por lo que en caso de un error como flag provided but not defined verifica la sintaxis correcta con lego accounts register --help, lego run --help o lego --help.

Conceptos básicos

• ACME – protocolo para la emisión y renovación automatizadas de certificados SSL/TLS.
• Lego – un cliente ACME escrito en Go. Puede realizar validación DNS a través de muchos proveedores de DNS (lista de proveedores de DNS compatibles).
• DNS-01 – validación mediante el registro DNS TXT _acme-challenge. Es necesaria para los certificados WildCard.
• EAB kid + hmac – datos de External Account Binding (EAB) de la autoridad de certificación. Vinculan Certbot a una cuenta o producto.
• VEDOS WAPI – la interfaz API de VEDOS a través de la cual Lego crea y elimina los registros DNS TXT.
• Servicio systemd - un archivo de configuración que indica al sistema Linux cómo iniciar una aplicación y mantenerla en ejecución incluso después de reiniciar el servidor.

En todos los ejemplos mostrados, sustituye el dominio example.com por tu propio dominio.

Instalación de Lego

apt update
apt install -y curl tar

cd /tmp
LEGO_URL=$(curl -s https://api.github.com/repos/go-acme/lego/releases/latest | sed -n 's/.*"browser_download_url": "\(.*linux_amd64.tar.gz\)".*/\1/p' | head -n1)
echo "$LEGO_URL"
curl -L -o lego.tar.gz "$LEGO_URL"
tar -xzf lego.tar.gz
install -m 0755 lego /usr/local/bin/lego
lego --version

Tras una instalación correcta, recomendamos eliminar los archivos temporales.

rm -f /tmp/lego /tmp/lego.tar.gz /tmp/LICENSE /tmp/CHANGELOG.md

Proveedor de API DNS

Esta guía usa la API DNS del registrador de dominios Vedos, que ofrece una API para gestionar el DNS de los dominios registrados. Para el hosting web de Vedos, necesitas activar WAPI y también rellenar las direcciones IP permitidas y la contraseña WAPI.

Direcciones IP del servidor VPS

curl -4 ifconfig.me
curl -6 ifconfig.me

En el campo Direcciones IP permitidas, introduce todas las direcciones IP salientes de tu servidor, normalmente tanto IPv4 como IPv6. Los valores se separan con un espacio. VEDOS solo permite peticiones API desde las direcciones IP indicadas.
Importante: Si permites solo IPv4 y alguna petición API sale por IPv6, la emisión del certificado puede tener éxito, pero la limpieza de los registros TXT fallará con el error Access not allowed from this IP address.

Valores recomendados para el proveedor de DNS VEDOS

Apache, webroot

La configuración básica de Apache es una parte de apoyo. La validación DNS se realiza a través de la API DNS, no por HTTP, pero el vhost de Apache es necesario para servir el sitio web después de emitir el certificado.

cd /var/www
apt update
apt install -y apache2
systemctl enable --now apache2
a2enmod rewrite headers ssl
systemctl reload apache2

DOMAIN="example.com"
mkdir -p /var/www/$DOMAIN/public
chown -R www-data:www-data /var/www/$DOMAIN
chmod -R 755 /var/www/$DOMAIN
echo "OK $DOMAIN" > /var/www/$DOMAIN/public/index.html

cat > /etc/apache2/sites-available/$DOMAIN.conf <<EOF
<VirtualHost *:80>
    ServerName $DOMAIN
    ServerAlias *.$DOMAIN

    DocumentRoot /var/www/$DOMAIN/public
    <Directory /var/www/$DOMAIN/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog \${APACHE_LOG_DIR}/${DOMAIN}_error.log
    CustomLog \${APACHE_LOG_DIR}/${DOMAIN}_access.log combined
</VirtualHost>
EOF

a2ensite $DOMAIN.conf
apache2ctl configtest
systemctl reload apache2
curl -I http://$DOMAIN

Archivos de configuración de Lego

El enfoque recomendado para Lego v5 es almacenar la configuración en un archivo de configuración. Así, el servicio systemd no necesita contener un comando largo con dominios, el proveedor de DNS y hooks.

Archivo de configuración .env

El archivo .env es un archivo de configuración de texto en el que se almacenan variables de entorno, por ejemplo credenciales de acceso, claves de API o ajustes de la aplicación. Para mayor claridad, puedes nombrar el archivo proveedor-dominio.env. El archivo vedos-example.com.env contendrá las credenciales de acceso de VEDOS WAPI, por lo que lo guardamos en /etc/lego y le establecemos permisos restringidos.

DOMAIN="example.com"

mkdir -p /etc/lego/$DOMAIN
nano /etc/lego/vedos-$DOMAIN.env

En la configuración de abajo, sustituye WEDOS_LOGIN por tu login de VEDOS y WEDOS_WAPI_PASSWORD por la contraseña generada en VEDOS WAPI. Puedes dejar los valores de timeout e interval tal como están.

WEDOS_USERNAME='WEDOS_LOGIN'
WEDOS_WAPI_PASSWORD='WEDOS_WAPI_PASSWORD'
WEDOS_PROPAGATION_TIMEOUT=3600
WEDOS_POLLING_INTERVAL=30
WEDOS_TTL=300

Archivo de configuración lego.yml

El archivo .yml es un archivo de configuración de texto en formato YAML, usado para una notación clara de ajustes, parámetros y datos estructurados. Antes de guardar la configuración YAML, sustituye example.com por tu propio dominio, *.example.com por el nombre comodín, vas@email.cz por tu correo de contacto y los valores KID / HMAC por los datos de tu pedido de certificado ACME. Nombres como certum-example o example-com-wildcard son etiquetas internas; puedes dejarlos, pero con varios dominios es recomendable renombrarlos según el dominio.

mkdir /etc/lego/$DOMAIN
nano /etc/lego/$DOMAIN/lego.yml

storage: /etc/lego/example.com

accounts:
  certum-example:
    server: certum
    email: vas@email.cz
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

servers:
  certum:
    url: https://acme.certum.pl/directory

challenges:
  vedos-dns:
    dns:
      provider: vedos
      envFile: /etc/lego/vedos-example-com.env
      resolvers:
        - 1.1.1.1:53

certificates:
  example-com-wildcard:
    account: certum-example
    challenge: vedos-dns
    domains:
      - example.com
      - "*.example.com"
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Emisión del certificado

Antes de ejecutar, sustituye example.com en la ruta por el dominio que usaste al crear el directorio. La primera ejecución crea la cuenta ACME, establece los registros DNS TXT a través de la API DNS, realiza la validación DNS-01 y guarda el certificado.

Mientras espera, Lego puede imprimir:

Esto significa que Lego comprueba el DNS cada 30 segundos y espera como máximo 1 hora. Tras el éxito, verifica los archivos:

El directorio certificates/ contiene el .crt emitido, la .key, los certificados intermedios de la autoridad de certificación y los metadatos.

Procedimiento CLI alternativo para Lego v5

lego accounts register \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --accept-tos \
  --eab \
  --eab.kid 'KID' \
  --eab.hmac 'HMAC'

set -a
. /etc/lego/vedos-example.com.env
set +a

lego run \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --dns vedos \
  --dns.resolvers 1.1.1.1:53 \
  --domains example.com \
  --domains '*.example.com'

Despliegue del certificado en Apache

Antes de crear el vhost HTTPS, sustituye example.com por tu propio dominio en el nombre del archivo, en los valores ServerName y ServerAlias, en las rutas del webroot y en las rutas del certificado. Estas rutas deben coincidir con el dominio usado en la configuración de Lego.

cat > /etc/apache2/sites-available/example.com-le-ssl.conf <<'EOF'
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName example.com
    ServerAlias *.example.com

    DocumentRoot /var/www/example.com/public
    <Directory /var/www/example.com/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/lego/example.com/certificates/example.com.crt
    SSLCertificateKeyFile /etc/lego/example.com/certificates/example.com.key

    ErrorLog ${APACHE_LOG_DIR}/example.com_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite example.com-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://example.com
curl -I https://test.example.com

Renovación automática

Lego puede renovar el certificado, pero tras la instalación no crea un timer systemd por sí mismo. La ejecución periódica se configura mediante un service y un timer personalizados. Antes de insertarlo, sustituye example-com en el nombre del service/timer por tu propio nombre seguro sin puntos, por ejemplo mojedomena-cz, y sustituye example.com en la ruta de configuración por tu propio dominio.

cat > /etc/systemd/system/lego-example-com-renew.service <<'EOF'
[Unit]
Description=Renew Certum WildCard SSL for example.com using Lego and VEDOS DNS
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/example.com/lego.yml
EOF

cat > /etc/systemd/system/lego-example-com-renew.timer <<'EOF'
[Unit]
Description=Daily Lego renewal check for example.com

[Timer]
OnCalendar=*-*-* 03:20:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now lego-example-com-renew.timer
systemctl list-timers | grep lego

Prueba segura del servicio:

systemctl start lego-example-com-renew.service
journalctl -u lego-example-com-renew.service -n 100 --no-pager

Si el certificado no está próximo a caducar, Lego puede informar de que la renovación no es necesaria. Este es el comportamiento correcto.

Errores comunes

Parámetro desconocido en Lego

En Lego v5 los parámetros EAB son --eab.kid y --eab.hmac. Los parámetros siempre pertenecen a un subcomando específico.

lego accounts register --help
lego accounts list --help
lego run --help

La limpieza de los registros TXT falla por una IP no permitida

Añade también la dirección IPv6 del servidor a las direcciones IP permitidas en VEDOS WAPI. El certificado puede emitirse correctamente, pero los registros TXT permanecerán en el DNS después de la validación.

Lista de verificación

dig TXT _acme-challenge.example.com +short
lego --config /etc/lego/example.com/lego.yml
systemctl status lego-example-com-renew.timer
apache2ctl configtest
curl -I https://example.com

¿A dónde ir a continuación?

• Protocolo ACME
• Cliente ACME Lego
• Cliente ACME Certbot
• Certificado SSL - Todo lo que necesitas saber