pdns-admin/DYNAMIC_DNS.md

Dynamic DNS Client Guide

This application can update selected DNS records through a public Dynamic DNS API endpoint. Dynamic DNS is available only for A and AAAA records.

Prerequisites

• The application must be running with its MySQL application database configured.
• The DNS record must already exist or be created through the web UI.
• Dynamic DNS must be enabled on the target record.
• The client must have the generated dynamic DNS token for that record.

Enable Dynamic DNS for a Record

1. Sign in to the web UI.
2. Open the zone that contains the record.
3. Create or edit an A or AAAA record.
4. Check Habilitar atualizacoes de DNS dinamico.
5. Save the record.
6. Copy the generated token immediately.

The token is displayed only once. If it is lost, regenerate it from the zone record list.

Update Endpoint

Clients update records by sending a JSON POST request to:

/api/dyndns

Request body:

{
  "name": "www.example.org",
  "token": "generated-token",
  "address": "198.51.100.40"
}

Fields:

• name: DNS record name to update. A trailing dot is optional.
• token: Dynamic DNS token generated by the application.
• address: Optional IP address to publish.

If address is omitted, the application detects the client address in this order:

1. First IP in the X-Forwarded-For header.
2. X-Real-IP header.
3. The direct remote client IP.

For A records, the address must be IPv4. For AAAA records, the address must be IPv6.

Examples

Update an A record with an explicit IPv4 address:

curl -X POST https://dns-admin.example.com/api/dyndns \
  -H 'Content-Type: application/json' \
  -d '{"name":"www.example.org","token":"generated-token","address":"198.51.100.40"}'

Update an A record using the detected client IP:

curl -X POST https://dns-admin.example.com/api/dyndns \
  -H 'Content-Type: application/json' \
  -d '{"name":"www.example.org","token":"generated-token"}'

Update an AAAA record with an explicit IPv6 address:

curl -X POST https://dns-admin.example.com/api/dyndns \
  -H 'Content-Type: application/json' \
  -d '{"name":"ipv6.example.org","token":"generated-token","address":"2001:db8::40"}'

Responses

Successful update:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"status":"OK"}

Error responses use this shape:

{
  "error": "message"
}

Common status codes:

• 200 OK: Record was updated in PowerDNS.
• 400 Bad Request: Invalid JSON, record name, token format, IP address, or address type.
• 401 Unauthorized: Record name and token do not match an enabled Dynamic DNS record.
• 502 Bad Gateway: The application could not update PowerDNS.
• 503 Service Unavailable: The application database is not configured or unavailable.

Token Management

Dynamic DNS tokens are stored as hashes and are not displayed again after generation.

To replace a token:

1. Open the zone in the web UI.
2. Find the record marked DNS dinamico.
3. Click Regenerar token.
4. Copy the new token immediately.

After regeneration, the previous token no longer works.

To disable Dynamic DNS for a record, edit the record and clear Habilitar atualizacoes de DNS dinamico. Deleting the record also disables its Dynamic DNS configuration.

Security Notes

• Treat the token like a password.
• Use HTTPS in production so tokens are not sent in clear text.
• The /api/dyndns endpoint is public and does not require a web UI session.
• Authentication for updates is based on the record name and token.
• Rotate the token if it may have been exposed.