Some configurations to enable dynamic DNS updates (DynDNSv2) for CoreDNS.
Go to file
Maximilian Kratz 056076e0c0
Merge pull request #6 from maxkratz/hotfix/update-webhook-version
Updates webhook image to latest version since the issue was resolved
2023-06-24 17:57:44 +02:00
config Bugfix for the IP parameter (DynDNSv2) 2022-08-03 21:21:15 +02:00
scripts Cleanup 2022-08-07 17:30:27 +02:00
.gitattributes Updated documentation 2021-04-13 17:14:18 +02:00
.gitignore Added dynamic zonefile to gitignore 2021-04-13 17:24:47 +02:00
LICENSE Edited 2021-04-10 10:59:48 +02:00 Bugfix for the IP parameter (DynDNSv2) 2022-08-03 21:21:15 +02:00
docker-compose.yml Updates webhook image to latest version since the issue was resolved 2023-06-24 17:57:07 +02:00


This repository holds some basic configurations to enable dynamic DNS updates in an authorative DNS-Server running CoreDNS without implementing a custom plugin. Therefore, this repsoitory "simulates" a DynDNSv2 endpoint.
Keep in mind that this is kind of a blueprint and not necessary production-ready.

How does it work?

CoreDNS is able to reread configuration and zone files on changes. This project provides a quite simple way to update such a zone file via a webhook. Most decent routers allow to specify a custom URL with basic auth to send IP updates to. The webhook provides such a URL and triggers a sh script that updates the dynamic zone file and boom - your dynamic IP updates are done.

In short (step-by-step):

  1. The client receives a new dynamic IP address.
  2. The client sends a cURL query to the webhook container containing the new IP address.
  3. The webhook container triggers the sh script.
  4. The sh script updates the CoreDNS zone file --> Includes the new IP address and updates serial.
  5. CoreDNS automatically reloads the zone file and serves the new IP address.

Please notice:
The sh script checks if the provided parameter is a valid IPv4 address using a regex. Currently, the updating of IPv6 addresses is not supported.


A Docker-Compose stack is used for the example configuration. Feel free to adapt the needed steps to, e.g., a native installation (with binaries) (although Docker-Compose is running just fine for my personal setup).

  • Adapt htpasswd to your needs. You need at least one valid entry with a username:password combination. The file is prefilled with the credential example:0123456789 - Do not forget to change/remove that!
    • This file will be used by an nginx container to provide basic authentification.
  • Adapt to match your root domain zone. In most cases, you already have such a file and can change the needed parameters in that. The needed parameters are already prefilled in the example file:
    • Three nameserver records for the root zone --> These values will not change at all.
    • Three nameserver records for the dynamic zone --> This is the zone that will be updated by web hooks. The records deligate all queries from DNS clients to the CoreDNS server specified for this zone. (It then will handle all DNS queries for the dynamic zone.)
      • In this example, the root zone will also be served by your CoreDNS server. Keep in mind that this is absolutely not neccessary! You just have to deligate the dynamic zone.
  • Copy to (This ensures that git does not track your dynamic updates.)
  • Use to create the dynamic zone. This file will get updated via the sh script.
  • Please notice: At least, you have to change all occurences of to your own domain in all config/zone files!

After you've adapted the configuration files to your needs, start the Docker-Compose stack: $ docker-compose up -d

Hint: Mostly, you want to use the stack behind a reverse proxy such as nginx secured with a SSL/TLS certificate. For an easy to use reverse proxy for Docker containers, check out nginx-proxy with its config examples.

OPNsense client example

This example can easily be used to update a dynamic zone with your OPNsense router.

In your OPNsense box go to Services --> Dynamic DNS and click on (+) Add.
Configure the following settings:

Field Value Explanation
Enable Checked Enables this update client
Service type Custom -
Protocol DynDns2 Sets URL to smth. like https://host/nic/update?
Username example Your username for basic auth from htpasswd
Password 0123456789 Your password for basic auth from htpasswd
Wildcard Unchecked -
Hostname(s) Your dynamic zone to update
Check ip method Interface You can also use some of the other provided methods
Force SSL Checked Uses HTTPS instead of HTTP
Interface to monitor E.g., WAN Interface on which the dynamic IP occurs
Description -