ddclient: a Perl dynamic DNS updater for Cloudflare, Porkbun and 60+ providers

The problem ddclient solves, and who actually needs it

A residential or small-office connection usually gets an IP address that changes. Anything you host behind it, a VPN endpoint, a mail server, a home lab box, becomes unreachable the moment the address rotates unless something rewrites the DNS record. ddclient is that something. It is a Perl client that updates dynamic DNS entries for accounts on a wide range of dynamic DNS services, using curl for internet access.

The intended user is someone with a Unix-ish host and an account at a provider that offers a dynamic DNS API. The README lists the requirements plainly: an account from a supported dynamic DNS service provider, Perl v5.10.1 or later, the JSON::PP library for JSON support, and Linux, macOS or any other Unix-ish system. That last line is the boundary. This is not a Windows-first tool, and the repository's sample files confirm the assumption: sample-etc_systemd.service, sample-etc_cron.d_ddclient, sample-etc_dhclient-exit-hooks and sample-etc_ppp_ip-up.local are all Unix integration points.

The provider list is the real draw. It spans CloudFlare, Porkbun, Namecheap, Duck DNS, Dynu, deSEC, Gandi, GoDaddy, Hetzner, Hurricane Electric, INWX, IONOS, Njalla, Noip, OVH, PowerDNS and many more, plus RFC 2136 nsupdate against BIND, Knot DNS and Technitium. If your registrar or DNS host is on that list, you probably do not need to write anything yourself.

How ddclient decides your address and pushes the update

The core loop is small. ddclient determines the current IP address, compares it against the address it last recorded, and only then talks to your provider. That comparison is what keeps the tool quiet: on a stable connection it does nothing but check.

Address discovery has two paths. The first is asking an external service over HTTP, which is what the use=web style configuration does; the README notes that ddclient supports finding your IP address from many cable and DSL broadband routers as well, so a router on the LAN can be the source instead of a public checkip endpoint. The second path is the RFC 2136 route, where ddclient sends DNS UPDATE messages directly to an authoritative server using protocol=nsupdate. The README lists DynV6, ISC BIND, Knot DNS, PowerDNS and Technitium DNS Server as reachable that way.

Provider-specific behaviour is expressed through the protocol setting. Most commercial providers speak dyndns2; PowerDNS can be driven through PowerDNS-Admin with protocol=dyndns2 or through RFC 2136 with protocol=nsupdate. This is a config-file-driven design, not a plugin API. Adding a provider means adding a Perl code path, which is why the supported list is a curated one rather than something you extend locally without patching.

One historical interaction is worth knowing because it still shapes configuration advice. The README's known issues section records that between v3.9.1 and v3.11.2 the ssl parameter forced all connections to use HTTPS, which broke HTTP-only IP querying sites such as http://checkip.dyndns.org. The README says the behaviour changed starting with v4.0.0. If you are copying an old configuration, that is the kind of setting to re-read rather than transplant.

Installing ddclient and getting a first update through

The README's recommended route is your operating system's package. It points readers at a packaging status badge that lists distributions shipping a ddclient package, and calls that the easiest way to install. Use that first; the manual build is for people who need a version their distro has not packaged.

Manual installation starts by extracting the release tarball and entering the directory. If you are working from a clone of the Git repository rather than a release tarball, the README says to run ./autogen before continuing.

tar xvfa ddclient-3.XX.X.tar.gz
cd ddclient-3.XX.X

Then configure, build, test and install. The README gives these exact arguments, including the check target, which is worth running because it exercises the build before it touches your system.

./configure \
    --prefix=/usr \
    --sysconfdir=/etc \
    --localstatedir=/var
make
make VERBOSE=1 check
sudo make install

After install, edit /etc/ddclient/ddclient.conf. That path is the 4.x default and it is the single most common source of confusion when people upgrade, so it is covered in its own section below.

For systemd hosts, the repository ships a unit file. Copy it into place, then enable and start it.

cp sample-etc_systemd.service /etc/systemd/system/ddclient.service
systemctl enable ddclient.service
systemctl start ddclient.service

If the service starts but appears to do nothing, the README names the diagnostic directly: run ddclient --verbose --debug and check that the === config ==== section is not empty. An empty config section means the config file is not being found. That single check resolves most first-run failures better than reading logs.

The 4.x config path change that breaks upgrades

Version 4.x moved the default config file location from ${sysconfdir}/ddclient.conf, typically /etc/ddclient.conf, to ${sysconfdir}/ddclient/ddclient.conf, typically /etc/ddclient/ddclient.conf. If you compiled 3.x from source and then upgrade, your existing config is in the old place and the new binary will not read it.

