CloudflareDDNS

Update your existing Cloudflare DNS records with your current (dynamic) IP address via systemd timers and a (POSIX) shell script.

Contents

• Prerequisites
• cfddns script
  • Installation
  • Usage
    • Parameters
• Cloudflare credentials file
  • File structure
  • Bearer token
  • Zone ID
• cfddns systemd service unit
  • IP4 or IP6
    • Examples
• cfddns systemd timer unit
  • Activation
• Logging
  • Using Logwatch to monitor this script
  • Using Logrotate to control log file size
• Final thoughts

Prerequisites

This script requires that curl and jq are installed. curl is used to interact with the Cloudflare API and jq is used to efficiently and reliably construct/deconstruct the JSON strings and arrays which is how the Cloudflare API communicates. In most cases you can install these programs using your package manager running as root or via sudo. On Debian/Ubuntu, for example, you would run:

apt install -y curl jq

While the script does not require root privileges, you will need sudo/root access to install the systemd service and timer.

cfddns script

Installation

I recommend putting this script in your /usr/local/bin directory or somewhere else in your path so it's easy to run.

1. Copy the script file to your desired path and rename if you want.

   sudo cp cfddns.sh /usr/local/bin/   # just copy it
   sudo cp cfddns.sh /usr/local/bin/cloudflare-update.sh   # copy and rename (choose any name)
   

2. Make it executable:

   sudo chmod +x /usr/local/bin/cfddns.sh
   

Note: You can rename cfddns.sh to anything you want, the script will auto-update itself. However, you must manually update the systemd service file (cfddns.service) ExecStart line as explained below.

Usage

If you run the script with no parameters, it will display the help screen. The script accepts several parameters with only one (1) being required. The parameters are summarized below. You can access the help screen and example usage screens by running:

cfddns.sh --help   # display help screen
cfddns.sh --examples   # show script usage examples

Parameters

Parameter	Description	Default	Required?
-r --record --records	The fully qualified hostname(s) that should be updated with new IP addresses. You can supply a comma-delimited list (no spaces) or just one. Note that the script can only update either A or AAAA records during a single run so you may need to batch your hostnames, depending on your set-up. N.B. This script will only update existing host records, it will not create new ones!	none	YES
-c --cred --creds --credentials -f	Full path to your CloudFlare credentials file. This file contains your access token and zone id. See the relevant section of this readme for more information.	scriptPath/cloudflare.credentials	NO
-i --ip --ip-address -a --address	The IP address that should be used to update Host A/AAAA records. If you omit this value, the script will attempt to auto-detect your public IP4/IP6 address and use that as appropriate. Use this option to manually force a specific IP to be used or when auto-detection fails. Note that the script does not check your IP addresses for correctness or proper form!	IP4 auto-detect	NO
-4 --ip4 --ipv4	Update Host A records only (IP4). The script can only update either A or AAAA records in a single run. If you specify this and also use the IP6 mode switch, the most recent one will take effect.	Enabled, update A records	NO
-6 --ip6 --ipv6	Update Host AAAA records only (IP6). The script can only update either A or AAAA records in a single run. If you specify this and also use the IP4 mode switch, the most recent one will take effect.	Disabled, update A records	NO
-l --log	Full path where the script should save its log. Recommend /var/log/scriptName.log	scriptPath/scriptName.log	NO
--nc --no-color --no-colour	Do not use ANSI colour-coding when writing to the log. This is useful if you review the logs using a reader that does not support ANSI colour-coding and instead displays control symbols which makes your log difficult to read.	Disabled, do colourful logs	NO
--log-console	Output the log to the console instead of a log file. You may use --nc with this option also.	Disabled, write to log file	NO
--no-log	Do not write a log file or output to the console. You will not have any feedback from the script if you run in this mode so you will not know if updates were successful or not. I’m not really sure why you’d want this option, but it’s available.	Disabled, write to log file	NO
-h --help -?	Display built-in help screen explaining these same parameters.
--examples	Display some usage examples. Sometimes it's just easier to understand by seeing rather than reading.

Cloudflare credentials file

This repo includes a sample credentials file (cloudflare.credentials at the root of the repo) with pretty self-explanatory variable names. The script reads this file to get the credentials it needs to connect to your Cloudflare account and update DNS entries. It should be noted that the script is designed to use a bearer token and not your username/password or your Global API token! Let’s break this down in case things are a little fuzzy still...

File structure

