catz/README.md

catalog-zone-gen

Generate RFC 9432 DNS catalog zone files from a declarative input file.

Given a list of zones with their catalog assignments and optional properties, this tool produces one BIND-format zone file per catalog. Output is deterministic: re-running with unchanged input produces unchanged output (no serial bump, no file write).

Installation

go install catalog-zone-gen@latest

Or build from source:

go build -o catalog-zone-gen .

Usage

catalog-zone-gen [--config path] [--output-dir path] <input-file>

Flags:

• --config — path to YAML config file (default: catz.yaml next to the input file)
• --output-dir — directory for output zone files (default: same directory as the input file)

Configuration File

The config file (default catz.yaml) defines catalog zone names and SOA parameters.

catalogs:
  catalog1:
    zone: catalog1.example.com.
  catalog2:
    zone: catalog2.example.com.

soa:
  mname: ns1.example.com.
  rname: hostmaster.example.com.

Fields

Field	Required	Description
catalogs	yes	Map of catalog names to their zone FQDNs. Names are used as references in the input file.
catalogs.<name>.zone	yes	The FQDN of the catalog zone (trailing dot optional, will be normalized).
soa.mname	yes	Primary nameserver for the SOA record.
soa.rname	yes	Responsible person email (in DNS format: hostmaster.example.com.).

SOA timing values are hardcoded: refresh=900, retry=600, expire=2147483646, minimum=0. The NS record is hardcoded to invalid. per RFC 9432.

Input File Format

Whitespace and comma delimited. Lines starting with # are comments. Blank lines are ignored.

<zone-name>  <catalog>[, <catalog>...]  [, group=<value>]  [, coo=<fqdn>]

Fields

Position	Format	Description
First token	FQDN	Zone name (trailing dot optional, normalized internally).
Bare names	identifier	Catalog assignments — must match a key in the config catalogs map. At least one required.
group=<value>	key=value	RFC 9432 group property. Tells consumers to apply shared configuration to grouped zones.
coo=<fqdn>	key=value	RFC 9432 change-of-ownership property. Points to the old catalog zone during migration.

A zone can appear in multiple catalogs (for distributing to different server groups).

Example

# Production zones
zone.example.org    catalog1, catalog2
zone.example.com    catalog2, coo=old-catalog.example.com.
test.example.net    catalog1, group=internal
app.example.org     catalog1, group=external, coo=migrated.example.com.

Whitespace and comma placement is flexible. These are all equivalent:

zone.example.org  catalog1,catalog2
zone.example.org  catalog1 , catalog2
zone.example.org  catalog1, catalog2

Output

One BIND-format zone file per catalog, written to the output directory.

Filename: <catalog-zone-fqdn>.zone (e.g., catalog1.example.com.zone)

Example output:

catalog1.example.com.	0	IN	SOA	ns1.example.com. hostmaster.example.com. 2026030201 900 600 2147483646 0
catalog1.example.com.	0	IN	NS	invalid.
version.catalog1.example.com.	0	IN	TXT	"2"
grfen8g.zones.catalog1.example.com.	0	IN	PTR	app.example.org.
group.grfen8g.zones.catalog1.example.com.	0	IN	TXT	"external"
coo.grfen8g.zones.catalog1.example.com.	0	IN	PTR	migrated.example.com.
2qvgcfg.zones.catalog1.example.com.	0	IN	PTR	test.example.net.
group.2qvgcfg.zones.catalog1.example.com.	0	IN	TXT	"internal"
1860l9o.zones.catalog1.example.com.	0	IN	PTR	zone.example.org.

Record order

1. SOA record
2. NS record (invalid.)
3. Version TXT record ("2")
4. Member zones sorted alphabetically by zone name, each with:
   • PTR record (member zone)
   • Group TXT record (if group= set)
   • COO PTR record (if coo= set)

All records use TTL 0 and class IN. Fully-qualified owner names; no $ORIGIN or $TTL directives.

Member zone hashing

Member zone labels are generated by FNV-1a 32-bit hashing the normalized zone name, then encoding as lowercase base32hex without padding. This produces compact labels like grfen8g.

Changing tools will likely produce different hash labels, which is intentional per RFC 9432 Section 5.4 — it triggers a reconfig event on consumers.

SOA serial

Format: YYYYMMDDNN where NN is a sequence number (01-99).

• New zone files start at YYYYMMDD01.
• On subsequent runs, the tool generates output with the existing serial and compares bytes. If unchanged, no write occurs.
• If content differs, the serial is incremented (same date bumps NN; new date resets to YYYYMMDD01).
• If NN reaches 99 on the same date: the tool errors.

Validation

The tool validates input and reports errors with file location:

error: zones.txt:3: unknown catalog "bogus"
error: zones.txt:5: zone example.com. already assigned to catalog "catalog1" at line 2

Checked conditions:

• Unknown catalog name (not in config) — error
• Same zone assigned to the same catalog more than once — error
• Hash collision (two zone names produce the same hash within a catalog) — error
• Missing required config fields — error
• Unknown properties (anything other than group and coo) — error