bindantic: describe BIND9 config as Pydantic models

Daniil Gruzdev — Sun, 02 Aug 2026 07:54:12 +0000

If you've ever administered BIND9, you know the feeling: you open named.conf, add a zone, forget the trailing dot on a domain name or a semicolon after a block - and named-checkconf (if you remembered to run it at all) quietly makes you read three different flavors of "syntax error" at once.

Maybe you've already moved on to Route53/Cloudflare/PowerDNS and similar managed setups? Fair enough - but BIND9 hasn't gone anywhere: self-hosted DNS, private zones, legacy infrastructure, requirements to keep everything on-prem - there's no shortage of reasons to still be running it.

named.conf is, well, configuration without a schema. No typing, no validation while you write it - just hoping you remember the exact syntax for allow-transfer { key tsig-key; }; by heart.

That's how I ended up building bindantic (bind + pydantic, you get it) - a library that describes BIND9 configuration as Pydantic models and generates correct named.conf/zone-file syntax from them. Just shipped 1.0.0, so here's what it does, why, and what broke along the way.

Never published anything like this before, but figured it's worth a shot - curious to see the reaction.

What it looks like

from bindantic import (
    ARecord, NamedConfig, NSRecord, OptionsBlock,
    SOARecord, ZoneBlock, ZoneTypeEnum,
)

config = NamedConfig(
    options_block=OptionsBlock(
        directory="/etc/bind",
        recursion=True,
        allow_recursion=["localhost", "localnets"],
        listen_on=["any"],
        listen_on_v6=["any"],
    ),
    zone_blocks=[
        ZoneBlock(
            name="example.com",
            zone_type=ZoneTypeEnum.PRIMARY,
            file="zones/example.com.zone",
            resource_records=[
                SOARecord(
                    mname="ns1.example.com", rname="admin.example.com",
                    serial=2026010101, refresh=10800, retry=3600,
                    expire=604800, minimum=3600,
                ),
                NSRecord(nsdname="ns1.example.com"),
                ARecord(name="@", address="192.168.1.1"),
            ],
        )
    ],
)

config.model_bind_syntax()

That prints a valid named.conf. Typo an IP, miss a required SOA field, or set an option that's incompatible with the zone type, and Pydantic tells you immediately when you build the model - not when BIND refuses to reload in production.

Out of the box: every named.conf block (acl, options, zone, view, dnssec-policy, tls, key, logging, remote-servers, ...) and every common resource record type - A, AAAA, MX, NS, SOA, TXT, CAA, DNSKEY, RRSIG, TLSA, SSHFP, and a dozen more. config.write_files() lays out named.conf, zone files, keys, and DNSSEC policies into the right directories for you.

How it's different from what's already out there

bind9_parser exists in the Python ecosystem, but it solves the reverse problem: it parses an existing named.conf. bindantic goes the other direction - you write the config in Python from scratch, with validation and IDE autocomplete, instead of writing text that gets parsed afterward.

Worth being upfront about where bindantic does not fit, too. If a zone is dynamic - nsupdate is allowed, a secondary is pulling updates via IXFR, dnssec-policy/inline-signing is on - BIND maintains its own .jnl journal and periodically flushes changes back into the zone file, rewriting it completely (often in raw format), with no regard for whatever formatting or comments were there before. So bindantic is a good fit for generating the "day zero" state at bootstrap, or for fully regenerating the config from scratch on every deploy (the IaC way - the zone is a build artifact, not a place for manual edits on top), but not for round-tripping with a zone BIND itself is actively mutating. If you need to read the current live state before regenerating, that's exactly the niche the bind9_parser mentioned above fills - the two tools probably complement each other more than compete.

How it's built

Out of the box: 96%+ test coverage, static typing (py.typed), a CI matrix across Python 3.10-3.13, and an auto-generated API reference for every model. No dependencies beyond Pydantic.

But string-based tests only verify what you thought to check - they don't guarantee BIND will actually accept the resulting config. So CI has a dedicated job that runs the generated named.conf through named-checkconf against a real BIND 9.20 install. That's exactly what caught the bugs below - literally right before the 1.0 release.

The fun part: bugs found while prepping for 1.0

Three genuinely nasty bugs surfaced:

View order was silently getting scrambled. For BIND, view order isn't cosmetic - the server applies the first matching view and stops. But model_bind_syntax() sorted view_blocks before rendering, since for most blocks (acl, key, zone) output order doesn't matter and sorting gives stable diffs. Turns out it does matter for views: ViewBlock never overrode comparison_attr, so the comparison always returned True, and sorted() effectively reversed the list. A split-horizon config with an internal view before external could come out in the opposite order - inverting who sees what.

key in an ACL rendered with bogus quotes. allow-transfer { key tsig-key; } is completely standard for TSIG-secured zone transfers. The generator wrapped it in quotes instead: "key tsig-key"; - invalid syntax that named-checkconf rejected outright. The shared formatter saw a space inside the string and decided to quote it, unaware that key is a special two-token grammar element, not a string literal.

Record owner names got force-qualified with a trailing dot. This one was the nastiest. The name field on a resource record shared a validator with fields that reference other domains (nsdname, mname, exchange) - those are supposed to always be fully-qualified, so the validator appends a dot. Correct for those. Wrong for the record's own owner name: a relative label like ns1 became ns1. - an absolute, root-level name instead of ns1.example.com. BIND flagged it as "out-of-zone data" and refused to load the zone. It broke essentially any record except @.

All three lived quietly in the code until I sat down to write realistic examples (split-horizon, TSIG transfers, DNSSEC) and ran them through a real named-checkconf instead of trusting string-based unit tests.

Try it

pip install bindantic

GitHub: github.com/DVSAWR/bindantic
Docs: dvsawr.github.io/bindantic
PyPI: pypi.org/project/bindantic

Feedback, issues, and PRs are genuinely welcome, criticism included. If you've got automation around BIND9 - provisioning scripts, an internal Ansible module, IaC for your DNS infrastructure - bindantic might slot in as the config-generation layer instead of Jinja2 templating or hand-rolled string concatenation. Curious how well it'd actually fit into an existing pipeline.