154 lines
8.2 KiB
Markdown
154 lines
8.2 KiB
Markdown
# 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.
|