Add BizTalk endpoint reachability monitoring

docs/EndpointCatalog.md

@@ -0,0 +1,98 @@
+# Endpoint-Katalog und Netzwerkprobe
+
+## Automatischer Betrieb
+
+Der privilegierte Provider liest bei seiner bereits vorhandenen
+`MSBTS_SendPort`-/`MSBTS_ReceiveLocation`-Abfrage auch die dokumentierten
+Transportadressen. Fehlt die Datei
+
+```text
+%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml
+```
+
+wird sie im ersten erfolgreichen Lauf erzeugt. Danach erfolgt der vollstaendige
+Abgleich alle `EndpointDiscoveryIntervalHours` (Default: 168 Stunden). Ein
+Fehler beim Abgleich ersetzt keinen letzten gueltigen Katalog. Checkmk meldet
+den ueberfaelligen/fehlgeschlagenen Abgleich trotzdem als `UNKNOWN`.
+
+Unabhaengig vom Wochenabgleich wird bei jedem Minutenlauf gegen den aktuellen
+BizTalk-Runtimezustand gefiltert:
+
+- Receive Location nur bei `IsDisabled=false`
+- Send Port nur bei `Status=Started`
+- dynamischer Send Port nie als statisches Ziel
+
+Damit wird ein inzwischen gestopptes/deaktiviertes Artefakt sofort nicht mehr
+geprueft. Neue Artefakte werden spaetestens beim naechsten Wochenabgleich
+aufgenommen.
+
+## Sicherheitsmodell
+
+Der Katalog speichert nicht die vollstaendige BizTalk-Adresse. Persistiert
+werden nur:
+
+- Artefakttyp, Anwendung, Name und Transportrolle
+- Adaptername
+- `TCP` oder `UDP`
+- Host und Port
+- `enabled` und `autoDiscovered`
+
+URI-Benutzerinformationen, Kennwoerter, Pfade und Querystrings werden nicht
+geschrieben. Der Katalog liegt im bereits ACL-geschuetzten `data`-Verzeichnis;
+nur Provider und Administratoren duerfen ihn aendern. `LocalSystem` liest nur
+den separaten, validierten Checkmk-Snapshot.
+
+## Manuelle Korrektur eines automatisch nicht aufloesbaren Endpoints
+
+Vor einer manuellen Aenderung den Scheduled Task kurz stoppen und die Datei
+sichern. Einen vorhandenen Eintrag auf den gewuenschten Host/Port korrigieren
+und `autoDiscovered="false"` setzen. Der vorhandene `key` bleibt unveraendert:
+
+```xml
+<Endpoint
+  key="SENDPORT|ORDERS|SP ORDER OUT|PRIMARY"
+  artifactType="SendPort"
+  application="Orders"
+  artifact="SP Order Out"
+  transportRole="Primary"
+  adapter="Custom Adapter"
+  protocol="TCP"
+  host="gateway.example.internal"
+  port="7443"
+  enabled="true"
+  autoDiscovered="false" />
+```
+
+Manuelle Eintraege werden beim Wochenabgleich erhalten. Stimmen Artefakttyp
+und `key` mit einem Send-/Receive-Artefakt ueberein, gilt weiterhin dessen
+Started-/Enabled-Filter. Ein zusaetzliches, nicht an BizTalk gebundenes Ziel
+kann `artifactType="Manual"` verwenden; es wird bei `enabled="true"` immer
+geprueft.
+
+Nach dem Speichern Task wieder starten und pruefen:
+
+```powershell
+Start-ScheduledTask -TaskName 'BizTalk Checkmk Pulse Provider'
+Get-Content "$env:ProgramData\BizTalkCheckmkPulse\logs\*.log" -Tail 100
+& "$env:ProgramFiles\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
+```
+
+Ungueltiges XML, doppelte Keys, falsche Maschine/Umgebung, unbekannte
+Protokolle, ungueltige Ports und uebergrosse Dateien werden verworfen. Der
+Provider kann bei vollstaendig verfuegbarem BizTalk-Runtimezustand einen
+ungueltigen rein automatisch erzeugten Katalog neu aufbauen. Deshalb muss ein
+manueller Eintrag vor dem produktiven Einsatz gesichert und im Provider-Log
+verifiziert werden.
+
+## Protokollgrenzen
+
+TCP-Connect ist fuer HTTP(S), SFTP, FTP, SMB/UNC, WCF und `net.tcp` der
+passende nebenwirkungsfreie Netzwerktest. Er bestaetigt DNS, Routing,
+Firewall und einen annehmenden TCP-Port, aber nicht die fachliche Antwort der
+Zielanwendung.
+
+UDP ist verbindungslos. Bei `udp://host:port` bestaetigt der Check nur DNS,
+Route und erfolgreichen lokalen Datagrammversand. Fuer einen belastbaren
+UDP-Dienstcheck waere ein adapter-/protokollspezifisches Request/Response-
+Payload erforderlich; ein solches fachliches Paket wird bewusst nicht
+erfunden.