Configuration Reference

The options in this document follow their config.toml version. The CLI or environment variable options will be noted as badges, where applicable.

`iteration_sleep`

CLI: --iteration-sleepEnv Var: DOCKNS_ITER_SLEEP

Default: 10

Possible values: 32-bit unsigned integers

Controls how long the main loop will sleep between checking for DNS record updates, in seconds.

`record_stale_after`

CLI: --record-stale-afterEnv Var: DOCKNS_RECORD_STALE_AFTER

Default: 300 (5 minutes)

Possible values: 32-bit unsigned integers

Controls how long DockNS will wait before deleting records it no longer defined by a container's labels, in seconds.

`include_stopped`

CLI: --include-stoppedEnv Var: DOCKNS_INCLUDE_STOPPED

Default: true

Possible values: true or false

Whether or not to include labels attached to containers that are stopped when looking for records.

`include_containers`

CLI: --include-containersEnv Var: DOCKNS_INCLUDE_CONTAINERS

Default: true

Possible values: true or false

Whether or not to include labels attached to containers when looking for records.

`include_swarm_services`

CLI: --include-swarm-servicesEnv Var: DOCKNS_INCLUDE_SWARM_SERVICES

Default: false

Possible values: true or false

Whether or not to include labels attached to Docker Swarm services when looking for records.

`adopt_existing_records`

CLI: --adopt-existing-recordsEnv Var: DOCKNS_ADOPT_EXISTING_RECORDS

Default: true

Possible values: true or false

Whether or not to adopt records already present on the target name server. If set to false, repeated errors or warnings may be thrown when records conflict.

`db_file`

CLI: --db-fileEnv Var: DOCKNS_DB_FILE

Default: ./record-db.json

Possible values: Valid filepath

Where to save information on records that have been created using DockNS. Both Docker and NixOS install methods set this to a sensible default for their deployment scenarios.

`dry_run`

CLI: --dry-runEnv Var: DOCKNS_DRY_RUN

Default: false

Possible values: true or false

Whether or not records are actually created on the remote name servers. Useful for testing configuration without modifying records.

`health_bind_addr`

CLI: --health-bind-addrEnv Var: DOCKNS_HEALTH_BIND_ADDR

Default: 127.0.0.1:4104

Possible values: IP address and port

IP address and port for the healthcheck server to bind to. The default behavior is to only receive health requests from the local machine, but other machines can make health requests by using 0.0.0.0:4104 instead.

`log_level`

CLI: --log-levelEnv Var: DOCKNS_LOG_LEVEL

Default: info

Possible values: error, warn, info, debug, trace

Controls the level of logging output to the console. Values are case-insensitive.

`record_defaults`

Env Var: DOCKNS_RECORD_DEFAULTS_*

`ttl`

Env Var: DOCKNS_RECORD_DEFAULTS_TTL

Possible values: 32-bit unsigned integers

How long intermediate DNS servers should cache a record, in seconds. Abbreviation for time to live.

`A`

`ip`

Env Var: DOCKNS_RECORD_DEFAULTS_A_IP

Possible values: IPv4 addresses

The default IPv4 address A records should point to. Takes priority over interface if defined together.

`interface`

Env Var: DOCKNS_RECORD_DEFAULTS_A_INTERFACE

Possible values: interface name

A network interface that an IPv4 address should be extracted from (ex. eth0 or wlan0). If ip is also for A records defined, interface is ignored.

`proxied` cloudflare

Env Var: DOCKNS_NS_<SERVER ID>_RECORD_DEFAULTS_A_PROXIED

Possible values: true or false

Whether A records should be proxied through Cloudflare by default.

`AAAA`

`ip`

Env Var: DOCKNS_RECORD_DEFAULTS_AAAA_IP

Possible values: IPv6 addresses

The default IPv6 address AAAA records should point to. Takes priority over interface if defined together.

`interface`

Env Var: DOCKNS_RECORD_DEFAULTS_AAAA_INTERFACE

Possible values: interface name

A network interface that an IPv6 address should be extracted from (ex. eth0 or wlan0). If ip is also defined for AAAA records, interface is ignored.

`proxied` cloudflare

Env Var: DOCKNS_NS_<SERVER ID>_RECORD_DEFAULTS_AAAA_PROXIED

Possible values: true or false

Whether AAAA records should be proxied through Cloudflare by default.

`CNAME`

`target_domain`

Env Var: DOCKNS_RECORD_DEFAULTS_CNAME_TARGET_DOMAIN

Possible values: fully qualified domain name

The default domain CNAME records should point to.

`proxied` cloudflare

Env Var: DOCKNS_NS_<SERVER ID>_RECORD_DEFAULTS_CNAME_PROXIED

Possible values: true or false

Whether CNAME records should be proxied through Cloudflare by default.

`SRV`

`target_domain`

Env Var: DOCKNS_RECORD_DEFAULTS_SRV_TARGET_DOMAIN

Possible values: fully qualified domain name

The default domain SRV records should point to.

`port`

Env Var: DOCKNS_RECORD_DEFAULTS_SRV_PORT

Possible values: 16-bit unsigned integers

The default port SRV records should point to.

`priority`

Env Var: DOCKNS_RECORD_DEFAULTS_SRV_PRIORITY

Possible values: 16-bit unsigned integers

Defaults SRV priority (servers pointed to by records with lower priority will receive more traffic).

