Dynflare - minimal self-service Cloudflare dynamic DNS

how to point a domain name to a dynamic IP address

Posted on 2019-06-23 in Posts

Dynflare (get it on GitHub) is a minimalistic, self-service alternative to full-fledged (and often bloated) dynamic DNS providers, leveraging Cloudflare’s great DNS API and various free IP detection services.

IPv4 address exhaustion and faster/cheaper Internet offers

Being 32 bytes long, an IPv4 address’ maximum value is 2^32, for 4.294.967.296 (less than 4.3 billion) unique addresses. This of course poses a problem for ISPs (as there are many more connected devices than that), and thus various solutions were born:

  • Dynamic IP addresses: instead of permanently reserving a fixed network address to each and every device in the network, they are rotated depending on usage - often when you reboot your router; note that the address is fixed during the whole duration of the connection
  • NAT (or IP masquerading): <src-ip>:<src-port> and <dst-ip>:<dst-port> are mapped together, so that an entire address space is hidden behind a single IP address; NAT-ed connections are common in mobile data offerings (your phone’s Internet)

…and various combinations of the above.

Most of the time, when trying out small home clusters (be it with Kubernetes or not) or setting up self-hosted services (SMTP/POP3/IMAP, HTTP(S), SSH…), the logical next step is exposing them to the Internet for external access – but the vast majority of people only have a dynamic or NAT-ed IP address, which makes setting up a domain’s DNS records almost pointless without a way to update them automatically.

A good-enough solution

While for ISP-level NAT-ed connections you would need a tunnel to some external server with a static (or predictable) IP allocated, if you have a dynamic IP at home not all hope is lost.

The most common solution, as offered by services like NoIP or Oracle’s Dyn, is locally running a third-party agent, with a “flow” similar to the below:

  1. the agent on your machine connects to the Dynamic DNS provider’s servers
  2. the Dynamic DNS provider detects your external IP
  3. their DNS server (or whatever DNS provider they have integrated) updates their DNS record’s value to your latest IP address

This is sufficiently simple (also considering the very simple setup/deployment) for most users to rely on.

However, it’s too basic and opaque if:

  1. you don’t want to disclose your IP address to anyone except you and your DNS provider
  2. you want to implement custom logic around IP detection and/or DNS updates
  3. you want to update multiple DNS records, maybe of types different than A, on different DNS providers and/or domains
  4. you need to mitigate hijacking of external IP detection (in case of bad or misbehaving IP detection providers)
  5. you don’t want to run untrusted, closed-source agent software on your infrastructure
  6. you don’t want any new accounts or platforms to manage

A couple possible solutions

DNS providers’ API availability is a big factor when choosing one for this kind of tasks. I personally tend to favor Cloudflare for the easy to use API, free CDN and low latency (I primarily use it for tinkering with side projects), but as long as yours has an API you should be fine.

Dynflare was born out of pure laziness and unwillingness to manage yet another external platform (or possible point of failure), as a dead-simple, deploy in 1 minute solution.

The above use cases are addressed more or less the following ways:

  1. you are in control of IP detection mechanisms and DNS record updating is done directly through the provider’s API
  2. it’s open source, MIT licensed and really, really simple, so you can fork it and add whatever features you might like (or open a pull request! contributions are always welcome)
  3. you can configure (through environment variables and/or command line flags) API credentials for any and multiple of the supported DNS providers, and specify multiple records to update using the <provider>:<zone>:<type>:<name> syntax
  4. support for self-tunneling-based IP detection (for example forwarding through ngrok) or custom servers (if you prefer having a VPS or very small server to query for IP detection, you can), as well as “consensus” between IP detection results (it’s really just picking the most-seen IP at the moment), which mitigates hijacking up to 49% of results (as in: if we always pick the most-seen address, we’re safe as long as 51% of IP detection results are good)
  5. as Dynflare is open source and MIT licensed, you can review it, fork, integrate…
  6. DNS record updates are directly applied to the DNS provider, and you can run Dynflare on your infrastructure using cron, Docker, Kubernetes…

Some example usage

Let’s imagine a simple scenario:

  • you want to have an A record called example-subdomain on Cloudflare always updated to your dynamic IP address, for your example.com domain
  • you want to mitigate hijacking with as less effort as possible
  • you want to run with cron

Using Dynflare, you would add this to your crontab:

0 * * * * CLOUDFLARE_API_KEY="your CF API key" CLOUDFLARE_API_SECRET="your CF API secret" /usr/bin/dynflare -r cloudflare:example.com:A:example-subdomain

What this does is:

  • configuring cron to run the above command every minute
  • setting your Cloudflare credentials as environment variables (note that this is a very simple example, you shouldn’t save your credentials in a crontab!)
  • running IP detection using all implemented providers and selecting the most-seen IP address
  • updating the example-subdomain A record in the example.com zone of your Cloudflare account


Take this post with a grain of salt. Some things are over-simplified to make for a shorter explanation, such as the dynamic IP allocation mechanisms or security in the above example.