Installation, Betrieb
und Kontrolle.

01 · Überblick

Was RootGuard bereitstellt

RootGuard kombiniert AdGuard Home als Netzwerkfilter mit Unbound als eigenem rekursiven und DNSSEC-validierenden Resolver. WebApp und Core verwalten den Stack; ein separater Updater tauscht Core und WebApp sicher als Paar aus.

02 · Voraussetzungen

Bevor du beginnst

• Docker Engine oder Docker Desktop mit Docker Compose v2
• Eine feste LAN-IP oder DHCP-Reservierung für den RootGuard-Host
• Freier TCP- und UDP-Port 53 auf der gewählten Host-Adresse
• Git für Repository und Submodule
• Ein starkes Admin-Passwort und ein zufälliges internes API-Token

03 · Installation

Control Plane starten

mkdir rootguard-alpha && cd rootguard-alpha
curl -LO https://raw.githubusercontent.com/foxly-it/rootguard/v0.1.0-alpha.2/compose.alpha.yaml
curl -Lo .env https://raw.githubusercontent.com/foxly-it/rootguard/v0.1.0-alpha.2/.env.alpha.example
openssl rand -hex 32
openssl rand -hex 32
docker compose -f compose.alpha.yaml up -d

Trage zwei getrennt erzeugte Zufallswerte als ROOTGUARD_API_TOKEN und ROOTGUARD_RECOVERY_TOKEN sowie ein eigenes starkes ROOTGUARD_ADMIN_PASSWORD in .env ein. Die Alpha lädt versionierte amd64-/arm64-Images aus GHCR; ein Checkout oder lokaler Build der Komponenten ist nicht erforderlich. Die Control Plane startet zuerst, die DNS-Dienste werden anschließend im Setup erzeugt.

http://localhost:8080/login

04 · Erste Einrichtung

DNS-Stack geführt bereitstellen

1. 1
   Anmelden

   Verwende ROOTGUARD_ADMIN_USER und ROOTGUARD_ADMIN_PASSWORD. Die Sitzung bleibt serverseitig geschützt und läuft nach zwölf Stunden ab. Ab 0.1.0-alpha.2 bietet „Passwort vergessen?“ zusätzlich eine lokale Wiederherstellung mit einem separaten Recovery-Schlüssel.

2. 2
   Host-Adresse wählen

   Wähle eine bereits vorhandene LAN-IP. 0.0.0.0 bindet alle Host-Adressen, eine konkrete LAN-IP begrenzt die Erreichbarkeit enger.

3. 3
   Vorprüfung ausführen

   RootGuard prüft Adresse, Port, Docker Engine und Compose, bevor Container verändert werden.

4. 4
   Bereitstellen

   Unbound wird gestartet und geprüft, danach AdGuard Home intern eingerichtet und ausschließlich mit Unbound als Upstream verbunden.

05 · Router & Clients

RootGuard im Netzwerk verwenden

Trage die im Setup angezeigte feste Host-IP als DNS-Server im Router ein. Verwende niemals 127.0.0.1 oder die interne Docker-Adresse 172.29.53.2 auf anderen Geräten. Port 53 muss für TCP und UDP erreichbar sein.

dig @192.168.178.10 example.com A
dig +dnssec @192.168.178.10 dnssec-failed.org A

Die erste Abfrage muss eine Adresse liefern. Die zweite muss mit SERVFAIL enden; dadurch wird eine ungültige DNSSEC-Kette korrekt verworfen.

06 · WebGUI

Die Bereiche der Oberfläche

07 · Unbound

Resolver sicher konfigurieren

Profile und Einstellungen

Balanced, Privacy, Resilience und Performance laden ausschließlich einen Entwurf. QNAME-Minimierung, Prefetch, Serve Expired, Cache-TTLs und Threads werden erklärt und vor der Aktivierung als Änderungsvorschau dargestellt.

Lokale Zonen

Der geführte Assistent erzeugt A-, AAAA- und CNAME-Einträge ohne manuelle Unbound-Syntax. Er erkennt parallele Änderungen und verwendet dieselbe Checkconf-, Versions- und Rollback-Kette.