`weight`

Env Var: DOCKNS_RECORD_DEFAULTS_SRV_WEIGHT

Possible values: 16-bit unsigned integers

Default SRV weight (servers pointed to by records with same priority, but higher weight will receive more traffic).

`TXT`

`value`

Env Var: DOCKNS_RECORD_DEFAULTS_TXT_VALUE

Possible values: Any string

Any arbitrary text.

`name_servers.<server id>`

Env Var: DOCKNS_NS_<SERVER ID>_*

More information: Name Server Configuration

Name servers can be configured entirely via environment variables using the DOCKNS_NS_<SERVER ID>_ prefix, where <SERVER ID> is an uppercase version of the server ID used in Docker labels. For example, a server with ID cloudflare would use the prefix DOCKNS_NS_CLOUDFLARE_.

Server ID Case Sensitivity

The <SERVER ID> in environment variables is automatically converted to lowercase to match Docker labels. DOCKNS_NS_CLOUDFLARE_SERVICE maps to server ID cloudflare, matching labels like dockns.cloudflare.record.

When an environment variable defines a field for a server that also exists in the config file, the environment variable value takes precedence. This allows you to define server structure in a config file while injecting secrets (like API keys) via environment variables at runtime.

To define a new server entirely via environment variables, the SERVICE field is required.

`service`

Env Var: DOCKNS_NS_<SERVER ID>_SERVICE

Possible values: adguard-home, cloudflare, netbird, pi-hole, porkbun, powerdns, technitium

Select the DNS service this name server connects to.

`host` adguard-home pi-hole powerdns technitium

Env Var: DOCKNS_NS_<SERVER ID>_HOST

Possible values: URL

Where to connect to the name server's API.

`api_key` cloudflare pi-hole porkbun powerdns technitium

Env Var: DOCKNS_NS_<SERVER ID>_API_KEY

Possible values: string

The name server API key.

`username` adguard-home

Env Var: DOCKNS_NS_<SERVER ID>_USERNAME

Possible values: string

The admin account username.

`password` adguard-home

Env Var: DOCKNS_NS_<SERVER ID>_PASSWORD

Possible values: string

The admin account password.

`account_id` cloudflare

Env Var: DOCKNS_NS_<SERVER ID>_ACCOUNT_ID

Possible values: string

The Cloudflare account ID.

`zone_ids` cloudflare

Env Var: DOCKNS_NS_<SERVER ID>_ZONE_IDS

Possible values: Map of zone to zone ID

Maps DNS zones to their Cloudflare IDs.

config.tomlEnvironment Variable

toml

zone_ids = { "domain.tld" = "domain.tld's zone ID" }

bash

DOCKNS_NS_CLOUDFLARE_ZONE_IDS="domain.tld=zone_id_1,domain2.tld=zone_id_2"

When using an environment variable, zone IDs are specified as comma-separated domain=zone_id pairs.

`secret_key` porkbun

Env Var: DOCKNS_NS_<SERVER ID>_SECRET_KEY

Possible values: string

Porkbun secret API key.

`record_defaults`

Env Var: DOCKNS_NS_<SERVER ID>_RECORD_DEFAULTS_*

Per-server record defaults can also be set via environment variables. The fields are the same as the global record_defaults, but prefixed with the server ID.

For example, to set the default TTL for a server called cloudflare:

bash

DOCKNS_NS_CLOUDFLARE_RECORD_DEFAULTS_TTL=3600
DOCKNS_NS_CLOUDFLARE_RECORD_DEFAULTS_A_IP=1.2.3.4

See the top-level record_defaults for the full list of available fields.

Configuration Reference ​

iteration_sleep ​

record_stale_after ​

include_stopped ​

include_containers ​

include_swarm_services ​

adopt_existing_records ​

db_file ​

dry_run ​

health_bind_addr ​

log_level ​

record_defaults ​

ttl ​

A ​

ip ​

interface ​

proxied cloudflare ​

AAAA ​

ip ​

interface ​

proxied cloudflare ​

CNAME ​

target_domain ​

proxied cloudflare ​

SRV ​

target_domain ​

port ​

priority ​

weight ​

TXT ​

value ​

name_servers.<server id> ​

service ​

host adguard-home pi-hole powerdns technitium ​

api_key cloudflare pi-hole porkbun powerdns technitium ​

username adguard-home ​

password adguard-home ​

account_id cloudflare ​

zone_ids cloudflare ​

secret_key porkbun ​

record_defaults ​

Configuration Reference

`iteration_sleep`

`record_stale_after`

`include_stopped`

`include_containers`

`include_swarm_services`

`adopt_existing_records`

`db_file`

`dry_run`

`health_bind_addr`

`log_level`

`record_defaults`

`ttl`

`A`

`ip`

`interface`

`proxied` cloudflare

`AAAA`

`ip`

`interface`

`proxied` cloudflare

`CNAME`

`target_domain`

`proxied` cloudflare

`SRV`

`target_domain`

`port`

`priority`

`weight`

`TXT`

`value`

`name_servers.<server id>`

`service`

`host` adguard-home pi-hole powerdns technitium

`api_key` cloudflare pi-hole porkbun powerdns technitium

`username` adguard-home

`password` adguard-home

`account_id` cloudflare

`zone_ids` cloudflare

`secret_key` porkbun

`record_defaults`