Quick answer

Before configuring Dynamic DNS, compare your router WAN address against an external IP lookup. An address inside 100.64.0.0/10 means ISP CGNAT, so inbound IPv4 port forwards fail regardless of DNS updates. With a real public IPv4 or routable IPv6 prefix, update one Cloudflare zone record using a Zone DNS Edit token.

Contents

At a glance

Class
Networking

Provenance

  • Nov 14, 2026Published

Most Dynamic DNS tutorials start inside the Cloudflare dashboard. Skip that trap.

Dynamic DNS only solves one narrow problem: rewriting an A or AAAA record after your ISP hands your router a new address, which helps only when unsolicited packets from the outside world can reach your WAN interface in the first place. It never punches through carrier-grade NAT. If an upstream ISP translator swallows inbound packets before they reach your home router, your updater container will happily log SUCCESS every five minutes while every outside connection times out in silence.

Whenever I wire remote access on a residential circuit, DNS comes second. Proving the WAN address is routable comes first.

Step 0: Run the CGNAT and IPv6 check before touching DNS

Log into your router or firewall status screen and read the IPv4 address assigned to its WAN interface. Do not rely on an external “what is my IP” site yet. Read the interface itself.

Now fetch what the public internet sees from a shell on the same LAN (curl -4 https://1.1.1.1/cdn-cgi/trace) and compare the ip= line against your router’s WAN status page. Three distinct outcomes show up on residential lines:

Router WAN IPv4Matches external IP check?What is happeningWill IPv4 DDNS + port forward work?
Public range (e.g., 71.x.x.x)YesDirect routable dynamic IPv4Yes
100.64.0.0 – 100.127.255.255NoISP CGNAT (100.64.0.0/10)No (use IPv6, overlay VPN, or tunnel)
192.168.x.x, 10.x.x.x, 172.16-31.x.xNoDouble NAT behind ISP combo gatewayOnly after bridging the ISP gateway

If your WAN address lands anywhere between 100.64.0.1 and 100.127.255.254, stop before installing any IPv4 updater. IETF RFC 6598 allocates 100.64.0.0/10 as Shared Address Space specifically so service providers can number the link between a carrier-grade NAT translator and customer-premises routers. Dozens of households sit behind the same public IPv4 address. None of the inbound ports on that public address belong to your router, which is also the first gate in our port forwarding troubleshooting checklist.

Check IPv6 next before giving up on direct ingress. Many fiber, cable, and 5G home gateways that put IPv4 behind 100.64.0.0/10 still delegate a globally routable /56 or /60 IPv6 prefix (2000::/3).

With IPv6, NAT disappears. Your Linux host or reverse proxy holds its own global 2xxx:... address, and your firewall opens a targeted IPv6 pinhole to that host rather than translating a WAN port. One detail trips people up here: modern operating systems rotate RFC 8981 privacy extensions (Temporary IPv6 Address) daily for outbound browsing. Always run your AAAA DDNS updater on the target server itself—or bind its stable SLAAC/DHCPv6 interface identifier—so the published AAAA record matches the exact host address your firewall allows.

Create a single-zone Cloudflare API token

Years ago, scripts authenticated to Cloudflare with an account email and the Global API Key. Retire that habit permanently. One leaked Global API Key exposes every domain, Worker, tunnel, and billing setting inside your account at once.

Cloudflare’s API token workflow and token template reference ship a purpose-built Edit zone DNS template that restricts automated updaters to the single domain they actually need to touch:

  1. Open My Profile → API Tokens → Create Token in the Cloudflare dashboard and choose Edit zone DNS.
  2. Set Permissions to Zone → DNS → Edit. Leave account-level permissions empty.
  3. Under Zone Resources, select Include → Specific zone → example.com so a leaked .env file on one homelab host cannot touch any other domain you own.
  4. Create the initial A record (such as vpn.example.com pointing to 192.0.2.1) in the Cloudflare DNS tab first if your chosen client expects an existing record to update, and leave Proxy status set to DNS only (grey cloud) for non-HTTP protocols or direct ACME validation.

Test the token once from a terminal before burying it inside a daemon config:

curl -sS "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_SCOPED_CF_API_TOKEN"

When the JSON reply prints "status":"active", the credential works. No guesswork required.

Three reliable ways to update Cloudflare DNS

Cloudflare’s dynamic IP documentation points to API clients, ddclient, and tunnels depending on where your edge lives. Pick the updater that sits closest to the interface you actually want published.

Option 1: Stateless Docker container (favonia/cloudflare-ddns)

If your homelab runs Docker on Debian, Ubuntu, or a Proxmox VM and you want zero config files on disk, favonia/cloudflare-ddns is clean and tiny. It drops root privileges, reads your scoped token from an environment variable or Docker secret, creates missing records automatically, and supports both A and AAAA records.

services:
  cloudflare-ddns:
    image: favonia/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    network_mode: host
    restart: unless-stopped
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    environment:
      - CF_API_TOKEN=YOUR_SCOPED_CF_API_TOKEN
      - DOMAINS=vpn.example.com,home.example.com
      - PROXIED=false
      - IP6_PROVIDER=none
      - TZ=America/Chicago

Using network_mode: host matters the moment you switch IP6_PROVIDER from none to cloudflare.trace. Inside a default Docker bridge without IPv6 routing, the container cannot see the host’s global IPv6 address; on the host network stack, it reads the exact egress address your server owns.

Option 2: OPNsense at the router edge (os-ddclient)

When you run an OPNsense mini-PC firewall at the perimeter, IPv4 DDNS belongs on the router itself because OPNsense already owns the WAN interface.

According to the OPNsense Dynamic DNS manual, install os-ddclient under System → Firmware → Plugins, then open Services → Dynamic DNS → Settings. In General Settings, pick native as the backend—OPNsense’s Python-native client handles Cloudflare token auth cleanly without legacy Perl quirks. Add an account with these exact fields:

  • Service: Cloudflare
  • Username: leave completely blank when authenticating with a scoped API token
  • Password: paste your Zone:DNS:Edit API token
  • Zone: example.com
  • Hostname(s): vpn.example.com
  • Check ip method: Interface [IPv4] bound to WAN (when your WAN holds a real public IPv4)

Reading the interface directly avoids hitting external IP echo servers every five minutes and prevents a LAN VPN policy-routing rule from accidentally publishing your commercial VPN exit IP as your home address.

Option 3: Bare-metal Linux daemon (ddclient)

On a minimal Debian or Proxmox host where you prefer standard distro packages over an extra container, upstream ddclient supports Cloudflare natively from v3.9.0 onward (ensure v3.10+ on Debian 12/Ubuntu 24.04 for clean Bearer token headers). Edit /etc/ddclient.conf with 0600 root-only permissions:

daemon=300
syslog=yes
ssl=yes
usev4=webv4, webv4=https://1.1.1.1/cdn-cgi/trace, webv4-skip='ip='

protocol=cloudflare, \
zone=example.com, \
ttl=1, \
password='YOUR_SCOPED_CF_API_TOKEN' \
vpn.example.com

In Cloudflare’s API, ttl=1 means “Automatic” (which Cloudflare serves as 300 seconds on unproxied records), or you can pass an explicit integer from 60 upward. Run sudo ddclient -daemon=0 -debug -verbose -noquiet once during setup to watch the exact HTTPS request and verify "success":true in real time.

Cloudflare DDNS vs DuckDNS

Not every homelab needs a custom domain on day one. DuckDNS remains popular because its entire update protocol is a single HTTPS GET request (https://www.duckdns.org/update?domains=yourname&token=YOUR_UUID&ip=) that runs from a one-line cron job with curl on almost any busybox router.

FactorCloudflare DDNS (own domain)DuckDNS (*.duckdns.org)
Annual domain costStandard TLD renewal (~$10–$15/yr)Free subdomain
Auth isolationScoped Zone:DNS:Edit token per zoneSingle account UUID token covers all 5 subdomains
TLS wildcard certsFull DNS-01 ACME (*.home.example.com)Limited to your *.duckdns.org prefix; shared public suffix rate-limit pool
Custom recordsMX, SRV, CAA, TXT, multiple A/AAAAA, AAAA, and one TXT record

My rule is straightforward. Pick by TLS needs. Use DuckDNS when you want a zero-dollar hostname for a single self-hosted WireGuard endpoint tonight, then move to an inexpensive domain on Cloudflare the moment you deploy Caddy, Nginx Proxy Manager, or Traefik and want valid Let’s Encrypt DNS-01 wildcard certificates across internal LAN services without ever exposing port 80 to the public internet.

TTL math: how long an IP change stalls access

People routinely blame their DDNS container when reconnects stall for forty minutes after a modem reboot. Usually the container updated Cloudflare in two minutes. Cached DNS records did the rest.

Worst-case cutover lag equals two timers added together:

$$\text{Max Stale Window} = T_{\text{poll}} + \text{TTL}_{\text{DNS}}$$

Suppose your client polls every 300 seconds (5 minutes) and your A record carries a legacy 3600-second (1 hour) TTL. If a recursive resolver caches your old IP ten seconds before your ISP forces a new DHCP lease during an overnight maintenance window, clients behind that resolver can keep dialing the dead IP for up to 65 minutes. Drop the record TTL to 120 or 300 seconds while keeping a 300-second poll interval, and the worst-case stale window shrinks to 7 to 10 minutes without hammering Cloudflare’s API.

When to skip DDNS and port forwarding altogether

Even with a clean public IPv4 and a 60-second TTL, opening router ports is no longer the default answer for every homelab workload.

  • Private admin access (Proxmox UI, SSH, SMB, RDP, Home Assistant): Skip public DNS and inbound ports if only your own phones and laptops connect. An outbound mesh VPN works through CGNAT, hotel Wi-Fi, and double NAT with zero firewall holes; see our Tailscale vs WireGuard breakdown for when raw kernel WireGuard still wins on throughput and battery life.
  • Public HTTPS apps behind CGNAT: When family or webhooks need browser access without installing VPN client apps—and your ISP locks you inside 100.64.0.0/10—an outbound cloudflared daemon publishes the web service through Cloudflare’s edge without a public WAN IP. Check the privacy and media-streaming tradeoffs in Tailscale vs Cloudflare Tunnel before routing Jellyfin video over it.
  • Self-hosted WireGuard on a real public IP: Here Dynamic DNS shines. Pair vpn.example.com (grey-clouded, TTL 120) with UDP port 51820 on your router, add PersistentKeepalive = 25 on road-warrior peers, and you hold an encrypted path back to your rack with zero third-party relay servers in the middle.

Frequently asked questions

Does Dynamic DNS work behind CGNAT?
An updater container behind CGNAT can still publish the shared public IPv4 address an external lookup service sees, yet inbound IPv4 connections will fail anyway. RFC 6598 reserves 100.64.0.0/10 for carrier-grade NAT links where multiple subscribers share one public IPv4 address and you hold no inbound router port to forward. Behind CGNAT, use a routable IPv6 firewall pinhole, an outbound overlay VPN like Tailscale, or Cloudflare Tunnel.
What permissions does a Cloudflare DDNS API token need?
Use Cloudflare’s Edit zone DNS template rather than your Global API Key. That template grants Zone DNS Edit permission and lets you restrict Zone Resources to Include Specific zone for the single domain your homelab uses. If a container or router config ever leaks, the token can only modify DNS records inside that one zone.
Should I turn on the Cloudflare orange cloud proxy for homelab DDNS?
Keep the record DNS-only (grey cloud, proxied false) if you terminate WireGuard UDP, raw SSH, game traffic, or direct Let’s Encrypt HTTP-01/TLS-ALPN-01 challenges on your own reverse proxy. Cloudflare’s HTTP reverse proxy intercepts standard web ports rather than arbitrary UDP tunnels like WireGuard on 51820.
What TTL should I set on a Dynamic DNS record?
Set a 60-second to 300-second TTL alongside a 5-minute updater check interval. When your residential ISP rotates your lease after a modem reboot, a 300-second TTL plus a 300-second polling loop caps worst-case stale-cache downtime around ten minutes, whereas leaving a 3600-second default stretches outages up to an hour.
Is Cloudflare DDNS better than DuckDNS for a self-hosted homelab?
If you already own a domain, Cloudflare DDNS gives you clean subdomains, DNS-01 wildcard ACME certificates for internal and external services, and granular scoped API tokens. DuckDNS costs zero dollars and updates through a single HTTPS GET URL without buying a domain, making it handy for a quick WireGuard endpoint when you do not want to register a zone.

Sources and corrections

Last updated
Methodology
See our methodology for research and review standards. It draws on 8 cited sources, listed below, each checked against the original page on the date above. Address ranges, API token scopes, daemon flags, and update protocols on this page come directly from IETF RFC 6598, Cloudflare’s DNS and API token documentation, OPNsense’s os-ddclient manual, the ddclient and favonia/cloudflare-ddns repositories, and the DuckDNS HTTP specification, all verified live on 2026-11-14.
Corrections
Spotted an error? Email a correction with the affected line and what you found. The draft includes this page’s address. Verified changes are recorded here. Contact details.

About the author

Written by Lowell K. Wood IV, who builds and runs TechFuelHQ from St. Louis, Missouri.