push zone to the nameservers

This block is part of the dns group and was last modified in core v15.0.0.

push zone to the nameservers v15.0.0

Replace the live zone file and reload, per nameserver. Only reachable once the check passed on every node.

In pins 6 + flow
  • flow
    flow
  • Zone required
    value

    The zone name, for example deverence.nl.

  • Zone file required
    value

    The rendered zone file. Must be byte-identical to what was checked.

  • Nameservers required
    array

    Each {name, host, port, user, key_path, known_hosts_path}. Paths only : never key material.

  • Check results required
    array

    The results pin from dnszone_check. Every node must appear here with ok true and a matching checksum.

  • Complete
    condition

    The render's complete pin. False refuses the push: a zone with an unanswered per-apex slot is unfinished.

    Default true

  • Allow removals
    condition

    Off by default. The push reads each nameserver's live zone and refuses if any record being served would disappear : named-checkzone cannot see that, because a zone missing every record still parses. Set this only when the deletions are the point, and read the removed pin afterwards.

    Default false

Out pins 8 + flow
  • flow
    flow
  • Success
    condition

    True only when every node applied the file.

  • Zone
    value

    The zone that was pushed.

  • Results
    array

    Per node: name, host, ok, output, exit_code.

  • Applied count
    number

    How many nodes replaced their live file.

  • Node count
    number

    How many nodes were pushed to.

  • Checksum
    value

    sha256 of the bytes that were sent.

  • Removed
    array

    Records that disappeared from a live zone, as {node, record}. Empty unless allow_removals was set : without it a push that removes anything is refused.

  • Error
    value

    Why the push was refused, or which nodes did not apply it.

Writes the rendered zone file to every nameserver and reloads it, reporting per node. IT WILL NOT RUN UNGATED. It requires the results from dnszone_check on the checks pin and refuses unless EVERY node in its own list has a passing check for this zone whose checksum matches a fresh sha256 of the bytes about to be sent. So a parse failure anywhere leaves every node's live file untouched : including the nodes that would have accepted it : and a flow cannot check one file and push another. It also refuses when complete is false (a per-apex slot nobody answered for renders a zone that parses perfectly and is missing a record, which named-checkzone cannot see) and when the file still carries the @SERIAL@ placeholder. Past that gate it is deliberately NOT atomic across nodes: the three servers are independent primaries serving identical files, each validates and swaps on its own, and a node that rejects the file keeps serving what it had. BEFORE WRITING ANYTHING it reads each nameserver's live zone with `dns-push get` and compares record sets: if any record currently being served would disappear, the push is REFUSED and named. named-checkzone cannot catch this : a zone stripped to its SOA and NS parses perfectly and is a total outage : and the store cannot be trusted to say what is live, because a record PATCH that deletes the record and an import that reports success before it lands both produced exactly that. allow_removals lifts the refusal for deliberate deletions and reports them on removed; nothing lifts the refusal on a zone rendered down to SOA+NS. If the live zone cannot be read the push refuses rather than proceeding blind. success is true only when every node applied; otherwise results names which refused and the error says how many of how many landed. Follow with dnszone_verify : agreement between the nodes is the only failure that matters and it is invisible from the store's own copy. Each node is {name, host, port, user, key_path, known_hosts_path}: paths only, never key material.

deploy zone
publish zone
rndc reload

A typical wiring for push zone to the nameservers: a function trigger starts the flow; value feeds the zone pin; value feeds the zone_file pin; with values feeds the nodes pin; with values feeds the checks pin; the flow out pin feeds debug.

Studio canvas example for the push zone to the nameservers block: typical wiring for push zone to the nameservers.

Used in these guides

These documentation pages use or explain this block:

Version history

Introduced in v15.0.0.


Back to dns Return to the main group to view all sub-groups Back to DNS zones Return to the group to view all blocks within this group