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:

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.

Warum die Architektur geändert 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. 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

Beispielausgaben: docs/ExampleOutput.md

Endpoint-Katalog, manuelle Overrides und Protokollgrenzen: 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

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:

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:

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

BizTalkCheckmkPulse-Setup.zip auf dem Zielserver vollständig entpacken.
Setup.exe starten und die UAC-Abfrage bestätigen.
Collector-Konto, zum Beispiel BEW\t231bizmon, Kennwort und Umgebung eingeben.
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:

prüft Paket und neun Self-Test-Zeilen, bevor der bestehende Task angehalten wird,
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,
schaltet die Programmdateien per Verzeichniswechsel um; bei einem Fehler werden vorherige Version, Wrapper und Task best effort wiederhergestellt,
behält %ProgramData%\BizTalkCheckmkPulse mit Endpoint-Katalog, Snapshot und Logs bei,
installiert EXE und Config nach %ProgramFiles%\BizTalkCheckmkPulse,
setzt explizite ACLs für Administratoren, Provider und LocalSystem,
installiert nur den kleinen .cmd-Consumer unter %ProgramData%\checkmk\agent\local,
registriert BizTalk Checkmk Pulse Provider minütlich mit IgnoreNew, fünf Minuten Laufzeitlimit und zwei Wiederholungen,
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:

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

Provider-Log:

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

Snapshot und Consumer:

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

Verbindlicher Test im echten LocalSystem-Kontext:

"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

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

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

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)
Microsoft: MSBTS_ReceiveLocation (WMI)
Microsoft: SQL-Adapter-Verbindungs-URI
Microsoft: Oracle-Database-Adapter-Verbindungs-URI
Checkmk: Windows Agent und Local Checks

Die genauen Links stehen in Dokumentation.md.