Integración con ACME / Let's Encrypt

Descripción general

El protocolo ACME (utilizado por Let's Encrypt y otras autoridades de certificación) admite el desafío DNS-01 para la validación de dominios. DNS-01 es el único tipo de desafío que admite certificados wildcard (*.example.com), y no requiere un servidor HTTP en la máquina de destino.

NexDNS proporciona integraciones nativas con tres clientes ACME populares, así como un hook de CLI genérico para cualquier cliente que admita hooks DNS manuales.

Todas las integraciones ACME requieren un token API con permisos records.read y records.write. Crea uno en nexdns.tech/settings/api-keys.

acme.sh

acme.sh es un cliente ACME escrito íntegramente en shell. NexDNS es compatible como proveedor de API DNS integrado.

Emitir un certificado

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxx"
acme.sh --issue --dns dns_nexdns -d example.com -d '*.example.com'

El token se guarda en ~/.acme.sh/account.conf después de la primera ejecución, por lo que no necesitas exportarlo nuevamente para las renovaciones.

Renovar

Las renovaciones se realizan automáticamente mediante cron. Para forzar una renovación manual:

acme.sh --renew -d example.com

lego y Traefik

lego es un cliente ACME basado en Go que también potencia la gestión automática de certificados de Traefik. NexDNS es compatible como proveedor DNS.

Uso independiente

NEXDNS_API_TOKEN=nxd_xxx \
lego --dns nexdns \
    --domains example.com \
    --domains '*.example.com' \
    --email admin@example.com \
    run

Configuración de Traefik

Añade el resolver de desafío DNS de NexDNS a tu configuración de Traefik. El siguiente ejemplo de docker-compose.yml muestra una configuración típica:

services:
  traefik:
    image: traefik:v3
    command:
      - "--certificatesresolvers.nexdns.acme.dnschallenge=true"
      - "--certificatesresolvers.nexdns.acme.dnschallenge.provider=nexdns"
      - "--certificatesresolvers.nexdns.acme.email=admin@example.com"
      - "--certificatesresolvers.nexdns.acme.storage=/letsencrypt/acme.json"
    environment:
      NEXDNS_API_TOKEN: "nxd_xxxxxxxxxxxxxxxxxxxx"
    volumes:
      - letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "443:443"

volumes:
  letsencrypt:

Luego usa el resolver en las etiquetas de tu servicio:

labels:
  - "traefik.http.routers.myapp.tls.certresolver=nexdns"
  - "traefik.http.routers.myapp.tls.domains[0].main=example.com"
  - "traefik.http.routers.myapp.tls.domains[0].sans=*.example.com"

cliente certbot

certbot es el cliente oficial de Let's Encrypt. Usa el plugin de autenticación DNS de NexDNS para la validación DNS-01 automatizada.

Instalar el plugin

pip install certbot-dns-nexdns

Crear archivo de credenciales

Crea el archivo ~/.nexdns/certbot-credentials.ini con tu token API:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxx

Restringe los permisos del archivo:

chmod 600 ~/.nexdns/certbot-credentials.ini

Emitir un certificado

certbot certonly \
    --authenticator dns-nexdns \
    --dns-nexdns-credentials ~/.nexdns/certbot-credentials.ini \
    -d '*.example.com'

Uso con Docker

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    certbot/dns-nexdns certonly \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d '*.example.com'

Hook de CLI

Si tu cliente ACME admite hooks DNS manuales, puedes usar el CLI de NexDNS como script de hook. Esto funciona con cualquier cliente que proporcione las opciones --manual-auth-hook y --manual-cleanup-hook (p. ej., certbot en modo manual).

certbot con hook de CLI

certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "nexdns acme hook --action create" \
    --manual-cleanup-hook "nexdns acme hook --action delete" \
    -d '*.example.com'

El hook lee las variables de entorno CERTBOT_DOMAIN y CERTBOT_VALIDATION establecidas por certbot y crea o elimina el registro TXT _acme-challenge automáticamente.

El CLI debe estar autenticado antes de usar hooks. Ejecuta nexdns auth token nxd_xxx o establece la variable de entorno NEXDNS_TOKEN.