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

See docs/ARCHITECTURE.md for the boundary contracts.

Build and test

Install the Arch toolchain and formal-check dependencies with:

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.

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:

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:

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.