Remove offline sample targets; load containers from appsettings KnownContainers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-24 12:20:26 +02:00
parent d1b95bcb9d
commit ade63d0e43
11 changed files with 956 additions and 131 deletions
@@ -0,0 +1,371 @@
+# 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
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  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"|"shutdown")` | Remote/„unbounded“ oft der Weg, den SMC faktisch nutzt |
+| 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:
+
+```text
+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):
+
+```json
+{
+  "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:
+
+```text
+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`.*