biztalk-checkmk-pulse/deployment/INSTALLATION.md

Installation auf dem BizTalk-Server

1. BizTalkCheckmkPulse-Setup.zip vollständig in ein lokales Verzeichnis entpacken.
2. Setup.exe als lokaler Administrator starten und die UAC-Abfrage bestätigen.
3. Das Collector-Konto im Format DOMAIN\Benutzer eingeben, zum Beispiel BEW\t231bizmon.
4. Kennwort und Umgebung eingeben und Installieren / aktualisieren wählen.
5. Im Aufgabenplaner den Task BizTalk Checkmk Pulse Provider und danach den Checkmk-Agent-Dump kontrollieren.

Bei einer bereits vorhandenen ACC-Installation ist dies ein Update. Der Installer erkennt die bestehende Umgebung, behält Endpoint-Katalog, Snapshot und Logs sowie vorhandene AppSettings bei und ergänzt neue Config-Keys aus dem Paket. Das BEW-Konto und sein aktuelles Kennwort müssen erneut eingegeben werden, weil der Scheduled Task mit den bestätigten Zugangsdaten neu registriert wird.

Die früheren unveränderten Endpoint-Defaults 12 parallele Probes und EndpointMaxCount=500 werden beim Update auf 16 beziehungsweise 100 migriert. Abweichende, bewusst konfigurierte Werte bleiben erhalten. EndpointMaxCount begrenzt nun eindeutige Socket-Ziele statt Artefakte; der neue Wert EndpointCatalogMaxEntries=1000 begrenzt separat die Kataloggröße.

Version 2.2.2 ergänzt IncludeEnvironmentInServiceName=false. Damit bleibt EnvironmentName=ACC als Umgebungsmetadatum erhalten, ohne die bestehenden Services von BizTalk ... in BizTalk ACC ... umzubenennen. Das beseitigt nach dem nächsten Agentenlauf das 2.2.1-Fehlerbild Item not found in monitoring data. Nur bei bewusst auf true gesetztem Opt-in ist anschließend eine Checkmk Service Discovery erforderlich.

Ab Version 2.2.5 vergleicht der Installer bei jedem Update die exakten Servicenamen der installierten und der vorbereiteten Version. Rein neue Services sind abwärtskompatibel, blockieren das Update nicht und werden als Hinweis für die anschließende Service Discovery angezeigt. Entfernte oder umbenannte Services führen vor dem Stoppen des Tasks zu einem Sicherheitsstopp. Die Installation darf dann nur über die Checkbox Service-Rename ist beabsichtigt; Checkmk Service Discovery ist eingeplant fortgesetzt werden. Der Installer zeigt dabei die entfernten und neuen Namen an. Eine bloß geänderte Ausgabereihenfolge gilt nicht als Rename.

Version 2.2.5 akzeptiert außerdem den gültigen Self-Test einer installierten Legacy-Version mit weniger Services. Paket, Staging und aktivierte Zielversion müssen weiterhin exakt neun Services liefern. Damit kann insbesondere eine Version mit acht Services auf die Version mit dem zusätzlichen Service BizTalk Endpoint Reachability aktualisiert werden. Der frühere Abbruch Exitcode=0, Zeilen=8 betraf die Altversion und war kein Fehler im neuen Paket.

Version 2.2.6 trennt technische Installationsabnahme und fachlichen Endpoint-Zustand. Ein frischer, integritäts- und identitätsgeprüfter Snapshot mit allen neun Services und ein frisch synchronisierter Endpoint-Katalog belegen eine funktionsfähige Installation. Meldet ausschließlich BizTalk Endpoint Reachability weiterhin UNKNOWN, wird die Installation abgeschlossen und die vollständige Checkmk-Zeile als Warnung im Setup sowie im Setup-Log ausgegeben. Der Status bleibt im Snapshot und in Checkmk unverändert UNKNOWN, bis Auflösungslücken, Katalog-/Probeprobleme oder fehlende manuelle Overrides betrieblich geklärt sind. UNKNOWN in Platform, SQL oder einem anderen Kernservice bleibt ein blockierender Abnahmefehler.

