dnscontrol/README.md

176 lines
6.7 KiB
Markdown
Raw Normal View History

2017-01-12 11:01:04 +08:00
# DNSControl
2023-12-05 21:46:51 +08:00
[![StackExchange/dnscontrol/build](https://github.com/StackExchange/dnscontrol/actions/workflows/pr_test.yml/badge.svg)](https://github.com/StackExchange/dnscontrol/actions/workflows/pr_test.yml)
2017-03-15 07:26:39 +08:00
[![Gitter chat](https://badges.gitter.im/dnscontrol/Lobby.png)](https://gitter.im/dnscontrol/Lobby)
2020-11-13 00:22:19 +08:00
[![Google Group](https://img.shields.io/badge/google%20group-chat-green.svg)](https://groups.google.com/forum/#!forum/dnscontrol-discuss)
2023-05-21 01:21:45 +08:00
[![PkgGoDev](https://pkg.go.dev/badge/github.com/StackExchange/dnscontrol)](https://pkg.go.dev/github.com/StackExchange/dnscontrol/v4)
2017-03-15 07:26:56 +08:00
[DNSControl](https://docs.dnscontrol.org/) is a system
for maintaining DNS zones. It has two parts:
2017-01-12 03:14:28 +08:00
a domain specific language (DSL) for describing DNS zones plus
software that processes the DSL and pushes the resulting zones to
DNS providers such as Route53, Cloudflare, and Gandi. It can send
the same DNS records to multiple providers. It even generates
the most beautiful BIND zone files ever. It runs anywhere Go runs (Linux, macOS,
2017-03-15 08:20:56 +08:00
Windows). The provider model is extensible, so more providers can be added.
Currently supported DNS providers:
- Akamai Edge DNS
- AutoDNS
- AWS Route 53
- AXFR+DDNS
- Azure DNS
- Azure Private DNS
- BIND
- Bunny DNS
- Cloudflare
- ClouDNS
- deSEC
- DigitalOcean
- DNS Made Easy
- DNSimple
- Domainnameshop (Domeneshop)
- Exoscale
- Gandi
2022-11-16 01:40:08 +08:00
- Gcore
- Google DNS
- Hetzner
- HEXONET
- hosting.de
- Hurricane Electric DNS
- INWX
- Linode
- Loopia
2023-03-09 23:15:59 +08:00
- LuaDNS
- Microsoft Windows Server DNS Server
- Mythic Beasts
- Namecheap
- Name.com
- Netcup
- Netlify
- NS1
- Oracle Cloud
- OVH
- Packetframe
- Porkbun
- PowerDNS
- Realtime Register
- RWTH DNS-Admin
- SoftLayer
- TransIP
- Vultr
Currently supported Domain Registrars:
- AWS Route 53
- CSC Global
- DNSOVERHTTPS
- Dynadot
- easyname
- Gandi
- HEXONET
- hosting.de
- Internet.bs
- INWX
- Namecheap
- Name.com
- OpenSRS
- OVH
- Realtime Register
2017-01-12 03:14:28 +08:00
At Stack Overflow, we use this system to manage hundreds of domains
and subdomains across multiple registrars and DNS providers.
You can think of it as a DNS compiler. The configuration files are
written in a DSL that looks a lot like JavaScript. It is compiled
to an intermediate representation (IR). Compiler back-ends use the
IR to update your DNS zones on services such as Route53, Cloudflare,
2022-08-12 01:15:19 +08:00
and Gandi, or systems such as BIND.
2017-01-12 03:14:28 +08:00
## An Example
2017-03-14 15:30:02 +08:00
`dnsconfig.js`:
2017-03-15 08:07:40 +08:00
```js
2017-03-14 15:30:02 +08:00
// define our registrar and providers
var REG_NAMECOM = NewRegistrar("name.com");
var r53 = NewDnsProvider("r53")
2017-03-14 15:30:02 +08:00
D("example.com", REG_NAMECOM, DnsProvider(r53),
2017-03-14 15:30:02 +08:00
A("@", "1.2.3.4"),
CNAME("www","@"),
2017-03-14 15:30:42 +08:00
MX("@",5,"mail.myserver.com."),
2017-03-14 15:30:02 +08:00
A("test", "5.6.7.8")
)
```
Running `dnscontrol preview` will talk to the providers (here name.com as registrar and route 53 as the dns host), and determine what changes need to be made.
2017-03-27 04:37:04 +08:00
Running `dnscontrol push` will make those changes with the provider and my dns records will be correctly updated.
2017-03-14 15:30:02 +08:00
The easiest way to run DNSControl is to use the Docker container:
```
docker run --rm -it -v "$(pwd):/dns" ghcr.io/stackexchange/dnscontrol preview
```
See [Getting Started](https://docs.dnscontrol.org/getting-started/getting-started) page on documentation site to get started!
2017-03-14 15:36:59 +08:00
## Benefits
2017-01-12 03:14:28 +08:00
- **Less error-prone** than editing a BIND zone file.
- **More reproducible** than clicking buttons on a web portal.
- **Easily switch between DNS providers:** The DNSControl language is
vendor-agnostic. If you use it to maintain your DNS zone records,
you can switch between DNS providers easily. In fact, DNSControl
will upload your DNS records to multiple providers, which means you
can test one while switching to another. We've switched providers 3
times in three years and we've never lost a DNS record.
- **Adopt CI/CD principles to DNS!** At StackOverflow we maintain our
DNSControl configurations in Git and use our CI system to roll out
changes. Keeping DNS information in a VCS means we have full
history. Using CI enables us to include unit-tests and
system-tests. Remember when you forgot to include a "." at the end
of an MX record? We haven't had that problem since we included a
test to make sure Tom doesn't make that mistake... again.
- **Adopt PR-based updates.** Allow developers to send updates as PRs,
which you can review before you approve.
- **Variables save time!** Assign an IP address to a constant and use the
variable name throughout the file. Need to change the IP address
globally? Just change the variable and "recompile."
- **Macros!** Define your SPF records, MX records, or other repeated data
once and re-use them for all domains.
- **Control Cloudflare from a single source of truth.** Enable/disable
Cloudflare proxying (the "orange cloud" button) directly from your
DNSControl files.
- **Keep similar domains in sync** with transforms and other features. If
one domain is supposed to be a filtered version of another, this is
easy to set up.
- **It is extendable!** All the DNS providers are written as plugins.
Writing new plugins is very easy.
2017-01-12 03:14:28 +08:00
## Installation
2017-01-12 03:14:28 +08:00
DNSControl can be installed via packages for macOS, Linux and Windows, or from source code. See the [official instructions](https://docs.dnscontrol.org/getting-started/getting-started#1-install-the-software).
## Via GitHub Actions (GHA)
See [dnscontrol-action](https://github.com/koenrh/dnscontrol-action) or [gacts/install-dnscontrol](https://github.com/gacts/install-dnscontrol).
## Deprecation warnings (updated 2024-02-24)
- **32-bit binaries will no longer be distributed after September 10, 2023.** There is a proposal to stop shipping 32-bit binaries (packages and containers). If no objections are raised by Sept 10, 2023, new releases will not include them. See https://github.com/StackExchange/dnscontrol/issues/2461 for details.
- **Call for new volunteer maintainers for NAMEDOTCOM and SOFTLAYER.** These providers have no maintainer. Maintainers respond to PRs and fix bugs in a timely manner, and try to stay on top of protocol changes.
- **ACME/Let's Encrypt support is frozen and will be removed after December 31, 2022.** The `get-certs` command (renews certs via Let's Encrypt) has no maintainer. There are other projects that do a better job. If you don't use this feature, please do not start. If you do use this feature, please plan on migrating to something else. See discussion in [issues/1400](https://github.com/StackExchange/dnscontrol/issues/1400)
## More info at our website
The website: [https://docs.dnscontrol.org/](https://docs.dnscontrol.org/)
The getting started guide: [https://docs.dnscontrol.org/getting-started/getting-started](https://docs.dnscontrol.org/getting-started/getting-started)
2024-01-10 05:22:03 +08:00
## Stargazers over time
[![Stargazers over time](https://starchart.cc/StackExchange/dnscontrol.svg?variant=adaptive)](https://starchart.cc/StackExchange/dnscontrol)