/custom-ddns

Dynamic DNS using an intermediate function

Primary LanguageTypeScriptGNU Affero General Public License v3.0AGPL-3.0

License: AGPL-3.0-or-later

Custom DDNS

Keep your A (IPv4) and AAAA (IPv6) records in sync with the public IP of your router. Useful in the following cases:

  • Your router has DDNS functionality but does not support your DNS provider.
  • You do not want your router to have unlimited write access to your DNS records. I.e. you only need DDNS for certain subdomains, and you would be negatively impacted if any other records were created or modified.
  • Your router supports DDNS and you want to update multiple DNS records across different domains and DNS providers.
  • Your router does not have DDNS support, but you can implement a simple version yourself and want to do the heavier lifting on another system.

Implementation

The following flow occurs on every IP update:
router -(notifies)> executor -(updates)> DNS provider

The router, e.g. Unifi Dream Machine, must be configured to send a request to the Executor with the new IP.

The executor processes the new IP and updates the DNS records.

The DNS provider, e.g. Cloudflare, provides an API that allows for updating the DNS records.

The reason behind this setup is to:

  • Not store any API token on the router, this prevents the router from creating arbitrary DNS records (security consideration)
  • Be able to support any DNS provider with an API using a single configuration file

Routers

In theory, any router that supports a DDNS client can work. Some clients are explicitly tested and supported.

Follow these links to read how to configure the routers:

Executors

Executors implement a public web server that takes requests from the routers. An executor is small and language/platform specific. Examples of platforms are Docker and Cloudflare Workers. The executor performs authentication and updates the DNS records using the configured providers.

Currently supported (platform/language):

Providers

Providers are executed by the Executors and contain the DNS provider specific code for updating the DNS records.

Currently supported (DNS provider/language):

Configuration and usage

Follow these steps:

  1. Based on your DNS provider, read the provider specific documentation.
  2. Copy the config.example.yaml to config.yaml and change it to meet your needs.
    Visualize config.yaml spec or view the JSON schema.
  3. Verify your config by running yarn run validate-config
  4. Choose an executor and follow the deployment instructions.
  5. Configure your router to send the update request to the executor.

Configuration spec

The source of truth for the config.yaml schema is the TypeScript Config interface. From this interface, the JSON schema config.schema.json is generated using yarn run update-config-schema.

Visualize the schema of the config file on json-schema.org.