From 21469360db5e0a830e7d73cca2873fa4e20f2038 Mon Sep 17 00:00:00 2001 From: michael Date: Wed, 10 Sep 2025 11:18:48 +0200 Subject: [PATCH] =?UTF-8?q?health=20check=20sh=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- health-check-sh.md | 259 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 health-check-sh.md diff --git a/health-check-sh.md b/health-check-sh.md new file mode 100644 index 0000000..9f0913e --- /dev/null +++ b/health-check-sh.md @@ -0,0 +1,259 @@ +# health-check.sh + +**furt Service-Status nach Installation validieren** + +## Getestet unter +- OpenBSD 7.7 +- Debian 12 +- Arch Linux + +## Zweck des Scripts + +Das `health-check.sh` Script überprüft ob der furt-Service nach der Installation korrekt läuft und erreichbar ist. Es testet sowohl die HTTP-API-Funktionalität als auch die grundlegende Port-Erreichbarkeit und dient als finaler Validierungsschritt im Installations-Orchestrator. + +Das Script eliminiert manuelles Testen nach Installationen und stellt sicher dass furt vollständig betriebsbereit ist bevor die Installation als erfolgreich gemeldet wird. + +## Wie das Script funktioniert + +Das Script implementiert eine zweistufige Health-Check-Strategie mit intelligenten Fallback-Mechanismen: + +```bash +# Primär: HTTP Health-Check mit curl +if curl -s "http://$HOST:$PORT/health" > /tmp/health_response; then + echo "Health check successful:" + cat /tmp/health_response | sed 's/^/ /' +``` + +Falls curl verfügbar ist, wird der `/health` Endpunkt abgefragt der detaillierte Service-Informationen in JSON-Format zurückgibt. Die Response wird formatiert ausgegeben um Status, Version und Features anzuzeigen. + +```bash +# Fallback: Port-Check mit netcat +else + if nc -z "$HOST" "$PORT" 2>/dev/null; then + echo "Port $PORT is listening on $HOST" +``` + +Als Fallback nutzt das Script `nc` (netcat) für einen einfachen Port-Check falls curl nicht verfügbar ist. Diese Strategie stellt sicher dass das Script auch in minimalen Umgebungen funktioniert. + +## Health-Check-Strategien verstehen + +Die zweistufige Validierung deckt verschiedene Fehlerszenarien ab: + +### HTTP-Level-Validierung (Primär) +Der `/health` Endpunkt testet die gesamte furt-Applikations-Pipeline: + +- **Lua-Runtime:** Script-Loading und Execution +- **HTTP-Server:** Request-Parsing und Response-Generation +- **Konfiguration:** Config-File-Loading und Validation +- **Features:** SMTP-Integration und Auth-System-Status + +Diese umfassende Validierung erkennt Probleme die ein einfacher Port-Check übersehen würde. + +### Port-Level-Validierung (Fallback) +Der netcat-basierte Port-Check testet nur die grundlegende Netzwerk-Erreichbarkeit: + +- **Socket-Binding:** Service lauscht auf konfigurierten Port +- **Firewall-Status:** Keine Blockierung durch lokale Firewall +- **Process-Status:** Haupt-Process läuft noch + +Dieser Minimal-Check ist nützlich für Debug-Szenarien und Umgebungen ohne HTTP-Tools. + +## Script praktisch nutzen + +### Als Teil der orchestrierten Installation +```bash +# Automatischer Aufruf durch install.sh +./install.sh +# [INFO] Phase 6: Running health check... OK +``` + +Das Orchestrator-Script ruft `health-check.sh` als finalen Schritt auf um sicherzustellen dass die komplette Installation funktioniert. + +### Manuelle Service-Validierung +```bash +# Standard Health-Check +./scripts/health-check.sh +``` + +Ausgabe bei erfolgreicher Installation: +``` +Checking furt health at 127.0.0.1:7811... +Health check successful: + {"status":"healthy","service":"furt-lua","version":"0.1.0","timestamp":1699123456} +``` + +### Remote-Server-Monitoring +```bash +# Health-Check auf externem Server +./scripts/health-check.sh --host 192.168.1.100 --port 7811 +``` + +Diese Flexibilität ermöglicht Monitoring von furt-Installationen auf verschiedenen Servern. + +### Integration in Monitoring-Systeme +```bash +# Nagios/Icinga Integration +if ./scripts/health-check.sh --host $HOSTNAME --port 7811; then + echo "FURT OK" + exit 0 +else + echo "FURT CRITICAL" + exit 2 +fi +``` + +## Installation validieren + +Das Script zeigt verschiedene Ausgabe-Formate je nach Erfolg und verfügbaren Tools: + +### Erfolgreiche HTTP-Validierung +``` +Checking furt health at 127.0.0.1:7811... +Health check successful: + {"status":"healthy","service":"furt-lua","version":"0.1.0","content_hash":"abc123","timestamp":1699123456,"features":{"smtp_configured":true,"auth_enabled":true}} +``` + +Die JSON-Response enthält Service-Metadaten die detaillierte Diagnose ermöglichen. + +### Erfolgreiche Port-Validierung (Fallback) +``` +Checking furt health at 127.0.0.1:7811... +Warning: curl not available, using basic port check +Port 7811 is listening on 127.0.0.1 +``` + +Diese Ausgabe zeigt dass der Service läuft aber HTTP-Validierung nicht möglich war. + +### Fehlgeschlagene Validierung +``` +Checking furt health at 127.0.0.1:7811... +Health check failed - service not responding +``` + +Das Script beendet sich mit Exit-Code 1 bei Fehlern für Integration in automatisierte Workflows. + +## Troubleshooting + +### "Health check failed - service not responding" +``` +Health check failed - service not responding +``` +Der Service ist nicht erreichbar - mehrere mögliche Ursachen: + +```bash +# Service-Status prüfen +# OpenBSD +rcctl check furt + +# Linux +systemctl status furt + +# Logs analysieren +tail -f /var/log/furt/furt.log +``` + +### "curl not available, using basic port check" +``` +Warning: curl not available, using basic port check +``` +Das ist eine normale Warnung - die Port-Validierung ist ausreichend aber weniger detailliert: + +```bash +# curl installieren für detaillierte Checks +# OpenBSD +pkg_add curl + +# Debian +apt install curl + +# Arch +pacman -S curl +``` + +### "Port 7811 is not accessible" +``` +Port 7811 is not accessible on 127.0.0.1 +``` +Der Service läuft nicht oder bindet an falscher Adresse: + +```bash +# Process-Liste prüfen +ps aux | grep furt + +# Port-Binding prüfen +netstat -an | grep 7811 + +# Config-Datei validieren +./scripts/validate-config.sh +``` + +### Host/Port-Parameter werden ignoriert +Das Script verwendet Standardwerte falls Parameter nicht erkannt werden: + +```bash +# Korrekte Syntax +./scripts/health-check.sh --host 192.168.1.10 --port 8080 + +# Nicht: +./scripts/health-check.sh 192.168.1.10 8080 +``` + +## Script erweitern + +### Detailliertere JSON-Response-Analyse +```bash +# JSON-Response parsen mit jq +if command -v jq >/dev/null 2>&1; then + VERSION=$(echo "$RESPONSE" | jq -r '.version') + STATUS=$(echo "$RESPONSE" | jq -r '.status') + echo "Service: furt-lua $VERSION ($STATUS)" +else + echo "$RESPONSE" +fi +``` + +### Timeout-Konfiguration +```bash +# Längere Timeouts für langsamere Server +TIMEOUT="${TIMEOUT:-5}" +curl --max-time "$TIMEOUT" -s "http://$HOST:$PORT/health" +``` + +### Multiple-Health-Check-Endpunkte +```bash +# Verschiedene Endpunkte testen +ENDPOINTS="/health /version /metrics" +for endpoint in $ENDPOINTS; do + echo "Testing $endpoint..." + curl -s "http://$HOST:$PORT$endpoint" || echo " Failed" +done +``` + +### Colored Output für bessere Lesbarkeit +```bash +# Grün für Erfolg, Rot für Fehler +GREEN='\033[0;32m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +echo -e "${GREEN}Health check successful:${NC}" +echo -e "${RED}Health check failed${NC}" +``` + +### Integration mit systemd/rcctl +```bash +# Service-Status in Health-Check einbeziehen +if [ "$(uname)" = "OpenBSD" ]; then + if ! rcctl check furt >/dev/null 2>&1; then + echo "Service not running according to rcctl" + exit 1 + fi +else + if ! systemctl is-active furt >/dev/null 2>&1; then + echo "Service not active according to systemctl" + exit 1 + fi +fi +``` + +Das `health-check.sh` Script ist der Schlussstein des modularen furt-Installationssystems und stellt sicher dass alle vorherigen Installationsschritte erfolgreich waren und der Service vollständig betriebsbereit ist. \ No newline at end of file