johannes/biztalk-checkmk-pulse

Fork 0

Files

T

admin 0f8e8034e6 Harden RTM endpoint adapter handling

2026-08-11 13:56:30 +02:00

31 KiB

Raw Blame History

Technische Dokumentation: BizTalk Checkmk Pulse

1. Ziel und Randbedingungen

Die Anwendung überwacht BizTalk Server 2020 auf Windows Server 2019 mit Checkmk 2.4. Pro Umgebung (ACC, DEV, TST, PRD) wird lokal auf dem BizTalk-Server gesammelt. Das Checkmk-MSSQL-Plugin bleibt für die allgemeine SQL-Überwachung zuständig; BizTalk Checkmk Pulse liefert die BizTalk-spezifische Laufzeit- und Berechtigungssicht.

Verbindliche Randbedingungen:

Der Checkmk Windows Agent bleibt LocalSystem.
LocalSystem erhält keine BizTalk-/SQL-Gruppenmitgliedschaft.
Ein normales dediziertes AD-Servicekonto sammelt minütlich.
Der Agentpfad führt niemals WMI- oder SQL-Abfragen aus.
Fehler müssen als gültige Checkmk-UNKNOWN-Services sichtbar werden.
Schreiben und Lesen dürfen nie einen halben Snapshot exponieren.
Installation und Laufzeit benötigen keine PowerShell und keine BizTalk-DLL-Referenz.
Installation, ACL und Scheduled Task müssen reproduzierbar sein.

2. Auslöser der Architekturänderung

Der ACC-Agent-Dump vom 29.07.2026 bewies:

Lokaler Prozess: NT AUTHORITY\SYSTEM
Netzwerkprincipal: BEW\AV23AGPWBIO1$
Providerfehler: COMException 0x80131904
Innerer Fehler: Login failed for user 'BEW\AV23AGPWBIO1$'

Lokales root\MicrosoftBizTalkServer war erreichbar. Die datenbankgestützten BizTalk-WMI-Klassen scheiterten erst beim Zugriff des Providers auf den getrennten SQL Server. DCOM-, Firewall- oder pauschale WMI-ACL-Änderungen beheben diesen Befund nicht.

Eine Berechtigung des Maschinenkontos hätte die Netzwerkrolle allen LocalSystem-Diensten des BizTalk-Servers vermittelt. Die jetzt implementierte Producer/Consumer-Trennung beschränkt sie stattdessen auf ein dediziertes Konto.

3. Architektur

                       Privilegierte Zone
┌──────────────────────────────────────────────────────────────┐
│ Task Scheduler: "BizTalk Checkmk Pulse Provider"             │
│ Konto: DOMAIN\svc_biztalk_cmk (RunLevel Limited)             │
│ Intervall: 1 Minute, IgnoreNew, Laufzeitlimit 5 Minuten       │
│                                                              │
│ BizTalkCheckmkPulse.exe --collect                             │
│   ├─ WMI root\MicrosoftBizTalkServer                         │
│   ├─ integrierter SQL-Test an MgmtDb/MsgBoxDb                │
│   ├─ lokales Windows Application Event Log                   │
│   ├─ Checkmk-Formatierung                                    │
│   └─ atomare Snapshot-Publikation + Provider-Log             │
└──────────────────────────────┬───────────────────────────────┘
                               │ Datei/ACL
                               v
 %ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot
                               │
                               v
┌──────────────────────────────────────────────────────────────┐
│ Unprivilegierter Transportpfad                               │
│ Checkmk-Agent (LocalSystem)                                  │
│   └─ local\biztalk_checkmk_pulse.cmd                         │
│       └─ BizTalkCheckmkPulse.exe --consume                   │
│           ├─ Format/Alter/Maschine/SHA-256 validieren        │
│           └─ Payload unverändert nach STDOUT                 │
└──────────────────────────────────────────────────────────────┘

Eine gemeinsame EXE implementiert beide Modi. Das reduziert Versionsabweichungen. Die zentrale Config unter %ProgramFiles% gilt für Provider und Consumer.

3.1 Provider-Modus

Aufruf:

"%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --collect

Ablauf:

