# Import or export a zone file

Move a domain's records in from another DNS host with a zone file, or take a zone's records out as one.

Replace _zone-id_ with the id of your hosted zone. A zone file is the RFC 1035 master-file text
most DNS hosts export. If your current host cannot export one, its record list holds the same
information; write it in the format the export below produces.

## Prerequisites

- To import, permission for `dns:ImportZone` on the zone. Without it, the console shows **Import
  zone file** as unavailable, with the note "Importing a zone file needs dns:ImportZone on this
  zone. Ask an administrator."
- To export, permission for `dns:ListRecords` on the zone.
- In the console, also `dns:ListZones` to open **Hosted zones** (without it the page shows an
  access-denied notice) and `dns:GetZone` to open the zone (without it the zone's page is not
  found).
- Room in the zone's **Record sets per zone** quota for the sets the file adds (see
  [Quotas](quotas.md)).

## What an import takes

```
$ORIGIN example.com.
$TTL 3600
@       IN  A      192.0.2.10
www     IN  CNAME  example.com.
@       IN  MX     10 mail.example.com.
@       IN  TXT    "v=spf1 -all"
```

- Lines with the same name and type become one record set. Each set replaces the set with the same
  name and type in the zone, and the replaced set loses its health check and routing; every other
  set of the zone stays as it is.
- A file is at most 1,000,000 characters.
- `$ORIGIN` and `$TTL` are read. A record without its own TTL gets the last `$TTL`, or 300 before
  the first one.
- **Skipped** and reported: `SOA` lines, `NS` lines at the apex, and other `$` directives.
- **Errors**: a record type other than `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV` and `CAA`
  (an `ALIAS` cannot be imported), a name outside the zone, an invalid name or value, and a `CNAME`
  next to other records at its name in the file. One error imports nothing.

## Import a zone file

**Console**
1. Open the zone. On the **Records** tab, choose **Import zone file**.
2. For **Zone file**, paste the file.
3. Choose **Import**.

The dialog reports "_n_ record sets imported." and lists the skipped lines; an error appears in the
dialog instead. If you close the dialog before importing, the pasted file is kept for the next time
you open it.

**CLI**
```sh
dcloud dns zones import zone-id --zone-file "$(cat example.com.zone)"
```

**API**
```http
POST /dns/api/zones/zone-id/import
{ "zoneFile": "$ORIGIN example.com.\n@ 3600 IN A 192.0.2.10\nwww 3600 IN CNAME example.com.\n" }
```

The answer is `200` with `imported`, the number of record sets written, and `skipped`, one line per
skipped line with the reason.

### When the import is refused

Nothing is written on a refusal.

- `400` "Nothing imported: line 4: unsupported record type "PTR"; …", naming up to five errors and
  how many more there are.
- `400` "Nothing imported: www.example.com has a CNAME next to other records".
- `409` "Nothing imported: A zone holds at most … record sets; this one has … and the change would
  add …" when the new sets do not fit in the quota.

## Export a zone

**Console:** not available. The console has no export of the zone file; its record table has an export of the rows.

**CLI**
```sh
dcloud dns zones export zone-id
```

**API**
```http
GET /dns/api/zones/zone-id/export
```

The answer is `{ zoneFile }`: a `$ORIGIN` line, `$TTL 300`, and one line per value with the set's
own TTL. An `ALIAS` set is written as a comment, `; www ALIAS (platform record, not exported)`,
because no other DNS host can serve it. Health checks and routing are not in the file: a routed set
is exported with its own values only.

## Related

- [Delegate a domain](delegate-a-domain.md)
- [Record sets](record-sets.md)
- `dns.zones.import` · `dns.zones.export` · `dcloud dns zones import`
