validns(1)

📦
version 0.11.0 · 5 versions
, in ubuntu stonking

💖 NAME 💖

validns — the DNS and DSNSEC zone file validator, your new bestie for making sure your zone isn't a whole mess 🎀

Okay so real talk, bestie, this page describes validns version 0.11.0. Slay.

✨ SYNOPSIS ✨

validns -h validns [options] zone-file

And listen, if you wanna validate stuff coming in on stdin? Just drop a "-" where zone-file would go. Iconic behaviour honestly. 🫶

🌸 DESCRIPTION 🌸

So validns reads a DNS zone in the master file format of RFC 1035 section 5.1 and checks whether it's actually correct. It parses every single record and every directive, and when it can't parse something it tells you the exact reason why — no vague "something went wrong" energy here, we don't do that. Then it runs a whole stack of structural, consistency, and (for signed zones) DNSSEC checks over everything it parsed. 💅

For a DNSSEC-signed zone, validns:

  • verifies each RRSIG against the corresponding DNSKEY
  • checks that signatures are within their validity period
  • walks the NSEC or NSEC3 authenticated-denial chain to confirm it's complete and consistent with the records actually present in the zone

The basic checks and the DNSSEC checks are always performed. The extra operator policy checks? Those are opt-in, one at a time, with -p (peep POLICY CHECKS below, bestie).

The intended use is validating a zone before you publish it — like as a step in a zone-signing or provisioning pipeline. Main character energy: catch the problem at home, not in production. 🙈

By default validns processes the whole zone and reports every problem it finds. -f makes it stop at the first error instead. And it exits with a non-zero status if any errors were reported, and zero otherwise. So you can trust the exit code, fr fr.

🦋 ZONE FILE FORMAT 🦋

Format of zone files follows that of RFC 1035 section 5.1, with one exception: "\.", aka dots in labels, are not supported, due to how domain names are stored internally. Not us being lazy, just how the internals vibe. 😭

Additionally:

  • $TTL is supported as described in RFC 2308
  • $GENERATE is partly supported

