# BizTalk Checkmk Pulse `BizTalk Checkmk Pulse` ist ein robuster Checkmk-2.4-Local-Check für Microsoft BizTalk Server 2020 auf Windows Server 2019. Die Anwendung trennt den berechtigten BizTalk-Datenzugriff vollständig 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 Identitätswechsel vor. ## Endpoint-Erreichbarkeitsprüfung Der Provider prüft die netzwerktechnische Erreichbarkeit der externen Ziele aktiver BizTalk Send Ports und Receive Locations. Die Funktion ist im eigenen Checkmk-Service `BizTalk Endpoint Reachability` zusammengefasst: - Berücksichtigt 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 vollständiger 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 geprüft. 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 ausschließlich die nicht erreichbaren Endpunkte ausgegeben; lange Listen sind begrenzt, die Metriken bleiben vollständig. - Doppelte Protokoll-/Host-/Port-Ziele werden nur einmal verbunden. Mit den Defaults benötigen 70 vollständig timeoutende eindeutige Ziele theoretisch etwa 15 Sekunden; die harte Standardgrenze von 100 Zielen liegt bei etwa 21 Sekunden. Der Checkmk-Agent führt diese Netzwerkprobes nicht selbst aus. Er liest als `LocalSystem` weiterhin ausschließlich den validierten lokalen Snapshot. Details zum Katalog und zu manuellen Overrides stehen in [docs/EndpointCatalog.md](docs/EndpointCatalog.md). ## Warum die Architektur geändert 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. Datenbankgestützte WMI-Abfragen wurden jedoch am SQL Server als Maschinenkonto `BEW\AV23AGPWBIO1$` abgewiesen. Eine Mitgliedschaft des Computerkontos würde die BizTalk-Netzwerkberechtigung allen als `LocalSystem` laufenden Diensten des Servers geben. Die neue Trennung reduziert diesen Berechtigungsumfang. Für 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 benötigte WMI-Klasse trotz bestätigter Read-Only-Zuordnung abgewiesen wird. Direkte SQL-Logins, manuelle Datenbankrollen und `sysadmin` sind keine Lösung. ## Robustheit Der Datenaustausch ist bewusst defensiv: - Der Provider schreibt zuerst eine eindeutige Temporärdatei im Zielordner, leert Betriebssystempuffer und ersetzt danach den Snapshot atomar. - Der Snapshot enthält Formatversion, UTC-Zeit, Quellmaschine, Provider-Identität, Zeilenanzahl und SHA-256 des Payloads. - Der Consumer akzeptiert nur denselben Rechner, gültiges UTF-8, intakte Checkmk-Zeilen, korrekte SHA-256-Prüfsumme und ein maximales Alter von standardmäßig 180 Sekunden. - Fehlende, veraltete, abgeschnittene, manipulierte oder unlesbare Dateien ergeben neun gültige `UNKNOWN`-Services statt einer kaputten Agent-Ausgabe. - Ein exklusives Lock und die Task-Einstellung `IgnoreNew` verhindern überlappende Providerläufe. - Ein unerwarteter Providerfehler erzeugt nach Möglichkeit einen aktuellen `UNKNOWN`-Snapshot und einen ungleich null lautenden Task-Exitcode. - Provider und Consumer protokollieren in tägliche Dateien; die Aufbewahrung ist standardmäßig 30 Tage. - Snapshotgröße, WMI-/SQL-Timeouts, Log-Retention und Stale-Grenze sind begrenzt und konfigurierbar. ## Erzeugte Services Standardmäßig 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 ausschließlich nicht erreichbare oder wirklich unaufgelöste Ziele - Orchestrations: total, started, stopped, bound, unbound und unbekannt Der Provider nutzt für 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, WCF-SQL/mssql und UNC werden per TCP geprüft; explizite `udp://`-Ziele per UDP-Datagramm. Es werden keine HTTP-Requests, Anmeldungen oder fachlichen Nachrichten gesendet. Nicht jede aktive BizTalk-Adresse ist selbst ein Socket-Ziel. Dynamische Send Ports, lokale Pfade, SMTP-Empfänger, Named Pipes und relative HTTP-/WCF- Receive-Listener werden deshalb als erwartbar nicht socket-prüfbar behandelt und erzeugen kein `UNKNOWN`. Nur eine aktive statische Adresse, die tatsächlich ein Netzwerkziel enthalten müsste und nicht sicher aufgelöst werden kann, bleibt `UNKNOWN` und wird geheimnisfrei mit Artefakt, Adapter und Grund genannt. Der geheimnisfreie Katalog liegt unter `%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml`. Fehlt er, wird er beim nächsten erfolgreichen Providerlauf erstellt. Alle 168 Stunden wird er gegen die Umgebung abgeglichen. Automatisch verwaltete Einträge für inzwischen inaktive Artefakte verschwinden beim Abgleich; bei jedem Minutenlauf werden sie zusätzlich gegen den aktuellen Started-/Enabled-Zustand gefiltert. Pro Service werden standardmäßig maximal fünf betroffene Namen gezeigt. Weitere Treffer erscheinen nur als `(+n more)`; Details sind zusätzlich auf 1600 Zeichen begrenzt. Metriken bleiben trotzdem vollständig. 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 für die einmalige Installation - normales dediziertes AD-Servicekonto für den Provider Das Provider-Konto benötigt: - lokales Recht zur Ausführung als Scheduled Task - lokalen Lese-/Ausführungszugriff 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 läuft 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 für 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\ 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 genügt daher; ein separates PowerShell-/WiX-/MSI-Tooling wird nicht benötigt. 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 prüfen zusätzlich Snapshot-Roundtrip, atomaren Ersatz, SHA-256-Manipulation, Stale-Erkennung, stabile Fallbacks und die bestehenden BizTalk-WMI-Diagnosen. Ein Mono-Build ist eine hilfreiche Quellcodeprüfung, 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 für die Gruppe repariert, nicht als Einzelberechtigung für das Provider-Konto. ## Installation mit normalem Servicekonto 1. `BizTalkCheckmkPulse-Setup.zip` auf dem Zielserver vollständig entpacken. 2. `Setup.exe` starten und die UAC-Abfrage bestätigen. 3. Collector-Konto, zum Beispiel `BEW\t231bizmon`, Kennwort und Umgebung eingeben. 4. **Installieren / aktualisieren** wählen. Der Installer übergibt das Kennwort direkt über 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 abläuft, muss es im Scheduled Task aktualisiert werden. Dazu `Setup.exe` mit dem neuen Kennwort erneut ausführen. Bis dahin wird der Snapshot nach 180 Sekunden stale und Checkmk zeigt alle neun Services als `UNKNOWN`. Ein gMSA kann über die Checkbox ohne Kennworteingabe installiert werden; die produktive Standardbeschreibung geht vom normalen Servicekonto aus. Der Installer: 1. prüft Paket und neun Self-Test-Zeilen, bevor der bestehende Task angehalten wird, 2. baut die neue Version in einem Staging-Verzeichnis auf und übernimmt vorhandene AppSettings; neue Keys erhalten ihre neuen Defaults. Die alten unveränderten 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. behält `%ProgramData%\BizTalkCheckmkPulse` mit Endpoint-Katalog, Snapshot und Logs bei, 5. installiert EXE und Config nach `%ProgramFiles%\BizTalkCheckmkPulse`, 6. setzt explizite ACLs für Administratoren, Provider und `LocalSystem`, 7. installiert nur den kleinen `.cmd`-Consumer unter `%ProgramData%\checkmk\agent\local`, 8. registriert `BizTalk Checkmk Pulse Provider` minütlich mit `IgnoreNew`, fünf Minuten Laufzeitlimit und zwei Wiederholungen, 9. führt 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 ausführen, die neun Services aufnehmen und Changes aktivieren. Ein zusätzlicher 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/Ausführen | Lesen/Ausführen | Vollzugriff | | `data` | Ändern | Lesen/Ausführen | Vollzugriff | | `logs` | Ändern | Ändern | Vollzugriff | Der Snapshot enthält Monitoringzustand und kompakte Fehlerdetails, aber keine Passwörter oder Nachrichteninhalte. Der Consumer validiert die Datei trotzdem vollständig, 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 Eingabegröße für den Consumer. | | `LogDirectory` | `%ProgramData%\BizTalkCheckmkPulse\logs` | Tageslogs. | | `LogRetentionDays` | `30` | Provider bereinigt ältere Logs. | | `ProbeEndpointConnectivity` | `true` | Aktiviert den aggregierten TCP-/UDP-Netzwerkcheck. | | `EndpointCatalogPath` | `%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml` | Lokal gepflegte Endpoint-Konfiguration ohne vollständige URIs/Secrets. | | `EndpointCatalogMaxEntries` | `1000` | Harte Größenbegrenzung für Artefakte im Katalog. | | `EndpointDiscoveryIntervalHours` | `168` | Intervall für den vollständigen Umgebungsabgleich. | | `EndpointProbeTimeoutMilliseconds` | `3000` | Timeout je dedupliziertem Host/Port-Ziel. | | `EndpointProbeMaxConcurrency` | `16` | Begrenzte parallele Socket-Probes. | | `EndpointMaxCount` | `100` | Obergrenze eindeutiger Host/Port/Protokoll-Ziele und damit 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 für stopped/bound/unbound Orchestrations. | | `MaxSummaryItems` | `5` | Maximal angezeigte betroffene Artefakte je Service. | | `MaxDetailCharacters` | `1600` | Harte Obergrenze für Checkmk-Summary. | | `EmitPerApplicationSuspensionServices` | `false` | Zusätzliche Anwendungsservices. | | `EventLogLookbackMinutes` | `60` | Event-Log-Zeitfenster des Providers. | Nach einer Config-Änderung den Scheduled Task manuell starten. Der Consumer liest den nächsten atomar publizierten Snapshot. ## Fehlerbilder | Beobachtung | Ursache / Maßnahme | | --- | --- | | Alle neun Services melden fehlenden Snapshot | Task, Provider-Log, Task-Konto/Kennwort und ACL prüfen. | | Snapshot ist `stale` | `LastTaskResult`, Laufzeit, WMI-/SQL-Timeout und Log prüfen. | | SHA-256 oder Format ungültig | Datei nicht manuell bearbeiten; Datenträger/AV und Schreibpfad prüfen, Task neu starten. | | Provider meldet `Login failed` | Provider-Konto und exakt konfigurierte Read-Only-Gruppe sowie `BTS_READONLY_USERS` prüfen. | | Receive Locations / Send Ports sind CRIT | `affected=` prüfen; nur fachlich bewusst inaktive Namen exakt in die jeweilige Allowlist aufnehmen. | | Endpoint Reachability ist CRIT | Nur `unavailable=` prüfen; DNS, Zielport, Firewall und externen Dienst kontrollieren. | | Endpoint Reachability ist UNKNOWN | `unresolved_endpoints=`, WMI-Vollständigkeit, `endpoints.xml` und wöchentlichen Refresh prüfen; indirekte Adapterziele bei Bedarf geheimnisfrei manuell überschreiben. | | `Wmi/Schema` | Klasse/Properties gegen BizTalk-2020-Schema prüfen; keine Rechte ausweiten. | | Nur Event Log `UNKNOWN` | lokalen Application-Log-Zugriff des Provider-Kontos prüfen. | | Task-Result `2` | Parallelstart oder Snapshot-I/O; Log und Lock/ACL prüfen. | Ausführliche Betriebs- und Architekturdetails stehen in [Dokumentation.md](Dokumentation.md). ## Deinstallation `Setup.exe` erneut starten und **Deinstallieren** wählen. Snapshot und Logs bleiben dabei unter `%ProgramData%\BizTalkCheckmkPulse` erhalten. Die AD-Gruppenmitgliedschaft des Provider-Kontos wird bewusst nicht automatisch geändert 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) - Microsoft: [SQL-Adapter-Verbindungs-URI](https://learn.microsoft.com/en-us/biztalk/adapters-and-accelerators/adapter-sql/create-the-sql-server-connection-uri) - Microsoft: [Oracle-Database-Adapter-Verbindungs-URI](https://learn.microsoft.com/en-us/biztalk/adapters-and-accelerators/adapter-oracle-database/create-the-oracle-database-connection-uri) - Checkmk: Windows Agent und Local Checks Die genauen Links stehen in [Dokumentation.md](Dokumentation.md).