biztalk-checkmk-pulse/Dokumentation.md

# Technische Dokumentation: BizTalk Checkmk Pulse

## 1. Ziel und Randbedingungen

Die Anwendung ueberwacht 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 fuer die allgemeine
SQL-Ueberwachung zustaendig; BizTalk Checkmk Pulse liefert die
BizTalk-spezifische Laufzeit- und Berechtigungssicht.

Verbindliche Randbedingungen:

- Der Checkmk Windows Agent bleibt `LocalSystem`.
- `LocalSystem` erhaelt keine BizTalk-/SQL-Gruppenmitgliedschaft.
- Ein normales dediziertes AD-Servicekonto sammelt minuetlich.
- Der Agentpfad fuehrt niemals WMI- oder SQL-Abfragen aus.
- Fehler muessen als gueltige Checkmk-`UNKNOWN`-Services sichtbar werden.
- Schreiben und Lesen duerfen nie einen halben Snapshot exponieren.
- Installation und Laufzeit benoetigen keine PowerShell und keine BizTalk-DLL-Referenz.
- Installation, ACL und Scheduled Task muessen reproduzierbar sein.

## 2. Ausloeser der Architekturanderung

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
datenbankgestuetzten BizTalk-WMI-Klassen scheiterten erst beim Zugriff des
Providers auf den getrennten SQL Server. DCOM-, Firewall- oder pauschale
WMI-ACL-Aenderungen beheben diesen Befund nicht.

Eine Berechtigung des Maschinenkontos haette die Netzwerkrolle allen
`LocalSystem`-Diensten des BizTalk-Servers vermittelt. Die jetzt implementierte
Producer/Consumer-Trennung beschraenkt 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 unveraendert nach STDOUT                │
└──────────────────────────────────────────────────────────────┘
```

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

### 3.1 Provider-Modus

Aufruf:

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

Ablauf:

1. Config laden und absolute Runtimepfade validieren.
2. Tageslogs gemaess `LogRetentionDays` bereinigen.
3. exklusives Handle auf `<SnapshotPath>.provider.lock` halten.
4. WMI-, SQL- und Event-Log-Probes ausfuehren.
5. neun stabile und optionale dynamische Checkmk-Zeilen formatieren.
6. Snapshot in einer eindeutigen Temporaerdatei desselben Verzeichnisses
   schreiben.
7. `Flush(true)` ausfuehren und Temporaerdatei 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
muessen 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:

- oeffnet nur den Snapshot,
- begrenzt die Dateigroesse vor dem Einlesen,
- validiert striktes UTF-8,
- validiert Formatversion und Header,
- fordert die lokale Maschinenkennung,
- berechnet SHA-256 ueber den exakten Payload,
- prueft Zeilenanzahl und Checkmk-Zeilenform,
- verwirft Zeitstempel mehr als fuenf Minuten in der Zukunft,
- verwirft Snapshots nach `SnapshotMaxAgeSeconds`,
- gibt bei Erfolg ausschliesslich den validierten Payload aus.

Er gibt immer Exitcode `0` zurueck, damit ein Fehler die komplette
Checkmk-Agentsektion nicht zerstoert. 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=8
payloadSha256=<64 hex characters>

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

Maschine und Identitaet sind Base64-kodiert, um Zeilenumbrueche und
Trennzeichen im Header auszuschliessen. Base64 ist hier keine Verschluesselung.
Die SHA-256-Pruefung schuetzt vor unbemerkter Teil-/Fehlschreibung, nicht vor
einem lokalen Administrator.

### 4.1 Atomare Publikation

Die Temporaerdatei 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 vollstaendige Snapshot erhalten. Seine Alterspruefung
verhindert unbegrenztes Weiterreichen alter Daten.

### 4.2 Keine direkte Checkmk-Spooldatei

Checkmk kann zwar Dateien aus seinem Spoolverzeichnis direkt anhaengen, prueft
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 uebernommen.

## 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-Zustaende. |
| `MSBTS_ServiceInstance` | suspendierte Instanzen. |
| `MSBTS_ReceiveLocation` | Receive-Location-Zustaende. |
| `MSBTS_SendPort` | Send-Port-Zustaende. |
| `MSBTS_Orchestration` | Orchestration-Zustaende. |

`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 fuer `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` mitgezaehlt.

### 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 fuer unerwartete
Aus-Zustaende. 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, waehrend
alle numerischen Metriken vollstaendig erhalten bleiben.