The file is a basic shell script variables file. Make sure you do not put spaces between the variable name, equal sign and the value. Also, do not add any executable code since it will be run! The file should contain values for the following two variables:

Variable	Value
cfKey	The bearer token granting access to edit the DNS records of the zone (domain) in question.
cfZoneId	The Cloudflare Zone ID of the zone (domain) you wish to update.

You can add comments if you’d like since the script will ignore them. In the end, your file should look something like this, but obviously with your data instead of this nonsense sample information:

#
# Cloudflare token for my.domain.tld
#

cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
cfZoneId=83d564234134513245311b23412331dd

You can save the file as anything you like and anywhere you’d like as long as you inform the script of its location using the --credentials parameter. By default, the script will look for a file named cloudflare.credentials in the same path as the script.

Please remember that this file basically contains a password! As a result, it should be protected and access limited to the root account:

chown root:root /path/to/cloudflare.credentials
chmod 600 /path/to/cloudflare.credentials

Bearer token

I chose to use an API bearer token instead of a username/password or Global API token for security reasons. Your username/password and Global API token provide unfettered access to your account so if anyone gets hold of them, they can do anything to your account. An API bearer token, by contrast, can only do what you authorize it to do and you can revoke it at any time. Therefore, I suggest making a bearer token that is based on the “Edit zone DNS” template and restricted to the specific domain/zone you wish to update. Cloudflare provides an excellent article on how to generate this token.

N.B. This is a breaking change from previous versions of this script!

Zone ID

This is required by the Cloudflare API so it knows which zone you are editing and can check the permissions of the bearer token. This script only caters to one zone so likely only one domain per configuration file. If you need to update multiple zones, you can have multiple configuration files and call them as required on separate invocations of the script.

To get your Zone ID, log into your Cloudflare account and open the domain in question. On the overview page, scroll down a bit and look to the right. You will see your Zone ID listed there. Copy that string into your configuration file.

cfddns systemd service unit

