Skip to content

Some configurations to enable dynamic DNS updates (DynDNSv2) as well as the Let's Encrypt TXT challenge for CoreDNS.

License

Notifications You must be signed in to change notification settings

maxkratz/coredns-dyndns

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CoreDNS-DynDNS

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. Available functions:

Keep in mind that this is kind of a blueprint and not necessary production-ready.

DynDNS A record update

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 an 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.

Configuration

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 db.example.com 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 example.com --> These values will not change at all.
    • Three nameserver records for the dynamic zone dyn.example.com --> 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 db.example.com.dyn.template to db.example.com.dyn. (This ensures that git does not track your dynamic updates.)
  • Use db.example.com.dyn 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 example.com 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?hostname=dyn.example.com&myip=192.0.2.1
Username example Your username for basic auth from htpasswd
Password 0123456789 Your password for basic auth from htpasswd
Wildcard Unchecked -
Hostname(s) dyn.example.com 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 -

Let's Encrypt DNS challenge

Additionally to the previous mentioned updating of A records, this stack also provides a function to update a TXT record for a Let's Encrypt DNS challenge. This means you can use it to include a TXT record that Certbot needs to update a Let's Encrypt certificate on a server that may not have a publicly available web server on port 80 + 443.

How does it work?

The core information is explained in the section of updating A records above. Let's Encrypt steps:

  1. Certbot requests a new certificate. The Let's Encrypt servers request to update the TXT record with value "ABC".
  2. Certbot triggers the le.sh script with value "ABC".
  3. The script sends a webhook with parameter "ABC" to http://$nameserver/nic/le
  4. The script cng.sh updates the dynamic zone file (including "ABC" as TXT record), updates the serial, and saves it to disk.
  5. CoreDNS automatically reloads the zone file and serves the new IP address.
  6. le.sh waits 60s to ensure the updated zone is available.
  7. The Let's Encrypt servers can now validate the TXT record and give the new certificate to Certbot.

Relevant files:

File Purpose
le.sh Certbot script that can provide the necessary call to this stack.
cng.sh Script that updates the TXT record within the dynamic zone file (analogously to the A record script explained above).
htpasswd_le Contains the authentification user/pw combination for the cng.sh script.
db.example.com.dyn.template Contains the necessary A record as well as the TXT record to update.
default.conf nginx configuration to pass calls to respective webhooks.
webhook.json Contains the webhook configuration.