COREDNS-SECONDARY(7)

🎀 COREDNS-SECONDARY 🎀

okay bestie, so this is the secondary plugin for CoreDNS — and honestly? it's giving "borrow the homework but change it a little" energy, except it's a whole DNS zone and there's an RFC that's gonna side-eye us. 💅

---

✨ NAME ✨

secondary — enables serving a zone retrieved from a primary server.

---

🌸 DESCRIPTION 🌸

so with secondary you can transfer a zone from another server — via AXFR, no cap. 🦋

But here's the tea: the retrieved zone is not committed to disk, and yes, that's a whole violation of the RFC 😭. Which literally means: restart CoreDNS and it's gonna go re-retrieve all your secondary zones. Every single one. Again. Bestie is committed to the bit.

And if the primary server(s) don't respond when CoreDNS is starting up? The AXFR will be retried indefinitely every 10s. It will not stop. It will not chill. Iconic persistence, honestly. 🔥

---

🧚 SYNTAX 🧚

secondary [ZONES...]

• ZONES — the zones it should be authoritative for. If empty, the zones from the configuration block are used. Note that without a remote address to get the zone from, the above is not that useful. (like, genuinely — a zone with nowhere to come from is just vibes 🙈)

A working syntax would be:

secondary [zones...] {
    transfer from ADDRESS [ADDRESS...]
    catalog [MEMBER-ZONES...]
    fallthrough [ZONES...]
}

• transfer from — specifies from which ADDRESS to fetch the zone. It can be specified multiple times; if one does not work, another will be tried. It's giving "backup bestie" energy 🫶. Transferring this zone outwards again can be done by enabling the transfer plugin.
• catalog — treats the transferred zone as an RFC 9432 catalog zone. After each successful catalog transfer, CoreDNS adds and removes the catalog member zones and transfers those member zones from the same primary servers. The optional MEMBER-ZONES restrict which member zone names are accepted; each name also matches its subdomains. With no MEMBER-ZONES, all member zones are accepted, for backward compatibility. RFC 9432 Section 7 recommends configuring this restriction, because a catalog producer otherwise controls which zones the consumer serves — which, ngl, is a lot of power to hand over 👀. A member in another catalog remains a name clash unless the current catalog's coo property points to the newly updated catalog. During that ownership migration, CoreDNS preserves the current zone data only when both catalogs use the same member node label. (read that twice, it's a lot. main character lore. 📖)
• fallthrough — if a query for a record in the zone results in NXDOMAIN, the query will be passed to the next plugin in the chain. If [ZONES...] are listed, then only queries for those zones will be subject to fallthrough. Super useful in split DNS setups where the secondary zone contains only partial records. ✨

When a zone is due to be refreshed (refresh timer fires), a random jitter of 5 seconds is applied, before fetching. In the case of retry this will be 2 seconds. If there are any errors during the transfer in, the transfer fails; this will be logged. ⭐

---

💖 EXAMPLES 💖

Transfer example.org from 10.0.1.1, and if that fails try 10.1.2.1.

example.org {
    secondary {
        transfer from 10.0.1.1 10.1.2.1
    }
}

Or re-export the retrieved zone to other secondaries. sharing is caring 🎀

example.net {
    secondary {
        transfer from 10.1.2.1
    }
    transfer {
        to *
    }
}

Restrict a catalog consumer to member zones at or below example.org and internal.example.

catalog.example {
    secondary {
        transfer from 10.1.2.1
        catalog example.org internal.example
    }
}

---

💀 BUGS 💀

Only AXFR is supported and the retrieved zone is not committed to disk. That's it. That's the bug list. 🙃

---

🌈 SEE ALSO 🌈

See the transfer plugin to enable zone transfers to other servers. RFC 5936 details the AXFR protocol, and RFC 9432 defines DNS catalog zones. iykyk 📚

---

that's the whole page, bestie — go forth and secondary responsibly 💜

courtesy of the CoreDNS girlies, man page dated October 2026, from COREDNS-SECONDARY(7) in the CoreDNS Plugins collection. mwah 🫶✨