Gizzler/123123
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
89a694ba217bc7d3701dea23c546f3582c5c1299
123123/ZA.CoreService.ESBCertificateManager/Docs/Komplette-Erklaerung.md
T

17 KiB
Raw Blame History

Komplette Erklärung: ESB Certificate Manager

Was passiert – einzeln, von oben nach unten.
Zertifikat prüfen · Ziele laden · Sonic-API · Container-Neustart.

Diese Datei ist zum Erklären (Präsentation, Kollegen, Übergabe).
Technischer Fokus: aktueller Stand mit MfApi-Neustart und lokaler Zertifikatserkennung.

Teil A – Was die Anwendung ist

A1. Zweck in einem Satz

Die WinForms-App hilft dabei,

  1. ein Zertifikat als Datei zu erkennen und lokal zu prüfen, und
  2. einen Sonic-/ESB-Container remote neu zu starten – so ähnlich wie der Restart-Button in der Sonic Management Console (SMC).

A2. Was sie bewusst nicht macht (aktuell)

Nicht aktiv Erklärung
Zertifikat auf den Server kopieren Deploy-Button ist ausgeblendet
Nach dem Deploy TLS gegen den Endpoint prüfen früher TLS-Probe – entfernt/deaktiviert
XApi importieren nicht mehr im Pfad
Neustart per stopcontainer.bat oft in SMC-only-Installationen nicht vorhanden
Neustart per WinRM / Windows-Login SMC-User ≠ Windows-User
Eigene HTTP-REST-API der App die App ist kein Server; sie ruft Sonic auf

A3. Die wichtigsten Namen in eurer Umgebung

Name Typ Beispiel
Verbindungs-Alias Eintrag in appsettings DE-Test
Domain Sonic-Domain proalpha-test
Container (kurz) Laufzeit-Container ct-ZADBService
ObjectName (JMX) vollständige Agent-Adresse proalpha-test.ct-ZADBService:ID=AGENT
ConnectionUrl Domain-Manager wie in SMC tcp://dekun-painwbdet:13070
Login SMC-Credentials Administrator / Administrator
Sonic-Libs Client-JARs C:\DEV\MQ10.0\lib
Java Runtime für das Hilfstool JRE 1.8+

Merksatz:
DE-Test = Verbindung. ct-ZADBService = Container. Nicht vertauschen.

Teil B – Programmstart (was zuerst passiert)

B1. Start der App

  1. Program.cs startet Form1.
  2. AppSettingsLoader liest appsettings.json (aus dem Output-Ordner der App).
  3. Es werden gebaut:
    • DeploymentOrchestrator (Neustart-Orchestrierung)
    • SonicContainerDiscovery (Container-Liste optional laden)
  4. Die UI (Dark-Design) wird aufgebaut.
  5. Beim ersten Anzeigen (Shown) werden Ziele geladen.

B2. Ziele laden

  1. Ziele kommen aus appsettings.json → SonicConnections[].KnownContainers (kein Offline-JSON).
  2. Jede Zeile hat u. a.:
    • Anzeigename (DE-Test / ct-ZADBService)
    • Umgebung = Domain
    • ContainerName (z. B. ct-ZADBService)
    • SonicConnectionName (z. B. DE-Test)
    • Status-Spalte

Optional: Button „Container laden“ fragt Sonic live per API und merged mit KnownContainers.

Teil C – Zertifikat: Erkennen & Verifizieren (Schritt für Schritt)

Hier geht es nur um die lokale Datei. Es wird nichts auf den ESB geschrieben und kein TLS zum Server aufgebaut.

C1. Benutzer wählt Datei

  1. Klick auf Dateiauswahl in der UI.
  2. OpenFileDialog filtert: .cer, .crt, .pem, .pfx.
  3. Abbruch → nichts ändert sich.
  4. Dateiendung wird geprüft (IsSupportedCertificateFile).
  5. Unbekanntes Format → Warnung, Ende.

