HostAvailabilityMonitor/Dokumentation.md

# 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