Note
Zone versioning is available upon request only. Contact the NS1 customer support team to enable this feature on your account.
On the NS1 platform, zone versioning refers to the ability to save backup copies of your zone data that can be restored later. This can be useful for troubleshooting purposes or if you need to change the zone configuration temporarily. You can save up to three "inactive" versions of a zone. The "active" version represents the current zone configuration. Any changes you make to the zone are saved automatically to the active version. If you create a new version or restore an old one, the previously active version becomes inactive.
You can see all existing zone versions in the NS1 portal by navigating to DNS > Zones, clicking the name of the zone to view details, and then navigating to the Versions tab.
This page contains a list of versions (active and inactive) for the selected zone and provides details for each version, including:
-
Name - This is a name you give to a zone version for internal reference only. How you name your versions is up to you, but we recommend using something to help distinguish between them.
-
ID - Each zone version is automatically given a unique identifier when it is created, and then the ID is updated each time you activate (restore) it.
-
Status - This indicates the current status, active or inactive, for each version. You can only have one active version at a time. You cannot delete the active version.
You can also view timestamps for each version indicating when it was created, when it was last activated or restored, and when it was last deactived.
-
Zone versioning and outgoing zone transfers are not compatible.
In other words, you cannot create a zone version if you have outgoing zone transfers enabled or configured. Similarly, enabling outgoing zone transfers will prevent you from creating new versions or restoring past versions of this zone. Zone transfer configurations are not included in the saved version data. If necessary, you can disable outgoing zone transfers to create or activate a zone version and enable them later.
-
You cannot save backup versions of a secondary or linked zone.
Due to the nature of secondary zones on the NS1 platform, you cannot create backup versions as secondary zone data is pulled directly from the primary DNS provider and updated on a recurring basis. The same is true for linked zones which do not support any extra configuration other than that of the target zone to which it points.
-
You cannot create versions of a zone containing >1000 records.
If your zone exceeds 1000 records, you will not be able to create a new version. You will still be able to activate previously saved versions (containing <1000 records).
Each section below provides instructions for creating, previewing, deleting, and activating (restoring) zone versions using the NS1 portal. If preferred, refer to the end of this article for details on managing zone versions using the NS1 API.
You can save up to three inactive versions of a zone after which point you will have to select an older version to replace with any new versions you create.
Note
You cannot create a new version of a zone if you have outgoing zone transfers enabled. As a workaround, you can delete and disable outgoing zone transfers, create a new version, and reconfigure the outgoing zone transfers as needed.
Follow the instructions below to create a new version for a zone in the NS1 portal. If you are using the NS1 API, refer to the API reference section for an index of relevant API requests.
-
In the NS1 portal, navigate to DNS > Zones, click the name of a zone to view details, and then click the Versions tab.
-
Click Create version.
-
Enter a name for this version for internal reference (40 character max).
If you have exceeded the maximum number of versions allowed for a zone, you will be prompted to select another inactive version to delete upon creating the new version.
-
Click Create. A banner appears indicating the version was created successfully. The new version appears in the list and is set to the "active" version. (Note: You may need to refresh the page to see the changes.)
Before activating or deleting an inactive version of a zone, you can preview the records and configuration settings contained within that version.
From the list of zones, click the preview icon next to the name of an inactive version.
A secondary browser tab or window appears containing a preview of the selected zone version. You can view the records and configuration settings associated with that version of the zone.
You can delete or activate the version from here, or you can close the preview window and return to the primary portal window.
Note
If you delete or activate a version from the preview page, you must refresh the portal to see changes reflected in the original tab/window.
You can delete an inactive version of a zone to make room for a new one or to prevent accidental rollback to the zone at that state. Before you delete a version, you can Preview an inactive zone version the zone data it contains.
Note
You cannot delete the active version.
-
From the list of versions, select the checkbox to the left to the version you want to delete.
-
Click Delete. A message appears asking you to confirm the change.
-
Click Yes, delete version. A banner appears indicating the version was deleted successfully. The deleted version is removed from the list. (Note: You may need to refresh the page to see the changes.)
You can activate an old version to revert back to the state of the zone at the point the version was created. Before doing so, you can preview the zone data by clicking the preview icon next to the version name.
-
From the list of versions, select the checkbox next to the inactive version you want to activate (restore).
-
Click Activate. A message appears asking you to confirm the change.
-
Click Activate again. The version you just activated appears at the top of the list and it is assigned a new version ID. All other versions are set to inactive.
If preferred, you can use the NS1 API to create and manage zone versions by sending requests to the following NS1 API endpoint:
https://api.nsone.net/v1/zones/<zoneName>/versions
In the URL path, <zoneName> refers to the unique name of the zone. Typically, this is the same as the zone FQDN.
You will also need a valid NS1 API key with permissions enabled to manage DNS resources. Replace the $NSONE_API_KEY variable in the example requests below with your unique API key secret.
Use the following GET request to return a list of all existing versions (active and inactive) for the specified zone.
curl -X GET -H "X-NSONE-Key: $NSONE_API_KEY" https://api.nsone.net/v1/zones/<zoneName>/versions
Example response:
[
{
"activated_at": 1686838053,
"active": false,
"created_at": 1686838053,
"deactivated_at": 1686838071,
"id": 1,
"name": "Initial version"
},
{
"activated_at": 1686838071,
"active": false,
"created_at": 1686838071,
"deactivated_at": 1686838185,
"id": 2,
"name": "v2 - Adding DNS records"
},
{
"activated_at": 1686838185,
"active": true,
"created_at": 1686838185,
"id": 3,
"name": "v3 - Testing Filter Chain configurations"
}
]
Warning
If you already have three inactive versions of a zone (four versions total), you will receive an error after attempting to create a new version. In this case, you must first delete an existing version and then try to create a new version again. Alternatively, you can add a query parameter (force=true) to force the NS1 platform to create the new version while deleting the version with the lowest version ID (presumably, the oldest zone version).
The following PUT request creates a new version of the specified zone.
curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '{"name":"string"}' https://api.nsone.net/v1/zones/<zoneName>/versions
Example response: Version created successfully
{
"activated_at": 1686839637,
"active": true,
"created_at": 1686839637,
"id": 4,
"name": "v4 - Adding subdomains"
}
Example response: Error (Maximum versions reached)
If you have reached the maximum number of versions, you will receive an error message similar to the following:
{"message":"zone has reached max number of versions (4 versions)","details":[{"type":"request-id","message":"46162310-1dcf-4341-8e4e-d0b39c5ff8af"}]}
In this case, you can add a query parameter (force=true) to the PUT request to replace the existing zone version with the lowest version ID number with the one you are trying to create.
Example request: Create a new version & delete the oldest inactive version
curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '{"name":"string"}' https://api.nsone.net/v1/zones/<zoneName>/versions\?force=true
The following POST request creates a new version of the specified zone. You must include an empty request body and replace <versionID> with the unique identifier for the zone version you are activating. You can view the ID for each existing version using a GET request to /v1/zones/<zoneName>/versions.
curl -X POST -H "X-NSONE-Key: $NSONE_API_KEY" -d '{}' https://api.nsone.net/v1/zones/<zoneName>/versions/<versionID>/activate
Example response: Version activated successfully
{}