C2. Datei lesen

  1. Aufruf TryReadSelectedCertificate(pfad).
  2. Intern: X509Certificate2 laden.
  3. PFX-Sonderfall:
    • Zuerst Versuch ohne Passwort.
    • Bei CryptographicException → Passwort-Dialog.
    • Falsches Passwort → Fehlermeldung, kein Zertifikat geladen.
  4. Andere Fehler (Datei kaputt, kein X.509) → Fehlermeldung.

C3. Was aus dem Zertifikat extrahiert wird

Feld Quelle Anzeige
Subject GetNameInfo(SimpleName) bzw. Subject „Ausgestellt für“
Issuer Issuer-SimpleName bzw. Issuer „Ausgestellt von“
Gültig von / bis NotBefore / NotAfter Datum
Fingerprint SHA-256 Hash, mit : formatiert z. B. AB:CD:…
Gültigkeitsstatus now zwischen NotBefore und NotAfter? grün GÜLTIG / rot UNGÜLTIG

C4. Was „Verifizierung“ hier genau heißt

Prüfung Passiert? Bedeutung
Datei lesbar als X.509 ja Format/Inhalt ok
Zeitlich gültig ja nicht abgelaufen / noch nicht gültig
Fingerprint anzeigen ja manueller Abgleich möglich
Signaturkette gegen Windows-CA nein nicht implementiert
Datei auf ESB kopieren nein Deploy aus
TLS-Handshake zum Live-System + Fingerprint vergleichen nein TLS-Probe aus

Erklärsatz:

Wir verifizieren das Zertifikat als Datei auf dem PC (lesbar + Gültigkeitszeitraum + Fingerprint).
Wir verifizieren nicht, dass genau dieses Zertifikat schon am laufenden ESB hängt.
Der Neustart ist davon getrennt.

C5. UI nach erfolgreichem Laden

  1. Pfad steht im Textfeld.
  2. Metadaten-Karte wird gefüllt.
  3. Statuszeile: „Zertifikat ausgewählt: …“.
  4. Sidebar-Schritt kann auf „Ziele“ springen.
  5. Neustart braucht das Zertifikat nicht zwingend – der Neustart hängt am Container, nicht an der Datei.

Teil D – Vor dem Neustart (Preflight)

D1. Benutzer hakt Ziel(e) an

Im Grid: Checkbox „Selected“ setzen.

D2. Button „ESB neu starten“

  1. GetSelectedTargets() sammelt alle angehakten Zeilen.
  2. ValidateRestartOnly prüft für jedes Ziel:
    • ContainerName nicht leer
    • SonicConnectionName nicht leer
  3. Fehler → Dialog „Neustart blockiert“ mit Liste der Probleme.
  4. OK → Bestätigungsdialog (Containername, Hinweis auf Management API).
  5. Nein → Abbruch. Ja → Neustart startet.

