BizTalk Checkmk Pulse ist ein lokaler Checkmk-Check fuer Microsoft BizTalk Server 2020 auf Windows. Er liest BizTalk-Betriebsdaten ueber WMI aus root\MicrosoftBizTalkServer, erzeugt Checkmk-Local-Check-Ausgaben und kann dadurch ohne serverseitigen Python-Check in Checkmk 2.4 integriert werden.

Der Ansatz ist fuer Umgebungen wie ACC, DEV, TST und PRD gedacht, in denen pro Umgebung ein BizTalk Server 2020 und ein SQL Server betrieben werden. SQL Server bleibt beim mitgelieferten Checkmk-MSSQL-Plugin; dieses Projekt ergaenzt die BizTalk-spezifische Sicht.

Die Plattform- und SQL-Zielermittlung verwendet ausschliesslich die dokumentierte WMI-Klasse MSBTS_GroupSetting. Management-Datenbank und Master-MessageBox werden ueber MgmtDbServerName/MgmtDbName sowie SubscriptionDBServerName/SubscriptionDBName gelesen. Eine Klasse MSBTS_MessageBoxSetting gehoert nicht zum BizTalk-WMI-Schema und wird bewusst nicht abgefragt.

Warum Local Check statt serverseitigem Check-Plugin?

Checkmk 2.4 kann Windows-Agent-Plugins und Local Checks direkt ausfuehren. Fuer diese Umgebung ist ein C#/.NET-Framework-Programm mit .cmd-Wrapper die robusteste Variante:

keine PowerShell-Ausfuehrung erforderlich
keine BizTalk-ExplorerOM/OperationsOM-DLL als Build-Abhaengigkeit
keine Python-Check-API-Abhaengigkeit auf der Checkmk-Site
einfache Verteilung auf die BizTalk-Maschinen per Dateiablage, Softwareverteilung oder Agent Bakery
automatische Service Discovery in Checkmk

Erzeugte Checkmk-Services

Standardmaessig entstehen diese stabilen Services:

BizTalk Platform
BizTalk SQL Access
BizTalk Suspended Instances
BizTalk Host Instances
BizTalk Runtime Artifacts
BizTalk Event Log

Wenn EnvironmentName=ACC, DEV, TST oder PRD gesetzt wird, wird der Name vor den Suffix gesetzt, z.B. BizTalk PRD Suspended Instances. Das ist praktisch, wenn die Umgebung bereits im Hostnamen oder Ordner abgebildet ist, aber nicht zwingend noetig.

Details zu Statuslogik und Metriken stehen in docs/CheckmkServices.md. Beispielausgaben stehen in docs/ExampleOutput.md.

Build

Voraussetzungen auf einem Windows-Build-Host:

Visual Studio 2019/2022 Build Tools oder Visual Studio
MSBuild im PATH
.NET Framework 4.7.2 Developer Pack

Build:

scripts\build-release.cmd

Build plus dependency-free regression tests:

scripts\test-release.cmd

Deployment-Paket erstellen:

scripts\package-release.cmd

Ergebnis:

artifacts\BizTalkCheckmkPulse-deploy\
  biztalk_checkmk_pulse.cmd
  BizTalkCheckmkPulse\
    BizTalkCheckmkPulse.exe
    BizTalkCheckmkPulse.exe.config

Validierung nach dem Build:

artifacts\BizTalkCheckmkPulse-deploy\biztalk_checkmk_pulse.cmd --self-test

Der Self-Test fuehrt keine WMI-, SQL- oder Event-Log-Abfrage aus und muss genau sechs OK-Zeilen liefern. Der Test-Runner prueft zusaetzlich UNKNOWN-Fallbacks, dynamische Application-Services, FQDN-/Kurznamensvergleich ohne WQL-Namensfilter und den dokumentierten MSBTS_GroupSetting-Queryvertrag. Die zusaetzliche lokale Verifikation mit Mono/MSBuild 16 prueft Build und Ausgabeformat, ersetzt aber nicht den Windows-/BizTalk-Test.

Installation auf dem BizTalk-Server

