Import and export a zone file

A zone file lists DNS records in the text format that BIND and most DNS providers use. Import one to copy many records into a Coritan zone at once, such as when you move a domain's DNS from another provider. The import adds only the records the zone does not have yet, so you can import a file again safely. Export one to keep a copy of a zone or to move its records elsewhere.

• The domain's DNS must be hosted on Coritan. If its DNS tab says No DNS zone for this domain, add the domain as an existing domain first.
• To move records from another provider, download the zone file from that provider. Cloudflare exports one from the domain's DNS records page. Import that file as it is: Files from Cloudflare says what the import does with it.

1. In the dashboard, go to Domain Management, open the domain and select the DNS tab.
2. Select More DNS actions, the three-dot button beside Add record…, then Import zone file…. When the zone has no records yet, Import zone file… is also under the empty table. The Import a zone file page opens under the tab.
3. Paste the file into Zone file, select Choose file… to pick it from your computer, or drop the file on the box. Check it against How the import reads a file first.
4. Select Import records.

Coritan reads the file as BIND does and adds a record for each one it can read, unless the zone already has that record. A record is a name, an optional TTL and class, a type and its content:

$TTL 1h
@                    IN A     203.0.113.10
www             3600 IN CNAME example.com.
@               3600 IN MX    10 mail.example.com.
mail                    A     203.0.113.20
                        AAAA  2001:db8::20
@               3600 IN TXT   "v=spf1 mx -all"   ; the domain's mail policy
_minecraft._tcp 3600 IN SRV   0 5 25565 play.example.com.

Name

@ for the domain, a name relative to the zone such as www, or the full name, such as www.example.com.. A line that starts with a space or a tab has no name of its own and belongs to the name above it, as 2001:db8::20 belongs to mail here. Coritan reads a name that ends in the domain as the full name with or without its trailing dot, so www.example.com makes www, where BIND would add the domain again. A full name outside the zone, such as mail.other.net., is skipped with an error.

TTL

Optional, in seconds or in BIND's units, such as 3600, 1h or 1h30m. A line without one gets the TTL of the $TTL line above it, or 300 seconds when there is none. 1, which Cloudflare writes for Auto, is 300 seconds. Coritan moves a TTL below 60 or above 86,400 seconds to the nearest of the two.

Class

IN, which is optional. A record in another class, such as CH, is skipped with an error.

Type and content

The types and formats in DNS record types, checked by the same rules as the dashboard. Write every hostname in the content in full, such as mail.example.com.. Coritan reads a hostname without its trailing dot as complete, where BIND would add the zone's domain to it. @ as a hostname is the domain itself, such as 10 @ for an MX record.

TXT values

Quotes are optional. A value in several quoted strings, such as a long DKIM key, is joined into one value, as resolvers join it, and a value without quotes keeps its words with one space between them. Inside quotes, \" is a quote, \\ a backslash and \059 the character with that number, here ;. Coritan's nameservers answer a value longer than 255 bytes in strings of 255 bytes, as DNS requires.

Comments, brackets and directives

A ; outside quotes starts a comment, which runs to the end of the line. Brackets join a record written over several lines, as the SOA record often is. $TTL sets the TTL of the lines below it, and $ORIGIN sets the name that relative names below it hang from, when that name is the domain or a name in it. A file for another domain still goes into the zone you import into. $INCLUDE and $GENERATE are skipped with an error: write their records out.

The import leaves out:

• Blank lines and comments.
• The SOA record, without an error. The zone keeps its own.
• An NS record at @ that the zone does not have, such as the last DNS host's nameservers. The zone keeps Coritan's, and the page lists each line it left out this way.
• Each record the zone already has, as Records the zone already has describes.

The import accepts a CNAME beside other records at the same name, which the dashboard refuses. A CNAME at @ is skipped with an error, unless it is proxied. A and AAAA records are DNS only unless the line is marked proxied, as Proxied records in a file describes. Turn Proxied on for any others that should go through Coritan's network (Add, edit and delete DNS records).

A line whose comment holds cf_tags=cf-proxied:true is a proxied record. Cloudflare's export writes this tag, and so does Coritan's. You can add it to a line yourself:

www  300  IN  A      203.0.113.10        ; cf_tags=cf-proxied:true
shop 300  IN  CNAME  shops.myhost.example. ; cf_tags=cf-proxied:true

• A proxied A or AAAA record is imported proxied, and the name gets a web proxy to its address, as when you turn Proxied on (Proxied records). Two proxied records at one name are both its origins. An address that cannot be an origin, such as a private one, is imported DNS only, and the page says so.
• A proxied CNAME answers with Coritan's addresses, and Coritan's network fetches the site from the CNAME's target, sending the visitor's hostname. Coritan stores it as a proxied A or AAAA record with an address of the target and the comment Proxied CNAME to shops.myhost.example, and gives the name a web proxy to the target itself, so the web proxy follows the target's own DNS. It works at @ too. When the target has no public address, the record is kept as a DNS only CNAME, or skipped with an error at @. When the name already has an A, AAAA or CNAME record, the line is left out.
• A proxied line for a wildcard name, such as * 300 IN A 203.0.113.10, is imported DNS only, because a web proxy serves one full hostname. The page says so, and the A, AAAA or CNAME record answers with its own content.
• cf-proxied:false, and every other tag, change nothing.

Cloudflare's export is a BIND zone file, and the import reads it as it is:

• The comments at the top and the end of each line are left out, and the cf_tags in them are read.
• Records with Cloudflare's Auto TTL, written as 1, get 300 seconds.
• Proxied records stay proxied, as Proxied records in a file describes.
• The SOA record and Cloudflare's NS records at @, such as chip.ns.cloudflare.com, are left out. Change the nameservers at your registrar to Coritan's (Check the nameservers).
• A DKIM key in two quoted strings becomes one TXT record that resolvers read whole.

An earlier version of the import kept Cloudflare's NS records at @. The DNS tab marks each one with This nameserver is not ours.: delete them, because resolvers that ask them get Cloudflare's answers.

The import skips a line when the zone already has the same record: the same name, type and content, the same priority for an MX record, and the same priority, weight and port for an SRV record. Case does not count, a hostname matches with or without its trailing dot, and a full name such as www.example.com. matches www. A line that repeats an earlier line of the file is skipped too.

So importing a file a second time, or importing a zone's own export, adds nothing. After a partial import, fix the lines that failed and import the whole file again: only the records the zone lacks are added.

The TTL and Proxied do not count, so a line that differs from a record only in its TTL leaves the record as it is. A line with different content adds a second record beside the first. To change a record, edit it on the DNS tab (Add, edit and delete DNS records).

1. On the domain's DNS tab, select More DNS actions, then Export zone file.
2. Your browser downloads the file, named after the domain, such as example.com.zone.

To download only some records, tick them in the table and select Export selected. The dashboard builds that file in your browser, named such as example.com.selection.zone. It holds only the records you chose, with no SOA record, and writes each hostname in content in full with its trailing dot, so BIND and other providers read it as it is.

The file starts with the zone's SOA record and lists every record, sorted by name and type:

; Zone file for example.com
$ORIGIN example.com.
$TTL 300

@    300    IN  SOA    ns1.coritan.com. hostmaster.example.com. ( 2026092501 7200 3600 1209600 300 )

@    300    IN  A      203.0.113.10 ; cf_tags=cf-proxied:true
@    86400  IN  NS     ns1.coritan.com
@    3600   IN  MX     10  mail.example.com
www  3600   IN  CNAME  example.com

• The file writes a hostname in content without its trailing dot. Coritan's import reads the file as it is, and importing it into the same zone adds nothing. Before you load it into another provider, add the dot to each hostname: BIND and most providers would read mail.example.com as mail.example.com.example.com.
• A proxied A or AAAA record is written with the address you entered and ends with ; cf_tags=cf-proxied:true, as in Cloudflare's export. Coritan's import and Cloudflare's read it as proxied, and other providers read it as a comment. Export selected marks proxied records the same way.
• A TXT value is written in quotes, in strings of up to 255 bytes each.
• Record comments are left out.

After an import, the dashboard reports how many records it added, how many the zone already had and how many lines it could not read, such as 12 records imported; 3 records already in the zone; 2 lines skipped. It leaves out a count that is zero. The page then says how many of the new records are proxied, such as 4 records are proxied through our network.. It lists the lines it left out or changed on purpose under 2 lines left out or changed, such as Line 30: left out the NS record for chip.ns.cloudflare.com at @. The zone keeps our nameservers., and each line it could not read with the reason, such as Line 4: too few fields. The result stays on the page until you select Done, which takes you back to the DNS tab. The new records appear in the table, and Coritan's nameservers answer with them straight away. After an export, the dashboard confirms Zone file for example.com downloaded.