Config laden und absolute Runtimepfade validieren.
Tageslogs gemäß LogRetentionDays bereinigen.
exklusives Handle auf <SnapshotPath>.provider.lock halten.
WMI-, SQL- und Event-Log-Probes ausführen.
neun stabile und optionale dynamische Checkmk-Zeilen formatieren.
Snapshot in einer eindeutigen Temporärdatei desselben Verzeichnisses schreiben.
Flush(true) ausführen und Temporärdatei atomar publizieren.
Laufzeit, Zeilen- und Diagnosezahl loggen.

Exitcodes:

Code	Bedeutung
`0`	Sammlung und Snapshot-Publikation erfolgreich.
`1`	unerwarteter Providerfehler; aktueller `UNKNOWN`-Snapshot wird versucht.
`2`	Parallelstart oder Snapshot-I/O-Fehler.

Fachliche WMI-/SQL-Fehler werden strukturiert in den Snapshot geschrieben und müssen nicht zwingend einen Prozessfehler verursachen. So bleibt die genaue Fehlerkategorie in Checkmk sichtbar.

3.2 Consumer-Modus

Aufruf:

"%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume

Ohne Modusargument ist --consume der sichere Default. Der Checkmk-Wrapper setzt es trotzdem explizit.

Der Consumer:

öffnet nur den Snapshot,
begrenzt die Dateigröße vor dem Einlesen,
validiert striktes UTF-8,
validiert Formatversion und Header,
fordert die lokale Maschinenkennung,
berechnet SHA-256 über den exakten Payload,
prüft Zeilenanzahl und Checkmk-Zeilenform,
verwirft Zeitstempel mehr als fünf Minuten in der Zukunft,
verwirft Snapshots nach SnapshotMaxAgeSeconds,
gibt bei Erfolg ausschließlich den validierten Payload aus.

Er gibt immer Exitcode 0 zurück, damit ein Fehler die komplette Checkmk-Agentsektion nicht zerstört. Jede Ablehnung erzeugt neun UNKNOWN-Zeilen und einen Eintrag im Consumer-Log.

4. Snapshot-Vertrag

Version 2:

BIZTALK_CHECKMK_PULSE_SNAPSHOT_V2
generatedUtc=2026-07-30T12:34:56.1234567Z
machineBase64=QVYyM0FHUFdCSU8x
identityBase64=QkVXXHN2Y19iaXp0YWxrX2NtayQ=
payloadLines=9
payloadSha256=<64 hex characters>

0 "BizTalk Platform" - ...
...

Maschine und Identität sind Base64-kodiert, um Zeilenumbrüche und Trennzeichen im Header auszuschließen. Base64 ist hier keine Verschlüsselung. Die SHA-256-Prüfung schützt vor unbemerkter Teil-/Fehlschreibung, nicht vor einem lokalen Administrator.

4.1 Atomare Publikation

Die Temporärdatei liegt zwingend im Snapshotverzeichnis. Dadurch findet der Ersatz auf demselben Volume statt. Existiert bereits ein Snapshot, wird File.Replace verwendet; beim ersten Lauf File.Move. Bis zum erfolgreichen Ersatz bleibt der letzte vollständige Snapshot erhalten. Seine Altersprüfung verhindert unbegrenztes Weiterreichen alter Daten.

4.2 Keine direkte Checkmk-Spooldatei

Checkmk kann zwar Dateien aus seinem Spoolverzeichnis direkt anhängen, prüft deren Inhalt aber laut eigener Dokumentation nicht. Ein fehlerhafter Spool kann nachfolgende Agentsektionen beeinflussen. Deshalb liegt der Provider-Snapshot in einem eigenen Verzeichnis und wird erst durch den validierenden Consumer in die Local-Check-Ausgabe übernommen.

5. Datenquellen

5.1 BizTalk WMI

Namespace:

root\MicrosoftBizTalkServer

Pflichtklassen:

Klasse	Zweck
`MSBTS_GroupSetting`	Gruppe, Read-Only-/Operator-Gruppe, Management- und Master-MessageBox-Ziel.
`MSBTS_HostInstance`	lokale Host-Instance-Zustände.
`MSBTS_ServiceInstance`	suspendierte Instanzen.
`MSBTS_ReceiveLocation`	Receive-Location-Zustände.
`MSBTS_SendPort`	Send-Port-Zustände.
`MSBTS_Orchestration`	Orchestration-Zustände.