The README gives the migration commands, including the permission change, which matters because the file holds provider credentials.

sudo mkdir -p /etc/ddclient
sudo mv /etc/ddclient.conf /etc/ddclient/ddclient.conf
sudo chmod 600 /etc/ddclient/ddclient.conf

If you would rather not move the file, configure accepts an override that keeps the old location. The README shows --with-confdir='${sysconfdir}' added to the same three arguments used above.

This is the clearest example of ddclient's upgrade cost. The tool is a Perl script plus a config file, so the code upgrade is trivial. The config migration is the part that fails silently, because a missing config does not produce an error, it produces a process that sleeps. The README anticipates exactly that symptom and tells you to look for an empty === config ==== section. Treat any post-upgrade silence as a config-path problem before you treat it as a provider problem.

Where ddclient is the wrong tool

The provider list is long but it is closed. If your DNS host is not in the README's list, ddclient will not talk to it, and there is no documented plugin interface for adding one yourself. The project's own answer to that situation is to file an issue, which is a request to upstream rather than a workaround you can deploy today. Anyone whose registrar is absent from that list should stop reading here and look at the alternatives the README names.

Windows is the second gap. The requirements say Linux, macOS or any other Unix-ish system. The repository does contain a sample-etc_dhcpc_dhcpcd-eth0.exe file, but the README documents no Windows installation path, no Windows service, and no Windows packaging. People searching for ddclient on Windows will not find an answer in this repository.

The third limitation is the dependency on curl for internet access. That is stated in the opening line of the README, and it means the runtime environment needs curl present and able to reach both the IP-check endpoint and the provider API. On a locked-down host where only a specific proxy is allowed, that is a constraint to check before installing rather than after.

Finally, consider what ddclient is not. It is not a DNS server, not a certificate manager, and not a monitoring system. It updates one kind of record in response to address changes. If your address is static, or your provider offers its own first-party updater that you already trust, ddclient adds a dependency without adding capability.

Alternatives the README itself points at

The README does not pretend to be the only option. It names two alternatives, inadyn and dnsupdate, with the caveat that you should consider them if they support your dynamic DNS provider.

The difference is in the implementation approach rather than the feature list. ddclient is a Perl program that shells out to curl for network access and expresses provider behaviour through a config file with protocol settings. inadyn is a C daemon, which changes the deployment footprint: a compiled binary with no Perl runtime and no JSON::PP dependency, but a different provider list and a different configuration format. dnsupdate takes a narrower approach still, aimed at the RFC 2136 DNS UPDATE path rather than the long tail of provider-specific HTTP APIs.

That distinction should drive the choice. If your provider is a commercial registrar with an HTTP API, ddclient's breadth is the reason to pick it. If you run your own authoritative DNS and only need authenticated DNS UPDATE messages, a tool focused on nsupdate semantics may be a smaller thing to operate. Note that ddclient also covers that case through protocol=nsupdate, so the overlap is real and the decision comes down to which runtime you prefer on the host.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-06-22. The most recent release listed is v4.0.1-rc.1 from 2026-05-17, with v4.0.0 released on 2025-01-19. So the 4.x line is the current one, and the newest published artefact is a release candidate rather than a final release. If you need a stable tag, v4.0.0 is the one to pin; if you take the release candidate, you are accepting pre-release code.

Operationally, the upgrade surface is small. There is no database, no state directory beyond what the localstatedir holds, and no service mesh. The recurring cost is the config file: every provider credential lives in /etc/ddclient/ddclient.conf, and the README's own migration instructions set that file to mode 600. Any upgrade that changes the default path requires a deliberate move, and the README documents that the breaking changes between 3.x and 4.x are collected in ChangeLog.md. Read that file before a major-version jump rather than after.

On licensing, ddclient is GPL-2.0. If you are deploying it internally on your own hosts, that is unremarkable. If you intend to redistribute it, embed it in a product, or ship a modified build, the GPL-2.0 obligations around source availability and derivative works apply, and those are questions for your own counsel. The repository carries COPYING and COPYRIGHT files at the top level, which is where the operative text lives.

Editorial conclusion

Adopt ddclient if you run a Unix-ish host, already have an account with one of the providers it lists, and want a single Perl client to keep that record current. Skip it if you need a Windows service, if your provider is not on the supported list, or if you want a daemon that ships with its own installer and updater. Before deploying, verify three things: that your distro package or source build landed the config at /etc/ddclient/ddclient.conf, that ddclient --verbose --debug shows a non-empty === config ==== section, and that your provider's entry in the README matches the protocol you configured.

Frequently asked questions

Official sources

1. ddclient/ddclient on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases