github.com/teknogeek/dnscontrol/v2@v2.10.1-0.20200227202244-ae299b55ba42/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  ## Important notes
    10  
    11  * When using `SPF()` or the `SPF_BUILDER()` the records are converted to RecordType `TXT` as Cloudflare API fails otherwise. See more [here](https://github.com/StackExchange/dnscontrol/issues/446).
    12  
    13  ## Configuration
    14  In the credentials file you must provide a [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens):
    15  
    16  {% highlight json %}
    17  {
    18    "cloudflare": {
    19      "apitoken": "your-cloudflare-api-token"
    20    }
    21  }
    22  {% endhighlight %}
    23  
    24  Make sure the token has at least the right read zones and edit DNS records (i.e. `Zone → Zone → Read` and `Zone → DNS → Edit`);
    25  checkout [Cloudflare's documentation](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys) for instructions on how to generate and configure permissions on API tokens.
    26  
    27  
    28  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):
    29  
    30  {% highlight json %}
    31  {
    32    "cloudflare": {
    33      "apikey": "your-cloudflare-api-key",
    34      "apiuser": "your-cloudflare-email-address"
    35    }
    36  }
    37  {% endhighlight %}
    38  
    39  If your Cloudflare account has access to multiple Cloudflare accounts, you can specify which Cloudflare account should be used when adding new domains:
    40  
    41  {% highlight json %}
    42  {
    43    "cloudflare": {
    44      "apitoken": "...",
    45      "accountid": "your-cloudflare-account-id",
    46      "accountname": "your-cloudflare-account-name"
    47    }
    48  }
    49  {% endhighlight %}
    50  
    51  ## Metadata
    52  Record level metadata available:
    53     * `cloudflare_proxy` ("on", "off", or "full")
    54  
    55  Domain level metadata available:
    56     * `cloudflare_proxy_default` ("on", "off", or "full")
    57     * `cloudflare_universalssl` (unset to keep untouched; otherwise "on, or "off")
    58  
    59  Provider level metadata available:
    60     * `ip_conversions`
    61     * `manage_redirects`: set to `true` to manage page-rule based redirects
    62  
    63  What does on/off/full mean?
    64  
    65     * "off" disables the Cloudflare proxy
    66     * "on" enables the Cloudflare proxy (turns on the "orange cloud")
    67     * "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.
    68  
    69  Good to know: You can also set the default proxy mode using `DEFAULTS()` function, see:
    70  {% highlight js %}
    71  
    72  DEFAULTS(
    73  	CF_PROXY_DEFAULT_OFF // turn proxy off when not specified otherwise
    74  );
    75  
    76  {% endhighlight %}
    77  
    78  **Aliases:**
    79  
    80  To make configuration files more readable and less prone to errors,
    81  the following aliases are *pre-defined*:
    82  
    83  {% highlight js %}
    84  // Meta settings for individual records.
    85  var CF_PROXY_OFF = {'cloudflare_proxy': 'off'};     // Proxy disabled.
    86  var CF_PROXY_ON = {'cloudflare_proxy': 'on'};       // Proxy enabled.
    87  var CF_PROXY_FULL = {'cloudflare_proxy': 'full'};   // Proxy+Railgun enabled.
    88  // Per-domain meta settings:
    89  // Proxy default off for entire domain (the default):
    90  var CF_PROXY_DEFAULT_OFF = {'cloudflare_proxy_default': 'off'};
    91  // Proxy default on for entire domain:
    92  var CF_PROXY_DEFAULT_ON = {'cloudflare_proxy_default': 'on'};
    93  // UniversalSSL off for entire domain:
    94  var CF_UNIVERSALSSL_OFF = { cloudflare_universalssl: 'off' };
    95  // UniversalSSL on for entire domain:
    96  var CF_UNIVERSALSSL_ON = { cloudflare_universalssl: 'on' };
    97  {% endhighlight %}
    98  
    99  The following example shows how to set meta variables with and without aliases:
   100  
   101  {% highlight js %}
   102  D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE),
   103      A('www1','1.2.3.11', CF_PROXY_ON),        // turn proxy ON.
   104      A('www2','1.2.3.12', CF_PROXY_OFF),       // default is OFF, this is a no-op.
   105      A('www3','1.2.3.13', {'cloudflare_proxy': 'on'}) // why would anyone do this?
   106  );
   107  {% endhighlight %}
   108  
   109  ## Usage
   110  Example Javascript:
   111  
   112  {% highlight js %}
   113  var REG_NONE = NewRegistrar('none', 'NONE')
   114  var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI');
   115  
   116  // Example domain where the CF proxy abides by the default (off).
   117  D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE),
   118      A('proxied','1.2.3.4', CF_PROXY_ON),
   119      A('notproxied','1.2.3.5'),
   120      A('another','1.2.3.6', CF_PROXY_ON),
   121      ALIAS('@','www.example.tld.', CF_PROXY_ON),
   122      CNAME('myalias','www.example.tld.', CF_PROXY_ON)
   123  );
   124  
   125  // Example domain where the CF proxy default is set to "on":
   126  D('example2.tld', REG_NONE, DnsProvider(CLOUDFLARE),
   127      CF_PROXY_DEFAULT_ON, // Enable CF proxy for all items unless otherwise noted.
   128      A('proxied','1.2.3.4'),
   129      A('notproxied','1.2.3.5', CF_PROXY_OFF),
   130      A('another','1.2.3.6'),
   131      ALIAS('@','www.example2.tld.'),
   132      CNAME('myalias','www.example2.tld.')
   133  );
   134  {%endhighlight%}
   135  
   136  ## Activation
   137  DNSControl depends on a Cloudflare Global API Key that's available under "My Settings".
   138  
   139  ## New domains
   140  If a domain does not exist in your Cloudflare account, DNSControl
   141  will *not* automatically add it. You'll need to do that via the
   142  control panel manually or via the `dnscontrol create-domains` command.
   143  
   144  ## Redirects
   145  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:
   146  
   147  {% highlight js %}
   148  
   149  // chiphacker.com is an alias for electronics.stackexchange.com
   150  
   151  var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI', {"manage_redirects": true}); // enable manage_redirects
   152  
   153  D("chiphacker.com", REG_NONE, DnsProvider(CLOUDFLARE),
   154      // must have A records with orange cloud on. Otherwise page rule will never run.
   155      A("@","1.2.3.4", CF_PROXY_ON),
   156      A("www", "1.2.3.4", CF_PROXY_ON)
   157      A("meta", "1.2.3.4", CF_PROXY_ON),
   158  
   159      // 302 for meta subdomain
   160      CF_TEMP_REDIRECT("meta.chiphacker.com/*", "https://electronics.meta.stackexchange.com/$1"),
   161  
   162      // 301 all subdomains and preserve path
   163      CF_REDIRECT("*chiphacker.com/*", "https://electronics.stackexchange.com/$2"),
   164  );
   165  {%endhighlight%}
   166  
   167  Notice a few details:
   168  
   169  1. We need an A record with cloudflare proxy on, or the page rule will never run.
   170  2. The IP address in those A records may be mostly irrelevant, as cloudflare should handle all requests (assuming some page rule matches).
   171  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.