MSBTS_GroupSetting wird mit den dokumentierten Properties MgmtDbServerName, MgmtDbName, SubscriptionDBServerName, SubscriptionDBName, BizTalkReadOnlyUserGroup und BizTalkOperatorGroup gelesen. Eine nicht dokumentierte MSBTS_MessageBoxSetting-Klasse wird nicht abgefragt.

Hostnamen werden clientseitig verglichen. Sonderzeichen und FQDN-/Kurzname gelangen nicht in dynamisch erzeugte WQL-Filter.

MSBTS_ServiceInstance wird für ServiceStatus=4 (resumable), ServiceStatus=32 (non-resumable) und ServiceClass=64 abgefragt. ServiceClass=64 kennzeichnet Routing Failure Reports. Sie werden als eigene Metrik ausgewiesen und zugleich in suspended_nonresumable mitgezählt.

5.2 Kompaktes Checkmk-Servicebild

Die alte Sammelzeile BizTalk Runtime Artifacts wurde durch drei kurze Services ersetzt. Insgesamt entstehen neun stabile Services:

BizTalk Platform
BizTalk SQL Access
BizTalk Suspended Instances
BizTalk Host Instances
BizTalk Receive Locations
BizTalk Send Ports
BizTalk Endpoint Reachability
BizTalk Orchestrations
BizTalk Event Log

Receive Locations und Send Ports alarmieren nur für unerwartete Aus-Zustände. Fachlich bewusst deaktivierte Namen werden exakt, ohne Wildcards, in ExpectedDisabledReceiveLocations beziehungsweise ExpectedInactiveSendPorts hinterlegt. Ein Eintrag ist entweder nur der Name oder Anwendung\Name.

Pro Summary werden maximal MaxSummaryItems Treffer angezeigt. Weitere Artefakte werden als (+n more) zusammengefasst. MaxDetailCharacters begrenzt jede Detailausgabe, damit Checkmk-Ansichten kompakt bleiben, während alle numerischen Metriken vollständig erhalten bleiben.

5.3 Endpoint-Discovery und Netzwerkprobe

Die Endpoint-Funktion erweitert keine WMI-Klassenmenge. Aus den ohnehin minütlich abgefragten Instanzen werden nur dokumentierte Properties gelesen:

WMI-Klasse	Properties
`MSBTS_SendPort`	`Status`, `IsDynamic`, `PTAddress`, `STAddress`, `PTTransportType`, `STTransportType`
`MSBTS_ReceiveLocation`	`IsDisabled`, `InboundTransportURL`, `AdapterName`

Nur Status=Started beziehungsweise IsDisabled=false wird geprüft. Inaktive Artefakte bleiben aus der Probe ausgeschlossen, auch wenn sie noch im Katalog stehen. Dynamische Send Ports, lokale Dateipfade, SMTP-Empfängerlisten und Named Pipes sowie relative HTTP-/WCF-Receive-Listener werden als erwartbar nicht socket-prüfbar behandelt und erzeugen kein UNKNOWN. WCF-SQL-Adressen im Format mssql://server[:port]/instanz/datenbank werden auf TCP 1433 oder den expliziten Port reduziert. Schemafreie host:port-Angaben werden vor der allgemeinen URI-Auswertung erkannt. Bei FTP und SFTP werden zusätzlich Angaben der Form [benutzer@]host[:port]/pfad auf Host und expliziten beziehungsweise adaptertypischen Standardport reduziert. Echte Auflösungslücken bleiben sichtbar und nennen Artefakt, Adapter und Grund, aber niemals die vollständige URI.

Der lokale Katalog %ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml wird beim ersten erfolgreichen Lauf erzeugt und danach standardmäßig alle 168 Stunden atomar abgeglichen. Er enthält keine vollständigen URIs, Querystrings, Benutzernamen oder Kennwörter, sondern nur Artefaktbezug, Adapter, Host, Port und TCP/UDP. Automatisch erzeugte Einträge tragen autoDiscovered="true". Ein bewusst manueller Override wird mit autoDiscovered="false" markiert und beim Wochenabgleich erhalten; sein key muss dem Artefakteintrag entsprechen. Eigenständige manuelle Ziele verwenden artifactType="Manual".

