docs: Dokumentation umfassend überarbeitet

2026-05-01 01:17:05 +02:00
parent a7f7dbdb71
commit 7bbdb104c4
10 changed files with 1970 additions and 1167 deletions
--- a/docs/update.md
+++ b/docs/update.md
@@ -5,7 +5,7 @@ AdGuard Shield wird in der Go-Version über das Binary selbst installiert und ak
 ## Kurzfassung

 ```bash
-# neues Linux-Binary bereitstellen
+# Neues Linux-Binary bereitstellen
 chmod +x ./adguard-shield

 # Update durchführen
@@ -14,7 +14,7 @@ sudo ./adguard-shield update

 Am Ende fragt der Updater, ob AdGuard Shield direkt neu gestartet werden soll.

-Danach prüfen:
+### Nach dem Update prüfen

 ```bash
 sudo /opt/adguard-shield/adguard-shield install-status
@@ -22,11 +22,13 @@ sudo /opt/adguard-shield/adguard-shield status
 sudo journalctl -u adguard-shield --no-pager -n 50
 ```

-## Woher kommt das neue Binary?
+---
+
+## Neues Binary beziehen

 Du brauchst ein fertiges Linux-Binary. Das kann aus einem Release, aus CI oder aus einem lokalen Build kommen.

-Release-Binary für v1.0.0 herunterladen:
+### Variante A: Release-Binary herunterladen

 ```bash
 curl -fL -o adguard-shield-linux-amd64.tar.gz \
@@ -35,13 +37,13 @@ tar -xzf adguard-shield-linux-amd64.tar.gz
 chmod +x ./adguard-shield
 ```

-Build mit lokal installiertem Go:
+### Variante B: Lokal mit Go bauen

 ```bash
 GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o adguard-shield ./cmd/adguard-shieldd
 ```

-Build ohne lokale Go-Installation mit Docker:
+### Variante C: Per Docker bauen (ohne lokales Go)

 ```bash
 docker run --rm -v "$PWD":/src -w /src \
@@ -51,41 +53,59 @@ docker run --rm -v "$PWD":/src -w /src \

 Auf dem Zielserver muss Go nicht installiert sein, wenn dort nur das fertige Binary ausgeführt wird.

+---
+
 ## Was `update` macht

 Der Update-Befehl nutzt intern dieselbe Routine wie die Installation:

-1. Linux- und root-Rechte prüfen.
-2. Auf alte Shell-Artefakte prüfen.
-3. Systemabhängigkeiten prüfen, sofern nicht `--skip-deps` gesetzt ist.
-4. Installationsverzeichnis sicherstellen.
-5. neues Binary nach `/opt/adguard-shield/adguard-shield` kopieren.
-6. Konfiguration migrieren.
-7. systemd-Service neu schreiben.
-8. `systemctl daemon-reload` ausführen.
-9. Autostart aktivieren, sofern nicht `--no-enable` gesetzt ist.
-10. fragen, ob der Service direkt neu gestartet werden soll.
+| Schritt | Aktion |
+|---:|---|
+| 1 | Linux- und Root-Rechte prüfen |
+| 2 | Auf alte Shell-Artefakte prüfen |
+| 3 | Systemabhängigkeiten prüfen (sofern nicht `--skip-deps`) |
+| 4 | Installationsverzeichnis sicherstellen |
+| 5 | Neues Binary nach `/opt/adguard-shield/adguard-shield` kopieren |
+| 6 | Konfiguration migrieren (vorhandene Werte behalten, neue ergänzen) |
+| 7 | systemd-Service neu schreiben |
+| 8 | `systemctl daemon-reload` |
+| 9 | Autostart aktivieren (sofern nicht `--no-enable`) |
+| 10 | Nachfrage: Service direkt neu starten |
+
+---

 ## Konfigurationsmigration

-Vorhandene Werte bleiben erhalten. Neue Parameter werden ergänzt.
+Vorhandene Werte bleiben erhalten. Neue Parameter werden am Ende der Datei ergänzt. Der Installer überschreibt keine bestehenden Einstellungen.

 Wenn eine Migration nötig ist:

-```text
-/opt/adguard-shield/adguard-shield.conf      # aktualisierte Konfiguration
-/opt/adguard-shield/adguard-shield.conf.old  # Backup der vorherigen Datei
-```
+| Datei | Inhalt |
+|---|---|
+| `adguard-shield.conf` | Aktualisierte Konfiguration mit alten + neuen Parametern |
+| `adguard-shield.conf.old` | Backup der vorherigen Datei |

-Nach dem Update solltest du prüfen:
+### Änderungen prüfen

 ```bash
 sudo diff -u /opt/adguard-shield/adguard-shield.conf.old /opt/adguard-shield/adguard-shield.conf
 ```