### 5.3 Endpoint-Discovery und Netzwerkprobe

Die Endpoint-Funktion erweitert keine WMI-Klassenmenge. Aus den ohnehin
minuetlich 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 geprueft.
Inaktive Artefakte bleiben aus der Probe ausgeschlossen, auch wenn sie noch im
Katalog stehen. Dynamische Send Ports, lokale Dateipfade, SMTP-Empfaengerlisten
und Named Pipes werden nicht als externe Host/Port-Ziele behandelt.

Der lokale Katalog
`%ProgramData%\BizTalkCheckmkPulse\data\endpoints.xml` wird beim ersten
erfolgreichen Lauf erzeugt und danach standardmaessig alle 168 Stunden atomar
abgeglichen. Er enthaelt keine vollstaendigen URIs, Querystrings,
Benutzernamen oder Kennwoerter, sondern nur Artefaktbezug, Adapter, Host, Port
und `TCP`/`UDP`. Automatisch erzeugte Eintraege tragen
`autoDiscovered="true"`. Ein bewusst manueller Override wird mit
`autoDiscovered="false"` markiert und beim Wochenabgleich erhalten; sein
`key` muss dem Artefakteintrag entsprechen. Eigenstaendige manuelle Ziele
verwenden `artifactType="Manual"`.

HTTP(S), SFTP, FTP, UNC/SMB, WCF und `net.tcp` werden ausschliesslich per
TCP-Connect geprueft. Es findet kein fachlicher Request und keine Anmeldung
statt. Explizite `udp://host:port`-Eintraege senden ein einzelnes Datagramm;
das bestaetigt DNS, Route und lokalen Versand, kann ohne
applikationsspezifisches Antwortprotokoll aber keinen entfernten Dienstzustand
beweisen. Gemeinsame Host/Port-Ziele werden dedupliziert und mit begrenzter
Parallelitaet getestet.

Der Checkmk-Service nennt im OK-Fall nur die Gesamtzahl. Bei Ausfaellen werden
ausschliesslich die nicht erreichbaren Artefakte in `unavailable=` angezeigt;
`MaxSummaryItems` und `MaxDetailCharacters` begrenzen die Darstellung. Alle
Einzelfehler bleiben vollstaendig im Provider-Log.

### 5.4 SQL-Zugriffsprobe

Der Provider oeffnet fuer Management- und Master-MessageBox-Datenbank eine
kurze `System.Data.SqlClient`-Verbindung mit integrierter
Windows-Authentifizierung, fuehrt `SELECT 1` aus und schliesst sie. Keine
BizTalk-Tabelle wird direkt gelesen oder veraendert.

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 fuehrte die `BizTalk Server Read Only Users`-Gruppe ein.
Sie darf Artefakte, Servicezustand, Message Flow und Trackinginformationen
lesen, aber keine administrativen Operationen ausfuehren. SQL-seitig wird sie
ueber `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 geprueft, 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 begruendet werden.

Unzulaessig:

- Checkmk-Dienstkonto aendern,
- Maschinenkonto pauschal berechtigen,
- individueller SQL-Login fuer 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 Eintraege 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 benoetigt, 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 ausgefuehrt, also
unabhaengig von einer interaktiven Anmeldung. Bei Kennwortwechsel oder
-ablauf muss das Task-Kennwort aktualisiert werden. Ein gMSA ist weiterhin
optional unterstuetzt, 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 vollstaendig 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.

Der installierte Task selbst laeuft mit `RunLevel Limited`. Der Installer
uebergibt das Kennwort direkt an die Windows-Task-Scheduler-COM-Schnittstelle;
es wird weder in einer Prozesskommandozeile noch in Config oder Log
geschrieben. Das Konto benoetigt `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 ausfuehren. Er liest nur maximal 1 MiB
lokale Daten; ein Checkmk-Async-Cache ist daher nicht notwendig. Falls alte
`check_mk.user.yml`-Regeln fuer den bisherigen 300-Sekunden-Cache existieren,
sollten sie entfernt werden, damit Checkmk den minuetlich aktualisierten
Snapshot nicht zusaetzlich verzoegert.

Nach dem Agent-Dump:

1. Service Discovery fuer den BizTalk-Host ausfuehren.
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 enthaelt UTC-Zeit, Level, Komponente, PID, Windows-Identitaet 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 zusaetzlich als eigene `WARN`-Zeile
protokolliert und bleibt damit auch ausserhalb der gekuerzten Checkmk-Summary
vollstaendig nachvollziehbar.

