cf-ddns

View script Copied!

Update a Cloudflare DNS A record to match this machine's current outbound IP address – a lightweight dynamic DNS solution for home servers, dev machines, or any host behind a changing IP.

Designed to run periodically from the target host (via cron or systemd timer). Fetches the machine's public IP from ipify.org, compares it to the hostname's current DNS resolution via Google DNS, and updates Cloudflare only when they differ. The hostname can be a zone apex such as example.com or a name within that zone such as home.example.com.

Quick start

$ cf-ddns YOUR_API_TOKEN home.example.com
[INF][cf-ddns] Device's IP: 203.0.113.42
[INF][cf-ddns] Hostname's IP: 198.51.100.8 (home.example.com)
[INF][cf-ddns] IP addresses do not match, updating DNS
[INF][cf-ddns] Deleting A record for 198.51.100.8 (abc123...)
[INF][cf-ddns] Creating A record for 203.0.113.42

For home.example.com, the script selects the example.com zone and replaces only A records named home.example.com. A records for the zone apex and other hostnames are left alone. TTL is hardcoded to 60 seconds for fast propagation.

Create a Cloudflare API token:

Go to the Cloudflare dashboard > API Tokens
Create token with permissions: Zone.Zone (read) and Zone.DNS (edit)
Scope to the specific zone if desired

Common examples

Run from cron every 5 minutes:

# crontab entry
*/5 * * * * /path/to/cf-ddns YOUR_API_TOKEN home.example.com 2>&1 | logger -t cf-ddns

Enable debug output to see full curl logs and API call details:

$ DDNS_DEBUG=1 cf-ddns YOUR_API_TOKEN home.example.com
[DBG][cf-ddns] curl output logged to: /tmp/curl.12345.log
[DBG][cf-ddns] GET /zones
[INF][cf-ddns] Device's IP: 203.0.113.42
...

Pipe from the web (since this is published at toolio.sh):

curl -s https://toolio.sh/cf-ddns | bash -s -- YOUR_API_TOKEN home.example.com

How it works

Fetch the machine's outbound IP via curl https://api.ipify.org
Query the hostname's current A record via dig @8.8.8.8 +tcp +short $hostname (Google DNS, TCP mode to avoid UDP blocks)
Compare IPs – if they match, exit early with success
If they differ:
- Page through Cloudflare zones to find the zone containing the hostname
- Page through DNS records in that zone and select A records whose name exactly matches the hostname
- Delete the matching A records (this is why the script uses DELETE + POST instead of PUT)
- Create a new A record for the full hostname with the current IP and 60-second TTL

Replacing all A records for the requested hostname ensures a clean state even if multiple records exist from manual edits or migrations.

Reference

All options

Flag	Description
`-h, --help`	Show help message with synopsis, description, dependencies, and API token requirements

Arguments

Argument	Description
`api_token`	Cloudflare API token (required permissions: Zone.Zone, Zone.DNS)
`hostname`	Fully qualified DNS hostname to update (e.g. `home.example.com`)

Environment variables

Variable	Description
`DDNS_DEBUG`	Set to any value to enable verbose curl and debug output. Logs API calls and curl traces to stderr.

Exit codes

Code	Meaning
0	Success (IP already matched or DNS updated successfully)
1	Runtime failure (IP fetch failed, zone not found, API error)
2	Usage error (missing API token or hostname)
3	Dependency error (`curl`, `jq`, or `dig` missing)

Dependencies

curl -- API calls to Cloudflare and ipify.org
jq -- JSON parsing for API responses
dig -- DNS lookup via Google DNS (uses TCP mode with +tcp flag)

Warnings

Deletes all A records for the requested hostname before creating the new one. If that hostname has multiple A records for load balancing or failover, this script will remove them.
No retry logic – if the API call fails, the script exits with an error. Suitable for cron where the next run will retry.
Assumes IPv4 – only updates A records, not AAAA (IPv6). The ipify.org endpoint returns IPv4 by default.
Requires Zone.Zone and Zone.DNS permissions – the token must be scoped to at least read zones and edit DNS records.

Behavior

TTL: Hardcoded to 60 seconds (A_RECORD_TTL=60) for fast propagation during IP changes.
API version: Uses Cloudflare API v4 (https://api.cloudflare.com/client/v4).
Logging: Colored output via raw ANSI escapes, guarded by TTY check and NO_COLOR. All diagnostic levels ([INF], [ERR], [DBG]) write to stderr in the shape [LVL][cf-ddns] message.
Curl logs: When DDNS_DEBUG is set, full curl stderr/stdout is logged to /tmp/curl.$$.log (where $$ is the process ID).
TCP DNS queries: Uses dig +tcp to avoid issues on networks that block UDP DNS traffic.