You can either download the latest github release, or build from the go source:
go get github.com/StackExchange/dnscontrol
go get command will will download the source, compile it, and
dnscontrol in your
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. In fact you should include
creds.json in your
.gitignore file. We recommend you encrypt the file using something
like git-crypt or
Create a subdirectory called
zones in the same directory as the
configuration files. (
zones is where the BIND
provider writes the zonefiles it creates. Even if you don’t
use BIND, it is useful for testing.
dnsconfig.js is the main configuration and defines providers, DNS
domains, and so on.
dnsconfig.js file by downloading
and renaming it.
The file looks like:
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:
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
registrar. You can define your registrar later when you want to
use advanced features.
DnsProvider is the service that actually provides DNS service
(port 53) and may be the same or different company. Even if both
your Registrar and DnsProvider are the same company, two different
definitions must be included in
creds.json stores credentials and a few global settings.
It is only needed if any providers require credentials (API keys,
usernames, passwords, etc.).
creds.json file by downloading
and renaming it.
The file looks like:
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.
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 -m json.tool creds.json
jq < creds.json
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.
dnscontrol preview and make sure that it completes with
no errors. The preview command is the “dry run” mode that shows
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
It should look something like this:
dnscontrol push to actually make the changes. In this
case, the change will be to create a zone file where one didn’t
Try making a change to
dnsconfig.js. For example, change the IP
address of in
A('@', '22.214.171.124') 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.
dnscontrol push to see the system generate a new zone file.
Other providers use an API do 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
You can change the “DEFAULT_NOT_SET” text by following the documentation for the BIND provider to set the “master” and “mbox” settings. Try that now.
Now that we know the system is working for test data, try controlling a real domain (or a test domain if you have one).
Set up the provider: Add the providers’s definition to
and list any credentials in
creds.json. Each provider is different.
See the provider docs for
Edit the domain: Add the
D() entry for the domain, or repurpose
example.com domain. Add individual
MX() and other
records as needed. Remember that the first parameter to
always a Registrar.
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 feature parity.
The Migrating 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
Now you can make change to the domain(s) and run
If you are going to use this in production, we highly recommend the following:
creds.jsonfile before storing it in Git.