Handbuch

Updates und Downgrades

Einleitung

Um eine angenehme und unkomplizierte Aktualisierung der Version sicher zu stellen, sollte im Normalfall, jedes neu erschienene Update installiert und so wenig wie möglich bis kaum überspringen werden.
Auch sollten im verteilten Betrieb Downgrades sowie ein Mischbetrieb von Versionen vermieden werden.

Falls diese Punkte nicht eingehalten werden, können Fehler in speziellen Situationen für bestimmte Versionen auftreten, die man manuell beheben muss.

Dieses Dokument beschreibt welche Fehler in diesen speziellen Situationen auftreten können und wie man diese beheben kann.

Updates

Hinweis:
Vor einem Update oder Downgrade muss eine vollständige Sicherung durchgeführt werden. Eine Anleitung dazu finden Sie hier.

Falls auf dem Host manuell eingerichtete Cron-Jobs (nicht empfohlen) vorhanden sind, sollten Kunden vor dem Update auf 21.3 den Mindbreeze Support kontaktieren.

Update von Versionen vor 21.3 auf Version 22.3 oder neuer

Ein direktes Update wird nicht unterstützt. Bitte aktualisieren Sie zuerst auf die Version 21.3 und dann erst auf 22.3 oder neuer.

Wenn das Update auf von einer Version vor 21.3 bereits ausgeführt wurde und der inspire Container nicht funktioniert, führen Sie bitte die folgenden Befehle aus:

docker exec -it inspire-system-loader inspire-systemloader update

docker exec -it inspire-system-manager inspire-systemmanager image update CoreOS

reboot

Update von Version 18.0 oder älter auf Version 21.3 oder neuer

Falls Mindbreeze InSpire noch mit Version 18.0 oder älter betrieben wird, und Sie auf Version 21.3 oder neuer updaten möchten, können Sie nicht direkt auf 21.3 updaten, sondern müssen zuerst auf 18.1 updaten und anschließend auf 21.3 oder neuer.

Update auf Version 20.4 oder neuer

Falls Sie beim Update folgende Fehlermeldung erhalten:

• verify.sh: ERROR: keycloak update script failed

Kann eine mögliche Ursache dieses Fehlers in fehlende oder fehlerhafte Konfigurationsdateien liegen.

Prüfen Sie daher die Datei /var/data/keycloak/config/keycloak_h2_db_name. Mit Version 20.3 oder älter soll die Datei den Inhalt keycloak_4_6_0 haben. Mit Version 20.4 oder neuer soll die Datei den Inhalt keycloak_10_0_2 haben.

Falls die Datei fehlt oder der Inhalt nicht übereinstimmt, korrigieren Sie dies und starten Sie das Update erneut. Der Fehler sollte nun behoben sein.

Erstmaliges Update auf Version 21.2 HF2 oder neuer

Falls Sie sich in einer älteren Version als 21.2 HF2 befinden und zusätzlich folgende zwei Punkte für Ihre Umgebung zutreffen:

• Verteilter Betrieb (Producer/Consumer)
• Sequenzielles Update der Nodes, (anstatt gleichzeitigen Updates) bei dem für kurze Zeit ältere und neuere Versionen gleichzeitig betrieben werden.

Führen Sie bitte ein Update auf Version 21.3 oder neuer durch.

Falls noch zusätzlich die Benachrichtigungen in mindestens einem Client Service aktiviert sind, melden Sie sich bitte beim Support, um eine reibungslose Aktualisierung zu gewährleisten.

Hinweis: Bei einem Update auf eine 21.2 HF Version ist in diesem Fall ein sequenzielles Update nicht ohne weiteres möglich.

Update von 22.2 HF2

Bei Updates von Version 22.2 HF2 auf eine beliebige andere Version kann folgende Fehlermeldung im Update-Log aufscheinen:

Could not execute update with exception:  out of pty devices

Um das Update erfolgreich starten zu können, muss in diesem Fall entwender:

• Die Appliance neu gestartet werden oder
• docker restart update-center auf der Kommandozeile ausgeführt werden

Docker exec with 22.2 HF2

Aufgrund desselben Problems kann es zu folgender Fehlermeldung beim Auführen von docker exec kommen:

OCI runtime exec failed: exec failed: unable to start container process: open /dev/pts/1: operation not permitted: unknown

Folgende Möglichkeiten sind verfügbar:

• Update auf mindestens 22.2 HF3
• docker restart CONTAINERNAME
• auf den inspire Container kann auch mittles ssh zugegriffen werden: ssh -T -i /var/data/default/config/sshkeys/mes/id_rsa mes@$(docker inspect inspire | jq .[].NetworkSettings.Networks.mindbreeze.IPAMConfig.IPv4Address -r)

