cloudflareddns

A tiny command line utility for implementing DDNS with Cloudflare.

• Supports virtually any server that is capable of running Python
• Synology DiskStations supported
• Quick to install using yum/dnf or pip

Synopsis

Update DNS A record for foo.example.com to 1.2.3.4

cloudflareddns --hostname foo.example.com --ip 1.2.3.4

Likewise, for an AAAA record:

cloudflareddns --hostname foo.example.com --ip 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Get all options by simply running cloudflareddns -h:

usage: cloudflareddns [-h] [--email EMAIL] [--key KEY] [--hostname HOSTNAME]
                      [--ip IP] [--ttl TTL] [--verbose] [--version]

Update DDNS in Cloudflare.

optional arguments:
  -h, --help           show this help message and exit
  --email EMAIL        Cloudflare account email (omit if using API tokens)
  --key KEY            Cloudflare API key or token
  --hostname HOSTNAME  Hostname to set IP for
  --ip IP              The IP address
  --ttl TTL            TTL in seconds
  --verbose
  --version            show program's version number and exit

When invoked without any options, cloudflareddns will try to point the FQDN (aka <hostname>.<domain-name> of the machine it runs on to its public IP address (auto-detected).

Install and use with Synology DiskStations

You can configure a Synology DiskStation with CloudFlare DDNS.

It's worth noting that if your Synology DSM is recent enough, you can simply use Synology's own DDNS service, then create a CNAME record at your domain that points to it. The downside to this solution, however, is extra DNS lookup required to resolve domain to IP.

Alternative solution is to use cloudflaredns which ships with the necessary CLI interface for Synology compatibility: cloudflareddns-syno.

Step 1. Access Synology via SSH

• Login to your DSM
• Go to Control Panel > Terminal & SNMP > Enable SSH service
• Use your client or commandline to access Synology. If you don't have any, I recommend you try out Putty for Windows.
• Use your Synology admin account to connect.

Step 2. Install cloudflareddns

If you're not a lazy man, checkout instructions on installing using virtualenv for this step. For quick setup instead:

curl https://bootstrap.pypa.io/get-pip.py | python
pip install cloudflareddns

Run the following command to add new DDNS provider:

cat >> /etc/ddns_provider.conf << 'EOF'
[USER_Cloudflare]
        modulepath=/bin/cloudflareddns-syno
        queryurl=https://www.cloudflare.com/
EOF

Step 3. Get Cloudflare parameters

It is recommended to use a Cloudflare API token. Check the wiki page for instructions on how to get an API token with the most secure permissions.

Alternatively, you can get Cloudflare global API key in your account settings.

Step 4. Setup DDNS

• Login to your DSM
• Go to Control Panel > External Access > DDNS > Add
• Select Cloudflare as service provider
• Enter your domain as hostname
• If using token authentication: enter x in the Username/Email, and API token as Password/Key. The requirement to put x is due to Synology GUI's constraints not allowing for an empty field
• If using global API key: enter your Cloudflare account as Username/Email, and API key as Password/Key

Installation for CentOS/RHEL 7, 8

sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm
sudo yum install cloudflareddns

Installation for other systems

Installing with pip is easiest:

pip install cloudflareddns

Cloudflare library compatibility

cloudflareddns currently targets the cloudflare PyPI package v2.x line. The upstream v3.0 release was a complete API rewrite and is not compatible with this tool. The pip install above pins cloudflare<3 automatically, so you don't need to do anything manually. If you previously installed a v3+ release in the same environment, run pip install 'cloudflare<3' to downgrade.

Usage in Python scripts

from cloudflareddns import cloudflareddns
hostname = 'foo.example.com'
ip = '1.2.3.4'
if cloudflareddns.updateRecord(hostname, ip):
  print('Record is OK')
  ...

Requires using environment variables (see tips below).

Specifying Cloudflare credentials

In non-Synology systems, you can store Cloudflare credentials in either environment variables or a configuration file.

Via configuration file

Create ~/.cloudflare/cloudflare.cfg and put:

[CloudFlare]
email = user@example.com # Do not set if using an API Token
token = xxxxxxxxxxxxxxxxxxxxxxxxxxx

Via environment variables

You can put your Cloudflare credentials into the ~/.bashrc file:

export CF_API_EMAIL="user@example.com" # Do not set if using an API Token
export CF_API_KEY="xxxxxx"

Don't forget to source ~/.bashrc if you have just put credentials in there. The cloudflareddns will pick those up, so no need to pass --email or --key every time.