dnscontrol/docs/creds-json.md

layout	title
default	creds.json file format

creds.json

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 creds.json file:

{
  "cloudflare_tal": {
    "_PROVIDER": "CLOUDFLAREAPI",
    "apikey": "REDACTED",
    "apiuser": "REDACTED"
  },
  "inside": {
    "_PROVIDER": "BIND",
    "directory": "inzones",
    "filenameformat": "db_%T%?_%D"
  },
  "hexonet": {
    "_PROVIDER": "HEXONET",
    "apilogin": "$HEXONET_APILOGIN",
    "apipassword": "$HEXONET_APIPASSWORD",
    "debugmode": "$HEXONET_DEBUGMODE",
    "domain": "$HEXONET_DOMAIN"
  }
}

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.
  • ...may include any printable character except colon (:)
  • Convention: all lower case, usually the name of the provider or the username at the provider or both.
• Subkeys: (e.g. apikey, apiuser and etc.)
  • ...are whatever the provider specifies.
  • ...can be credentials, secrets, or configuration settings. In the above examples the inside setting is configuration parameters for the BIND provider, not credentials.
  • A missing subkey is not an error. The value is the empty string.
  • The subkey _PROVIDER indicates which provider plug-in to use. In the future it will be required and dnscontrol will report an error if it is missing or invalid. Currently DNSControl reports warnings.
• Values:
  • ...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

The --creds flag allows you to specify a different file name.

• Normally the file is read as a JSON file.
• Do not end the filename with .yaml or .yml as some day we hope to support YAML.
• Rather than specifying a file, you can specify a program to be run. The output of the program must be valid JSON and will be read the same way.
  • If the name begins with !, the remainder of the name is taken to be the command to be run.
  • If the name is a file that is executable (chmod +x bit), it is taken as the command to be run.
  • 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!

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.