Update mit individuellen Keycloak System Änderungen

Hinweis: Um Komplikationen beim Update zu vermeiden, wird es nicht empfohlen nicht persistierte Änderungen (z.B.: individuell hinzugefügte vertrauenswürdige SSL Zertifikate zum JVM-Keystore) im Keycloak-Container zu machen.

Im Keycloak-Container sind nur die Verzeichnisse /config, /opt/keycloak/data (vor Mindbreeze Inspire 23.3 /opt/jboss/keycloak/data) und /opt/keycloak/log (vor 23.3 /opt/jboss/keycloak/log) persistiert, jegliche Änderungen in anderen Verzeichnissen und Dateien gehen bei einem Update verloren und müssen manuell nachgezogen werden!

Wenn individuell vertrauenswürde SSL Zertifikate zum JVM-Keystore hinzugefügt wurden, um z.B. User Federation mit einem System, welches ein Self-Signed Zertifikat hat, zu ermöglichen, wird ein Update nicht möglich sein.

Um das Update zu ermöglichen müssen zuerst (vor dem Beginn des Updates) manuell alle User Federation Provider und Identity Provider, welche sich auf die hinzugefügten SSL Zertifikate verlassen, deaktiviert werden (Vergewissern Sie sich vor der Deaktivierung, dass Sie auch einen Admin-Benutzer haben, der in Keycloak gespeichert ist und nicht über die User Federation importiert wird - falls dies nicht der Fall ist, erstellen Sie einen). Dies kann man im MMC im Tab Setup > Credentials gemacht werden. Dazu einfach in den Tabs „User Federation“ und „Identity Providers“ alle nötigen Provider heraussuchen und in den Einstellungen deaktivieren.

Danach kann das Update erfolgen. Sobald das Update abgeschlossen ist, muss das Zertifikat im Keycloak Container wieder zum JVM-Keystore hinzugefügt werden. Dazu müssen folgende Befehle, im Keycloak Container, ausgeführt werden:

# <path_to_certificate> ist der Pfad zum Zertifikat – der Pfad muss also
# vom Container aus erreichbar sein

cp <path_to_certificate> /etc/pki/ca-trust/source/anchors

update-ca-trust extract

Danach muss der Docker Container neugestartet werden (docker restart keycloak) um die Änderungen im Keystore wahrzunehmen. Nach dem Neustart kann man wieder alle Provider aktivieren.

Downgrades

Hinweis:
Vor einem Update oder Downgrade muss eine vollständige Sicherung durchgeführt werden. Eine Anleitung dazu finden Sie hier.

Grundsätzlich unterscheidet man bei Downgrades zwischen zwei unterschiedlichen Fällen:

1. Downgrade nach Update:
   In der Vergangenheit wurde ein Update durchgeführt, beim Downgrade soll wieder auf die alte Version zurückgestiegen werden. Dies ist der Normalfall.
2. Downgrade ohne vorherige Version:
   Es soll auf eine alte Version zurückgestiegen werden, die noch nie auf der Appliance betrieben worden ist.

Einschränkungen für Keycloak-Daten beim Downgrade

Beim Downgrade auf einige ältere Versionen ist eine Beibehaltung aller Keycloak-Daten nicht möglich. Dies betrifft beispielsweise zusätzlich angelegte Clients, Synchronisierte Benutzer, angepasste User Role Mappings.

Das heißt, beispielweise werden bei einem Downgrade von 20.4 auf 20.3 nicht alle Keycloak-Daten beibehalten, wo hingegen bei einem Downgrade von 20.3 auf 20.2 die Keycloak-Daten beibehalten werden.
Das heißt falls ein Downgrade auf die genannten Versionen durchgeführt werden soll, müssen die Keycloak-Änderungen nach dem Downgrade manuell nachgetragen werden.

Die Keycloak-Daten sind unter anderem in Datenbank-Dateien im Verzeichnis /var/data/keycloak/data/data/ gespeichert. Die Datenbank-Dateien beinhalten die Keycloak-Version im Dateinamen.

• Mindbreeze InSpire 19.0 bis inklusive Version 20.3 verwendet Keycloak 4.6
• Mindbreeze InSpire 20.4 verwendet Keycloak 10.0
• Mindbreeze InSpire 20.5 verwendet Keycloak 11.0
• Mindbreeze InSpire 21.2 verwendet Keycloak 14.0
• Mindbreeze InSpire 21.3 verwendet Keycloak 15.1.1
• Mindbreeze InSpire 22.2 verwendet Keycloak 18.0
• Mindbreeze InSpire 23.3 verwendet Keycloak 21.0.2
• Mindbreeze InSpire 23.6 verwendet Keycloak 22.0.1
• Mindbreeze InSpire 24.1 verwendet Keycloak 23.0.4
• Mindbreeze InSpire 24.5 verwendet Keycloak 25.0.1

