Skip to content

Secondary DNS Servers ​

Secondary DNS Servers lets this server feed your own secondary nameservers, so the zones it serves are also answered by nameservers you run elsewhere. It works on a standalone server, without a hub. Available since panel 1.9.0.

Overview ​

URL: /admin/settings/dns-secondary-servers

Open it from Settings > DNS > Secondary DNS Servers. On a server running as a hub, the same page sits under Cluster > DNS Cluster instead, at /admin/cluster/dns/secondary-servers (see DNS Cluster).

The page follows hub mode. When you turn Enable hub mode on in Hub Settings, it moves from Settings to DNS Cluster, and when you turn it off, it moves back. Since panel 1.9.3 the move takes effect at once: every Settings page keeps opening right after the change, and a link or bookmark to the other place leads to the page where it is now. The earlier address /admin/dns-cluster/dns-secondary-servers also leads straight to the current place.

AdminBolt nodes under a hub are connected automatically by their Secondary DNS role. This page is for any other nameserver, such as PowerDNS or BIND.

The list shows each secondary's Name, IP Address, Transfer auth (the TSIG key name, or IP only), Source (Cluster node for a hub node with the Secondary DNS role, Manual for one added here), whether it is Active, and when it was Added. Since panel 1.9.3 it also shows Zones served and Last check, described under Checking what a secondary serves. A Cluster node row is managed from the node and cannot be edited or deleted here.

How a secondary gets its zones ​

Every active secondary may transfer each zone this server is primary for, and receives NOTIFY when a zone is created or changes.

Since panel 1.9.3 this server also sends NOTIFY for every zone it is primary for when a secondary joins: when you add it, change its IP Address, or make it Active again. The secondary then creates the zones it is missing and transfers them on its own. Before 1.9.3 the panel did not send them, so a secondary added later could stay without the zones that already existed.

Send zones on a secondary's row sends NOTIFY for every zone to that secondary again, after you confirm. Use it when the secondary is missing zones.

This server also publishes a catalog zone that lists every zone it is primary for. A secondary set up with the instructions in the form follows the catalog, so new domains reach it and deleted ones leave it on their own. A secondary configured without the catalog needs each zone added by hand. A cPanel DNSOnly server cannot follow the catalog; see A cPanel DNSOnly server as a secondary.

Adding a secondary ​

The form for adding a secondary DNS server, with the optional TSIG key section

The Setting up the secondary section of the form, with the PowerDNS, BIND, and cPanel DNSOnly instructions

  1. Configure the secondary first, using the instructions under Setting up the secondary in the form. They are filled in with this server's real address, its nameservers, the catalog zone name, and the key, for:
  2. Click the button to add a secondary and fill in:
    • Name (required) - a label for the secondary.
    • IP Address (required) - the secondary's address. NOTIFY messages are sent to it, and zone transfers are allowed from it.
    • Active - whether the secondary is in service.
    • Notes - free text.
  3. Optionally fill in the TSIG key section. With a key, the secondary proves who it is by signing its zone transfers, rather than by its address alone. Use one for a public nameserver that serves other zones too.
    • Key name - for example bolt-secondary.
    • Algorithm - the signing algorithm.
    • Secret - Base64. Generate creates one. Enter the same name, algorithm, and secret on the secondary.
    • Since panel 1.9.3 key names starting with bolt-fleet- are reserved for the keys a hub gives its nodes, so the form refuses them: "Key names starting with bolt-fleet- are reserved for cluster node keys. Choose another name."
  4. Save. The secondary's address may transfer zones and receives NOTIFY as soon as you save, and the TSIG key, when set, is put in place on this server at the same time.

Without a TSIG key, skip the key lines in the setup instructions.

A cPanel DNSOnly server as a secondary ​

Since panel 1.9.6, Setting up the secondary has its own block for a cPanel DNSOnly server, cPanel DNSOnly secondary (PowerDNS, its default nameserver), separate from the BIND secondary block. Use that block on a DNSOnly server, and do not paste the BIND block into its configuration: a DNSOnly server runs PowerDNS by default, which does not take the BIND block and stops answering.