Logging ist best effort: Ein blockiertes Log darf Checkmk-Ausgabe oder
Snapshot-Publikation nicht zerstoeren. Der Provider entfernt beim Start Dateien
aelter als `LogRetentionDays`.

## 10. Diagnose und Runbook

### 10.1 Grundpruefung

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

Pruefen:

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 gueltig.
5. Provider besitzt Modify auf `data` und `logs`.
6. EXE/Config sind ausfuehrbar.

### 10.3 Staler Snapshot

Der Consumer nennt Alter und Grenzwert. Ursachen:

- Task deaktiviert oder Konto/Kennwort ungueltig,
- vorheriger Lauf haengt,
- WMI-/SQL-Timeouts,
- Task Scheduler lief waehrend Wartung nicht,
- Snapshot-Publikation wird durch AV/EDR oder ACL blockiert.

Nicht einfach `SnapshotMaxAgeSeconds` stark erhoehen. Zuerst den minuetlichen
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,
Datentraeger und AV/EDR pruefen. Wiederholt sich der Fehler, Temporaerdateien,
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 pruefen.
4. neuen Logontoken durch neuen Tasklauf sicherstellen.
5. SQL-seitig Gruppenlogin und `BTS_READONLY_USERS` read-only pruefen.
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.
Berechtigungserhoehung kann eine nicht vorhandene Klasse nicht erzeugen.
Installierte BizTalk-Version, WQL und Properties pruefen.

## 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` | `.` |
| `QueryTimeoutSeconds` | `25` |
| `ProbeSqlConnectivity` | `true` |
| `SqlConnectionTimeoutSeconds` | `5` |
| `ProbeEventLog` | `true` |
| `EventLogLookbackMinutes` | `60` |
| `ProbeEndpointConnectivity` | `true` |
| `EndpointDiscoveryIntervalHours` | `168` |
| `EndpointProbeTimeoutMilliseconds` | `3000` |
| `EndpointProbeMaxConcurrency` | `12` |
| `EndpointMaxCount` | `500` |

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 gezaehlt,
- Receive-/Send-Allowlisten trennen bewusste von unerwarteten Aus-Zustaenden,
- ein fehlender `IsDisabled`-Wert wird `UNKNOWN` statt still als enabled,
- betroffene Namen und Gesamtlaenge der Summary bleiben begrenzt,
- Endpoint-Adressen werden ohne URI-Secrets auf Host/Port reduziert,
- manuelle Endpoint-Overrides ueberleben den automatischen Wochenabgleich,
- nur nicht erreichbare Endpoints erscheinen im Checkmk-Detail,
- Snapshot-Roundtrip und Ersatz,
- SHA-256-Manipulation wird verworfen,
- Stale-Snapshot wird verworfen,
- Consumer-Fallback enthaelt neun `UNKNOWN`-Services.

Windows-/ACC-Abnahme:

1. `LastTaskResult=0`.
2. Snapshot wird mindestens dreimal minuetlich 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,
   einschliesslich Routing Failure Reports.
8. Eine bewusst deaktivierte Receive Location und einen inaktiven Send Port
   ueber die exakten Allowlisten als expected bestaetigen.
9. Einen Testnamen aus der Allowlist entfernen und den erwarteten CRIT mit
   kurzem `affected=`-Detail pruefen.
10. ACL-Test: `LocalSystem` kann Snapshot lesen, nicht schreiben.
11. `endpoints.xml` wurde erzeugt; sie enthaelt keine vollstaendigen URIs oder
    Zugangsdaten und nur Started-/Enabled-Artefakte.
12. Einen erreichbaren Testport sperren: nur `Endpoint Reachability` wird CRIT
    und nennt ausschliesslich das nicht erreichbare Ziel.
13. Ein Artefakt stoppen/deaktivieren: es wird im naechsten Minutenlauf nicht
    mehr geprueft.
14. Katalogzeit auf aelter als 168 Stunden setzen beziehungsweise Intervall
    testweise reduzieren: erfolgreicher atomarer Umgebungsabgleich.
15. Task deaktivieren: nach 180 Sekunden neun stale-`UNKNOWN`s.
16. Task wieder aktivieren: naechster Snapshot stellt Echtzustand her.
17. 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**
waehlen. Der Installer entfernt Task, Wrapper und Programmdateien, behaelt
Logs und Snapshot aber absichtlich bei. Die AD-Gruppenmitgliedschaft wird
nicht geaendert 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://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