This guide installs DNSControl on a Linux host. DNSControl is a DNS-as-code tool written in Go that manages DNS records across multiple providers using a JavaScript DSL.
The easiest way to run DNSControl is using the official Docker image.
Pull and run DNSControl:
# Run DNSControl in a container
docker run --rm -it -v "$(pwd):/dns" ghcr.io/stackexchange/dnscontrol version
Create a working directory:
mkdir -p ~/dnscontrol
cd ~/dnscontrol
Create initial configuration files:
# Create dnsconfig.js
cat > dnsconfig.js << 'EOF'
var REG_NONE = NewRegistrar("none");
var DSP_BIND = NewDnsProvider("bind");
D("example.com", REG_NONE, DnsProvider(DSP_BIND),
A("@", "192.0.2.1"),
A("www", "192.0.2.1"),
MX("@", 10, "mail.example.com.")
);
EOF
# Create creds.json
cat > creds.json << 'EOF'
{
"bind": {
"TYPE": "BIND",
"directory": "/dns/zones"
}
}
EOF
# Create zones directory
mkdir -p zones
Run DNSControl commands:
# Preview changes
docker run --rm -it -v "$(pwd):/dns" ghcr.io/stackexchange/dnscontrol preview
# Push changes
docker run --rm -it -v "$(pwd):/dns" ghcr.io/stackexchange/dnscontrol push
macOS (Homebrew):
brew install dnscontrol
Linux (Generic):
Download pre-built binaries from GitHub Releases.
Arch Linux (AUR):
yay -S dnscontrol
Requires Go 1.21+.
# Clone repository
git clone https://github.com/StackExchange/dnscontrol.git
cd dnscontrol
# Build
go build -o dnscontrol
# Verify installation
./dnscontrol version
Create your DNS configuration in dnsconfig.js:
// dnsconfig.js
var REG_NONE = NewRegistrar("none");
var DSP_CLOUDFLARE = NewDnsProvider("cloudflare");
D("example.com", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
// A records
A("@", "192.0.2.1"),
A("www", "192.0.2.1"),
// MX records
MX("@", 10, "mail.example.com."),
// TXT records (SPF, DKIM, DMARC)
TXT("@", "v=spf1 mx -all"),
// CNAME records
CNAME("blog", "example.github.io.")
);
Create credentials file creds.json:
{
"cloudflare": {
"TYPE": "CLOUDFLARE",
"apitoken": "YOUR_CLOUDFLARE_API_TOKEN"
}
}
Verify DNSControl installation and configuration:
# Check version
dnscontrol version
# Preview changes (dry-run)
dnscontrol preview
# Push changes to providers
dnscontrol push
# Print zone file
dnscontrol print-ir
See DNSControl Configuration for detailed configuration guidance.
Need assistance with DNSControl deployment? Our experts specialize in DNS-as-code implementations and can help with setup, customization, and integration. Contact us at office@linux-server-admin.com or visit our contact page.