Integrazione ACME e Let's Encrypt

Panoramica

Il protocollo ACME (utilizzato da Let's Encrypt e altre autorità di certificazione) supporta la challenge DNS-01 per la validazione del dominio. DNS-01 è l’unico tipo di challenge che supporta i certificati wildcard (*.example.com) e non richiede un server HTTP sulla macchina di destinazione.

NexDNS fornisce integrazioni native con tre popolari client ACME, oltre a un hook CLI generico per qualsiasi client che supporta hook DNS manuali.

Tutte le integrazioni ACME richiedono un token API con permessi records.read e records.write. Crearne uno su nexdns.tech/settings/api-keys.

acme.sh

acme.sh è un client ACME in puro shell. NexDNS è supportato come provider API DNS integrato.

Emissione di un certificato

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

Il token viene salvato in ~/.acme.sh/account.conf dopo la prima esecuzione, quindi non è necessario esportarlo nuovamente per i rinnovi.

Rinnovo

I rinnovi avvengono automaticamente tramite cron. Per forzare un rinnovo manuale:

acme.sh --renew -d example.com

lego / Traefik

lego è un client ACME basato su Go che alimenta anche la gestione automatica dei certificati di Traefik. NexDNS è supportato come provider DNS.

Utilizzo autonomo

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

Configurazione Traefik

Aggiungere il resolver della challenge DNS NexDNS alla configurazione Traefik. Il seguente esempio docker-compose.yml mostra una configurazione tipica:

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:

Quindi utilizzare il resolver nelle etichette del servizio:

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"

certbot

certbot è il client ufficiale di Let's Encrypt. Utilizzare il plugin di autenticazione DNS NexDNS per la validazione automatica DNS-01.

Installazione del plugin

pip install certbot-dns-nexdns

Creazione del file delle credenziali

Creare ~/.nexdns/certbot-credentials.ini con il token API:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxx

Limitare i permessi del file:

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

Emissione di un certificato

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

Utilizzo 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 CLI

Se il client ACME supporta hook DNS manuali, è possibile utilizzare la CLI NexDNS come script di hook. Funziona con qualsiasi client che fornisce le opzioni --manual-auth-hook e --manual-cleanup-hook (es. certbot in modalità manuale).

certbot con hook 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'

L’hook legge le variabili d’ambiente CERTBOT_DOMAIN e CERTBOT_VALIDATION impostate da certbot e crea o rimuove automaticamente il record TXT _acme-challenge.

La CLI deve essere autenticata prima di utilizzare gli hook. Eseguire nexdns auth token nxd_xxx o impostare la variabile d’ambiente NEXDNS_TOKEN.