# Connect Cloudflare DNS

RedundantDNS talks to Cloudflare with an **API token**. The token is
encrypted with your organization's key as soon as it reaches us, is never
shown again, and is only used to read and write the DNS zones you attach.

Pick the access level that matches how much you want to delegate:

| Access level | What RedundantDNS can do |
|---|---|
| **Create and manage zones** | Add zones to one Cloudflare account, write their records, and delete a zone when you detach it (only after you type the zone name). |
| **Manage an existing zone** | Read and edit the records of one zone that you added. It never creates or deletes zones. |
| **Mirror source (read-only)** | Only read the records of one zone that you added and keep editing yourself. RedundantDNS mirrors it to your other providers and never writes to it, not even a setting. |

## Read this first: how Cloudflare fits a multi-provider zone

Cloudflare works as one of the providers of a RedundantDNS zone. Four
things differ from the others:

- **Multi-provider DNS.** By default Cloudflare only answers with its own
  two nameservers at the zone apex and expects the registrar to delegate to
  Cloudflare alone. Its
  [Multi-provider DNS setting](https://developers.cloudflare.com/dns/nameservers/nameserver-options/)
  makes Cloudflare honour NS records added at the apex and activate the
  zone even when the registrar also lists other providers. RedundantDNS
  turns the setting on for you: when it creates a zone, when it adopts an
  existing one and again before it writes the apex NS set. The apex NS set
  on Cloudflare then lists every provider of the zone, like on the others.
  Cloudflare accepts *DNS · Edit* or *DNS Settings · Edit* for this
  setting ([Update DNS Settings](https://developers.cloudflare.com/api/resources/dns/subresources/settings/subresources/zone/methods/edit/));
  a token without either still syncs every other record and the
  attachment shows the error. Removing RedundantDNS leaves the setting on.
- **Zone status.** A zone whose registrar does not list Cloudflare's
  nameservers yet stays **pending** (Cloudflare still serves it). If
  Cloudflare ever marks the zone **moved**, re-check the nameservers in the
  Cloudflare dashboard (Overview → Re-check now). The dashboard shows the
  zone status on the attachment.
- **Proxy is always off.** RedundantDNS writes every record with *Proxy
  status: DNS only*, so all providers answer the same addresses; the
  platform's contract is DNS-only. If you turn the orange cloud on for a
  record in Cloudflare, Cloudflare answers with its own edge addresses and
  your providers disagree. The drift check sees it: a proxied record is
  reported as drift whatever its TTL and values (the attachment's
  `lastDiff.reasons` names it, for example `{"www CNAME": ["proxied"]}`,
  and the drift alert says "proxied at the provider"), a reconcile writes
  it again with the proxy off, and the probes of the Cloudflare
  nameservers report a mismatch on that set while it is proxied (they
  compare the addresses served with the canonical values). An adopt takes
  the record's DNS-only value (its origin), never the proxy. A mirror
  source is never written: a record proxied there is mirrored to your
  other providers with its origin value, and Cloudflare keeps answering
  its edge addresses until you turn the proxy off.
- **Cloudflare adds CAA records.** When a zone holds any CAA record at a
  name, Cloudflare also answers there with CAA records for the certificate
  authorities of its Universal SSL (`issue` and `issuewild` for
  `comodoca.com`, `digicert.com`, `letsencrypt.org`, `pki.goog`,
  `ssl.com`, some with `cansignhttpexchanges=yes`; Cloudflare also lists
  `sectigo.com`), which the API does not list. Cloudflare's answer is then
  wider than your record set and than the other providers' answers. The
  probes of the Cloudflare nameservers accept it: when every value of your
  set is served and the extra values are only `issue`/`issuewild` for
  those CAs, the set matches and the probe result carries a note
  (`notes`); any other extra value, or one of your values missing, is a
  mismatch. Keep in mind the policy effect: through Cloudflare, those CAs
  may issue for the name (wildcards included) even when your set allows
  one CA only (the provider capability `caaAdditions` lists them).
- **CNAME at the apex is flattened.** Cloudflare accepts a CNAME at the
  apex but never serves it as a CNAME: it answers every query at the apex
  (A, AAAA, TXT, MX...) with the target's own records, and NXDOMAIN when
  the target does not exist. Only a zone whose providers all allow it
  accepts an apex CNAME (today, Cloudflare alone).
- **Cloudflare Registrar** cannot use other nameservers at all: see
  [below](#cloudflare-registrar).
- **Subdomain zones need Cloudflare Enterprise.** Cloudflare adds a
  subdomain (`api.example.com`) as a zone of its own only on the Enterprise
  plan ([subdomain setup](https://developers.cloudflare.com/dns/zone-setups/subdomain-setup/)).
  On the other plans, attach Cloudflare to registrable domains
  (`example.com`) and serve subdomain zones with the other providers;
  Cloudflare can still hold the parent zone and the child's delegation.

TTLs on Cloudflare go from 60 seconds to one day (86,400 seconds); a zone
attached to Cloudflare accepts only TTLs in that range. A record set to
*Automatic* in Cloudflare (TTL 1) reads as 300 seconds.

**MX and SRV priorities before v0.1.8.** Up to v0.1.7 the Cloudflare
adapter read every MX and SRV priority as 0 (the Cloudflare SDK dropped
them when it decoded the API answer). Each reconcile rewrote those sets and
a verify reported them as drift, and an **adopt** or a **mirror** from
Cloudflare wrote priority 0 into the canonical zone, which then reached the
other providers. v0.1.8 reads the priorities (and every SRV and CAA field)
from the API answer itself. `rdns doctor` warns about zones attached to
Cloudflare whose MX and SRV priorities are all 0 (finding
`cloudflare_priority_zero`, a warning: it is never repaired automatically,
since priority 0 may be intended); check those sets and fix the priorities
with a record edit (a mirrored zone picks them up at the next mirror read).

## 1. Find your account ID

In the Cloudflare dashboard open **Account home**; the **account ID** is in
the account's menu (**⋯ → Copy account ID**), or on any zone's **Overview**
page, bottom right.

## 2a. Create and manage zones

**My Profile → API Tokens → Create Token → Create Custom Token**:


| Permission | Access |
|---|---|
| Zone · Zone | Edit |
| Zone · DNS | Edit |
| Zone · DNS Settings | Edit |


**Account resources**: *Include · your account*. **Zone resources**:
*Include · All zones from an account · your account*. Create the token and
copy it (it is shown once).

In RedundantDNS, **Providers → Add connection**: provider *Cloudflare*,
access level *Create and manage zones*, paste the **API token** and the
**account ID**, then click **Test and save**. We check the token by
listing the account's zones. That check does not create anything, so a
token without permission to add zones is accepted here and only fails at
the first attach, with `422 providerRejected` and Cloudflare's message
(`Requires permission "com.cloudflare.api.account.zone.create" to create
zones for the selected account`): fix the token's permissions and attach
again. An account-owned token (**Manage Account → Account API Tokens**)
works the same way as a user token.

## 2b. Manage an existing zone

Create a custom token restricted to the one zone:


| Permission | Access |
|---|---|
| Zone · Zone | Read |
| Zone · DNS | Edit |
| Zone · DNS Settings | Edit |

**Zone resources**: *Include · Specific zone · your zone*. *Zone · Read*
lets RedundantDNS check the zone name and read its nameservers and status;
*DNS · Edit* lets it edit the records; *DNS Settings · Edit* lets it turn on
Multi-provider DNS. The token cannot add or delete zones.

Add the connection with access level *Manage an existing zone* (the account
ID can stay empty). The token is checked when you attach the connection to
a zone: open the zone, **Providers → Attach**, pick the connection and
paste the **zone ID** (the zone's **Overview** page, bottom right; the
zone name is not accepted: `422 providerZoneNotFound`). We verify that the
zone holds the same domain and that the token can read its records, turn
on Multi-provider DNS, and compare the zone with RedundantDNS without
writing anything: an empty zone is in sync at once. A Cloudflare zone
that already holds records is never wiped: into an empty zone in
RedundantDNS its records are imported, and records that exist only at
Cloudflare make the dashboard ask you to import them or overwrite them
(see "Adopting an existing zone" in the providers overview); other
differences show until you adopt or reconcile them. A
wrong token is only refused here (`422 providerRejected`, e.g.
`cloudflare: 6003: Invalid request headers`), and a zone id the token
cannot see answers `422 providerRejected` with `9109: Invalid zone
identifier`.

## 2c. Mirror source (read-only)

Use this when the zone stays edited in Cloudflare and RedundantDNS only
copies it to your other providers. RedundantDNS reads the zone and **never
writes to it**: no record, no setting (Multi-provider DNS is not turned
on). Create a custom token restricted to the one zone:


| Permission | Access |
|---|---|
| Zone · Zone | Read |
| Zone · DNS | Read |

**Zone resources**: *Include · Specific zone · your zone*. In RedundantDNS,
**Zones → New zone → Mirror an existing zone**: pick *Cloudflare*, paste
the token and the **zone ID**. RedundantDNS checks that it can read the
zone and its records, creates the zone as its mirror and copies every
record. The NS plan starts as the zone's own apex NS set (the NS records
Cloudflare lists at the apex, else its two nameservers), so nothing needs
to change at your registrar.

## What RedundantDNS writes

- Every record set you manage in the dashboard. Cloudflare stores single
  records; RedundantDNS replaces a record set by deleting its records and
  adding the new ones in the same batch request (at most 200 operations per
  request).
- The apex NS set: one NS record per nameserver of the **other** providers
  of the zone. Cloudflare's own nameservers are not records; Cloudflare
  serves them itself.
- The zone's **Multi-provider DNS** setting (turned on, never off).
- Nothing in the SOA.

## Cloudflare Registrar

Domains registered at **Cloudflare Registrar** must use Cloudflare's
nameservers: the registrar does not accept any other nameserver
([Cloudflare Registrar FAQ](https://developers.cloudflare.com/registrar/faq/)).
The domain's delegation can therefore never list the other providers of
the zone, and RedundantDNS cannot give that apex a second provider. The
delegation check detects it: it reads the delegation from the parent zone's
servers (the TLD's, not a resolver, which would answer the apex NS set that
RedundantDNS writes at Cloudflare with every provider), looks the domain up
in RDAP, and when the registrar is Cloudflare and the parent does not
delegate to the whole plan, the zone's **Delegation** tab explains it. You have three options:

1. **Transfer the registration** to another registrar, then set the
   nameservers RedundantDNS shows you. A domain cannot be transferred in its
   first 60 days after registration or after a previous transfer (an ICANN
   rule). Cloudflare explains the steps in
   [Transfer your domain out of Cloudflare](https://developers.cloudflare.com/registrar/account-options/transfer-out-from-cloudflare/).
2. **Use subdomain redundancy.** Keep the apex on Cloudflare and create the
   names that matter as their own zones in RedundantDNS, for example
   `api.example.com`. When the parent zone `example.com` is also in
   RedundantDNS (Cloudflare attached with either access level), the
   platform writes the child's NS delegation into it and keeps it up to
   date, so `api.example.com` is served by several providers even though
   `example.com` is not. The child zone is served by the other providers:
   Cloudflare can serve a subdomain zone only on its Enterprise plan.
3. **Keep Cloudflare as one provider** of the zone and accept that the apex
   stays delegated to Cloudflare only. The other providers still hold a
   synchronized copy you can switch to after a transfer.

## Revoking access

Roll or delete the API token at any time. Then remove the connection in
**Providers**; zones keep being served by Cloudflare exactly as they are.
