From 381cdb1933874d138ee603319b27fef93fadc5b9 Mon Sep 17 00:00:00 2001 From: michael Date: Wed, 10 Sep 2025 11:09:14 +0200 Subject: [PATCH] =?UTF-8?q?validate=20config=20sh=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- validate-config-sh.md | 249 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 validate-config-sh.md diff --git a/validate-config-sh.md b/validate-config-sh.md new file mode 100644 index 0000000..0ba3112 --- /dev/null +++ b/validate-config-sh.md @@ -0,0 +1,249 @@ +# validate-config.sh + +**furt Konfiguration vor Service-Start validieren** + +## Getestet unter +- OpenBSD 7.7 +- Debian 12 +- Arch Linux + +## Zweck des Scripts + +Das `validate-config.sh` Script überprüft die furt-Konfigurationsdatei auf Syntax-Fehler und fehlende Pflicht-Abschnitte vor dem Service-Start. Es erkennt betriebssystem-spezifische Config-Pfade und validiert INI-Format, Server-Einstellungen und API-Key-Konfiguration. + +Das Script verhindert Service-Starts mit defekter Konfiguration und gibt spezifische Hinweise auf Problembereiche für schnellere Fehlerbehebung. + +## Wie das Script funktioniert + +Das Script erkennt zunächst den korrekten Konfigurationspfad basierend auf dem Betriebssystem: + +```bash +if [ "$(uname)" = "OpenBSD" ]; then + CONFIG_FILE="/usr/local/etc/furt/furt.conf" +else + CONFIG_FILE="/etc/furt/furt.conf" +fi +``` + +Anschließend führt es eine mehrstufige Validierung durch: + +1. **Datei-Existenz:** Prüft ob die Config-Datei gefunden wird +2. **INI-Syntax:** Validiert grundlegende INI-Struktur +3. **Pflicht-Abschnitte:** Stellt sicher dass [server] existiert +4. **Server-Parameter:** Prüft port- und host-Konfiguration +5. **API-Keys:** Warnt bei fehlenden API-Key-Definitionen +6. **Berechtigungen:** Überprüft Config-Datei-Permissions + +Das `set -e` Flag sorgt dafür dass das Script bei kritischen Fehlern sofort abbricht statt weiterzumachen. + +## Betriebssystem-Philosophien verstehen + +Die Config-Pfad-Erkennung spiegelt unterschiedliche System-Philosophien wider: + +### BSD-Ansatz (OpenBSD) +OpenBSD trennt strikt zwischen Base-System (`/etc`) und Third-Party-Software (`/usr/local/etc`). Diese Separation verhindert Konflikte bei System-Updates und hält die Base-System-Konfiguration sauber. + +```bash +# OpenBSD +CONFIG_FILE="/usr/local/etc/furt/furt.conf" +``` + +Die `/usr/local/`-Hierarchie überlebt System-Upgrades und ermöglicht klare Trennung zwischen Betriebssystem- und Anwendungs-Konfiguration. + +### Linux-Ansatz (Debian, Arch, etc.) +Linux-Distributionen verwenden meist `/etc` für alle Konfigurationsdateien unabhängig von der Installationsquelle. Package-Manager koordinieren zwischen verschiedenen Software-Quellen in einem gemeinsamen Namespace. + +```bash +# Linux +CONFIG_FILE="/etc/furt/furt.conf" +``` + +Diese Konvention macht alle System-Konfiguration zentral auffindbar und integriert sich nahtlos in etablierte Admin-Workflows. + +## Validierungs-Strategien verstehen + +Das Script implementiert eine pragmatische Validierungs-Pipeline die auf häufige Konfigurationsfehler abzielt: + +**INI-Format-Validierung:** Grep-basierte Suche nach Section-Headers vermeidet komplexe Parser-Dependencies. Die Regex-Patterns sind POSIX-kompatibel für maximale Portabilität. + +**Server-Parameter-Checks:** Explizite Prüfung auf `port` und `host` Einstellungen da diese für die Server-Funktionalität kritisch sind. + +**API-Key-Warnung:** Fehlende API-Keys werden als Warning behandelt statt Error da furt theoretisch ohne sie starten könnte - aber praktisch nutzlos wäre. + +**Permission-Monitoring:** Config-Dateien enthalten SMTP-Passwörter und API-Keys. Zu offene Berechtigungen werden gewarnt aber blockieren nicht den Service-Start. + +## Script praktisch nutzen + +### Als Teil der Installation +```bash +# Orchestrierter Aufruf durch install.sh +./install.sh +# [INFO] Phase 5: Validating configuration... OK +``` + +Das Orchestrator-Script ruft `validate-config.sh` nach der Config-Installation auf um sicherzustellen dass die Standard-Konfiguration syntaktisch korrekt ist. + +### Manuelle Validierung nach Config-Änderungen +```bash +# Nach Bearbeitung von furt.conf +sudo ./scripts/validate-config.sh +``` + +Ausgabe zeigt den Validierungserfolg: +``` +Validating configuration: /usr/local/etc/furt/furt.conf +Configuration validation completed +``` + +### Integration in Service-Restart-Workflow +```bash +# Sichere Config-Updates +sudo ./scripts/validate-config.sh && sudo rcctl restart furt +``` + +Diese Kombination verhindert Service-Ausfälle durch defekte Konfiguration. + +### Development-Testing +```bash +# Config-Syntax nach Änderungen prüfen +vim /usr/local/etc/furt/furt.conf +./scripts/validate-config.sh +``` + +## Installation validieren + +Nach der Script-Ausführung kannst du die Config-Datei direkt prüfen: + +```bash +# Strukturelle Validierung +grep '^\[' /usr/local/etc/furt/furt.conf +grep '^port' /usr/local/etc/furt/furt.conf +grep '^host' /usr/local/etc/furt/furt.conf + +# Berechtigungen prüfen +ls -la /usr/local/etc/furt/furt.conf +``` + +Korrekte Konfiguration zeigt die erwarteten Abschnitte und angemessene Berechtigungen: +``` +[server] +[smtp_default] +[api_key "example-key"] +-rw-r----- 1 root _furt 2048 furt.conf +``` + +## Troubleshooting + +### "Configuration file not found" +``` +Error: Configuration file not found: /etc/furt/furt.conf +``` +Die Config-Datei wurde nicht installiert oder liegt am falschen Ort: +```bash +# Prüfe alternative Pfade +ls -la /usr/local/etc/furt/furt.conf # OpenBSD +ls -la /etc/furt/furt.conf # Linux + +# Config aus Example erstellen +cp /usr/local/share/furt/config/furt.conf.example /etc/furt/furt.conf +``` + +### "[server] section missing" +``` +Error: [server] section missing in config +``` +Die Config-Datei ist unvollständig oder beschädigt: +```bash +# Grundstruktur prüfen +head -20 /usr/local/etc/furt/furt.conf + +# Example-Config als Basis verwenden +cp /usr/local/share/furt/config/furt.conf.example /usr/local/etc/furt/furt.conf +``` + +### "server port not configured" +``` +Error: server port not configured +``` +Der [server]-Abschnitt existiert aber die port-Zeile fehlt: +```bash +# [server]-Abschnitt überprüfen +grep -A 5 '^\[server\]' /usr/local/etc/furt/furt.conf + +# Port-Zeile hinzufügen +echo "port = 7811" >> /usr/local/etc/furt/furt.conf +``` + +### "No API keys configured" +``` +Warning: No API keys configured +``` +Dies ist eine Warnung, kein Fehler. API-Keys sind für praktische Nutzung erforderlich: +```bash +# API-Key-Abschnitt hinzufügen +cat >> /usr/local/etc/furt/furt.conf << EOF + +[api_key "test-key"] +name = "Test API Key" +permissions = mail:send +allowed_ips = 127.0.0.1 +mail_to = admin@example.com +mail_from = noreply@example.com +EOF +``` + +### "Config file permissions too open" +``` +Warning: Config file permissions too open (644), should be 640 +``` +Die Config-Datei ist für alle Benutzer lesbar obwohl sie Passwörter enthält: +```bash +# Berechtigungen korrigieren +chmod 640 /usr/local/etc/furt/furt.conf + +# OpenBSD +chown root:_furt /usr/local/etc/furt/furt.conf + +# Linux +chown root:furt /etc/furt/furt.conf +``` + +## Script erweitern + +### Detailliertere INI-Validierung +```bash +# Validierung für fehlende Closing-Brackets +if grep -q '^\[.*[^]]$' "$CONFIG_FILE"; then + echo "Error: Malformed section header in config" + exit 1 +fi +``` + +### SMTP-Konfiguration prüfen +```bash +# Prüfe ob SMTP-Settings vorhanden sind +if ! grep -q '^\[smtp_default\]' "$CONFIG_FILE"; then + echo "Warning: No default SMTP configuration found" +fi +``` + +### Config-Backup vor Validierung +```bash +# Backup erstellen für Rollback-Möglichkeit +if [ -f "$CONFIG_FILE" ]; then + cp "$CONFIG_FILE" "$CONFIG_FILE.backup.$(date +%Y%m%d_%H%M%S)" +fi +``` + +### Syntax-Highlighting für Fehler +```bash +# Zeige problematische Zeilen mit Kontext +if ! grep -q '^port' "$CONFIG_FILE"; then + echo "Error: server port not configured" + echo "Expected: port = 7811" + echo "In section: [server]" + exit 1 +fi +``` + +Das `validate-config.sh` Script ist ein kritischer Sicherheits-Checkpoint der verhindert dass furt mit defekter Konfiguration startet und dadurch unvorhersagbare Fehler oder Sicherheitslücken entstehen. Es balanciert gründliche Validierung mit praktischer Nutzbarkeit. \ No newline at end of file