Kopiere den Inhalt von artifacts\BizTalkCheckmkPulse-deploy nach:

%ProgramData%\checkmk\agent\local

Zielstruktur:

%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config

Manueller Test auf dem BizTalk-Server:

"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd" --self-test
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"

Agent-Ausgabe wie Checkmk sie sieht:

"C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump

Danach in Checkmk fuer den BizTalk-Host eine Service Discovery ausfuehren, die neuen Services aufnehmen und Changes aktivieren.

Konfiguration

Die Konfiguration liegt neben der EXE:

%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config

Wichtige Werte:

Key	Default	Bedeutung
`Server`	`.`	Lokaler BizTalk-Server. Remote-WMI ist moeglich, aber nicht empfohlen.
`ServicePrefix`	`BizTalk`	Prefix fuer alle Checkmk-Services.
`EnvironmentName`	leer	Optional `ACC`, `DEV`, `TST` oder `PRD`.
`QueryTimeoutSeconds`	`25`	WMI-Timeout pro Query.
`ProbeSqlConnectivity`	`true`	Prueft die integrierte Windows-Anmeldung an der per WMI ermittelten Management- und Master-MessageBox-Datenbank.
`SqlConnectionTimeoutSeconds`	`5`	Timeout je SQL-Ziel fuer Verbindungsaufbau und harmlose Testabfrage.
`WarnResumableThreshold`	`1`	WARN ab n resumable suspended instances.
`CritNonResumableThreshold`	`1`	CRIT ab n non-resumable suspended instances.
`AlertOnArtifactRuntimeIssues`	`false`	Wenn `true`, werden deaktivierte Receive Locations und inaktive Ports/Orchestrations als WARN gewertet.
`EmitPerApplicationSuspensionServices`	`false`	Erzeugt zusaetzliche Services pro Anwendung mit Suspensions.
`ProbeEventLog`	`true`	Liest das Windows Application Log nach BizTalk-bezogenen Sources.
`EventLogLookbackMinutes`	`60`	Zeitraum fuer Event-Log-Auswertung.
`EventLogWarnThreshold`	`1`	WARN ab n Errors oder Warnings.
`EventLogCritThreshold`	`10`	CRIT ab n Errors.

Empfehlung:

In DEV, TST, ACC: AlertOnArtifactRuntimeIssues=false, damit bewusst gestoppte Artefakte nicht rauschen.
In PRD: erst zwei Wochen beobachten; danach nur aktivieren, wenn die Runtime-Artefakte wirklich als Betriebsstandard immer aktiv sein muessen.
EmitPerApplicationSuspensionServices=true nur verwenden, wenn Anwendungsteams eigene Services benoetigen. Sonst bleibt die Discovery schlanker.

Integration in Checkmk Managed Services Edition 2.4

Aufgaben der Checkmk-Kollegen:

BizTalk-Hosts in Checkmk anlegen oder bestehende Hosts pruefen.
Sicherstellen, dass der Checkmk Windows Agent installiert, registriert und erreichbar ist.
Plugin-Dateien auf die BizTalk-Server verteilen, manuell oder per Agent Bakery.
Optional EnvironmentName je Umgebung setzen, z.B. ACC, DEV, TST oder PRD.
Agent-Ausgabe mit cmk-agent-ctl.exe dump pruefen.
Service Discovery fuer jeden BizTalk-Host ausfuehren.
Gefundene BizTalk ... Services aufnehmen und Changes aktivieren.
Views, Dashboards, Servicegruppen und Benachrichtigungen fuer die BizTalk-Services konfigurieren.

Manuelle Integration:

Dateien auf dem BizTalk-Server nach %ProgramData%\checkmk\agent\local kopieren.
Optional BizTalkCheckmkPulse.exe.config je Umgebung anpassen.
Agent-Dump pruefen.
Service Discovery auf dem BizTalk-Host ausfuehren.
Services in ein BizTalk-Dashboard aufnehmen.

Integration ueber Agent Bakery:

