Files
syno-scripts/EJBCA
2026-09-25 21:14:21 +02:00
..
2026-09-25 21:14:21 +02:00
2026-09-24 16:39:49 +02:00
2026-09-24 16:39:49 +02:00
2026-09-24 16:39:49 +02:00

EJBCA Issuing: automatisierte Migration von H2 nach PostgreSQL

Start

Die Datei migrate_ejbca_issuing.py auf den Docker-Host nach /root/migrate_ejbca_issuing.py hochladen. Nicht den Quelltext aus einem Chat in das Terminal kopieren. Auf dem Docker-Host als root ausführen:

python3 /root/migrate_ejbca_issuing.py

Die Issuing-CA wird nach den Vorprüfungen gestoppt und bleibt bis zum anschließenden Portainer-Update außer Betrieb. Die Root-CA wird weder gestoppt noch verändert. Der Lauf kann mehrere Minuten dauern. Keine zweite Instanz des Skripts starten.

Voraussetzungen und festgelegter Umfang

  • Linux-Docker-Host mit Python ab 3.9; keine zusätzlichen Python-Pakete nötig.
  • Quelle: Container ejbca_issuing, ein Volume ejbca_issuing_data unter /mnt/persistent, Netzwerk cert-net, keine veröffentlichten Host-Ports.
  • Das bereits geprüfte EJBCA-Image wird über seinen Digest festgelegt: keyfactor/ejbca-ce@sha256:183b86af44b9b13e7cc8912c868f635aeb8dba6bf056ccbd4683b17626964d0a.
  • Die konfigurierte H2-Datei muss direkt unter /mnt/persistent liegen.
  • Der H2-Treiber muss dem bereits geprüften H2 2.2.224 entsprechen.
  • Das Skript ist für die gezeigte Konfiguration mit Software-CryptoTokens gebaut. Bei inaktiven Tokens, HSMs, unbekannten Datentypen, anderen Mounts oder nicht unterstützten Containeroptionen bricht es ab.
  • Es benötigt ausreichend freien Speicher für die Volumesicherung, zwei Anwendungskopien, H2-Arbeitskopien und zwei PostgreSQL-Volumes.
  • PostgreSQL 17 und Java 17 werden bei Bedarf vor der Ausfallzeit heruntergeladen.

Bereits vorhandene Issuing-Sicherung

Vor dem Stoppen prüft das Skript die im Chat bestätigten Sicherungen:

  • /root/ejbca-backup/ejbca_issuing.tar.gz
  • /mnt/HEIMLAN/001-Zertifikate/EJBCA-Backup/2026-09-24/ejbca_issuing.tar.gz

Mindestens eine Kopie muss erreichbar sein. Jede vorhandene Kopie wird anhand der damaligen SHA-256-Prüfsummen des Archivs und der enthaltenen H2-Datei geprüft. Bei einer Abweichung bricht das Skript vor dem Stoppen ab. Die Archive werden ausschließlich gelesen, niemals überschrieben oder entpackt.

Zusätzlich wird nach dem Stoppen ein aktueller Stand gesichert und für die Migration verwendet. Issuing lief seit der alten Sicherung weiter; deshalb wird kein älterer Datenstand zurückgespielt. Ein Unterschied der H2-Dateien wird protokolliert und ist kein Fehler. Er beweist allein keine fachliche Datenänderung. existing-backups.json und backup-comparison.json dokumentieren die Prüfung im neuen Arbeitsverzeichnis.

Ablauf

  1. Containerkonfiguration und Image prüfen, JDBC-Treiber und SQL-Skripte aus dem vorhandenen Issuing-Container extrahieren, Java-Helfer kompilieren.
  2. Issuing stoppen, vollständiges Originalvolume als TAR sichern, H2-Datei separat kopieren und beide Kopien über SHA-256 vergleichen.
  3. H2 Recover ausschließlich auf einer Arbeitskopie ausführen. Alle im Dump gefundenen binären Hilfsspalten von VARCHAR auf VARBINARY korrigieren. Der ursprüngliche Dump bleibt erhalten. Ein neues temporäres H2-Passwort wird ausschließlich für die Rekonstruktion verwendet.
  4. Neue H2-Datenbank erzeugen. Alle nichtleeren Tabellenzahlen mit den Recover-INSERTs und alle Binärwerte einschließlich ihrer Längen und SHA-256-Werte mit den Hexliteralen im ursprünglichen Dump vergleichen.
  5. Neue Testdatenbank in einem internen Netzwerk erstellen. Den aus dem Root-Verfahren abgeleiteten JDBC-Helper ausführen. Tabellen-/Zeilenzahlen werden aus der Issuing-Quelle ermittelt. Spaltenzuordnung, Datentypen, Fremdschlüssel, Leerheit, vollständige Werte und Rowcounts werden geprüft. Inserts erfolgen in einer Transaktion. Der Helper kennt ausschließlich ejbca_issuing_migration_test_db.
  6. Alle 44 PostgreSQL-Indizes vor dem ersten EJBCA-Teststart anlegen. Die vier DELETE-Befehle im Originalskript werden durch eine Abbruchprüfung ersetzt.
  7. Testanwendung mit kopiertem Volume, erhaltenen Verschlüsselungs-/CLI-Einstellungen, ohne veröffentlichte Ports und in einem internen Netzwerk starten. Bereitschaft, Fehlerlogs, CA-Liste, Tokenstatus und alle erkannten Software-Schlüsselpaare prüfen. Danach Testanwendung stoppen.
  8. Ausschließlich das vom Skript neu angelegte Testschema erneut aufbauen und die ursprünglichen Issuing-Daten plus Indizes importieren. Somit werden keine beim Teststart erzeugten Zertifikate oder anderen Änderungen übernommen.
  9. Sauberen Dump erstellen. Neue endgültige Datenbank ejbca_issuing_db in ejbca-issuing-db-net erstellen, Dump transaktional wiederherstellen und Tabellenzahlen, vollständige Zeilen-Digests sowie Indizes vergleichen.
  10. Eigenes dauerhaftes App-Volume aus dem gestoppten Original kopieren und die fertige Compose-Datei für den bestehenden Portainer-Stack erzeugen.

