biztalk-checkmk-pulse/docs/Integration.md

Integration in Checkmk

Zielstruktur auf dem BizTalk-Server

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

Manuelle Installation

1. Release-Paket auf den BizTalk-Server kopieren.
2. Inhalt nach %ProgramData%\checkmk\agent\local kopieren.
3. Optional EnvironmentName in der .exe.config setzen.
4. Test ausfuehren:

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

5. Agent-Ausgabe pruefen:

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

6. In Checkmk:

• Host oeffnen
• Service Discovery ausfuehren
• gefundene BizTalk ... Services aufnehmen
• Changes aktivieren

Aufgaben in Checkmk

Die Checkmk-Kollegen muessen kein serverseitiges Python-Check-Plugin installieren. Das Plugin liefert bereits fertige Local-Check-Services ueber den Windows Agent. In Checkmk selbst sind diese Schritte erforderlich:

1. BizTalk-Hosts fuer ACC, DEV, TST und PRD anlegen oder vorhandene Hosts pruefen.
2. Windows-Agent-Status pruefen: Host muss Agent-Daten liefern.
3. Nach Installation des Local Checks den Agent-Dump pruefen.
4. Service Discovery fuer jeden BizTalk-Host ausfuehren.
5. Gefundene BizTalk ... Services aufnehmen.
6. Changes aktivieren.
7. Views oder Dashboards mit Filter Service starts with: BizTalk anlegen.
8. Benachrichtigungen und Eskalationen je Umgebung definieren.

Empfohlene Service-Behandlung:

Service	Empfehlung
BizTalk Platform	UNKNOWN immer als Integrationsproblem behandeln.
BizTalk SQL Access	UNKNOWN anhand der Kategorie Permission, Connectivity, Timeout, Configuration oder Provider bearbeiten.
BizTalk Suspended Instances	In PRD alarmieren; in ACC/TST/DEV nach Teamvereinbarung.
BizTalk Host Instances	CRIT alarmieren.
BizTalk Runtime Artifacts	Erst beobachten; strenge Alarmierung nur bei klar definiertem Runtime-Sollzustand.
BizTalk Event Log	Schwellwerte nach Beobachtungsphase feinjustieren.

Agent Bakery

Checkmk Managed Services Edition 2.4 enthaelt die kommerziellen Mechanismen fuer Agent Bakery. Fuer einen sauberen Rollout:

1. Deployment-Dateien als Custom Files oder ueber ein spaeteres MKP bereitstellen.
2. Regel nur auf BizTalk-Hosts anwenden, z.B. Host-Tag application:biztalk.
3. Gebackenen Windows-Agenten fuer die BizTalk-Hosts installieren.
4. Service Discovery ausfuehren.

Hinweis: Dieses Repository enthaelt bewusst noch kein Bakery-Python-Plugin. Die manuelle bzw. dateibasierte Verteilung ist die risikoarme erste Version. Eine Bakery-Erweiterung ist eine sinnvolle Version-2-Ausbaustufe.

Berechtigungen fuer WMI und BizTalk-Datenbanken

Ausfuehrung als LocalSystem

Der Checkmk Windows Agent und der Agent Controller laufen standardmaessig unter LocalSystem (NT AUTHORITY\SYSTEM). Dadurch werden auch biztalk_checkmk_pulse.cmd und BizTalkCheckmkPulse.exe in diesem Kontext gestartet.

Das Plugin verbindet sich mit dem lokalen Namespace \\<eigener-server>\root\MicrosoftBizTalkServer, setzt keine separaten Anmeldedaten und verwendet kein Remote-WMI. Es fuehrt ausschliesslich WMI-Leseabfragen aus und liest das lokale Windows Application Event Log. Fuer diese lokalen Zugriffe sind normalerweise keine zusaetzlichen DCOM-, Firewall- oder WMI-Namespace-Freigaben erforderlich.

Besonderheit bei getrenntem SQL Server

Mehrere BizTalk-WMI-Klassen lesen Daten aus der BizTalk Management- oder MessageBox-Datenbank. Bei einem getrennten SQL Server verwendet LocalSystem fuer diesen Netzwerkzugriff das Active-Directory-Computerkonto des BizTalk-Servers:

DOMAIN\BIZTALKSERVER$

Lokale Administratorrechte von LocalSystem gelten nicht automatisch auf dem entfernten SQL Server. Daher koennen SQL-gestuetzte WMI-Abfragen fehlschlagen, obwohl der lokale WMI-Namespace grundsaetzlich erreichbar ist.

Verbindlicher Funktionstest

Der direkte Start des Wrappers in einer administrativen Eingabeaufforderung ist nur ein Vorabtest, weil er mit dem angemeldeten Benutzer laeuft. Fuer die Berechtigungspruefung ist die Ausgabe unter dem echten Checkmk-Kontext massgeblich:

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

Die Ausgabe muss die sechs stabilen BizTalk ... Services mit plausiblen Daten enthalten. Access denied, UnauthorizedAccessException, Sql/Permission und ein berechtigungsbedingtes UNKNOWN weisen auf eine fehlende Rollenzuordnung hin.

Die EXE klassifiziert WMI- und SQL-Probleme und schreibt zu jeder Diagnose Massnahme: und Technik:. WMI-Schemafehler (InvalidClass/InvalidQuery) werden separat als Wmi/Schema ausgewiesen und duerfen nicht durch Rechteerweiterungen behandelt werden. Eine fehlgeschlagene erforderliche WMI-Abfrage erzeugt beim betroffenen Service immer UNKNOWN; fehlende Daten werden nicht als Nullbestand und damit nicht als OK ausgegeben.

