Gizzler/123123
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fix/mfapi-classpath-ct-zadbservice
123123/ZA.CoreService.ESBCertificateManager/Docs/Neustart-und-Management-API.md
T

18 KiB
Raw Permalink Blame History

ESB Certificate Manager – Neustart, Management-API & Zertifikatsprüfung

Ausführliche Erklärung für Präsentation, Übergabe und Troubleshooting.
Stand: Branch fix/mfapi-classpath-ct-zadbservice (MfApi-Neustart, Zertifikat erkennen).

1. Was die App heute macht (und was nicht)

Aktiv

Funktion Kurzbeschreibung
Zertifikat erkennen Datei wählen (.cer / .crt / .pem / .pfx), Metadaten anzeigen, Gültigkeit prüfen
Container laden Optional: Liste aus Sonic Domain Manager + Fallback KnownContainers
ESB neu starten Container-Neustart über Sonic Management Application API (wie Restart in der SMC)

Bewusst nicht (mehr) aktiv

Entfernt / deaktiviert Warum
Zertifikat auf Zielpfad kopieren (Deploy) UI-Button ausgeblendet; war eigener Deploy-Pfad
TLS-Probe nach Deploy Fingerprint gegen laufenden Endpoint – nicht Teil des aktuellen Scope
XApi-Import Extra-Skript/WinRM-Pfad, oft nicht vorhanden
WinRM / stopcontainer.bat SMC-only-Installationen haben die Server-Scripts oft nicht; Logins ≠ Windows
HTTP-REST Management Kein stabiler Endpoint in dieser Umgebung nachweisbar
SQL- / Offline-Sample-Ziele Container kommen aus KnownContainers / Live-Discovery

Kurz: Datei prüfen + Neustart. Alles andere war Ballast für den aktuellen Use-Case.

2. Begriffe (wichtig für die Erklärung)

Begriff Bedeutung in diesem Projekt
SMC Sonic Management Console – die GUI, mit der Operatoren Container starten/stoppen/neustarten
Domain Logische Sonic-Domain, hier: proalpha-test
Container Laufzeit-Container / Agent, hier: ct-ZADBService
Verbindungs-Alias Name in appsettings (DE-Test) – nicht der Containername
ObjectName JMX-Name: proalpha-test.ct-ZADBService:ID=AGENT
Domain Manager / Broker-URL tcp://dekun-painwbdet:13070 – dieselbe URL wie beim SMC-Login
MfApi Unser Modusname für „Management Application API“ über Java-Client-JARs
unbounded client connector Remote-JMS-Client (wie die SMC von außen). Manche Proxy-Methoden (z. B. IAgentProxy.restart()) sind dafür gesperrt
Launch Daemon Prozess auf dem Host, der einen gestoppten Container oft automatisch wieder startet (SMC „Restart“ ≈ Stop + Auto-Relaunch)

Merksatz für Präsentationen:

DE-Test ist die Verbindung. ct-ZADBService ist der Container. Die Domain heißt proalpha-test.

3. Architektur – Überblick

┌─────────────────────────────────────────────────────────────┐
│  WinForms UI (Form1)                                        │
│  - Zertifikat wählen / anzeigen                             │
│  - Ziele anhaken                                            │
│  - Button „ESB neu starten“                                 │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  DeploymentOrchestrator.RestartOnlyAsync                    │
│  → PreflightValidator (ContainerName + SonicConnection)     │
│  → RestartExecutor                                          │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  SonicManagementClient (dünne Fassade, nur MfApi)           │
│  → SonicMfApiExecutor                                       │
└───────────────────────────┬─────────────────────────────────┘
                            │ startet Prozess
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  java.exe (Java 8+)                                         │
│  Classpath: Tools\ + C:\DEV\MQ10.0\lib\*.jar                │
│  Klasse: SonicMfContainerTool                               │
│  Befehl: restart --domain … --url … --user … --container …│
└───────────────────────────┬─────────────────────────────────┘
                            │ JMS / JMX (Management Framework)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Sonic Domain Manager                                       │
│  tcp://dekun-painwbdet:13070                                │
│  Agent: proalpha-test.ct-ZADBService:ID=AGENT               │
└─────────────────────────────────────────────────────────────┘

Es gibt keine eigene REST-API der WinForms-App.
Die „API“ ist die Sonic Management Application API (Java, JARs unter MQ10.0\lib), dieselbe Schicht, die auch die SMC nutzt.

Offizielle Doku-Verweise (Index im Repo):

  • doc-10.0.10/CXMessenger_2017_R3.htm → Management Application API Reference (Docs2017/api/mgmt_api/)
  • Bücher: MQ/ESB Configuration and Management Guide

