Overview
Last updated
Last updated
Choose one of the following installation methods:
On macOS (or Linux) you can install it using .
You can use DNSControl locally using the Docker image from or and the command below.
Download binaries from for Linux (binary, tar, RPM, DEB), FreeBSD (tar), Windows (exec, ZIP) for 32-bit, 64-bit, and ARM.
DNSControl can be built from source with Go version 1.18 or higher.
The go install command will download the source, compile it, and
install dnscontrol in your $GOBIN directory.
To install, simply run
To download the source
Shell completion is available for zsh and bash.
Add eval "$(dnscontrol shell-completion zsh)" to your ~/.zshrc file.
Add eval "$(dnscontrol shell-completion bash)" to your ~/.bashrc file.
Create a directory where you'll store your configuration files. We highly recommend storing these files in a Git repo, but for simple tests anything will do.
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
use BIND for DNS service, it is useful for testing.
dnsconfig.jsdnsconfig.js is the main configuration and defines providers, DNS
domains, and so on.
The file looks like:
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:
There are 2 types of providers:
A "Registrar" is with whom you register the domain. Start withNONE, 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.
A "DnsProvider" is the service that actually provides DNS service
(port 53) and may be the same or a different registrar. Even if both
your Registrar and DnsProvider are the same company, two different
definitions must be included in dnsconfig.js.
creds.jsoncreds.json stores credentials and a few global settings.
It is only needed if any providers require credentials (API keys,
usernames, passwords, etc.).
The file looks like:
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
and other formatting. There are a few different ways to check for typos:
Python:
jq:
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:
Before you edit the sample files, verify that the system is working.
First run dnscontrol preview and ensure it completes without
error(s). The preview command is the "dry run" mode that shows only
what changes need to be made and never makes any actual changes.
It will use APIs if needed to find out what DNS entries currently
exist.
(All output assumes the --full flag)
It should look something like this:
Next, run dnscontrol push to actually make the changes. In this
case, the change will be to create a zone file where one didn't
previously exist.
Try making a change to dnsconfig.js. For example, change the IP
address of in A("@", "1.2.3.4") or add an additional A record.
In our case, we changed the IP address to 10.10.10.10. Previewing our change looks like this:
Notice that it read the old zone file and was able to produce a
"diff" between the old A record and the new one. If the zonefile
didn't exist, the output would look different because the zone file
was being created from scratch.
Run dnscontrol push to see the system generate a new zone file.
Other providers use an API to do updates. In those cases the individual changes will translate into API calls that update the specific records.
Take a look at the zones/example.com.zone file. It should look
like:
Now that we know the system is working for test data, try controlling a real domain (or a test domain if you have one).
Edit the domain: Add the D() entry for the domain, or repurpose
the example.com domain. Add individual A(), MX() and other
records as needed. Remember that the first parameter to D() is
always a Registrar.
Run dnscontrol preview to test your work. It may take a few tries
to list all the DNS records that make up the domain. When preview
shows no changes required, then you know you are at record parity.
Now you can make changes to the domain(s) and run dnscontrol preview
If you are going to use this in production, we highly recommend the following:
Store the configuration files in Git.
Encrypt the creds.json file before storing it in Git. Do NOT store
API keys or other credentials without encrypting them.
If these don't work, more info is in .
This requires completion to be enabled in zsh. A good tutorial for this is available at [].
This requires the bash-completion package to be installed. See for instructions.
Start your dnsconfig.js file by downloading
and renaming it.
Modify this file to match your particular providers and domains. See and for more details.
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 or.
Start your creds.json file by downloading
and renaming it.
You can change the "DEFAULT_NOT_SET" text by following the documentation for the to set the "master" and "mbox" settings. Try that now.
Set up the provider: Add the providers's definition to dnsconfig.js
and list any credentials in creds.json. Each provider is different.
See for
specifics.
The doc has advice
about converting from other systems.
You can manually create the D() statements, or you can
generate them automatically using the
command to import the zone from (most) providers and output it as code
that can be added to dnsconfig.js and used with very little
modification.
Use a CI/CD tool like , Jenkins, CircleCI, , etc. to automatically push DNS changes.
Join the DNSControl community. File and .