372 lines
18 KiB
Markdown
372 lines
18 KiB
Markdown
# 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`.*
|