Version 2.2.4 nimmt die umgeschaltete Installation zusätzlich vollständig ab:

• einmaliger, triggerloser Providerlauf unter dem angegebenen Collector-Konto,
• erzwungener vollständiger Abgleich von endpoints.xml, wobei gültige manuelle Overrides erhalten bleiben,
• maximal vier Minuten Warten auf LastTaskResult=0,
• Snapshot muss nach Beginn des Abnahmelaufs erzeugt, SHA-256-valid, für die aktuelle Maschine und vom erwarteten Collector-Konto geschrieben sein,
• alle neun stabilen Services müssen eindeutig vorhanden sein; WARN und CRIT sind reale Betriebszustände. UNKNOWN in Kernservices blockiert die Installation; ausschließlich BizTalk Endpoint Reachability = UNKNOWN wird ab 2.2.6 als nicht blockierende Betriebswarnung übernommen,
• bei aktivierter Endpoint-Prüfung muss auch der Katalog nach Beginn des Abnahmelaufs atomar synchronisiert worden sein.

Erst danach ersetzt der Installer den Abnahmetask durch den normalen Minutentask und löscht das Backup. Bei Fehler oder Timeout wird die vorherige Programmversion samt Task wiederhergestellt und ein frischer Lauf der alten Version abgewartet. Fehler in Paket-, Config- oder Rename-Vorprüfung treten vor jeder Taskänderung auf und lassen die laufende Installation unangetastet.

Jeder Installations-/Updatelauf schreibt ein separates Diagnoselog nach %ProgramData%\BizTalkCheckmkPulse\logs\setup-*.log. Es enthält die aktuelle Phase, Pfad und Version jeder geprüften EXE, Exitcode, vollständiges stdout und stderr des Self-Tests, Taskstatus samt Dezimal-/Hexcode, Exception-Kette und Rollback-Ergebnis. Bei einem Runtime-Abnahmefehler werden zusätzlich die letzten Provider-Logzeilen übernommen. Das Collector-Kennwort wird weder an das Logging übergeben noch protokolliert. Ein abgeschlossener Providerlauf mit Fehlercode beendet die Abnahme sofort; nur ein noch laufender Task wird bis zur Timeoutgrenze abgewartet.

Beim korrigierenden Wechsel von 2.2.1 mit BizTalk ACC ... auf stabile BizTalk ...-Namen ist die Änderung beabsichtigt: Checkbox aktivieren und den Servicebestand danach per Discovery abgleichen. Sind in Checkmk bereits die unpräfixierten Services vorhanden, werden damit insbesondere eventuell vorhandene falsche BizTalk ACC ...-Services bereinigt.

Vor dem Stoppen des vorhandenen Tasks wird die neue Version separat getestet und ihr Checkmk-Servicevertrag mit der installierten Version verglichen. Bei normalen Servicekonten prüft der Installer außerdem Kennwort und Batch-Anmelderecht vor der Umschaltung. Der Task wird vor dem Dateitausch deaktiviert und sein Prozessende maximal zehn Sekunden abgewartet, damit keine laufende Provider-EXE überschrieben wird. Bei einem Fehler nach der Umschaltung versucht der Installer, vorherige Programmdateien, Wrapper und Task wiederherzustellen.

PowerShell wird für Installation, Update, Deinstallation und Laufzeit nicht benötigt. Das Kennwort wird direkt an die Windows-Aufgabenplanung übergeben und weder in einer Datei noch in einer Prozesskommandozeile abgelegt.

Der Installer vergibt keine AD-, BizTalk- oder SQL-Berechtigungen. Das Konto muss separat Mitglied der für die BizTalk-Gruppe konfigurierten Read-Only- Gruppe sein und lokal das Recht Log on as a batch job besitzen.

Bei einer Deinstallation bleiben Snapshot und Logs absichtlich unter %ProgramData%\BizTalkCheckmkPulse erhalten. Sie können nach der Betriebsfreigabe manuell entfernt werden.