systemd-resolved-rs 0.2.1

# systemd-resolved-rs

`systemd-resolved-rs` 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.

> **Release 0.2.1 certification:** this release is undergoing a fresh
> source-bound replacement certificate after the version bump. Do not replace
> the host resolver with this checkout until the new exact-source certificate
> is published.

A green build is necessary but is not a parity certificate. Only the exact
source tree named by the newest passing certificate is authorized for
replacement; every later commit requires a new exact-source certificate.

## 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.freedesktop.resolve1` Manager and Link objects whose introspection
  is checked against pinned manifests;
- core `io.systemd.Resolve` Varlink resolution and maintenance methods;
- per-link netlink and systemd-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 transport and policy machinery, with remaining end-to-end parity
  tracked in the compatibility ledger;
- DNSSEC record parsing, canonicalization, digest, and signature-verification
  primitives, with full trust-chain behavior still release-blocking;
- 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, and Varlink lookups through the production executable path.

## Release-blocking work

`docs/COMPATIBILITY.md` is the source of truth. Major remaining work includes
complete Varlink and `resolvectl` behavior, NSS integration parity, complete
DNSSEC trust-chain handling, remaining LLMNR conflict/cache behavior,
remaining mDNS and DNS-SD edge semantics, upstream differential suites,
network lifecycle scenarios, and transactional installation and rollback
validation.

Unchecked ledger entries must not be inferred complete merely because related
source modules or unit tests exist.

## 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
`SYSTEMD_NSS_RESOLVE_SHM=/path/to/cache` and
`SYSTEMD_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 and are exercised by all-feature development tests,
but they are not linked into release or replacement-certification artifacts.

## Language boundaries

| Language | Responsibility |
| --- | --- |
| 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 --all-features --locked -- -D warnings
cargo test --all-targets --all-features --locked
cargo build --release --locked
python3 tests/live-dns.py \
  target/release/systemd-resolved \
  target/release/resolvectl
make check-formal
```

## Safe development run

Use an unprivileged port and private runtime directory while developing:

```sh
cargo run --bin systemd-resolved -- \
  --port 1053 \
  --runtime-directory /tmp/systemd-resolved-rs \
  --varlink /tmp/systemd-resolved-rs/io.systemd.Resolve \
  --no-dbus

cargo run --bin resolvectl -- \
  --socket /tmp/systemd-resolved-rs/io.systemd.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 & 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.

This will safely vendor dependencies to `crates-vendor/` (preserving any local patches in `vendor/`), update your Cargo config, and build a `.orig.tar.gz` and `_source.changes` file ready for `dput`.

## Installation layout

The current Makefile installs:

- `/usr/lib/systemd/systemd-resolved`
- `/usr/bin/resolvectl`
- `/usr/lib/systemd/system/systemd-resolved.service`
- `/usr/lib/systemd/system/systemd-resolved-varlink.socket`
- `/usr/lib/tmpfiles.d/systemd-resolved.conf`

Installation is authorized only for the newly certified source tree and its
matching certificate bundle. Distribution packages and host replacement
procedures must retain the clean install, upgrade, rollback, and recovery
evidence.

## 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.