(Die PDF-/HTML-API-Ordner können im Checkout fehlen – der Index verlinkt sie trotzdem.)

4. Zertifikat – Erkennen & „Verifizieren“

4.1 Was wir heute tun

Die App liest und prüft die Zertifikatsdatei lokal. Sie spielt das Zertifikat nicht auf den ESB und prüft nicht per TLS-Handshake gegen einen Server (dieser Pfad ist deaktiviert).

Ablauf in der UI (Form1):

  1. Benutzer wählt Datei (.cer, .crt, .pem, .pfx).
  2. Datei wird mit X509Certificate2 geladen.
  3. Bei .pfx ggf. Passwort-Dialog.
  4. Anzeige:
    • Subject
    • Issuer
    • Gültig bis
    • SHA-256-Fingerprint (formatiert mit :)
    • Status GÜLTIG / UNGÜLTIG / ABGELAUFEN (Vergleich mit DateTimeOffset.Now und NotBefore/NotAfter)

Das ist Dateiverifikation / Metadaten-Check, kein Deploy und kein Remote-TLS-Verify.

4.2 Was „Zertifikat verifizieren“ bedeuten kann (für die Erklärung)

Stufe Bedeutung Status in dieser App
A. Datei lesen Datei ist ein gültiges X.509, Parsing ok ✅ aktiv
B. Zeitliche Gültigkeit now zwischen NotBefore und NotAfter ✅ aktiv
C. Fingerprint anzeigen SHA-256 zum manuellen Abgleich ✅ aktiv
D. Auf Ziel kopieren Datei nach TargetDirectory legen ❌ deaktiviert
E. TLS-Probe TCP/TLS zum Host:Port, Remote-Zertifikat lesen, Fingerprint vergleichen ❌ entfernt / nicht aktiv
F. Trust-Chain / CA Kette gegen Windows-Truststore prüfen ❌ nicht implementiert

Wenn jemand fragt „Wird das Zertifikat verifiziert?“:

Wir verifizieren die Datei lokal (lesbar, Gültigkeitszeitraum, Fingerprint).
Ein Abgleich gegen den laufenden ESB-Endpoint per TLS ist aktuell nicht Teil der App.
Der Neustart betrifft den Container, nicht automatisch die Zertifikatsinstallation.

4.3 Typische Demo-Sätze

  • „Hier lade ich das Zertifikat – Subject/Issuer/Fingerprint erscheinen sofort.“
  • „Rot = abgelaufen oder außerhalb des Gültigkeitsfensters.“
  • „Den Fingerprint kann man mit dem erwarteten Wert aus der Doku/SMC abgleichen.“
  • „Kopieren auf den Server und TLS-Nachprüfung wären der nächste Ausbauschritt – bewusst getrennt vom Neustart.“

5. Die Sonic Management Application API – warum sie kompliziert wirkt

5.1 Was Sonic bereitstellt (Produkt-API, nicht unsere Erfindung)

Sonic/Aurea CX Messenger hat mehrere API-Welten:

API Zweck Nutzen wir für Neustart?
Management Application API (mgmt_api) Domain Manager, Agenten, Restart/Stop wie SMC ✅ ja
CX Messenger MQ API Messaging (Queues, Producer/Consumer) ❌ nein
ESB API ESB-Services/Prozesse ❌ nein
Metrics / Notifications Monitoring ❌ nein
Administrative Programming Guide erweiterte Admin-Szenarien nur indirekt als Konzept

Für den Container-Neustart ist laut Produkt-Doku-Index die Management Application API der richtige Einstieg – analog zum SMC-Button „Restart“.

5.2 Kernklassen (die wirklich gebraucht werden)

Klasse / Konzept Rolle
JMSConnectorAddress Verbindungsparameter (URL, User, Pass)
JMSConnectorClient JMS/JMX-Verbindung zum Domain Manager
ObjectName Ziel-Agent, z. B. domain.container:ID=AGENT
MFProxyFactory.createAgentProxy Typisierter Proxy (IAgentProxy)
IAgentProxy / MBean-Operationen stop / restart / shutdown …
Client-JARs unter lib u. a. mgmt_client.jar, mfcontext.jar, sonic_Client.jar

5.3 Warum es trotzdem „viele unnötige Funktionen“ zu geben scheint

Ja – die Sonic-API ist enorm breit. Sie deckt Broker-Verwaltung, Queues, Durable Subscribers, Metrics, Config-Beans, Directory Service, Host Manager usw. ab.
Für unseren Use-Case brauchen wir nur einen schmalen Schnitt:

  1. Verbinden
  2. Agent-ObjectName finden
  3. Lifecycle: Stop/Restart

