David Schlachter

Configure ddclient for Cloudflare Dynamic DNS

Cloudflare offers free DNS services, including an API for updating DNS records, making this a great dynamic DNS system. I recently moved to Cloudflare from FreeDNS and wanted to keep using ddclient to update the IP addresses of my domains. It took me a while to get a working configuration — hopefully I can help you do the same. I'll assume you have a Cloudflare account set up with an A record for your domain.

Create an API token

Go to the "API Tokens" section your Cloudflare profile to create a token. Your new token needs to have:

Install the latest version of ddclient

Update 2024-11-19: ddclient 3.10 added support for CloudFlare API tokens and has been out for a couple years, so this section probably does not apply to you.

The current release of ddclient (3.9.1) doesn't support Cloudflare API Tokens. If you try to use an API token, you'll see errors like these ones:

WARNING: skipping host: davidschlachter.com: 'login=' is an invalid login.
WARNING: skipping host: \: 'login=' is an invalid login.

{"success": false, "errors": [{"code":6003, "message": "Invalid request headers", "error_chain":[{"code":6102, "message": "Invalid format for X-Auth-Email header"},{"code":6103, "message": "Invalid format for X-Auth-Key header"}]}], "messages":[], "result":null}

If a new release hasn't been made yet, you'll have to install ddclient from Github. For details, take a look at the project's README. I've also submitted a patch to allow you to build ddclient v3.10 RC2 on FreeBSD with ports.

Configure ddclient

With your token and an updated ddclient, you're now ready to configure it. Here's my configuration file:

daemon=300 # check every 300 seconds
syslog=yes # log update msgs to syslog
pid=/var/run/ddclient.pid # record PID in file
ssl=yes # use TLS
use=web # get IP with website below
web='https://cloudflare.com/cdn-cgi/trace'
web-skip='ip=' # IP address above is after 'ip='

protocol=cloudflare, \
zone=mydomain.tld, \
ttl=1,
password='cloudflare-api-token',
mydomain.tld,subdomain.mydomain.tld

Replace cloudflare-api-token with your API token, and mydomain.tld with your domain. Note that no username should be provided when using an API token. The last line is a comma-separated list of the domains to update.

I'm resolving my client's IP using CloudFlare's Trace tool. Note that this may return an IPv6 address if you have a dual IPv4/v6 stack. If this is a problem, you should consider another service to get your IP address.

Troubleshooting

It's helpful to run ddclient with the -verbose flag, which will show you each request that it makes, along with detailed error messages. For example, here's the error message I got when I had scoped my token to a particular zone, rather than to all zones in my account:

FAILED: updating \: Cannot set IPv4 to 174.129.141.119 No 'A' record at Cloudflare

When I had some weird syntax issue in my config file, I was seeing these errors:

file /var/cache/ddclient/ddclient.cache, line 4: Invalid Value for keyword 'ip' = ''

In the end, the successful update message looked like:

SUCCESS: updating davidschlachter.com: IPv4 address set to 174.129.141.119