What is Secondary DNS?

Secondary DNS is available for domains on Enterprise plans.


Secondary DNS allows Cloudflare to act as a Secondary DNS provider to another organization's Master DNS. With Secondary DNS, DNS entries are edited in a system outside of Cloudflare and changes are transferred to Cloudflare's infrastructure. 


If the current DNS provider does not support Zone Transfer, Cloudflare cannot become a Secondary DNS provider.

Prerequisites

1. Contact your Cloudflare Account team:

  • Request Secondary DNS to be enabled.
  • Request the configuration parameters to set at the primary DNS provider.


2. In the Cloudflare Overview app for the domain requiring Secondary DNS:

  • Identify the Cloudflare Account ID.
  • Identify the Cloudflare Zone ID.
  • Note the two Cloudflare Nameservers.


If the Cloudflare Nameservers don't contain secondary in the name, confirm the Cloudflare Account team has enabled Secondary DNS.


3. Consult the Master DNS provider's documentation for instructions on configuring the Master zone.

4. Determine the configuration parameters from the Master zone:

  • Master IP Address - The IP address that Cloudflare should accept Zone Transfers from.
  • Zone transfer type - Will zone transfers be full (AXFR) or incremental (IXFR)?
  • (Optional) TSIG Secret - The secret string used to authenticate zone transfers.
  • (Optional) TSIG Algorithm - The algorithm used to authenticate zone transfers.


Once the list of prerequisites have been completed, configure the Secondary Zone at Cloudflare.

Configuring a Secondary Zone through the CloudFlare API


DNSSEC is currently unsupported when Cloudflare is configured as a Secondary DNS provider.


Secondary DNS can only be configured via the Cloudflare API. Requests can be sent to the API via a command-line utility like cURL or a browser plugin such as Postman.  


Refer to the Cloudflare API documentation for full examples on the supported API methods available:


For each POST example provided in the steps below, replace :account_tag with the Account ID identified from the Prerequisites section of this article:

 

STEP 1 - Configure TSIG (Optional)


In the example request below, name and secret must be provided by the primary DNS provider and algomust reflect the correct TSIG algorithm from the Master DNS server.

#POST https://api.cloudflare.com/client/v4/accounts/:account_tag/secondary_dns/tsigs/ 
{"name": ":tsig_secret_name<e.g.zone-cf>", 
"secret": ":tsig_secret_string", 
"algo": "hmac-sha512"}


A successful POST request will respond with an id.  Include this id when adding a Master.


STEP 2 - Add a Master


Multiple Masters can be added via the Cloudflare API.

#POST https://api.cloudflare.com/client/v4/accounts/:account_tag/secondary_dns/masters/
{"ip": ":master_ip",
"port": 53, 
"ixfr_enable": true, 
"tsig_id": ":tsig_tag"}
  • :master_ip is the IPv4/IPv6 address of Master nameserver.
  • ixfr_enable set to true enables IXFR transfer protocol. The default is AXFR.
  • :tsig_tag (optional) is the id provided in STEP 1 - Configure TSIG, if configured


A successful POST request will respond with an id for the Master DNS server and must be included when creating a Secondary Zone via the Cloudflare API. 

 

STEP 3 - Create Secondary Zone

#POST https://api.cloudflare.com/client/v4/zones/:zone_tag/secondary_dns/
{"id": ":zone_tag", 
"name": ":zone_name", 
"masters": [ ":zone_master_tag" ], 
"auto_refresh_seconds": 30 }
  • :zone_tag is the Zone ID of the domain configured for Secondary DNS.
  • :zone_name is the domain name configured for Secondary DNS.
  • :zone_master_tag is the list of Master IDs created in STEP 2 - Add a Master.


The Cloudflare DNS UI will be disabled for Secondary Zones since records are managed through the primary DNS provider's Master server.


STEP 4 - Testing Secondary DNS


Add a TXT record to the primary DNS provider to test transfer to Cloudflare's Secondary DNS servers.  Then, verify the TXT record is visible when querying Cloudflare's nameservers.  Replace nsNNNN with the correct name of a Cloudflare Secondary DNS servers for the domain: 

dig @nsNNN.secondary.cloudflare.com :zone_name txt +short


The Cloudflare Analytics app will continue to provide DNS data but only for DNS requests that Cloudflare's nameservers answer.


Related Resources