HTTP(S), SFTP, FTP, UNC/SMB, WCF und net.tcp werden ausschließlich per TCP-Connect geprüft. Es findet kein fachlicher Request und keine Anmeldung statt. Explizite udp://host:port-Einträge senden ein einzelnes Datagramm; das bestätigt DNS, Route und lokalen Versand, kann ohne applikationsspezifisches Antwortprotokoll aber keinen entfernten Dienstzustand beweisen. Gemeinsame Host/Port-Ziele werden dedupliziert und mit begrenzter Parallelität getestet.

Der Checkmk-Service nennt im OK-Fall nur die Gesamtzahl. Bei Ausfällen werden ausschließlich die nicht erreichbaren Artefakte in unavailable= angezeigt; MaxSummaryItems und MaxDetailCharacters begrenzen die Darstellung. Alle Einzelfehler bleiben vollständig im Provider-Log.

5.4 SQL-Zugriffsprobe

Der Provider öffnet für Management- und Master-MessageBox-Datenbank eine kurze System.Data.SqlClient-Verbindung mit integrierter Windows-Authentifizierung, führt SELECT 1 aus und schließt sie. Keine BizTalk-Tabelle wird direkt gelesen oder verändert.

Die Ausgabe execution_identity= zeigt deshalb das Provider-Konto, nicht mehr NT AUTHORITY\SYSTEM. Der Check beweist, dass genau das Scheduled-Task-Konto die Ziele erreichen kann.

5.5 Event Log

Der Provider liest das lokale Application Log im konfigurierten Zeitfenster und filtert Quellen wie BizTalk Server, XLANG/s, ENTSSO, BizTalk Server Application und BizTalk Server EDI.

6. Berechtigungsmodell

6.1 Bevorzugte BizTalk-Rolle

BizTalk Server 2020 führte die BizTalk Server Read Only Users-Gruppe ein. Sie darf Artefakte, Servicezustand, Message Flow und Trackinginformationen lesen, aber keine administrativen Operationen ausführen. SQL-seitig wird sie über BTS_READONLY_USERS vermittelt.

Soll:

DOMAIN\svc_biztalk_cmk$
  -> konfigurierte BizTalk Server Read Only Users-Domaingruppe
  -> vorhandener Windows-Gruppenlogin am SQL Server
  -> BTS_READONLY_USERS in den von BizTalk konfigurierten Datenbanken

Die genaue Gruppe ist aus MSBTS_GroupSetting.BizTalkReadOnlyUserGroup beziehungsweise der BizTalk-Administration zu lesen. Nicht vom Standardnamen ausgehen.

Die Operator-Gruppe (BTS_OPERATORS) wird erst geprüft, wenn eine konkret benannte erforderliche WMI-Klasse trotz nachgewiesener Read-Only-Konfiguration und neuem Anmeldetoken abgewiesen wird. Die Erweiterung muss mit Security, BizTalk- und SQL-Administration begründet werden.

Unzulässig:

Checkmk-Dienstkonto ändern,
Maschinenkonto pauschal berechtigen,
individueller SQL-Login für das Provider-Konto,
direkte ad-hoc DB-Rollen,
db_owner oder sysadmin,
WMI-/DCOM-Vollzugriff als Reaktion auf einen SQL-Loginfehler.

6.2 Dateisystem-ACL

Der Installer entfernt die Vererbung an den Runtimeverzeichnissen und setzt explizite Einträge mit sprachneutralen Well-known-SIDs:

Ziel	Collector	SYSTEM	lokale Administratoren
Runtime-Root	RX	RX	F
`data`	Modify	RX	F
`logs`	Modify	Modify	F

LocalSystem kann deshalb den Snapshot lesen, aber im Datenverzeichnis nicht schreiben. Schreibrecht im Logverzeichnis wird benötigt, um abgelehnte Snapshots aus dem Consumer-Kontext zu protokollieren.

7. Scheduled Task

Name:

BizTalk Checkmk Pulse Provider

Sollkonfiguration:

Einstellung	Wert
Trigger	einmalig, Wiederholung jede Minute ohne Enddatum
Programm	`%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe`
Argument	`--collect`
Arbeitsverzeichnis	`%ProgramFiles%\BizTalkCheckmkPulse`
Benutzer	normales dediziertes AD-Servicekonto
Run level	`Limited`; keine lokale Administratorrolle erforderlich
Mehrfachinstanzen	`IgnoreNew`
Laufzeitlimit	5 Minuten
StartWhenAvailable	aktiv
Restart	zweimal im Minutenabstand

Der Task wird mit gespeichertem Dienstkontokennwort ausgeführt, also unabhängig von einer interaktiven Anmeldung. Bei Kennwortwechsel oder -ablauf muss das Task-Kennwort aktualisiert werden. Ein gMSA ist weiterhin optional unterstützt, aber nicht die produktive Standardannahme.

8. Installation

8.1 Build

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

Der Release-Build der Visual-Studio-2019-Solution baut Anwendung, grafischen Installer und Packaging-Werkzeug. Danach liegen der Paketordner artifacts\BizTalkCheckmkPulse-Setup und das direkt transportierbare artifacts\BizTalkCheckmkPulse-Setup.zip bereit.

8.2 Normales Servicekonto

Das ZIP wird auf dem Zielserver vollständig entpackt. Danach Setup.exe als Administrator starten, Konto im Format DOMAIN\Benutzer (zum Beispiel BEW\t231bizmon), Kennwort und Umgebung eintragen und die Installation starten.

Der Installer muss als lokaler Administrator laufen. Er vergibt keine AD-/BizTalk-/SQL-Rechte; diese bleiben getrennte administrative Freigaben.

Beim Update wird zuerst die neue Paketversion im Staging-Verzeichnis mit neun Self-Test-Zeilen validiert. Bestehende AppSettings werden in die neue Config übernommen; neue Keys stammen aus der neuen Standardkonfiguration. Die Runtime-Daten unter %ProgramData% bleiben bestehen. Erst danach wird der Task gestoppt und die Programmversion umgeschaltet. Scheitert ein Folgeschritt, versucht der Installer Programmverzeichnis, Checkmk-Wrapper und Scheduled Task auf den vorherigen Stand zurückzusetzen.

Ab Version 2.2.4 ist die Umschaltung erst nach einer transaktionalen Runtime-Abnahme abgeschlossen. Ein einmaliger, triggerloser Task läuft unter dem echten Collector-Konto und erzwingt einen vollständigen Endpoint- Katalogabgleich. Der Installer wartet begrenzt auf LastTaskResult=0 und lässt anschließend die installierte Produkt-EXE Snapshot und Katalog mit den normalen Produktparsern validieren. Der Snapshot muss aus diesem Lauf stammen, die erwartete Identität und alle neun eindeutigen Services enthalten. Erst dann wird der normale Minutentask registriert und das Backup gelöscht. Bei Fehler oder Timeout wird die alte Version wiederhergestellt und ein frischer Lauf des alten Tasks abgewartet.

Version 2.2.5 korrigiert die versionsübergreifende Vorprüfung. Die neue Paket-, Staging- und Zielversion muss weiterhin exakt neun gültige Self-Test-Zeilen liefern. Für die installierte Ausgangsversion wird dagegen deren vollständiger, eindeutiger und ausschließlich grüner Servicevertrag akzeptiert, auch wenn er aus einer älteren Version mit acht Services stammt. Rein additive Services blockieren das Update nicht; entfernte Namen und damit auch Renames bleiben vor der Umschaltung bestätigungspflichtig.

Parallel erzeugt jeder Installations-/Updatelauf ein separates %ProgramData%\BizTalkCheckmkPulse\logs\setup-*.log. Protokolliert werden Phase, Setup-/Binary-Version, Pfad und Größe, Self-Test-stdout/-stderr, Exitcodes, Taskstatus, Exception-Kette, letzte Provider-Logzeilen bei einem Abnahmefehler und das Rollback-Ergebnis. Das Collector-Kennwort wird der Logging-Komponente nie übergeben. Ein frisch abgeschlossener Task mit Fehlercode wird sofort erkannt; der Fehler erscheint dezimal und hexadezimal.

Version 2.2.6 behandelt einen fachlichen UNKNOWN-Zustand der Endpoint-Prüfung nicht mehr als Installationsdefekt. Sind Providerlauf, Snapshot, Identität, neun Services und der erzwungen aktualisierte Katalog technisch valide, darf BizTalk Endpoint Reachability als einziger Service UNKNOWN bleiben. Die vollständige Local-Check-Zeile wird als Abnahmewarnung ausgegeben und bleibt unverändert für Checkmk erhalten. Damit wird eine unvollständige Endpoint-Auflösung nicht grüngefärbt und zugleich kein funktionsfähiges Update zurückgerollt. UNKNOWN in Platform, SQL Access, Suspensions, Host Instances, Receive Locations, Send Ports, Orchestrations oder Event Log bleibt blockierend, weil dort die Kern-Datenerhebung nicht zuverlässig belegt ist.

Version 2.2.7 klassifiziert die im RTM-Abnahmelauf identifizierten Adapter präziser. Scheduling-Komponenten sind keine Netzwerkziele und werden komplett ausgenommen. Database://host[:port]/.../Oracle wird per TCP auf den expliziten Port oder den Oracle-Standard 1521 geprüft. WCF-SAP verwendet den ersten SAProuter-Hop oder das Paar ListenerGwHost/ListenerGwServ; dabei entspricht sapgwNN dem TCP-Port 33NN. Diese beiden Adapterklassen laufen als Best-Effort-Diagnose: Ein Fehlschlag bleibt über Metriken sichtbar, erzeugt aber keinen Alarm. Alle regulären und manuellen Ziele behalten ihre bisherige strenge Statuslogik.

Der installierte Task selbst läuft mit RunLevel Limited. Der Installer übergibt das Kennwort direkt an die Windows-Task-Scheduler-COM-Schnittstelle; es wird weder in einer Prozesskommandozeile noch in Config oder Log geschrieben. Das Konto benötigt Log on as a batch job.

8.3 Optionales gMSA

Im Installer die gMSA-Checkbox aktivieren und ein auf $ endendes Konto wie BEW\svc_biztalk_cmk$ eingeben. Ein Kennwort wird dann nicht abgefragt.

8.4 Checkmk

Der installierte Wrapper liegt unter:

%ProgramData%\checkmk\agent\local\biztalk_checkmk_pulse.cmd

Der Agent darf den Consumer synchron ausführen. Er liest nur maximal 1 MiB lokale Daten; ein Checkmk-Async-Cache ist daher nicht notwendig. Falls alte check_mk.user.yml-Regeln für den bisherigen 300-Sekunden-Cache existieren, sollten sie entfernt werden, damit Checkmk den minütlich aktualisierten Snapshot nicht zusätzlich verzögert.

Nach dem Agent-Dump:

Service Discovery für den BizTalk-Host ausführen.
neun stabile Services aufnehmen; den alten Service BizTalk Runtime Artifacts nach erfolgreicher Discovery entfernen.
Changes aktivieren.
Views/Benachrichtigungen nach Umgebung konfigurieren.

9. Logging

Pfad:

%ProgramData%\BizTalkCheckmkPulse\logs\
  biztalk-checkmk-pulse-YYYYMMDD.log

Jede Zeile enthält UTC-Zeit, Level, Komponente, PID, Windows-Identität und einzeilige Nachricht. Provider-Erfolge werden pro Lauf geloggt; der Consumer loggt nur abgelehnte Snapshots. Exceptions werden mit Typ, Nachricht, HRESULT-/Providerdetails und Stacktrace einzeilig gespeichert.

Der erfolgreiche Abschluss nennt Suspensions, Routing Failure Reports, Receive-Location-/Send-Port-Zahlen und Laufzeit. Jede strukturierte WMI-/SQL-/Event-Log-Diagnose wird zusätzlich als eigene WARN-Zeile protokolliert und bleibt damit auch außerhalb der gekürzten Checkmk-Summary vollständig nachvollziehbar.

Logging ist best effort: Ein blockiertes Log darf Checkmk-Ausgabe oder Snapshot-Publikation nicht zerstören. Der Provider entfernt beim Start Dateien älter als LogRetentionDays.

10. Diagnose und Runbook

10.1 Grundprüfung

schtasks.exe /query /tn "BizTalk Checkmk Pulse Provider" /v /fo list
dir "%ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot"
type "%ProgramData%\BizTalkCheckmkPulse\logs\biztalk-checkmk-pulse-*.log"
"%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
"C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump

10.2 Kein Snapshot

Prüfen:

Task existiert und ist aktiviert.
LastTaskResult und Provider-Log.
Dienstkonto kann sich als Batch anmelden.
gespeichertes Task-Kennwort ist nach Rotation/Ablauf noch gültig.
Provider besitzt Modify auf data und logs.
EXE/Config sind ausführbar.

10.3 Staler Snapshot

Der Consumer nennt Alter und Grenzwert. Ursachen:

Task deaktiviert oder Konto/Kennwort ungültig,
vorheriger Lauf hängt,
WMI-/SQL-Timeouts,
Task Scheduler lief während Wartung nicht,
Snapshot-Publikation wird durch AV/EDR oder ACL blockiert.

Nicht einfach SnapshotMaxAgeSeconds stark erhöhen. Zuerst den minütlichen Lauf wiederherstellen. Bei geplanten Wartungen darf Checkmk bewusst UNKNOWN anzeigen.

10.4 SHA-256-/Formatfehler

Snapshot nicht reparieren oder direkt an Checkmk kopieren. Task neu starten, Datenträger und AV/EDR prüfen. Wiederholt sich der Fehler, Temporärdateien, NTFS-Ereignisse und Schreibrechte untersuchen.

10.5 BizTalk-/SQL-Permission

Log zeigt execution_identity des Providers.
BizTalkReadOnlyUserGroup gegen BizTalk-Konfiguration abgleichen.
AD-Gruppenmitgliedschaft des Provider-Kontos prüfen.
neuen Logontoken durch neuen Tasklauf sicherstellen.
SQL-seitig Gruppenlogin und BTS_READONLY_USERS read-only prüfen.
keine Einzelrechte erteilen.
Nur wenn eine spezifische Klasse weiter abgewiesen wird, Read-Only-Umfang mit Microsoft-Dokumentation und BizTalk-Betrieb abgleichen; Operator-Rolle ist eine bewusste Eskalation.

10.6 WMI-Schema

InvalidClass oder InvalidQuery wird als Wmi/Schema klassifiziert. Berechtigungserhöhung kann eine nicht vorhandene Klasse nicht erzeugen. Installierte BizTalk-Version, WQL und Properties prüfen.

11. Konfiguration

Alle AppSettings befinden sich in:

%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe.config

Runtime:

Key	Default	Bereich
`SnapshotPath`	`%ProgramData%\BizTalkCheckmkPulse\data\...`	absolut
`SnapshotMaxAgeSeconds`	`180`	60 bis 86400
`SnapshotMaxBytes`	`1048576`	4096 bis 16777216
`LogDirectory`	`%ProgramData%\BizTalkCheckmkPulse\logs`	absolut
`LogRetentionDays`	`30`	1 bis 365
`EndpointCatalogPath`	`%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml`	absolut
`EndpointCatalogMaxBytes`	`1048576`	4096 bis 16777216

BizTalk-Probes:

Key	Default
`Server`	`.`
`EnvironmentName`	leer
`IncludeEnvironmentInServiceName`	`false`
`QueryTimeoutSeconds`	`25`
`ProbeSqlConnectivity`	`true`
`SqlConnectionTimeoutSeconds`	`5`
`ProbeEventLog`	`true`
`EventLogLookbackMinutes`	`60`
`ProbeEndpointConnectivity`	`true`
`EndpointDiscoveryIntervalHours`	`168`
`EndpointProbeTimeoutMilliseconds`	`3000`
`EndpointProbeMaxConcurrency`	`16`
`EndpointCatalogMaxEntries`	`1000`
`EndpointMaxCount`	`100` eindeutige Netzwerkziele

Alarmierung:

Key	Default
`WarnResumableThreshold`	`1`
`CritNonResumableThreshold`	`1`
`CritRoutingFailureThreshold`	`1`
`AlertOnArtifactRuntimeIssues`	`true`
`ExpectedDisabledReceiveLocations`	leer; exakte Pipe-Liste
`ExpectedInactiveSendPorts`	leer; exakte Pipe-Liste
`AlertOnInactiveOrchestrations`	`false`
`MaxSummaryItems`	`5`
`MaxDetailCharacters`	`1600`
`EmitPerApplicationSuspensionServices`	`false`
`EventLogWarnThreshold`	`1`
`EventLogCritThreshold`	`10`

12. Tests und Abnahmekriterien

Automatisiert:

