johannes/biztalk-checkmk-pulse
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
0001d7b86155d507e6dce51a90fd3d7e72868db3
biztalk-checkmk-pulse/README.md
T

20 KiB
Raw Blame History

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.

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.

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 SQL Access
  • 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. Beispielausgaben stehen in docs/ExampleOutput.md. Die konkrete ACC-Freigabeanleitung steht als Textdatei in docs/ACC-WMI-SQL-Berechtigung.txt.

Build

Voraussetzungen auf einem Windows-Build-Host:

  • Visual Studio 2019/2022 Build Tools oder Visual Studio
  • MSBuild im PATH
  • .NET Framework 4.7.2 Developer Pack

Build:

scripts\build-release.cmd

Build plus dependency-free regression tests:

scripts\test-release.cmd

Deployment-Paket erstellen:

scripts\package-release.cmd

Ergebnis:

artifacts\BizTalkCheckmkPulse-deploy\
  biztalk_checkmk_pulse.cmd
  BizTalkCheckmkPulse\
    BizTalkCheckmkPulse.exe
    BizTalkCheckmkPulse.exe.config

Validierung nach dem Build:

artifacts\BizTalkCheckmkPulse-deploy\biztalk_checkmk_pulse.cmd --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.

Installation auf dem BizTalk-Server

Kopiere den Inhalt von artifacts\BizTalkCheckmkPulse-deploy nach:

%ProgramData%\checkmk\agent\local

Zielstruktur:

%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:

"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd" --self-test
"%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd"

Agent-Ausgabe wie Checkmk sie sieht:

"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:

%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.
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.

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:

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:

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.

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:

& "C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump |
    Select-String -Pattern "BizTalk|Login failed|Access denied|Unauthorized|UNKNOWN" -Context 0,1

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 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:

local:
  enabled: yes
  execution:
    - pattern: $CUSTOM_LOCAL_PATH$\biztalk_checkmk_pulse.cmd
      async: yes
      run: yes
      cache_age: 300

Vorgehen bei Berechtigungsfehlern

  1. Den Agent-Dienst und sein Startkonto kontrollieren:

    Get-CimInstance Win32_Service |
    Where-Object { $_.Name -match 'check|cmk' -or $_.DisplayName -match 'checkmk' } |
    Select-Object Name, DisplayName, State, StartName

  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:

    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:

    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:

    & "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.

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.

Quellen

Reference in New Issue View Git Blame Copy Permalink