biztalk-checkmk-pulse/Dokumentation.md

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

```text
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

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

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

Ablauf:

1. Config laden und absolute Runtimepfade validieren.
2. Tageslogs gemäß `LogRetentionDays` bereinigen.
3. exklusives Handle auf `<SnapshotPath>.provider.lock` halten.
4. WMI-, SQL- und Event-Log-Probes ausführen.
5. neun stabile und optionale dynamische Checkmk-Zeilen formatieren.
6. Snapshot in einer eindeutigen Temporärdatei desselben Verzeichnisses
   schreiben.
7. `Flush(true)` ausführen und Temporärdatei atomar publizieren.
8. 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:

```cmd
"%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:

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

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

1. `BizTalk Platform`
2. `BizTalk SQL Access`
3. `BizTalk Suspended Instances`
4. `BizTalk Host Instances`
5. `BizTalk Receive Locations`
6. `BizTalk Send Ports`
7. `BizTalk Endpoint Reachability`
8. `BizTalk Orchestrations`
9. `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:

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

```text
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

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

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

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

## 9. Logging

Pfad:

```text
%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

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

1. Task existiert und ist aktiviert.
2. `LastTaskResult` und Provider-Log.
3. Dienstkonto kann sich als Batch anmelden.
4. gespeichertes Task-Kennwort ist nach Rotation/Ablauf noch gültig.
5. Provider besitzt Modify auf `data` und `logs`.
6. 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

1. Log zeigt `execution_identity` des Providers.
2. `BizTalkReadOnlyUserGroup` gegen BizTalk-Konfiguration abgleichen.
3. AD-Gruppenmitgliedschaft des Provider-Kontos prüfen.
4. neuen Logontoken durch neuen Tasklauf sicherstellen.
5. SQL-seitig Gruppenlogin und `BTS_READONLY_USERS` read-only prüfen.
6. keine Einzelrechte erteilen.
7. 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:

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

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

## 14. Referenzen

- https://learn.microsoft.com/en-us/biztalk/core/managing-biztalk-server-security
- https://learn.microsoft.com/en-us/biztalk/core/windows-groups-and-user-accounts-in-biztalk-server
- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-biztalkreadonlyusergroup-property-wmi
- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-groupsetting-wmi
- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-serviceinstance-serviceclass-property-wmi
- https://learn.microsoft.com/en-us/biztalk/core/types-of-message-failures
- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-receivelocation-isdisabled-property-wmi
- https://learn.microsoft.com/en-us/biztalk/core/technical-reference/msbts-sendport-status-property-wmi
- https://learn.microsoft.com/en-us/biztalk/adapters-and-accelerators/adapter-sql/create-the-sql-server-connection-uri
- https://learn.microsoft.com/en-us/biztalk/adapters-and-accelerators/adapter-oracle-database/create-the-oracle-database-connection-uri
- https://docs.checkmk.com/latest/en/agent_windows.html
- https://docs.checkmk.com/latest/en/localchecks.html
- https://docs.checkmk.com/latest/en/spool_directory.html