biztalk-checkmk-pulse/README.md

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

```text
Scheduled Task (normales dediziertes Servicekonto)
  |
  | 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
acht kompakte 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:

```text
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 acht 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 Receive Locations`
- `BizTalk Send Ports`
- `BizTalk Orchestrations`
- `BizTalk Event Log`

Die drei Artefaktbereiche sind absichtlich getrennte Services. Dadurch sind
Zustand und Graphen direkt erkennbar, ohne eine lange Sammelzeile zu lesen:

- Suspensions: total, resumable, non-resumable und Routing Failure Reports
- Receive Locations: total, enabled, unerwartet/bewusst disabled und unbekannt
- Send Ports: total, started, stopped, bound, unbekannt sowie bewusst inactive
- Orchestrations: total, started, stopped, bound, unbound und unbekannt

Pro Service werden standardmaessig maximal fuenf betroffene Namen gezeigt.
Weitere Treffer erscheinen nur als `(+n more)`; Details sind zusaetzlich auf
1600 Zeichen begrenzt. Metriken bleiben trotzdem vollstaendig.

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](docs/CheckmkServices.md)

Beispielausgaben: [docs/ExampleOutput.md](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
- normales dediziertes AD-Servicekonto 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. Der Scheduled
Task laeuft mit `RunLevel Limited`. Das Servicekonto braucht ein gespeichertes
Task-Kennwort und das Recht `Log on as a batch job`. Ein gMSA bleibt optional,
ist aber fuer diese Installation nicht vorausgesetzt.

## Build und Tests

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

Jeder Release-Build der Solution erzeugt automatisch den fertigen Paketordner
und das transportierbare ZIP:

```text
artifacts\
  BizTalkCheckmkPulse-Setup.zip
  BizTalkCheckmkPulse-Setup\
    Setup.exe
    INSTALLATION.md
    biztalk_checkmk_pulse.cmd
    application\
      BizTalkCheckmkPulse.exe
      BizTalkCheckmkPulse.exe.config
```

Das Packaging-Projekt ist Teil von `BizTalkCheckmkPulse.sln`. Ein normaler
`Release`-Build in Visual Studio 2019 genuegt daher; ein separates
PowerShell-/WiX-/MSI-Tooling wird nicht benoetigt.

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

```cmd
artifacts\BizTalkCheckmkPulse-Setup\application\BizTalkCheckmkPulse.exe --self-test
```

Erwartet werden exakt acht `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 AD-Administrator nimmt das neue Provider-Konto in
`BizTalkReadOnlyUserGroup` auf. Nach AD-Replikation muss das Servicekonto durch
einen neuen Tasklauf einen neuen Anmeldetoken erhalten.

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 normalem Servicekonto

1. `BizTalkCheckmkPulse-Setup.zip` auf dem Zielserver vollstaendig entpacken.
2. `Setup.exe` starten und die UAC-Abfrage bestaetigen.
3. Collector-Konto, zum Beispiel `BEW\t231bizmon`, Kennwort und Umgebung
   eingeben.
4. **Installieren / aktualisieren** waehlen.

Der Installer uebergibt das Kennwort direkt ueber die Windows-Task-Scheduler-
COM-Schnittstelle. Es steht weder in einer Prozesskommandozeile noch in der
Konfigurationsdatei oder in Logs. Der Backslash in `DOMAIN\Benutzer` wird als
normaler Bestandteil des Kontonamens verarbeitet.

Wenn das Kennwort rotiert oder ablaeuft, muss es im Scheduled Task aktualisiert
werden. Dazu `Setup.exe` mit dem neuen Kennwort erneut ausfuehren. Bis dahin
wird der Snapshot nach 180 Sekunden stale und Checkmk zeigt alle acht Services
als `UNKNOWN`.

Ein gMSA kann ueber die Checkbox ohne Kennworteingabe installiert werden; die
produktive Standardbeschreibung geht vom normalen Servicekonto aus.

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.

Installation, Update, Deinstallation und Laufzeit verwenden keine PowerShell.

## Verifikation auf dem Server

Task und letzter Lauf:

```cmd
schtasks.exe /query /tn "BizTalk Checkmk Pulse Provider" /v /fo list
```

Provider-Log:

```cmd
dir /o-d "%ProgramData%\BizTalkCheckmkPulse\logs"
type "%ProgramData%\BizTalkCheckmkPulse\logs\biztalk-checkmk-pulse-*.log"
```

Snapshot und Consumer:

```cmd
dir "%ProgramData%\BizTalkCheckmkPulse\data\biztalk-checkmk-pulse.snapshot"
"%ProgramFiles%\BizTalkCheckmkPulse\BizTalkCheckmkPulse.exe" --consume
```

Verbindlicher Test im echten `LocalSystem`-Kontext:

```cmd
"C:\Program Files (x86)\checkmk\service\cmk-agent-ctl.exe" dump
```

Danach in Checkmk eine Service Discovery ausfuehren, die acht 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

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

```text
%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. |
| `CritRoutingFailureThreshold` | `1` | CRIT ab n Routing Failure Reports. |
| `AlertOnArtifactRuntimeIssues` | `true` | Unerwartet deaktivierte Receive Locations bzw. inaktive Send Ports werden CRIT. |
| `ExpectedDisabledReceiveLocations` | leer | Pipe-getrennte exakte Allowlist: `Name` oder `Anwendung\Name`. |
| `ExpectedInactiveSendPorts` | leer | Pipe-getrennte exakte Allowlist: `Name` oder `Anwendung\Name`. |
| `AlertOnInactiveOrchestrations` | `false` | Optional WARN fuer stopped/bound/unbound Orchestrations. |
| `MaxSummaryItems` | `5` | Maximal angezeigte betroffene Artefakte je Service. |
| `MaxDetailCharacters` | `1600` | Harte Obergrenze fuer Checkmk-Summary. |
| `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 acht Services melden fehlenden Snapshot | Task, Provider-Log, Task-Konto/Kennwort 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. |
| Receive Locations / Send Ports sind CRIT | `affected=` pruefen; nur fachlich bewusst inaktive Namen exakt in die jeweilige Allowlist aufnehmen. |
| `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](Dokumentation.md).

## Deinstallation

`Setup.exe` erneut starten und **Deinstallieren** waehlen. Snapshot und Logs
bleiben dabei unter `%ProgramData%\BizTalkCheckmkPulse` erhalten.

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

## 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](Dokumentation.md).