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
README.md
+302 -268
View File
@@ -1,24 +1,80 @@
# BizTalk Checkmk Pulse
`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.
`BizTalk Checkmk Pulse` ist ein robuster Checkmk-2.4-Local-Check fuer Microsoft
BizTalk Server 2020 auf Windows Server 2019. Die Anwendung trennt den
berechtigten BizTalk-Datenzugriff vollstaendig vom Checkmk-Agenten:
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.
```text
Scheduled Task (dediziertes Dienstkonto oder gMSA)
|
| jede Minute: BizTalkCheckmkPulse.exe --collect
v
lokales BizTalk-WMI + BizTalk-SQL + Application Event Log
|
| atomarer, versionierter, SHA-256-geschuetzter Snapshot
v
%ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot
^
| nur lesen: BizTalkCheckmkPulse.exe --consume
|
Checkmk Windows Agent (LocalSystem)
|
v
sechs stabile Checkmk Local Checks
```
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.
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 Identitaetswechsel vor.
## Warum Local Check statt serverseitigem Check-Plugin?
## Warum die Architektur geaendert wurde
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:
Der ACC-Test vom 29.07.2026 zeigte:
- 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
```text
Login failed for user 'BEW\AV23AGPWBIO1$'
```
## Erzeugte Checkmk-Services
Der Checkmk-Agent lief korrekt als `NT AUTHORITY\SYSTEM` und erreichte lokales
BizTalk-WMI. Datenbankgestuetzte WMI-Abfragen wurden jedoch am SQL Server als
Maschinenkonto `BEW\AV23AGPWBIO1$` abgewiesen. Eine Mitgliedschaft des
Computerkontos wuerde die BizTalk-Netzwerkberechtigung allen als `LocalSystem`
laufenden Diensten des Servers geben.
Standardmaessig entstehen diese stabilen Services:
Die neue Trennung reduziert diesen Berechtigungsumfang. Fuer 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 benoetigte WMI-Klasse trotz bestaetigter Read-Only-Zuordnung
abgewiesen wird. Direkte SQL-Logins, manuelle Datenbankrollen und `sysadmin`
sind keine Loesung.
## Robustheit
Der Datenaustausch ist bewusst defensiv:
- Der Provider schreibt zuerst eine eindeutige Temporaerdatei im Zielordner,
leert Betriebssystempuffer und ersetzt danach den Snapshot atomar.
- Der Snapshot enthaelt Formatversion, UTC-Zeit, Quellmaschine,
Provider-Identitaet, Zeilenanzahl und SHA-256 des Payloads.
- Der Consumer akzeptiert nur denselben Rechner, gueltiges UTF-8, intakte
Checkmk-Zeilen, korrekte SHA-256-Pruefsumme und ein maximales Alter von
standardmaessig 180 Sekunden.
- Fehlende, veraltete, abgeschnittene, manipulierte oder unlesbare Dateien
ergeben sechs gueltige `UNKNOWN`-Services statt einer kaputten Agent-Ausgabe.
- Ein exklusives Lock und die Task-Einstellung `IgnoreNew` verhindern
ueberlappende Providerlaeufe.
- Ein unerwarteter Providerfehler erzeugt nach Moeglichkeit einen aktuellen
`UNKNOWN`-Snapshot und einen ungleich null lautenden Task-Exitcode.
- Provider und Consumer protokollieren in taegliche Dateien; die Aufbewahrung
ist standardmaessig 30 Tage.
- Snapshotgroesse, WMI-/SQL-Timeouts, Log-Retention und Stale-Grenze sind
begrenzt und konfigurierbar.
## Erzeugte Services
Standardmaessig entstehen:
- `BizTalk Platform`
- `BizTalk SQL Access`
@@ -27,323 +83,301 @@ Standardmaessig entstehen diese stabilen Services:
- `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.
Mit `EnvironmentName=ACC`, `DEV`, `TST` oder `PRD` wird die Umgebung in den
Servicenamen aufgenommen, zum Beispiel `BizTalk ACC Platform`.
Details zu Statuslogik und Metriken stehen in [docs/CheckmkServices.md](docs/CheckmkServices.md).
Beispielausgaben stehen in [docs/ExampleOutput.md](docs/ExampleOutput.md).
Die konkrete ACC-Freigabeanleitung steht als Textdatei in [docs/ACC-WMI-SQL-Berechtigung.txt](docs/ACC-WMI-SQL-Berechtigung.txt).
Statuslogik und Metriken: [docs/CheckmkServices.md](docs/CheckmkServices.md)
## Build
Beispielausgaben: [docs/ExampleOutput.md](docs/ExampleOutput.md)
Voraussetzungen auf einem Windows-Build-Host:
## Voraussetzungen
Build-Host:
- Visual Studio 2019/2022 Build Tools oder Visual Studio
- MSBuild im `PATH`
- .NET Framework 4.7.2 Developer Pack
Build:
BizTalk-Server:
- Windows Server 2019
- BizTalk Server 2020 und lokaler Namespace
`root\MicrosoftBizTalkServer`
- .NET Framework 4.7.2
- Checkmk Windows Agent
- administrativer Zugriff fuer die einmalige Installation
- dediziertes AD-Dienstkonto oder bevorzugt gMSA fuer den Provider
Das Provider-Konto benoetigt:
- lokales Recht zur Ausfuehrung als Scheduled Task
- lokalen Lese-/Ausfuehrungszugriff 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. Fuer ein gMSA
muss der BizTalk-Server das verwaltete Kennwort abrufen duerfen und das Konto
lokal installiert sein.
## Build und Tests
```cmd
scripts\build-release.cmd
```
Build plus dependency-free regression tests:
```cmd
scripts\test-release.cmd
```
Deployment-Paket erstellen:
```cmd
scripts\package-release.cmd
```
Ergebnis:
Das Paket wird unter `artifacts\BizTalkCheckmkPulse-deploy` erzeugt:
```text
artifacts\BizTalkCheckmkPulse-deploy\
BizTalkCheckmkPulse-deploy\
Install-BizTalkCheckmkPulse.ps1
Uninstall-BizTalkCheckmkPulse.ps1
biztalk_checkmk_pulse.cmd
BizTalkCheckmkPulse\
application\
BizTalkCheckmkPulse.exe
BizTalkCheckmkPulse.exe.config
```
Validierung nach dem Build:
Format-Self-Test ohne WMI, SQL oder Event Log:
```cmd
artifacts\BizTalkCheckmkPulse-deploy\biztalk_checkmk_pulse.cmd --self-test
artifacts\BizTalkCheckmkPulse-deploy\application\BizTalkCheckmkPulse.exe --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.
Erwartet werden exakt sechs `OK`-Zeilen. Die Regressionstests pruefen
zusaetzlich Snapshot-Roundtrip, atomaren Ersatz, SHA-256-Manipulation,
Stale-Erkennung, stabile Fallbacks und die bestehenden BizTalk-WMI-Diagnosen.
Ein Mono-Build ist eine hilfreiche Quellcodepruefung, ersetzt aber nicht die
Windows-/BizTalk-Laufzeitvalidierung.
## Installation auf dem BizTalk-Server
## Berechtigung vorbereiten
Kopiere den Inhalt von `artifacts\BizTalkCheckmkPulse-deploy` nach:
Die exakte Read-Only-Gruppe wird in der BizTalk Administration Console unter
den Eigenschaften der BizTalk-Gruppe abgelesen. Ein bereits berechtigtes Konto
kann sie alternativ ermitteln:
```powershell
Get-CimInstance `
-Namespace root/MicrosoftBizTalkServer `
-ClassName MSBTS_GroupSetting |
Select-Object Name, BizTalkReadOnlyUserGroup, BizTalkOperatorGroup,
MgmtDbServerName, MgmtDbName
```
Ein AD-Administrator nimmt das neue Provider-Konto in
`BizTalkReadOnlyUserGroup` auf. Bei einem gMSA endet der Kontoname mit `$`.
Nach AD-Replikation muss ein regulaeres Dienstkonto einen neuen Anmeldetoken
erhalten; bei gMSA wird der Task nach der Gruppenfreigabe neu gestartet.
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 fuer die Gruppe repariert, nicht als Einzelberechtigung
fuer das Provider-Konto.
## Installation mit gMSA
Deployment-Paket auf den BizTalk-Server kopieren. In administrativer Windows
PowerShell:
```powershell
Set-Location C:\Temp\BizTalkCheckmkPulse-deploy
# Optional, falls das gMSA noch nicht lokal installiert wurde:
Install-ADServiceAccount -Identity svc_biztalk_cmk
Test-ADServiceAccount -Identity svc_biztalk_cmk
.\Install-BizTalkCheckmkPulse.ps1 `
-CollectorAccount 'BEW\svc_biztalk_cmk$' `
-Gmsa `
-EnvironmentName ACC
```
## Installation mit regulaerem Dienstkonto
```powershell
Set-Location C:\Temp\BizTalkCheckmkPulse-deploy
.\Install-BizTalkCheckmkPulse.ps1 `
-CollectorAccount 'BEW\svc_biztalk_cmk' `
-EnvironmentName ACC
```
Der Installer fragt das Kennwort ueber `Get-Credential` ab und speichert es
durch die Windows-Aufgabenplanung. Das Kennwort steht weder in der
Konfigurationsdatei noch in den Logs.
Der Installer:
1. kopiert EXE und Config nach
`%ProgramFiles%\BizTalkCheckmkPulse`,
2. erstellt `%ProgramData%\BizTalkCheckmkPulse\data` und `logs`,
3. setzt explizite ACLs fuer Administratoren, Provider und `LocalSystem`,
4. installiert nur den kleinen `.cmd`-Consumer unter
`%ProgramData%\checkmk\agent\local`,
5. registriert `BizTalk Checkmk Pulse Provider` minuetlich mit
`IgnoreNew`, fuenf Minuten Laufzeitlimit und zwei Wiederholungen,
6. fuehrt den Self-Test aus und startet den Provider einmalig.
PowerShell wird nur fuer Installation und Betriebsdiagnose verwendet. Der
minuetliche Provider und der Checkmk-Consumer sind .NET-/CMD-Laufzeitcode und
haengen nicht von der PowerShell Execution Policy ab.
## Verifikation auf dem Server
Task und letzter Lauf:
```powershell
Get-ScheduledTask -TaskName 'BizTalk Checkmk Pulse Provider' |
Select-Object TaskName, State
Get-ScheduledTaskInfo -TaskName 'BizTalk Checkmk Pulse Provider' |
Select-Object LastRunTime, LastTaskResult, NextRunTime
```
Provider-Log:
```powershell
Get-ChildItem "$env:ProgramData\BizTalkCheckmkPulse\logs" |
Sort-Object LastWriteTime -Descending |
Select-Object -First 3 Name, Length, LastWriteTime
Get-Content `
"$env:ProgramData\BizTalkCheckmkPulse\logs\biztalk-checkmk-pulse-*.log" `
-Tail 100
```
Snapshot und Consumer:
```powershell
Get-Item `
"$env:ProgramData\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot" |
Select-Object FullName, Length, LastWriteTimeUtc
& "$env:ProgramFiles\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
```
Verbindlicher Test im echten `LocalSystem`-Kontext:
```powershell
& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
Select-String -Pattern "BizTalk|UNKNOWN|Snapshot|Permission" -Context 0,1
```
Danach in Checkmk eine Service Discovery ausfuehren, die sechs Services
aufnehmen und Changes aktivieren. Ein zusaetzlicher 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
```text
%ProgramData%\checkmk\agent\local
%ProgramFiles%\BizTalkCheckmkPulse\
BizTalkCheckmkPulse.exe
BizTalkCheckmkPulse.exe.config
%ProgramData%\BizTalkCheckmkPulse\
data\
biztalk-checkmk-pulse.snapshot
biztalk-checkmk-pulse.snapshot.provider.lock
logs\
biztalk-checkmk-pulse-YYYYMMDD.log
%ProgramData%\checkmk\agent\local\
biztalk_checkmk_pulse.cmd
```
Zielstruktur:
ACL-Soll:
```text
%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config
```
| Pfad | Provider | LocalSystem | Administratoren |
| --- | --- | --- | --- |
| Programm | Lesen/Ausfuehren | Lesen/Ausfuehren | Vollzugriff |
| `data` | Aendern | Lesen/Ausfuehren | Vollzugriff |
| `logs` | Aendern | Aendern | Vollzugriff |
Manueller Test auf dem BizTalk-Server:
```cmd
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd" --self-test
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"
```
Agent-Ausgabe wie Checkmk sie sieht:
```cmd
"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.
Der Snapshot enthaelt Monitoringzustand und kompakte Fehlerdetails, aber keine
Passwoerter oder Nachrichteninhalte. Der Consumer validiert die Datei trotzdem
vollstaendig, bevor er sie an Checkmk weitergibt.
## Konfiguration
Die Konfiguration liegt neben der EXE:
Datei:
```text
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config
%ProgramFiles%\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. |
| `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 Eingabegroesse fuer den Consumer. |
| `LogDirectory` | `%ProgramData%\BizTalkCheckmkPulse\logs` | Tageslogs. |
| `LogRetentionDays` | `30` | Provider bereinigt aeltere Logs. |
| `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. |
| `AlertOnArtifactRuntimeIssues` | `false` | WARN fuer bewusst inaktive Artefakte aktivieren. |
| `EmitPerApplicationSuspensionServices` | `false` | Zusaetzliche Anwendungsservices. |
| `EventLogLookbackMinutes` | `60` | Event-Log-Zeitfenster des Providers. |
Empfehlung:
Nach einer Config-Aenderung den Scheduled Task manuell starten. Der Consumer
liest den naechsten atomar publizierten Snapshot.
- 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.
## Fehlerbilder
## Integration in Checkmk Managed Services Edition 2.4
| Beobachtung | Ursache / Massnahme |
| --- | --- |
| Alle sechs Services melden fehlenden Snapshot | Task, Provider-Log, Task-Konto und ACL pruefen. |
| Snapshot ist `stale` | `LastTaskResult`, Laufzeit, WMI-/SQL-Timeout und Log pruefen. |
| SHA-256 oder Format ungueltig | Datei nicht manuell bearbeiten; Datentraeger/AV und Schreibpfad pruefen, Task neu starten. |
| Provider meldet `Login failed` | Provider-Konto und exakt konfigurierte Read-Only-Gruppe sowie `BTS_READONLY_USERS` pruefen. |
| `Wmi/Schema` | Klasse/Properties gegen BizTalk-2020-Schema pruefen; keine Rechte ausweiten. |
| Nur Event Log `UNKNOWN` | lokalen Application-Log-Zugriff des Provider-Kontos pruefen. |
| Task-Result `2` | Parallelstart oder Snapshot-I/O; Log und Lock/ACL pruefen. |
Aufgaben der Checkmk-Kollegen:
Ausfuehrliche Betriebs- und Architekturdetails stehen in
[Dokumentation.md](Dokumentation.md).
1. BizTalk-Hosts in Checkmk anlegen oder bestehende Hosts pruefen.
2. Sicherstellen, dass der Checkmk Windows Agent installiert, registriert und erreichbar ist.
3. Plugin-Dateien auf die BizTalk-Server verteilen, manuell oder per Agent Bakery.
4. Optional `EnvironmentName` je Umgebung setzen, z.B. `ACC`, `DEV`, `TST` oder `PRD`.
5. Agent-Ausgabe mit `cmk-agent-ctl.exe dump` pruefen.
6. Service Discovery fuer jeden BizTalk-Host ausfuehren.
7. Gefundene `BizTalk ...` Services aufnehmen und Changes aktivieren.
8. Views, Dashboards, Servicegruppen und Benachrichtigungen fuer die BizTalk-Services konfigurieren.
Manuelle Integration:
1. Dateien auf dem BizTalk-Server nach `%ProgramData%\checkmk\agent\local` kopieren.
2. Optional `BizTalkCheckmkPulse.exe.config` je Umgebung anpassen.
3. Agent-Dump pruefen.
4. Service Discovery auf dem BizTalk-Host ausfuehren.
5. Services in ein BizTalk-Dashboard aufnehmen.
Integration ueber Agent Bakery:
1. Deployment-Dateien in der Checkmk-Site als Custom-Agent-Dateien bereitstellen.
2. Windows-Agent-Regel fuer die BizTalk-Hosts erstellen.
3. Agent backen und auf ACC/DEV/TST/PRD-BizTalk-Hosts ausrollen.
4. 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:
```text
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.
### Einordnung des ACC-Befunds vom 29.07.2026
Der Agent-Dump von `AV23AGPWBIO1` zeigt den entscheidenden inneren Providerfehler:
```text
COMException HRESULT=0x80131904
Internal error from OLEDB provider: 'Login failed for user 'BEW\AV23AGPWBIO1$'.'
```
Damit ist der lokale Namespace `root\MicrosoftBizTalkServer` bereits erreichbar. Der BizTalk-WMI-Provider kann aber seine SQL-gestuetzten Abfragen nicht ausfuehren, weil SQL Server das Computerkonto `BEW\AV23AGPWBIO1$` ablehnt. Zusaetzliche DCOM-, Firewall- oder WMI-Namespace-Rechte sind fuer diesen konkreten Fehler nicht die richtige Massnahme. Die `UNKNOWN`-Zustaende bei Platform, Host Instances, Runtime Artifacts und Suspended Instances sowie `targets=0` bei SQL Access sind Folgewirkungen derselben fehlenden Berechtigung.
`BizTalk Event Log` funktioniert unabhaengig von diesem SQL-Zugriff. Die dort sichtbaren zwei Fehler und sechs Warnungen sind echte Ereignisse im betrachteten Zeitfenster und nach Behebung der Berechtigung separat zu untersuchen.
### Codekorrektur und Berechtigungsfreigabe sind zwei getrennte Schritte
Die ueberarbeitete Version vergibt keine Windows-, Active-Directory- oder SQL-Rechte. Sie erkennt den eingebetteten SQL-Loginfehler nur korrekt, nennt das abgewiesene Konto und verhindert eine irrefuehrende Provider-/Konfigurationsdiagnose. Ohne Berechtigungsfreigabe bleibt der Check deshalb auch mit der neuen EXE `UNKNOWN`.
Der Zugriff funktioniert erst, wenn `BEW\AV23AGPWBIO1$` Mitglied der exakt konfigurierten BizTalk-Operator-Gruppe ist und das erneuerte Maschinen-Token diese Mitgliedschaft enthaelt. Normalerweise ist diese Windows-Gruppe bereits durch die BizTalk-Konfiguration als SQL-Login beziehungsweise Datenbankbenutzer mit `BTS_OPERATORS` in den BizTalk-Datenbanken eingerichtet. Das Maschinenkonto erbt diese SQL-Rechte ueber seine Gruppenmitgliedschaft; ein eigener SQL-Login fuer `BEW\AV23AGPWBIO1$` ist dann weder erforderlich noch gewuenscht.
### 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:
## Deinstallation
```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
.\Uninstall-BizTalkCheckmkPulse.ps1
```
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 Skript fragt vor dem Entfernen. Mit `-KeepRuntimeData` bleiben Snapshot und
Logs erhalten:
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.
- Ein im BizTalk-WMI-Provider eingebettetes `Login failed for user` wird als `Wmi/Permission` klassifiziert; das tatsaechlich abgewiesene Konto wird in die Diagnose und in `BizTalk SQL Access` uebernommen.
- Nach erfolgreicher Plattformabfrage zeigt `BizTalk Platform` mit `operator_group=` die von BizTalk konfigurierte Operator-Gruppe.
- 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`:
```yaml
local:
enabled: yes
execution:
- pattern: $CUSTOM_LOCAL_PATH$\biztalk_checkmk_pulse.cmd
async: yes
run: yes
cache_age: 300
```powershell
.\Uninstall-BizTalkCheckmkPulse.ps1 -KeepRuntimeData
```
### Vorgehen bei Berechtigungsfehlern
Die AD-Gruppenmitgliedschaft des Provider-Kontos wird bewusst nicht automatisch
geaendert und muss separat durch AD-/BizTalk-Administration entfernt werden.
1. Den Agent-Dienst und sein Startkonto kontrollieren:
## Certutil-Transport
```powershell
Get-CimInstance Win32_Service |
Where-Object { $_.Name -match 'check|cmk' -or $_.DisplayName -match 'checkmk' } |
Select-Object Name, DisplayName, State, StartName
```
Zu jeder Uebergabe wird ein Source-ZIP und eine certutil-kompatible
Base64-Textdatei erzeugt. Auf Windows:
2. Die exakt konfigurierte Operator-Gruppe in der BizTalk Administration Console unter `BizTalk Group` > `Properties` > `General` > `BizTalk Operators Group` ablesen. Nicht blind vom Standardnamen ausgehen. Alternativ kann ein bereits berechtigtes Konto abfragen:
```cmd
certutil -decode biztalk-checkmk-pulse-source-<datum>-<commit>.zip.b64.txt biztalk-checkmk-pulse-source.zip
certutil -hashfile biztalk-checkmk-pulse-source.zip SHA256
tar -xf biztalk-checkmk-pulse-source.zip
```
```powershell
Get-CimInstance -Namespace root/MicrosoftBizTalkServer -ClassName MSBTS_GroupSetting |
Select-Object Name, BizTalkOperatorGroup, MgmtDbServerName, MgmtDbName
```
3. Ein AD-Administrator nimmt das Computerobjekt in genau diese Gruppe auf. Fuer ACC ist das Computerobjekt `AV23AGPWBIO1`, dessen Netzwerkprincipal `BEW\AV23AGPWBIO1$` ist:
```powershell
Import-Module ActiveDirectory
$computer = Get-ADComputer -Identity 'AV23AGPWBIO1'
Add-ADGroupMember -Identity '<EXAKTE_BIZTALK_OPERATOR_GRUPPE>' -Members $computer -WhatIf
```
Nach Kontrolle der aufgeloesten Ziele wird derselbe Befehl ohne `-WhatIf` ausgefuehrt. Anschliessend die Mitgliedschaft mit `Get-ADPrincipalGroupMembership -Identity 'AV23AGPWBIO1'` pruefen.
4. AD-Replikation abwarten. Die sicherste Aktivierung ist ein Neustart des BizTalk-Servers im Wartungsfenster. Ohne Neustart kann ein Administrator die Maschinen-Tickets mit `klist purge -li 0x3e7` verwerfen und danach den zuvor ermittelten Checkmk-Agent-Dienst neu starten.
5. Den Test im echten Agent-Kontext wiederholen:
```powershell
& "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
```
6. Erwartet werden Platform und SQL Access mit vollstaendiger Zielermittlung, zwei erreichbaren Datenbankzielen und keine berechtigungsbedingten `UNKNOWN`-Services. Erst wenn eine konkret benannte Klasse danach weiter scheitert, wird deren Rollenanforderung mit BizTalk- und SQL-Administration untersucht.
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.
Bleibt `Login failed` nach bestaetigter Gruppenmitgliedschaft, AD-Replikation und Token-Erneuerung bestehen, pruefen BizTalk- und SQL-Administration die Gruppenabbildung auf dem SQL Server. Die konfigurierte Domain-Gruppe muss als Windows-Gruppenlogin aufloesbar sein und ihre Datenbankbenutzer muessen den von BizTalk vorgesehenen Rollen angehoeren, insbesondere `BTS_OPERATORS` in `BizTalkMgmtDb` und `BizTalkMsgBoxDb`. Eine fehlende oder abweichende Abbildung wird mit der BizTalk-Konfiguration abgeglichen und fuer die Gruppe repariert, nicht durch einen ad-hoc Einzel-Login fuer das Maschinenkonto umgangen.
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. |
| SQL-gestuetzte BizTalk-Klassen liefern `0x80131904`, `Login failed for user` oder `UNKNOWN` | Das in der Meldung genannte Computerkonto in die exakt konfigurierte BizTalk-Operator-Gruppe 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.
Die konkrete Datei und SHA-256-Summe werden bei der Uebergabe genannt.
## 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 Windows-Gruppen und SQL-Rollen: https://learn.microsoft.com/en-us/biztalk/core/windows-groups-and-user-accounts-in-biztalk-server
- Microsoft BizTalk administrative Rollen: https://learn.microsoft.com/en-us/biztalk/core/access-control-for-administrative-roles
- Microsoft BizTalk Gruppen-Eigenschaften: https://learn.microsoft.com/en-us/biztalk/core/how-to-modify-group-properties
- 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 `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
- Microsoft: BizTalk `MSBTS_GroupSetting.BizTalkReadOnlyUserGroup`
- Microsoft: Windows Groups and User Accounts in BizTalk Server
- Microsoft: Managing BizTalk Server Security
- Checkmk: Windows Agent und Local Checks
Die genauen Links stehen in [Dokumentation.md](Dokumentation.md).