OPNsense is a great open source firewall with lots of plugins and support for wireguard, dynamic DNS and many other. Few months ago, OPNsense decided to switch from dyndns (os-dyndns) to DDclient (os-ddclient) and it seems some users, including me, have issues with switching from legacy one to new one. In my case, I had to switch from Azure DNS to Cloudflare because ddclient doesn’t support Azure DNS. Configuring Cloudflare also did not work that well in the beginning, but after some research, it worked. This blog post is the summary of the research.

Step 1: Install ddclient dynamic DNS plugin

Open OPNsense admin panel and go to “System > Firmware > Plugins” and select os-ddclient (do not use os-dyndns as it is outdated and will no longer be supported). Once it is installed you can find “Dynamic DNS” under services.

Step 2: Configure dynamic DNS

Go to Cloudflare and add the DNS entry that should be set by ddclient. In this example, I will add an A record dyn.arminreiter.com with IP 0.0.0.0 (choose whatever you want), deactivated proxy and TTL of 5 minutes.

Within OPNsense, go to “Services > Dynamic DNS > Settings” and add a new dynamic DNS configuration and enter the values that fit your configuration:

• Enabled: true
• Service: Cloudflare
• Username: E-Mail address of your account
• Password: Global API key for your account (Open Cloudflare > My Account > API Tokens > Global API Key > View)
• Zone: your.domain (e.g. arminreiter.com)
• Hostname: full domain name you want to update (e.g. dyn.arminreiter.com)
• Check ip method: Interface
• Force SSL: true
• Interface to monitor: WAN

The DNS entry will be updated every 5 minutes. If you want to change the interval, go to “General Settings” and update the interval.

Thats it already. Once it ran, you should see the updated DNS entry within Cloudflare. In case it does not work or if you have any issues, check the next (Troubleshoot) section.

Troubleshoot

General Troubleshooting

If you have any issues, connect via ssh to OPNsense and try one of the following:

# run ddclient and show debug and verbose output (if you only get some "skipping update" message, just try again)
ddclient -debug -verbose

# check ddclient configuration
cat /usr/local/etc/ddclient.conf

# clean ddclient cache
rm /var/tmp/ddclient.cache

API Token does not work

Unfortunately, DDclient (v 3.9.1) does not work with Cloudflare API Tokens. There is a fix available which is not yet released. This is also discussed in OPNsense forum (https://forum.opnsense.org/index.php?topic=26446.300) and at GitHub (https://github.com/opnsense/plugins/issues/2842). Second one proposes as a workaround to quickfix the version until the update is released. This quickfix can be done as follows:

vi +4566 /usr/local/sbin/ddclient

change the header values to:

            my $headers = "";
            if ($config{$key}{'login'} eq 'token') {
                    $headers .= "Authorization: Bearer $config{$key}{'password'}\n";
            } else {
                    $headers .= "X-Auth-Email: $config{$key}{'login'}\n";
                    $headers .= "X-Auth-Key: $config{$key}{'password'}\n";
            }
            $headers .= "Content-Type: application/json";

save the file, open your configuration in OPNsense and replace the username with “token” and use your Cloudflare API token as password. This token must have the following configuration:

• Permissions:
  • Zone, Zone, Read
  • Zone, DNS, Edit
• Zone Resources:
  • Include, Specific Zone, [your zone]

The downside of this approach is, that an update of ddclient will overwrite the changes and you have to do it again. Therefore, the recommendation is to use the global API key until there is an official fix available.