README.md

azone

DNSSEC zone signing and key management command-line tool. This bash wrapper script simplifies the use of NSD, an authoritative-only DNS nameserver, and some of its related ldns tools.

Purpose

For those wanting to operate their own authoritative DNS server while also implementing DNSSEC, the number of moving parts involved, all the functions, options, parameters, etc. of the numerous dnssec-* or ldns-* CLI tools one would have to remember, makes it a much more involved, cumbersome, and time consuming task than it really needs to be.

Surprisingly, there aren't a whole lot of simple free or open source tools out there (that I could find) that streamlines all of this for anyone wanting to self-host their domains.

Which is why I ended up building up an unorganized set of shell functions over time, just for my own use. Once the complexity of it all got past the point of your typical ease-of-use shortcuts (and everything still seemed to work fine), I figured I might as well gather up the scattered scripts/functions and turn it into a simple CLI tool that others could also use.

Features

• Straight forward key generation & zone signing
• Automated directory organization of keys and zones
• One command to push all changes to live NSD server
• Auto-increments SOA serial value
• Maintains cron file for weekly zone re-signing
• Import and sort existing keys
• DNSSEC chain validation
• Supports Handshake domains

Requirements

Of course, having an authoritative nameserver is the main requirement. This tool is just a wrapper of certain NSD & ldns commands.

Either build from source using instructions from nlnetlabs/nsd and nlnetlabs/ldns or get them via your package manager:

• Debian/Ubuntu

  sudo apt install nsd ldnsutils

• Fedora

  sudo yum install nsd ldns

• FreeBSD

  sudo pkg install nsd ldns

• Homebrew/Linuxbrew

  brew install nsd ldns

The script won't work out-of-the-box if you're using something like BIND & dnssec-tools. If you don't want to use NSD, the azone update command won't do anything. As long as you have ldns installed, everything else should work fine and you can manually relay changes or set configs for your preferred DNS server as needed.

Install

Donwload

git clone https://github.com/nlydv/azone.git
sudo rm -rf azone/.git

Since you'll be storing zonefiles and generating keys into the directory, it's best to avoid accidental git operations that could delete everything. Hence removing the .git directory.

see #updating for how to upgrade to a new version without using git

Move stuff

sudo mv azone/azone /usr/local/bin
sudo mv azone /etc/nsd

You can move the script to wherever you like that's accessible via your $PATH variable, /usr/local/bin is just a common spot.

The script does have its ZONEDIR variable hardcoded to be /etc/nsd/azone though, if you want to change that just edit that variable in the script. There's a few a other configurable locations at the top of the script too.

You should get the whole repo because it also contains a set of files with root trust anchor keys under data/ that are needed to use the azone test command. The rest of the files and directory structure will be generated by the script itself.

Usage

azone help has pretty straight forward descriptions of the commands:

Notes on specific comands

• import will only find existing keys that follow the K<name>+<alg>+<id> naming scheme
• test -g or "global" DNSSEC validation, may act finicky... I think that might have to do with how ldns-verify-zone uses /etc/resolv.conf to do recursive resolution
• keygen always creates
  • ECDSAP256SHA256 keys (aka DNSKEY algo #13)
  • SHA-256 key digests (aka DS algo #2)

General usage notes

• ZONE should be the fully-qualified domain name (FQDN) of interest, without trailing dot.

• By default, the associated plain zone file should also simply be named ZONE rather than the common naming schemes of ZONE.zone or ZONE.txt for simplicity's sake and because errors may occur with domains underneath the .zone or .txt TLDs.

• Plain zonefiles should be placed in the top directory /etc/nsd/azone.

• This script DOES NOT manage or update or create the actual plain zonefiles, only signed zonefiles. You should make those manually (or with some other program).

• This script can handle auto-incrementing your zones' SOA serial numbers every time it gets signed. Just place SIGNED_ON where the actual serial number would otherwise go in your plain zone files.

• There's a dynamic cron file at data/azone.cron that auto re-signs live zones every week. Move/symlink to wherever your crons go, if you have an /etc/cron.d dir it's already symlinked. In any case, RRSIGs created with azone have a shelf life of 36.5 days.

• auto re-signing can't be guaranteed out-of-the-box so just make sure your cron/whatever setup works properly

Updating

If you followed the directions in the install section, deleting the .git directory means you can't just pull a new commit via git (which you don't want to do anyways).

Instead, to get a newer version, pull the raw script to wherever you originally placed it. Assuming you saved it to /usr/local/bin:

sudo curl https://raw.githubusercontent.com/nlydv/azone/master/azone > /usr/local/bin/azone

Forewarnings

Can't guarantee this script is 100% portable.
Tested on:

• Ubuntu 18.04 & 20.04
• Bash 4.4.20
• NSD 4.1.17
• ldns 1.7.0

Development

Since this tool originally started as a few simple helper functions, the use of Bash was perfectly ok at first. Now that they've been amalgamated into a single monolothic, open-sourced executable... Bash isn't so ideal, especially if more functionality is going to be added.

I may or may not convert this to a NodeJS package in the near future so that I can more easily use it as part of another project.

Contributions/suggestions always welcome though.

License

This project is licensed under the terms of the MIT license (see LICENSE file published therein).