Das Skript exportiert keine privaten Schlüssel als separate Dateien und stellt keine Zertifikate per CLI aus. Der EJBCA-Teststart selbst kann ein Serverzertifikat in seiner isolierten Testdatenbank anlegen. Sicherungen und Datenbank-Dumps enthalten selbstverständlich vertrauliche CA-Daten.

Ergebnis

Am Ende zeigt das Skript das neu generierte Passwort für Issuing-PostgreSQL und die vollständige Compose-Konfiguration direkt im lokalen Terminal an. Dieses Passwort ist nicht das alte H2-Passwort, kein Root-CA-Passwort und kein CryptoToken-PIN. Vorhandene Schlüssel-/Verschlüsselungspasswörter werden nicht geändert. Die Compose-Datei enthält das neue DB-Passwort bereits; keine zusätzliche Portainer-Variable ist erforderlich.

Alle Dateien liegen in einem neuen, nur für root zugänglichen Verzeichnis:

/root/ejbca-issuing-migration/run-DATUM-UHRZEIT-ZUFALL/

Wichtige Dateien:

  • docker-compose.issuing.yml: fertige Konfiguration für den vorhandenen Portainer-Stack ejbca-issuing.
  • credentials.private.json: erzeugte H2-, Test- und endgültige DB-Zugangsdaten.
  • original.inspect.json, original-volume.tar, original.mv.db und original.sha256: Originalkonfiguration und geprüfte Sicherungen.
  • recover/ejbcadb.h2.sql: ursprünglicher Recover-Dump.
  • restored/: binärsicher rekonstruierte H2-Quelle; SQL enthält ein temporäres Passwort.
  • source-inventory.tsv, migration.log, key-tests.log, report.json: Prüfresultate ohne vollständige Nutzdaten.
  • issuing-clean.dump und .sha256: sauberer Export vor Anwendungsstart.
  • verify-after-deploy.sh: Bereitschafts- und Schlüsseltests nach dem Deployment.
  • docker-compose.database-reference.yml: Dokumentation des bereits vom Skript gestarteten DB-Containers. Nicht als zusätzlichen Stack deployen, solange dieser Container existiert.

Das Skript ersetzt/deployt den bestehenden Issuing-Container nicht automatisch. Die endgültige PostgreSQL-Datenbank läuft bereits mit einem benannten Volume und Restart-Policy unless-stopped. Die Testanwendung ist gestoppt.

Portainer-Update und Abschluss

  1. Nach erfolgreichem Skriptende in Portainer den bestehenden Stack ejbca-issuing öffnen.
  2. Den Editorinhalt durch docker-compose.issuing.yml ersetzen.
  3. Stack aktualisieren. Das festgelegte Image bleibt die getestete Version.
  4. Nach etwa 90 Sekunden den erzeugten Prüfblock ausführen:
sh /root/ejbca-issuing-migration/run-DATUM-UHRZEIT-ZUFALL/verify-after-deploy.sh
  1. In der gewohnten Adminoberfläche Issuing-CA und Profile kontrollieren.
  2. Nach erfolgreichem Abschluss einen aktuellen PostgreSQL-Dump sichern und regelmäßige Datenbankbackups vorsehen. Alte H2-Sicherungen vorerst behalten.

Bestehende TLS-/Adminzugangseinstellungen werden übernommen. Insbesondere wird TLS_SETUP_ENABLED=simple, falls vorhanden, durch dieses Migrationsskript nicht auf Clientzertifikatsanmeldung umgestellt.

Bei einem Fehler

Das Skript bricht ab und stoppt seine eigene Testanwendung, soweit sie bereits angelegt wurde. Es löscht keine vorhandenen Container/Volumes automatisch. Nach begonnenen Arbeiten nicht blind erneut ausführen: vorhandene Zielnamen führen absichtlich zum Abbruch.

Die ursprüngliche Issuing-Compose-Konfiguration und das ursprüngliche H2-Volume bleiben unverändert. Die ursprüngliche Anwendung kann bereits gestoppt sein. Solange noch kein Portainer-Update erfolgt ist und niemand die Originalkonfiguration geändert hat, kann sie bei Bedarf mit docker start ejbca_issuing wieder auf dem alten H2-Stand laufen. Danach ist eine frühere Migrationskopie möglicherweise veraltet und darf nicht ohne neuen Abgleich eingesetzt werden.

Zur Diagnose zunächst nur die Abbruchmeldung und progress.log weitergeben. private-errors.log, test-start.private.log, JSON-Konfigurationen, SQL-Dumps und Compose-Dateien können Geheimnisse enthalten; nicht ungeschwärzt posten.

Prüfstatus dieses Lieferstands

Python-Syntax und lokale Tests für SQL-Lexer, Binärkorrektur, Abbruchfälle, Indexkonvertierung und Compose-Werte wurden geprüft. Der JDBC-Migrationscode ist aus dem auf deinem Host ausgeführten Root-Helper abgeleitet; das Original bleibt unverändert. Ein vollständiger Docker-/EJBCA-Durchlauf wurde in dieser Arbeitsumgebung nicht ausgeführt. Die Java-Helfer werden auf dem Docker-Host vor dem Stoppen der Issuing-Anwendung kompiliert.