From 6cc823613a3095cd4f0a92c6eb344fa760fcf66a Mon Sep 17 00:00:00 2001
From: CroneKorkN <i@ckn.li>
Date: Sun, 10 May 2026 20:46:00 +0200
Subject: [PATCH] bind/README: applying changes needs both master and slave
 nodes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The slave's bw-managed zone files are rendered from the master's
metadata at slave-apply time. Changing a record on the master only
publishes once both bw apply runs are done. The left4me-integration
session burned ~20 minutes assuming bw apply on htz.mails would
propagate to ovh.secondary via bind's own AXFR; it doesn't, because
bw verify measures the on-disk file, not the running zone.

Frame as the workflow rule rather than the absolute "not AXFR"
claim — the bundle does set type slave; in named.conf.local, but
that's orthogonal to the practical apply-both rule.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 bundles/bind/README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 bundles/bind/README.md

diff --git a/bundles/bind/README.md b/bundles/bind/README.md
new file mode 100644
index 0000000..d837587
--- /dev/null
+++ b/bundles/bind/README.md
@@ -0,0 +1,30 @@
+# bind
+
+Authoritative DNS — primary plus optional `bind/master_node` slaves.
+
+## Applying changes needs both nodes
+
+The slave's bw-managed zone files are rendered from the master's
+metadata at slave-apply time (see `bundles/bind/items.py:100`). When
+you change a record on the master (adding a `letsencrypt/domains`
+entry, a new vhost, etc.), the change is only published once you
+apply BOTH:
+
+```sh
+bw apply htz.mails        # primary (where the source records live)
+bw apply ovh.secondary    # secondary (renders its own zone files)
+```
+
+Until both have been applied, `bw verify ovh.secondary` will show
+stale zones and consumers that hit the secondary (Let's Encrypt's
+secondary-region validators in particular) will see NXDOMAIN. Even
+though the slave's named.conf.local declares `type slave;`, don't
+rely on bind's own AXFR catching up — the bw-rendered file on disk
+is what `bw verify` measures.
+
+## See also
+
+- `bundles/bind-acme/` — the in-house ACME-update receiver.
+- `bundles/letsencrypt/README.md` — DNS-01 prerequisites and the
+  negative-cache penalty (the most common operational consequence
+  of forgetting to apply the secondary).