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](https://github.com/StackExchange/dnscontrol/issues/1457) 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" %}
```diff
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" %}
```diff
{
  "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" %}
```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:

```shell
dnscontrol check-creds myr53
dnscontrol check-creds myr53 -
dnscontrol check-creds myr53 ROUTE53
```

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

```shell
dnscontrol check-creds myr53
```

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

```shell
dnscontrol check-creds myr53 -
```

For get-zones/get-zone:

Starting in v3.16 these forms are valid:

```shell
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:

```shell
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:

```shell
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" %}
```diff
{
  "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...

```text
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...

```text
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...

```text
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" %}
```diff
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!