johannes/biztalk-checkmk-pulse
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Separate BizTalk collection from Checkmk agent

Browse Source
This commit is contained in:
admin
2026-07-30 15:50:42 +02:00
parent e3d7f6a780
commit d15bb6539b
22 changed files with 2051 additions and 988 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ACC-WMI-SQL-Berechtigung.txt
+76 -113
View File
@@ -1,152 +1,115 @@
BizTalk Checkmk Pulse - ACC Berechtigungsfreigabe
Stand: 29.07.2026
BizTalk Checkmk Pulse - ACC Berechtigung und Architektur
Stand: 30.07.2026
BEFUND
======
Host: AV23AGPWBIO1
Lokale Identitaet: NT AUTHORITY\SYSTEM (LocalSystem)
Netzwerkidentitaet: BEW\AV23AGPWBIO1$
Checkmk-Identitaet: NT AUTHORITY\SYSTEM
Alte Netzwerkidentitaet: BEW\AV23AGPWBIO1$
Fehler: COMException HRESULT=0x80131904
Innerer Fehler: Login failed for user 'BEW\AV23AGPWBIO1$'
Der lokale BizTalk-WMI-Namespace ist erreichbar. Der BizTalk-WMI-Provider wird
aber bei seinem SQL-Zugriff als Maschinenkonto abgewiesen. Deshalb sind
Platform, Host Instances, Runtime Artifacts und Suspended Instances UNKNOWN.
BizTalk SQL Access kann ohne MSBTS_GroupSetting keine Ziele ermitteln.
Der lokale BizTalk-WMI-Namespace war erreichbar. Datenbankgestuetzte
BizTalk-WMI-Abfragen scheiterten am SQL-Login des Maschinenkontos.
Keine DCOM-, Firewall- oder WMI-Namespace-Rechte erweitern. Keinen direkten
SQL-Login, keine manuellen BizTalk-Datenbankrollen und kein sysadmin fuer das
Maschinenkonto anlegen.
NEUE VERBINDLICHE ARCHITEKTUR
=============================
WICHTIG ZUR NEUEN VERSION
=========================
Das Maschinenkonto erhaelt keine BizTalk-Berechtigung.
Die neue EXE repariert keine Berechtigungen. Sie erkennt den eingebetteten
SQL-Loginfehler korrekt, zeigt BEW\AV23AGPWBIO1$ und klassifiziert die
Folgediagnose als Berechtigungsproblem. Ohne die nachfolgende Freigabe bleiben
die betroffenen Checks auch mit der neuen Version UNKNOWN.
1. Ein dediziertes Dienstkonto oder bevorzugt gMSA laeuft minuetlich als
Scheduled Task "BizTalk Checkmk Pulse Provider".
2. Dieses Konto fuehrt BizTalkCheckmkPulse.exe --collect aus.
3. Es schreibt atomar einen SHA-256-geschuetzten Snapshot nach:
Die alte Version kann nach korrekter Freigabe grundsaetzlich funktionieren.
Empfohlen ist die neue Version zusammen mit der Gruppenfreigabe, weil sie
Fehlerursache, Konto und Massnahme eindeutig anzeigt.
%ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot
FREIGABE
========
4. Der Checkmk-Agent bleibt LocalSystem und startet nur den Consumer.
5. Der Consumer liest und validiert den Snapshot. Er fuehrt kein WMI und
keinen SQL-Zugriff aus.
1. Exakte Operator-Gruppe ermitteln
BERECHTIGUNG DES PROVIDER-KONTOS
================================
In der BizTalk Administration Console:
Bevorzugte Rolle fuer BizTalk Server 2020:
BizTalk Group > Properties > General > BizTalk Operators Group
BizTalk Server Read Only Users
SQL-Datenbankrolle: BTS_READONLY_USERS
Nicht ungeprueft den Standardnamen verwenden. Mit einem bereits berechtigten
Konto ist alternativ folgende Abfrage moeglich:
Die exakt konfigurierte Gruppe mit einem bereits berechtigten Konto ermitteln:
Get-CimInstance -Namespace root/MicrosoftBizTalkServer `
-ClassName MSBTS_GroupSetting |
Select-Object Name, BizTalkOperatorGroup, MgmtDbServerName, MgmtDbName
Select-Object Name, BizTalkReadOnlyUserGroup, BizTalkOperatorGroup,
MgmtDbServerName, MgmtDbName
2. Computerobjekt durch einen AD-Administrator aufnehmen
Das Provider-Konto durch AD-Administration in BizTalkReadOnlyUserGroup
aufnehmen. Nicht vom Standardnamen ausgehen.
Import-Module ActiveDirectory
$computer = Get-ADComputer -Identity 'AV23AGPWBIO1'
Add-ADGroupMember `
-Identity '<EXAKTE_BIZTALK_OPERATOR_GRUPPE>' `
-Members $computer `
-WhatIf
Die Operator-Gruppe ist nur eine begruendungspflichtige Eskalation, falls eine
konkret benoetigte WMI-Klasse trotz bestaetigter Read-Only-Zuordnung und neuem
Anmeldetoken verweigert wird.
Ziele kontrollieren und danach denselben Add-ADGroupMember-Befehl ohne
-WhatIf ausfuehren.
NICHT DURCHFUEHREN
==================
Mitgliedschaft pruefen:
- keinen SQL-Einzellogin fuer Provider- oder Maschinenkonto
- keine ad-hoc BizTalk-Datenbankrollen
- kein db_owner oder sysadmin
- keine pauschalen DCOM-/WMI-ACL-Erweiterungen
- Checkmk-Agentdienst nicht auf das Provider-Konto umstellen
- Maschinenkonto BEW\AV23AGPWBIO1$ nicht fuer diese Loesung berechtigen
Get-ADPrincipalGroupMembership -Identity 'AV23AGPWBIO1' |
Select-Object Name, SamAccountName
INSTALLATION
============
3. Neue Gruppenzugehoerigkeit aktivieren
gMSA:
AD-Replikation abwarten. Bevorzugt den BizTalk-Server in einem Wartungsfenster
neu starten. Alternativ in einer administrativen Shell:
.\Install-BizTalkCheckmkPulse.ps1 `
-CollectorAccount 'BEW\svc_biztalk_cmk$' `
-Gmsa `
-EnvironmentName ACC
klist purge -li 0x3e7
Regulaeres Dienstkonto:
Danach den zuvor eindeutig ermittelten Checkmk-Agent-Dienst neu starten. Falls
die neue Mitgliedschaft nicht wirksam wird, den Server neu starten.
.\Install-BizTalkCheckmkPulse.ps1 `
-CollectorAccount 'BEW\svc_biztalk_cmk' `
-EnvironmentName ACC
4. Im echten Checkmk-Kontext verifizieren
VERIFIKATION
============
Get-ScheduledTaskInfo -TaskName 'BizTalk Checkmk Pulse Provider'
Get-Content `
"$env:ProgramData\BizTalkCheckmkPulse\logs\*.log" `
-Tail 100
Get-Item `
"$env:ProgramData\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot"
& "$env:ProgramFiles\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
Select-String `
-Pattern "BizTalk|Login failed|Wmi/Permission|Sql/Permission|UNKNOWN" `
-Context 0,1
Select-String -Pattern "BizTalk|UNKNOWN|Permission|snapshot" -Context 0,1
Erwartetes Ergebnis:
ERWARTET
========
- BizTalk Platform ist OK und zeigt operator_group=<exakte Gruppe>.
- BizTalk SQL Access zeigt targets=2, available=2,
discovery_complete=True.
- Host Instances, Runtime Artifacts und Suspended Instances sind nicht mehr
wegen WMI-/SQL-Berechtigungen UNKNOWN.
- Kein Login failed fuer BEW\AV23AGPWBIO1$.
Der separate Event-Log-Service zeigte im Screenshot zwei Fehler und sechs
Warnungen. Diese Ereignisse bleiben nach der Berechtigungsfreigabe fachlich zu
pruefen.
WENN ES DANACH WEITERHIN SCHEITERT
==================================
Normalerweise wurde die konfigurierte BizTalk-Operator-Gruppe bereits durch die
BizTalk-Konfiguration am SQL Server eingerichtet. Das Maschinenkonto erbt ueber
seine AD-Gruppenmitgliedschaft die Rolle BTS_OPERATORS und benoetigt keinen
eigenen SQL-Login.
Bleibt "Login failed" trotz bestaetigter Mitgliedschaft, AD-Replikation und
Token-Erneuerung bestehen, prueft die SQL-Administration read-only:
SELECT name, type_desc
FROM sys.server_principals
WHERE name = N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>';
Danach jeweils in BizTalkMgmtDb und BizTalkMsgBoxDb:
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';
Fehlt die Abbildung, gleichen BizTalk- und SQL-Administration sie mit der
BizTalk-Konfiguration ab und reparieren sie fuer die konfigurierte Gruppe.
Keinen Einzel-Login oder Sonderrollen fuer BEW\AV23AGPWBIO1$ als Umgehung
anlegen.
SICHERHEIT
==========
Die Gruppenmitgliedschaft des Computerobjekts steht allen Diensten zur
Verfuegung, die auf AV23AGPWBIO1 als LocalSystem laufen und auf
Netzwerkressourcen zugreifen. Mit Security und BizTalk-Betrieb abstimmen.
Ist dies nicht akzeptabel, ist ein separater Collector unter einem dedizierten
gMSA-/Dienstkonto mit BizTalk-Operator-Rechten die sauberere Architektur. Nicht
allein fuer dieses Plugin die Identitaet des gesamten Checkmk-Agent-Dienstes
aendern.
- LastTaskResult = 0
- Snapshot wird minuetlich aktualisiert
- Provider-Log nennt das dedizierte Konto
- BizTalk Platform zeigt read_only_group=<exakte Gruppe>
- BizTalk SQL Access zeigt targets=2 und available=2
- keine berechtigungsbedingten UNKNOWN-Services
- LocalSystem besitzt auf data nur Lesezugriff
QUELLEN
=======
https://learn.microsoft.com/en-us/windows/win32/services/localsystem-account
https://learn.microsoft.com/en-us/entra/architecture/service-accounts-computer
https://learn.microsoft.com/en-us/biztalk/core/managing-biztalk-server-security
https://learn.microsoft.com/en-us/biztalk/core/windows-groups-and-user-accounts-in-biztalk-server
https://learn.microsoft.com/en-us/biztalk/core/access-control-for-administrative-roles
https://learn.microsoft.com/en-us/biztalk/core/how-to-modify-group-properties
https://learn.microsoft.com/en-us/powershell/module/activedirectory/add-adgroupmember
https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/klist
https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-biztalkreadonlyusergroup-property-wmi
https://docs.checkmk.com/latest/en/agent_windows.html
https://docs.checkmk.com/latest/en/localchecks.html
docs/CheckmkServices.md
+9 -3
View File
@@ -8,12 +8,17 @@ Alle Services werden als Checkmk Local Checks ausgegeben. Das Format ist:
Die Ausgabe ist so gebaut, dass sie auch mit Checkmk 2.4.0p4 kompatibel bleibt: zwischen den vier Feldern steht genau ein normales Leerzeichen.
Die fachlichen Daten werden minuetlich vom privilegierten Scheduled-Task-
Provider erzeugt. Der Checkmk-Agent liest als `LocalSystem` nur den
integritaets- und altersgeprueften Snapshot. Ist dieser Transport nicht
verfuegbar, liefern alle sechs stabilen Services `UNKNOWN`.
## BizTalk Platform
Zweck:
- Prueft, ob der BizTalk-WMI-Namespace erreichbar ist.
- Zeigt Server, Gruppe, konfigurierte BizTalk-Operator-Gruppe, Management-DB und Master-MessageBox-DB aus `MSBTS_GroupSetting`.
- Zeigt Server, Gruppe, konfigurierte BizTalk-Read-Only-/Operator-Gruppe, Management-DB und Master-MessageBox-DB aus `MSBTS_GroupSetting`.
Status:
@@ -31,11 +36,12 @@ Metriken:
Zweck:
- Ermittelt Management- und Master-MessageBox-Datenbank ueber `MSBTS_GroupSetting`.
- Oeffnet mit der Windows-Identitaet des Checkmk-Agentprozesses eine integrierte SQL-Verbindung.
- Oeffnet mit der Windows-Identitaet des privilegierten Provider-Tasks eine integrierte SQL-Verbindung.
- Fuehrt die harmlose Abfrage `SELECT 1` aus und schliesst die Verbindung sofort wieder.
- Zeigt lokale Ausfuehrungsidentitaet und erwartete Netzwerkidentitaet an.
Der Service ersetzt nicht das Checkmk-MSSQL-Plugin. Er prueft den fuer das BizTalk-Monitoring relevanten Zugriff des Local Checks.
Der Service ersetzt nicht das Checkmk-MSSQL-Plugin. Er prueft den fuer das
BizTalk-Monitoring relevanten Zugriff des dedizierten Provider-Kontos.
Status:
docs/ExampleOutput.md
+8 -8
View File
@@ -14,8 +14,8 @@
## Gesunder BizTalk-Server
```text
0 "BizTalk Platform" - BizTalk WMI and platform data reachable, server=BIZTALK01, group=BizTalkMgmtDb, operator_group=CONTOSO\BizTalk Server Operators, mgmt_db=SQL01\BizTalkMgmtDb, msgbox_db=SQL01\BizTalkMsgBoxDb
0 "BizTalk SQL Access" biztalk_sql_targets_total=2;;;0|biztalk_sql_targets_available=2;;;0|biztalk_sql_targets_failed=0;;1;0 SQL access targets=2, available=2, discovery_complete=True, execution_identity=NT AUTHORITY\SYSTEM, network_identity=<DOMAIN>\BIZTALK01$; databases=Management=SQL01\BizTalkMgmtDb:OK, MasterMessageBox=SQL01\BizTalkMsgBoxDb:OK
0 "BizTalk Platform" - BizTalk WMI and platform data reachable, server=BIZTALK01, group=BizTalkMgmtDb, read_only_group=CONTOSO\BizTalk Server Read Only Users, operator_group=CONTOSO\BizTalk Server Operators, mgmt_db=SQL01\BizTalkMgmtDb, msgbox_db=SQL01\BizTalkMsgBoxDb
0 "BizTalk SQL Access" biztalk_sql_targets_total=2;;;0|biztalk_sql_targets_available=2;;;0|biztalk_sql_targets_failed=0;;1;0 SQL access targets=2, available=2, discovery_complete=True, execution_identity=CONTOSO\svc_biztalk_cmk$, network_identity=CONTOSO\svc_biztalk_cmk$; databases=Management=SQL01\BizTalkMgmtDb:OK, MasterMessageBox=SQL01\BizTalkMsgBoxDb:OK
0 "BizTalk Suspended Instances" biztalk_suspended_total=0;;;0|biztalk_suspended_resumable=0;1;;0|biztalk_suspended_nonresumable=0;;1;0 No suspended BizTalk service instances found.
0 "BizTalk Host Instances" biztalk_host_instances_total=4;;;0|biztalk_host_instances_started=4;;;0|biztalk_host_instances_stopped=0;;1;0|biztalk_host_instances_pending=0;1;;0|biztalk_host_instances_unknown=0;;1;0 Host instances total=4, started=4, stopped=0, pending=0, unknown=0
0 "BizTalk Runtime Artifacts" biztalk_applications=8;;;0|biztalk_receive_locations=24;;;0|biztalk_receive_locations_disabled=0;1;;0|biztalk_send_ports=31;;;0|biztalk_send_ports_started=31;;;0|biztalk_send_ports_inactive=0;1;;0|biztalk_send_ports_unknown=0;;1;0|biztalk_orchestrations=12;;;0|biztalk_orchestrations_started=12;;;0|biztalk_orchestrations_inactive=0;1;;0|biztalk_orchestrations_unknown=0;;1;0 Applications=8; receive_locations total=24, disabled=0; send_ports total=31, started=31, inactive=0, unknown=0; orchestrations total=12, started=12, inactive=0, unknown=0
@@ -31,20 +31,20 @@
## SQL-Berechtigungsfehler
```text
3 "BizTalk SQL Access" biztalk_sql_targets_total=2;;;0|biztalk_sql_targets_available=0;;;0|biztalk_sql_targets_failed=2;;1;0 SQL access targets=2, available=0, discovery_complete=True, execution_identity=NT AUTHORITY\SYSTEM, network_identity=<DOMAIN>\BIZTALK01$; databases=Management=SQL01\BizTalkMgmtDb:FAILED, MasterMessageBox=SQL01\BizTalkMsgBoxDb:FAILED; diagnostics: Sql/Permission [Management SQL01\BizTalkMgmtDb]: SQL Server hat die integrierte Anmeldung abgelehnt. Erwartete Netzwerkidentitaet: <DOMAIN>\BIZTALK01$. Massnahme: <DOMAIN>\BIZTALK01$ in die konfigurierte BizTalk-Operator-Gruppe aufnehmen; keine direkten BizTalk-DB-Rollen vergeben. Danach Kerberos-Tickets erneuern und den Agent-Dump wiederholen. Technik: SqlException Number=18456: Login failed for user
3 "BizTalk SQL Access" biztalk_sql_targets_total=2;;;0|biztalk_sql_targets_available=0;;;0|biztalk_sql_targets_failed=2;;1;0 SQL access targets=2, available=0, discovery_complete=True, execution_identity=CONTOSO\svc_biztalk_cmk$, network_identity=CONTOSO\svc_biztalk_cmk$; databases=Management=SQL01\BizTalkMgmtDb:FAILED, MasterMessageBox=SQL01\BizTalkMsgBoxDb:FAILED; diagnostics: Sql/Permission [Management SQL01\BizTalkMgmtDb]: SQL Server hat die integrierte Anmeldung abgelehnt. Massnahme: Provider-Konto und konfigurierte BizTalk-Read-Only-Gruppe mit BTS_READONLY_USERS pruefen; keine direkten BizTalk-DB-Rollen vergeben. Technik: SqlException Number=18456: Login failed for user
```
## WMI-Berechtigungsfehler
```text
3 "BizTalk Suspended Instances" - Suspendierte Instanzen konnten nicht verlaesslich gelesen werden. Ein leerer Datenbestand wird nicht als OK gewertet.; diagnostics: Wmi/Permission [MSBTS_ServiceInstance]: Zugriff auf MSBTS_ServiceInstance wurde im LocalSystem-Kontext verweigert. Massnahme: Agent-Dump pruefen und Computerkonto <DOMAIN>\BIZTALK01$ zunaechst der konfigurierten BizTalk-Operator-Gruppe zuordnen. Technik: UnauthorizedAccessException HRESULT=0x80070005: Access is denied
3 "BizTalk Suspended Instances" - Suspendierte Instanzen konnten nicht verlaesslich gelesen werden. Ein leerer Datenbestand wird nicht als OK gewertet.; diagnostics: Wmi/Permission [MSBTS_ServiceInstance]: Zugriff des Provider-Kontos auf MSBTS_ServiceInstance wurde verweigert. Massnahme: Provider-Identitaet und konfigurierte BizTalk-Read-Only-Gruppe pruefen. Technik: UnauthorizedAccessException HRESULT=0x80070005: Access is denied
```
## SQL-Loginfehler innerhalb des BizTalk-WMI-Providers
## Fehlender oder veralteter Provider-Snapshot
```text
3 "BizTalk Platform" - BizTalk-Plattformdaten konnten nicht vollstaendig gelesen werden.; diagnostics: Wmi/Permission [MSBTS_GroupSetting]: BizTalk-WMI-Provider konnte den SQL-Zugriff fuer BEW\AV23AGPWBIO1$ nicht anmelden. Massnahme: Computerkonto BEW\AV23AGPWBIO1$ der in der BizTalk-Gruppe konfigurierten BizTalk-Operator-Gruppe zuordnen; keine direkten SQL-Logins oder Datenbankrollen vergeben. Technik: COMException HRESULT=0x80131904: Internal error from OLEDB provider: 'Login failed for user 'BEW\AV23AGPWBIO1$'.'
3 "BizTalk SQL Access" biztalk_sql_targets_total=0;;;0|biztalk_sql_targets_available=0;;;0|biztalk_sql_targets_failed=0;;1;0 SQL access targets=0, available=0, discovery_complete=False, execution_identity=NT AUTHORITY\SYSTEM, network_identity=BEW\AV23AGPWBIO1$; diagnostics: Sql/Permission [BizTalk database discovery]: SQL-Zielermittlung ist unvollstaendig, weil der BizTalk-WMI-Provider beim SQL-Zugriff abgewiesen wurde.
3 "BizTalk Platform" - Privilegierter BizTalk-Datensnapshot nicht verfuegbar: Snapshot is stale: age=241s, maximum=180s. Massnahme: Scheduled Task 'BizTalk Checkmk Pulse Provider', Provider-Log, Snapshot-Alter und ACL pruefen.
3 "BizTalk SQL Access" - Privilegierter BizTalk-Datensnapshot nicht verfuegbar: Snapshot is stale: age=241s, maximum=180s. Massnahme: Scheduled Task 'BizTalk Checkmk Pulse Provider', Provider-Log, Snapshot-Alter und ACL pruefen.
```
## WMI-Schemafehler
@@ -56,5 +56,5 @@
## Fehlendes Deployment
```text
3 "BizTalk Platform" - BizTalkCheckmkPulse.exe fehlt unter C:\ProgramData\checkmk\agent\local\BizTalkCheckmkPulse. Massnahme: Deployment-Paket und Dateirechte pruefen und danach cmk-agent-ctl.exe dump erneut ausfuehren.
3 "BizTalk Platform" - BizTalkCheckmkPulse.exe fehlt unter C:\Program Files\BizTalkCheckmkPulse. Massnahme: Install-BizTalkCheckmkPulse.ps1 erneut als Administrator ausfuehren und danach cmk-agent-ctl.exe dump erneut ausfuehren.
```
docs/Integration.md
+112 -217
View File
@@ -1,247 +1,142 @@
# Integration in Checkmk
# Checkmk-Integration und Betriebsuebergabe
## Zielstruktur auf dem BizTalk-Server
## Verantwortungsgrenzen
| Team | Aufgabe |
| --- | --- |
| AD/Security | dediziertes Dienstkonto oder gMSA; Aufnahme in exakt konfigurierte BizTalk-Read-Only-Gruppe |
| BizTalk/SQL | Gruppenabbildung und `BTS_READONLY_USERS` bestaetigen; keine Einzelrechte |
| Windows | Paket installieren, ACL und Scheduled Task pruefen |
| Checkmk | Wrapper verteilen beziehungsweise Installation koordinieren, Discovery und Alarmierung |
Der Checkmk-Agent bleibt `LocalSystem`. Er greift weder auf BizTalk-WMI noch
auf SQL zu. Der minuetliche Scheduled Task sammelt unter dem privilegierten
Provider-Konto und publiziert einen validierbaren Snapshot.
## Installation
gMSA:
```powershell
.\Install-BizTalkCheckmkPulse.ps1 `
-CollectorAccount 'BEW\svc_biztalk_cmk$' `
-Gmsa `
-EnvironmentName ACC
```
Regulaeres Dienstkonto:
```powershell
.\Install-BizTalkCheckmkPulse.ps1 `
-CollectorAccount 'BEW\svc_biztalk_cmk' `
-EnvironmentName ACC
```
Der Installer legt den Local Check hier ab:
```text
%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:
```cmd
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd" --self-test
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"
```
5. Agent-Ausgabe pruefen:
```cmd
"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:
Die EXE liegt zentral hier:
```text
DOMAIN\BIZTALKSERVER$
%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe
```
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.
## Checkmk-Agent-Konfiguration
### Konkreter ACC-Befund
Der Wrapper darf synchron laufen, da er nur einen kleinen lokalen Snapshot
liest. Eine alte Async-Regel mit `cache_age: 300` aus der direkten
WMI-Architektur soll entfernt werden; andernfalls addiert sie eine unnoetige
Verzoegerung zum minuetlichen Provider.
Auf `AV23AGPWBIO1` meldet der Provider `COMException HRESULT=0x80131904` und als inneren SQL-Fehler `Login failed for user 'BEW\AV23AGPWBIO1$'`. Das beweist zugleich:
Aktive Agentkonfiguration pruefen:
- 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
```powershell
& "C:\Program Files (x86)\checkmk\service\check_mk_agent.exe" showconfig local
```
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:
Verbindlicher Agent-Dump:
```powershell
& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
Select-String -Pattern "BizTalk|Login failed|Access denied|Unauthorized|UNKNOWN" -Context 0,1
Select-String -Pattern "BizTalk|UNKNOWN|snapshot|Permission" -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.
## Service Discovery
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.
1. Provider dreimal erfolgreich laufen lassen.
2. `LastTaskResult=0`, frischen Snapshot und Log pruefen.
3. Agent-Dump im `LocalSystem`-Kontext pruefen.
4. Service Discovery fuer den BizTalk-Host ausfuehren.
5. sechs stabile Services aufnehmen.
6. Changes aktivieren.
7. Views, Servicegruppen und Benachrichtigungen einrichten.
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`:
Host-Tags:
```yaml
local:
enabled: yes
execution:
- pattern: $CUSTOM_LOCAL_PATH$\biztalk_checkmk_pulse.cmd
async: yes
run: yes
cache_age: 300
```text
env:ACC|DEV|TST|PRD
app:biztalk
```
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:
```powershell
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:
```sql
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:
```sql
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:
Servicefilter:
```text
Service starts with: BizTalk
```
Dashboard-Kacheln:
## Bakery-/Softwareverteilung
- 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
Die komplette Installation umfasst mehr als eine Dateiablage:
- Programmdateien unter `%ProgramFiles%`,
- Runtimeverzeichnisse und ACLs,
- Scheduled Task mit Providerkonto,
- Local-Check-Wrapper.
Der Wrapper allein kann per Agent Bakery verteilt werden, ersetzt aber nicht
die lokale Providerinstallation und die Kontofreigabe. Fuer den ersten Rollout
ist das signierte/abgenommene Deployment-Paket mit administrativer
Installationsautomation die klarere Variante.
## Healthchecks
```powershell
Get-ScheduledTaskInfo -TaskName 'BizTalk Checkmk Pulse Provider'
Get-Item "$env:ProgramData\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot"
Get-Content "$env:ProgramData\BizTalkCheckmkPulse\logs\*.log" -Tail 50
& "$env:ProgramFiles\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
```
Soll:
- Task laeuft jede Minute und endet mit `0`.
- Snapshot ist kleiner als `SnapshotMaxBytes` und juenger als 180 Sekunden.
- Log nennt das dedizierte Providerkonto.
- Platform zeigt `read_only_group=...`.
- SQL Access zeigt `targets=2`, `available=2`.
- keine berechtigungsbedingten `UNKNOWN`-Services.
## Alarmierung der Transportkette
Ein Ausfall des Providers wird ueber alle sechs Services als `UNKNOWN`
sichtbar. Die Summary nennt fehlenden, unlesbaren, ungueltigen oder stale
Snapshot. Als Betriebsregel sollte `UNKNOWN` dieser Services genauso
eskaliert werden wie ein technischer Monitoringausfall.
Optional kann Windows Task Scheduler zusaetzlich durch vorhandene Checkmk
Task-/Event-Log-Regeln ueberwacht werden. Das ist eine Ergaenzung, kein Ersatz
fuer die eingebaute Stale-Pruefung.
## Rollout
Empfohlene Reihenfolge:
1. ACC: Berechtigung, Task, Snapshot, Stale-Test und Discovery abnehmen.
2. DEV/TST: gleiche Automatisierung und umgebungsspezifische Config.
3. PRD: Change, Wartungsfenster, Healthcheck und fachliche Plausibilitaet.
Ausfuehrliche Architektur, ACL, Fehlerbilder und Abnahmekriterien:
[Dokumentation.md](../Dokumentation.md).