Folgende Abschnitte beschreiben die Schritte, die in den jeweiligen Downgrade-Fällen zu tun sind:

Keycloak: Downgrade nach Update

1. Vor dem Downgrade, stellen Sie sicher, dass im Verzeichnis /var/data/keycloak/data/data/ alte Datenbankdateien vorhanden sind.
   
   z.B auf einer InSpire 20.4:
   # ll  /var/data/keycloak/data/data/
   total 2076
   drwxr-xr-x 2 1000 1000       6 Sep  8 13:43 content
   drwxr-xr-x 2 1000 1000      26 Sep  8 13:43 kernel
   -rw-r--r-- 1 1000 1000     146 Sep 16 16:57 keycloak_10_0_2.lock.db
   -rw-r--r-- 1 1000 1000 1302528 Sep 17 10:16 keycloak_10_0_2.mv.db
   -rw-r--r-- 1 1000 1000    7924 Sep 16 16:57 keycloak_10_0_2.trace.db
   -rw-r--r-- 1 1000 1000     146 Sep 14 10:50 keycloak_4_6_0.lock.db
   -rw-r--r-- 1 1000 1000  798720 Sep 14 11:19 keycloak_4_6_0.mv.db
   -rw-r--r-- 1 1000 1000    4507 Sep 14 10:46 keycloak_4_6_0.trace.db
   drwxr-xr-x 2 1000 1000       6 Sep 14 10:44 timer-service-data
   drwxr-xr-x 3 1000 1000      35 Sep 14 11:19 tx-object-store
   
   In dieser Auflistung erkennen Sie, dass eine keycloak_4_6_0.mv.db Datenbankdatei existiert, die von der vorherigen, alten InSpire Version stammt. Falls Sie hier keine ältere Datenbank-Datei finden können, befolgen Sie stattdessen bitte den Abschnitt Keycloak: Downgrade ohne vorherige Version.
2. Installieren Sie im MMC unter „Update“ die alte InSpire Version. Damit wird wieder die alte Keycloak Datenbankdatei verwendet. Alle Keycloak-Daten sind dann wieder auf dem Stand vor dem letzten InSpire Update.
   
   Hinweis: falls Sie seit dem letzten InSpire Update Ihr Passwort geändert haben, müssen Sie nach dem Downgrade wieder das alte Passwort verwenden. Sie müssen auch alle Anpassungen, die Sie in Keycloak seit dem letzten InSpire Update durchgeführt haben, wenn Notwendig, manuell nachziehen.
3. Sie verwenden nun wieder die alte Version von InSpire mit der alten Version von Keycloak. Damit Sie in Zukunft Problemlos wieder updaten können, müssen Sie noch folgende Schritte durchführen:
   
   Da nun die alte Datenbankdateien verwenden werden, müssen Sie die Datenbankdateien mit der neuen Version löschen, um ein divergieren der Daten zu verhindern.
   # ll /var/data/keycloak/data/data/
   total 2080
   drwxr-xr-x 2 1000 1000       6 Sep  8 13:43 content
   drwxr-xr-x 2 1000 1000      26 Sep  8 13:43 kernel
   -rw-r--r-- 1 1000 1000     146 Sep 16 16:57 keycloak_10_0_2.lock.db
   -rw-r--r-- 1 1000 1000 1302528 Sep 17 10:16 keycloak_10_0_2.mv.db
   -rw-r--r-- 1 1000 1000    7924 Sep 16 16:57 keycloak_10_0_2.trace.db
   -rw-r--r-- 1 1000 1000     146 Sep 17 11:15 keycloak_4_6_0.lock.db
   -rw-r--r-- 1 1000 1000  798720 Sep 17 11:15 keycloak_4_6_0.mv.db
   -rw-r--r-- 1 1000 1000    8469 Sep 17 11:15 keycloak_4_6_0.trace.db
   drwxr-xr-x 2 1000 1000       6 Sep 14 10:44 timer-service-data
   drwxr-xr-x 3 1000 1000      35 Sep 14 11:19 tx-object-store
   
   In diesem Fall müssen Sie die Dateien keycloak_10_0_2.lock.db, keycloak_10_0_2.mv.db und keycloak_10_0_2.trace.db löschen.
   
   Anschließend überprüfen Sie den Inhalt folgender Dateien:
   # cat /var/data/keycloak/config/keycloak_version
   4_6_0
   # cat /var/data/keycloak/config/keycloak_h2_db_name
   keycloak_10_0_2
   
   Der Inhalt der Datei /var/data/keycloak/config/keycloak_h2_db_name muss geändert werden. Ändern Sie die Versionsnummer auf dieselbe (alte) Version, die in der Datei /var/data/keycloak/config/keycloak_version vorhanden ist.
   
   Überprüfen Sie anschließend den Inhalt folgender Dateien, die Versionen sollten nun (mit der alten Version) übereinstimmen:
   # cat  /var/data/keycloak/config/keycloak_version
   4_6_0
   # cat  /var/data/keycloak/config/keycloak_h2_db_name
   keycloak_4_6_0
