dns-keeper/README.md

DNS Keeper

A small but robust program to keep DNS records updated with your public (external) IPv4 address.

Mostly like DDNS but using API driven updates.
Currently only gandi's liveDNS API is supported.

How it works

Every POLL_INTERVAL seconds, DNS Keeper will check if the IPv4 in the domain(s) is still
valid by seeing if DNS_KEEPER_RECORD.DNS_KEEPER_DOMAIN still points to itself.

Note

On startup DNS Keeper starts a detached thread with a UDP socket on which it answers with a random set of challenge bytes.
DNS Keeper will send an empty data-frame to its own socket using the DNS resolved IPv4 address to see if it gets a response with the correct challenge bytes.
The challenge bytes are changed before every self-check.

If DNS Keeper fails to get a response from itself for 3 times it will check it's cached IP against the response of multiple external services that return your public IPv4.

If the returned public IP is the same as the cached one, DNS Keepr will see that as drift.
If this happens too much it will revalidate its own cache against the self-record.

If the returned public IP is different from the cached one, DNS Keeper will check the new IP using its own socket again, this time without DNS.
If it proves to be correct it will update all A record of the specified DOMAINS who's value match the old IP to the new IP.
The chached IP is only updated after the self-record is updated correctly.

Note

DNS Keeper enforces a strict majority amongst the services.
If a strict majority cannot be reached or not enough services were able to respond, it will take no action and reset the failed counter.
This is to prevent any issues should external services be compromised and to avoid spamming these services in case something else is wrong.

Environment Variables

Field	Descript	Default
GANDI_API_TOKEN	Gandi API Token with permission to "See and renew domain names".
DOMAINS	The domains (eg. "example.noreal,demo.notreal") to keep the A records up to date of.
DNS_KEEPER_PORT	The port on which DNS Keepr runs its self-check UDP Socket.	65535
DNS_KEEPER_DOMAIN	The domain on which the record pointing to dns-keeper lives. (eg. example.notreal).
DNS_KEEPER_RECORD	DNS record that points to your public IP/DNS-Keeper (eg. _dnsk).
POLL_INTERVAL	The interval (in seconds) at which DNS Keeper should check if it can still reach itself.	5

Setup

You can the binary using the dynamically linked or static using make.

# Dynamically linked
make

# Static:
make STATIC=1

The dynamically linked binary is smaller but requires dependencies: libcurl, libcjson and pthread to be on the target machine.

The static binary is slightly bigger but is fully self contained.

Docker Image

The Dockerfile in this repo builds a minimal image with just the static binary and CA certificates.

docker build -t dns-keeper .

Tip

Because the image is just the c binary with ca certs, there is no shell to exec into.
docker exec will not work for debugging.