# 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 (dediziertes Dienstkonto oder gMSA) | | jede Minute: BizTalkCheckmkPulse.exe --collect v lokales BizTalk-WMI + BizTalk-SQL + Application Event Log | | atomarer, versionierter, SHA-256-geschuetzter Snapshot v %ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot ^ | nur lesen: BizTalkCheckmkPulse.exe --consume | Checkmk Windows Agent (LocalSystem) | v sechs stabile 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. ## 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 sechs 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 Runtime Artifacts` - `BizTalk Event Log` 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) ## 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 - dediziertes AD-Dienstkonto oder bevorzugt gMSA 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. Fuer ein gMSA muss der BizTalk-Server das verwaltete Kennwort abrufen duerfen und das Konto lokal installiert sein. ## Build und Tests ```cmd scripts\build-release.cmd scripts\test-release.cmd scripts\package-release.cmd ``` Das Paket wird unter `artifacts\BizTalkCheckmkPulse-deploy` erzeugt: ```text BizTalkCheckmkPulse-deploy\ Install-BizTalkCheckmkPulse.ps1 Uninstall-BizTalkCheckmkPulse.ps1 biztalk_checkmk_pulse.cmd application\ BizTalkCheckmkPulse.exe BizTalkCheckmkPulse.exe.config ``` Format-Self-Test ohne WMI, SQL oder Event Log: ```cmd artifacts\BizTalkCheckmkPulse-deploy\application\BizTalkCheckmkPulse.exe --self-test ``` Erwartet werden exakt sechs `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 bereits berechtigtes Konto kann sie alternativ ermitteln: ```powershell Get-CimInstance ` -Namespace root/MicrosoftBizTalkServer ` -ClassName MSBTS_GroupSetting | Select-Object Name, BizTalkReadOnlyUserGroup, BizTalkOperatorGroup, MgmtDbServerName, MgmtDbName ``` Ein AD-Administrator nimmt das neue Provider-Konto in `BizTalkReadOnlyUserGroup` auf. Bei einem gMSA endet der Kontoname mit `$`. Nach AD-Replikation muss ein regulaeres Dienstkonto einen neuen Anmeldetoken erhalten; bei gMSA wird der Task nach der Gruppenfreigabe neu gestartet. 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 gMSA Deployment-Paket auf den BizTalk-Server kopieren. In administrativer Windows PowerShell: ```powershell Set-Location C:\Temp\BizTalkCheckmkPulse-deploy # Optional, falls das gMSA noch nicht lokal installiert wurde: Install-ADServiceAccount -Identity svc_biztalk_cmk Test-ADServiceAccount -Identity svc_biztalk_cmk .\Install-BizTalkCheckmkPulse.ps1 ` -CollectorAccount 'BEW\svc_biztalk_cmk$' ` -Gmsa ` -EnvironmentName ACC ``` ## Installation mit regulaerem Dienstkonto ```powershell Set-Location C:\Temp\BizTalkCheckmkPulse-deploy .\Install-BizTalkCheckmkPulse.ps1 ` -CollectorAccount 'BEW\svc_biztalk_cmk' ` -EnvironmentName ACC ``` Der Installer fragt das Kennwort ueber `Get-Credential` ab und speichert es durch die Windows-Aufgabenplanung. Das Kennwort steht weder in der Konfigurationsdatei noch in den Logs. Der Installer: 1. kopiert EXE und Config nach `%ProgramFiles%\BizTalkCheckmkPulse`, 2. erstellt `%ProgramData%\BizTalkCheckmkPulse\data` und `logs`, 3. setzt explizite ACLs fuer Administratoren, Provider und `LocalSystem`, 4. installiert nur den kleinen `.cmd`-Consumer unter `%ProgramData%\checkmk\agent\local`, 5. registriert `BizTalk Checkmk Pulse Provider` minuetlich mit `IgnoreNew`, fuenf Minuten Laufzeitlimit und zwei Wiederholungen, 6. fuehrt den Self-Test aus und startet den Provider einmalig. PowerShell wird nur fuer Installation und Betriebsdiagnose verwendet. Der minuetliche Provider und der Checkmk-Consumer sind .NET-/CMD-Laufzeitcode und haengen nicht von der PowerShell Execution Policy ab. ## Verifikation auf dem Server Task und letzter Lauf: ```powershell Get-ScheduledTask -TaskName 'BizTalk Checkmk Pulse Provider' | Select-Object TaskName, State Get-ScheduledTaskInfo -TaskName 'BizTalk Checkmk Pulse Provider' | Select-Object LastRunTime, LastTaskResult, NextRunTime ``` Provider-Log: ```powershell Get-ChildItem "$env:ProgramData\BizTalkCheckmkPulse\logs" | Sort-Object LastWriteTime -Descending | Select-Object -First 3 Name, Length, LastWriteTime Get-Content ` "$env:ProgramData\BizTalkCheckmkPulse\logs\biztalk-checkmk-pulse-*.log" ` -Tail 100 ``` Snapshot und Consumer: ```powershell Get-Item ` "$env:ProgramData\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot" | Select-Object FullName, Length, LastWriteTimeUtc & "$env:ProgramFiles\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume ``` Verbindlicher Test im echten `LocalSystem`-Kontext: ```powershell & "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump | Select-String -Pattern "BizTalk|UNKNOWN|Snapshot|Permission" -Context 0,1 ``` Danach in Checkmk eine Service Discovery ausfuehren, die sechs 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 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. | | `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. | | `AlertOnArtifactRuntimeIssues` | `false` | WARN fuer bewusst inaktive Artefakte aktivieren. | | `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 sechs Services melden fehlenden Snapshot | Task, Provider-Log, Task-Konto 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. | | `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 ```powershell .\Uninstall-BizTalkCheckmkPulse.ps1 ``` Das Skript fragt vor dem Entfernen. Mit `-KeepRuntimeData` bleiben Snapshot und Logs erhalten: ```powershell .\Uninstall-BizTalkCheckmkPulse.ps1 -KeepRuntimeData ``` Die AD-Gruppenmitgliedschaft des Provider-Kontos wird bewusst nicht automatisch geaendert und muss separat durch AD-/BizTalk-Administration entfernt werden. ## Certutil-Transport Zu jeder Uebergabe wird ein Source-ZIP und eine certutil-kompatible Base64-Textdatei erzeugt. Auf Windows: ```cmd certutil -decode biztalk-checkmk-pulse-source--.zip.b64.txt biztalk-checkmk-pulse-source.zip certutil -hashfile biztalk-checkmk-pulse-source.zip SHA256 tar -xf biztalk-checkmk-pulse-source.zip ``` Die konkrete Datei und SHA-256-Summe werden bei der Uebergabe genannt. ## Quellen - Microsoft: BizTalk `MSBTS_GroupSetting.BizTalkReadOnlyUserGroup` - Microsoft: Windows Groups and User Accounts in BizTalk Server - Microsoft: Managing BizTalk Server Security - Checkmk: Windows Agent und Local Checks Die genauen Links stehen in [Dokumentation.md](Dokumentation.md).