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.