Secondary Zones¶
The Designate v2 API introduced functionality that allows Designate to act as a DNS slave, rather than a master for a zone. This is accomplished by completing a zone transfer (AXFR) from a DNS server managed outside of Designate.
RecordSets / Records¶
Changes to secondary zones are managed outside of Designate. Users must make the changes they wish, and prompt a fresh zone transfer (AXFR) into Designate to make those changes live on any DNS servers Designate manages.
Setup¶
To add a secondary zone to Designate, there must be a DNS master for the zone, to which Designate can act as a slave. For this guide, we assume that you have already set this up.
The remaining Designate set up will be similar to a non-secondary zone setup. You’ll need a primary DNS server for Designate to manage and transfer secondary zones to.
In our examples we’ll use the following values:
Name - example.com.
Masters - 192.168.27.100
Setup - example NSD4¶
Skip this section if you have a master already to use.
Note
For this it is assumed that you are running on Ubuntu.
Install¶
For some reason there’s a bug with the nsd package so it doesn’t create the user that it needs for the installation. So we’ll create that before installing the package.
$ sudo apt-get install nsd
Configure¶
$ sudo zcat /usr/share/doc/nsd/examples/nsd.conf.sample.gz >/tmp/nsd.conf
$ sudo mv /tmp/nsd.conf /etc/nsd/nsd.conf
Add the following to /etc/nsd/nsd.conf
Note
If you’re wondering why we set notify to 192.168.27.100:5354 it’s because MDNS runs on 5354 by default.
$ sudo vi /etc/nsd/nsd.conf
Add the contents:
pattern:
name: "mdns"
zonefile: "%s.zone"
notify: 192.168.27.100@5354 NOKEY
provide-xfr: 192.168.27.100 NOKEY
allow-axfr-fallback: yes
Add a zone file¶
Create a new Zone in NSD called example.com.
/etc/nsd/example.com.zone
$ sudo vi /etc/nsd/example.com.zone
And add the contents:
$TTL 1800 ;minimum ttl
example.com. IN SOA ns1.example.com. admin.example.net. (
2014111301 ;serial
3600 ;refresh
600 ;retry
180000 ;expire
600 ;negative ttl
)
TXT "v=spf1 +a +mx ~all"
SPF "v=spf1 +a +mx ~all"
NS ns1.example.com.
NS ns2.example.com.
NS ns3.example.com.
MX 0 mail1.example.com.
MX 5 mail2.example.com.
MX 10 mail3.example.com.
A 10.0.0.1
A 10.0.0.2
A 10.0.0.3
ns1 A 172.16.28.100
ns2 A 172.16.28.101
ns3 A 172.16.28.103
mail1 A 10.0.10.1
mail2 A 10.0.10.2
mail3 A 10.0.10.3
google CNAME google.com.
Restart NSD¶
$ sudo service nsd restart
Check that it’s working
$ sudo nsd-control status
Activate the zone in NSD
$ sudo nsd-control addzone example.com mdns
Creating the Zone¶
When you create a domain in Designate there are two possible initial actions:
- Domain is created but transfer fails if it’s not available yet in master, then typically the initial transfer will be done once the master sends first NOTIFY.
- Domain is created and transfers straight away.
In both cases the interaction between your master and Designate is handled by the MDNS instance at the Designate side.
Definition of values:
- email set to the value of the managed_resource_email option in the central section of the Designate configuration.
- transferred_at is null and version is 1 since the zone has not transferred yet.
- serial gets set automatically by the system initially and to the value of the master’s serial post initial AXFR.
-
POST
/zones
¶ Creates a new zone.
Example request:
POST /v2/zones HTTP/1.1 Host: 127.0.0.1:9001 Accept: application/json Content-Type: application/json { "name": "example.com.", "type": "SECONDARY", "masters": ["192.168.27.100"], "description": "This is a slave for example.com." }
Example response:
HTTP/1.1 201 Created Content-Type: application/json { "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", "name": "example.com.", "email": "email@example.io", "ttl": 3600, "serial": 1404757531, "status": "ACTIVE", "description": "This is a slave for example.com." "masters": ["192.168.27.100"], "type": "SECONDARY", "transferred_at": null, "version": 1, "created_at": "2014-07-07T18:25:31.275934", "updated_at": null, "links": { "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" } }
Get Zone¶
-
GET
/zones/
(uuid: id)¶ Retrieves a secondary zone with the specified zone ID.
Example request:
GET /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 Host: 127.0.0.1:9001 Accept: application/json Content-Type: application/json
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", "name": "example.com.", "email": "email@example.io", "ttl": 3600, "serial": 1404757531, "status": "ACTIVE", "description": "This is a slave for example.com." "masters": ["192.168.27.100"], "type": "SECONDARY", "transferred_at": null, "version": 1, "created_at": "2014-07-07T18:25:31.275934", "updated_at": null, "links": { "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" } }
Status Codes: - 200 OK – Success
- 401 Unauthorized – Access Denied
List Secondary Zones¶
-
GET
/zones
¶ Lists all zones.
Example Request:
GET /v2/zones?type=SECONDARY HTTP/1.1 Host: 127.0.0.1:9001 Accept: application/json Content-Type: application/json
Example Response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "zones": [{ "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", "name": "example.com.", "email": "email@example.io", "ttl": 3600, "serial": 1404757531, "status": "ACTIVE", "description": "This is a slave for example.com.", "masters": ["192.168.27.100"], "type": "SECONDARY", "transferred_at": null, "version": 1, "created_at": "2014-07-07T18:25:31.275934", "updated_at": null, "links": { "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" } }, { "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca4", "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", "name": "bar.io.", "email": "email@example.io", "ttl": 3600, "serial": 10, "status": "ACTIVE", "description": "This is a slave for bar.io.", "masters": ["192.168.27.100"], "type": "SECONDARY", "transferred_at": "2014-07-07T18:25:35.275934", "version": 2, "created_at": "2014-07-07T18:25:31.275934", "updated_at": null, "links": { "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" } }], "links": { "self": "https://127.0.0.1:9001/v2/zones" } }
Status Codes: - 200 OK – Success
- 401 Unauthorized – Access Denied
Update Zone¶
-
PATCH
/zones/
(uuid: id)¶ Changes the specified attribute(s) for an existing zone.
In the example below, we update the TTL to 3600.
Request:
PATCH /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 Host: 127.0.0.1:9001 Accept: application/json Content-Type: application/json { "masters": ["192.168.27.101"] }
Response:
HTTP/1.1 200 OK Content-Type: application/json { "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", "name": "example.com.", "email": "email@example.io", "ttl": 3600, "serial": 1404757531, "status": "ACTIVE", "description": "This is a slave for example.com.", "masters": ["192.168.27.101"], "type": "SECONDARY", "transferred_at": null, "version": 2, "created_at": "2014-07-07T18:25:31.275934", "updated_at": "2014-07-07T18:25:34.275934", "links": { "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" } }
Form Parameters: - description – UTF-8 text field.
- name – Valid zone name (Immutable).
- type – Enum PRIMARY/SECONDARY, default PRIMARY (Immutable).
- email – email address, required for type PRIMARY, NULL for SECONDARY.
- ttl – time-to-live numeric value in seconds, NULL for SECONDARY
- masters – Array of master nameservers. (NULL for type PRIMARY, required for SECONDARY otherwise zone will not be transferred before set.)
Status Codes: - 200 OK – Success
- 202 Accepted – Accepted
- 401 Unauthorized – Access Denied
Delete Zone¶
-
DELETE
zones/
(uuid: id)¶ Deletes a zone with the specified zone ID.
Example Request:
DELETE /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 Host: 127.0.0.1:9001 Accept: application/json Content-Type: application/json
Example Response:
HTTP/1.1 204 No Content
Status Codes: - 204 No Content – No content