Create a DNS zone – NS1 Help Center

There are three types of zones you can create on the NS1 platform: primary, secondary, and linked zones. You can create these zones manually or import a zone file. Some configuration options vary based on the type of zone you select.

To create any type of zone in the NS1 portal, log into the portal (https://my.nsone.net) and navigate to DNS > Zones.

Click the + icon to create a new zone.

"Add zone" modal; Create a DNS, resource management

Enter the fully qualified Domain name (FQDN) associated with the zone.

Optionally, you can select a DNS view with which to associate the zone. For more information, refer to Configuring DNS views.

Warning

At this time, zones published on the NS1 Managed DNS or NS1 Managed DNS for China networks cannot be associated with a DNS view.

Additionally, you have the option to click Override zone name and enter a unique zone name to apply to this zone. This feature is used if you plan to create multiple zones that point to the same FQDN. If you associate the zone with a DNS view during the initial setup, the name of the DNS view is appended to the end of the zone FQDN to make up the zone name (e.g., <zoneFQDN>-<DNS_view>). Otherwise, if you do not associate the zone with a DNS view and you do not override the zone name, the zone name defaults to match the zone FQDN. Note that you cannot modify the zone name after creating 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. Note that selecting or deselecting the network options removes any custom nameservers specified as answers in the zone's NS record.

Note

In most cases, if publishing a zone to a Dedicated DNS network, NS1 recommends publishing the zone to the Managed DNS network as well.

Under Zone Settings, select one of the following options:

Normal setup - This option creates a primary zone hosted on the NS1 platform.
Zone file import - This option allows you to import a zone file. After importing the zone, you can modify zone details based on the type of zone imported.
Secondary zone - This option creates a secondary zone hosted on the NS1 platform.
Linked zone - This option allows you to create a linked zone. Note that you cannot modify zone settings for a linked zone after import.

Refer to the relevant section below to view configuration details for primary and secondary zones.

Next, refer to Creating a DNS record to learn how to add DNS records to a zone.

Primary zone configuration options

To create a primary zone, select Normal setup in the Add zone modal.

Optionally, you can 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 is automatically populated with the associated nameserver(s). If you did not select a network, the NS record is empty.

After creating the zone on the NS1 platform and publishing it to a network, you must update the nameservers at the registrar. If this primary zone has secondary zones hosted by third-party DNS providers, you must enable outgoing zone transfers. Refer to Configuring NS1 as a primary DNS provider for details.

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.

API: Create a primary zone

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>

Parameters

Table 1. Path parameters

<zone_name>

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

`zone`	string	(Required) Fully qualified domain name for this zone.
`networks`	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 `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.
`ttl`	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).
`refresh`	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).
`retry`	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.
`expiry`	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).
`nx_ttl`	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).

Secondary zone configuration options

To create a secondary zone, select Secondary zone in the Add Zone modal.

Then, complete the following form fields:

Enter the Primary IP address corresponding to the primary DNS server, specify the Port on which this primary is configured to receive incoming SOA and IXFR/AXFR queries from NS1, and then select the NS1 Network from which the SOA and IXFR/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. The new zone appears in the list and, if you selected a network on which to publish the zone, the NS record is automatically populated with the associated nameserver(s). If you did not select a network, the NS record is empty.

After creating the zone on the NS1 platform and publishing it to a network, you must update the primary DNS configuration, adding NS records that point to the NS1 nameservers. Refer to Configuring NS1 as a secondary provider for more information and your third-party DNS provider's documentation for instructions on adding NS records to DNS zones.

API: Create a secondary zone

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

Example 1. 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 2. 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 3. 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.

Warning

Articles in this section

Warning

Note

Primary zone configuration options

Warning

API: Create a primary zone

Parameters

Secondary zone configuration options

Note

Warning

API: Create a secondary zone

Parameters

Warning

Related articles