github.com/philhug/dnscontrol@v0.2.4-0.20180625181521-921fa9849001/docs/_providers/cloudflare.md (about) 1 --- 2 name: Cloudflare 3 title: Cloudflare Provider 4 layout: default 5 jsId: CLOUDFLAREAPI 6 --- 7 # Cloudflare Provider 8 9 ## Configuration 10 In the credentials file you must provide your Cloudflare API username and access token: 11 12 {% highlight json %} 13 { 14 "cloudflare": { 15 "apikey": "your-cloudflare-api-key", 16 "apiuser": "your-cloudflare-email-address" 17 } 18 } 19 {% endhighlight %} 20 21 ## Metadata 22 Record level metadata availible: 23 * `cloudflare_proxy` ("on", "off", or "full") 24 25 Domain level metadata availible: 26 * `cloudflare_proxy_default` ("on", "off", or "full") 27 28 Provider level metadata availible: 29 * `ip_conversions` 30 * `manage_redirects`: set to `true` to manage page-rule based redirects 31 32 What does on/off/full mean? 33 34 * "off" disables the Cloudflare proxy 35 * "on" enables the Cloudflare proxy (turns on the "orange cloud") 36 * "full" is the same as "on" but also enables Railgun. DNSControl will prevent you from accidentally enabling "full" on a CNAME that points to an A record that is set to "off", as this is generally not desired. 37 38 **Aliases:** 39 40 To make configuration files more readable and less prone to errors, 41 the following aliases are pre-defined: 42 43 {% highlight js %} 44 // Meta settings for individual records. 45 var CF_PROXY_OFF = {'cloudflare_proxy': 'off'}; // Proxy disabled. 46 var CF_PROXY_ON = {'cloudflare_proxy': 'on'}; // Proxy enabled. 47 var CF_PROXY_FULL = {'cloudflare_proxy': 'full'}; // Proxy+Railgun enabled. 48 // Per-domain meta settings: 49 // Proxy default off for entire domain (the default): 50 var CF_PROXY_DEFAULT_OFF = {'cloudflare_proxy_default': 'off'}; 51 // Proxy default on for entire domain: 52 var CF_PROXY_DEFAULT_ON = {'cloudflare_proxy_default': 'on'}; 53 {% endhighlight %} 54 55 The following example shows how to set meta variables with and without aliases: 56 57 {% highlight js %} 58 D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE), 59 A('www1','1.2.3.11', CF_PROXY_ON), // turn proxy ON. 60 A('www2','1.2.3.12', CF_PROXY_OFF), // default is OFF, this is a no-op. 61 A('www3','1.2.3.13', {'cloudflare_proxy': 'on'}) // why would anyone do this? 62 ); 63 {% endhighlight %} 64 65 ## Usage 66 Example Javascript: 67 68 {% highlight js %} 69 var REG_NONE = NewRegistrar('none', 'NONE') 70 var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI'); 71 72 // Example domain where the CF proxy abides by the default (off). 73 D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE), 74 A('proxied','1.2.3.4', CF_PROXY_ON), 75 A('notproxied','1.2.3.5'), 76 A('another','1.2.3.6', CF_PROXY_ON), 77 ALIAS('@','www.example.tld.', CF_PROXY_ON), 78 CNAME('myalias','www.example.tld.', CF_PROXY_ON) 79 ); 80 81 // Example domain where the CF proxy default is set to "on": 82 D('example2.tld', REG_NONE, DnsProvider(CLOUDFLARE), 83 CF_PROXY_DEFAULT_ON, // Enable CF proxy for all items unless otherwise noted. 84 A('proxied','1.2.3.4'), 85 A('notproxied','1.2.3.5', CF_PROXY_OFF), 86 A('another','1.2.3.6'), 87 ALIAS('@','www.example2.tld.'), 88 CNAME('myalias','www.example2.tld.') 89 ); 90 {%endhighlight%} 91 92 ## Activation 93 DNSControl depends on a Cloudflare Global API Key that's available under "My Settings". 94 95 ## New domains 96 If a domain does not exist in your CloudFlare account, DNSControl 97 will *not* automatically add it. You'll need to do that via the 98 control panel manually or via the `dnscontrol create-domains` command. 99 100 ## Redirects 101 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: 102 103 {% highlight js %} 104 105 // chiphacker.com is an alias for electronics.stackexchange.com 106 107 var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI', {"manage_redirects": true}); // enable manage_redirects 108 109 D("chiphacker.com", REG_NONE, DnsProvider(CLOUDFLARE), 110 // must have A records with orange cloud on. Otherwise page rule will never run. 111 A("@","1.2.3.4", CF_PROXY_ON), 112 A("www", "1.2.3.4", CF_PROXY_ON) 113 A("meta", "1.2.3.4", CF_PROXY_ON), 114 115 // 302 for meta subdomain 116 CF_TEMP_REDIRECT("meta.chiphacker.com/*", "https://electronics.meta.stackexchange.com/$1"), 117 118 // 301 all subdomains and preserve path 119 CF_REDIRECT("*chiphacker.com/*", "https://electronics.stackexchange.com/$2"), 120 ); 121 {%endhighlight%} 122 123 Notice a few details: 124 125 1. We need an A record with cloudflare proxy on, or the page rule will never run. 126 2. The IP address in those A records may be mostly irrelevant, as cloudflare should handle all requests (assuming some page rule matches). 127 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.