Release-Build .NET Framework 4.7.2,
exakt neun Self-Test-Services,
unbekannte Quellen werden UNKNOWN,
dynamische Anwendungsservices nur bei bekannter Anwendung,
WMI-Queryvertrag nutzt dokumentierte Properties,
eingebetteter SQL-Loginfehler wird Permission,
abgewiesener Principal wird extrahiert,
Routing Failure Reports werden separat und als non-resumable gezählt,
Receive-/Send-Allowlisten trennen bewusste von unerwarteten Aus-Zuständen,
ein fehlender IsDisabled-Wert wird UNKNOWN statt still als enabled,
betroffene Namen und Gesamtlänge der Summary bleiben begrenzt,
Endpoint-Adressen werden ohne URI-Secrets auf Host/Port reduziert,
manuelle Endpoint-Overrides überleben den automatischen Wochenabgleich,
nur nicht erreichbare oder wirklich unaufgelöste Endpoints erscheinen im Checkmk-Detail,
70 vollständig timeoutende eindeutige Ziele bleiben mit den Defaults in einem theoretischen Socket-Budget von etwa 15 Sekunden; das konfigurierte Maximum von 100 Zielen in etwa 21 Sekunden,
Update-Config-Merge erhält bestehende Werte und fügt neue Defaults hinzu,
erzwungener Installations-Katalogabgleich wird unabhängig vom Katalogalter ausgeführt,
Runtime-Abnahme weist alten/manipulierten Snapshot, falsche Identität, fehlenden Service, Kernservice-UNKNOWN, alten/ungültigen Katalog und fehlerhaften oder nicht rechtzeitig beendeten Tasklauf zurück; ein isoliertes Endpoint-Reachability-UNKNOWN wird mit vollständigem Detail akzeptiert,
Snapshot-Roundtrip und Ersatz,
SHA-256-Manipulation wird verworfen,
Stale-Snapshot wird verworfen,
Consumer-Fallback enthält neun UNKNOWN-Services.

Windows-/ACC-Abnahme:

LastTaskResult=0.
Snapshot wird mindestens dreimal minütlich aktualisiert.
Provider-Log nennt das dedizierte Konto.
BizTalk Platform zeigt read_only_group=.
BizTalk SQL Access: targets=2, available=2.
keine Permission-UNKNOWNs.
Suspensionsmetriken mit der BizTalk Group Hub Page plausibilisieren, einschließlich Routing Failure Reports.
Eine bewusst deaktivierte Receive Location und einen inaktiven Send Port über die exakten Allowlisten als expected bestätigen.
Einen Testnamen aus der Allowlist entfernen und den erwarteten CRIT mit kurzem affected=-Detail prüfen.
ACL-Test: LocalSystem kann Snapshot lesen, nicht schreiben.
endpoints.xml wurde erzeugt; sie enthält keine vollständigen URIs oder Zugangsdaten und nur Started-/Enabled-Artefakte.
Endpoint Reachability zeigt unresolved=0; erwartbar lokale oder adapterinterne Adressen stehen nur unter expected_non_socket und bleiben OK.
Einen erreichbaren Testport sperren: nur Endpoint Reachability wird CRIT und nennt ausschließlich das nicht erreichbare Ziel.
Ein Artefakt stoppen/deaktivieren: es wird im nächsten Minutenlauf nicht mehr geprüft.
Katalogzeit auf älter als 168 Stunden setzen beziehungsweise Intervall testweise reduzieren: erfolgreicher atomarer Umgebungsabgleich.
Task deaktivieren: nach 180 Sekunden neun stale-UNKNOWNs.
Task wieder aktivieren: nächster Snapshot stellt Echtzustand her.
Agent-Dump und Checkmk Service Discovery erfolgreich.

Erst nach ACC-Abnahme erfolgt der gestufte Rollout nach DEV/TST/PRD.

13. Deinstallation und Rollback

Setup.exe aus dem entpackten Paket erneut starten und Deinstallieren wählen. Der Installer entfernt Task, Wrapper und Programmdateien, behält Logs und Snapshot aber absichtlich bei. Die AD-Gruppenmitgliedschaft wird nicht geändert und separat nach Change-Verfahren entzogen.

Rollback auf die alte direkte LocalSystem-Architektur ist nicht empfohlen. Falls kurzfristig notwendig, muss Security die Maschinenkonto-Berechtigung explizit freigeben; der Checkmk-Agentdienst selbst darf nicht auf das Collector-Konto umgestellt werden.

31 KiB Raw Blame History