OPNsense DynDNS via Cloudflare API: Automating Dynamic Public IPs

Many small and mid-sized businesses face the same problem: The fibre or VDSL line delivers a dynamic public IP, but the site-to-site VPN, remote access to the phone system or a self-hosted mail server need a stable DNS name. Classic DynDNS providers like No-IP or DynDNS.org still work, but in a business context they are increasingly unattractive: TTLs of five minutes, sluggish propagation, occasional account suspensions and weak two-factor options.

If you already hold your domain at Cloudflare, you have a much more elegant lever: OPNsense updates an A record directly in your own zone via the Cloudflare API. The os-ddclient plugin in OPNsense 25.1 supports Cloudflare natively, the API token can be scoped precisely to a single zone, and the TTL can be set to Cloudflare’s minimum of one minute. In this article we show the full setup path, how to handle multi-WAN scenarios and the gotchas we have run into during real-world projects at DATAZONE.

Why Cloudflare as a DynDNS backend

Cloudflare is best known as a CDN and DDoS provider, but as a side effect it operates one of the fastest and most stable DNS services worldwide — with DNS servers in more than 300 PoPs. For DynDNS purposes that brings three concrete benefits:

• Low TTL: Cloudflare allows a TTL of one minute even on Free zones. Classic registrars like INWX, IONOS or Strato usually enforce 300 or 600 seconds minimum.
• Fast global propagation: API-driven updates are typically visible worldwide in under 30 seconds. In our tests from Munich, Frankfurt and Singapore we measure propagation times between 15 and 45 seconds.
• Clean token model: API tokens can be scoped per zone and per permission. A token that may only DNS:Edit on the zone company.com cannot do account-wide damage if stolen.

On top of that: If you already host the domain at Cloudflare, you save another external account and another password in the stack.

Creating the API token in Cloudflare

The first step happens in the Cloudflare dashboard. Under “My Profile — API Tokens — Create Token” do not pick the Global API Key (which has full account access). Instead create a Custom Token with minimal rights:

Permission	Scope	Value
Zone — DNS	Edit	enabled
Zone — Zone	Read	enabled
Zone Resources	Include — Specific Zone	company.com
Client IP Filter	Operator: is in — IP/CIDR	optional
TTL	Start now — expires never	recommended

The “Client IP Filter” is optional, but in multi-WAN setups it is dangerous: If the OPNsense currently routes through the backup uplink and you filtered for the primary IP, the update fails. In practice we leave the filter open and instead secure the token via token rotation every six months.

After clicking “Create Token” the string is shown exactly once. Store it securely in your password manager — Cloudflare will never show it again.

Installing os-ddclient in OPNsense

The os-ddclient plugin is not part of the default package set, but installs with one click. In the OPNsense web UI:

1. System — Firmware — Plugins
2. Search for os-ddclient in the list
3. Click the ”+” and confirm the installation
4. After roughly 30 seconds a new entry appears under Services — Dynamic DNS

Under the hood the ddclient daemon is installed. Since version 4.0 it ships with a natively supported protocol=cloudflare module. Earlier versions needed workarounds with nsupdate — thankfully that is history.

Configuring account and service

In Services — Dynamic DNS — Settings you create two objects: an account (your Cloudflare access) and a service (the actual DNS record).

The account entry only needs the API token; a descriptive name is otherwise enough. Configure the service like this:

Enabled:      yes
Description:  fw-neuburg cloudflare
Service:      Cloudflare (v4)
Account:      cloudflare-company-com
Username:     <leave empty -- only needed for Global Key>
Hostname:     fw.company.com
Zone:         company.com
TTL:          60
Check IP Mode: Interface
Interface:    WAN
Force SSL:    yes

Important detail: Set “Check IP Mode” to “Interface”, not “Web”. The “Web” mode queries an external service for your own IP — it works, but it is fragile on multi-WAN or CG-NAT uplinks. The Interface mode reads the IP directly from the OPNsense WAN interface and is deterministic.

Multi-WAN: two records, two services

Things get interesting when the firewall has two active WAN uplinks — typically fibre primary plus LTE backup. Here you create two separate service entries, each with its own hostname:

Hostname	Interface	TTL	Purpose
fw-fibre.company.com	WAN	60	Primary endpoint for VPN
fw-lte.company.com	WAN2	60	Backup endpoint, always active
fw.company.com	WAN	60	CNAME or dynamic round-robin

The third entry fw.company.com is usually implemented as a two-stage solution: A Cloudflare Worker reads both records and returns the reachable one. If you want it simpler, just use both hostnames directly in the OPNsense site-to-site VPN profile as failover endpoints.

Important: If the OPNsense actively load-balances both interfaces through a gateway group, the DDNS service should still run per interface, not via the gateway group. Otherwise the IP detection switches with every routing flip and you flood Cloudflare with update requests.

Subdomain handling and wildcard records

Cloudflare manages subdomains as independent records. The os-ddclient plugin can update exactly one record per service. If you need multiple subdomains — for instance mail.company.com, vpn.company.com, cloud.company.com — all pointing to the same dynamic IP, there are two clean paths:

1. Multiple services in OPNsense: One service entry per subdomain. Works, but becomes unmanageable from four or five records onward.
2. One A record, multiple CNAMEs: Only update fw.company.com via DynDNS, and point all other hostnames as CNAME to fw.company.com. This is the clean variant.

Note: Cloudflare’s “CNAME flattening” makes it possible to point even the root domain company.com as a CNAME to fw.company.com — something classic DNS does not allow. Useful when the apex domain should resolve to a self-hosted web server behind the OPNsense.

Wildcard records (*.company.com) can also be updated, but the hostname must be entered in OPNsense exactly as *.company.com and the wildcard record must be created manually in Cloudflare beforehand.

Troubleshooting and monitoring

In Services — Dynamic DNS — Log File you see every update attempt with timestamp. Typical patterns:

• SUCCESS: updating fw.company.com — all good, record is set.
• WARNING: skipped, no IP change — normal, IP has not changed.
• ERROR: Cloudflare API returned 9109 — the API token lacks rights or is scoped to the wrong zone.
• ERROR: could not determine IP — “Check IP Mode” is Interface but the interface is down.

For production setups we recommend additional external monitoring — such as Uptime Kuma or Checkmk — that resolves the DNS record every 60 seconds and compares it against the expected IP. That way silent token expirations are detected immediately, not only when the site-to-site VPN at the customer no longer comes up.

If you run OPNsense in production with a dynamic public IP and want to integrate it cleanly into the Cloudflare ecosystem, DATAZONE supports you with setup, multi-WAN architecture and monitoring. Complete firewall migrations from Sophos or Lancom to OPNsense are also part of our daily business in Neuburg an der Donau. Get in touch via our contact form or by phone.