Integrace s ACME / Let's Encrypt

Přehled

Protokol ACME (používaný Let's Encrypt a dalšími certifikačními autoritami) podporuje výzvu DNS-01 pro validaci domény. DNS-01 je jediný typ výzvy, který podporuje wildcard certifikáty (*.example.com), a nevyžaduje HTTP server na cílovém stroji.

NexDNS nabízí nativní integrace s oblíbenými ACME klienty a také obecný CLI hook pro každého klienta, který podporuje ruční DNS hooky.

Všechny integrace ACME vyžadují API token, který je dostupný v tarifu Pro a vyšším. Každý klient si zónu nejprve vyhledá, než zapíše výzvu, takže token potřebuje kromě records.read a records.write také zones.read. Vytvořte si ho na nexdns.tech/settings/api-keys.

Jak se validuje wildcard

Výzva je záznam TXT na _acme-challenge pod validovaným názvem. Certifikát, který pokrývá example.com i *.example.com, vytvoří dvě různé hodnoty výzvy pod stejným názvem a obě musí být přítomné současně. Každá integrace níže s tím počítá, a proto sadu záznamů mezi oběma validacemi nikdy nemažte.

Počítejte s propagací

Ověřovací záznam potřebuje zhruba 30 sekund, než se dostane na jmenné servery, takže třicetisekundové čekání nenechává žádnou rezervu – viděli jsme, jak ověření selhalo s NXDOMAIN. Dejte certifikační autoritě alespoň 60 sekund: plugin certbot i lego čekají ve výchozím nastavení 60 a u acme.sh a CLI hooku si čekání nastavíte sami.

acme.sh

acme.sh je ACME klient napsaný čistě v shellu. Náš DNS hook zatím není součástí žádného vydání acme.sh, proto jej před prvním spuštěním umístěte do ~/.acme.sh/dnsapi/: curl -fsSL https://get.nexdns.tech/acme/dns_nexdns.sh -o ~/.acme.sh/dnsapi/dns_nexdns.sh. Stejný soubor najdete v repozitáři CLI, pokud si jej chcete nejdřív přečíst.

Vydání certifikátu

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
acme.sh --issue --server letsencrypt --dns dns_nexdns \
    --dnssleep 60 \
    -d example.com -d '*.example.com'

Token se po prvním spuštění uloží do ~/.acme.sh/account.conf, takže ho při obnovování nemusíte exportovat znovu.

Obnovení

Obnovení probíhá automaticky přes cron. Pro vynucení ručního obnovení:

acme.sh --renew -d example.com

lego a Traefik

lego je ACME klient napsaný v Go, který také pohání automatickou správu certifikátů v Traefiku. Provider je součástí lego od verze 5.4.0.

Samostatné použití

NEXDNS_API_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
NEXDNS_PROPAGATION_TIMEOUT=300 \
lego --dns nexdns \
    --domains example.com \
    --domains '*.example.com' \
    --email admin@example.com \
    --accept-tos \
    run

lego čte své časové limity jako prosté číslo v sekundách: NEXDNS_PROPAGATION_TIMEOUT=300 funguje, zatímco 300s se nepodaří načíst a tiše se nahradí výchozí hodnotou 60 sekund.

Konfigurace Traefik

Traefik zabudovává tabulku providerů z lego při sestavení a stále používá starší verzi, takže je zde potřeba sestavení Traefiku s lego 5.4.0. Přidejte do konfigurace Traefiku resolver DNS výzvy NexDNS – následující docker-compose.yml ukazuje typické nastavení:

services:
  traefik:
    image: traefik:v3  # lego >= v5.4.0
    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:

Poté použijte resolver v labelech vaší služby:

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 je oficiální klient Let's Encrypt. Použijte plugin NexDNS DNS authenticator pro automatizovanou validaci DNS-01.

Instalace pluginu

Nainstalujte plugin z PyPI nebo použijte Docker image níže, který jej již obsahuje.

pip install certbot-dns-nexdns

Vytvoření souboru s přihlašovacími údaji

Vytvořte soubor ~/.nexdns/certbot-credentials.ini s vaším API tokenem:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Omezte oprávnění souboru:

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

Vydání certifikátu

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

Použití s Docker

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    nexdns/certbot certonly \
        --non-interactive --agree-tos --email admin@example.com \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d example.com \
        -d '*.example.com'

Háček CLI

Pokud váš ACME klient podporuje manuální DNS hooky, můžete použít NexDNS CLI jako hook skript. Funguje to s jakýmkoli klientem, který poskytuje volby --manual-auth-hook a --manual-cleanup-hook (např. certbot v manuálním režimu).

certbot s CLI Hook

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

Hook čte proměnné prostředí CERTBOT_DOMAIN a CERTBOT_VALIDATION nastavené certbotem a automaticky vytváří nebo odstraňuje záznam TXT _acme-challenge.

CLI musí být autentizován před použitím hooků. Spusťte nexdns auth token nxd_xxx nebo nastavte proměnnou prostředí NEXDNS_TOKEN.