When dnscontrol interacts with a provider, any API keys, credentials, or other
configuration parameters required are stored in creds.json
. The file contains a set of key/value pairs for each configuration. That is, since a provider can be used multiple times with different credentials, the file contains a section for each set of credentials.
Here’s a sample file:
{
"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",
"domain": "$HEXONET_DOMAIN"
}
}
cloudflare_tal
, inside
, hexonet
)
NewRegistrar()
or NewDnsProvider()
functions in a dnsconfig.js file.:
)apikey
, apiuser
and etc.)
inside
setting is configuration parameters for the BIND provider, not credentials.$
, 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.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.
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:
{
"entryName": {
"TYPE": "FILL_IN"
}
}
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.
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.
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.
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.
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.
The --creds
flag allows you to specify a different file name.
.yaml
or .yml
as some day we hope to support YAML.!
, the remainder of the name is taken to be a shell command or program to be run.+x
bit), it is taken as the command to be run.x
bit is not checked if the filename ends with .yaml
, .yml
or .json
.Following commands would execute a program/script:
dnscontrol preview --creds !./creds.sh
dnscontrol preview --creds ./creds.sh
dnscontrol preview --creds creds.sh
dnscontrol preview --creds !creds.sh
dnscontrol preview --creds !/some/absolute/path/creds.sh
dnscontrol preview --creds /some/absolute/path/creds.sh
Following commands would execute a shell command:
dnscontrol preview --creds "!op inject -i creds.json.tpl"
This example requires the 1Password command-line tool
but works with any shell command that returns a properly formatted creds.json
.
In this case, the 1Password CLI is used to inject the secrets from
a 1Password vault, rather than storing them in environment variables.
An example of a template file containing Linode and Cloudflare API credentials is available here: creds.json.tpl-example.txt)
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
your Git repository or the history will know your apiuser is REDACTED
.
Removing secrets accidentally stored in Git is very difficult. You’ll probably
give up and re-create the repo and lose all history.
Instead, use environment variables as in the hexonet
example above. Use
secure means to distribute the names and values of the environment variables.