Cloudflare Provider

Important notes

Configuration

In the credentials file you must provide a Cloudflare API token:

{
  "cloudflare": {
    "apitoken": "your-cloudflare-api-token"
  }
}

Make sure the token has at least the right read zones and edit DNS records (i.e. Zone → Zone → Read and Zone → DNS → Edit); checkout Cloudflare’s documentation for instructions on how to generate and configure permissions on API tokens.

Or you can provide your Cloudflare API username and access key instead (but it isn’t recommended because those credentials give DNSControl access to the complete Cloudflare API):

{
  "cloudflare": {
    "apikey": "your-cloudflare-api-key",
    "apiuser": "your-cloudflare-email-address"
  }
}

If your Cloudflare account has access to multiple Cloudflare accounts, you can specify which Cloudflare account should be used when adding new domains:

{
  "cloudflare": {
    "apitoken": "...",
    "accountid": "your-cloudflare-account-id",
    "accountname": "your-cloudflare-account-name"
  }
}

Metadata

Record level metadata available:

Domain level metadata available:

Provider level metadata available:

What does on/off/full mean?

Good to know: You can also set the default proxy mode using DEFAULTS() function, see:

DEFAULTS(
	CF_PROXY_DEFAULT_OFF // turn proxy off when not specified otherwise
);

Aliases:

To make configuration files more readable and less prone to errors, the following aliases are pre-defined:

// Meta settings for individual records.
var CF_PROXY_OFF = {'cloudflare_proxy': 'off'};     // Proxy disabled.
var CF_PROXY_ON = {'cloudflare_proxy': 'on'};       // Proxy enabled.
var CF_PROXY_FULL = {'cloudflare_proxy': 'full'};   // Proxy+Railgun enabled.
// Per-domain meta settings:
// Proxy default off for entire domain (the default):
var CF_PROXY_DEFAULT_OFF = {'cloudflare_proxy_default': 'off'};
// Proxy default on for entire domain:
var CF_PROXY_DEFAULT_ON = {'cloudflare_proxy_default': 'on'};
// UniversalSSL off for entire domain:
var CF_UNIVERSALSSL_OFF = { cloudflare_universalssl: 'off' };
// UniversalSSL on for entire domain:
var CF_UNIVERSALSSL_ON = { cloudflare_universalssl: 'on' };

The following example shows how to set meta variables with and without aliases:

D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE),
    A('www1','1.2.3.11', CF_PROXY_ON),        // turn proxy ON.
    A('www2','1.2.3.12', CF_PROXY_OFF),       // default is OFF, this is a no-op.
    A('www3','1.2.3.13', {'cloudflare_proxy': 'on'}) // why would anyone do this?
);

Usage

Example Javascript:

var REG_NONE = NewRegistrar('none', 'NONE')
var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI');

// Example domain where the CF proxy abides by the default (off).
D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE),
    A('proxied','1.2.3.4', CF_PROXY_ON),
    A('notproxied','1.2.3.5'),
    A('another','1.2.3.6', CF_PROXY_ON),
    ALIAS('@','www.example.tld.', CF_PROXY_ON),
    CNAME('myalias','www.example.tld.', CF_PROXY_ON)
);

// Example domain where the CF proxy default is set to "on":
D('example2.tld', REG_NONE, DnsProvider(CLOUDFLARE),
    CF_PROXY_DEFAULT_ON, // Enable CF proxy for all items unless otherwise noted.
    A('proxied','1.2.3.4'),
    A('notproxied','1.2.3.5', CF_PROXY_OFF),
    A('another','1.2.3.6'),
    ALIAS('@','www.example2.tld.'),
    CNAME('myalias','www.example2.tld.')
);

Activation

DNSControl depends on a Cloudflare Global API Key that’s available under “My Settings”.

New domains

If a domain does not exist in your Cloudflare account, DNSControl will not automatically add it. You’ll need to do that via the control panel manually or via the dnscontrol create-domains command.

Redirects

The Cloudflare provider can manage Page-Rule based redirects for your domains. Simply use the CF_REDIRECT and CF_TEMP_REDIRECT functions to make redirects:

// chiphacker.com is an alias for electronics.stackexchange.com

var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI', {"manage_redirects": true}); // enable manage_redirects

D("chiphacker.com", REG_NONE, DnsProvider(CLOUDFLARE),
    // must have A records with orange cloud on. Otherwise page rule will never run.
    A("@","1.2.3.4", CF_PROXY_ON),
    A("www", "1.2.3.4", CF_PROXY_ON)
    A("meta", "1.2.3.4", CF_PROXY_ON),

    // 302 for meta subdomain
    CF_TEMP_REDIRECT("meta.chiphacker.com/*", "https://electronics.meta.stackexchange.com/$1"),

    // 301 all subdomains and preserve path
    CF_REDIRECT("*chiphacker.com/*", "https://electronics.stackexchange.com/$2"),
);

Notice a few details:

  1. We need an A record with cloudflare proxy on, or the page rule will never run.
  2. The IP address in those A records may be mostly irrelevant, as cloudflare should handle all requests (assuming some page rule matches).
  3. Ordering matters for priority. CF_REDIRECT records will be added in the order they appear in your js. So put catch-alls at the bottom.