resolved
resolved (pronounced "resolved", not "resolved") is a simple DNS server for home networks. To that end, it supports:
- Recursive and non-recursive resolution
- Caching
- Hosts files
- Zone files
It does not support querying upstream nameservers over IPv6: I don't have IPv6 at home, so this code doesn't support it yet.
Usage
The DNS Server
I use resolved for my home network with no problems, but it may not work for you. You also probably don't want to expose this to the internet!
Compile it in release mode and run it like so:
cargo build --release
sudo ./target/release/resolved -Z config/zones
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.
See the --help text for options.
Signals:
SIGUSR1- reload the configuration
Monitoring:
- Prometheus metrics are exposed at
http://127.0.0.1:9420/metrics - Log level can be controlled with the
RUST_LOGenvironment variable:RUST_LOG=trace- verbose messages useful for development, like "entered function X"RUST_LOG=debug- warns about strange but recoverable situations, like "socket read error"RUST_LOG=info- gives top-level information, like "new connection" or "reloading configuration"RUST_LOG=warn- warns about recoverable internal errors and invalid configuration, like "could not serialise message" or "invalid record in cache"RUST_LOG=error- warns about fatal errors and then terminates the process, like "could not bind socket"
- Log format can be controlled with the
RUST_LOG_FORMATenvironment variable, which is a sequence of comma-separated values:- One of
full(default),compact,pretty, orjson- see the tracing_subscriber crate - One of
ansi(default),no-ansi - One of
time(default),no-time
- One of
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
The project structure should hopefully be fairly straightforward. The modules are:
-
lib-dns-types- basic types used in other packageshosts- hosts filesprotocol- the DNS message types and serialisation / deserialisation logiczones- authoritative and non-authoritative zones
-
lib-dns-resolver- the DNS resolverscache- the cacheforwarding- the forwarding resolvermetrics- resolver-specific metricsnonrecursive- the non-recursive resolverrecursive- the recursive resolverutil- shared types and functions
-
bin-resolved- the DNS server -
bin-htoh- utility to normalise hosts files -
bin-htoz- utility to convert hosts files to zone files -
bin-ztoh- utility to convert zone files to hosts files -
bin-ztoz- utility to normalise zone files
Testing
Run the unit and integration 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
Supported standards
-
RFC 1034: Domain Names - Concepts and Facilities
Gives the basic semantics of DNS and the algorithms for recursive and non-recursive resolution.
-
RFC 1035: Domain Names - Implementation and Specification
Defines the wire format and discusses implementation concerns of the algorithms from RFC 1034.
-
RFC 2782: A DNS RR for specifying the location of services (DNS SRV)
Defines the
SRVrecord and query types. -
RFC 3596: DNS Extensions to Support IP Version 6
Defines the
AAAArecord and query types. -
RFC 4343: Domain Name System (DNS) Case Insensitivity Clarification
Clarifies that domain names are not ASCII, and yet for case insensitivity purposes are case-folded as ASCII is. And also that "case preservation", as required by other RFCs, is more or less meaningless.
-
RFC 6761: Special-Use Domain Names
Defines several zones with special behaviour. This is RFC implemented as configuration distributed with the DNS server (in
config/zones) not code. -
Defines the Linux hosts file format.
246 Dec 20, 2022
2.7k Dec 30, 2022
3 Jul 27, 2023
5 Aug 3, 2023
32 Oct 6, 2023
142 Oct 23, 2023
4 Mar 19, 2024
1 Dec 6, 2021
24 Dec 1, 2022
2 Sep 22, 2021
1k Jan 3, 2023
2 Feb 4, 2022
2 Nov 13, 2021
5 May 24, 2022
8 Aug 30, 2022
1 Mar 15, 2022
7 Aug 23, 2022
94 Oct 18, 2022
30 Dec 22, 2022