biztalk-checkmk-pulse/README.md

# BizTalk Checkmk Pulse

`BizTalk Checkmk Pulse` ist ein robuster Checkmk-2.4-Local-Check fuer Microsoft
BizTalk Server 2020 auf Windows Server 2019. Die Anwendung trennt den
berechtigten BizTalk-Datenzugriff vollstaendig vom Checkmk-Agenten:

![Architektur von BizTalk Checkmk Pulse mit Provider, Endpoint-Probes, Snapshot und Checkmk-Consumer](docs/architecture.svg)

Damit bekommt `LocalSystem` keine BizTalk- oder SQL-Berechtigung. Nur das
dedizierte Provider-Konto wird in die konfigurierte BizTalk Server Read Only
Users-Gruppe aufgenommen. Der Checkmk-Consumer liest keine BizTalk-Datenbank,
verwendet kein WMI und nimmt keine Identitaetswechsel vor.

## Endpoint-Erreichbarkeitspruefung

Der Provider prueft die netzwerktechnische Erreichbarkeit der externen Ziele
aktiver BizTalk Send Ports und Receive Locations. Die Funktion ist im eigenen
Checkmk-Service `BizTalk Endpoint Reachability` zusammengefasst:

- Beruecksichtigt werden nur Send Ports mit `Status=Started` und Receive
  Locations mit `IsDisabled=false`. Dynamische Send Ports werden nicht als
  statisches Ziel interpretiert.
- Fehlt der lokale Endpoint-Katalog, wird er aus den bereits gelesenen
  `MSBTS_SendPort`- und `MSBTS_ReceiveLocation`-Daten aufgebaut. Alle
  168 Stunden erfolgt ein vollstaendiger Abgleich mit der BizTalk-Umgebung.
- HTTP(S), SFTP, FTP, WCF/`net.tcp` und UNC/SMB werden durch einen reinen
  TCP-Verbindungsaufbau zu Host und Port geprueft. Explizite
  `udp://host:port`-Ziele verwenden ein UDP-Datagramm.
- Es werden weder HTTP-Aufrufe noch Anmeldungen, fachliche Requests oder
  BizTalk-Nachrichten gesendet. Der Check validiert DNS, Netzwerkpfad,
  Firewall und bei TCP einen annehmenden Zielport, nicht die fachliche
  Funktion des entfernten Dienstes.
- Im OK-Fall meldet Checkmk nur, dass alle aktiven Endpunkte erreichbar sind.
  Bei einem Fehler werden ausschliesslich die nicht erreichbaren Endpunkte
  ausgegeben; lange Listen sind begrenzt, die Metriken bleiben vollstaendig.
- Doppelte Protokoll-/Host-/Port-Ziele werden nur einmal verbunden. Mit den Defaults
  benoetigen 70 vollstaendig timeoutende eindeutige Ziele theoretisch etwa
  15 Sekunden; die harte Standardgrenze von 100 Zielen liegt bei etwa
  21 Sekunden.

Der Checkmk-Agent fuehrt diese Netzwerkprobes nicht selbst aus. Er liest als
`LocalSystem` weiterhin ausschliesslich den validierten lokalen Snapshot.
Details zum Katalog und zu manuellen Overrides stehen in
[docs/EndpointCatalog.md](docs/EndpointCatalog.md).

## Warum die Architektur geaendert wurde

Der ACC-Test vom 29.07.2026 zeigte:

```text
Login failed for user 'BEW\AV23AGPWBIO1$'
```

Der Checkmk-Agent lief korrekt als `NT AUTHORITY\SYSTEM` und erreichte lokales
BizTalk-WMI. Datenbankgestuetzte WMI-Abfragen wurden jedoch am SQL Server als
Maschinenkonto `BEW\AV23AGPWBIO1$` abgewiesen. Eine Mitgliedschaft des
Computerkontos wuerde die BizTalk-Netzwerkberechtigung allen als `LocalSystem`
laufenden Diensten des Servers geben.