4. Damit ist das Downgrade aus Sicht von Keycloak abgeschlossen.

Keycloak: Downgrade ohne vorherige Version

1. In diesem Fall existiert keine Datenbankdatei, die nach dem Downgrade verwendet werden kann. Prüfen Sie das Verzeichnis /var/data/keycloak/data/data/ und stellen Sie sicher, dass keine älteren Datenbankdateien vorhanden sind.
   # ll  -a /var/data/keycloak/data/data/
   total 796
   drwxr-xr-x 6 1000 root    173 Sep 17 11:32 .
   drwxr-xr-x 4 1000 root     32 Sep 14 11:00 ..
   drwxr-xr-x 2 1000 1000      6 Sep  8 13:43 content
   drwxr-xr-x 2 1000 1000     26 Sep  8 13:43 kernel
   -rw-r--r-- 1 1000 1000    146 Sep 17 11:15 keycloak_10_0_2.lock.db
   -rw-r--r-- 1 1000 1000 798720 Sep 17 11:15 keycloak_10_0_2.mv.db
   -rw-r--r-- 1 1000 1000   8469 Sep 17 11:15 keycloak_10_0_2.trace.db
   drwxr-xr-x 2 1000 1000      6 Sep 14 10:44 timer-service-data
   drwxr-xr-x 3 1000 1000     35 Sep 14 11:19 tx-object-store
   
   Falls hier doch Datenbankdateien älterer Versionen aufgelistet sind, fahren Sie stattdessen mit dem Abschnitt Keycloak: Downgrade nach Update fort.
2. Installieren Sie im MMC unter „Update“ die alte InSpire Version und aktivieren Sie die Option „Force Update on Recoverable Verification Errors“. Nach dem Downgrade ist keine Anmeldung im MMC möglich, da sich der Keycloak-Container, welcher noch nicht downgraded ist, in einem fehlerhaften Zustand befindet. Führen Sie die folgenden Befehle aus, um Keycloak auf die InSpire Werkseinstellungen zurückzusetzen und zu downgraden:
   
3. inspire-system-manager reset keycloak -f
   
   Sie können mit dem Kommando journalctl -f den Fortschritt beobachten. Mit dem Log-Eintrag „Initial Config Successful“ ist die Operation abgeschlossen. Starten Sie anschließend alle Container neu mit folgendem Kommando: systemctl restart docker
   
   Anschließend müssen Sie alle Anpassungen, die Sie in Keycloak in der neuen InSpire Version durchgeführt haben, wenn notwendig, manuell nachziehen.

Damit ist auch in diesem Fall das Downgrade aus Sicht von Keycloak abgeschlossen.

Downgrade von Version 21.3 auf 21.2 oder älter

Nach einem Downgrade von Version 21.3 auf 21.2 können Credentials nicht mehr geladen werden, es werden entsprechende Fehlermeldungen im Log angezeigt und betroffene Services starten nicht mehr. Beispiel für diesen Fehler im Log:

/opt/mindbreeze/bin/mesmaster.exe[245]: 2021-12-13 17:53:19,109 [Threadpool worker] ERROR: Failed to load build-in credentials store file /etc/mindbreeze/builtincredentials.proto

Um dieses Problem zu beheben müssen folgende Schritte auf der Kommandozeile durchgeführt werden:

1. Wechseln Sie in den inspire container (In einem verteilten Betrieb ist dies der Master-Node):
   docker exec -it inspire bash
2. Löschen Sie die betroffene Datei:
   rm /etc/mindbreeze/builtincredentials.proto
3. Starten Sie die betroffenen Services neu:
   systemctl restart mesinspireadminapi
   
   Damit wird die Datei im korrekten Format neu generiert und anschließend werden die betroffenen Services automatisch neu gestartet. (In einem verteilten Betrieb kann es ein paar Minuten dauern, bis die Änderungen auf alle Nodes synchronisiert sind)