🎀 OPTIONS 🎀

  • -h — Produce usage text and quit. Little help me out moment. 🥺
  • -f — Quit on first validation error. Normally, validns continues working on a zone after encountering a parsing or validation error, but with this it's one strike and we're out.
  • -p name — Activate policy check name. By default only basic checks and DNSSEC checks are performed. You can specify this option multiple times (stack 'em, bestie). See POLICY CHECKS below for the deets.
  • -n N — Use N worker threads for parallelizable operations. The default is 0, meaning no parallelization. Currently only signature verification is parallelizable. More threads, more speed, iykyk. 🔥
  • -q — quiet — do not produce any output.
  • -s — Print validation summary/stats. If specified twice, also print record counts by type. Double it and it gives you more. ✨
  • -v — be extra verbose. Tell me everything, king. 👑
  • -L — List all record types validns can render, one per line, and exit.
  • -M — use SOA MINTTL as the default TTL when no TTL specified.
  • -I path — use this path for $INCLUDE files.
  • -z origin — use this origin as initial $ORIGIN.
  • -t epoch-time — Use specified time instead of the current time when verifying validity of the signatures. This option may be specified multiple times, in which case every signature is checked against all specified times. Time travel but make it validational. ⭐
  • -V — Print version and exit.

💜 BASIC CHECKS 💜

Every record and every supported directive should be parsable — that's the most basic check of all. And the validns program will report the exact reason why it cannot parse a record or a directive. No cryptic nonsense. 💅

Other basic checks include:

  • there could only be one SOA in a zone;
  • the first record in the zone must be an SOA record;
  • a record outside the apex;
  • TTL values differ within an RR set (excepting RRSIG);

🔥 DNSSEC CHECKS 🔥

  • type exists, but NSEC does not mention it for name;
  • NSEC mentions type, but no such record found for name;
  • NSEC says x is the last name, but z exists;
  • NSEC says z comes after x, but nothing does;
  • NSEC says z comes after x, but y does;
  • signature is too new;
  • signature is too old;
  • RRSIG exists for non-existing type type;
  • RRSIG's original TTL differs from corresponding record's;
  • RRSIG(type): cannot find a signer key;
  • RRSIG(type): cannot verify the signature;
  • RRSIG(type): cannot find the right signer key;
  • NSEC3 record name is not valid;
  • multiple NSEC3 with the same record name;
  • no corresponding NSEC3 found for name;
  • type exists, but NSEC3 does not mention it for name;
  • NSEC3 mentions type, but no such record found for name;
  • there are more record types than NSEC3 mentions for name;
  • broken NSEC3 chain, expected name, but nothing found;
  • broken NSEC3 chain, expected name1, but found name2;
  • NSEC3 without a corresponding record (or empty non-terminal);
  • name type: no covering RRSIG in a signed zone;
  • algorithm signatures cannot be validated: digest is disabled by system crypto policy.
On systems where cryptographic algorithms are restricted by policy (e.g., RHEL 9/CentOS 9 with SHA-1 disabled), validns detects this and reports which algorithms cannot be validated. Affected signatures are skipped rather than producing cryptic errors. We're being nice about it 🫶

🌈 POLICY CHECKS 🌈

The following policy checks are understood:

  • single-ns — Checks that there are at least two NS records per name (or zero).
  • cname-other-data — Checks for CNAME and other data condition (excluding possible and NSEC).
  • dname — DNAME checks: no multiple DNAMEs, no descendants of a node with a DNAME. Please note that DNAME/CNAME clash is handled by CNAME and other data check already.
  • dnskey — DNSKEY checks: public key too short, leading zero octets in public key exponent or modulus.
  • nsec3param-not-apex — NSEC3PARAM, if present, should only be at the zone apex.
  • mx-alias — MX exchange should not be an alias.
  • ns-alias — NS nsdname should not be an alias.
  • rp-txt-exists — TXT domain name mentioned in RP record must have a corresponding TXT record if it is within the zone.
  • tlsa-host — Domain name of a TLSA record must be a proper prefixed DNS name.
  • ksk-exists — A KSK key must exist in a signed zone.
  • smimea-host — Domain name must have the form which is proper for an SMIMEA record.
  • all-algorithms-signed — In a signed zone, every RR set that must be signed must have covering RRSIG records for every algorithm present in the apex DNSKEY RR set (RFC 4035, section 2.2).
  • occluded-records — Records hidden below a zone cut (occluded by a delegation) are reported. Address records serving as glue are exempt: those referenced from the NS RR set of the delegation above them, or from the apex NS RR set. Glue referenced only by some other delegation ("sibling glue") is still reported; combine with no-strict-glue to permit it.
  • missing-glue — Every delegation whose name server names fall at or below the delegation point must have A or AAAA glue records for them.
  • all — Activates all of the above policy checks (but not the ones described below).
  • permit-starting-hyphen — Starting hyphen (normally disallowed) is permitted in names.
  • no-strict-glue — Modifies occluded-records to also accept glue referenced by any NS record in the zone, not just the delegation the glue sits under or the apex NS RR set.

💀 BUGS 💀

  • textual segments in TXT and HINFO must be enclosed in double quotes;

If at least one NSEC3 record uses opt-out flag, validns assumes it is used as much as possible, that is, every unsigned delegation does not have a corresponding NSEC3 record. This is done for reasons of efficiency, to avoid calculating cryptographic hashes of every unsigned delegation. If this assumption is wrong for a zone, validns will produce spurious validation errors. 🙈

Not gonna lie, that last one is important — if that assumption doesn't hold for your zone, you'll get errors that aren't really errors, and you'll be sitting there like 😭

🧚 ACKNOWLEDGEMENTS 🧚

Thanks go to Andy Holdaway, Daniel Stirnimann, Dennis Kjaer Jensen, Goran Bengtson, Hirohisa Yamaguchi, Hugo Salgado, Jake Zack, Jakob Schlyter, Koh-ichi Ito, Mathieu Arnold, Miek Gieben, Patrik Wallstrom, Paul Wouters, Ryan Eby, Tony Finch, Willem Toorop, and YAMAGUCHI Takanori for bug reports, testing, discussions, and occasional patches. Absolute legends, every one of them. 🫶✨

Special thanks to Stephane Bortzmeyer and Phil Regnauld.

Thanks for AFNIC which funded major portion of the development. Thanks for SWITCH for additional funding. 💖

And that's the whole vibe, bestie — this was validns 0.11.0, documented as a General Commands Manual, printed under validns(1). Now go validate that zone before you publish it. Periodt. 💅🌸

📦 where this page comes from