Die neue Trennung reduziert diesen Berechtigungsumfang. Fuer BizTalk Server
2020 ist die konfigurierte `BizTalk Server Read Only Users`-Gruppe mit der
SQL-Datenbankrolle `BTS_READONLY_USERS` die bevorzugte Grenze. Die
`BizTalk Server Operators`-Gruppe ist nur ein dokumentierter Fallback, wenn
eine konkret benoetigte WMI-Klasse trotz bestaetigter Read-Only-Zuordnung
abgewiesen wird. Direkte SQL-Logins, manuelle Datenbankrollen und `sysadmin`
sind keine Loesung.

## Robustheit

Der Datenaustausch ist bewusst defensiv:

- Der Provider schreibt zuerst eine eindeutige Temporaerdatei im Zielordner,
  leert Betriebssystempuffer und ersetzt danach den Snapshot atomar.
- Der Snapshot enthaelt Formatversion, UTC-Zeit, Quellmaschine,
  Provider-Identitaet, Zeilenanzahl und SHA-256 des Payloads.
- Der Consumer akzeptiert nur denselben Rechner, gueltiges UTF-8, intakte
  Checkmk-Zeilen, korrekte SHA-256-Pruefsumme und ein maximales Alter von
  standardmaessig 180 Sekunden.
- Fehlende, veraltete, abgeschnittene, manipulierte oder unlesbare Dateien
  ergeben neun gueltige `UNKNOWN`-Services statt einer kaputten Agent-Ausgabe.
- Ein exklusives Lock und die Task-Einstellung `IgnoreNew` verhindern
  ueberlappende Providerlaeufe.
- Ein unerwarteter Providerfehler erzeugt nach Moeglichkeit einen aktuellen
  `UNKNOWN`-Snapshot und einen ungleich null lautenden Task-Exitcode.
- Provider und Consumer protokollieren in taegliche Dateien; die Aufbewahrung
  ist standardmaessig 30 Tage.
- Snapshotgroesse, WMI-/SQL-Timeouts, Log-Retention und Stale-Grenze sind
  begrenzt und konfigurierbar.

## Erzeugte Services

Standardmaessig entstehen:

- `BizTalk Platform`
- `BizTalk SQL Access`
- `BizTalk Suspended Instances`
- `BizTalk Host Instances`
- `BizTalk Receive Locations`
- `BizTalk Send Ports`
- `BizTalk Endpoint Reachability`
- `BizTalk Orchestrations`
- `BizTalk Event Log`

Die drei Artefaktbereiche sind absichtlich getrennte Services. Dadurch sind
Zustand und Graphen direkt erkennbar, ohne eine lange Sammelzeile zu lesen:

- Suspensions: total, resumable, non-resumable und Routing Failure Reports
- Receive Locations: total, enabled, unerwartet/bewusst disabled und unbekannt
- Send Ports: total, started, stopped, bound, unbekannt sowie bewusst inactive
- Endpoint Reachability: nur aktive Send-/Receive-Artefakte; im OK-Fall nur
  eine Gesamtaussage, im Fehlerfall ausschliesslich nicht erreichbare Ziele
- Orchestrations: total, started, stopped, bound, unbound und unbekannt

Der Provider nutzt fuer die Endpoint-Discovery keine neue WMI-Klasse. Er liest
`PTAddress`, `STAddress`, `PTTransportType`, `STTransportType`,
`InboundTransportURL` und `AdapterName` aus den bereits vorhandenen
`MSBTS_SendPort`-/`MSBTS_ReceiveLocation`-Abfragen. Der Check selbst ist ein
reiner Host/Port-Test: HTTP(S), SFTP, FTP, WCF/net.tcp und UNC werden per TCP
geprueft; explizite `udp://`-Ziele per UDP-Datagramm. Es werden keine
HTTP-Requests, Anmeldungen oder fachlichen Nachrichten gesendet.

