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:

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:

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

Beispielausgaben: 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

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

Das Paket wird unter artifacts\BizTalkCheckmkPulse-deploy erzeugt:

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:

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:

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:

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

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:

kopiert EXE und Config nach %ProgramFiles%\BizTalkCheckmkPulse,
erstellt %ProgramData%\BizTalkCheckmkPulse\data und logs,
setzt explizite ACLs fuer Administratoren, Provider und LocalSystem,
installiert nur den kleinen .cmd-Consumer unter %ProgramData%\checkmk\agent\local,
registriert BizTalk Checkmk Pulse Provider minuetlich mit IgnoreNew, fuenf Minuten Laufzeitlimit und zwei Wiederholungen,
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:

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:

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:

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:

& "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

%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:

%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.

Deinstallation

.\Uninstall-BizTalkCheckmkPulse.ps1

Das Skript fragt vor dem Entfernen. Mit -KeepRuntimeData bleiben Snapshot und Logs erhalten:

.\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:

certutil -decode biztalk-checkmk-pulse-source-<datum>-<commit>.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.