CLI Reference

BoronDNS is a single binary. The primary command is serve. Config inspection commands run without binding sockets or starting the server.

Top-level flags

borondns [flags] <command>

Flags:
  --config PATH         Path to the TOML config file.
                        Default: /etc/borondns-secondary/config.toml
                        Also: BORONDNS_CONFIG env var

  --validate-config     Parse and validate the config file, print any errors,
                        and exit without starting the server.

  --dump-config         Print the effective configuration after validation.
                        Inline TSIG secrets are redacted; file path references
                        (XoT trust anchors, client certificates, key paths) are
                        preserved for operator audit.

  --example-config      Print the built-in example configuration (valid TOML)
                        and exit. Suitable for piping to a file:
                        borondns --example-config > /etc/borondns-secondary/config.toml

  --version             Print the binary version and exit.

  --help, -h            Show help.

Commands

serve

Start the authoritative DNS server:

borondns serve
borondns serve --config /etc/borondns-secondary/config.toml

On startup, BoronDNS:

1. Validates the configuration.
2. Binds the DNS listener sockets (UDP and TCP on the configured address/port).
3. Drops privileges to the configured user (if run_as_user is set).
4. Starts zone transfer sessions for all configured zones.
5. Begins serving authoritative queries as zones become ACTIVE.

The server is ready when /readyz returns HTTP 200.

check-config (alias: validate-config)

Validate the configuration without starting the server or binding sockets:

borondns check-config
borondns check-config --config /path/to/config.toml
# or:
borondns --validate-config

Exit code 0 on success, non-zero on validation error.

dump-config

Print the effective configuration after validation, with secrets redacted:

borondns dump-config
borondns --dump-config

Use this to audit configuration wiring: listener addresses, zone primaries, TSIG key names, and XoT paths are all shown. Inline secret = "..." values are replaced with [REDACTED].

example-config

Print the built-in annotated example config:

borondns --example-config
borondns --example-config | sudo tee /etc/borondns-secondary/config.toml
borondns --validate-config  # validate the newly placed file

Environment variables

A subset of scalar process settings can be overridden via environment variables using the pattern ODS_<SECTION>_<KEY>. Environment overrides take precedence over the config file and are visible in --dump-config output. For example:

ODS_LOG_LEVEL=debug borondns serve

The most useful env overrides are:

Signals

Health checks

Check server liveness and readiness directly without borondnsctl:

# Is the process alive?
curl -fsS http://127.0.0.1:8080/livez

# Are zones active and ready to serve?
curl -fsS http://127.0.0.1:8080/readyz

# Prometheus metrics
curl -s http://127.0.0.1:8080/metrics | grep '^borondns_'

Build and validate a config from scratch

# 1. Print the example config to a file
borondns --example-config | sudo tee /etc/borondns-secondary/config.toml

# 2. Edit to match your environment
$EDITOR /etc/borondns-secondary/config.toml

# 3. Validate
borondns --validate-config /etc/borondns-secondary/config.toml

# 4. Inspect effective config (secrets redacted)
borondns --dump-config /etc/borondns-secondary/config.toml

# 5. Start
borondns serve --config /etc/borondns-secondary/config.toml

Exit codes