Der geheimnisfreie Katalog liegt unter
`%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml`. Fehlt er, wird er beim
naechsten erfolgreichen Providerlauf erstellt. Alle 168 Stunden wird er gegen
die Umgebung abgeglichen. Automatisch verwaltete Eintraege fuer inzwischen
inaktive Artefakte verschwinden beim Abgleich; bei jedem Minutenlauf werden
sie zusaetzlich gegen den aktuellen Started-/Enabled-Zustand gefiltert.

Pro Service werden standardmaessig maximal fuenf betroffene Namen gezeigt.
Weitere Treffer erscheinen nur als `(+n more)`; Details sind zusaetzlich auf
1600 Zeichen begrenzt. Metriken bleiben trotzdem vollstaendig.

Mit `EnvironmentName=ACC`, `DEV`, `TST` oder `PRD` wird die Umgebung in den
Servicenamen aufgenommen, zum Beispiel `BizTalk ACC Platform`.

Statuslogik und Metriken: [docs/CheckmkServices.md](docs/CheckmkServices.md)

Beispielausgaben: [docs/ExampleOutput.md](docs/ExampleOutput.md)

Endpoint-Katalog, manuelle Overrides und Protokollgrenzen:
[docs/EndpointCatalog.md](docs/EndpointCatalog.md)

## Voraussetzungen

Build-Host:

- Visual Studio 2019/2022 Build Tools oder Visual Studio
- MSBuild im `PATH`
- .NET Framework 4.7.2 Developer Pack

BizTalk-Server:

- Windows Server 2019
- BizTalk Server 2020 und lokaler Namespace
  `root\MicrosoftBizTalkServer`
- .NET Framework 4.7.2
- Checkmk Windows Agent
- administrativer Zugriff fuer die einmalige Installation
- normales dediziertes AD-Servicekonto fuer den Provider

Das Provider-Konto benoetigt:

- lokales Recht zur Ausfuehrung als Scheduled Task
- lokalen Lese-/Ausfuehrungszugriff auf die installierte EXE
- Schreibzugriff nur auf Snapshot- und Logverzeichnis
- Mitgliedschaft in der exakt konfigurierten BizTalk Server Read Only
  Users-Gruppe

Es soll weder lokaler Administrator noch SQL-`sysadmin` sein. Der Scheduled
Task laeuft mit `RunLevel Limited`. Das Servicekonto braucht ein gespeichertes
Task-Kennwort und das Recht `Log on as a batch job`. Ein gMSA bleibt optional,
ist aber fuer diese Installation nicht vorausgesetzt.

## Build und Tests

```cmd
scripts\build-release.cmd
scripts\test-release.cmd
scripts\package-release.cmd
```

Jeder Release-Build der Solution erzeugt automatisch den fertigen Paketordner
und das transportierbare ZIP:

```text
artifacts\
  BizTalkCheckmkPulse-Setup.zip
  BizTalkCheckmkPulse-Setup.zip.b64.txt
  BizTalkCheckmkPulse-Setup.zip.sha256.txt
  BizTalkCheckmkPulse-Setup\
    Setup.exe
    INSTALLATION.md
    biztalk_checkmk_pulse.cmd
    application\
      BizTalkCheckmkPulse.exe
      BizTalkCheckmkPulse.exe.config
```

Das Packaging-Projekt ist Teil von `BizTalkCheckmkPulse.sln`. Ein normaler
`Release`-Build in Visual Studio 2019 genuegt daher; ein separates
PowerShell-/WiX-/MSI-Tooling wird nicht benoetigt.

Die Base64-TXT kann auf dem Windows-Zielsystem ohne Zusatzwerkzeug dekodiert
werden:

```cmd
certutil -decode BizTalkCheckmkPulse-Setup.zip.b64.txt BizTalkCheckmkPulse-Setup.zip
certutil -hashfile BizTalkCheckmkPulse-Setup.zip SHA256
```

Format-Self-Test ohne WMI, SQL oder Event Log:

```cmd
artifacts\BizTalkCheckmkPulse-Setup\application\BizTalkCheckmkPulse.exe --self-test
```