Alles andere in den JARs und in der mgmt_api-Javadoc ist Produktumfang, nicht „unsere App-API“.

Zusätzlich wirkt unser Java-Tool (SonicMfContainerTool) kompliziert, weil es Fallbacks hat:

Schritt Was Warum
1 `MBean.invoke("stop" "restart"
2 IAgentProxy.stop/restart/shutdown „Schöner“ typisierter Pfad – scheitert oft mit unbounded
3 DomainManager/restartContainer Weitere Fallback-Variante

Das ist Absicherung, kein Feature-Wahn. Man könnte später auf den einen Pfad reduzieren, der in eurer Umgebung stabil ist (vermutlich MBean stop).

5.4 „Unbounded client connector“ – Kernpunkt für Erklärungen

Remote-Clients (SMC, unser Tool) verbinden sich als unbounded JMS-Connector.

Manche Methoden am typisierten Proxy prüfen das und werfen:

javax.management.JMRuntimeException:
Operation unsupported for unbounded client connector.

Deshalb:

  • IAgentProxy.restart() allein ist kein zuverlässiger Remote-Weg.
  • Stattdessen: JMX invoke auf dem Agent-MBean, typischerweise stop.
  • Wenn der Container unter einem Launch Daemon / Host Manager läuft, kommt er wieder hoch → Operator-Wirkung „Restart“.

6. Neustart – End-to-End-Ablauf

6.1 Konfiguration (appsettings.json)

Beispiel (relevante Felder):

{
  "Name": "DE-Test",
  "DomainName": "proalpha-test",
  "ConnectionUrl": "tcp://dekun-painwbdet:13070",
  "Username": "Administrator",
  "Password": "Administrator",
  "SonicHome": "C:\\DEV\\MQ10.0",
  "JavaPath": "C:\\Program Files (x86)\\Java\\jre1.8.0_501\\bin\\java.exe",
  "MfClientLibPath": "C:\\DEV\\MQ10.0\\lib",
  "KnownContainers": [ "ct-ZADBService" ],
  "TimeoutSeconds": 120,
  "PostRestartDelaySeconds": 20
}

Container in appsettings unter der Verbindung DE-Test:

  • KnownContainers: [ "ct-ZADBService" ]

6.2 UI → C#

  1. Benutzer hakt Ziel an → ESB neu starten.
  2. PreflightValidator: ContainerName + SonicConnectionName müssen gesetzt sein.
  3. RestartExecutor sucht die SonicConnection und ruft SonicManagementClient.RestartContainerAsync auf.
  4. SonicMfApiExecutor:
    • Java 8+ finden
    • Classpath aus allen JARs unter MfClientLibPath / SonicHome\lib bauen
    • Tools\SonicMfContainerTool.class (Java-8-Bytecode) laden
    • Prozess starten mit sauberer Argumentübergabe (ArgumentList, keine doppelten Quotes)

Ungefährer Aufruf:

java -cp "<Tools>;<jar1>;<jar2>;..." SonicMfContainerTool restart
  --domain proalpha-test
  --url tcp://dekun-painwbdet:13070
  --user Administrator
  --container ct-ZADBService
  --timeout 120

Passwort: Umgebungsvariable ESB_SONIC_PASSWORD (nicht auf der Kommandozeile).

6.3 Java-Tool (SonicMfContainerTool)

  1. Loggt INFO:ToolVersion=… (Build-Kontrolle).
  2. connect über JMSConnectorAddress + JMSConnectorClient.
  3. ObjectName: bevorzugt proalpha-test.ct-ZADBService:ID=AGENT.
  4. Lifecycle-Versuche (siehe Abschnitt 5.3).
  5. Erfolg: Zeile OK:RestartInvoked method=…
  6. C# wertet OK:RestartInvoked als Erfolg und wartet PostRestartDelaySeconds.

6.4 Erfolgsdefinition

Signal Bedeutung
INFO:Connected … Login/URL ok
INFO:ToolVersion=… Richtige Tool-Version läuft
OK:RestartInvoked … Lifecycle-Aufruf durchgekommen
SMC zeigt Offline → Online / Uptime reset Operative Bestätigung

7. Braucht die API „viele unnötige Funktionen“?

Kurze Antwort

Die Sonic-Produkt-API ja – unser benötigter Schnitt nein.

Aufschlüsselung

Schicht Viele Funktionen? Für uns nötig?
Sonic mgmt_api + Client-JARs Ja, sehr breit Nur Connect + Agent-Lifecycle
Unser C#-Client früher (WinRM, HTTP, XApi, Bat) Ja, historisch gewachsen Nein – weitgehend entfernt
SonicMfContainerTool Fallbacks (MBean / IAgentProxy / DomainManager) Mehrere Wege Nützlich bis ein Weg überall stabil ist; danach ausdünnbar
Zertifikat TLS-Probe / Deploy Extra-Komplexität Aktuell nicht nötig

Was man später noch verschlanken könnte

  1. Im Java-Tool nur noch den einen erfolgreichen Weg behalten (z. B. nur MBean.invoke("stop")).
  2. In appsettings tote Felder entfernen (WinRm*, Container*Path, ManagementHttpPort, …) – stehen teils noch in JSON, werden vom schlanken Client nicht mehr genutzt.
  3. SonicMfApiExecutor Java-Discovery vereinfachen, sobald JavaPath überall fest gesetzt ist.
  4. Optional: Zertifikat-Deploy + TLS-Probe als eigenes Modul wieder einführen – klar getrennt vom Neustart.

8. Voraussetzungen auf dem Rechner (Checkliste)

Voraussetzung Beispiel / Hinweis
SMC-Client / MQ-Libs C:\DEV\MQ10.0\lib mit mgmt_client.jar, mfcontext.jar, sonic_Client.jar
Java 8+ z. B. jre1.8.0_501\bin\java.exe (nicht zu alte Sonic-JRE 6/7)
Netzwerk Port 13070 zum Domain Manager erreichbar
Credentials Dieselben wie SMC-Login
Containername Exakt wie in SMC (ct-ZADBService), nicht der Alias DE-Test
App-Build Frische Tools\SonicMfContainerTool.class (Ausgabe muss ToolVersion zeigen)

9. Typische Fehler & Interpretation

Fehler / Symptom Ursache Maßnahme
ClassNotFoundException: JMSConnectorAddress Classpath/JARs fehlen oder Quotes kaputt MfClientLibPath, neuen Build, ArgumentList
UnsupportedClassVersionError Tool mit zu neuem Java gebaut / zu alte Runtime Tool major 52 + Java 8+ Runtime
Operation unsupported for unbounded… IAgentProxy.restart remote gesperrt MBean stop / neuer Tool-Build mit Fallbacks
Kein INFO:ToolVersion= Alte .class im Output Neu bauen, Debug/Release-Ordner prüfen
Container DE-Test Alias statt Kurzname ct-ZADBService setzen
stopcontainer.bat fehlt SMC-only Erwartet – MfApi nutzen, nicht Bat

10. Dateien im Code (Orientierung)

Datei Rolle
Form1.cs UI: Zertifikat + Ziele + Neustart (Design)
Services/DeploymentOrchestrator.cs Nur RestartOnlyAsync
Services/RestartExecutor.cs Mappt Ziel → Sonic-Verbindung
Services/SonicManagementClient.cs Fassade MfApi
Services/SonicMfApiExecutor.cs Java starten, Classpath, Tool
Tools/SonicMfContainerTool.java Eigentliche Management-API-Aufrufe
appsettings.json Domain, URL, Login, Java, Lib-Pfad, KnownContainers

11. Präsentations-Skript (kurz)

  1. Problem: Zertifikat prüfen und ESB-Container neu starten – ohne manuelle SMC-Klicks jedes Mal.
  2. Zertifikat: Datei laden → Subject/Issuer/Fingerprint/Gültigkeit. Lokal verifiziert, noch kein Deploy.
  3. Neustart: Dieselbe Management-API wie die SMC, nicht FTP, nicht stopcontainer.bat.
  4. Technik: C# orchestriert, Java + Sonic-Client-JARs sprechen mit dem Domain Manager.
  5. Komplexität: Die Sonic-API ist riesig; wir nutzen nur Connect + Agent-Stop/Restart. Fallbacks wegen „unbounded connector“.
  6. Ergebnis: Container ct-ZADBService in Domain proalpha-test wird remote neu gestartet.

12. Offene Punkte / nächste sinnvolle Ausbauten

  1. Zertifikat nach Erkennung auf den Zielhost legen (Deploy) – bewusst getrennt.
  2. Optional TLS-Probe (Remote-Fingerprint) nach Deploy.
  3. Java-Tool auf den einen erfolgreichen Lifecycle-Pfad reduzieren.
  4. appsettings von Altlast-Feldern (WinRM/HTTP) bereinigen.
  5. Fehlende offizielle mgmt_api-HTML/PDF ins Repo legen, damit man in Reviews direkt die Klassen verlinken kann.

Dokument erzeugt für Übergabe/Erklärung. Bei Abweichungen gilt der Code auf Branch fix/mfapi-classpath-ct-zadbservice.

Reference in New Issue View Git Blame Copy Permalink