Tornevall Networks

← Back to docs

Dynamic DNS

Dynamic DNS

ToolsAPI provides a Dynamic DNS layer under /api/dyndns for hosts whose public address can change over time.

The normal self-service namespace is:

<name>.dyn.tornevall.net

Nested names can be enabled per Dynamic DNS zone, for example:

router.home.dyn.tornevall.net

Administrators may add special Dynamic DNS namespaces and assign hosts outside the default namespace.

Authentication model

There are two separate authentication boundaries:

  1. Updater client -> /api/dyndns: a Dynamic DNS token is required.
  2. Dynamic DNS -> DNS writer: no second HTTP/API token is used inside ToolsAPI.

The Dynamic DNS controller validates the client token and host ownership, then calls the existing DNS services directly. The underlying DNS service handles its own provider credentials.

Each Tools user has one Dynamic DNS token. The same token can update every Dynamic DNS host owned by that user. The credential is stored in the shared api_keys storage with provider tornevall_dyndns, but it is a dedicated Dynamic DNS credential rather than a normal api_keys.access_scopes permission. Ordinary Tools API keys and their access scopes do not authorize /api/dyndns.

Tokens can be created or rotated from the canonical user surface at /me/dyndns.

Supported token transports:

  • Authorization: Bearer <token>
  • X-DynDNS-Token: <token>
  • HTTP Basic password for DynDNS-compatible clients
  • token=<token> as a compatibility fallback

Bearer headers are recommended for scripts and applications.

Update endpoint

Endpoint: POST /api/dyndns/update

Example:

curl -X POST https://tools.tornevall.net/api/dyndns/update \
  -H "Authorization: Bearer YOUR_DYNDNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"home.dyn.tornevall.net","address":"auto"}'

address="auto" uses the source address of the HTTP request.

An explicit address may also be sent:

{
  "hostname": "home.dyn.tornevall.net",
  "ipv4": "192.0.2.25"
}

or:

{
  "hostname": "home.dyn.tornevall.net",
  "ipv6": "2001:db8::25"
}

Multiple owned hosts can be updated in one request:

{
  "hosts": [
    "home.dyn.tornevall.net",
    "vpn.dyn.tornevall.net"
  ],
  "address": "auto"
}

Replacement semantics - stale records are removed

Dynamic DNS address updates are treated as desired state, not as ordinary DNS ADD operations.

For every A or AAAA RRset touched by an update, ToolsAPI:

  1. Reads the currently published address records.
  2. Explicitly deletes every existing value for that hostname and record type.
  3. Adds the one requested address, if that family is enabled.
  4. Reads the DNS data again and verifies that the resulting RRset contains exactly the requested address.

This prevents old addresses from remaining beside the new one and causing round-robin or double resolving.

The existing DNS safety rule is retained: ordinary DNS API calls are not given a generic empty-target RRset delete. Dynamic DNS removes the discovered address values explicitly and only manages A/AAAA records belonging to the Dynamic DNS host.

If a host is configured as IPv4-only, stale AAAA records are cleared. The inverse applies to IPv6-only hosts.

Host state

Endpoint: GET /api/dyndns/state?hostname=<hostname>

Authentication is required and the hostname must belong to the token owner.

Example response:

{
  "ok": true,
  "hostname": "home.dyn.tornevall.net",
  "ipv4": "192.0.2.25",
  "ipv6": null,
  "dns_status": "ok",
  "last_dns_sync_at": "2026-08-27T20:00:00+02:00"
}

The state endpoint can be consumed by a separate system that needs the latest address accepted for one of the token owner's hosts. Dynamic DNS does not grant that consumer any additional ownership or DNS-editing rights.

List hosts

Endpoint: GET /api/dyndns/hosts

Returns all Dynamic DNS hosts owned by the token user.

GET /api/dyndns is an equivalent authenticated host-list entry point.

Current client address

Endpoint: GET /api/dyndns/ip

Returns the address seen by ToolsAPI. A Dynamic DNS token is required.

DynDNS-compatible endpoint

For routers and devices with traditional Dynamic DNS support:

GET /api/dyndns/nic/update?hostname=home.dyn.tornevall.net&myip=192.0.2.25

If myip is omitted, ToolsAPI uses the source address of the request.

The Dynamic DNS token can be used as the HTTP Basic password.

Typical responses include:

good 192.0.2.25
nochg 192.0.2.25
nohost
badauth
dnserr

nochg means the address stored by ToolsAPI did not change. The DNS RRset may still be rewritten and verified in order to guarantee that stale address records have not survived.

Web interface

The canonical user management surface is:

/me/dyndns

The older GET /dyndns URL remains as a compatibility redirect to /me/dyndns. Existing legacy form/action URLs under /dyndns remain accepted for compatibility, while generated Tools links and forms use the canonical /me/dyndns routes.

The user surface is owner-scoped. A signed-in user, including an administrator using the user surface, can modify only Dynamic DNS hosts owned by that account. Cross-user administration stays under /admin/dyndns.

Users can:

  • create hosts in self-service zones
  • enable IPv4 and/or IPv6 management
  • set TTL
  • update a host from the current browser address
  • create or rotate the account Dynamic DNS token
  • see recent update history and DNS status

Administration remains at:

/admin/dyndns

Administrators can:

  • create additional Dynamic DNS namespaces
  • make zones self-service or admin-managed
  • allow or deny nested subdomains
  • configure IPv4/IPv6 availability and default TTL
  • create special hosts for a specific user
  • inspect all configured Dynamic DNS hosts

The API contract remains under /api/dyndns. Tools does not add version segments to Dynamic DNS routes.

Linux updater

A ready-to-use client is stored in:

scripts/dyndns/tools-dyndns.sh

Environment variables:

export DYNDNS_HOST="home.dyn.tornevall.net"
export DYNDNS_TOKEN="YOUR_DYNDNS_TOKEN"

Then run:

scripts/dyndns/tools-dyndns.sh

Use the operating system's scheduler if the updater should run periodically.

Windows updater

The Windows client is stored in:

scripts/dyndns/tools-dyndns.bat

Set DYNDNS_HOST and DYNDNS_TOKEN in the environment or in the scheduled task configuration, then run the BAT file through Windows Task Scheduler.

Storage

Dynamic DNS uses its own zone, host and update records. Dynamic DNS update tokens reuse the existing api_keys storage, with one dedicated tornevall_dyndns key per user. The token is ownership-bound and is not a general Tools API access scope.