Deployment-Dateien in der Checkmk-Site als Custom-Agent-Dateien bereitstellen.
Windows-Agent-Regel fuer die BizTalk-Hosts erstellen.
Agent backen und auf ACC/DEV/TST/PRD-BizTalk-Hosts ausrollen.
Discovery und Dashboard-Aufnahme durchfuehren.

Die Checkmk-Dokumentation nennt fuer Windows Local Checks %ProgramData%\checkmk\agent\local und fuer Windows Agent Plugins %ProgramData%\checkmk\agent\plugins. Dieses Projekt nutzt bewusst local, weil der Zustand direkt vom Host berechnet und sofort als Checkmk-Service geliefert wird.

Berechtigungen fuer WMI und BizTalk-Datenbanken

Ausfuehrungskontext

Der Checkmk Windows Agent und der Agent Controller laufen standardmaessig als LocalSystem (NT AUTHORITY\SYSTEM). Der .cmd-Wrapper und BizTalkCheckmkPulse.exe erben diesen Sicherheitskontext.

Das Programm:

verbindet sich lokal mit \\<eigener-server>\root\MicrosoftBizTalkServer
setzt keine separaten WMI-Anmeldedaten
verwendet kein Remote-WMI
ruft keine veraendernden BizTalk-WMI-Methoden auf
liest zusaetzlich nur das lokale Windows Application Event Log

Fuer den lokalen WMI-Verbindungsaufbau und das lokale Application Event Log reichen die Rechte von LocalSystem normalerweise aus. Es muessen deshalb im Regelfall keine DCOM-, Firewall- oder WMI-Namespace-Freigaben eingerichtet werden.

Zugriff auf einen separaten SQL Server

Einige BizTalk-WMI-Klassen beziehen ihre Daten aus der BizTalk Management- oder MessageBox-Datenbank. Wenn der SQL Server auf einer anderen Maschine laeuft, greift ein unter LocalSystem ausgefuehrter Prozess im Netzwerk mit dem Computerkonto des BizTalk-Servers zu:

DOMAIN\BIZTALKSERVER$

Die weitreichenden lokalen Rechte von LocalSystem ergeben nicht automatisch Berechtigungen auf dem entfernten SQL Server. Deshalb kann die Verbindung zum lokalen WMI-Namespace funktionieren, waehrend einzelne SQL-gestuetzte BizTalk-WMI-Abfragen mit Access denied, UnauthorizedAccessException oder UNKNOWN fehlschlagen.

Test im echten Checkmk-Kontext

Ein manueller Aufruf von BizTalkCheckmkPulse.exe oder des Wrappers verwendet das Konto der angemeldeten Person. Ein erfolgreicher manueller Test beweist daher nicht, dass die Ausfuehrung durch Checkmk als LocalSystem ebenfalls funktioniert.

Der verbindliche Test erfolgt ueber den Agent Controller:

& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
    Select-String -Pattern "BizTalk|Access denied|Unauthorized|UNKNOWN" -Context 0,1

Erwartet werden die sechs stabilen BizTalk ... Services mit plausiblen Daten. Insbesondere BizTalk Platform und BizTalk SQL Access duerfen nicht wegen eines WMI-, SQL- oder Berechtigungsfehlers UNKNOWN sein.

Das Programm prueft Berechtigungen aktiv:

Der WMI-Namespace-Verbindungsaufbau und jede erforderliche WMI-Klasse werden getrennt bewertet.
Fehler werden als Permission, Connectivity, Timeout, Configuration, Schema oder Provider klassifiziert.
BizTalk SQL Access oeffnet mit integrierter Windows-Authentifizierung eine Verbindung zur ermittelten Management- und Master-MessageBox-Datenbank und fuehrt SELECT 1 aus.
Die Service-Ausgabe nennt Ausfuehrungsidentitaet, erwartete Netzwerkidentitaet, betroffene Komponente, technische Ursache und konkrete Massnahme.
Fehlgeschlagene Pflichtabfragen werden nie als leerer, erfolgreicher Datenbestand gewertet. Der betroffene Service wird UNKNOWN.

