Skip to content

dyndns

A dynamic DNS service to update domain IPs

Network

A Dynamic-DNS (DDNS) service continuously keeps one or more DNS records in sync with the current public IP address of your machine.
In clan this service is backed by qdm12/ddns-updater.

Info
ddns-updater itself is heavily opinionated and version-specific. Whenever you need the exhaustive list of flags or provider-specific fields refer to its versioned documentation – not the GitHub README

1. Configuration model

Internally ddns-updater consumes a single file named config.json.
A minimal configuration for the registrar Namecheap looks like:

{
  "settings": [
    {
      "provider": "namecheap",
      "domain": "sub.example.com",
      "password": "e5322165c1d74692bfa6d807100c0310"
    }
  ]
}

Another example for Porkbun:

{
  "settings": [
    {
      "provider": "porkbun",
      "domain": "domain.com",
      "api_key": "sk1_…",
      "secret_api_key": "pk1_…",
      "ip_version": "ipv4",
      "ipv6_suffix": ""
    }
  ]
}

When you write a clan.nix the common fields (provider, domain, period, …) are already exposed as typed Nix options.
Registrar-specific or very new keys can be passed through an open attribute set called extraSettings.

2. Full Porkbun example

Manage three records – @, home and test – of the domain jon.blog and refresh them every 15 minutes:

clan.nix
inventory.instances = {
  dyndns = {
    roles.default.machines."jon" = { };
    roles.default.settings = {
      period   = 15;                # minutes
      settings = {
        "all-jon-blog" = {
          provider         = "porkbun";
          domain           = "jon.blog";

          # (1) tell the secret-manager which key we are going to store
          secret_field_name = "secret_api_key";

          # everything below is copied verbatim into config.json
          extraSettings = {
            host         = "@,home,test";   # (2) comma-separated list of sub-domains
            ip_version   = "ipv4";
            ipv6_suffix  = "";
            api_key      = "pk1_4bb2b231275a02fdc23b7e6f3552s01S213S"; # (3) public – safe to commit
          };
        };
      };
    };
  };
};
  1. secret_field_name tells the vars-generator to store the entered secret under the specified JSON field name in the configuration.
  2. ddns-updater allows multiple hosts by separating them with a comma.
  3. The api_key above is public; the corresponding private key is retrieved through secret_field_name.

Roles

The dyndns module has the following roles:

  • default

Options for the default role

period

Domain update period in minutes

Type: signed integer

Default:

5

Declared in: clanServices/dyndns/default.nix

server.acmeEmail

Email address for account creation and correspondence from the CA. It is recommended to use the same email for all certs to avoid account creation limits.

Type: string

Declared in: clanServices/dyndns/default.nix

server.domain

Domain to serve the webservice on

Type: string

Declared in: clanServices/dyndns/default.nix

server.enable

Whether to enable dyndns webserver.

Type: boolean

Default:

false
Example 
true

Declared in: clanServices/dyndns/default.nix

server.port

Port to listen on

Type: signed integer

Default:

54805

Declared in: clanServices/dyndns/default.nix

settings

Configuration for which domains to update

Type: attribute set of (submodule)

Default:

{ }

Declared in: clanServices/dyndns/default.nix

settings.<name>.domain

The top level domain to update.

Type: string

Example 
"example.com"

Declared in: clanServices/dyndns/default.nix

settings.<name>.extraSettings

Extra settings for the provider. Provider specific settings: https://github.com/qdm12/ddns-updater#configuration

Type: attribute set of string

Default:

{ }

Declared in: clanServices/dyndns/default.nix

settings.<name>.provider

The dyndns provider to use

Type: string

Example 
"namecheap"

Declared in: clanServices/dyndns/default.nix

settings.<name>.secret_field_name

The field name for the secret

Type: one of "password", "token", "api_key", "secret_api_key"

Default:

"password"
Example 
"api_key"

Declared in: clanServices/dyndns/default.nix