mirror/stackexchange-dnscontrol
1
0
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2024-05-11 05:55:12 +00:00
Code Issues Releases Activity

NEW FEATURE: Moving provider TYPE from dnsconfig.js to creds.json (#1500)

Browse Source 
Fixes https://github.com/StackExchange/dnscontrol/issues/1457

* New-style creds.json implememented backwards compatible

* Update tests

* Update docs

* Assume new-style TYPE
This commit is contained in:
Tom Limoncelli
2022-05-08 14:23:45 -04:00
committed by GitHub
parent bbecce74bd
commit 9e6d642e35
23 changed files with 949 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/_functions/global/D.md
View File

@@ -19,8 +19,8 @@ Modifier arguments are processed according to type as follows:
{% capture example %}
```js
var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
var r53 = NewDnsProvider("R53","ROUTE53");
var REGISTRAR = NewRegistrar("name.com");
var r53 = NewDnsProvider("R53");
// simple domain
D("example.com", REGISTRAR, DnsProvider(r53),
@@ -60,9 +60,9 @@ To differentiate the different domains, specify the domains as
{% capture example %}
```js
var REG = NewRegistrar("Third-Party", "NONE");
var DNS_INSIDE = NewDnsProvider("Cloudflare", "CLOUDFLAREAPI");
var DNS_OUTSIDE = NewDnsProvider("bind", "BIND");
var REG = NewRegistrar("Third-Party");
var DNS_INSIDE = NewDnsProvider("Cloudflare");
var DNS_OUTSIDE = NewDnsProvider("bind");
D("example.com!inside", REG, DnsProvider(DNS_INSIDE),
A("www", "10.10.10.10")

2
docs/_functions/global/DEFAULTS.md
View File

@@ -9,7 +9,7 @@ arguments passed as if they were the first modifiers in the argument list.
{% capture example %}
```js
var COMMON = NewDnsProvider("foo","BIND");
var COMMON = NewDnsProvider("foo");
// we want to create backup zone files for all domains, but not actually register them.
// also create a default TTL
DEFAULTS( DnsProvider(COMMON,0), DefaultTTL(1000));

4
docs/_functions/global/FETCH.md
View File

@@ -20,8 +20,8 @@ Otherwise the syntax of `FETCH` is the same as `fetch`.
{% capture example %}
```js
var REG_NONE = NewRegistrar('none', 'NONE');
var DNS_BIND = NewDnsProvider('bind', 'BIND');
var REG_NONE = NewRegistrar('none');
var DNS_BIND = NewDnsProvider('bind');
D('example.com', REG_NONE, DnsProvider(DNS_BIND), [
A('@', '1.2.3.4'),

36
docs/_functions/global/NewDnsProvider.md
View File

@@ -7,20 +7,36 @@ parameters:
return: string
---
NewDnsProvider registers a new DNS Service Provider. The name can be any string value you would like to use.
The type must match a valid dns provider type identifier (see [provider page.]({{site.github.url}}/provider-list))
NewDnsProvider activates a DNS Service Provider (DSP) specified in creds.json.
A DSP stores a DNS zone's records and provides DNS service for the zone (i.e.
answers on port 53 to queries related to the zone).
Metadata is an optional object, that will only be used by certain providers. See [individual provider docs]({{site.github.url}}/provider-list) for specific details.
* `name` must match the name of an entry in `creds.json`.
* `type` specifies a valid DNS provider type identifier listed on the [provider page.]({{site.github.url}}/provider-list).
* Starting with v3.16, the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields).
* Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare.
* `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs]({{site.github.url}}/provider-list) for details.
This function will return the name as a string so that you may assign it to a variable to use inside [D](#D) directives.
This function will return an opaque string that should be assigned to a variable name for use in [D](#D) directives.
Prior to v3.16:
{% capture example %}
```js
var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
var R53 = NewDnsProvider("r53", "ROUTE53");
var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM");
var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53");
D("example.com", REGISTRAR, DnsProvider(R53), A("@","1.2.3.4"));
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
```
{% endcapture %}
{% include example.html content=example %}
In v3.16 and later:
```js
var REG_MYNDC = NewRegistrar("mynamedotcom");
var DNS_MYAWS = NewDnsProvider("myaws");
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
```

36
docs/_functions/global/NewRegistrar.md
View File

@@ -7,20 +7,36 @@ parameters:
return: string
---
NewRegistrar registers a registrar provider. The name can be any string value you would like to use.
The type must match a valid registrar provider type identifier (see [provider page.]({{site.github.url}}/provider-list))
NewRegistrar activates a Registrar Provider specified in `creds.json`.
A registrar maintains the domain's registration and delegation (i.e. the
nameservers for the domain). DNSControl only manages the delegation.
Metadata is an optional object, that will only be used by certain providers. See [individual provider docs]({{site.github.url}}/provider-list) for specific details.
* `name` must match the name of an entry in `creds.json`.
* `type` specifies a valid DNS provider type identifier listed on the [provider page.]({{site.github.url}}/provider-list).
* Starting with v3.16, the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields).
* Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare.
* `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs]({{site.github.url}}/provider-list) for details.
This function will return the name as a string so that you may assign it to a variable to use inside [D](#D) directives.
This function will return an opaque string that should be assigned to a variable name for use in [D](#D) directives.
Prior to v3.16:
{% capture example %}
```js
var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
var r53 = NewDnsProvider("R53","ROUTE53");
var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM");
var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53");
D("example.com", REGISTRAR, DnsProvider(r53), A("@","1.2.3.4"));
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
```
{% endcapture %}
{% include example.html content=example %}
In v3.16 and later:
```js
var REG_MYNDC = NewRegistrar("mynamedotcom");
var DNS_MYAWS = NewDnsProvider("myaws");
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
```

2
docs/assets/creds.json-example.txt
View File

@@ -1,7 +1,9 @@
{
"bind": {
"TYPE": "BIND"
},
"r53_ACCOUNTNAME": {
"TYPE": "ROUTE53",
"KeyId": "change_to_your_keyid",
"SecretKey": "change_to_your_secretkey",
"Token": "optional_sts_token"

4
docs/assets/dnsconfig.js-example.txt
View File

@@ -4,8 +4,8 @@
// Providers:
var REG_NONE = NewRegistrar('none', 'NONE'); // No registrar.
var DNS_BIND = NewDnsProvider('bind', 'BIND'); // ISC BIND.
var REG_NONE = NewRegistrar('none'); // No registrar.
var DNS_BIND = NewDnsProvider('bind'); // ISC BIND.
// Domains:

18
docs/check-creds.md
View File

@@ -8,8 +8,7 @@ title: Check-Creds subcommand
This is a stand-alone utility to help verify entries in `creds.json`.
The command does a trivia operation to verify credentials. If
successful, a list of zones will be output. If not, hopefully you see
verbose error messages.
successful, a list of zones will be output (which may be an empty list). If the credentials or other problems prevent this operation from executing, the exit code will be non-zero and hopefully verbose error messages will be output.
Syntax:
@@ -22,14 +21,23 @@ ARGUMENTS:
credkey: The name used in creds.json (first parameter to NewDnsProvider() in dnsconfig.js)
provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
Starting in v3.16, "provider" is optional. If it is omitted (or the placeholder value `-` is used), the `TYPE` specified in `creds.json` will be used instead. A warning will be displayed with advice on how to remain compatible with v4.0.
Starting in v4.0, the "provider" argument is expected to go away.
EXAMPLES:
dnscontrol check-creds myr53 ROUTE53
Starting in v3.16:
dnscontrol check-creds myr53
dnscontrol check-creds myr53 -
dnscontrol check-creds myr53 ROUTE53
Starting in v4.0:
dnscontrol check-creds myr53
This command is the same as:
dnscontrol get-zones --out=/dev/null myr53 ROUTE53
This command is the same as `get-zones` with `--format=nameonly`
# Developer Note
This command is not implemented for all providers.
To add this to a provider, implement the get-zones subcommand
To add this to a provider, implement the get-zones subcommand.

132
docs/creds-json.md
View File

@@ -13,14 +13,17 @@ Here's a sample file:
```json
{
"cloudflare_tal": {
"TYPE": "CLOUDFLAREAPI",
"apikey": "REDACTED",
"apiuser": "REDACTED"
},
"inside": {
"TYPE": "BIND",
"directory": "inzones",
"filenameformat": "db_%T%?_%D"
},
"hexonet": {
"TYPE": "HEXONET",
"apilogin": "$HEXONET_APILOGIN",
"apipassword": "$HEXONET_APIPASSWORD",
"debugmode": "$HEXONET_DEBUGMODE",
@@ -29,7 +32,7 @@ Here's a sample file:
}
```
# Format
## Format
* Primary keys: (e.g. `cloudflare_tal`, `inside`, `hexonet`)
* ...refer to the first parameter in the `NewRegistrar()` or `NewDnsProvider()` functions in a dnsconfig.js file.
@@ -43,7 +46,130 @@ Here's a sample file:
* ...may include any JSON string value including the empty string.
* If a subkey starts with `$`, it is taken as an env variable. In the above example, `$HEXONET_APILOGIN` would be replaced by the value of the environment variable `HEXONET_APILOGIN` or the empty string if no such environment variable exists.
# Using a different name
## New in v3.16:
The special subkey "TYPE" is used to indicate the provider type (NONE,
CLOUDFLAREAPI, GCLOUD, etc).
Prior to v3.16, the provider type is specified as the second argument
to `NewRegistrar()` and `NewDnsProvider()` in `dnsconfig.js` or as a
command-line argument in tools such as `dnscontrol get-zones`.
Starting in v3.16, `NewRegistrar()`, and `NewDnsProvider()` no longer
require the provider type to be specified. It may be specified for
backwards compatibility, but a warning will be generated with a
suggestion of how to upgrade to the 4.0 format. Likewise,
command-line tools no longer require the provider type to be
specified, but for backwards compatibility one may specify `-` since
the parameter is positional.
In 4.0, DNSControl will require the "TYPE" subkey in each `creds.json`
entry. Command line tools will have a backwards-incompatible change to
remove the provider-type as a positional argument. Prior to 4.0, the
various commands will output warnings and suggestions to avoid
compatibility issues during the transition.
## Error messages
### Missing
Message: `WARNING: For future compatibility, add this entry creds.json:...`
Message: `WARNING: For future compatibility, update the ... entry in creds.json by adding:...`
These messages indicates that this provider is not mentioned in `creds.json`. In v4.0
all providers used in `dnsconfig.js` will require an entry in `creds.json`.
For a smooth transition, please update your `creds.json` file now.
Here is the minimal entry required:
```json
{
"entryName": {
"TYPE": "FILL_IN"
}
}
```
### hyphen
Message: `ERROR: creds.json entry ... has invalid ... value ...`
This indicates the entry for `creds.json` has a TYPE value that is
invalid i.e. it is the empty string or a hyphen (`-`).
The fix is to correct the `TYPE` parameter in the `creds.json` entry.
Change it to one of the all caps identifiers in [the service provider list](https://stackexchange.github.io/dnscontrol/provider-list).
### cleanup
Message: `INFO: In dnsconfig.js New*(..., ...) can be simplified to New*(...)`
This message indicates that the same provider name is specified in
`dnsconfig.js` and `creds.json` and offers a suggestion for reducing
the redundancy.
The fix is to update `dnsconfig.js` as suggested in the error.
Usually this is to simply remove the second parameter to the function.
Examples:
```
OLD: var REG_THING = NewRegistrar("thing", "THING");
NEW: var REG_THING = NewRegistrar("thing");
OLD: var REG_THING = NewRegistrar("thing", "THING", { settings: "value" } );
NEW: var REG_THING = NewRegistrar("thing", { settings: "value" } );
OLD: var DNS_MYGANDI = NewDnsProvider("mygandi", "GANDI_V5");
NEW: var DNS_MYGANDI = NewDnsProvider("mygandi");
OLD: var DNS_MYGANDI = NewDnsProvider("mygandi", "GANDI_V5", { settings: "value" } );
NEW: var DNS_MYGANDI = NewDnsProvider("mygandi", { settings: "value" } );
```
Starting with v3.16 use of an OLD format will trigger warnings with suggestions on how to adopt the NEW format.
Starting with v4.0 support for the OLD format may be reported as an error.
Please adopt the NEW format when your installation has eliminated any use of DNSControl pre-3.16.
### mismatch
Message: `ERROR: Mismatch found! creds.json entry ... has ... set to ... but dnsconfig.js specifies New*(..., ...)`
This indicates that the provider type specifed in `creds.json` does not match the one specifed in `dnsconfig.js` or on the command line.
The fix is to change one to match the other.
### fixcreds
Message: `ERROR: creds.json entry ... is missing ...: ...`
However no `TYPE` subkey was found in an entry in `creds.json`.
In 3.16 forward, it is required if new-style `NewRegistrar()` or `NewDnsProvider()` was used.
In 4.0 this is required.
The fix is to add a `TYPE` subkey to the `creds.json` entry.
### hyphen
Message: `ERROR: creds.json entry ... has invalid ... value ...`
This indicates that the type `-` was specified in a `TYPE` value in
`creds.json`. There is no provider named `-` therefore that is
invalid. Perhaps you meant to specify a `-` on a command-line tool?
The fix is to change the `TYPE` subkey entry in `creds.json` from `-` to
a valid service provider identifier, as listed
in [the service provider list](https://stackexchange.github.io/dnscontrol/provider-list).
## Using a different file name
The `--creds` flag allows you to specify a different file name.
@@ -55,7 +181,7 @@ The `--creds` flag allows you to specify a different file name.
* Exceptions: The `x` bit is not checked if the filename ends with `.yaml`, `.yml` or `.json`.
* Windows: Executing an external script isn't supported. There's no code that prevents it from trying, but it isn't supported.
# Don't store secrets in a Git repo!
## Don't store secrets in a Git repo!
Do NOT store secrets in a Git repository. That is not secure. For example,
storing the example `cloudflare_tal` is insecure because anyone with access to

31
docs/get-zones.md
View File

@@ -68,6 +68,10 @@ zones at the provider.
provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
zone: One or more zones (domains) to download; or "all".
As of v3.16, `provider` can be `-` to indicate that the provider name is listed in `creds.json` in the `TYPE` field. Doing this will be backwards compatible with an (otherwise) breaking change due in v4.0.
As of v4.0 (BREAKING CHANGE), you must not specify `provider`. That value is found in the `TYPE` field of the credkey's `creds.json` file. For backwards compatibility, if the first `zone` is `-`, it will be skipped.
FORMATS:
--format=js dnsconfig.js format (not perfect, just a decent first draft)
--format=djs js with disco commas (leading commas)
@@ -92,12 +96,35 @@ The `--ttl` flag only applies to zone/js/djs formats.
dnscontrol get-zones gmain GANDI_V5 example.comn other.com
dnscontrol get-zones cfmain CLOUDFLAREAPI all
dnscontrol get-zones --format=tsv bind BIND example.com
dnscontrol get-zones --format=djs --out=draft.js glcoud GCLOUD example.com`,
dnscontrol get-zones --format=djs --out=draft.js glcoud GCLOUD example.com
As of v3.16:
# NOTE: When "-" appears as the 2nd argument, it is assumed that the
# creds.json entry has a field TYPE with the provider's type name.
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
As of v4.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
# 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
Read a zonefile, generate a JS file, then use the JS file to see how
different it is from the zonefile:
dnscontrol get-zone --format=djs -out=foo.djs bind BIND example.org
dnscontrol get-zone --format=djs -out=foo.djs bind - example.org
dnscontrol preview --config foo.js
# Developer Notes

58
docs/getting-started.md
View File

@@ -9,7 +9,7 @@ title: Getting Started
## From source
DNSControl can be built with Go version 1.16 or higher.
DNSControl can be built with Go version 1.18 or higher.
The `go get` command will download the source, compile it, and
install `dnscontrol` in your `$GOBIN` directory.
@@ -48,13 +48,6 @@ Create a directory where you'll be storing your configuration files.
We highly recommend storing these files in a Git repo, but for
simple tests anything will do.
Note: Do **not** store your creds.json file in Git unencrypted.
That is unsafe. Add `creds.json` to your
`.gitignore` file as a precaution. This file should be encrypted
using something
like [git-crypt](https://www.agwa.name/projects/git-crypt) or
[Blackbox](https://github.com/StackExchange/blackbox).
Create a subdirectory called `zones` in the same directory as the
configuration files. (`mkdir zones`). `zones` is where the BIND
provider writes the zonefiles it creates. Even if you don't
@@ -75,8 +68,8 @@ The file looks like:
```js
// Providers:
var REG_NONE = NewRegistrar('none', 'NONE'); // No registrar.
var DNS_BIND = NewDnsProvider('bind', 'BIND'); // ISC BIND.
var REG_NONE = NewRegistrar('none'); // No registrar.
var DNS_BIND = NewDnsProvider('bind'); // ISC BIND.
// Domains:
@@ -85,30 +78,43 @@ D('example.com', REG_NONE, DnsProvider(DNS_BIND),
);
```
You may modify this file to match your particular providers and domains. See [the javascript docs]({{site.github.url}}/js) and [the provider docs]({{site.github.url}}/provider-list) for more details.
If you are using other providers, you will likely need to make a `creds.json` file with api tokens and other account information. For example, to use both name.com and Cloudflare, you would have:
Modify this file to match your particular providers and domains. See [the dnsconfig docs]({{site.github.url}}/js) and [the provider docs]({{site.github.url}}/provider-list) for more details.
```js
Create a file called `creds.json` for storing provider configurations (API tokens and other account information).
For example, to use both name.com and Cloudflare, you would have:
```json
{
"cloudflare":{ // provider name to be used in dnsconfig.js
"apitoken": "token" // API token
"cloudflare": { // The provider name used in dnsconfig.js
"TYPE": "CLOUDFLAREAPI", // The provider type identifier
"accountid": "your-cloudflare-account-id", // credentials
"apitoken": "your-cloudflare-api-token" // credentials
},
"namecom":{ // provider name to be used in dnsconfig.js
"apikey": "key", // API Key
"apiuser": "username" // username for name.com
}
"namecom": { // The provider name used in dnsconfig.js
"TYPE": "NAMEDOTCOM", // The provider type identifier
"apikey": "key", // credentials
"apiuser": "username" // credentials
},
"none": { "TYPE": "NONE" } // The no-op provider
}
```
Note: Do **not** store your creds.json file in Git unencrypted.
That is unsafe. Add `creds.json` to your
`.gitignore` file as a precaution. This file should be encrypted
using something
like [git-crypt](https://www.agwa.name/projects/git-crypt) or
[Blackbox](https://github.com/StackExchange/blackbox).
There are 2 types of providers:
A "Registrar" is who you register the domain with. Start with
`REG_NONE`, which is a provider that never talks to or updates the
`NONE`, which is a provider that never talks to or updates the
registrar. You can define your registrar later when you want to
use advanced features.
The `DnsProvider` is the service that actually provides DNS service
(port 53) and may be the same or different company. Even if both
A "DnsProvider" is the service that actually provides DNS service
(port 53) and may be the same or different as the registrar. Even if both
your Registrar and DnsProvider are the same company, two different
definitions must be included in `dnsconfig.js`.
@@ -128,15 +134,17 @@ The file looks like:
```js
{
"bind": {
"TYPE": "BIND"
},
"r53_ACCOUNTNAME": {
"r53_accountname": {
"TYPE": "ROUTE53",
"KeyId": "change_to_your_keyid",
"SecretKey": "change_to_your_secretkey"
}
}
```
Ignore the `r53_ACCOUNTNAME` section. It is a placeholder and will be ignored. You
Ignore the `r53_accountname` section. It is a placeholder and will be ignored. You
can use it later when you define your first set of API credentials.
Note that `creds.json` is a JSON file. JSON is very strict about commas
@@ -148,7 +156,7 @@ Python:
jq:
jq < creds.json
jq . < creds.json
FYI: `creds.json` fields can be read from an environment variable. The field must begin with a `$` followed by the variable name. No other text. For example:

16
docs/nameservers.md
View File

@@ -20,20 +20,20 @@ All the examples use the variables. Substitute your own.
// ========== Registrars:
// A typical registrar.
var REG_NAMECOM = NewRegistrar("namedotcom_main", "NAMEDOTCOM");
var REG_NAMECOM = NewRegistrar("namedotcom_main");
// The "NONE" registrar is a "fake" registrar.
// This is useful if the registrar is not supported by DNSControl,
// or if you don't want to control the domain's delegation.
var REG_THIRDPARTY = NewRegistrar("ThirdParty", "NONE");
var REG_THIRDPARTY = NewRegistrar("ThirdParty");
// ========== DNS Providers:
var DNS_NAMECOM = NewDnsProvider("namedotcom_main", "NAMEDOTCOM");
var DNS_AWS = NewDnsProvider("aws_main", "ROUTE53");
var DNS_GOOGLE = NewDnsProvider("gcp_main", "GCLOUD");
var DNS_CLOUDFLARE = NewDnsProvider("cloudflare_main", "CLOUDFLAREAPI");
var DNS_BIND = NewDnsProvider("bind", "BIND");
var DNS_NAMECOM = NewDnsProvider("namedotcom_main");
var DNS_AWS = NewDnsProvider("aws_main");
var DNS_GOOGLE = NewDnsProvider("gcp_main");
var DNS_CLOUDFLARE = NewDnsProvider("cloudflare_main");
var DNS_BIND = NewDnsProvider("bind");
```
# Typical Delegations
@@ -226,7 +226,7 @@ Sometimes you just want to know if something changes!
See the <a href="{{site.github.url}}/providers/doh">DNS-over-HTTPS Provider</a> documentation for more info.
```js
var REG_MONITOR = NewRegistrar('DNS-over-HTTPS', 'DNSOVERHTTPS');
var REG_MONITOR = NewRegistrar('DNS-over-HTTPS');
D("example1.com", REG_MONITOR,
NAMESERVER("ns1.example1.com."),

220
docs/v316.md Normal file
View File

@@ -0,0 +1,220 @@
---
layout: default
title: Converting to v3.16
---
# 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:
OLD dnsconfig.js:
```js
var REG_GANDI = NewRegistrar("gandi", "GANDI_V5");
var DSP_CF = NewDnsProvider("cloudflare_tal", "CLOUDFLAREAPI");
```
NEW dnsconfig.js:
```js
var REG_GANDI = NewRegistrar("gandi");
var DSP_CF = NewDnsProvider("cloudflare_tal");
```
The second paramter (`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.
NEW creds.json:
```json
{
"gandi": {
"TYPE": "GANDI_V5", << NEW
"apikey": "reacted"
},
"cloudflare_tal": {
"TYPE": "CLOUDFLAREAPI", << NEW
"apikey": "reacted",
"apiuser": "reacted"
}
}
```
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:
```json
{
"none": { "TYPE": "NONE" },
"bind": { "TYPE": "BIND" }
}
```
# 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 look 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 used 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:
```json
{
"bind_inside": {
"TYPE": "BIND", << ADDED
"directory": "inzones"
},
"cloudflare_tal": {
"TYPE": "CLOUDFLAREAPI", << ADDED
"apikey": "redacted",
"apiuser": "redacted"
},
"gandi": {
"TYPE": "GANDI_V5", << ADDED
"apikey": "redacted"
},
```
## 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:
```
WARNING: For future compatibility, update the "namedotcom_main" entry in `creds.json` by adding: "TYPE": "NAMEDOTCOM", (See https://stackexchange.github.io/dnscontrol/creds-json#missing)
```
```
ERROR: Mismatch found! creds.json entry "namedotcom_main" has "TYPE" set to "ROUTE53" but dnsconfig.js specifies New*("namedotcom_main", "NAMEDOTCOM") (See https://stackexchange.github.io/dnscontrol/creds-json#mismatch)
```
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://stackexchange.github.io/dnscontrol/creds-json#cleanup)
```
Those messages 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.
OLD:
```js
var REG_NAMEDOTCOM_TAL = NewRegistrar("namedotcom_tal", "NAMEDOTCOM");
var DNS_GANDI_TAL = NewDnsProvider("gandi_v5_tal", "GANDI_V5");
```
NEW:
```js
var REG_NAMEDOTCOM_TAL = NewRegistrar("namedotcom_tal");
var DNS_GANDI_TAL = NewDnsProvider("gandi_v5_tal");
```
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!