alexion/dev
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
bf99d3093476a58c4ce864d531364e444ab2bee7
dev/docs/00 INBOX/ai/adguard-pikachu-migration-design-tree.md

7.9 KiB
Raw Blame History

AdGuard migration to Pikachu: design tree

Research facts

  • The pinned Nixpkgs revision provides adguardhome version 0.107.79.
  • NixOS provides the services.adguardhome module.
  • The module runs AdGuard Home as a hardened dynamic systemd user.
  • It stores state in /var/lib/AdGuardHome.
  • It grants CAP_NET_BIND_SERVICE for DNS port 53.
  • It grants CAP_NET_RAW when AdGuard Home DHCP is enabled.
  • The module supports an arbitrary YAML configuration through settings.
  • The module supports fully declarative operation with mutableSettings = false.
  • In fully declarative operation, the module replaces /var/lib/AdGuardHome/AdGuardHome.yaml on each service start.
  • Fully declarative operation requires dns.bootstrap_dns as a list.
  • Declarative settings pass an AdGuard configuration check during the build.
  • mutableSettings = true merges declared settings into UI changes at service start.
  • mutableSettings = false replaces the state configuration on every service start.
  • openFirewall opens only the web interface port.
  • The migration must explicitly open DNS ports 53/TCP and 53/UDP when clients need them.
  • Pikachu has address 10.23.10.102 on its untagged network.
  • Pikachu carries VLAN 20 and creates bridge br-vlan20.
  • The guest framework runs each guest in its own systemd-nspawn container.
  • Each guest attaches to a host VLAN bridge and receives an address through DHCP.
  • Pikachu currently configures only VLAN 20 for guests.
  • The repository has no AdGuard configuration, Proxmox inventory, or DHCP-provider configuration.
  • The current DHCP provider remains unestablished.
  • The current Proxmox AdGuard container uses MAC bc:24:11:91:60:bf.
  • The current Proxmox AdGuard container uses address 10.23.20.33 on VLAN 20.
  • This environment has no Proxmox SSH target or local Proxmox control utility.
  • The current AdGuard configuration listens on all guest addresses at DNS port 53.
  • The current AdGuard configuration has no allowed-client or disallowed-client restrictions.
  • The current AdGuard configuration uses Cloudflare, Google, and Quad9 encrypted upstreams in parallel.
  • The current AdGuard configuration disables DNSSEC.
  • The current AdGuard configuration defines three local rewrites.
  • The repository configures no host backup system or monitoring system.
  • Hosts update through explicit nixos-rebuild switch --flake commands.
  • The working tree has unrelated operator changes.

Service tradeoffs

Service NixOS support Domain filtering Administration UI DHCP Encrypted DNS Main tradeoff
AdGuard Home services.adguardhome; checked YAML and mutable or immutable state Native block lists, rules, and per-client policy Native Native Upstream and client-facing encrypted DNS Direct migration with the closest state and feature match. UI state conflicts with fully declarative operation unless configuration is immutable.
Blocky services.blocky; checked declarative YAML Native lists, allow lists, rewrites, and per-client groups No UI; REST API and metrics only No Encrypted upstreams and client-facing DoH, DoT, and DoQ Strong Git-managed configuration and low operational surface. It lacks an interactive administration interface and DHCP.
Pi-hole services.pihole-ftl plus services.pihole-web; declarative TOML, lists, and dashboard Native gravity lists, allow lists, regex rules, and groups Native Native Use a companion for encrypted upstream DNS Familiar filtering product with a dashboard. The migration changes product data and uses more coupled services.
Technitium DNS Server services.technitium-dns-server; service and firewall options only Native block lists and DNS applications Native Native Upstream and client-facing encrypted DNS Broadest DNS feature set, including authoritative DNS. NixOS does not expose its runtime configuration declaratively.
Unbound services.unbound; structured server and free-form settings Local zones or response-policy zones require custom policy management No No DNS-over-TLS support Mature validating recursive resolver. Filtering and user operations require separate design.
dnscrypt-proxy services.dnscrypt-proxy; declarative TOML Local block and allow rules, without a list-management UI No No Encrypted upstream DNS, including DNSCrypt and DoH Strong upstream privacy and resolver selection. It is not a full network filtering appliance.
Knot Resolver services.kresd; structured listener settings and extra Lua Custom policy modules No No Client-facing DoH and TLS listeners Flexible high-performance recursive resolver. Filtering requires resolver expertise and custom policy.
SmartDNS services.smartdns; free-form settings Domain and address rules No NixOS-integrated UI No Encrypted upstream and client-facing DNS Optimizes upstream selection and latency. It offers less complete filtering management than dedicated blockers.

Native means that the product provides the feature without a companion service.

Decision tree

  • D1 — DNS service product [settled]
    • Retain AdGuard Home on Pikachu.
      • Constraint: Preserve AdGuard Home as the DNS service product.
      • D2A — AdGuard Home role [settled]
        • Provides DNS filtering and resolution only.
        • Constraint: The existing DHCP provider continues to assign addresses and DHCP options.
      • D3A — Execution placement [settled]
        • Runs in a dedicated guest on Pikachu's existing VLAN 20.
        • Constraint: Isolate AdGuard Home from the Pikachu host.
      • D4A — Guest network identity [settled]
        • Reuses MAC bc:24:11:91:60:bf and address 10.23.20.33 on VLAN 20.
        • Constraint: Stop the Proxmox container before the guest starts.
      • D5A — Network exposure [settled]
        • Listens on all guest addresses at port 53.
        • Accepts requests from every reachable internal device.
      • D6A — Resolver policy [settled]
        • Preserves the existing upstream resolvers and parallel resolver mode.
        • Preserves disabled DNSSEC and the three local rewrites.
      • D7A — Configuration authority [settled]
        • Uses fully declarative Nix configuration.
        • Constraint: Set services.adguardhome.mutableSettings = false.
        • Constraint: Declare dns.bootstrap_dns as a list.
        • Constraint: Web UI changes do not persist.
        • Constraint: Match existing service behavior except for the administrator password.
      • D8A — Migration data [settled]
        • Migrate functional DNS configuration only.
        • Constraint: Do not migrate query history or statistics.
      • D9A — Operations [settled]
        • Declares a newly generated bcrypt verifier in Nix.
        • Constraint: Keep the plaintext password outside the repository and Nix store.
        • Constraint: The verifier is readable from the Nix store.
      • D10A — Cutover and rollback [settled]
        • Uses a planned atomic cutover with rollback.
        • Stop the Proxmox container before starting the guest.
        • Validate the guest before restoring the Proxmox container during rollback.
      • D11A — Runtime-state backup [settled]
        • Do not back up rebuildable AdGuard Home runtime state.
      • D12A — Monitoring [settled]
        • Do not add DNS availability monitoring.
      • D13A — Upgrade ownership [settled]
        • The normal flake update and explicit NixOS rebuild workflow owns upgrades.
    • Replace AdGuard Home. [not selected]
      • D2B — Replacement product [not applicable]
        • Choose Blocky, Pi-hole, Technitium, or a composed resolver.

Frontier

None.

Sources

  • Pinned Nixpkgs module: nixos/modules/services/networking/adguardhome.nix.
  • Pinned Nixpkgs modules: blocky.nix, pihole-ftl.nix, pihole-web.nix, technitium-dns-server.nix, unbound.nix, dnscrypt-proxy.nix, knot-resolver.nix, and smartdns.nix.
  • AdGuard Home README, release v0.107.79.
  • Technitium DNS Server README, current upstream.
Reference in New Issue View Git Blame Copy Permalink