DNSControl is an opinionated platform for seamlessly managing your DNS configuration across any number of DNS hosts, both in the cloud or in your own infrastructure. This guide will walk you through the steps to set up DNSControl on Ubuntu 18.04.
For this guide, we will use DNSimple as the example DNS provider.
Prerequisites
To begin this tutorial, you'll need one Ubuntu 18.04 server with a sudo non-root user and a fully registered domain name with DNS hosted by a supported provider.
Once you have these ready, log in to your server as your non-root user to begin.
Installing DNSControl
DNSControl is written in Go, so you'll start this step by installing Go to your Ubuntu server and setting your GOPATH.
Go is available within Ubuntu's default software repositories, making it possible to install using conventional package management tools.
sudo apt update
sudo apt -y install golang-go
After confirming the installation, apt will download and install Go and all of its required dependencies.
Next, we'll configure the required path environment variables for Go.
nano ~/.profile
Add the following lines to the very end of your file:
export GOPATH="$HOME/go"
export PATH="$PATH:$GOPATH/bin"
Once you have added these lines to the bottom of the file, save and close it. Then reload your profile by either logging out and back in, or sourcing the file again:
source ~/.profile
Now you've installed and configured Go, you can install DNSControl.
The go get command can be used to fetch a copy of the code, automatically compile it and install it into your Go directory:
go get github.com/StackExchange/dnscontrol
Once this is complete, you can check the installed version to make sure that everything is working:
dnscontrol version
Your output will look similar to the following:
Output
dnscontrol 0.2.8-dev
If you see a dnscontrol: command not found error, double-check your Go path setup.
Now that you've installed DNSControl, you can create a configuration directory and connect DNSControl to your DNS provider in order to allow it to make changes to your DNS records.
Configuring DNSControl
In this section, we'll create the required configuration directories for DNSControl, and connect it to your DNS provider so that it can begin to make live changes to your DNS records.
First, you need to create a new directory in which you can store your DNSControl configuration, and then move into it:
mkdir ~/dnscontrol
cd ~/dnscontrol
If you plan to use DNSControl to write BIND zone files, you should also create the zones directory:
mkdir ~/dnscontrol/zones
Next, you need to configure the creds.json file, which is what will allow DNSControl to authenticate to your DNS provider and make changes. The format of creds.json differs slightly depending on the DNS provider that you are using. Please see the Service Providers list in the official DNSControl documentation to find the configuration for your own provider.
Create the file creds.json in the ~/dnscontrol directory:
cd ~/dnscontrol
nano creds.json
Add the sample creds.json configuration for your DNS provider to the file. If you're using DNSimple as your DNS provider, you can use the following parameters replacing red highlighted text with yours:
{
"dnsimple": {
"token": "your-dnsimple-account-access-token"
}
}
This file tells DNSControl to which DNS providers you want it to connect.
You'll need to provide some form of authentication for your DNS provider. This is usually an API key or OAuth token, but some providers require extra information, as documented in the Service Providers list in the official DNSControl documentation.
If you have multiple different DNS providers—for example, for multiple domain names, or delegated DNS zones—you can define these all in the same creds.json file.
You've set up the initial DNSControl configuration directories, and configured creds.json to allow DNSControl to authenticate to your DNS provider and make changes. Next you'll create the configuration for your DNS zones.
Creating a DNS Configuration File
In this step, you'll create an initial DNS configuration file, which will contain the DNS records for your domain name or delegated DNS zone.
dnsconfig.js is the main DNS configuration file for DNSControl. In this file, DNS zones and their corresponding records are defined using JavaScript syntax. This is known as a DSL, or Domain Specific Language. The JavaScript DSL page in the official DNSControl documentation provides further details.
To begin, create the DNS configuration file in the ~/dnscontrol directory:
cd ~/dnscontrol
nano dnsconfig.js
Then, add the following sample configuration to the file:
// Providers:
var REG_DNSIMPLE = NewRegistrar("dnsimple", "DNSIMPLE");
var DNSIMPLE = NewDnsProvider("dnsimple", "DNSIMPLE");
// Domains:
D("example.tld", REG_DNSIMPLE, DnsProvider(DNSIMPLE),
A("@","1.2.3.4")
);
This sample file defines a domain name or DNS zone at a particular provider, which in this case is example.com hosted by DNSimple. An example A record is also defined for the zone root (@), pointing to the IPv4 address of the server that you're hosting your domain/website on.
There are three main functions that make up a basic DNSControl configuration file:
You should configure NewRegistrar(), NewDnsProvider(), and D() accordingly using the Service Providers list in the official DNSControl documentation.
Once complete, save and close the file.
Populating Your DNS Configuration File
Next, we'll populate the DNS configuration file with useful DNS records for our website or service, using the DNSControl syntax.
In order to begin adding DNS records for your domain or delegated DNS zone, edit your DNS configuration file:
cd ~/dnscontrol
nano dnsconfig.js
Next, you can begin populating the parameters for the existing D() function using the syntax described in the previous list, as well as the Domain Modifiers section of the official DNSControl documentation. A comma (,) must be used in-between each record.
For reference, the code block here contains a full sample configuration for a basic, initial DNS setup:
D('example.com', REG_NONE, DnsProvider(DNS_DNSimple),
A('@', 'your-server-ip'),
A('www', 'your-server-ip'),
A('mail', 'your-server-ip'),
AAAA('@', 'your-server-ipv6-address'),
AAAA('www', 'your-server-ipv6-address'),
AAAA('mail', 'your-server-ipv6-address'),
MX('@', 10, 'mail.example.com.'),
TXT('@', 'v=spf1 -all'),
TXT('_dmarc', 'v=DMARC1; p=reject; rua=mailto:abuse@example.com; aspf=s; adkim=s;')
);
Once you have completed your initial DNS configuration, save and close the file.
Testing and Deploying Your DNS Configuration
We'll run a local syntax check on your DNS configuration, and then deploy the changes to the live DNS server/provider.
Firstly, move into your dnscontrol directory:
cd ~/dnscontrol
Next, use the preview function of DNSControl to check the syntax of your file, and output what changes it will make (without actually making them):
dnscontrol preview
If the syntax of your DNS configuration file is correct, DNSControl will output an overview of the changes that it will make. This should look similar to the following:
Output
******************** Domain: example.com
----- Getting nameservers from: dnsimple
----- DNS Provider: dnsimple...8 corrections
#1: CREATE A example.com your-server-ip ttl=300
#2: CREATE A www.example.com your-server-ip ttl=300
#3: CREATE A mail.example.com your-server-ip ttl=300
#4: CREATE AAAA example.com 2001:db8::1 ttl=300
#5: CREATE TXT _dmarc.example.com "v=DMARC1; p=reject; rua=mailto:abuse@example.com; aspf=s; adkim=s;" ttl=300
#6: CREATE AAAA www.example.com 2001:db8::1 ttl=300
#7: CREATE AAAA mail.example.com 2001:db8::1 ttl=300
#8: CREATE MX example.com 10 mail.example.com. ttl=300
----- Registrar: none...0 corrections
Done. 8 corrections.
If you see an error warning in your output, DNSControl will provide details on what and where the error is located within your file.
Finally, you can push out the changes to your live DNS provider:
dnscontrol push
You'll see an output similar to the following:
Output
******************** Domain: example.com
----- Getting nameservers from: dnsimple
----- DNS Provider: dnsimple...8 corrections
#1: CREATE TXT _dmarc.example.com "v=DMARC1; p=reject; rua=mailto:abuse@example.com; aspf=s; adkim=s;" ttl=300
SUCCESS!
#2: CREATE A example.com your-server-ip ttl=300
SUCCESS!
#3: CREATE AAAA example.com 2001:db8::1 ttl=300
SUCCESS!
#4: CREATE AAAA www.example.com 2001:db8::1 ttl=300
SUCCESS!
#5: CREATE AAAA mail.example.com 2001:db8::1 ttl=300
SUCCESS!
#6: CREATE A www.example.com your-server-ip ttl=300
SUCCESS!
#7: CREATE A mail.example.com your-server-ip ttl=300
SUCCESS!
#8: CREATE MX example.com 10 mail.example.com. ttl=300
SUCCESS!
----- Registrar: none...0 corrections
Done. 8 corrections.
Now, if you check the DNS settings for your domain in the DNSimple control panel, you'll see the changes.
You can also check the record creation by running a DNS query for your domain/delegated zone. You'll see that the records have been updated accordingly:
dig +short example.com
You'll see output showing the IP address and relevant DNS record from your zone that was deployed using DNSControl. DNS records can take some time to propagate, so you may need to wait and run this command again.
Wrapping up
For this guide, we will use DNSimple as the example DNS provider.
Prerequisites
To begin this tutorial, you'll need one Ubuntu 18.04 server with a sudo non-root user and a fully registered domain name with DNS hosted by a supported provider.
Once you have these ready, log in to your server as your non-root user to begin.
Installing DNSControl
DNSControl is written in Go, so you'll start this step by installing Go to your Ubuntu server and setting your GOPATH.
Go is available within Ubuntu's default software repositories, making it possible to install using conventional package management tools.
sudo apt update
sudo apt -y install golang-go
After confirming the installation, apt will download and install Go and all of its required dependencies.
Next, we'll configure the required path environment variables for Go.
nano ~/.profile
Add the following lines to the very end of your file:
export GOPATH="$HOME/go"
export PATH="$PATH:$GOPATH/bin"
Once you have added these lines to the bottom of the file, save and close it. Then reload your profile by either logging out and back in, or sourcing the file again:
source ~/.profile
Now you've installed and configured Go, you can install DNSControl.
The go get command can be used to fetch a copy of the code, automatically compile it and install it into your Go directory:
go get github.com/StackExchange/dnscontrol
Once this is complete, you can check the installed version to make sure that everything is working:
dnscontrol version
Your output will look similar to the following:
Output
dnscontrol 0.2.8-dev
If you see a dnscontrol: command not found error, double-check your Go path setup.
Now that you've installed DNSControl, you can create a configuration directory and connect DNSControl to your DNS provider in order to allow it to make changes to your DNS records.
Configuring DNSControl
In this section, we'll create the required configuration directories for DNSControl, and connect it to your DNS provider so that it can begin to make live changes to your DNS records.
First, you need to create a new directory in which you can store your DNSControl configuration, and then move into it:
mkdir ~/dnscontrol
cd ~/dnscontrol
If you plan to use DNSControl to write BIND zone files, you should also create the zones directory:
mkdir ~/dnscontrol/zones
Next, you need to configure the creds.json file, which is what will allow DNSControl to authenticate to your DNS provider and make changes. The format of creds.json differs slightly depending on the DNS provider that you are using. Please see the Service Providers list in the official DNSControl documentation to find the configuration for your own provider.
Create the file creds.json in the ~/dnscontrol directory:
cd ~/dnscontrol
nano creds.json
Add the sample creds.json configuration for your DNS provider to the file. If you're using DNSimple as your DNS provider, you can use the following parameters replacing red highlighted text with yours:
{
"dnsimple": {
"token": "your-dnsimple-account-access-token"
}
}
This file tells DNSControl to which DNS providers you want it to connect.
You'll need to provide some form of authentication for your DNS provider. This is usually an API key or OAuth token, but some providers require extra information, as documented in the Service Providers list in the official DNSControl documentation.
If you have multiple different DNS providers—for example, for multiple domain names, or delegated DNS zones—you can define these all in the same creds.json file.
You've set up the initial DNSControl configuration directories, and configured creds.json to allow DNSControl to authenticate to your DNS provider and make changes. Next you'll create the configuration for your DNS zones.
Creating a DNS Configuration File
In this step, you'll create an initial DNS configuration file, which will contain the DNS records for your domain name or delegated DNS zone.
dnsconfig.js is the main DNS configuration file for DNSControl. In this file, DNS zones and their corresponding records are defined using JavaScript syntax. This is known as a DSL, or Domain Specific Language. The JavaScript DSL page in the official DNSControl documentation provides further details.
To begin, create the DNS configuration file in the ~/dnscontrol directory:
cd ~/dnscontrol
nano dnsconfig.js
Then, add the following sample configuration to the file:
// Providers:
var REG_DNSIMPLE = NewRegistrar("dnsimple", "DNSIMPLE");
var DNSIMPLE = NewDnsProvider("dnsimple", "DNSIMPLE");
// Domains:
D("example.tld", REG_DNSIMPLE, DnsProvider(DNSIMPLE),
A("@","1.2.3.4")
);
This sample file defines a domain name or DNS zone at a particular provider, which in this case is example.com hosted by DNSimple. An example A record is also defined for the zone root (@), pointing to the IPv4 address of the server that you're hosting your domain/website on.
There are three main functions that make up a basic DNSControl configuration file:
- NewRegistrar(name, type, metadata): defines the domain registrar for your domain name. DNSControl can use this to make required changes, such as modifying the authoritative nameservers. If you only want to use DNSControl to manage your DNS zones, this can generally be left as NONE.
- NewDnsProvider(name, type, metadata): defines a DNS service provider for your domain name or delegated zone. This is where DNSControl will push the DNS changes that you make.
- D(name, registrar, modifiers): defines a domain name or delegated DNS zone for DNSControl to manage, as well as the DNS records present in the zone.
You should configure NewRegistrar(), NewDnsProvider(), and D() accordingly using the Service Providers list in the official DNSControl documentation.
Once complete, save and close the file.
Populating Your DNS Configuration File
Next, we'll populate the DNS configuration file with useful DNS records for our website or service, using the DNSControl syntax.
In order to begin adding DNS records for your domain or delegated DNS zone, edit your DNS configuration file:
cd ~/dnscontrol
nano dnsconfig.js
Next, you can begin populating the parameters for the existing D() function using the syntax described in the previous list, as well as the Domain Modifiers section of the official DNSControl documentation. A comma (,) must be used in-between each record.
For reference, the code block here contains a full sample configuration for a basic, initial DNS setup:
D('example.com', REG_NONE, DnsProvider(DNS_DNSimple),
A('@', 'your-server-ip'),
A('www', 'your-server-ip'),
A('mail', 'your-server-ip'),
AAAA('@', 'your-server-ipv6-address'),
AAAA('www', 'your-server-ipv6-address'),
AAAA('mail', 'your-server-ipv6-address'),
MX('@', 10, 'mail.example.com.'),
TXT('@', 'v=spf1 -all'),
TXT('_dmarc', 'v=DMARC1; p=reject; rua=mailto:abuse@example.com; aspf=s; adkim=s;')
);
Once you have completed your initial DNS configuration, save and close the file.
Testing and Deploying Your DNS Configuration
We'll run a local syntax check on your DNS configuration, and then deploy the changes to the live DNS server/provider.
Firstly, move into your dnscontrol directory:
cd ~/dnscontrol
Next, use the preview function of DNSControl to check the syntax of your file, and output what changes it will make (without actually making them):
dnscontrol preview
If the syntax of your DNS configuration file is correct, DNSControl will output an overview of the changes that it will make. This should look similar to the following:
Output
******************** Domain: example.com
----- Getting nameservers from: dnsimple
----- DNS Provider: dnsimple...8 corrections
#1: CREATE A example.com your-server-ip ttl=300
#2: CREATE A www.example.com your-server-ip ttl=300
#3: CREATE A mail.example.com your-server-ip ttl=300
#4: CREATE AAAA example.com 2001:db8::1 ttl=300
#5: CREATE TXT _dmarc.example.com "v=DMARC1; p=reject; rua=mailto:abuse@example.com; aspf=s; adkim=s;" ttl=300
#6: CREATE AAAA www.example.com 2001:db8::1 ttl=300
#7: CREATE AAAA mail.example.com 2001:db8::1 ttl=300
#8: CREATE MX example.com 10 mail.example.com. ttl=300
----- Registrar: none...0 corrections
Done. 8 corrections.
If you see an error warning in your output, DNSControl will provide details on what and where the error is located within your file.
Finally, you can push out the changes to your live DNS provider:
dnscontrol push
You'll see an output similar to the following:
Output
******************** Domain: example.com
----- Getting nameservers from: dnsimple
----- DNS Provider: dnsimple...8 corrections
#1: CREATE TXT _dmarc.example.com "v=DMARC1; p=reject; rua=mailto:abuse@example.com; aspf=s; adkim=s;" ttl=300
SUCCESS!
#2: CREATE A example.com your-server-ip ttl=300
SUCCESS!
#3: CREATE AAAA example.com 2001:db8::1 ttl=300
SUCCESS!
#4: CREATE AAAA www.example.com 2001:db8::1 ttl=300
SUCCESS!
#5: CREATE AAAA mail.example.com 2001:db8::1 ttl=300
SUCCESS!
#6: CREATE A www.example.com your-server-ip ttl=300
SUCCESS!
#7: CREATE A mail.example.com your-server-ip ttl=300
SUCCESS!
#8: CREATE MX example.com 10 mail.example.com. ttl=300
SUCCESS!
----- Registrar: none...0 corrections
Done. 8 corrections.
Now, if you check the DNS settings for your domain in the DNSimple control panel, you'll see the changes.
You can also check the record creation by running a DNS query for your domain/delegated zone. You'll see that the records have been updated accordingly:
dig +short example.com
You'll see output showing the IP address and relevant DNS record from your zone that was deployed using DNSControl. DNS records can take some time to propagate, so you may need to wait and run this command again.
Wrapping up
You have completed DNSControl set up and DNS configuration deployment to a live provider. Now you can manage and test your DNS configuration changes in a safe, offline environment before deploying them to production.
No comments: