247 lines
13 KiB
Markdown
247 lines
13 KiB
Markdown
# 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.
|
|
|
|
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.
|
|
|
|
## Warum Local Check statt serverseitigem Check-Plugin?
|
|
|
|
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:
|
|
|
|
- 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
|
|
|
|
## Erzeugte Checkmk-Services
|
|
|
|
Standardmaessig entstehen diese stabilen Services:
|
|
|
|
- `BizTalk Platform`
|
|
- `BizTalk Suspended Instances`
|
|
- `BizTalk Host Instances`
|
|
- `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.
|
|
|
|
Details zu Statuslogik und Metriken stehen in [docs/CheckmkServices.md](docs/CheckmkServices.md).
|
|
Beispielausgaben stehen in [docs/ExampleOutput.md](docs/ExampleOutput.md).
|
|
|
|
## Build
|
|
|
|
Voraussetzungen auf einem Windows-Build-Host:
|
|
|
|
- Visual Studio 2022 Build Tools oder Visual Studio
|
|
- MSBuild im `PATH`
|
|
- .NET Framework 4.7.2 Developer Pack
|
|
|
|
Build:
|
|
|
|
```cmd
|
|
scripts\build-release.cmd
|
|
```
|
|
|
|
Deployment-Paket erstellen:
|
|
|
|
```cmd
|
|
scripts\package-release.cmd
|
|
```
|
|
|
|
Ergebnis:
|
|
|
|
```text
|
|
artifacts\BizTalkCheckmkPulse-deploy\
|
|
biztalk_checkmk_pulse.cmd
|
|
BizTalkCheckmkPulse\
|
|
BizTalkCheckmkPulse.exe
|
|
BizTalkCheckmkPulse.exe.config
|
|
```
|
|
|
|
Validierung nach dem Build:
|
|
|
|
```cmd
|
|
artifacts\BizTalkCheckmkPulse-deploy\biztalk_checkmk_pulse.cmd --self-test
|
|
```
|
|
|
|
## Installation auf dem BizTalk-Server
|
|
|
|
Kopiere den Inhalt von `artifacts\BizTalkCheckmkPulse-deploy` nach:
|
|
|
|
```text
|
|
%ProgramData%\checkmk\agent\local
|
|
```
|
|
|
|
Zielstruktur:
|
|
|
|
```text
|
|
%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd
|
|
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe
|
|
%ProgramData%\checkmk\agent\local\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config
|
|
```
|
|
|
|
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.
|
|
|
|
## Konfiguration
|
|
|
|
Die Konfiguration liegt neben der EXE:
|
|
|
|
```text
|
|
%ProgramData%\checkmk\agent\local\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. |
|
|
| `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. |
|
|
|
|
Empfehlung:
|
|
|
|
- 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.
|
|
|
|
## Integration in Checkmk Managed Services Edition 2.4
|
|
|
|
Aufgaben der Checkmk-Kollegen:
|
|
|
|
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.
|
|
|
|
### 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:
|
|
|
|
```powershell
|
|
& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
|
|
Select-String -Pattern "BizTalk|Access denied|Unauthorized|UNKNOWN" -Context 0,1
|
|
```
|
|
|
|
Erwartet werden die fuenf `BizTalk ...` Services mit plausiblen Daten. Insbesondere `BizTalk Platform` darf nicht wegen eines WMI- oder Berechtigungsfehlers `UNKNOWN` sein.
|
|
|
|
### Vorgehen bei Berechtigungsfehlern
|
|
|
|
1. Pruefen, unter welchem Computerkonto der BizTalk-Server im Netzwerk auftritt, normalerweise `DOMAIN\BIZTALKSERVER$`.
|
|
2. Die fuer die BizTalk-Gruppe konfigurierte Windows-Gruppe `BizTalk Server Operators` ermitteln. Der tatsaechliche Gruppenname kann bei der BizTalk-Konfiguration angepasst worden sein.
|
|
3. Das Computerkonto des BizTalk-Servers in diese Operator-Gruppe aufnehmen.
|
|
4. Kerberos-Tickets des Systemkontos erneuern oder den BizTalk-Server in einem Wartungsfenster neu starten.
|
|
5. Den Test mit `cmk-agent-ctl.exe dump` wiederholen.
|
|
6. Nur wenn konkrete WMI-Klassen weiterhin abgelehnt werden, gemeinsam mit BizTalk- und SQL-Administration pruefen, ob diese Abfrage `BizTalk Server Administrators` benoetigt.
|
|
|
|
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.
|
|
|
|
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. |
|
|
| Nur SQL-gestuetzte BizTalk-Klassen liefern `Access denied` oder `UNKNOWN` | Computerkonto `DOMAIN\BIZTALKSERVER$` zunaechst in `BizTalk Server Operators` 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 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.
|
|
|
|
## 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 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 WMI Namespace Security: https://learn.microsoft.com/en-us/windows/win32/wmisdk/access-to-wmi-namespaces
|