0 records imported; 12 records already in the zone.

The zone already has every record in the file. A record keeps its own TTL when the file's differs. To change it, edit the record on the DNS tab.

2 lines skipped

The import page lists each line it could not read, with the reason, up to 50 of them. Fix those lines and import the whole file again: the records it already added are skipped.

Choose a file of 2 MB or less.

The dashboard reads a file up to 2 MB. Split a larger file, or paste it in parts.

Line 4: too few fields

A line that starts with a name needs at least its name, its type and its content, such as www A 203.0.113.10. A line that starts with a space needs its type and its content.

Line 5: the line names no owner, and no line above it does

The line starts with a space or a tab, so it belongs to the name above it, and no line above it names one. Start the line with its name.

Line 2: unsupported type NAPTR

Coritan does not host that type, and every other record in the file still imports. DNS record types lists the types Coritan hosts.

Line 2: only the IN class is hosted

The record is in another class, such as CH. Coritan hosts IN records only.

Line 1: $INCLUDE is not supported; write its records out instead

The import reads one file. Paste the records of the included file in its place. The same goes for $GENERATE.

Line 3: mail.other.net is not in the zone example.com. …

The line names a host outside the zone. Import it into the zone of its own domain, or write the name relative to this zone.

Line 3: a CNAME cannot be at @. …

A CNAME at the domain itself would hide its other records. Add the target's address as an A or AAAA record at @, or add ; cf_tags=cf-proxied:true to the line to proxy it (Proxied records in a file).

Line 9: kept DNS only. Proxied origin …

The line is marked proxied, but its address is private or reserved, so it cannot be a web proxy's origin. The record is imported DNS only.

Line 4: kept DNS only. A wildcard record cannot be proxied.

The line is marked proxied, but its name is * or has a * label. The record is imported DNS only. To proxy the site, add a proxied record for each hostname.

Line 8: kept shop.example.com as a DNS-only CNAME, because shops.myhost.example has no public address to proxy.

Coritan could not find a public address for the proxied CNAME's target, so the record answers as a plain CNAME. Check the target's DNS, then turn the record into a proxied A record on the DNS tab.

Line 8: left out the proxied CNAME for shop.example.com, because the name already has an address.

The name already has an A, AAAA or CNAME record, in the zone or earlier in the file. Delete the line, or the record, and import again.

Line 1: shops.myhost.example has no public address, so the proxied CNAME at @ could not be imported

A CNAME cannot be at @ unproxied, and Coritan found no address to proxy. Add the site's address as an A record at @ instead.

Record limit reached (1000), import truncated

A zone holds up to 1,000 records. The import added records up to the limit and stopped. Delete records the zone no longer needs, then import the file again: the records it already added are skipped.

The zone lists another host's nameservers

An earlier import kept the NS records at @ from the file, such as Cloudflare's. The DNS tab marks each one with This nameserver is not ours.. Delete them; the zone keeps at least two NS records at @.

• DNS record types
• Add, edit and delete DNS records
• Add a domain you already own

Import a zone file by sending its text as zone_file. In JSON, each line break is \n:

curl -X POST https://api.coritan.com/api/v1/dns/zones/42/import \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone_file": "@ 3600 IN A 203.0.113.10\nwww 1 IN A 198.51.100.7 ; cf_tags=cf-proxied:true\nbad line\nexample.com. 86400 IN NS chip.ns.cloudflare.com."}'

In the answer, imported counts the records added and duplicates counts the lines skipped because the zone already had the record or an earlier line added it. proxied counts the added records that are proxied. notes lists the lines left out or changed on purpose, and errors each line the import could not read. Here the zone already had the A record at @:

{
  "imported": 1,
  "duplicates": 1,
  "proxied": 1,
  "notes": ["Line 4: left out the NS record for chip.ns.cloudflare.com at @. The zone keeps our nameservers."],
  "errors": ["Line 3: too few fields"]
}

An organization imports into its zone with POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/import, which answers the same way.

Export a zone with GET /api/v1/dns/zones/42/export. The answer holds the file as one string:

{
  "zone_file": "; Zone file for example.com\n$ORIGIN example.com.\n$TTL 300\n…"
}