Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

resolved

resolved (pronounced "resolved", not "resolved") is a simple DNS server, and associated tools, for home networks. To that end, it supports:

  • Three modes of operation: as a recursive or forwarding nameserver (with caching) or as an authoritative nameserver for your specified domains only.
  • Defining custom records in hosts files (to make existing DNS blacklists each to use) and in zone files.
  • Listening on either IPv4 or IPv6, and communicating with upstream nameservers over both.

Usage

Install rustup, and then install the default toolchain:

rustup show

Then, compile in release mode;

cargo build --release

The DNS Server

Danger

resolved hasn't had any sort of security review, so be wary of exposing it on a public network.

Since resolved binds to port 53 (both UDP and TCP), it needs to be run as root or to have the CAP_NET_BIND_SERVICE capability.

sudo ./target/release/resolved -Z config/zones

The config/zones directory contains standard configuration which you'll usually want to have (such as the "root hints" file), so you would typically either put your zone files in config/zones, or put them somewhere else and pass a second -Z option like so:

sudo ./target/release/resolved -Z config/zones -Z /path/to/your/zone/files

See the CLI documentation for more.

The DNS Client

There is also a dnsq utility to resolve names based on the server configuration directly. The main purpose of it is to test configuration changes.

$ ./target/release/dnsq www.barrucadu.co.uk. AAAA -Z config/zones
;; QUESTION
www.barrucadu.co.uk.    IN      AAAA

;; ANSWER
www.barrucadu.co.uk.    300     IN      CNAME   barrucadu.co.uk.
barrucadu.co.uk.        300     IN      AAAA    2a01:4f8:c0c:bfc1::

See the --help text for all options.

Other Tools

There are also four utility programs (htoh, htoz, ztoh, and ztoz) to convert between hosts files and zone files.

They accept any syntactically valid file as input, and output it in a consistent format regardless of how the input is structured, so htoh and ztoz can be used to normalise existing files.

Development

Rust sources are in the crates/ directory. There are two shared libraries:

And six binaries:

Developing with nix

Open a development shell:

nix develop

And run cargo commands in there.

Testing

Run the unit tests with:

cargo test

There are also fuzz tests in the fuzz/ directory, using cargo-fuzz:

cargo install cargo-fuzz

# list targets
cargo fuzz list

# run a target until it panics or is killed with ctrl-c
cargo fuzz run <target>

Supported standards