The block is filled in with this server's address and the TSIG key, like the other two. It differs from them in one way: a DNSOnly server cannot follow the catalog zone, so you add every zone by hand.

  • For each domain this server has now, and for each new one: add the zone line from the block with <domain> replaced by the domain, then run the commands shown below it.
  • To remove a zone: delete its line and its zone file, as the text under the block describes, then run the command it names.
  • Without a TSIG key: skip the two key lines the text under the block names.

A zone the DNSOnly server already holds

If the DNSOnly server already has its own zone for a domain, for example from a cPanel DNS cluster, delete that zone there before you add the line. The transfer from this server overwrites it otherwise. If the DNSOnly server is still part of a cPanel DNS cluster, also make sure the cluster no longer sends it that zone, or the cluster may put it back. The text under the block names the WHM screen and the command for the deletion.

To replace a cPanel DNS cluster with AdminBolt nameservers instead of keeping a DNSOnly server, see Replacing a cPanel DNS cluster.

Checking what a secondary serves ​

Since panel 1.9.3 every send of the zones, on save or with Send zones, is followed by a check of up to two minutes. Its result arrives in the panel bell as Zone delivery to followed by the secondary's address, for example "All 24 zone(s) are served by 203.0.113.7.", or with the zones that are not served and the reason for each. A zone counts as served when the secondary answers with this server's SOA serial. On a hub, the zones of accounts hosted on a node with the Secondary DNS role count as served on that node when it answers for them with authority, whatever their serial.

This server also checks every active secondary on its own, every few minutes and shortly after a zone changes, and shows the result in the Zones served and Last check columns of the list. Since panel 1.9.4 Zones served leads with the result, for example "2 of 24 zones not served correctly", and clicking that badge opens Sync issues with each failing zone. The line under the badge only says how the records were compared. Last check is the time of the check behind that result, with the zone named when the check covered one zone only. Edit and Delete sit in the row's action menu next to Send zones. A zone that a secondary has not served correctly for longer than a set time appears on Health. The columns and the check from the command line are described under Checking that a secondary serves the zones.

NOTIFY and the TSIG key ​

Since panel 1.9.2 this server sends NOTIFY unsigned, to every secondary, even when a TSIG key is set. The key signs the zone transfers (AXFR) only. The TSIG key section of the form says so:

NOTIFY from this server is never signed, even when a key is set: the key authenticates the zone transfers (AXFR) only. A secondary that requires a signed NOTIFY (for example BIND with the key in allow-notify) must accept an unsigned NOTIFY from this server's address.

This way every secondary, with or without a key, hears about new and changed zones. Before 1.9.2, once any secondary had a key, NOTIFY went out signed with it, and secondaries that did not know that key, such as hub nodes with the Secondary DNS role, refused it and stopped receiving new zones.

If you configured a secondary to accept only a signed NOTIFY, change it to accept an unsigned NOTIFY from this server's address. Zone transfers keep using the key.

Updating to 1.9.2 applies this once on every server that has at least one active secondary, hub or not, so you do not need to save the list again. If that step cannot finish, the update reports it as a failed upgrade step and NOTIFY may still be signed. Correct the reason it gives, then run bolt-cli run-upgrade-steps --retry-failed (see Updating AdminBolt), or edit and save a Manual secondary on this page, which pushes the same configuration.

The administrator API ​

Since panel 1.9.4, this list is on the administrator REST API, with the rules of this page:

Method and pathWhat it does
GET /api/dns/secondary-serversEvery secondary DNS server, cluster nodes included.
POST /api/dns/secondary-serversAdd a secondary. The row is saved even when the DNS server cannot be configured, and cluster_config says how that went. An active secondary is sent every zone.
GET /api/dns/secondary-servers/{id}Read one secondary.
PATCH /api/dns/secondary-servers/{id}Change the fields sent. A TSIG secret not sent stays as it is, and tsig_secret: null removes it. A secondary moved to a new address, or switched back on, is sent every zone.
DELETE /api/dns/secondary-servers/{id}Remove the secondary, so it no longer gets NOTIFY or zone transfers.

The row of a cluster node is refused with 409: turn the node's Secondary DNS role off instead. A row a node left at an old address may be deleted. Sending the zones again is described in Send zones over the API.