Teil E – Neustart Gesamtablauf (C#-Seite)

Alles von hier läuft ohne Zertifikatskopieren.

Form1.RunRestartOnlyAsync
  → DeploymentOrchestrator.RestartOnlyAsync
      → für jedes Ziel:
          RestartExecutor.ExecuteAsync
            → SonicManagementClient.RestartContainerAsync
                → SonicMfApiExecutor.RestartAsync
                    → java SonicMfContainerTool restart …

E1. Orchestrator

Pro Ziel:

  1. Status im Grid: „Neustart…“
  2. RestartExecutor.ExecuteAsync(target)
  3. Ergebnis + Detail in Logdatei unter Logs\
  4. Status im Grid aktualisieren
  5. Am Ende: Erfolgs-/Fehlerdialog mit Tool-Ausgabe

E2. RestartExecutor

  1. Liest target.ContainerName (z. B. ct-ZADBService).
  2. Sucht in appsettings die SonicConnection mit Name == SonicConnectionName (DE-Test).
  3. Fehlt die Verbindung → Fehler „Sonic-Verbindung nicht gefunden“.
  4. Sonst: new SonicManagementClient(connection) und RestartContainerAsync(containerName).

E3. SonicManagementClient

Schlanke Fassade, nur MfApi:

  1. Ruft _mfApi.RestartAsync(containerName) auf.
  2. Bei Erfolg: wartet PostRestartDelaySeconds (z. B. 20 s), damit der Container Zeit zum Hochfahren hat.
  3. Liefert Status-Text + komplette Java-Ausgabe zurück.
  4. Bei Fehler: Fehlermeldung + Output für den Dialog.

Teil F – SonicMfApiExecutor: Java vorbereiten und starten

Das ist die Brücke von .NET zu Sonic.

F1. Java finden

Reihenfolge grob:

  1. JavaPath aus appsettings (bevorzugt)
  2. JavaHome
  3. Umgebungsvariablen / PATH / Registry / unter SonicHome

Bedingung: Runtime muss Java 8+ können (Class-File major ≥ 52).
Zu alte Sonic-JREs (6/7) werden übersprungen.

F2. Classpath bauen (Sonic-JARs)

  1. MfClientLibPath (z. B. C:\DEV\MQ10.0\lib) oder Suche unter SonicHome.
  2. Es müssen echte Client-JARs da sein, u. a.:
    • mgmt_client.jar
    • mfcontext.jar
    • sonic_Client.jar
  3. Alle *.jar im Lib-Ordner werden explizit in den Classpath geschrieben (kein fragiles lib\* mit kaputten Quotes).
  4. Das Tool-Verzeichnis Tools\ kommt vorne in den Classpath, damit die richtige SonicMfContainerTool.class geladen wird.

F3. Java-Tool laden

  1. Bevorzugt vorcompilierte Tools\SonicMfContainerTool.class (Java 8, major 52).
  2. Alte/zu kleine Class-Dateien werden verworfen.
  3. Temp-Cache alter Compilate wird gelöscht.
  4. Falls nötig: aus .java mit javac --release 8 neu bauen.

F4. Prozess starten

Ungefähr:

"C:\...\java.exe"
  -cp "C:\...\Tools;C:\DEV\MQ10.0\lib\mgmt_client.jar;...;C:\DEV\MQ10.0\lib\mfcontext.jar;..."
  SonicMfContainerTool
  restart
  --domain proalpha-test
  --url tcp://dekun-painwbdet:13070
  --user Administrator
  --container ct-ZADBService
  --timeout 120

Wichtig:

  • Argumente über ProcessStartInfo.ArgumentList (keine doppelten Anführungszeichen).
  • Passwort über Umgebung ESB_SONIC_PASSWORD, nicht in der sichtbaren Kommandozeile.
  • stdout/stderr werden gelesen und an die UI zurückgegeben.

F5. Erfolgsauswertung in C#

Neustart gilt nur als Erfolg, wenn die Ausgabe enthält:

OK:RestartInvoked

Sonst: Fehlerdialog mit kompletter Tool-Ausgabe.

Teil G – Die Sonic Management Application API (Java-Tool)

Hier passiert der eigentliche „API-Call“ – nicht REST, sondern JMS/JMX Management Framework.

Offizielle Produktwelt (Aurea CX Messenger / Sonic):

  • Index: doc-10.0.10/CXMessenger_2017_R3.htm
  • Eintrag: Management Application API Reference (Docs2017/api/mgmt_api/)

Das ist dieselbe API-Familie, die die SMC für Restart nutzt.

G1. Warum „API“ hier kompliziert klingt

Die Sonic-Produkt-API enthält sehr viele Bereiche:

  • Broker / Queues / Topics
  • ESB-Services
  • Metrics / Notifications
  • Directory / Config
  • Agent Lifecycle

Für unseren Neustart brauchen wir nur einen schmalen Teil:

  1. Verbinden zum Domain Manager
  2. Agent-ObjectName ansprechen
  3. Lifecycle: stop/restart

Der Rest der JARs ist Produktumfang – nicht „unsere App-API mit 100 Features“.

G2. Schritt 1 – Tool startet

Ausgabe:

INFO:ToolVersion=2026-07-24c-mbean-stop

Wenn diese Zeile fehlt → oft noch eine alte .class im Einsatz.

G3. Schritt 2 – Argumente parsen

Pflicht:

  • Befehl: ping | list | restart
  • --domain
  • --url
  • --user
  • bei restart: --container
  • Passwort: --password oder ESB_SONIC_PASSWORD

G4. Schritt 3 – Connect (der eigentliche API-Login)

Java (vereinfacht, per Reflection):

Hashtable env:
  ConnectionURLs  = tcp://dekun-painwbdet:13070
  DefaultUser     = Administrator
  DefaultPassword = ***

JMSConnectorAddress address = new JMSConnectorAddress(env)
JMSConnectorClient connector = new JMSConnectorClient()
connector.connect(address, timeout)

Klassen kommen aus den Sonic-JARs:

  • com.sonicsw.mf.jmx.client.JMSConnectorAddress
  • com.sonicsw.mf.jmx.client.JMSConnectorClient

Ausgabe bei Erfolg:

INFO:Connected url=tcp://dekun-painwbdet:13070 user=Administrator

Das entspricht dem SMC-Login gegen denselben Domain Manager.

G5. Schritt 4 – Ziel-Agent bestimmen

ObjectName:

proalpha-test.ct-ZADBService:ID=AGENT

Muster:

{DomainName}.{ContainerName}:ID=AGENT

Optional: per queryNames nach vorhandenen Agenten suchen; wenn das scheitert, Preferred-Name verwenden.

G6. Schritt 5 – Lifecycle (Neustart) – drei Wege nacheinander

Weg 1 – MBean invoke (bevorzugt remote)

connector.invoke(objectName, "stop", [], [])
// oder "restart", "shutdown"

Warum zuerst stop?

  • Remote-Clients sind oft „unbounded“.
  • IAgentProxy.restart() wirft dann häufig:
    Operation unsupported for unbounded client connector
  • SMC-Restart wirkt für den Operator oft wie: Stop + automatischer Relaunch durch Launch Daemon / Host Manager.

Erfolg:

OK:RestartInvoked method=MBean.stop container=ct-ZADBService domain=proalpha-test

Weg 2 – Typisierter Proxy

IAgentProxy agent = MFProxyFactory.createAgentProxy(connector, objectName)
agent.stop() / agent.restart() / agent.shutdown()

Schön dokumentiert, remote oft eingeschränkt (unbounded).

Weg 3 – DomainManager / Manager-MBeans

Suche nach Operationen wie:

  • restartContainer(containerName)
  • stopContainer(containerName)

Fallback, falls Agent-direkt nicht klappt.

G7. Schritt 6 – Disconnect

connector.disconnect() im finally.

G8. Befehle des Tools im Überblick

Befehl Zweck
ping Verbindungstest + Agenten zählen
list Containernamen der Domain ausgeben
restart Lifecycle auf einem Container

Teil H – Komplette Kette als nummerierte Liste

So kannst du es jemandem erzählen:

Zertifikat

  1. App starten
  2. Zertifikatsdatei wählen
  3. Datei als X.509 lesen (PFX ggf. mit Passwort)
  4. Subject, Issuer, Fingerprint, Gültigkeit anzeigen
  5. Lokal „verifiziert“ = lesbar + im Gültigkeitszeitraum

Neustart

  1. Ziel im Grid anhaken (ct-ZADBService / Verbindung DE-Test)
  2. „ESB neu starten“ → Preflight → Bestätigung
  3. C# findet Sonic-Verbindung in appsettings
  4. C# findet Java 8+ und baut Classpath aus C:\DEV\MQ10.0\lib
  5. C# startet SonicMfContainerTool restart …
  6. Java verbindet per Management API an tcp://…:13070
  7. Java adressiert proalpha-test.ct-ZADBService:ID=AGENT
  8. Java ruft Stop/Restart per MBean (Fallback Proxy/Manager)
  9. Java schreibt OK:RestartInvoked
  10. C# wartet PostRestartDelaySeconds
  11. UI zeigt Erfolg/Fehler + Logausgabe
  12. Optional in SMC prüfen: Uptime/Status des Containers

Teil I – Konfiguration im Detail

I1. appsettings.json (Sonic-Block)

Feld Rolle
Name Alias, von Zielen referenziert (DE-Test)
DomainName Sonic-Domain
ConnectionUrl Domain-Manager-URL (wie SMC)
Username / Password SMC-Login
SonicHome Installationsroot
MfClientLibPath Ordner mit Client-JARs
JavaPath / JavaHome Java 8+
KnownContainers Fallback-Liste, z. B. ct-ZADBService
TimeoutSeconds Timeout Java/API
PostRestartDelaySeconds Wartezeit nach erfolgreichem Invoke

Felder wie WinRm*, Container*Path, ManagementHttpPort können noch in der JSON stehen, werden vom schlanken MfApi-Client nicht mehr genutzt.

I2. Container-Liste

Kein separates Sample-JSON. Container stehen in:

"KnownContainers": [ "ct-ZADBService" ]

Live-Erweiterung über UI-Button „Container laden“.

Teil J – Dateien und Verantwortlichkeiten

Datei Verantwortung
Form1.cs UI, Zertifikat lesen, Neustart-Button, Dialoge
DeploymentOrchestrator.cs Neustart über alle gewählten Ziele
PreflightValidator.cs Pflichtfelder prüfen
RestartExecutor.cs Ziel → SonicConnection
SonicManagementClient.cs Fassade MfApi
SonicMfApiExecutor.cs Java/Classpath/Prozess
Tools/SonicMfContainerTool.java Connect + Lifecycle über Sonic-API
appsettings.json Laufzeitkonfiguration inkl. KnownContainers
Logs\ Laufprotokolle

Teil K – Erfolgs- und Fehlerbilder

K1. Gesunde Ausgabe (Auszug)

INFO:ToolVersion=2026-07-24c-mbean-stop
INFO:Connected url=tcp://dekun-painwbdet:13070 user=Administrator
INFO:PreferredObjectName=proalpha-test.ct-ZADBService:ID=AGENT
INFO:Trying MBean.invoke(stop) on …
OK:RestartInvoked method=MBean.stop container=ct-ZADBService domain=proalpha-test

K2. Häufige Fehler

Meldung Bedeutung Typische Lösung
ClassNotFoundException: JMSConnectorAddress JARs fehlen / Classpath kaputt MfClientLibPath, neuer Build
UnsupportedClassVersionError Java-Version mismatch Tool als Java 8 + Runtime Java 8+
Operation unsupported for unbounded… Proxy-Restart remote gesperrt MBean-stop-Pfad / aktuelles Tool
Kein ToolVersion= Alte Class-Datei Neu bauen, richtigen bin-Ordner starten
Container DE-Test Alias statt Kurzname ct-ZADBService
stopcontainer.bat fehlt SMC-only normal – MfApi nutzen

Teil L – Wie man es jemandem erklärt (Kurzskript)

  1. UI: Zertifikat laden → wir sehen Subject/Fingerprint/Gültigkeit. Das ist lokale Dateiprüfung.
  2. Neustart: Wir starten denselben Management-Weg wie die SMC, nicht per Batch-Datei und nicht per FTP.
  3. Technik: C# orchestriert; ein kleines Java-Tool + Sonic-Client-JARs sprechen mit dem Domain Manager.
  4. API: Sonic Management Application API (JMS/JMX). Sehr große Produkt-API, wir nutzen nur Connect + Agent-Stop/Restart.
  5. Haken: Remote heißt „unbounded“ – deshalb oft stop per MBean statt IAgentProxy.restart().
  6. Ergebnis: Container ct-ZADBService in Domain proalpha-test wird neu gestartet; danach in der SMC Status/Uptime prüfen.

Teil M – Abgrenzung: Was ist „unsere API“ vs. Sonic-API?

Ebene Beschreibung
Unsere App WinForms + C#-Services. Kein öffentlicher REST-Endpoint.
Unser Java-Tool Dünner Adapter (ping/list/restart) mit Fallbacks.
Sonic Management Application API Produkt-API in den JARs; offiziell dokumentiert; SMC nutzt dieselbe Familie.
Unnötig für den Use-Case MQ Messaging API, ESB API, Metrics, XApi, WinRM, Bat-Scripts, TLS-Probe – solange nur „Datei prüfen + Neustart“ gefragt ist.

Ende der kompletten Erklärung. Bei Abweichungen gilt der Code im Projekt (Branch mit MfApi-Neustart).

Reference in New Issue View Git Blame Copy Permalink