This file must be copied to your /etc/systemd/system directory (or equivalent directory if you're not running Debian/Ubuntu). If you change the name of the cfddns.sh file, you must update the filename in the ExecStart line as shown below:

...
[Service]
Type=oneshot
ExecStart=/full/path/to/your/renamed.file -parameter1 -parameter2 -parameter...
...

IP4 or IP6

The cfddns.service file includes two ExecStart lines, one without a specified IP-protocol parameter (default IP4) and the other with the -6 (IP6) parameter. The service will run the cfddns.sh script in default (IP4) mode with specified parameters first and then will run the script again in IP6 mode with specified parameters.

Note: The parameters can be different in each case.

Examples

1. Only update A records Update mail.example.com A record with the current auto-detected public IP4 address of this machine and log results to /var/log/cfddns.log.

   [Service]
   Type=oneshot
   ExecStart=/usr/local/bin/cfddns.sh -c /root/cloudflare.credentials -r mail.example.com -l /var/log/cfddns.log
   ...
   

2. Only update AAAA records Update git.example.com and mail.example.com AAAA records with the current auto-detected public IP6 address of this machine. Log will be stored in the same directory as the script file (/usr/local/bin).

   [Service]
   Type=oneshot
   ExecStart=/usr/local/bin/cfddns.sh -6 -c /home/johndoe/cloudflare.credentials -r git.example.com,mail.example.com
   ...
   

3. Update A records then AAAA records Update mail.example.com A record with auto-detected public IP4 address of this machine and write to log file stored at /var/log/DDNS_IP4.log. Then, update both mail.example.com and git.example.com AAAA records with the specified IP6 address and write to log file at /var/log/DDNS_IP6.log.

   [Service]
   Type=oneshot
   # update IP4 addresses
   ExecStart=/usr/local/bin/cfddns.sh -c /dir1/account.cf -r mail.example.com -l /var/log/DDNS_IP4.log
   # update IP6 addresses
   ExecStart=/usr/local/bin/cfddns.sh -6 -c /dir2/cloudflare.details -r mail.example.com,git.example.com --ip fd3f:e6db:9817:df84::a001 -l /var/log/DDNS_IP6.log
   ...
   

cfddns systemd timer unit

Just like the service file unit, this file must be copied to your /etc/systemd/system directory (or equivalent directory if you're not running Debian/Ubuntu). This timer file unit tells your system how often to call the cfddns.service file which runs the cfddns.sh script. By default, the timer is set for 5 minutes after the system boots up (to allow for other processes to initialize even on slower systems like a RasPi) and is then run every 15 minutes thereafter. Remember when setting your timer that Cloudflare limits API calls to 1200 every 5 minutes.

You can change the timer by modifying the relevant section of the cfddns.timer file:

[Timer]
OnBootSec=5min
OnUnitActiveSec=15min

OnBootSec is how long to wait after the system boots up before executing the cfddns.service. OnUnitActiveSec will then wait the specified time from that first (after boot) call or after the timer is explicitly started before calling cfddns.service again. I recommend setting OnUnitActiveSec to a low value (like 2 minutes) for testing then setting it to a more reasonable time (like 15 minutes) after everything is working.

After you’ve copied both the systemd unit and this timer unit, don’t forget to reload the systemd daemon so they are recognized by the system! On most systems you can do this by running the following as root or via sudo:

systemctl daemon-reload

Activation

You can start the timer system immediately via systemctl

systemctl start cfddns.timer

and can enable it to start automatically on boot by typing

systemctl enable cfddns.timer

You can check the status of the timer via systemctl also

systemctl status cfddns.timer

It is NOT necessary to enable/start the cfddns.service, only the timer needs to be active.

Also remember that if you make changes to settings like OnUnitActiveSec while testing or after testing is complete you must reload the systemd daemon! It will restart the appropriate units for you and your new settings will take effect immediately.

Logging

The script logs every major action it takes and provides details on any errors it encounters in the log file (see the parameters section for details about setting log location and name). If errors are encountered, they are colour coded red and an explanation of the error code is provided.

While the log file is as terse as I felt reasonable, you may still want to configure any log-watch programs to further filter things for you so you don't have to review this log as part of your daily routine. To make that easier, the following conventions are observed in the log file and can be used to program your log-watch system:

• Specific update process errors: [TIMESTAMP] ERR: message
  • These can be counted/filtered separately if you only care about update errors and not any other errors.
• Error messages: [TIMESTAMP] ERROR: message (code: number)
  • Only one summary error message will be displayed for any/all update errors. This message contains a tally of failed updates. If you want to count individual update errors, filter for the above process error message format.
  • While process error messages only relate to updates, these general error messages are logged for a variety of error conditions so it’s a good idea to include them in any filters.
• Cloudflare API error messages: [TIMESTAMP] CF-ERR: message (code: cf-error-code)
  • These are only logged when update process errors occur so that you can see exactly what the Cloudflare API is complaining about.
• Specific update process warnings: [TIMESTAMP] WARN: message
  • These can be counted/filtered separately from general warning messages. Presently, there are no general warning messages.
• Warning messages: [TIMESTAMP] WARNING: message
  • Summary of each type of warning. Contains a tally of the specific warning.
  • Currently, warnings are only issued for hostnames that are not found (i.e. update process warnings).
• Success messages: [TIMESTAMP] SUCCESS: message
  • Each successful update generates a success message. There is no process or tally message.
• Already up-to-date: [TIMESTAMP] IP address for {fqdn} is already up-to-date
  • Already up-to-date host entries generate a success message but you may still want to filter for them separately using this criteria.
• A session log always starts with [TIMESTAMP] -- Cloudflare DDNS update-script: starting --
• A successful session log always ends with [TIMESTAMP] -- Cloudflare DDNS update-script: completed successfully --
• A session ending with errors always ends with [TIMESTAMP] -- Cloudflare DDNS update-script: completed with error(s) --

Using Logwatch to monitor this script

If you are using the Logwatch package to monitor your system, see the README in the /etc/logwatch folder for details about the pre-configured service files already done for you :-)

Using Logrotate to control log file size

Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great way to automatically rotate your log files and control how many old logs you keep on your system so they don't accumulate and eat up your disk space. I've included a sample configuration file you can copy to your /etc/logrotate.d/ folder. This file is set up to rotate your logs once a week, keep 3 weeks worth of history (compressed) and delete all logs older than that. The configuration file is located in this git archive at /etc/logrotate.d/cfddns and is fully commented to help you customize it to suit your needs.

Final thoughts

Hopefully this helps you with an easy and reliable way to update your Cloudflare DNS entries with a dynamic IP address. Please feel free to comment and provide feedback and suggestions to make this script better!

Please check out my blog at https://mytechiethoughts.com where I tackle problems like this all the time and find free/cheap solutions to tech problems.