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

13 KiB
Raw Blame History

BizTalk Checkmk Pulse

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:

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

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 die Architektur geaendert wurde

Der ACC-Test vom 29.07.2026 zeigte:

Login failed for user 'BEW\AV23AGPWBIO1$'

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.

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
  • BizTalk Suspended Instances
  • BizTalk Host Instances
  • BizTalk Runtime Artifacts
  • BizTalk Event Log

Mit EnvironmentName=ACC, DEV, TST oder PRD wird die Umgebung in den Servicenamen aufgenommen, zum Beispiel BizTalk ACC Platform.

Statuslogik und Metriken: docs/CheckmkServices.md

Beispielausgaben: docs/ExampleOutput.md

Voraussetzungen

Build-Host:

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

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

scripts\build-release.cmd
scripts\test-release.cmd
scripts\package-release.cmd

Das Paket wird unter artifacts\BizTalkCheckmkPulse-deploy erzeugt:

BizTalkCheckmkPulse-deploy\
  Install-BizTalkCheckmkPulse.ps1
  Uninstall-BizTalkCheckmkPulse.ps1
  biztalk_checkmk_pulse.cmd
  application\
    BizTalkCheckmkPulse.exe
    BizTalkCheckmkPulse.exe.config

Format-Self-Test ohne WMI, SQL oder Event Log:

artifacts\BizTalkCheckmkPulse-deploy\application\BizTalkCheckmkPulse.exe --self-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.

Berechtigung vorbereiten

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:

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:

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

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:

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:

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:

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:

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

%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

ACL-Soll:

Pfad Provider LocalSystem Administratoren
Programm Lesen/Ausfuehren Lesen/Ausfuehren Vollzugriff
data Aendern Lesen/Ausfuehren Vollzugriff
logs Aendern Aendern Vollzugriff

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

Datei:

%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config

Wichtige Werte:

Key Default Bedeutung
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.

Nach einer Config-Aenderung den Scheduled Task manuell starten. Der Consumer liest den naechsten atomar publizierten Snapshot.

Fehlerbilder

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.

Ausfuehrliche Betriebs- und Architekturdetails stehen in Dokumentation.md.

Deinstallation

.\Uninstall-BizTalkCheckmkPulse.ps1

Das Skript fragt vor dem Entfernen. Mit -KeepRuntimeData bleiben Snapshot und Logs erhalten:

.\Uninstall-BizTalkCheckmkPulse.ps1 -KeepRuntimeData

Die AD-Gruppenmitgliedschaft des Provider-Kontos wird bewusst nicht automatisch geaendert und muss separat durch AD-/BizTalk-Administration entfernt werden.

Certutil-Transport

Zu jeder Uebergabe wird ein Source-ZIP und eine certutil-kompatible Base64-Textdatei erzeugt. Auf Windows:

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

Die konkrete Datei und SHA-256-Summe werden bei der Uebergabe genannt.

Quellen

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

Reference in New Issue View Git Blame Copy Permalink