lainos-dns-mediation

DNS mediation architecture for lainOS Layer 03 ~ a split-controller DNS stack built around three real, independently-swappable pieces: dnsmasq for stateless forwarding, unbound for validation and caching, and dnscrypt-proxy for encrypted, anonymized upstream resolution. Ships with lainos-dns and private-mode, two orchestration scripts that switch the whole chain between modes cleanly, with no manual config editing required.

Why this exists

Most distros hand you a single /etc/resolv.conf and call it done. That's fine until you actually care about who sees your DNS queries ~ your ISP, a coffee shop's router, or the resolver itself. lainos-dns-mediation treats DNS as a real, layered problem:

• dnsmasq never talks to the internet directly. It's a thin, stateless local forwarder that your applications actually query.
• unbound does the real work of DNSSEC validation and caching, and decides where queries actually go next.
• dnscrypt-proxy is the only piece that ever touches the open internet for DNS, and it does so encrypted, over anonymized relays when configured, so no single hop sees both who you are and what you're resolving.

Each piece can be swapped, disabled, or bypassed without touching the others. That's the whole point.

Modes

Controlled by lainos-dns {plaintext|encrypted|private|status}.

plaintext

The default, low-friction mode. dnsmasq forwards directly to whatever DNS servers your DHCP lease or config specify. No unbound, no dnscrypt-proxy running. Fast, simple, not private.

encrypted

dnsmasq forwards to unbound (127.0.0.1:5053), which forwards to dnscrypt-proxy (127.0.0.1:5300), which does the actual upstream resolution over DNSCrypt, optionally routed through anonymization relays. Your DNS queries are encrypted in transit and, with relays configured, no single relay operator can see both your IP and the domains you're resolving.

private

Used automatically by private-mode (see below). dnsmasq points directly at Tor's own DNSPort, so DNS resolution happens entirely inside the Tor circuit alongside the rest of your traffic. unbound and dnscrypt-proxy are stopped in this mode since they serve no purpose once Tor owns DNS resolution.

status

Shows the current mode, whether each service is actually running (not just what the config file says), and runs a real resolution test so you know DNS genuinely works, not just that the services started.

private-mode

private-mode {on|off|status} is the bigger picture this DNS mediation stack plugs into. Turning it on:

1. Takes WiFi/ethernet down cleanly
2. Enables Snowflake pluggable transport bridges for Tor (helps in censored or restrictive network environments)
3. Enables sdwdate, a Tor-based time sync that avoids leaking your clock/timezone to a plaintext NTP server
4. Brings networking back up with a randomized MAC address
5. Bootstraps DNS through the encrypted chain first (dnscrypt-proxy + unbound) while Tor itself bootstraps, so no plaintext DNS ever leaks during the transition window
6. Once Tor's own DNSPort is confirmed ready with a real resolution test, switches dnsmasq over to private mode
7. Stops unbound/dnscrypt-proxy, since Tor now owns DNS entirely

Turning it off reverses cleanly, restoring whatever DNS mode was active before you turned private-mode on.

Requirements

• net-dns/dnsmasq, net-dns/unbound, net-dns/dnscrypt-proxy (real accounts via acct-user/acct-group, not shared with any other service)
• net-dns/bind (for dig, used by private-mode's Tor DNSPort readiness check)
• net-proxy/snowflake (from the GURU overlay) for the Snowflake pluggable transport, used by private-mode
• net-vpn/tor

Installation notes

This package deliberately does not install its dnsmasq.conf, unbound.conf, or dnscrypt-proxy.toml directly onto the paths those base packages already own. Doing so causes a real Portage file collision the moment this package is pulled in as a dependency rather than emerged standalone. Instead, each is installed under a .lainos-dns suffixed name and copied onto the live path in pkg_postinst. If you're building a downstream ebuild against this repo, keep that pattern ~ don't newins straight onto a path a base daemon package already owns.

If you're on a Gentoo profile where /lib isn't a merged-usr symlink to /usr/lib, fix that first. Both dhcpcd's hook runner and openresolv's own subscriber-notification script hardcode /lib/... paths internally, and DNS resolution will silently fail to write /etc/resolv.conf at all without it, with no error anywhere in the boot log to point you at the cause.

Known limitations

• private-mode's Tor DNSPort readiness check needs real dig. net-dns/bind-tools is masked upstream by Gentoo (deprecated since Bind 9.18), so this pulls in the full net-dns/bind package. A lighter alternative using drill (from net-dns/unbound, already a dependency) was tried and found unreliable in practice, so dig stays the supported path for now.
• Snowflake bridge connections can be flaky depending on the current pool of available proxies. private-mode waits for a real, working Tor circuit rather than just a bootstrap percentage, so it may take longer than the bootstrap log alone suggests.
• iwd is intentionally excluded from lainOS's default startup chain. WiFi stays off until manually enabled. private-mode and lainos-wifi-dns both work with this, not around it.

License

GPLv3