Organizations with multiple DNS providers can use NS1 as the primary provider, configuring third-party DNS servers as secondaries. In this type of configuration, NS1 supports authoritative (AXFR) transfers in which the entire zone file is transferred from NS1's DNS servers to the secondary servers.
Follow the instructions below to configure NS1 as a primary DNS provider.
Note
When transferring zone data from NS1, it's important to note that the AXFR protocol does not support much of NS1's advanced functionality or configurations — including ALIAS records, Filter Chain™ configurations, answer metadata, etc.
Follow the instructions below to create a primary zone in the NS1 portal. Alternatively, you can do this via API.
-
Log into the NS1 portal (https://my.nsone.net) and navigate to DNS > Zones.
-
Click the + icon to create a new zone.
-
Enter the fully qualified Domain name (FQDN) for the zone.
-
Select the DNS network(s) on which you want to publish the zone. You can deselect all networks to leave the zone unpublished for now.
-
Under Zone Settings, ensure the Normal setup option is selected.
-
Optionally, adjust the following zone settings:
-
SOA TTL (seconds) - The time-to-live (TTL) of the zone’s start of authority (SOA) record. This value indicates the amount of time resolvers cache the SOA. Default is 3600 seconds (i.e., 1 hour).
-
Refresh (seconds) - The amount of time between each attempt by the secondary DNS servers to refresh the primary zone file. Default is 43200 seconds (i.e., 12 hours).
-
Retry (seconds) - If the secondary server's attempt to refresh the primary zone file fails, this is the amount of time before the secondary server attempts the refresh again. Default is 7200 seconds (i.e., 2 hours). The secondary server will continue to try refresh at this interval until the zone has refreshed successfully or until reaching the expiry time.
-
Expire (seconds) - If refresh and retry attempts fail repeatedly, this is the amount of time after which the primary server should be considered “down” and no longer the authoritative. Default is 1209600 seconds (i.e., 14 days).
-
NX TTL (seconds) - If the DNS query results in an NXDOMAIN error or EBOT/NODATA response, this value indicates the amount of time the “negative” answer is cached. Default is 3600 seconds (i.e., 1 hour).
-
MNAME - The domain name of the nameserver that is the original or primary source of data for this zone.
-
RNAME - The email address of the administrator responsible for this zone.
-
-
Once complete, click Save Zone. The new zone appears in the list and, if you selected a network on which to publish the zone, the NS record automatically populates with the associated nameserver(s). If you did not select a network, the NS record is empty.
Warning
To complete the zone configuration, you must add the new DNS nameservers to the domain registrar. Do not update the registrar until you are ready to send DNS traffic to the new nameservers. If you are undergoing a large migration to the NS1 platform or between NS1 services, adhere to the guidance provided by the NS1 team before updating the registrar.
Execute the command below to create a primary zone via the NS1 API. Note that you must use a valid NS1 API key with all DNS permissions enabled.
curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
"zone":"<zoneFQDN>",
"networks": [0]
}
' https://api.nsone.net/v1/zones/<zone_name>
Table 1. Path parameters
|
|
string |
(Required) Unique name of the zone. Likely, you’ll want to set this to match the zone FQDN, but you can apply a nominal zone name if you plan to create multiple zones that point to the same FQDN. |
Table 2. Request body parameters
|
|
string |
(Required) Fully qualified domain name for this zone. |
|
|
array of integers |
Unique network ID(s) corresponding to NS1’s DNS networks on which to publish the zone. To view a list of network IDs available to you, execute a GET command against |
|
|
integer |
The time-to-live (TTL) of the zone’s start of authority (SOA) record. This value indicates the amount of time resolvers cache the SOA. Default is 3600 (seconds; i.e., 1 hour). |
|
|
integer |
The amount of time between each attempt by the secondary DNS servers to refresh the primary zone file. Default is 43200 ( seconds; i.e., 12 hours). |
|
|
integer |
If the secondary server’s attempt to refresh the primary zone file fails, this is the amount of time before the secondary server attempts the refresh again. Default is 7200 (seconds; i.e., 2 hours). The secondary server will continue to attempt refresh at this interval until the zone has refreshed successfully or until the expiry time is reached. |
|
|
integer |
If refresh and retry attempts fail repeatedly, this is the amount of time after which the primary server should be considered “down” and no longer the authoritative. Default is 1209600 (seconds; i.e., 14 days). |
|
|
integer |
If the DNS query results in an NXDOMAIN error or EBOT/NODATA response, this value indicates the amount of time the “negative” answer will be cached. Default is 3600 (seconds; i.e., 1 hour). |
Next, you must enable and configure outgoing zone transfers from the primary zone you just created to the secondary zone(s) hosted outside the NS1 platform.
When changes are made to the primary zone, NS1 will send a DNS notification (i.e., “NOTIFY”) to the secondary zone server. In response, the secondary server sends an SOA/AXFR query to NS1, requesting the new zone data. Then, NS1 transfers the new zone data to the requesting secondary. Note that the “NOTIFY” messages are optional and may be automatically disabled based on your settings. If NOTIFYs are disabled, the zone transfer will not occur until the next SOA request from the secondary servers based on the refresh TTL.
Follow the instructions below to enable outgoing zone transfers on the zone in the NS1 portal. Alternatively, you can do this via API.
-
In the NS1 portal, navigate to the Zones page (i.e., DNS > Zones). From the list of zones, find and click the name of the primary zone you just created to view zone details.
-
Click the Zone transfers tab, and click the toggle next to Allow outgoing transfers.
-
Click Add another IP address.
-
Enter the Secondary IP address — that is, the IP address of the server hosting the secondary zone. Optionally, you can enter an IP subnet in this field using CIDR notation (e.g., 192.0.2.0/24) to allow NS1 to receive SOA/AXFR requests from any address within that subnet. Note that if you do this, however, “NOTIFYs” are automatically disabled. Alternatively, you can add each secondary IP address individually to allow NOTIFYs to each.
-
Optionally, select the checkbox next to Notify on change to enable DNS notifications (i.e., NOTIFY messages) from NS1 when there are changes to the primary zone.
In response, the secondary zone will send an SOA/AXFR query to NS1 requesting the new zone data. If you leave this option disabled, the zone transfer will occur in response to the next SOA/AXFR query whose frequency is based on the defined SOA refresh TTL value.
If you enable notifications, complete the following additional fields:
-
Port - Enter the inbound port configured on the secondary IP to ensure the server can receive NOTIFY messages from NS1. The default port is 53. You might need to modify this if, for example, your security team has blocked inbound traffic to port 53 or if you’d prefer to use a different port.
-
Network - Select the network from which the DNS notification (i.e., NOTIFY) should originate. Upon changes to the NS1 zone, this network will send a NOTIFY to the secondary IP.
Note
You must select a network on which the corresponding NS1 zone is published — otherwise, NOTIFYs will be disabled. Optionally, you can select a network on which you plan to publish the zone, and then when you publish the zone to that network, the NOTIFYs will be automatically re-enabled.
-
-
If you enable notifications, you have the additional option to enable the Notify with TSIG. This ensures the NOTIFY messages are sent using TSIG authentication.
If you select this option, you must also specify the following information:
-
TSIG hash - Indicates the cryptographic algorithm used to generate the TSIG key.
-
TSIG key name - Name of the TSIG key used in domain name syntax.
-
TSIG key value - The base64 string encoding the shared key secret.
Note
The "Notify with TSIG" option only enables TSIG authentication for the NOTIFY message. It does not enable TSIG authentication for the actual zone transfer from NS1.
-
-
Click Save. Repeat this process as needed by clicking + Add another IP address, specifying additional secondary IP addresses or subnets to direct zone transfers from NS1.
-
After adding all of the secondary IPs to the list, click Save zone transfers.
Execute one of the commands below to enable outgoing zone transfers on an existing zone to one or more secondary IP addresses.
Example 1. Enable outgoing zone transfers (without NOTIFYs)
curl -X POST -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
"primary": {
"enabled": true,
"secondaries": [
{
"ip":"<secondary_IP>",
"notify": false
}]
}
}
' https://api.nsone.net/v1/zones/<zone_name>
Example 2. Enable outgoing zone transfers with NOTIFYs enabled
curl -X POST -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
"primary": {
"enabled": true,
"secondaries": [
{
"ip":"<secondary_IP>",
"notify": true,
"port":<secondary_port>,
"network": 0
}]
}
}
' https://api.nsone.net/v1/zones/<zone_name>
Example 3. Enable outgoing zone transfers with NOTIFYs with TSIG enabled
curl -X POST -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
"primary": {
"enabled": true,
"secondaries": [
{
"ip":"<secondary_IP>",
"notify": true,
"port":<secondary_port>,
"network": 0,
"tsig": {
"enabled": true,
"hash": "<tsig_hash>",
"name": "<tsig_name>",
"key": "<tsig_key>"
}
}]
}
}
' https://api.nsone.net/v1/zones/<zone_name>
Path parameters:
|
|
string |
(Required) Unique name of the zone for which you are enabling outgoing zone transfers. In most cases, this is the same as the zone FQDN. |
Request body parameters:
|
|
object |
(Required for enabling zone transfers) An object containing all secondary IP configurations corresponding to this primary zone. |
|
> |
boolean |
(Required for enabling zone transfers) Set to true to indicate that this zone is a primary zone with one or more secondaries. |
|
> |
array of objects |
(Required for enabling zone transfers) An array of objects containing details about each secondary IP. |
|
>> |
string |
(Required for enabling zone transfers) IP address corresponding to a secondary DNS server. You can also enter an IP subnet here using CIDR notation, but doing so automatically disables NOTIFYs. |
|
>> |
boolean |
Indicates whether or not to enable DNS notifications (i.e., NOTIFYs) to the secondary IP upon changes to the primary zone data. Default is false. |
|
>> |
integer |
The unique network ID for the network from which to send the NOTIFY message. The network ID must match a network to which the primary zone is published in order for NOTIFYs to be sent. |
|
>> |
integer |
Inbound port on the secondary IP configured to receive NOTIFY messages from NS1. Default is 53. |
|
>> |
object |
An object containing TSIG authentication details. |
|
>>> |
boolean |
Indicates whether or not the NOTIFY message should be sent using TSIG authentication. Default is false. If set to true, you must also include the TSIG configuration parameters below. |
|
>>> |
string |
Indicates the cryptographic algorithm used to generate the TSIG key. NS1 supports the following hash types: hmac-md5, hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512. |
|
>>> |
string |
Name of the TSIG key used in domain name syntax. |
|
>>> |
string |
The base64 string encoding the shared key secret. |
Optionally, after enabling outgoing zone transfers on the NS1 platform, you can use the dig command below from the secondary server to verify that the zone transfers configuration:
$ dig +tcp @xfr01.nsone.net <zoneFQDN> axfr
Replacing <zoneFQDN> with the fully qualified domain name of the zone.
Note
The hostname of the XFR service (i.e., shown above as xfr01.nsone.net) will vary if the zone is published to an NS1 edge network or if you are using a dedicated namespace from NS1.
After configuring the zone transfers, you must configure the secondary DNS servers to use NS1’s XFR server as the zone’s primary.
-
For primary zones published to the shared Managed DNS network, the corresponding secondary zones must be configured to allow NOTIFY messages from xfr01.nsone.net (192.135.223.10) if NOTIFYs are enabled.
-
For zones published to a dedicated namespace within the Managed DNS network, the IP addresses for the zone transfer services will be provided to you.
If using BIND, you can add the following code snippet to the configuration file:
zone "<zoneFQDN>" IN { type slave; file "/var/lib/bind/<myzone.com>.db"; masters { 192.135.223.10; }; };
This completes the configuration process. Optionally, you can use a dig command to verify the configurations match on the primary (NS1) and secondary DNS servers, but note that this process may vary depending on your setup. For example:
$ dig @xfr01.nsone.net +noall +answer -t soa <zoneFQDN> +multiline
If you haven't already, you must update the DNS configuration at the domain registrar (e.g., GoDaddy, BlueHost, etc.) to point to the NS1 nameservers. Do not update the registrar until you are ready to send DNS traffic to the new nameservers. If you are undergoing a large migration to the NS1 platform or between NS1 services, adhere to the guidance provided by the NS1 team before updating the registrar.