Floating Octothorpe

Cloudflare API: dynamic DNS

If you have a standard internet connection, your ISP will normally give you a dynamic IP address. For most users this is fine, however if you want to connect back to your home network this can be a problem.

Following on from last week's post, this post is going to go over how to use Cloudflare's API to dynamically update a DNS record.

Initial setup

To get started you will need to have already done the following:

  1. Registered a domain
  2. Setup a Cloudflare account
  3. Created an A record you want to manage dynamically
  4. Make a note of your Cloudflare API key

Once you've completed the steps above, you will need to decide where to run the update script. The script requires a Python environment and the requests module. On most Linux distributions such as CentOS, Debian and Ubuntu python will already be installed. There are a few ways you can install the requests module. In this instance I used Apt:

$ sudo apt-get update
$ sudo apt-get install python-requests

Update script installation

Once you have a done the initial setup steps above, you will need to get a copy of the update script. This can be done by cloning directly from Github:

$ git clone https://github.com/FloatingOctothorpe/cloudflare-dynamic-dns.git

Alternatively if you don't have git installed, you can download the script from the releases page. The first time the update script is run you will be prompted for your authentication details, zone name and A record name:

$ python update.py
CloudFlare registered email: [email protected]
Auth key: df4c90320bfa7ed984c5752ccb8f96e9d343c
Zone name: example.com
A record name: f-o.example.com
INFO:root:Saving new config to cloudflare-dynamic-dns.json
INFO:root:testing.f-o.example.com already points to 203.0.113.120, nothing to do

Assuming the details you entered were correct, the script will run through the following steps:

  1. Check your current public IP using ipify.org
  2. Prompt for configuration if no config is found
  3. Check your public IP address against the current DNS A record
  4. Update the DNS record using Cloudflare's API if required

The first time update.py is run, a configuration file called cloudflare-dynamic-dns.json will be created. This will allow the script to run without prompting for configuration:

$ python update.py
INFO:root:testing.f-o.example.com already points to 203.0.113.120, nothing to do

Note: the generated configuration will contain your API key, however the config should not be world readable.

$ ls -l cloudflare_dns_update.json
-rw------- 1 alice alice 152 Nov 15 21:29 cloudflare-dynamic-dns.json

Scheduling

For the Dynamic DNS entry to be dynamic, the update script needs to be run routinely. One way to automate this is with a cron job similar to the following:

*/15 * * * * cd /home/alice/cloudflare-dynamic-dns && python update.py > /dev/null

This cron job will run update.py every fifteen minutes. Note that the update script currently expects configuration in the current working directory, hence the cd. In the future I might add a --config option to avoid having to change directory.

Alternatives

If you would rather used better tested code you could consider using ddclient instead. Cloudflare provide setup instructions on their website.