Quick Start

Get BoronDNS running in under 5 minutes using the prebuilt installer, or follow the full build path from source.

Option A — Installer archive (recommended)

Download the static installer archive for your platform from the releases page, then:

tar -xf borondns-0.2.0-x86_64-unknown-linux-musl.tar.xz
cd borondns-0.2.0-x86_64-unknown-linux-musl/
sudo ./install.sh

For unattended setup with a single zone:

sudo BORONDNS_ZONE=example.com. \
  BORONDNS_PRIMARY=10.0.0.10:53 \
  BORONDNS_NOTIFY_SOURCE=10.0.0.10 \
  ./install.sh --yes

The installer places the binary at /usr/local/bin/borondns, installs a systemd service unit, and writes a starting config to /etc/borondns-secondary/config.toml.

Option B — Build from source

Prerequisites

Rust stable toolchain — rustup.rs
An existing primary nameserver that supports AXFR/IXFR
A TSIG key shared with the primary (optional but strongly recommended)

Install Rust tools:

rustup toolchain install stable
rustup component add rustfmt clippy

Clone and build

git clone https://github.com/Integrity-Ltd/borondns.git
cd borondns
cargo build --locked --release -p borondns-cli
sudo install -m 0755 target/release/borondns /usr/local/bin/borondns

Confirm the build:

./target/release/borondns --version

Create a config

Start from the built-in example config:

sudo install -d -m 0755 /etc/borondns-secondary
borondns --example-config | sudo tee /etc/borondns-secondary/config.toml
$EDITOR /etc/borondns-secondary/config.toml

A minimal working config requires a [[zones]] block with a zone name and primary address:

[interfaces.dns]
# Address to serve authoritative DNS (UDP and TCP)
bind_address = "0.0.0.0"
port = 53

[[zones]]
name     = "example.com."
primaries = [{ address = "10.0.0.1", port = 53 }]
notify_sources = ["10.0.0.1"]
tsig_name = "my-primary-key"

[tsig."my-primary-key"]
algorithm = "hmac-sha256"
secret_file = "/etc/borondns-secondary/keys/my-primary-key.key"

Validate and start

# Validate config without starting the server
borondns --validate-config /etc/borondns-secondary/config.toml

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

# Start the server
borondns serve --config /etc/borondns-secondary/config.toml

Verify

In another shell, check liveness and zone status:

curl -fsS http://127.0.0.1:8080/livez
curl -fsS http://127.0.0.1:8080/readyz

When zones are loaded and active, /readyz returns HTTP 200.

Next: Installation — packaging, Docker, and systemd service setup.

Installation