Conditional Forwarding

Mehrere interne Zonen lassen sich an geordnete IPv4- und IPv6-DNS-Server weiterleiten. RootGuard normalisiert Zonennamen und Adressen, blockiert Schleifen und gibt die Aktivierung erst frei, wenn jedes Ziel die konfigurierte Zone mit NOERROR und einem SOA-Eintrag bestätigt. Rekursiver Fallback, unsignierte private Zonen und private RFC1918-Antworten besitzen getrennte, klar erklärte Opt-ins; DNSSEC und Rebinding-Schutz bleiben sonst aktiv.

Expertenmodus und Live-Konfiguration

Der Editor besitzt nur 90-rootguard-custom.conf und blockiert gefährliche Includes, Listener, Remote Control sowie DNSSEC-Umgehungen. Die Live-Ansicht liest die tatsächlich aktiven Dateien read-only aus dem Container.

08 · AdGuard Home

Geschützte native Verwaltung

AdGuard Home erhält keinen öffentlichen Admin-Port. RootGuard führt den offiziellen Einrichtungsablauf intern durch, erzeugt Zugangsdaten im geschützten Core-Volume und stellt die Oberfläche ausschließlich unter /adguard-ui/ über die angemeldete WebApp bereit.

09 · Updates & Rollback

Zwei getrennte Sicherheitswege

AdGuard Home und Unbound

Core zieht nur konfigurierte Ziel-Images, vergleicht echte Image-IDs, sichert persistente Dienstpfade und ersetzt genau einen Dienst. DNS, DNSSEC und Upstream werden danach geprüft. Bei Fehlern folgen Daten- und Image-Rollback.

Core und WebApp

Der separate Updater bleibt während des Austauschs aktiv. Er aktualisiert Core und WebApp nur gemeinsam, prüft beide Image-IDs und Health-Endpunkte und pinnt bei einem Fehler beide vorherigen Images. Browser-Anfragen können weder Image-Namen noch Compose-Argumente festlegen.

ROOTGUARD_CORE_UPDATE_IMAGE=ghcr.io/foxly-it/rootguard-core:latest
ROOTGUARD_WEBAPP_UPDATE_IMAGE=ghcr.io/foxly-it/rootguard-webapp:latest

10 · Sicherheit

Vertrauensgrenzen

• WebApp ohne Docker-Socket und ohne frei ausführbare Host-Befehle
• HttpOnly-, SameSite-Strict-Sitzung und Same-Origin-Prüfung für Schreibzugriffe
• Core und Updater nur in internen Docker-Netzen und mit Bearer-Token
• Unbound read-only, non-root, ohne zusätzliche Capabilities
• AdGuard-Administration ohne öffentlichen Port

11 · Betrieb

Nützliche Befehle

# Status der Control Plane
docker compose -f compose.alpha.yaml ps

# Logs
docker compose -f compose.alpha.yaml logs --tail=200 core webapp updater

# Control Plane neu starten
docker compose -f compose.alpha.yaml restart core webapp updater

# Gestoppte Alpha wieder starten
docker compose -f compose.alpha.yaml start

# DNS testen
dig @ROOTGUARD_LAN_IP example.com A

Konfigurations- und Installationszustand liegt in benannten Docker-Volumes. Entferne Volumes nicht mit docker compose down --volumes, solange du keine bewusste Neuinstallation durchführen willst.

12 · Fehlerbehebung

Häufige Probleme

13 · Konfiguration

Wichtige Umgebungsvariablen

14 · Lizenz

GNU AGPL-3.0-or-later

RootGuard ist freie Open-Source-Software unter einer starken Copyleft-Lizenz. Nutzung, Prüfung, Veränderung und Weitergabe sind erlaubt. Wer eine veränderte Version verteilt oder Nutzern über ein Netzwerk bereitstellt, muss den entsprechenden Quellcode und die Lizenzhinweise zugänglich machen.