half broken

deploy/k8s/10-deployment.yaml

@@ -150,8 +150,9 @@ spec:
         - name: config
           configMap:
             name: fancy-dns-config
-        # Local zones are ordinary master files; ship them in a ConfigMap or
-        # manage them through the admin API (`/api/zones`), which writes into
+    # Local zones are ordinary master files; ship them in a ConfigMap or
+    # edit them in the mounted volume. There is no zone API — the admin API
+    # drives blocklists, the cache and the query log, not the zone files.
         # the data volume. Optional because the glob in the config matches
         # nothing cleanly.
         - name: zones

deploy/local.example.zone

@@ -1,24 +1,33 @@
 ; Local authoritative data. fancy-dns answers for these names itself, which
 ; removes the need for a second nameserver for a handful of records.
+;
+; Every name here is fully qualified on purpose. A master file is loaded with
+; an origin, and for a file under `blocklist.local_zones` that origin is the
+; file's base name (zonefile.OriginFromPath): `local.example.zone` gives the
+; origin "local.". A relative name would be qualified with THAT, so "ns1"
+; here would become ns1.local. and not ns1.lan. — a zone that looks right in
+; the editor and answers nothing. Absolute names are the same in every file,
+; whatever it is called.
 $TTL 300
-@ SOA ns1.lan. hostmaster.lan. 2024010101 3600 600 604800 300
-@ NS  ns1.lan.
-@ NS  ns2.lan.
+lan.        SOA     ns1.lan. hostmaster.lan. 2024010101 3600 600 604800 300
+lan.        NS      ns1.lan.
+lan.        NS      ns2.lan.
 
-ns1     A     192.168.1.2
-ns2     A     192.168.1.3
+ns1.lan.        A     192.168.1.2
+ns2.lan.        A     192.168.1.3
 
-router      A     192.168.1.1
-nas         A     192.168.1.10
-nas         AAAA  fd00::10
+router.lan.     A     192.168.1.1
+nas.lan.        A     192.168.1.10
+nas.lan.        AAAA  fd00::10
 
 ; A wildcard covers one label: printer.lan., host.lan., ...
-*.lan  A     192.168.1.50
+*.lan.          A     192.168.1.50
 
 ; A wildcard deeper down.
-*.internal.lan  A    10.0.0.50
+*.internal.lan. A     10.0.0.50
 
-; Services.
+; Services. These were already absolute; keeping every record absolute means
+; the file reads the same as it behaves.
 _ntp._udp.lan.        SRV 0 0 123 ns1.lan.
 _ldap._tcp.lan.       SRV 10 0 389 nas.lan.
 _dmarc._domain.lan.   TXT "v=DMARC1; p=reject; rua=mailto:dmarc.lan"

deploy/zones/local.rpz.zone.example

@@ -1,23 +1,31 @@
 ; Example RPZ-style policy zone.
 ;
 ; Drop everything from these services, for this host and its subdomains.
+;
+; As in local.example.zone, every owner name is fully qualified. A policy zone
+; is read with the origin taken from the file name (internal/blocklist prepends
+; `$ORIGIN` per file), so a relative `*.doubleclick.net` in a file called
+; local.rpz.zone.example becomes *.doubleclick.net.local. — a rule that blocks
+; nothing you care about. Absolute owner names are the only spelling that is
+; independent of what the file is called; TestExampleRPZZoneBlocksWhatItSays
+; in internal/blocklist pins that the example blocks what its comments claim.
 $TTL 60
-@ SOA localhost. hostmaster.localhost. 1 3600 600 604800 60
-@ NS  localhost.
+localhost.        SOA     localhost. hostmaster.localhost. 1 3600 600 604800 60
+localhost.        NS      localhost.
 
 ; *.doubleclick.net CNAME .   -> NXDOMAIN
-*.doubleclick.net       CNAME .
-*.ads.example.com       CNAME .
-*.tracker.example.net   CNAME .
-analytics.example.org   CNAME .
+*.doubleclick.net.        CNAME .
+*.ads.example.com.        CNAME .
+*.tracker.example.net.    CNAME .
+analytics.example.org.    CNAME .
 
 ; CNAME rpz-drop. -> answer with silence
-*.noisy-cdn.example     CNAME rpz-drop.
+*.noisy-cdn.example.      CNAME rpz-drop.
 
 ; CNAME rpz-passthru. -> ignore blocklists for this name
-metrics.internal.       CNAME rpz-passthru.
+metrics.internal.         CNAME rpz-passthru.
 
 ; A/AAAA records in a policy zone are returned verbatim, which is the cleanest
 ; way to point a blocked name at a local landing page.
-blocked.example         A     192.0.2.10
-                       AAAA  2001:db8::10
+blocked.example.          A     192.0.2.10
+                          AAAA  2001:db8::10