Default Record Values

DockNS includes a powerful defaulting system which allows global defaults to be set, as well as name server specific defaults. Utilizing defaults reduces the number of labels you need to create while still allowing different name servers to point to different values.

How to Define

Defaults can be specified in the config file or via environment variables:

1. The top-level record_defaults table (or DOCKNS_RECORD_DEFAULTS_* env vars) contains the global defaults which are applied to every record.

2. The record_defaults table underneath the name server config (i.e. name_servers.<server id>.record_defaults or DOCKNS_NS_<SERVER ID>_RECORD_DEFAULTS_* env vars) contains name server specific defaults that are applied only to records that will be sent to that name server.

Inheritance

When combining the defaults, any values defined at the name server level override the value defined at the global level. If a record has a value defined in labels that conflicts with the values from the defaults, the label version takes precedence. Said another way, Docker label values take precedence over name server defaults, which take precedence over global defaults.

Within each level, environment variable values take precedence over config file values.

Valid Values

Defaults can be set for every record option, except for the record type (dockns.<server id>.record) and the record name (dockns.<server id>.name).

For a full list of available options, check out the record defaults section of the config reference.

Example

Lets say you have an application called MyApp which needs to be at the URL my.app.tld for both internal and external clients.

The configuration would be as follows:

config.toml

# Global defaults table
[record_defaults]
ttl = 3600 # Set time to live to 1 hour

[name_servers.internaldns]
service = "technitium"
# ...
# Defaults for internaldns records
record_defaults.A.ip = "192.168.1.70"

[name_servers.externaldns]
service = "cloudflare"
# ...
# Defaults for externaldns records
record_defaults.A.ip = "1.2.3.4"

Environment Variables

# Global defaults
DOCKNS_RECORD_DEFAULTS_TTL=3600

# Per-server defaults
DOCKNS_NS_INTERNALDNS_RECORD_DEFAULTS_A_IP=192.168.1.70
DOCKNS_NS_EXTERNALDNS_RECORD_DEFAULTS_A_IP=1.2.3.4

docker-compose.yaml

services:
  my_app:
    image: my_app
    # ...
    labels:
      dockns.internaldns.record: A
      dockns.internaldns.name: my.app.tld

      dockns.externaldns.record: A
      dockns.externaldns.name: my.app.tld

Server ID Case Sensitivity

The <SERVER ID> in environment variables is automatically converted to lowercase. For example, DOCKNS_NS_INTERNALDNS_RECORD_DEFAULTS_A_IP maps to server ID internaldns, matching Docker labels like dockns.internaldns.record.

Here we set a global time to live default which is shared by all records, and we set each name server with a default IP address that is specific to where we expect that servers clients to be (either in the network, or on the Internet). With this setup we only need 2 labels to define a record, the record type and the name.

A note on syntax

This example shows one way to set nested values in TOML (record_defaults.A.ip = ""), but there many other ways to achieve the same result.

If you are setting more than one value, you may prefer the multi-line table syntax:

[name_servers.internaldns]
service = "technitium"
# ...
record_defaults = {
  A.ip = "192.168.1.70"
  CNAME.target_domain = "proxy.domain.tld"
}

And if you are setting many values, you may want to separate the defaults into its own top-level table:

[name_servers.internaldns]
service = "technitium"
# ...

[name_servers.internaldns.record_defaults]
A.ip = "192.168.1.70"
CNAME.target_domain = "proxy.domain.tld"
SRV = {
  target_domain = "proxy.domain.tld"
  port = 1234
  priority = 2
  weight = 1
}
TXT.value = "My text value"