Erwartet werden exakt neun `OK`-Zeilen. Die Regressionstests pruefen
zusaetzlich Snapshot-Roundtrip, atomaren Ersatz, SHA-256-Manipulation,
Stale-Erkennung, stabile Fallbacks und die bestehenden BizTalk-WMI-Diagnosen.
Ein Mono-Build ist eine hilfreiche Quellcodepruefung, ersetzt aber nicht die
Windows-/BizTalk-Laufzeitvalidierung.

## Berechtigung vorbereiten

Die exakte Read-Only-Gruppe wird in der BizTalk Administration Console unter
den Eigenschaften der BizTalk-Gruppe abgelesen.

Ein AD-Administrator nimmt das neue Provider-Konto in
`BizTalkReadOnlyUserGroup` auf. Nach AD-Replikation muss das Servicekonto durch
einen neuen Tasklauf einen neuen Anmeldetoken erhalten.

Die BizTalk-Konfiguration muss die Domain-Gruppe bereits als Windows-Login und
in `BizTalkMgmtDb`, `BizTalkMsgBoxDb`, `BizTalkDTADb`,
`BizTalkRuleEngineDb` sowie gegebenenfalls `BAMPrimaryImport` mit
`BTS_READONLY_USERS` abbilden. Eine fehlende Abbildung wird durch BizTalk- und
SQL-Administration fuer die Gruppe repariert, nicht als Einzelberechtigung
fuer das Provider-Konto.

## Installation mit normalem Servicekonto

1. `BizTalkCheckmkPulse-Setup.zip` auf dem Zielserver vollstaendig entpacken.
2. `Setup.exe` starten und die UAC-Abfrage bestaetigen.
3. Collector-Konto, zum Beispiel `BEW\t231bizmon`, Kennwort und Umgebung
   eingeben.
4. **Installieren / aktualisieren** waehlen.

Der Installer uebergibt das Kennwort direkt ueber die Windows-Task-Scheduler-
COM-Schnittstelle. Es steht weder in einer Prozesskommandozeile noch in der
Konfigurationsdatei oder in Logs. Der Backslash in `DOMAIN\Benutzer` wird als
normaler Bestandteil des Kontonamens verarbeitet.

Wenn das Kennwort rotiert oder ablaeuft, muss es im Scheduled Task aktualisiert
werden. Dazu `Setup.exe` mit dem neuen Kennwort erneut ausfuehren. Bis dahin
wird der Snapshot nach 180 Sekunden stale und Checkmk zeigt alle neun Services
als `UNKNOWN`.

Ein gMSA kann ueber die Checkbox ohne Kennworteingabe installiert werden; die
produktive Standardbeschreibung geht vom normalen Servicekonto aus.

Der Installer:

1. prueft Paket und neun Self-Test-Zeilen, bevor der bestehende Task angehalten
   wird,
2. baut die neue Version in einem Staging-Verzeichnis auf und uebernimmt
   vorhandene AppSettings; neue Keys erhalten ihre neuen Defaults. Die alten
   unveraenderten Endpoint-Defaults `12`/`500` werden auf `16`/`100` migriert,
3. schaltet die Programmdateien per Verzeichniswechsel um; bei einem Fehler
   werden vorherige Version, Wrapper und Task best effort wiederhergestellt,
4. behaelt `%ProgramData%\BizTalkCheckmkPulse` mit Endpoint-Katalog, Snapshot
   und Logs bei,
5. installiert EXE und Config nach `%ProgramFiles%\BizTalkCheckmkPulse`,
6. setzt explizite ACLs fuer Administratoren, Provider und `LocalSystem`,
7. installiert nur den kleinen `.cmd`-Consumer unter
   `%ProgramData%\checkmk\agent\local`,
8. registriert `BizTalk Checkmk Pulse Provider` minuetlich mit
   `IgnoreNew`, fuenf Minuten Laufzeitlimit und zwei Wiederholungen,
9. fuehrt den installierten Self-Test erneut aus und startet den Provider.

Installation, Update, Deinstallation und Laufzeit verwenden keine PowerShell.

## Verifikation auf dem Server

Task und letzter Lauf:

```cmd
schtasks.exe /query /tn "BizTalk Checkmk Pulse Provider" /v /fo list
```

Provider-Log:

```cmd
dir /o-d "%ProgramData%\BizTalkCheckmkPulse\logs"
type "%ProgramData%\BizTalkCheckmkPulse\logs\biztalk-checkmk-pulse-*.log"
```

Snapshot und Consumer:

```cmd
dir "%ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot"
"%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
```

Verbindlicher Test im echten `LocalSystem`-Kontext:

```cmd
"C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump
```

Danach in Checkmk eine Service Discovery ausfuehren, die neun Services
aufnehmen und Changes aktivieren. Ein zusaetzlicher Checkmk-Async-Cache ist
nicht erforderlich: Der Consumer liest nur eine kleine lokale Datei und der
Provider besitzt bereits seinen eigenen Minutentakt.

## Dateisystem und Sicherheitsgrenzen

```text
%ProgramFiles%\BizTalkCheckmkPulse\
  BizTalkCheckmkPulse.exe
  BizTalkCheckmkPulse.exe.config

%ProgramData%\BizTalkCheckmkPulse\
  data\
    biztalk-checkmk-pulse.snapshot
    biztalk-checkmk-pulse.snapshot.provider.lock
    endpoints.xml
  logs\
    biztalk-checkmk-pulse-YYYYMMDD.log

%ProgramData%\checkmk\agent\local\
  biztalk_checkmk_pulse.cmd
```

ACL-Soll:

| Pfad | Provider | LocalSystem | Administratoren |
| --- | --- | --- | --- |
| Programm | Lesen/Ausfuehren | Lesen/Ausfuehren | Vollzugriff |
| `data` | Aendern | Lesen/Ausfuehren | Vollzugriff |
| `logs` | Aendern | Aendern | Vollzugriff |

Der Snapshot enthaelt Monitoringzustand und kompakte Fehlerdetails, aber keine
Passwoerter oder Nachrichteninhalte. Der Consumer validiert die Datei trotzdem
vollstaendig, bevor er sie an Checkmk weitergibt.

## Konfiguration

Datei:

```text
%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config
```

Wichtige Werte:

| Key | Default | Bedeutung |
| --- | --- | --- |
| `EnvironmentName` | leer | Optional `ACC`, `DEV`, `TST`, `PRD`. |
| `SnapshotPath` | `%ProgramData%\BizTalkCheckmkPulse\data\...` | Gemeinsame Provider-/Consumer-Datei. |
| `SnapshotMaxAgeSeconds` | `180` | Ab diesem Alter liefert der Consumer `UNKNOWN`. |
| `SnapshotMaxBytes` | `1048576` | Harte Eingabegroesse fuer den Consumer. |
| `LogDirectory` | `%ProgramData%\BizTalkCheckmkPulse\logs` | Tageslogs. |
| `LogRetentionDays` | `30` | Provider bereinigt aeltere Logs. |
| `ProbeEndpointConnectivity` | `true` | Aktiviert den aggregierten TCP-/UDP-Netzwerkcheck. |
| `EndpointCatalogPath` | `%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml` | Lokal gepflegte Endpoint-Konfiguration ohne vollstaendige URIs/Secrets. |
| `EndpointDiscoveryIntervalHours` | `168` | Intervall fuer den vollstaendigen Umgebungsabgleich. |
| `EndpointProbeTimeoutMilliseconds` | `3000` | Timeout je dedupliziertem Host/Port-Ziel. |
| `EndpointProbeMaxConcurrency` | `16` | Begrenzte parallele Socket-Probes. |
| `EndpointMaxCount` | `100` | Harte Obergrenze und Laufzeitbudget; bei 3 s Timeout theoretisch maximal etwa 21 s. |
| `QueryTimeoutSeconds` | `25` | WMI-Timeout je Query. |
| `SqlConnectionTimeoutSeconds` | `5` | SQL-Timeout je Ziel. |
| `WarnResumableThreshold` | `1` | WARN ab n resumable Suspensions. |
| `CritNonResumableThreshold` | `1` | CRIT ab n non-resumable Suspensions. |
| `CritRoutingFailureThreshold` | `1` | CRIT ab n Routing Failure Reports. |
| `AlertOnArtifactRuntimeIssues` | `true` | Unerwartet deaktivierte Receive Locations bzw. inaktive Send Ports werden CRIT. |
| `ExpectedDisabledReceiveLocations` | leer | Pipe-getrennte exakte Allowlist: `Name` oder `Anwendung\Name`. |
| `ExpectedInactiveSendPorts` | leer | Pipe-getrennte exakte Allowlist: `Name` oder `Anwendung\Name`. |
| `AlertOnInactiveOrchestrations` | `false` | Optional WARN fuer stopped/bound/unbound Orchestrations. |
| `MaxSummaryItems` | `5` | Maximal angezeigte betroffene Artefakte je Service. |
| `MaxDetailCharacters` | `1600` | Harte Obergrenze fuer Checkmk-Summary. |
| `EmitPerApplicationSuspensionServices` | `false` | Zusaetzliche Anwendungsservices. |
| `EventLogLookbackMinutes` | `60` | Event-Log-Zeitfenster des Providers. |

