Separate BizTalk collection from Checkmk agent

2026-07-30 15:50:42 +02:00
parent e3d7f6a780
commit d15bb6539b
22 changed files with 2051 additions and 988 deletions
@@ -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).