Configuring NS1 as a secondary provider – NS1 Help Center

Customers with multiple DNS providers can use NS1 as their secondary DNS provider, creating one or more secondary zones that contain a read-only copy of the primary zone file that a different DNS provider hosts.

Typically, with this configuration, the primary DNS server will notify NS1 upon changes to the zone file — for example, if a new IP is associated with a domain name. In response, NS1 will send an SOA/AXFR query to the primary server to request the new data. Then, the primary server transfers the new zone data to the NS1 servers, updating the secondary zone.

If you do not have DNS notifications (NOTIFYs) enabled on your primary zone, the zone transfer will occur in response to the following SOA/AXFR query whose frequency is based on the defined SOA refresh TTL value.

As explained in RFC 5936, there are two types of zone transfers — both of which are supported for incoming zone transfers to NS1 (i.e., when NS1 is secondary).

Authoritative transfers (AXFR) copy the entire zone file from the primary to the secondary.
Incremental transfers (IXFR) copy only the zone data that has changed.

It’s important to understand that secondary zones hosted by NS1 contain a read-only copy of the primary zone data. The only new record you can create within a secondary zone is an ALIAS record. Otherwise, you cannot add or edit DNS records or answers from within the NS1 platform. Additionally, you cannot apply certain NS1 functionality to secondary zones, such as Filter Chain™ configurations to these records. In terms of managing secondary zones in the NS1 platform, only the following actions are supported:

You can publish the secondary zone to one or more NS1 networks.
You can specify one or more primary IPs.
You can indicate which NS1 network should receive NOTIFYs from each primary.
You can enable TSIG authentication for incoming zone transfers from the primary.
You can create an ALIAS record within a secondary zone. Note that no other record types can be added.
You can enable outgoing zone transfers from this secondary to other secondary IPs. This type of configuration is useful for creating redundancy in public DNS by using a "hidden primary" configuration whereby the source of truth doesn't serve public traffic directly. Instead, it serves as a primary to NS1's DNS server. Even though the DNS zone is technically a secondary zone, it serves as primary to additional secondaries hosted outside of NS1.

Note

ALIAS records are not included in outgoing zone transfers from the NS1 platform.
If necessary, you can convert the secondary zone to a primary zone.

Note

NS1 supports DNSSEC on incoming zone transfers — that is, zone transfers from third-party DNS servers (primary) to NS1 (secondary) — in which an NSEC or NSEC3 record is used to prove non-existence.

Refer to FAQs: Understanding secondary zones for more information.

Follow the instructions below to configure NS1 as your secondary DNS provider.

Step 1: Configure your primary DNS server to allow AXFR queries from NS1.

To enable zone transfers to NS1, you must configure your primary DNS server to allow AXFR queries over TCP and SOA queries over UDP from NS1’s XFR server.

For secondary zones published to NS1’s shared Managed DNS network (i.e., network 0), the AXFR server IP address is 192.135.223.10.
For secondary zones published to a dedicated namespace, the required IPs will be provided to you during the initial setup.
For zones published to an NS1 edge network (e.g., Cloud-Managed DDI), the relevant IP is that of the edge node running NS1’s XFR service.

Step 2: Create a secondary zone on the NS1 platform.

Follow the instructions below to create a secondary zone on the NS1 platform. You can do this via the NS1 portal or 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 secondary zone.
Select the DNS network(s) on which you want to publish the zone. You can deselect all networks to leave the zone unpublished.
Under Zone Settings, select Secondary zone.
Enter the Primary IP address corresponding to the primary DNS server, specify the Port on which this primary is configured to receive incoming SOA/AXFR queries from NS1, and then select the NS1 Network from which the SOA/AXFR queries will originate.

Note

To facilitate zone transfers, the network you select here must match a network to which the secondary zone is published. The primary server must be configured to receive queries from the AXFR server corresponding to this network.
Optionally, you can specify additional primary IPs (including the associated port and network). NS1 will balance AXFR queries among all primary servers. If an AXFR query fails, NS1 will attempt to query one of the other primary servers.
Optionally, click the Enable TSIG toggle to support TSIG authentication on incoming zone transfers from the primary servers to NS1. If enabled, you must enter the following details:
- TSIG hash - Indicates the cryptographic algorithm used to generate the TSIG key.
- TSIG key name - Name of the TSIG key used in the domain name syntax.
- TSIG key value - The base64 string encoding the shared key secret.
Warning

The TSIG key name and value defined here must match what is on the primary nameserver.
Once complete, click Save zone.

Once saved, the secondary zone is created in a “pending” state. It may take a few minutes for the first synchronization with your primary server. You can monitor the server’s status under the Zone Settings tab. Once the primary and secondary zones are in sync, all records configured on your primary server will appear on the NS1 platform.

API: Create a secondary zone

Execute one of the API commands below to create a secondary zone.

Example 4. Create a secondary zone with one primary IP

curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
    "zone":"<zoneFQDN>", 
    "networks": [0], 
    "secondary": 
    {
        "enabled": true, 
        "primary_ip": "<primaryIP>", 
        "primary_port": 53, 
        "primary_network": 0
    }
}' https://api.nsone.net/v1/zones/<zone_name>

Example 5. Create a secondary zone with one primary IP (with TSIG enabled)

curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
    "zone":"<zoneFQDN>", 
    "networks": [0], 
    "secondary": 
    {
        "enabled": true, 
        "primary_ip": "<primaryIP>", 
        "primary_port": 53, 
        "primary_network": 0, 
        "tsig": 
        {
            "enabled": true, 
            "hash": "<tsig_hash>", 
            "name": "<tsig_name>", 
            "key": "<tsig_key>"
        }
    }
}' https://api.nsone.net/v1/zones/<zone_name>

Example 6. Create a secondary zone with multiple primary IPs (with TSIG enabled)

curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
    "zone":"<zoneFQDN>", 
    "networks": [0], 
    "secondary": 
    {
        "enabled": true, 
        "primary_ip": "<primaryIP>", 
        "primary_port": 53, 
        "primary_network": 0, 
        "other_ips": ["<primaryIP_2>", "<primaryIP_3>"], 
        "other_networks": [0,0], 
        "other_ports": [53,53]
    }
}' https://api.nsone.net/v1/zones/<zone_name>

Parameters

Path parameters:

<zone_name>

string

(Required) Unique name of the zone. Likely,you will 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.

Request body parameters:

`zone`	string	(Required) Fully qualified domain name of the zone.
`networks`	array of integers	Unique network ID(s) corresponding to NS1’s DNS networks to which you want to publish the zone. To view a list of network IDs available to you, execute a GET command against `https://api.nsone.net/v1/networks`. Note that if you do not include the networks parameter when creating the zone, your zone will be automatically published to NS1’s Managed DNS network; however, if you include the networks parameter with an empty value (i.e., ({`“networks”: []}`), then the zone will not be published to any network.
`secondary`	object	(Required for creating secondary zones) Object containing all primary IP configurations corresponding to this secondary zone.
> `enabled`	boolean	Set to true to indicate this is a secondary zone.
> `primary_ip`	string	IPv4 address corresponding to the primary DNS server.
> `primary_port`	integer	Inbound port configured on the primary DNS server to receive incoming SOA/AXFR queries from NS1. Default is 53.
> `primary_network`	integer	Unique network ID for the NS1 network from which SOA/AXFR queries will originate. The network specified here must match a network to which the secondary zone is published. The primary server must be configured to allow incoming queries from this network.
> `other_ips`	array of strings	Comma-separated list of all additional primary IPv4 addresses. You need only include this if there are multiple primaries to this secondary zone.
> `other_ports`	array of integers	Comma-separated list of ports corresponding to the IPs listed under “other_ips.” Ensure the order of ports listed aligns with the order of “other_ips” and “other_networks.” Default is 53.
> `other_networks`	array of integers	Comma-separated list of network IDs corresponding to the IPs listed under “other_ips.” These are the network IDs from which SOA/AXFR queries will originate and must match a network to which the secondary zone is published. Ensure the order of ports listed aligns with the order of “other_ips” and “other_networks.”
> `tsig`	object	Object containing TSIG authentication details for incoming zone transfers (from third-party DNS providers to NS1).
>> `enabled`	boolean	Indicates whether or not to enable TSIG authentication for incoming zone transfers. If set to “true,” you must include the configuration parameters below.
>> `hash`	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.
>> `key`	string	Name of the TSIG key used in domain name syntax.
>> `name`	string	The base64 string encoding the shared key secret.

Step 3: Point DNS traffic to NS1 servers.

To complete the configuration, you must add NS records in the primary zone that point to the NS1 nameservers.

Use the NS1 portal or API to determine the nameservers associated with the secondary zone you just created.

To locate your nameservers using the NS1 portal, navigate to DNS > Zones, and click the name of the secondary zone you just created to view zone details. Then, click the Nameservers tab to view a list of nameservers associated with this zone.

Note

Only nameservers for zones published to NS1’s Managed DNS network will be shown on this page. If the zone is published to a dedicated namespace or edge network (e.g., NS1’s Cloud-Managed DDI network) this page will be empty. In this case, you can use the NS1 API to view a list of nameservers associated with a zone.

Alternatively, you can execute the API command below to view a list of nameservers associated with your secondary zone.
```
curl -X GET -H "X-NSONE-Key: $NSONE_API_KEY" https://api.nsone.net/v1/zones/<zone_name>
```
The response includes a dns_servers object containing all corresponding NS1 nameservers. For example,
```
{...
  "dns_servers": [
    "dns1.p01.nsone.net",
    "dns2.p01.nsone.net",
    "dns3.p01.nsone.net",
    "dns4.p01.nsone.net"
  ],
...}
```
Using the configuration tools provided by your primary DNS provider, add NS records to the primary zone for each NS1 nameserver.

Once complete, the zone is re-synchronized based on the refresh interval defined in the zone’s SOA record. If the zone transfer fails, the secondary zone enters a “warning” state and NS1 will attempt to complete the zone transfer based on the retry interval until it is successful or until it reaches the expiry timeout. If the process exceeds the expiry timeout before NS1 can sync successfully, then the secondary zone enters an “error” state and the NS1 server responds to queries with zone data based on the last successful transfer.

Articles in this section

Note

Note

Step 1: Configure your primary DNS server to allow AXFR queries from NS1.

Step 2: Create a secondary zone on the NS1 platform.

Note

Warning

API: Create a secondary zone

Parameters

Step 3: Point DNS traffic to NS1 servers.

Note

Related articles