Sql/Configuration weist je nach Detailtext entweder auf eine unvollstaendige WMI-Zielermittlung oder auf TLS-, Zertifikats-, SPN-/SSPI-Probleme hin. Die Diagnose empfiehlt bewusst nicht, SQL-Verschluesselung pauschal abzuschalten.

Wmi/Schema kennzeichnet InvalidClass oder InvalidQuery. Das ist kein Berechtigungsfehler: Klassen- und Property-Namen muessen gegen das installierte BizTalk-WMI-Schema geprueft werden; eine Rechteerhoehung kann eine nicht vorhandene Klasse nicht erzeugen. Die technischen Details enthalten die ausgefuehrte WQL-Abfrage und deren Laufzeit bis zum Fehler.

Der SQL-Zugriffstest ersetzt nicht das Checkmk-MSSQL-Plugin auf dem SQL-Server. Er prueft ausschliesslich, ob genau die Identitaet des BizTalk Local Checks die fuer seine Diagnose benoetigten BizTalk-Datenbankziele erreichen kann.

Da bei fehlenden Rechten jeder Lauf einen abgewiesenen SQL-Login erzeugen kann, wird fuer den produktiven Betrieb eine asynchrone Ausfuehrung mit 300 Sekunden Cache empfohlen. Das begrenzt SQL-Logeintraege und Last, verzoegert einen Zustandswechsel aber um maximal fuenf Minuten. Beispiel in %ProgramData%\checkmk\agent\check_mk.user.yml:

local:
  enabled: yes
  execution:
    - pattern: $CUSTOM_LOCAL_PATH$\biztalk_checkmk_pulse.cmd
      async: yes
      run: yes
      cache_age: 300

Vorgehen bei Berechtigungsfehlern

Pruefen, unter welchem Computerkonto der BizTalk-Server im Netzwerk auftritt, normalerweise DOMAIN\BIZTALKSERVER$.
Die fuer die BizTalk-Gruppe konfigurierte Windows-Gruppe BizTalk Server Operators ermitteln. Der tatsaechliche Gruppenname kann bei der BizTalk-Konfiguration angepasst worden sein.
Das Computerkonto des BizTalk-Servers in diese Operator-Gruppe aufnehmen.
Kerberos-Tickets des Systemkontos erneuern oder den BizTalk-Server in einem Wartungsfenster neu starten.
Den Test mit cmk-agent-ctl.exe dump wiederholen.
Nur wenn konkrete WMI-Klassen weiterhin abgelehnt werden, gemeinsam mit BizTalk- und SQL-Administration pruefen, ob diese Abfrage BizTalk Server Administrators benoetigt.

Die Operator-Rolle ist fuer grundlegende Administration und Monitoring vorgesehen und kann Zustands- und Message-Flow-Informationen lesen, ohne BizTalk-Konfiguration oder Nachrichteninhalte einzusehen. Das Plugin fuehrt ausschliesslich Leseabfragen aus. Direkte manuelle Aenderungen an BizTalk-SQL-Datenbankrollen sollten nicht vorgenommen werden; die von BizTalk konfigurierte Windows-Gruppe ist die vorgesehene Berechtigungsgrenze.

Entscheidungsmatrix:

Ergebnis im Agent-Dump	Massnahme
Alle BizTalk-Services liefern plausible Daten	Keine Berechtigungsaenderung erforderlich.
Verbindung zu `root\MicrosoftBizTalkServer` scheitert	Namespace, BizTalk-WMI-Provider, WMI-Dienst und Namespace-ACL gezielt pruefen. Keine pauschalen WMI-Rechte vergeben.
Service meldet `Wmi/Schema` beziehungsweise `InvalidClass`/`InvalidQuery`	WMI-Klasse und Properties gegen das BizTalk-Schema pruefen. Keine Berechtigungen erweitern.
`BizTalk SQL Access` meldet `Sql/Permission`	Computerkonto `DOMAIN\BIZTALKSERVER$` in die konfigurierte BizTalk-Operator-Gruppe aufnehmen, Kerberos erneuern und erneut testen. Keine direkten BizTalk-DB-Rollen vergeben.
`BizTalk SQL Access` meldet `Sql/Connectivity` oder `Sql/Timeout`	Server-/Instanzname, DNS, SQL-Dienst, TCP-Protokoll, Port und Firewall aus Sicht des BizTalk-Servers pruefen.
Nur SQL-gestuetzte BizTalk-Klassen liefern `Access denied` oder `UNKNOWN`	Computerkonto `DOMAIN\BIZTALKSERVER$` zunaechst in `BizTalk Server Operators` aufnehmen.
`BizTalk Event Log` ist `UNKNOWN`	Zugriff auf das lokale Application Log pruefen; `LocalSystem` kann es normalerweise lesen.
Fehler bleibt trotz Operator-Rolle bestehen	Betroffene WMI-Klasse und BizTalk-/SQL-Rollenzuordnung mit den Fachadministratoren untersuchen.

Sicherheitsabwaegung und Alternative

Wird das Computerkonto in BizTalk Server Operators aufgenommen, erhalten alle Dienste, die auf diesem BizTalk-Server als LocalSystem laufen, diese Netzwerkberechtigung. Das ist vor dem Rollout mit der Security- und BizTalk-Administration abzustimmen.

Falls diese Freigabe nicht zulaessig ist, ist die sauberere Alternative ein separater Collector unter einem dedizierten gMSA- oder Dienstkonto mit Operator-Rechten. Dieser Collector kann seine Checkmk-Ausgabe in eine Spool-Datei schreiben. Der Checkmk-Agent liest dann nur die bereits erzeugten Daten ein. Den gesamten Checkmk-Agent-Dienst sollte man nicht allein fuer dieses Plugin von LocalSystem auf ein anderes Konto umstellen, weil dadurch alle Agent-Sektionen und Local Checks betroffen sind.

Empfohlene Alarmierung:

BizTalk Platform: UNKNOWN immer untersuchen, da dann WMI, Rechte oder Deployment betroffen sind.
BizTalk SQL Access: UNKNOWN als Integrations-, Berechtigungs- oder Verbindungsproblem behandeln und die eingebettete Massnahme abarbeiten.
BizTalk Suspended Instances: in PRD direkt alarmieren; in Nicht-PRD nach Betriebsbedarf.
BizTalk Host Instances: CRIT alarmieren, weil gestoppte Host Instances Laufzeitverarbeitung verhindern koennen.
BizTalk Runtime Artifacts: zunaechst beobachten; strengere Alarmierung erst aktivieren, wenn deaktivierte Artefakte nicht fachlich gewollt sind.
BizTalk Event Log: Schwellwerte nach Beobachtungsphase anpassen.

Quellen

Checkmk Local Checks: https://docs.checkmk.com/latest/en/localchecks.html
Checkmk Windows Agent und Plugin-Pfade: https://docs.checkmk.com/latest/en/agent_windows.html
Checkmk Agent-Based Plugin-Entwicklung: https://docs.checkmk.com/latest/en/devel_check_plugins.html
Checkmk Bakery API: https://docs.checkmk.com/latest/en/bakery_api.html
Checkmk MKP-Pakete: https://docs.checkmk.com/latest/en/mkps.html
Microsoft BizTalk WMI MSBTS_ServiceInstance: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-wmi
Microsoft BizTalk WMI ServiceStatus: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-servicestatus-property-wmi
Microsoft BizTalk WMI MSBTS_GroupSetting: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-wmi
Microsoft BizTalk WMI Core Server Classes: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/core-server-classes
Microsoft BizTalk Mindestberechtigungen: https://learn.microsoft.com/en-us/biztalk/core/minimum-security-user-rights
Microsoft BizTalk Access Control: https://learn.microsoft.com/en-us/biztalk/core/access-control-and-data-security
Microsoft LocalSystem und Computerkonten: https://learn.microsoft.com/en-us/entra/architecture/service-accounts-computer
Microsoft WMI Namespace Security: https://learn.microsoft.com/en-us/windows/win32/wmisdk/access-to-wmi-namespaces