dnscontrol/documentation/v316.md

creds.json file format change

Feel free to skip to "How do I convert?" if you don't care about the details.

Starting in v3.16 the "provider type identifier" (PTI) will be located in creds.json instead of dnsconfig.js. The PTI is the all caps string like ROUTE53 or CLOUDFLAREAPI used to identify a provider's type.

V3.16 will enable a syntax that is backwards and forwards compatible. The old syntax will be removed in v4.0. There's no planned release date for v4.0 but it is expected to be after Dec 31, 2022.

The change was discussed in Request for Comments: Include the provider type in creds.json, remove it from dnsconfig.js where we decided "Plan A" would be selected.

What does this mean to you?

In a nutshell, NewRegistrar() and NewDnsProvider() will lose the 2nd parameter:

{% code title="dnscontrol.js" %}

var REG_GANDI = NewRegistrar(
-   "gandi",
-   "GANDI_V5"
+   "gandi"
);
var DSP_CF = NewDnsProvider(
-   "cloudflare_tal",
-   "CLOUDFLAREAPI"
+   "cloudflare_tal"
);

{% endcode %}

The second parameter (GANDI_V5 and CLOUDFLAREAPI in the above examples) has moved to creds.json instead. It will be in a TYPE field, which all providers have. It can appear in both places for backwards compatibility for now.

{% code title="creds.json" %}

{
  "gandi": {
+   "TYPE": "GANDI_V5",
    "apikey": "reacted"
  },
  "cloudflare_tal": {
+   "TYPE": "CLOUDFLAREAPI",
    "apikey": "reacted",
    "apiuser": "reacted"
  }
}

{% endcode %}

In the past, a provider didn't need an entry in creds.json if there were no credentials to be stored. Starting in v4.0 all providers must have an entry in creds.json. To aid the transition, starting in v3.16 warnings will appear on stdout that direct you to convert to the new format.

Also to help in the conversion, if no provider named "none" or "bind" exist, ones will be added for you. They look like this:

{% code title="creds.json" %}

{
  "none": { "TYPE": "NONE" },
  "bind": { "TYPE": "BIND" }
}

{% endcode %}

Command line tools

How does this affect command line tools?

The following subcommands require the PTI a parameter on the command line:

• get-zone
• get-zones
• check-creds

In 3.16, that parameter can be changed to - as a placeholder, or removed entirely if it is the last parameter on the command line. When you omit this parameter, DNSControl will find the value in creds.json instead.

In 4.0, that parameter will be removed, though a - is permitted for backwards compatibility.

In other words, if you add the TYPE field to creds.json, you no longer need to specify it on the command line. You can specify - instead, or leave it out entirely starting in v4.0.

For check-creds:

Starting in v3.16 these forms are valid:

dnscontrol check-creds myr53
dnscontrol check-creds myr53 -
dnscontrol check-creds myr53 ROUTE53

Starting in v4.0 this is the only valid form:

dnscontrol check-creds myr53

For backwards compatibility, these are valid until at least v5.0:

dnscontrol check-creds myr53 -

For get-zones/get-zone:

Starting in v3.16 these forms are valid:

dnscontrol get-zones gmain GANDI_V5 example.comn other.com
dnscontrol get-zones gmain - example.comn other.com
dnscontrol get-zones cfmain CLOUDFLAREAPI all
dnscontrol get-zones cfmain - all
dnscontrol get-zones --format=tsv bind BIND example.com
dnscontrol get-zones --format=tsv bind - example.com
dnscontrol get-zones --format=djs --out=draft.js glcoud GCLOUD example.com
dnscontrol get-zones --format=djs --out=draft.js glcoud - example.com

Starting in v4.0 these forms are valid:

dnscontrol get-zones gmain example.comn other.com
dnscontrol get-zones cfmain all
dnscontrol get-zones --format=tsv bind example.com
dnscontrol get-zones --format=djs --out=draft.js glcoud example.com

For backwards compatibility, these are valid until at least v5.0:

dnscontrol get-zones gmain - example.comn other.com
dnscontrol get-zones cfmain - all
dnscontrol get-zones --format=tsv bind - example.com
dnscontrol get-zones --format=djs --out=draft.js glcoud - example.com

How do I convert?

Step 1: Upgrade

Upgrade to v3.16 or later. If DNSControl is installed in many places, do not continue until they are all at v3.16 or later.

Step 2: Edit creds.json

Now that all uses of DNSControl are on v3.16 or later...

For each creds.json entry, add a field "TYPE" set to the provider type identifier. This is the all-caps name such as ROUTE53, GCLOUD, or CLOUDFLAREAPI.

For example, here is a new-style creds.json file with TYPE fields added:

{% code title="creds.json" %}

{
  "bind_inside": {
+   "TYPE": "BIND",
    "directory": "inzones"
  },
  "cloudflare_tal": {
+   "TYPE": "CLOUDFLAREAPI",
    "apikey": "redacted",
    "apiuser": "redacted"
  },
  "gandi": {
+   "TYPE": "GANDI_V5",
    "apikey": "redacted"
  }
}

{% endcode %}

Step 3: Cross-check

Run dnscontrol preview as one normally would. Fix any errors, warnings, or informational messages that appear on stdout.

Here are some examples:

If you see something like...

WARNING: For future compatibility, update the "namedotcom_main" entry in `creds.json` by adding: "TYPE": "NAMEDOTCOM", (See https://docs.dnscontrol.org/commands/creds-json#missing)

...it means that the TYPE field is missing from that entry in creds.json.

If you see something like...

ERROR: Mismatch found! creds.json entry "namedotcom_main" has "TYPE" set to "ROUTE53" but dnsconfig.js specifies New*("namedotcom_main", "NAMEDOTCOM") (See https://docs.dnscontrol.org/commands/creds-json#mismatch)

...it means your dnsconfig.js and creds.json specify mismatched values. Fix one or the other.

After you correct some warnings, you may receive information messages like...

INFO: In dnsconfig.js New*("namedotcom_main", "NAMEDOTCOM") can be simplified to New*("namedotcom_main") (See https://docs.dnscontrol.org/commands/creds-json#cleanup)

...which is a message that will disappear as you update dnsconfig.js in the next step.

Step 4: Edit dnsconfig.js

Remove the 2nd parameter to any NewDnsProvider() or NewRegistrar() functions.

{% code title="dnsconfig.js" %}

var REG_NAMEDOTCOM_TAL = NewRegistrar(
-   "namedotcom_tal",
-   "NAMEDOTCOM"
+   "namedotcom_tal"
);
var DNS_GANDI_TAL = NewDnsProvider(
-   "gandi_v5_tal",
-   "GANDI_V5"
+   "gandi_v5_tal"
);

{% endcode %}

Again, run dnscontrol preview to verify you setup still works as expected.

Step 5: Update any shell scripts

Any shell scripts or documentation that uses the subcommands get-zone, get-zones or check-creds should be updated. The "provider type" parameter should be changed to -. If it is the last parameter on the command, it can be removed.

It's unlikely you have scripts that use these commands. However you may have documentation that refers to them and needs to be updated.

Step 4: Test

Run dnscontrol preview as one normally would. Fix any errors, warnings, or informational messages that appear on stdout.

Step 5: Done

That's it!