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.

Konkreter ACC-Befund

Auf AV23AGPWBIO1 meldet der Provider COMException HRESULT=0x80131904 und als inneren SQL-Fehler Login failed for user 'BEW\AV23AGPWBIO1$'. Das beweist zugleich:

• der Check laeuft als NT AUTHORITY\SYSTEM
• der lokale BizTalk-WMI-Namespace ist erreichbar
• der Netzwerkzugriff erfolgt als Maschinenkonto BEW\AV23AGPWBIO1$
• dieses Konto besitzt noch nicht die durch BizTalk vermittelte SQL-Berechtigung

Die vielen UNKNOWN-Services sind Folgewirkungen desselben Fehlers. WMI-Namespace-ACL, DCOM und Firewall muessen fuer diesen Befund nicht erweitert werden. Die zwei Fehler und sechs Warnungen in BizTalk Event Log sind davon unabhaengig und separat auszuwerten.

Was die neue Version aendert - und was nicht

Die neue Version verbessert Diagnose und Betriebsfuehrung:

• 0x80131904 mit Login failed for user wird als Wmi/Permission erkannt.
• Das wirklich abgewiesene Konto wird aus der Providerfehlermeldung uebernommen.
• Die unvollstaendige SQL-Zielermittlung wird als Sql/Permission statt als allgemeine Konfigurationstoerung ausgegeben.
• Nach erfolgreichem Zugriff wird die konfigurierte Gruppe als operator_group= sichtbar.

Die EXE kann und darf jedoch keine AD-Gruppenmitgliedschaft, SQL-Logins oder Datenbankrollen anlegen. Die alte Version kann nach korrekter Berechtigungsfreigabe grundsaetzlich arbeiten; die neue Version ohne Freigabe bleibt weiterhin UNKNOWN. Der Sollzustand ist daher: neue Version plus korrekte Gruppenberechtigung.

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|Login failed|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. Dienstkonto mit Get-CimInstance Win32_Service kontrollieren; der ACC-Dump bestaetigt bereits NT AUTHORITY\SYSTEM.

2. In der BizTalk Administration Console unter BizTalk Group > Properties > General den Wert BizTalk Operators Group ablesen. Alternativ kann ein berechtigtes Konto MSBTS_GroupSetting.BizTalkOperatorGroup abfragen.

3. Ein AD-Administrator fuegt das Computerobjekt AV23AGPWBIO1 genau dieser Gruppe hinzu:

   Import-Module ActiveDirectory
   $computer = Get-ADComputer -Identity 'AV23AGPWBIO1'
   Add-ADGroupMember -Identity '<EXAKTE_BIZTALK_OPERATOR_GRUPPE>' -Members $computer -WhatIf
   

   Erst nach Kontrolle ohne -WhatIf ausfuehren. Keine direkten SQL-Logins, Datenbankrollen oder sysadmin-Rechte fuer BEW\AV23AGPWBIO1$ anlegen.

4. AD-Replikation abwarten und den Server im Wartungsfenster neu starten. Alternativ Maschinen-Tickets in einer administrativen Shell mit klist purge -li 0x3e7 verwerfen und den Checkmk-Agent-Dienst neu starten.

5. Agent-Dump erneut ausfuehren. Erwartet werden operator_group=<...>, targets=2, available=2, discovery_complete=True und keine berechtigungsbedingten UNKNOWN-Services.

6. Nur bei weiterhin abgelehnten, konkret identifizierten WMI-Klassen mit BizTalk- und SQL-Administration klaeren, ob erweiterte Rechte erforderlich sind.

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.

Wenn die Gruppenmitgliedschaft allein nicht genuegt

Normalerweise hat die BizTalk-Konfiguration die konfigurierte Domain-Gruppe bereits auf dem SQL Server abgebildet und ihren Datenbankbenutzern die Rolle BTS_OPERATORS zugeordnet. Das Maschinenkonto benoetigt dann keinen eigenen SQL-Login, sondern erbt den Zugriff ueber die AD-Gruppe.

Bleibt der Loginfehler nach AD-Replikation und Token-Erneuerung bestehen, prueft die SQL-Administration zunaechst read-only den Gruppenlogin:

SELECT name, type_desc
FROM sys.server_principals
WHERE name = N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>';

Anschliessend wird in BizTalkMgmtDb und BizTalkMsgBoxDb die Rollenzuordnung geprueft:

SELECT
    member_principal.name AS member_name,
    role_principal.name AS role_name
FROM sys.database_role_members AS drm
JOIN sys.database_principals AS role_principal
    ON role_principal.principal_id = drm.role_principal_id
JOIN sys.database_principals AS member_principal
    ON member_principal.principal_id = drm.member_principal_id
WHERE member_principal.name = N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>'
  AND role_principal.name = N'BTS_OPERATORS';

Liefert die Abfrage keinen passenden Eintrag, wird die fehlende Gruppenabbildung mit der BizTalk-Konfiguration verglichen und durch BizTalk-/SQL-Administration fuer die konfigurierte Gruppe repariert. Kein Einzel-Login fuer BEW\AV23AGPWBIO1$, keine ad-hoc Rollenvergabe und kein sysadmin als Umgehung.

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.
SQL-gestuetzte Klassen melden 0x80131904 oder Login failed for user	Das exakt genannte Computerkonto 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 Windows-Gruppen und SQL-Rollen: https://learn.microsoft.com/en-us/biztalk/core/windows-groups-and-user-accounts-in-biztalk-server
• BizTalk administrative Rollen: https://learn.microsoft.com/en-us/biztalk/core/access-control-for-administrative-roles
• BizTalk Gruppen-Eigenschaften: https://learn.microsoft.com/en-us/biztalk/core/how-to-modify-group-properties
• 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 Add-ADGroupMember: https://learn.microsoft.com/en-us/powershell/module/activedirectory/add-adgroupmember
• Microsoft klist: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/klist
• 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