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

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

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.

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:

scripts\build-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

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 den per WMI ermittelten Management- und MessageBox-Datenbanken.
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.

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|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 oder Provider klassifiziert.
  • BizTalk SQL Access oeffnet mit integrierter Windows-Authentifizierung eine Verbindung zur ermittelten Management- und MessageBox-Datenbank und fuehrt SELECT 1 aus.
  • Die Service-Ausgabe nennt Ausfuehrungsidentitaet, erwartete Netzwerkidentitaet, betroffene Komponente, technische Ursache und konkrete Massnahme.
  • 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.

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