-Falls `diff` keine Datei findet, war keine Konfigurationsmigration nötig.
+Falls `diff` keine `.old`-Datei findet, war keine Konfigurationsmigration nötig.

-## Update mit Service-Neustart
+### Neue Parameter prüfen
+
+Nach dem Update solltest du die neu ergänzten Parameter überprüfen und bei Bedarf anpassen:
+
+```bash
+sudo nano /opt/adguard-shield/adguard-shield.conf
+```
+
+---
+
+## Update-Optionen
+
+### Update mit Service-Neustart

 Wenn der Service nach dem Update direkt laufen soll, bestätige die Nachfrage am Ende mit `j`.

@@ -98,141 +118,167 @@ sudo /opt/adguard-shield/adguard-shield dry-run
 sudo systemctl restart adguard-shield
 ```

-## Update ohne Paketprüfung
+### Update ohne Paketprüfung

 ```bash
 sudo ./adguard-shield update --skip-deps
 ```

-Das ist sinnvoll, wenn du sicher weißt, dass `iptables`, `ip6tables`, `ipset` und `systemctl` vorhanden sind oder wenn Paketinstallation auf deinem System nicht über `apt-get` laufen soll.
+Sinnvoll, wenn `iptables`, `ip6tables`, `ipset` und `systemctl` bereits vorhanden sind oder die Paketinstallation nicht über `apt-get` laufen soll.

-## Update in anderem Installationsverzeichnis
+### Update mit expliziter Konfigurationsquelle
+
+```bash
+sudo ./adguard-shield update --config-source ./adguard-shield.conf
+```
+
+### Update in anderem Installationsverzeichnis

 ```bash
 sudo ./adguard-shield update --install-dir /opt/adguard-shield-test
 ```

-Beachte: Die systemd-Unit heißt weiterhin `adguard-shield.service`. Mehrere parallele produktive Installationen über dieselbe Unit sind nicht vorgesehen.
+**Hinweis:** Die systemd-Unit heißt weiterhin `adguard-shield.service`. Mehrere parallele produktive Installationen über dieselbe Unit sind nicht vorgesehen.
+
+---

 ## Migration von der alten Shell-Version

 Die Go-Version erkennt alte Shell-Artefakte und bricht ab, wenn sie noch vorhanden sind.

-Typische Funde:
+### Typische alte Artefakte

-```text
-/opt/adguard-shield/adguard-shield.sh
-/opt/adguard-shield/iptables-helper.sh
-/opt/adguard-shield/external-blocklist-worker.sh
-/opt/adguard-shield/external-whitelist-worker.sh
-/opt/adguard-shield/geoip-worker.sh
-/opt/adguard-shield/offense-cleanup-worker.sh
-/opt/adguard-shield/report-generator.sh
-/opt/adguard-shield/unban-expired.sh
-/etc/systemd/system/adguard-shield-watchdog.service
-/etc/systemd/system/adguard-shield-watchdog.timer
-```
+| Datei | Funktion in der alten Version |
+|---|---|
+| `adguard-shield.sh` | Hauptskript |
+| `iptables-helper.sh` | Firewall-Management |
+| `external-blocklist-worker.sh` | Blocklist-Synchronisation |
+| `external-whitelist-worker.sh` | Whitelist-Synchronisation |
+| `geoip-worker.sh` | GeoIP-Prüfung |
+| `offense-cleanup-worker.sh` | Offense-Bereinigung |
+| `report-generator.sh` | Report-Erstellung |
+| `unban-expired.sh` | Ablauf temporärer Sperren |
+| `adguard-shield-watchdog.service` | Watchdog-Service |
+| `adguard-shield-watchdog.timer` | Watchdog-Timer |

-Warum Abbruch?
+### Warum bricht der Installer ab?

-Die alte und die neue Version würden sonst dieselbe Firewall, dieselbe Konfiguration und dieselben Sperren verwalten. Das kann zu schwer nachvollziehbaren Zuständen führen.
+Die alte und die neue Version würden sonst dieselbe Firewall, dieselbe Konfiguration und dieselben Sperren verwalten. Das kann zu schwer nachvollziehbaren Zuständen führen, bei denen zwei Implementierungen sich gegenseitig die Regeln überschreiben.

-Empfohlener Migrationsablauf:
+### Empfohlener Migrationsablauf

 ```bash
-# Konfiguration sichern
+# 1. Konfiguration sichern
 sudo cp /opt/adguard-shield/adguard-shield.conf /root/adguard-shield.conf.backup

-# alte Shell-Version mit deren Uninstaller entfernen
-# dabei Konfiguration behalten, falls der alte Uninstaller diese Option anbietet
+# 2. Alte Shell-Version mit deren Uninstaller entfernen
+#    (dabei Konfiguration behalten, falls der alte Uninstaller diese Option anbietet)

