This commit is contained in:
Madzone
2026-09-24 16:31:15 +02:00
parent dc08e3ec4f
commit 9da9ec58cc
4 changed files with 651 additions and 0 deletions
+153
View File
@@ -0,0 +1,153 @@
# 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:
```bash
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.
## 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:
```text
/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:
```bash
sh /root/ejbca-issuing-migration/run-DATUM-UHRZEIT-ZUFALL/verify-after-deploy.sh
```
5. In der gewohnten Adminoberfläche Issuing-CA und Profile kontrollieren.
6. 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.