Let's Encrypt / ACME DNS-01

Obtain automatic TLS certificates using the DNS-01 challenge — DomU DNS handles the _acme-challenge TXT records directly. No HTTP port 80 required.

Prerequisites

Required: Your domain's NS records must point to your DomU DNS instance so Let's Encrypt can query _acme-challenge.<domain> TXT.

Step 1: Create a Named API Key

Named API keys are dedicated keys for external tools — separate from your root API key. Create one in the dashboard:

  1. Open the Dashboard → Settings → Security
  2. Scroll to API Keys → click + New API Key
  3. Enter a name (e.g. Traefik ACME) and save
  4. Copy the key — it is shown only once
Named API Keys are dedicated keys for external tools. Create them in the Dashboard under Settings → Security → API Keys. They are separate from your root API key.

Option A: Traefik (httpreq provider)

Traefik's built-in httpreq DNS provider uses Basic Auth. The Named API Key is used as the HTTP password.

Static configuration (traefik.yml)

yaml 
certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /acme/acme.json
      dnsChallenge:
        provider: httpreq

Environment variables

bash 
HTTPREQ_ENDPOINT=http://<domudns-ip>/api/acme/httpreq
HTTPREQ_USERNAME=traefik          # any string
HTTPREQ_PASSWORD=<named-api-key>  # from DomU DNS dashboard

Traefik will call POST /api/acme/httpreq/present with the DNS-01 token and POST /api/acme/httpreq/cleanup after validation.

Option B: Certbot DNS Plugin

Install the certbot-dns-domudns plugin, then use it like any other Certbot DNS plugin.

Install

bash 
pip install certbot certbot-dns-domudns

Credentials file /etc/letsencrypt/domudns.ini

ini 
certbot_dns_domudns:dns_domudns_url     = http://<domudns-ip>
certbot_dns_domudns:dns_domudns_api_key = <named-api-key>
bash 
chmod 600 /etc/letsencrypt/domudns.ini

Issue certificate (staging)

bash 
certbot certonly \
  --authenticator dns-domudns \
  --dns-domudns-credentials /etc/letsencrypt/domudns.ini \
  --server https://acme-staging-v02.api.letsencrypt.org/directory \
  -d example.com -d '*.example.com'

Issue certificate (production)

bash 
certbot certonly \
  --authenticator dns-domudns \
  --dns-domudns-credentials /etc/letsencrypt/domudns.ini \
  -d example.com -d '*.example.com'

Option C: acme.sh / Proxmox

Copy the hook script from the DomU DNS repository and use it with acme.sh or Proxmox ACME.

Install acme.sh and the hook

bash 
# Install acme.sh
curl https://get.acme.sh | sh

# Copy DomU DNS hook script
cp /path/to/domudns/scripts/dns_domudns.sh ~/.acme.sh/dnsapi/
chmod +x ~/.acme.sh/dnsapi/dns_domudns.sh

Issue certificate

bash 
export DOMUDNS_URL=http://<domudns-ip>
export DOMUDNS_API_KEY=<named-api-key>

acme.sh --issue --dns dns_domudns -d example.com -d '*.example.com'

Proxmox ACME (Datacenter → ACME → DNS Plugin)

Plugin ID domudns
API data DOMUDNS_URL=http://<domudns-ip>
DOMUDNS_API_KEY=<named-api-key>

Manual API Test

Verify the full flow before using an ACME client:

bash 
API=http://<domudns-ip>
KEY=<named-api-key>

# 1. Store challenge
curl -X POST $API/api/acme/dns-01/present \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","txt_value":"test-token-123"}'

# 2. Query DNS — must return "test-token-123"
dig @<domudns-ip> _acme-challenge.example.com TXT

# 3. Remove challenge
curl -X POST $API/api/acme/dns-01/cleanup \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Troubleshooting

Problem Solution
dig returns NXDOMAIN Challenge not stored yet, or TTL expired (default 60 s)
401 Unauthorized Use a Named API Key from Settings → Security → API Keys
Connection refused DomU DNS HTTP server not reachable on the configured port
Domain does not resolve NS records for the domain must point to your DomU DNS server
Rate limit exceeded Use staging: --server https://acme-staging-v02.api.letsencrypt.org/directory
Traefik: 401 Unauthorized HTTPREQ_PASSWORD must match the Named API Key exactly
← Previous