Fuer den produktiven Betrieb wird empfohlen, den Local Check alle 300 Sekunden asynchron auszufuehren. Dadurch erzeugen fehlende SQL-Rechte nicht bei jedem Agent-Abruf neue fehlgeschlagene Logins. 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

Alternativ koennen die Checkmk-Kollegen in der Agent Bakery die Regeln Set execution mode for plug-ins and local checks und Set cache age for plug-ins and local checks verwenden. Der Cache reduziert Last und SQL-Fehlerlogs; ein Zustandswechsel wird dadurch um maximal die konfigurierte Cache-Zeit verzoegert.

Least-Privilege-Vorgehen

1. Das verwendete Computerkonto feststellen, normalerweise DOMAIN\BIZTALKSERVER$.
2. Die bei der BizTalk-Konfiguration hinterlegte Operator-Gruppe ermitteln. Sie kann anders als BizTalk Server Operators benannt sein.
3. Das Computerkonto in diese Operator-Gruppe aufnehmen.
4. Kerberos-Tickets des Systemkontos erneuern oder den Server in einem Wartungsfenster neu starten.
5. cmk-agent-ctl.exe dump erneut ausfuehren.
6. Nur bei weiterhin abgelehnten, konkret identifizierten WMI-Klassen mit BizTalk- und SQL-Administration klaeren, ob BizTalk Server Administrators erforderlich ist.

Die BizTalk-Operator-Rolle ist fuer grundlegende Administration und Monitoring vorgesehen. Sie kann Zustands- und Message-Flow-Informationen lesen, darf aber keine Konfiguration oder Nachrichteninhalte einsehen. Das entspricht dem lesenden Funktionsumfang dieses Plugins. Keine direkten SQL-Rollen in den BizTalk-Datenbanken hinzufuegen; die von BizTalk konfigurierte Windows-Gruppe soll die Berechtigungen vermitteln.

Entscheidungsmatrix:

Beobachtung	Bewertung und Massnahme
Alle sechs stabilen Services liefern plausible Werte	Keine Aenderung erforderlich.
root\MicrosoftBizTalkServer ist nicht erreichbar	BizTalk-WMI-Provider, WMI-Dienst, Namespace und dessen ACL gezielt pruefen.
Wmi/Schema beziehungsweise InvalidClass/InvalidQuery	Klassen- und Property-Namen gegen das installierte BizTalk-WMI-Schema pruefen; keine Berechtigungen erweitern.
BizTalk SQL Access meldet Sql/Permission	Maschinenkonto in die konfigurierte BizTalk-Operator-Gruppe aufnehmen, Kerberos erneuern und Agent-Dump wiederholen.
BizTalk SQL Access meldet Sql/Connectivity	SQL-Server-/Instanzname, DNS, Dienst, TCP-Port und Firewall pruefen.
BizTalk SQL Access meldet Sql/Timeout	SQL-/Netzwerkauslastung untersuchen; Timeout nur nach Ursachenanalyse anpassen.
Verbindung funktioniert, einzelne SQL-gestuetzte Klassen melden Zugriffsfehler	DOMAIN\BIZTALKSERVER$ zunaechst in die konfigurierte BizTalk-Operator-Gruppe aufnehmen.
Nur BizTalk Event Log ist UNKNOWN	Lokalen Zugriff auf das Application Event Log pruefen.
Fehler bleibt nach Operator-Zuweisung bestehen	Exakte WMI-Klasse anhand der Service-Ausgabe bestimmen und deren BizTalk-/SQL-Rollenanforderung pruefen.

Sicherheitsauswirkung und gMSA-Alternative

Die Mitgliedschaft des Computerkontos in der Operator-Gruppe gilt fuer alle Dienste, die auf dem BizTalk-Server als LocalSystem laufen und mit dem Computerkonto auf Netzwerkressourcen zugreifen. Diese Auswirkung muss mit Security und BizTalk-Betrieb abgestimmt werden.

Falls das Computerkonto keine BizTalk-Rechte erhalten darf, kann ein separater Collector unter einem dedizierten gMSA- oder Dienstkonto mit Operator-Rechten die Checkmk-Ausgabe erzeugen und als Spool-Datei bereitstellen. Das waere eine eigene Betriebsvariante und ist in der aktuellen Local-Check-Version noch nicht implementiert. Den gesamten Checkmk-Agent-Dienst nur fuer dieses Plugin auf ein anderes Konto umzustellen ist nicht empfohlen, da die Identitaetsaenderung alle Agent-Sektionen und Local Checks betrifft.

Quellen:

• Checkmk Windows Agent: https://docs.checkmk.com/latest/en/agent_windows.html
• Checkmk Local Checks: https://docs.checkmk.com/latest/en/localchecks.html
• BizTalk Minimum Security User Rights: https://learn.microsoft.com/en-us/biztalk/core/minimum-security-user-rights
• BizTalk Access Control and Data Security: https://learn.microsoft.com/en-us/biztalk/core/access-control-and-data-security
• BizTalk MSBTS_GroupSetting: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-wmi
• BizTalk WMI Core Server Classes: https://learn.microsoft.com/en-us/biztalk/core/technical-reference/core-server-classes
• 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

Empfohlene Host-Struktur

Host-Tags oder Ordner:

• env:ACC
• env:DEV
• env:TST
• env:PRD
• app:biztalk

Service-Filter fuer Views:

Service starts with: BizTalk

Dashboard-Kacheln:

• Host/Service state fuer BizTalk-Host
• Service state fuer BizTalk Suspended Instances
• Service state fuer BizTalk SQL Access
• Graph biztalk_suspended_total
• Graph biztalk_host_instances_stopped
• Graph biztalk_eventlog_errors
• MSSQL-Services des SQL-Servers daneben