# RustD-Resolved
`rustd-resolved` is the Rustd network name resolver. It is a
compatibility-oriented reimplementation of `systemd-resolved` built from Rust,
C, Fortran, Idris, and Agda. The target is behavioral and interface parity with
the pinned upstream resolver, including its local DNS stubs, D-Bus and Varlink
APIs, per-link routing, command-line programs, security behavior, protocol
support, installation contract, and recovery behavior.
> **Current certification status:** the naming migration requires a fresh
> exact-source replacement certificate. Do not replace the host resolver with
> the current head until that certificate and its matching evidence bundle are
> green, cryptographically authenticated to the expected repository/workflow,
> and accepted by an administrator-controlled trust root. That authentication
> is not implemented yet, so transactional install mode currently refuses to
> modify the host even when a schema-3 bundle is internally consistent.
A green build is necessary but is not a parity certificate. Only the exact
source tree named by the newest passing certificate can be considered for
replacement; every later commit requires a new exact-source certificate. A
self-consistent certificate is not authorization because a clean-checkout user
can fabricate its unsigned gate records and hashes.
The native executables are `rustd-resolved` and `rustd-resolvectl`. Installation
also provides `rustd-resolved`, `resolvectl`, `rustd-resolve`, and
`resolvconf` as compatibility aliases to the same implementation. Upstream
D-Bus, Varlink, NSS, service-account, unit, configuration, and filesystem names
remain compatibility contracts so existing software continues to work without
modification.
## Supported platform
Arch Linux and compatible Arch-based distributions are the only supported
release and maintenance targets. Package layout, resolver integration, and
replacement procedures are tested against the Arch systemd layout; other
distributions are outside the maintenance promise.
## Verified foundation
- bounded DNS packet, name-compression, question, and resource-record parsing;
- UDP and TCP full-stub service, with a separate proxy-stub mode;
- `/etc/hosts`, localhost, numeric-address, `_localdnsstub`, and
`_localdnsproxy` synthesis;
- positive and RFC 2308 negative caching with TTL aging, bounded eviction,
optional stale retention, transaction-ID isolation, and TSIG exclusion;
- UDP upstream queries with response identity validation and TCP retry after
truncation;
- generated runtime `stub-resolv.conf` and uplink `resolv.conf` files;
- systemd readiness, reload, stopping, and watchdog notifications;
- live `org.rustd.resolve1` Manager and Link objects whose introspection
is checked against pinned manifests;
- complete `io.rustd.Resolve` and `io.rustd.Resolve.Monitor` Varlink
compatibility surfaces;
- per-link netlink and rustd-networkd state, split DNS, and routing-domain
scoring;
- independent DNS delegate scopes with layered configuration, longest-suffix
routing, firewall-marked sockets, and live D-Bus/Varlink exposure;
- DNS-over-TLS opportunistic and strict transport behavior;
- DNSSEC validation, trust-anchor management, and authenticated denial;
- dual-stack LLMNR and mDNS resolver/responder behavior plus DNS-SD;
- NSS integration through `libnss_resolve.so.2` and the upstream Varlink path;
- a compiled Fortran routing-domain scoring ABI, an Idris policy model, and
Agda DNS-name and transaction invariants;
- deterministic live CI coverage for UDP, TCP, proxy-stub, generated resolver
files, NSS, D-Bus, Varlink, network lifecycle, installation, and rollback.
## Release gate
`docs/COMPATIBILITY.md` is the source of truth for implemented behavior and
required validation. The current source may claim hash-consistent replacement
readiness only after the full workflow fleet publishes a new certificate for
the exact commit being installed. Actual host authorization additionally
requires authenticated artifact provenance or a complete
administrator-trusted local rerun; the current installer remains blocked until
that trust root is implemented. Renaming a package, binary, unit alias,
internal ABI symbol, or source path invalidates an older certificate even when
runtime behavior is intended to remain unchanged.
## Beyond parity
Enhancements that are not part of upstream compatibility are developed behind
clear boundaries and must remain opt-in until independently validated. Current
research areas include sharded caching, stale-while-revalidate, aggressive
negative caching, shared-memory NSS acceleration, pooled transports, richer
metrics, and flight-recorder diagnostics. Compatibility mode remains the
reference behavior; an optimization may not change externally observable
semantics.
The NSS shared-memory and direct DNS-stub fast paths are disabled by default so
the module follows upstream Varlink and `nsswitch.conf` fallback semantics.
Research deployments can opt into them with
`RUSTD_NSS_RESOLVE_SHM=/path/to/cache` and
`RUSTD_NSS_RESOLVE_STUB=address:port` respectively.
The default feature set builds the production compatibility path, including
IDNA handling and the Fortran routing kernel. The `hyper` and `supremacy`
research stacks are opt-in. `supremacy` currently contains experimental
transport scaffolding: its DoH and DoQ pool methods fail closed with an
explicit unsupported result, so that feature is not part of the replacement
path. All-feature development checks verify that research code still compiles;
they are not evidence of upstream parity and are not used by release or
replacement-certification artifacts. The release feature boundary is enforced
by `tests/release_feature_boundary.sh`.
## Language boundaries
| Rust | daemon, DNS wire engine, cache, transports, configuration, and CLIs |
| C | Linux signal, notification, inherited-descriptor, crypto, and peer-credential ABI |
| Fortran | deterministic routing-domain scoring kernel |
| Idris | total resolver-policy model |
| Agda | proof-oriented wire, pointer, bound, and TTL invariants |
See `docs/ARCHITECTURE.md` for the boundary contracts.
## Build and test
Install the Arch toolchain and formal-check dependencies with:
```sh
sudo pacman -S --needed base-devel rust cargo gcc-fortran openssl idris2 agda
```
The required build tools are Rust 1.74 or newer, a C17 compiler, GNU Fortran
with Fortran 2018 support, OpenSSL development files, and `ar`.
```sh
make check-native
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo build --release --locked
python3 tests/live-dns.py \
target/release/rustd-resolved \
target/release/rustd-resolvectl
make check-formal
```
Research-only feature compilation is a separate hygiene check and must not be
used as replacement evidence:
```sh
cargo check --all-targets --all-features --locked
```
The live command above intentionally exercises the upstream compatibility
entry points. The same build also produces `target/release/rustd-resolved` and
`target/release/rustd-resolvectl`.
## Safe development run
Use an unprivileged port and private runtime directory while developing:
```sh
cargo run --bin rustd-resolved -- \
--port 1053 \
--runtime-directory /tmp/rustd-resolved \
--varlink /tmp/rustd-resolved/io.rustd.Resolve \
--no-dbus
cargo run --bin rustd-resolvectl -- \
--socket /tmp/rustd-resolved/io.rustd.Resolve \
query example.com
```
The replacement installer is a release gate, not a development shortcut. Do
not overwrite the host resolver, NSS module, or resolver policy files manually.
## Packaging and distribution
Arch packages are built from the locked source tree and published through the
Sisyphus repository. Keep Cargo dependencies locked and reproduce the package
with the Arch packaging checks before publishing.
## Installation layout
The native installation provides:
- `/usr/lib/rustd/rustd-resolved`
- `/usr/bin/rustd-resolvectl`
- `rustd-resolved.service` and matching socket aliases
Drop-in compatibility also provides:
- `/usr/lib/rustd/rustd-resolved`
- `/usr/bin/resolvectl`
- `/usr/bin/rustd-resolve`
- `/usr/sbin/resolvconf`
- `/usr/lib/rustd/system/rustd-resolved.service`
- `/usr/lib/rustd/system/rustd-resolved-varlink.socket`
- `/usr/lib/rustd/system/rustd-resolved-monitor.socket`
- `/usr/lib/tmpfiles.d/rustd-resolved.conf`
Installation will be authorized only for an exact source tree with a matching,
authenticated certificate bundle. Distribution packages and host replacement
procedures must retain the clean install, upgrade, rollback, and recovery
evidence. Until certificate provenance verification is implemented, install
mode fails closed before making host changes.
## Compatibility baseline
The pinned reference is the official systemd v261 release at
`systemd/systemd` commit `de9dbc37ad4aa637e200ac02a0545095997055df`.
See `docs/UPSTREAM_BASELINE.md` before changing it.
## License
GNU Lesser General Public License 2.1 or later.