All documentation pages ↓

How LiteBlox works

LiteBlox runs your BIND servers for you. Give it a few Debian machines with a sudo account and it takes over their BIND configuration: zones, server options, ACLs and keys are all edited in the browser. One server is the primary for every zone and the others are its secondaries, so a change is made in one place and the rest copy it within seconds. On the same machines it can also run Kea for DHCP and chrony for time, and it keeps an address list (IPAM) of every network.

Each of these is a module you can switch off. LiteBlox can run DHCP only (registering clients at a DNS server you already have), or be just an address list, with no BIND anywhere.

The pieces

browser ──▶ LiteBlox container ──(mutual TLS, port 8530)──▶ agent on ns1 ─▶ BIND (primary)   ─▶ Kea (DHCP)
                │                                        └▶ agent on ns2 ─▶ BIND (secondary) ─▶ Kea (DHCP)
                ├─ zone history (git)
                └─ backups of each node        BIND: ns1 ──NOTIFY, IXFR──▶ ns2
                                               Kea:  ns1 ◀──failover (TLS, 8001)──▶ ns2
                                                     each Kea's D2 ──DNS updates──▶ the DNS primary

Kea is optional: a node runs only BIND until you set DHCP up on it.

IPAM lives in LiteBlox itself: it reads the zones, the leases and what the nodes see on the network, and adds names of its own (IPAM).

LiteBlox owns the whole BIND config

After setup, a node's /etc/bind/named.conf only includes files LiteBlox writes:

The package's own root hints stay included as they were, and rndc.key stays the node's own. The node's original files are kept in /etc/bind/pre-liteblox/. A server that already has a configuration of its own can be taken over too: LiteBlox imports it and proves its version is equivalent before switching.

Every configuration change works the same way: LiteBlox backs the node up, sends the new files, and the agent checks each file against a strict allow-list, runs named-checkconf on the whole set and switches over with rndc reconfig. Changes to more than one node go one node at a time, and LiteBlox checks after each that its zones still answer. If one stops answering, every node the change touched is rolled back.

If someone edits these files by hand, LiteBlox notices within a minute (config drift) and lets you overwrite the edit or keep it. See Primary, failover and drift.

One primary, the rest secondaries

Make ns1 the primary (on the Nodes page) gives ns1 the zone files and makes every other node its secondary. LiteBlox publishes to the primary only. The primary tells its secondaries (NOTIFY) and they fetch just the changes (IXFR), signed with a key LiteBlox creates for itself. If the primary fails, Promote a secondary; the old primary is demoted automatically when it comes back.

Kinds of zones

A forward or reverse zone is either:

• static (the default): you edit a draft, review it and publish it. LiteBlox writes the zone file.
• dynamic: DHCP servers, ACME clients and other programs with a key may change it with DNS updates (RFC 2136). Grid edits apply at once. See Dynamic zones and TSIG keys.

Changing a static zone

1. Edit: changes go into a draft, never straight to the servers. Changing an A/AAAA record can also change the matching PTR in a reverse zone; the two drafts are then linked.
2. Review: what changed, named-checkzone's verdict, the file diff, and the state of every node.
3. Publish: LiteBlox:
   • checks the primary still has the file LiteBlox last wrote (if someone edited it by hand, that's drift, and you choose what to do)
   • bumps the serial above anything a node serves
   • stages the new file on the primary, which checks it with its own named-checkzone, then switches over (atomic file swap + rndc reload)
   • asks the primary, then each secondary, over DNS which serial it now serves

Every publish is a commit in the zone's History, with an optional message. Any two versions can be compared, and any version can be restored into a draft. See Editing and publishing.

DHCP

On a node with Kea, LiteBlox writes Kea's configuration the way it writes BIND's: the interfaces it answers on, the subnets with their pools, options and reservations, and DNS registration. Every change is previewed as a diff, checked on the node by kea-dhcp4 -t, applied one node at a time, and rolled back if Kea stops answering. Two nodes can share the work as a hot-standby failover pair, and clients' names can be registered in a dynamic zone, or at another DNS server (DNS registration). Leases live in Kea; LiteBlox reads them live. See DHCP (Kea).

Safety nets

• Drafts and review: nothing reaches a server without passing review.
• Checked config changes: every node is backed up first, the agent checks each file against its allow-list and named-checkconf, and a node that stops answering afterwards rolls everything back.
• Drift detection: hand edits to zone files and to the generated configuration are noticed, never silently overwritten.
• History: every published version of every zone, with who and when; dynamic zones get a version after each LiteBlox edit and a daily snapshot.
• Backups: each node's BIND configuration and zones (and Kea's configuration and leases), daily and before every configuration change. They restore with a plain tar zxf … -C /.
• Re-adopt: if LiteBlox's own data is lost, a new LiteBlox rebuilds it from the nodes (Disaster recovery).
• Failover reports: when a demoted primary held records the new one doesn't, LiteBlox keeps them for you to put back.

Accounts

LiteBlox has its own accounts, separate from the servers' logins:

• admin: everything, including managing accounts on the Users page
• readonly: sees zones, nodes, settings, history, reviews and backup lists; can't change anything, download backups or view their contents

Roles apply to all of LiteBlox, not per zone. Every change, login and failed login is recorded in the audit log (Users → Audit log; sign-ins are hidden unless you ask for them). See the Security model.