CloudflareDDNS

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

Contents

• CloudflareDDNS
  • 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
    • JSON format
    • SYSLOG format
    • Systemd journal (journald)
    • 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 returned by the Cloudflare API. If you want to log to the system journal (journald), then logger must also be installed. In most cases you can install these programs using your package manager running as root or via sudo:

# Debian/Ubuntu
sudo apt update && sudo apt install -y curl jq bsdutils

# Arch
sudo pacman -Sy curl jq logger

# Redhat/CentOS/Fedora
sudo dnf install curl jq util-linux

# Redhat/CentOS/Fedora (older versions)
sudo yum install curl jq util-linux

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 it 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 automatically use its current name. 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
--log-file	Generate a log file and save it in the specified location. Only specify this option if you want to save the log file in a non-default location. If you want to save the log in the default location, omit this option. Recommend /var/log/scriptName.log	scriptPath/scriptName.log	NO
--log-journal	Log to the system journal (journald) instead of a log file. Log entries are automatically tagged 'CFDDNS' for easier filtering. Format tags do NOT apply when using this option. Use json or pretty-json with journalctl to see all logged properties.	Disabled, write to log file	NO
--log-console	Write log entries to the console (stdout) instead of a log file. Using --fmt-syslog with this option is strongly recommended since JSON is difficult to read on the console.	Disabled, write to log file	NO
--no-log	Do not write a log file, write to the journal, 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
--fmt-json	Write the log file or console output in a structured Compact Log Event Format (CLEF) JSON format. You will probably need a log viewer to meaningfully parse the logs.	Enabled	NO
--fmt-syslog	Write the log file or console output in a modified plain-text syslog style. This option is recommended when using --log-console or if you need easily readable log files. While all log entries are consistent using this format, they are not structured.	Disabled, just JSON format	NO
-h --help -?	Display built-in help screen explaining these same parameters.
--examples	Display some usage examples. Sometimes it's 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 at 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, only permits actions you explicitly authorize when you create it, 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

For the easiest implementation, this file should be copied to your /etc/systemd/system directory. 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.

N.B. This is a oneshot type systemd unit-file, so we can have multiple ExecStart lines.

Examples

1. Only update A records Update the A record for mail.example.com with the current auto-detected public IP4 address of this machine and log in JSON format (default) to /var/log/cfddns.log. Note our Cloudflare credentials file is located in the root user's home directory.

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

2. Only update AAAA records Update AAAA records for git.example.com and mail.example.com with the current auto-detected public IP6 address of this machine. The log will be stored in the same directory as the script file (default) and will be JSON-formatted (default). In this case, the Cloudflare credentials file is located in /home/johndoe.

   [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 the A record for mail.example.com with the auto-detected public IP4 address of this machine. Then, update AAAA records for both mail.example.com and git.example.com with the specified IP6 address. In both cases, we are logging to the system journal (journald). Also notice that the Cloudflare credentials file is located in different places for each script call.

   [Service]
   Type=oneshot
   # update IP4 addresses
   ExecStart=/usr/local/bin/cfddns.sh -c /dir1/account.cf -r mail.example.com --log-journal
   # 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 --log-journal
   ...
   

cfddns systemd timer unit

Again, for the easiest configuration, this file should be copied to your /etc/systemd/system directory. 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.

Remember to reload systemd after you’ve copied both the systemd unit and this timer unit. Run 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. Refer to the parameters section for details about setting log location and name. Starting in version 3.0, the entire logging system outputs structured JSON by default.

PLEASE remember to review your current log review/parsing system if upgrading from previous versions since this is a major change to how logging works.

IMPORTANT: This script uses the same log file for its output (unless you specify a different log file each time it is run) therefore, you should avoid switiching formats within existing log files. For example, if you are using the default log file, and run the script once with --fmt-syslog then switch to the default --fmt-json, parsing your log will become very difficult. If you are switching log formats, it is best to start with a fresh log file.

JSON format

This is the default logging format since it allows for easy parsing and filtering of log entries while still retaining a structured format. I chose to implement a modified Compact Log Event Format (CLEF) with the following format for every message (expanded for readability, the log file is not 'pretty-printed'):

{
  "@t": "ISO-8601 timestamp",
  "@m": "message describing the event",
  "@l": "log level",
  "hostname": "hostname of the machine executing the script",
  "programName": "CFDDNS",
  "pid": "PID of the process executing the script",
  "status": "status of the operation being logged",
  "operation": "short-name of the operation being logged",
  "code": "numeric 'exit code' of the operation being logged"
}

SYSLOG format

The SYSLOG format (--fmt-syslog) is a modified version of the typical plain-text *nix syslog format. This format is useful when outputting the log to the console or when you need a very human-friendly format for the log files since you will be manually parsing them. While the plain-text format is not structured, it is consistent:

ISO-8601 timestamp hostname CFDDNS[pid]: LOG_LEVEL STATUS MESSAGE (OPERATION:CODE)

Systemd journal (journald)

When using the --log-journal option, all logging will be sent to journald using its format. All log messages are tagged CFDDNS to make filtering easier. Additional information logged with each entry can be exposed using the json or json-pretty output options for journalctl.

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 most linux 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/inexpensive solutions to tech problems.