# 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: ```text Scheduled Task (normales dediziertes Servicekonto) | | jede Minute: BizTalkCheckmkPulse.exe --collect v lokales BizTalk-WMI + BizTalk-SQL + Application Event Log + parallele TCP-/UDP-Netzwerkprobes zu aktiven BizTalk-Endpunkten | | atomarer, versionierter, SHA-256-geschuetzter Snapshot v %ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot ^ | nur lesen: BizTalkCheckmkPulse.exe --consume | Checkmk Windows Agent (LocalSystem) | v neun kompakte Checkmk Local Checks ``` 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).