-# neues Go-Binary installieren und alte Konfiguration als Quelle nutzen
+# 3. Neues Go-Binary installieren und alte Konfiguration als Quelle nutzen
 sudo ./adguard-shield install --config-source /root/adguard-shield.conf.backup

-# prüfen
+# 4. API-Verbindung prüfen
 sudo /opt/adguard-shield/adguard-shield test
+
+# 5. Dry-Run: prüfen, was gesperrt würde
 sudo /opt/adguard-shield/adguard-shield dry-run
+
+# 6. Produktiven Service starten
+sudo systemctl start adguard-shield
+sudo systemctl status adguard-shield
 ```

-Wenn der Go-Installer Legacy-Dateien meldet, entferne nur die gemeldeten alten Artefakte der Shell-Version. Keine fremden Firewall-Regeln oder unrelated Dateien löschen.
+**Wichtig:** Wenn der Go-Installer Legacy-Dateien meldet, entferne nur die gemeldeten alten Artefakte der Shell-Version. Keine fremden Firewall-Regeln oder unrelated Dateien löschen.
+
+---

 ## Nach dem Update prüfen

-Installation:
+### Installation

 ```bash
 sudo /opt/adguard-shield/adguard-shield install-status
 ```

-Service:
+### Service

 ```bash
 sudo systemctl status adguard-shield
 sudo journalctl -u adguard-shield --no-pager -n 100
 ```

-API:
+### API-Verbindung

 ```bash
 sudo /opt/adguard-shield/adguard-shield test
 ```

-Runtime:
+### Laufzeitstatus

 ```bash
 sudo /opt/adguard-shield/adguard-shield status
 sudo /opt/adguard-shield/adguard-shield live --once
 ```

-Firewall:
+### Firewall

 ```bash
 sudo /opt/adguard-shield/adguard-shield firewall-status
 ```

+---
+
 ## Rollback

 Ein Rollback besteht aus zwei Teilen: altes Binary wieder bereitstellen und passende Konfiguration verwenden.

-Vorgehen:
-
-1. Service stoppen.
-2. altes Binary nach `/opt/adguard-shield/adguard-shield` kopieren.
-3. optional `adguard-shield.conf.old` zurückkopieren.
-4. Service starten.
-
-Beispiel:
+### Schritt-für-Schritt

 ```bash
+# 1. Service stoppen
 sudo systemctl stop adguard-shield
+
+# 2. Altes Binary wiederherstellen
 sudo cp ./adguard-shield-alte-version /opt/adguard-shield/adguard-shield
 sudo chmod +x /opt/adguard-shield/adguard-shield
+
+# 3. Service starten
 sudo systemctl start adguard-shield
 ```

-Wenn die Konfiguration zurückgesetzt werden soll:
+### Konfiguration zurücksetzen (optional)

 ```bash
 sudo cp /opt/adguard-shield/adguard-shield.conf.old /opt/adguard-shield/adguard-shield.conf
 sudo systemctl restart adguard-shield
 ```

-Hinweis: SQLite-Schema-Migrationen sind aktuell sehr konservativ. Trotzdem solltest du vor größeren Updates ein Backup von `/var/lib/adguard-shield/adguard-shield.db` erstellen, wenn dir History und aktive Sperren wichtig sind.
+**Hinweis:** SQLite-Schema-Migrationen sind aktuell sehr konservativ. Trotzdem solltest du vor größeren Updates ein Backup der Datenbank erstellen, wenn dir History und aktive Sperren wichtig sind.
+
+---

 ## Backup vor größeren Updates

 ```bash
+# Service kurz stoppen für konsistentes Backup
 sudo systemctl stop adguard-shield
+
+# Konfiguration und Datenbank sichern
 sudo cp /opt/adguard-shield/adguard-shield.conf /root/adguard-shield.conf.$(date +%F)
 sudo cp /var/lib/adguard-shield/adguard-shield.db /root/adguard-shield.db.$(date +%F)
+
+# Service wieder starten
 sudo systemctl start adguard-shield
 ```

+### WAL-Dateien beachten
+
 Bei laufendem SQLite mit WAL können zusätzliche Dateien existieren:

-```text
-adguard-shield.db-wal
-adguard-shield.db-shm
-```
+| Datei | Beschreibung |
+|---|---|
+| `adguard-shield.db` | Hauptdatenbank |
+| `adguard-shield.db-wal` | Write-Ahead-Log (enthält noch nicht in die Hauptdatei geschriebene Daten) |
+| `adguard-shield.db-shm` | Shared-Memory-Datei |

-Am saubersten ist ein kurzer Service-Stop während des Backups.
+Am saubersten ist ein kurzer Service-Stop während des Backups. So wird sichergestellt, dass alle WAL-Einträge in die Hauptdatei geschrieben werden.