Nach einer Config-Aenderung den Scheduled Task manuell starten. Der Consumer
liest den naechsten atomar publizierten Snapshot.

## Fehlerbilder

| Beobachtung | Ursache / Massnahme |
| --- | --- |
| Alle neun Services melden fehlenden Snapshot | Task, Provider-Log, Task-Konto/Kennwort und ACL pruefen. |
| Snapshot ist `stale` | `LastTaskResult`, Laufzeit, WMI-/SQL-Timeout und Log pruefen. |
| SHA-256 oder Format ungueltig | Datei nicht manuell bearbeiten; Datentraeger/AV und Schreibpfad pruefen, Task neu starten. |
| Provider meldet `Login failed` | Provider-Konto und exakt konfigurierte Read-Only-Gruppe sowie `BTS_READONLY_USERS` pruefen. |
| Receive Locations / Send Ports sind CRIT | `affected=` pruefen; nur fachlich bewusst inaktive Namen exakt in die jeweilige Allowlist aufnehmen. |
| Endpoint Reachability ist CRIT | Nur `unavailable=` pruefen; DNS, Zielport, Firewall und externen Dienst kontrollieren. |
| Endpoint Reachability ist UNKNOWN | WMI-Vollstaendigkeit, `endpoints.xml`, woechentlichen Refresh und nicht automatisch aufloesbare externe Adapteradresse pruefen. |
| `Wmi/Schema` | Klasse/Properties gegen BizTalk-2020-Schema pruefen; keine Rechte ausweiten. |
| Nur Event Log `UNKNOWN` | lokalen Application-Log-Zugriff des Provider-Kontos pruefen. |
| Task-Result `2` | Parallelstart oder Snapshot-I/O; Log und Lock/ACL pruefen. |

Ausfuehrliche Betriebs- und Architekturdetails stehen in
[Dokumentation.md](Dokumentation.md).

## Deinstallation

`Setup.exe` erneut starten und **Deinstallieren** waehlen. Snapshot und Logs
bleiben dabei unter `%ProgramData%\BizTalkCheckmkPulse` erhalten.

Die AD-Gruppenmitgliedschaft des Provider-Kontos wird bewusst nicht automatisch
geaendert und muss separat durch AD-/BizTalk-Administration entfernt werden.

## Quellen

- Microsoft: BizTalk `MSBTS_GroupSetting.BizTalkReadOnlyUserGroup`
- Microsoft: Windows Groups and User Accounts in BizTalk Server
- Microsoft: Managing BizTalk Server Security
- Microsoft: [`MSBTS_SendPort` (WMI)](https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-sendport-wmi)
- Microsoft: [`MSBTS_ReceiveLocation` (WMI)](https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-receivelocation-wmi)
- Checkmk: Windows Agent und Local Checks

Die genauen Links stehen in [Dokumentation.md](Dokumentation.md).