TSIG to BIND

Lattice updates BIND (or any RFC 2136 server that accepts TSIG) after DHCP. The worker does this from the outbox. dhcpd never talks to BIND on the Ack path.

Adapter: bind_tsig. HMAC-SHA256 via miekg/dns. Community includes this adapter.

Hub: integrations. AD (Kerberos, not a shared secret): ad-ddns. Hidden-primary from Lattice to BIND secondaries is a different mode (embedded + AXFR) — dns.

Vendor documentation (algorithm names, named.conf syntax, and nsupdate flags change with BIND 9 releases):

ISC recommends authenticating updates with TSIG keys, not source IP addresses. Our walkthrough is the Lattice-specific path (secret ref, worker host).

Just show me the steps — commands at the bottom, without the education.

1. What problem this solves

You already have BIND as the authoritative server for office.example.com. Laptops already use it (or Unbound that forwards to it) via DHCP option 6. After Lattice Acks a lease, someone must write:

printer-01.office.example.com.  300  IN  A    10.20.20.10
10.20.20.10.in-addr.arpa.       300  IN  PTR  printer-01.office.example.com.

ISC dhcpd did that with nsupdate and a key in dhcpd.conf. Lattice does it in the worker so Ack cannot stall on DNS.

TSIG vs GSS-TSIG vs “allow-update any”

Lattice bind_tsig is the first row. Do not point it at a DC.

2. Why a key (and how BIND checks it)

A TSIG key is a name plus a secret plus an algorithm. The update packet carries an HMAC over the request. BIND looks up key "lattice.";, computes the same HMAC, and applies allow-update { key lattice.; }; on that zone.

The key name is not a hostname. Convention: lattice. (the trailing dot is a DNS name convention and matches BIND key "lattice."). Lattice’s TSIG name field must match exactly, including the dot if BIND has it.

The secret is random bytes, usually base64 from tsig-keygen. Treat it like a password. Lattice stores a ref (env:LATTICE_TSIG_SECRET or file:/etc/lattice/tsig.secret), not the secret, in Postgres.

TSIG has a time fudge (minutes). NTP on Lattice and BIND still matters, just less brutally than Kerberos.

3. Mint the key on BIND

On the BIND host:

tsig-keygen -a hmac-sha256 lattice.

Example output (generate your own secret; do not reuse this placeholder):

key "lattice." {
    algorithm hmac-sha256;
    secret "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
};

Put the key { ... }; block in a file only named can read (include it from named.conf). Put only the secret string on the Lattice worker. From Windows, copy a one-line file with WinSCP to /tmp, then SSH:

# /etc/lattice/tsig.secret  (0600, lattice user) — the base64 only, one line
sudo mv /tmp/tsig.secret /etc/lattice/tsig.secret
sudo chown lattice:lattice /etc/lattice/tsig.secret
sudo chmod 600 /etc/lattice/tsig.secret

chmod 600 = only that account can read it. windows-admin §7. Or set LATTICE_TSIG_SECRET in the worker environment (0600 env file).

Zone statements

Forward and reverse zones Lattice will update:

zone "office.example.com" {
    type primary;   /* or master on older BIND */
    file "/var/lib/bind/db.office";
    allow-update { key lattice.; };
};

zone "20.20.10.in-addr.arpa" {
    type primary;
    file "/var/lib/bind/db.rev";
    allow-update { key lattice.; };
};

Create the reverse zone before you enable DDNS on 10.20.20.0/24. Lattice will not create BIND zones.

Do not allow-update { any; };. Restrict allow-query as you already do; TSIG is about writes, not reads.

Reload: rndc reload (or your distro’s unit).

4. Firewall and topology

Only lattice-worker needs 53/tcp (and UDP if you use it) to BIND. dhcpd does not. In HA, every worker host needs that path.

BIND does not need to reach Lattice. Updates are outbound from the worker.

5. Point Lattice at BIND

Console More → DDNS adapters:

{
  "adapter": "bind_tsig",
  "name": "bind-office",
  "host": "bind.office.example.com",
  "port": 53,
  "tsig_name": "lattice.",
  "tsig_secret_ref": "file:/etc/lattice/tsig.secret"
}

Subnet: DDNS on, adapter name bind-office, ddns_forward_zone=office.example.com, ddns_reverse_zone=20.20.10.in-addr.arpa. Pool addresses must reverse into that zone.

Option 6 stays whatever clients already use (often this BIND, or Unbound in front of it). Enabling DDNS does not change option 6.

6. Rotation

1. tsig-keygen a new key (new name, e.g. lattice-2026.), or replace the secret in place (brief dual-fail window).
2. Add the new key to BIND; allow-update both keys if you overlap.
3. Update the Lattice ref / file; workers pick it up on the next outbox claim (restart workers if the env changed).
4. Remove the old key from BIND.

In-flight outbox rows retry.

7. Troubleshooting

nsupdate -k lattice.key (BIND key file format) against the same server is a good outside-Lattice probe.

Just the steps

Replace zone names and the BIND host. Confirm tsig-keygen against the BIND ARM.

On BIND:

tsig-keygen -a hmac-sha256 lattice.

Put the key { … }; block where named can read it. On forward and reverse zones Lattice will update:

allow-update { key lattice.; };

Then rndc reload. Put only the secret string (one line) on each Lattice worker:

sudo mv /tmp/tsig.secret /etc/lattice/tsig.secret
sudo chown lattice:lattice /etc/lattice/tsig.secret
sudo chmod 600 /etc/lattice/tsig.secret

Console More → DDNS adapters: bind_tsig, host = BIND, port 53, TSIG name lattice. (match the key name including the dot), secret ref file:/etc/lattice/tsig.secret. Subnet: DDNS on, that adapter, forward + reverse zone names. Option 6 unchanged. Worker → BIND :53; dhcpd does not need it.