ACME / Let's Encrypt entegrasyonu

Genel bakış

ACME protokolü (Let's Encrypt ve diğer sertifika otoriteleri tarafından kullanılır) alan doğrulaması için DNS-01 doğrulamasını destekler. DNS-01, wildcard sertifikaları (*.example.com) destekleyen tek doğrulama türüdür ve hedef makinede bir HTTP sunucusu gerektirmez.

NexDNS, yaygın ACME istemcileriyle yerel entegrasyonlar ve manuel DNS hook'larını destekleyen her istemci için genel bir CLI hook sunar.

Tüm ACME entegrasyonları bir API jetonu gerektirir; bu jeton Pro ve üzeri planlarda kullanılabilir. Her istemci, doğrulama kaydını yazmadan önce bölgeyi arar; bu nedenle jetonun records.read ve records.write yanında zones.read izin kapsamına da ihtiyacı vardır. nexdns.tech/settings/api-keys adresinden bir tane oluşturun.

Wildcard nasıl doğrulanır

Doğrulama, doğrulanan adın altındaki _acme-challenge konumunda bir TXT kaydıdır. Hem example.com hem de *.example.com adreslerini kapsayan bir sertifika, aynı adda iki farklı doğrulama değeri üretir ve ikisinin aynı anda bulunması gerekir – aşağıdaki entegrasyonların hepsi bunu yönetir, bu yüzden iki doğrulama arasında kayıt kümesini asla silmemelisiniz.

Yayılıma zaman tanıyın

Bir doğrulama kaydının ad sunucularına ulaşması yaklaşık 30 saniye sürer, bu yüzden 30 saniyelik bekleme hiç pay bırakmaz - bir doğrulamanın NXDOMAIN ile başarısız olduğunu gördük. Sertifika otoritesine en az 60 saniye tanıyın: certbot eklentisi ve lego varsayılan olarak 60 bekler, acme.sh ve CLI hook'ta süreyi siz belirlersiniz.

acme.sh

acme.sh tamamen shell ile yazılmış bir ACME istemcisidir. DNS hook'umuz henüz bir acme.sh sürümüne dahil değil; bu yüzden ilk çalıştırmadan önce ~/.acme.sh/dnsapi/ dizinine koyun: curl -fsSL https://get.nexdns.tech/acme/dns_nexdns.sh -o ~/.acme.sh/dnsapi/dns_nexdns.sh. Önce okumayı tercih ederseniz aynı dosya CLI deposunda da bulunuyor.

Sertifika düzenleme

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

Jeton ilk çalıştırmadan sonra ~/.acme.sh/account.conf dosyasına kaydedilir, bu nedenle yenilemeler için tekrar dışa aktarmanız gerekmez.

Yenileme

Yenilemeler cron aracılığıyla otomatik olarak gerçekleşir. Manuel yenilemeyi zorlamak için:

acme.sh --renew -d example.com

Lego ve Traefik

lego, Go tabanlı bir ACME istemcisidir ve aynı zamanda Traefik'in otomatik sertifika yönetimini de sağlar. Sağlayıcı lego v5.4.0 ve sonrasında yer alır.

Bağımsız kullanım

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 zaman aşımlarını düz saniye sayısı olarak okur: NEXDNS_PROPAGATION_TIMEOUT=300 çalışır, 300s ise ayrıştırılamaz ve sessizce 60 saniyelik varsayılan değerle değiştirilir.

Traefik yapılandırması

Traefik, lego'nun sağlayıcı tablosunu derleme sırasında gömer ve hâlâ daha eski bir sürümü kullanır; bu yüzden burada lego v5.4.0 ile derlenmiş bir Traefik gerekir. NexDNS DNS doğrulama çözümleyicisini Traefik yapılandırmanıza ekleyin - aşağıdaki docker-compose.yml tipik bir kurulumu gösterir:

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:

Ardından çözümleyiciyi servis etiketlerinizde kullanın:

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 istemcisi

certbot, resmi Let's Encrypt istemcisidir. Otomatik DNS-01 doğrulaması için NexDNS DNS kimlik doğrulama eklentisini kullanın.

Eklentiyi kurma

Eklentiyi PyPI'den kurun ya da onu zaten içeren aşağıdaki Docker imajını kullanın.

pip install certbot-dns-nexdns

Kimlik bilgileri dosyası oluşturma

API jetonunuzla ~/.nexdns/certbot-credentials.ini dosyasını oluşturun:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Dosya izinlerini kısıtlayın:

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

Sertifika düzenleme

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

Docker kullanımı

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'

CLI hook entegrasyonu

ACME istemciniz manuel DNS hook'larını destekliyorsa, NexDNS CLI'yi bir hook betiği olarak kullanabilirsiniz. Bu, --manual-auth-hook ve --manual-cleanup-hook seçeneklerini sağlayan herhangi bir istemciyle çalışır (örn. manuel modda certbot).

certbot ile 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, certbot tarafından ayarlanan CERTBOT_DOMAIN ve CERTBOT_VALIDATION ortam değişkenlerini okur ve _acme-challenge TXT kaydını otomatik olarak oluşturur veya kaldırır.

Hook'ları kullanmadan önce CLI kimlik doğrulaması yapılmış olmalıdır. nexdns auth token nxd_xxx komutunu çalıştırın veya NEXDNS_TOKEN ortam değişkenini ayarlayın.