# 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`.*