Initial version of the .NET HostAvailabilityMonitor.

2026-04-16 12:40:53 +02:00
commit c267069d02
19 changed files with 2252 additions and 0 deletions
@@ -0,0 +1,349 @@
+# Dokumentation – Host Availability Monitor (.NET Framework 4.8)
+
+## 1. Zielbild
+
+Die Anwendung überwacht auf einem Windows Server 2019 in festen Intervallen die netzwerktechnische Verfügbarkeit definierter Ziele. Typische Einsatzzwecke:
+
+- interne Fileshares
+- externe HTTPS-Endpunkte
+- SFTP-Gegenstellen
+- TCP-Dienste
+- Hosts per Ping
+
+Der Betrieb erfolgt typischerweise über den **Windows Task Scheduler** alle 30 Minuten.
+
+## 2. Unterstützte Zieltypen
+
+### 2.1 UNC / SMB
+
+Beispiel:
+
+```text
+\\internerserver1\share1
+```
+
+Verhalten:
+
+1. TCP-Check auf Port 445 (oder überschriebenen Port)
+2. Optional zusätzliche Pfadvalidierung mit `Directory.Exists(...)` / `File.Exists(...)`
+
+Hinweis:
+
+- `ValidateUncPathAccess=false` ist robuster, wenn es nur um Erreichbarkeit geht.
+- `ValidateUncPathAccess=true` ist strenger, weil Berechtigungen, Namensauflösung und tatsächlicher Share-Zugriff geprüft werden.
+
+### 2.2 HTTP / HTTPS
+
+Beispiele:
+
+```text
+https://host1.de/url
+http://intranet.local/health
+```
+
+Verhalten:
+
+- Standardmäßig `HEAD`
+- Fallback auf `GET`, wenn `HEAD` nicht unterstützt wird (`405` / `501`) oder der HEAD-Request fehlschlägt
+- Jede empfangene HTTP-Antwort zählt als **netzwerktechnisch erreichbar**
+
+### 2.3 SFTP
+
+Beispiel:
+
+```text
+sftp://partner.example.local/inbound
+```
+
+Verhalten:
+
+- TCP-Port-Prüfung, standardmäßig Port 22
+- kein Login, keine Dateioperation
+
+### 2.4 TCP
+
+Beispiel:
+
+```text
+tcp://host2.example.local:8443
+```
+
+Verhalten:
+
+- reiner Verbindungsaufbau auf dem Zielport
+
+### 2.5 ICMP
+
+Beispiel:
+
+```text
+icmp://server01
+```
+
+Verhalten:
+
+- Ping über `System.Net.NetworkInformation.Ping`
+
+### 2.6 Plain Hostnames
+
+Beispiele:
+
+```text
+server01
+partner-gateway
+```
+
+Verhalten:
+
+- wenn `Port` gesetzt ist: TCP-Check
+- wenn kein `Port` gesetzt ist: ICMP-Check
+
+## 3. Konfigurationsmodell
+
+Die Konfiguration erfolgt in `appsettings.json`.
+
+### 3.1 Runtime
+
+| Feld | Bedeutung |
+|---|---|
+| `MaxConcurrency` | Maximale parallele Checks |
+| `DefaultValidateUncPathAccess` | Default für UNC-Pfadzugriffsprüfung |
+| `NonZeroExitCodeOnAnyFailure` | Exit Code 2 bei mindestens einem fehlgeschlagenen Check |
+| `NonZeroExitCodeOnExecutionError` | Exit Code 1 bei technischen Fehlern |
+| `StateDirectory` | Verzeichnis für Statusdatei |
+
+### 3.2 Logging
+
+| Feld | Bedeutung |
+|---|---|
+| `LogDirectory` | Verzeichnis der Logdateien |
+| `FilePrefix` | Präfix des Tageslogs |
+| `RetentionDays` | Anzahl Tage zur Aufbewahrung |
+
+### 3.3 EventLog
+
+| Feld | Bedeutung |
+|---|---|
+| `Enabled` | Aktiviert Event Log |
+| `LogName` | Standard: `Application` |
+| `Source` | Event Source |
+| `CreateSourceIfMissing` | Optionaler Versuch, die Source anzulegen |
+| `WriteSuccessEntries` | Erfolgreiche Einzelchecks schreiben |
+| `WriteSummaryEntries` | Laufzusammenfassung schreiben |
+
+### 3.4 Email
+
+| Feld | Bedeutung |
+|---|---|
+| `Enabled` | Aktiviert SMTP-Benachrichtigung |
+| `SmtpHost` / `SmtpPort` | SMTP-Ziel |
+| `UseSsl` | SSL/TLS für SMTP |
+| `Username` / `Password` | Optionale Credentials |
+| `From` | Absender |
+| `To` | Empfängerliste |
+| `SubjectPrefix` | Präfix im Betreff |
+| `SendOnFailure` | Mail bei Fehler |
+| `SendOnRecovery` | Mail bei Wiederherstellung |
+| `OnlyOnStateChange` | Nur bei Statuswechsel |
+| `CooldownMinutes` | Minimaler Abstand zwischen Benachrichtigungen |
+| `TimeoutSeconds` | SMTP-Timeout |
+
+### 3.5 Targets
+
+| Feld | Bedeutung |
+|---|---|
+| `Name` | Anzeigename |
+| `Endpoint` | UNC, URL, SFTP, TCP, ICMP oder Hostname |
+| `TimeoutSeconds` | Timeout je Ziel |
+| `Port` | Optionaler Zielport |
+| `ValidateUncPathAccess` | Optional pro UNC-Ziel |
+| `HttpMethod` | `HEAD` oder `GET` |
+| `Enabled` | Ziel aktiv/inaktiv |
+
+## 4. Logging-Verhalten
+
+### 4.1 Dateilog
+
+Pro Tag entsteht genau eine Logdatei:
+
+```text
+logs\host-availability-monitor-2026-04-16.log
+```
+
+Format:
+
+```text
+2026-04-16 08:00:00.123 +02:00 | INFO | Lauf gestartet.
+2026-04-16 08:00:00.532 +02:00 | SUCCESS | Name=Externe Webseite | Kind=Https | Endpoint=https://host1.de/url | DurationMs=278 | Status=Reachable | Detail=HTTP-Antwort erhalten (200 OK). | Host=host1.de | Port=443 | HttpStatus=200
+2026-04-16 08:00:01.003 +02:00 | FAIL | Name=SFTP Partner A | Kind=Sftp | Endpoint=sftp://partner.example.local/inbound | DurationMs=10005 | Status=Unreachable | Detail=TCP-Verbindung fehlgeschlagen: A connection attempt failed... | Host=partner.example.local | Port=22 | ErrorType=SocketException
+```
+
+### 4.2 Retention
+
+Beim Start eines Laufs werden alte Tageslogs bereinigt.
+
+Standard:
+
+- aktueller Tag + 4 vorherige Tage bleiben erhalten
+- ältere Logs werden gelöscht
+
+## 5. Event Log
+
+Es wird in das Windows Application Event Log geschrieben.
+
+Typische Events:
+
+- Fehler bei Einzelchecks: Warning
+- technische Fehler: Error
+- Laufzusammenfassung: Information oder Warning
+
+Wichtig:
+
+- Das Erzeugen einer Event Source benötigt erhöhte Rechte.
+- Im produktiven Betrieb sollte die Source einmalig per Skript registriert werden.
+- Falls Event Log nicht verfügbar ist, fällt die Anwendung auf Dateilogging zurück und läuft weiter.
+
+## 6. Benachrichtigungslogik
+
+Die Anwendung speichert je Ziel einen Status in `state\monitor-state.json`.
+
+Gespeicherte Informationen pro Ziel:
+
+- `IsUp`
+- `ConsecutiveFailures`
+- `LastCheckedUtc`
+- `LastChangedUtc`
+- `LastNotificationUtc`
+- `LastDetail`
+
+### 6.1 Benachrichtigung bei Fehler
+
+Es wird benachrichtigt, wenn:
+
+- `Email.Enabled=true`
+- `SendOnFailure=true`
+- das Ziel aktuell fehlschlägt
+- und je nach Einstellung entweder
+  - ein Statuswechsel vorliegt oder
+  - der Cooldown abgelaufen ist
+
+### 6.2 Benachrichtigung bei Recovery
+
+Es wird benachrichtigt, wenn:
+
+- `Email.Enabled=true`
+- `SendOnRecovery=true`
+- das Ziel aktuell erfolgreich ist
+- und der vorherige bekannte Zustand `down` war
+
+### 6.3 Anti-Spam
+
+Mit `OnlyOnStateChange=true` werden bei Dauerfehlern nicht bei jedem Lauf erneut Mails versendet.
+
+Mit `CooldownMinutes > 0` kann zusätzlich ein Zeitfenster definiert werden.
+
+## 7. Exit Codes
+
+| Exit Code | Bedeutung |
+|---|---|
+| `0` | Lauf erfolgreich abgeschlossen |
+| `1` | technischer Fehler / Konfigurations- oder Laufzeitproblem |
+| `2` | mindestens ein Ziel fehlgeschlagen und `NonZeroExitCodeOnAnyFailure=true` |
+
+## 8. Task Scheduler Empfehlung
+
+### 8.1 Allgemein
+
+- Trigger: alle 30 Minuten
+- Benutzerkonto: dediziertes Servicekonto, falls UNC-Zugriffe Berechtigungen benötigen
+- "Start in": Installationsverzeichnis setzen
+
+### 8.2 Beispiel
+
+**Aktion**
+
+- Program/script:
+
+```text
+C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe
+```
+
+- Add arguments:
+
+```text
+C:\Tools\HostAvailabilityMonitor\appsettings.json
+```
+
+- Start in:
+
+```text
+C:\Tools\HostAvailabilityMonitor
+```
+
+## 9. Betriebshinweise
+
+### 9.1 UNC-Prüfung
+
+Wenn echte Share-Verfügbarkeit geprüft werden soll:
+
+- Task mit geeignetem Servicekonto ausführen
+- `ValidateUncPathAccess=true` für das betreffende Ziel setzen
+
+Wenn nur der Zielserver bzw. SMB-Port relevant ist:
+
+- `ValidateUncPathAccess=false` belassen
+
+### 9.2 HTTP/HTTPS
+
+Die Anwendung prüft Erreichbarkeit, nicht Business-Logik. Für Applikations-Health kann eine dedizierte Health-URL sinnvoller sein.
+
+### 9.3 SFTP
+
+Da nur der Port geprüft wird, eignet sich der Check für "Ist die Gegenstelle erreichbar?", nicht für "Kann ich mich anmelden und Dateien lesen?".
+
+### 9.4 TLS
+
+Die Anwendung aktiviert zusätzlich gängige SecurityProtocol-Werte, damit HTTPS-Ziele in älteren .NET-Framework-Umgebungen robuster funktionieren.
+
+## 10. Build und Deployment
+
+### 10.1 Voraussetzungen
+
+- Windows Build Host
+- Visual Studio oder Build Tools mit MSBuild
+- .NET Framework 4.8 Targeting/Developer Pack
+
+### 10.2 Build
+
+```powershell
+msbuild .\HostAvailabilityMonitor.sln /p:Configuration=Release /p:Platform="Any CPU"
+```
+
+### 10.3 Artefakte
+
+Relevant für Deployment:
+
+- `HostAvailabilityMonitor.exe`
+- `HostAvailabilityMonitor.exe.config`
+- `appsettings.json`
+- weitere referenzierte .NET-Assemblies aus `bin\Release`
+
+## 11. Sicherheits- und Resilienz-Aspekte
+
+Die Anwendung ist bewusst defensiv aufgebaut:
+
+- Fehler einzelner Checks stoppen nicht den Gesamtlauf
+- Event Log Ausfälle führen nicht zum Abbruch
+- Statusdatei wird atomar aktualisiert
+- Log-Bereinigung blockiert den Lauf nicht
+- Mailversand markiert Benachrichtigungen nur bei echtem Erfolg
+
+## 12. Empfohlene nächste Ausbaustufen
+
+Optional könnte das Projekt später erweitert werden um:
+
+- CSV- oder HTML-Report pro Lauf
+- pro Target eigene Empfängergruppen
+- zusätzliche Protokolle wie FTP oder LDAP-Portchecks
+- Performance Counter oder Windows Service statt Task Scheduler
+- Gitea CI-Workflow für Windows Runner