github DNSControl/dnscontrol v5.0.0
on GitHub

3 hours ago

Greetings DNS fans!

v5.0.0 is released! This was a big community effort!

Thanks to all the people that helped test and fix bugs including @labrown @fm @cafferata @chicks @androw @AsifNawaz-cnic @blackshadev @bytemain @chicks-net @cylonchau @das7pad @dnscale-ops @DustyRah @eliheady @haylinmoore @huihuimoe @huskyistaken @imlonghao @jbelien @jochristian @kallsyms @KlettIT @kordianbruck @labrown @masterzen @meghanakudua02 @morozov-alexey @mtmn @patschi @pgaskin @ppmathis @rblenkinsopp @riku22 @riyadhalnur @SimenBai @SukkaW @ttkzw @vojtad @willpower232 @xddxdd @yzqzss @zupolgec (it's impossible to make such a list without forgetting someone. Apologies in advance to anyone I missed!) A special thanks to my new employer, CoreWeave, for their support!

v5.0.0 is all about EXTENSIBILITY!

  • When IETF standarizes a new record type: DNS Support is automatic!
    • When they appear in codeberg.org/miekg/dns, DNS control supports them (almost) automatically!
    • Individual provider support requires very little work, often none!
  • Non-standard record types like R53_ALIAS act just like standard types!
    • We no longer need to special-case them all over the code. They even appear in zonefiles!
  • “Builders” are easier to create, less brittle!
    • Builder can now be written in Go, which has much better testing facilities.
    • Legacy providers (SPF_BUILDER, DKIM_BUILDER, DMARC_BUILDER) are still brittle, but will soon be upgraded.
  • And…
    • Better internationalized domain name (IDN) support. Fields are now consistently processed at input, not later in the pipeline. This simplifies code and reduces potential errors. As a result, all providers now have 100% IDN support “for free”.
    • DNSControl should use significantly less memory for large DNS zones.
    • Writing new providers is significantly easier.
    • Processing large zones is faster, with new potential optimizations coming!
    • Zero compatibility issues. Your old dnsconfig.js should “just work”.

How did this happen? We upgraded from github.com/miekg/dns to codeberg.org/miekg/dns (a.k.a. “DNS version 2”) and took advantage of the new features. Specifically, models.RecordConfig no longer contains fields for each record type, most of which go unused. Instead it stores a DNS version 2 RDATA interface that contains the fields needed for that specific record type. This also allowed us to create new factories (NewRecordConfig() and NewRecordConfigParse()) which replace many lines of code in providers. As a result, every file that touches models.RecordConfig had to change. Thanks to @miekg for collaborating on the RDATA features which make much of this possible.

What does this mean to you?

  • IGNORE() is now reliable for all providers!
  • SOA records are no longer special. They work like all other records.
  • DS ordering works: A DS record is created after its target NS exists, and deleted only after its target NS is removed
  • dnscontrol foo now errors “command not found” instead of carping that no help for “foo” exists.
  • Documentation bugfix: Parameters for various types and builders now in sync with code.
  • VULTR now supports concurrency and AUTODNSSEC
  • Custom record types for ADGUARDHOME, AKAMAIDNS, AZURE_DNS, ROUTE52, BUNNYDNS, CLOUDFLAREAPI, CLOUDNS, LUADNS, MIKROTIK, NETLIFY, and PORKBUN have been converted to the new custom record type system. They are no longer special and even appear in zonefile backups.

Some potential regressions: (These record types may not have worked previously.)

  • deSEC no longer supports DS records
  • Exoscale no longer supports PTR records
  • Tencent no longer supports ALIAS or PTR records

Dev notes:

Developers might be interested in the code changes, which are described here in modernizingproviders.md

  • Code for standard record types (models/record_astype.go) and custom types (pkg/privatetypes/) are generated.
  • Record type is stored as an integer, because string comparisons are slow. (.Type is still available for now but please use .TypeNum)
  • Go 1.27 is now the minimum Go compiler version. The struct literal change is particularly helpful.
  • “Golden files” record API input/outputs for off-line testing, eliminating the need for API access in many cases.
  • All providers have been upgraded to “diff2”. The diff1 compatibility code has been removed.
    There is a new “cookbook” which explains common code patterns: Cookbook.
  • It is now significantly easier to write providers. The translation from native to models.RecordConfig is much easier thanks to new factory functions.
  • I'm now maintaining a list of REFACTORING PROJECTS in case anyone wants to grab one. It's a good way to learn the code base or get more experience with the Go language.
  • You may be interested that during the development of this release, both the old and new RecordConfig were supported with a very slick bidirectional conversion process. As the legacy fields were eliminated, the conversionn process got closer and closer to being a no-op until suddenly the and n

Stats:

  • 467 files changed!
  • 283 new files added!
  • 34 files deleted! (my favorite statistic!)

Testing notes

The following providers received extensive testing:

AKAMAIEDGEDNS ALIDNS AXFRDDNS AZUREDNS AZUREPRIVATEDNS BIND CLOUDFLARE CLOUDNS
CNR DESEC DIGITALOCEAN DNSCALE DNSIMPLE DOMAINNAMESHOP DYNU GANDIV5 GCLOUD
GIDINET HEDNS HUAWEICLOUD INFOMANIAK INWX LINODE LUADNS MYTHICBEASTS NAMECHEAP
NAMEDOTCOM NETBIRD NETLIFY NETNOD NEXDNS NS1 OPENWRT ORACLE OVH PORKBUN POWERDNS
ROUTE53 SAKURACLOUD TRANSIP UNIFI VERCEL VULTR WEBSUPPORT

The following providers lacked testing. Please use with caution:

ADGUARDHOME AUTODNS BUNNYDNS CSCGLOBAL DNSMADEEASY EXOSCALE FORTIGATE GCORE
GIGAHOST HETZNERV2 HOSTINGDE JOKER LOOPIA MIKROTIK NETCUP PACKETFRAME
REALTIMEREGISTER RWTH SCALEWAY SOFTLAYER TENCENTDNS

Users of the IMPORT_TRANSFORM() and IMPORT_TRANSFORM_STRIP() functions should test carefully before using in production.

Changes

The list is too long to include all commits, but here are the highlights:

  • Add factory for models.DomainConfig: models.NewDomainConfig(zone).
  • Add factories for models.RecordConfig, replace old code where we can.
  • Down-casing, canonicalization, IDN conversion, stutter checking, and normalizing fields is now done when making the RecordConfig, not at the validation/normalization step later in the pipeline. As a result, errors are reported sooner and more accurately. pkg/normalize/validate.go still exists and is used, but is slowly being deprecated.
  • Remove the rtypecontrol module. In the few places it was used, replace with the new RDATA functionality.
  • DNS types RP and DS were reimplemented using the new RDATA system.
  • Replace RecordConfig.Comparable with RecordConfig.ComparableV3 (name change to find stragglers).
  • Custom types are now described in YAML with code generated automatically (pkg/privatetypes/types_generate.yaml)
  • TLSA comparison is now done on ToUpper, not ToLower, strings.
  • Added a "cookbook" of how to use new factories: Cookbook.
  • Integration tests: Test cfworkers and cfredirect by default.
  • Integration tests: Improve SVCB/HTTPS tests, especially for ech=IGNORE
  • LOC() is now a "builder" that outputs LOC records.
  • LOC floating point rounding error fixed
  • Builders are registered using models.RegisterBuilder()
  • No longer store the "Raw" domain names (the name as the user input them). They were never used.
  • D_EXTEND() refactored. Implementation is simplier and faster.
  • RecordConfig now stores .TypeNum which is the numeric value for the type. Eventually we'll remove .Type.
  • Change github.com/miekg/dns to codeberg.org/miekg/dns (and related packages) where possible, including new helper functions in pkg/dnsrr/dnsrr.go to help migrate away from dnsv1
  • pkg/js/helpers.js: Improved rawRecordBuilder() to be feature-compatible with recordBuilder()
  • pkg/js/helpers.js: Convert to "the new way" for all record types.
  • pkg/js/parse_tests update fixtures due to new JSON fields. .json files no longer have Unicode chars.
  • Zonefiles now include "real" data for custom types instead of comments.
  • New package: mustbe for converting raw data to the types we need.
  • BIND: Zonefile generator produces better files.
  • BIND: Refactor SOA serial number handling.
  • CLOUDFLAREAPI: Update SINGLE_REDIRECT, CF_REDIRECT, CF_TMP_REDIRECT, CF_WORKER_ROUTE to comply with the new way to do custom record types.
  • New functions ZoneifyQuoted, Zoneify, etc. are standard ways to create zonefile-compatible strings.

Sincerely,
--Tom Limoncelli

Monthly video call!

Everyone is invited to the Monthly DNSControl Community Video Conference Call on the 2nd Tuesday of each month. Join whether you are a new user with questions or an experienced developer that wants to discuss DNSControl internals... or anything in between! Meeting details on
GitHub Discussions.

Changelog

Major features:

Provider-specific changes:

Documentation:

CI/CD:

Dependencies:

Other changes and improvements:

Deprecation warnings

Warning

  • REV() will switch from RFC2317 to RFC4183 sometime after v5.0 is released. This is a breaking change. Warnings are output if your configuration is affected. See https://docs.dnscontrol.org/language-reference/top-level-functions/revcompat
  • NAMEDOTCOM, OPENSRS and SOFTLAYER need maintainers! 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.

Install

macOS and Linux

Install with Homebrew (recommended)
brew trust --formula dnscontrol/tap/dnscontrol
brew install DNSControl/tap/dnscontrol
Using with Docker

You can use the Docker image from Docker hub or GitHub Container Registry. 

docker run --rm -it -v "$(pwd):/dns" ghcr.io/dnscontrol/dnscontrol preview

Anywhere else

Alternatively, you can install the latest binary (or the apt/rpm/deb/archlinux package) from this page.

Or, if you have Go installed, you can install the latest version of DNSControl with the following command: 

go install github.com/DNSControl/dnscontrol/v4@main

Update

Update to the latest version depends on how you choose to install dnscontrol on your machine.

Update with Homebrew

brew upgrade DNSControl/tap/dnscontrol

Alternatively, you can grab the latest binary (or the apt/rpm/deb package) from this page.

Check out latest releases or
releases around DNSControl/dnscontrol v5.0.0

Don't miss a new dnscontrol release

NewReleases is sending notifications on new releases.

Get notifications