Repository

Als Repository für die Content-Datenspeicherung wird in FirstSpirit Oracle Berkeley DB verwendet, aktuell in Version 7.
Dieses Repository wird in Form eines System-Moduls zur Verfügung gestellt (fs-berkeleydb7.fsm).

Backend: Hier wird angezeigt, welche Berkeley DB-Version für das betreffende Projekt verwendet wird. Aktuell handelt es sich um Version 7.x. Sollten zukünftig weitere Versionen zur Verfügung stehen, können sie über diese Klappliste ausgewählt werden.

Hinweis: Die Berkeley DB prüft als Sicherheitsmaßnahme zum Schutz vor Datenverlust den noch zur Verfügung stehenden Festplattenspeicher. Standardmäßig sind bei einem Wert unterhalb von 512 MebiBytes (entspricht ca. 536 MB) keine weiteren Speicheroperationen in der Berkeley-Datenbank mehr möglich (Fehlermeldung: Disk usage is not within je.maxDisk or je.freeDisk limits and write operations are prohibited.).

Der Wert für „Server beenden bei“ in den Globalen Server-Eigenschaften sollte daher nicht unterhalb von 512 MebiBytes liegen.

Hinweis für ältere FirstSpirit-Server: Ab FirstSpirit 2018-11 wird nur noch Berkeley DB in der Version 7 unterstützt. FirstSpirit-Server, die mit FirstSpirit 2018-06 oder niedriger neu installiert wurden, und Berkeley DB in einer Version <7 verwenden, müssen konvertiert werden, da Berkeley DB 7 ein anderes Datenformat verwendet als die zuvor mit FirstSpirit verwendeten Versionen 3 und 5. Wurden bestehende Daten nicht in das neue Berkeley DB 7-Format konvertiert, startet der Server mit FirstSpirit 2018-11 nicht mehr. Für eine komfortable Konvertierung steht das Kommandozeilenwerkzeug „BerkeleyUtil.jar“ zur Verfügung. Siehe dazu Abschnitt Konvertierung nach Berkeley DB 7.

Compressor: Über diese Klappliste kann bei Bedarf eine andere Kompression eingestellt werden. Kompression wirkt sich nicht nur auf den Speicherplatz aus, sondern auch auf die Zugriffsgeschwindigkeit.

• [keiner]: Es wird keine Kompression verwendet (empfohlene Standardeinstellung).
• Deflate: Algorithmus mit hoher Kompressionsrate
• LZ4: Algorithmus, der auf hohe Geschwindigkeit ausgelegt ist

Verschlüsselung

In diesem Bereich kann die Verschlüsselung der Repository-Inhalte (Inhalte, Strukturen, Medien) für ein Projekt konfiguriert werden. Hintergrundinformationen zur verschlüsselten Dateiablage siehe Verschlüsselte Dateiablage.

Voraussetzungen: Für die Konfiguration dieser Projekteinstellungen ist eine globale Server-Key-Datei notwendig (siehe Erstellen der Key-Datei). Der Pfad zur Key-Datei muss über den Parameter repository.encryption.keyFilePath innerhalb der Konfigurationsdatei fs-server.conf hinterlegt werden (Konfiguration siehe Bereich: Storage Engine Properties).

Hinweis zur Standard-Vorbelegung: Für neu angelegte und importierte Projekte können die Eingabefelder mit globalen Werten aus der Konfigurationsdatei fs-server.conf vorbelegt werden. So kann eine Verschlüsselung für ein neu angelegtes Projekt bereits aktiviert sein, weil der Parameter repository.encryption in der Konfigurationsdatei fs-server.conf den Wert 1 hat (siehe Bereich: Storage Engine Properties). Die Projekteinstellungen können unabhängig von den global gesetzten Werten konfiguriert werden. Die Verschlüsselung kann also für einzelne Projekte ein- oder ausgeschaltet werden. Außerdem können einzelne Projekte nach Bedarf mit stärkeren oder schwächeren Algorithmen verschlüsselt werden.

Verschlüsselung aktiv: Über die Checkbox kann die Verschlüsselung des Projekt-Repositorys für jedes Projekt einzeln an- bzw. abgeschaltet werden. Ist diese Checkbox aktiviert, greift der Verschlüsselungsmechanismus für das aktuelle Projekt (siehe auch Durchführung der Ver- bzw. Entschlüsselung), ist sie deaktiviert, werden die Repository-Inhalte nicht verschlüsselt. Für bestehende Projekte muss die Checkbox initial aktiviert werden, um bereits vorhandene Repository-Inhalte zu verschlüsseln. Während des initialen Verschlüsselungsprozesses kann das Projekt nicht verwendet werden (temporär deaktiviert). Beim Deaktivieren der Verschlüsselung wird analog eine Entschlüsselung der Dateiablage vorgenommen. Eine globale Vorbelegung dieses Wertes ist über den Parameter repository.encryption in der Konfigurationsdatei fs-server.conf möglich (für neu angelegte oder importierte Projekte) (siehe Bereich: Storage Engine Properties).

Verschlüsselungs-Algorithmus: Über das Drop-Down-Menü kann der zu verwendende Verschlüsselungs-Algorithmus ausgewählt werden. Dazu wird jeweils Name, Modus und Padding angegeben. Die hier angebotenen Algorithmen sind lediglich Beispielwerte und stellen keine Empfehlung dar:

• AES/CBC/PKCS5Padding
• AES/CTR/NoPadding (Standard)
• ARCFOUR
• Blowfish/CBC/PKCS5Padding
• Blowfish/CTR/NoPadding

Alternativ zu den vorgeschlagenen Werten kann ein gültiger Verschlüsselungs-Algorithmus von Hand in das Feld eingetragen werden. Die eigentliche Verschlüsselung übernimmt die Java Cryptography Extension. Die hier konfigurierbaren, symmetrischen Verschlüsselungen und Modi sind damit abhängig von der verwendeten Java-Plattform. Die möglichen Algorithmen, Modi und Schlüssellängen können der jeweiligen JCE-Dokumentation entnommen werden:

• http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#Cipher
• http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJCEProvider

sowie Abschnitt Hinweise zu speziellen Java-Versionen.

Eine globale Vorbelegung ist über den Parameter encryption.algorithm in der Konfigurationsdatei fs-server.conf möglich (für neu angelegte oder importierte Projekte) (siehe Bereich: Storage Engine Properties).

Schlüssellänge der Verschlüsselung: Über das Drop-Down-Menü kann die Schlüssellänge der Verschlüsselung konfiguriert werden. Alternativ zu den vorgeschlagenen Beispielwerten (64, 128, 192 und 256 Bits) können weitere Werte manuell eingegeben werden. Die Schlüssellänge muss zum konfigurierten Algorithmus (Verschlüsselung, Modi) passen. Weitere Informationen zu erlaubten Schlüssellängen siehe

• http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJCEProvider
• http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#importlimits

sowie Abschnitt Hinweise zu speziellen Java-Versionen.

Eine globale Vorbelegung ist über den Parameter encryption.keySize in der Konfigurationsdatei fs-server.conf möglich (siehe Bereich: Storage Engine Properties).

Verschlüsselungs-Parameter testen: Mit einem Klick auf die Schaltfläche wird die Verschlüsselung mit den aktuell konfigurierten Parametern getestet. Der Test prüft die Verschlüsselung anhand der Vorgaben der Java Cryptography Extension, beispielsweise ob die angegebene Kombination von Algorithmus und Schlüssellänge zueinander passt.

Wenn möglich schnelle Repository-Konvertierung benutzen: Diese Checkbox hat aktuell keine Auswirkung. Sollte zukünftig neuere Versionen der Berkeley DB zur Verfügung stehen, kann über das Aktivieren dieser Checkbox eine beschleunigte Konvertierung der Daten eingestellt werden.

Wird die Auswahl mit OK bestätigt, beginnt die Konvertierung der Daten mit den gewünschten Einstellungen. Das betroffene Projekt wird während dieser Zeit deaktiviert.

Um Datenverlust zu vermeiden, sollten alle Benutzer des Projekts zuvor abgemeldet sein. Eine Änderung der Repository-Einstellungen kann potenziell einige Zeit in Anspruch nehmen und sollte daher nur während eines Wartungsintervalls durchgeführt werden. Vor einer Repository-Konvertierung sollte eine Datensicherung angelegt werden.

Konvertierung nach Berkeley DB 7 (ab FirstSpirit-Version 5.2R19)

(nur für FirstSpirit-Server, die Berkeley DB in einer Version <7 verwenden!)

Mit dem Konvertierungstool „BerkeleyUtil“ können sämtliche in den Berkeley-DBs gespeicherten Daten auf bestehenden FirstSpirit-Servern komfortabel mit wenigen Befehlen per Kommandozeile in das Berkeley DB 7-Format konvertiert werden („Projekt-Repositorys“ und „interne Repositorys“). Die genaue Vorgehensweise wird im Abschnitt Empfohlene Vorgehensweise für eine Konvertierung zu Berkeley DB 7 beschrieben. Da es sich auch um Daten auf Server-Ebene handelt, die konvertiert werden müssen, kann eine solche Konvertierung nur durchgeführt werden, wenn der FirstSpirit-Server offline ist, um Datenverlust vorzubeugen. Eine Konvertierung wird in der Regel in kurzer Zeit abgeschlossen sein. Nur in Ausnahmefällen kann sie, beispielsweise im Falle von sehr großen und / oder vielen Projekten, bis zu einigen Stunden in Anspruch nehmen.

Verwendung

Das Tool „BerkeleyUtil“ ist in der Datei fs-isolated-server.jar enthalten und wird beim Server-Start in das „bin“-Verzeichnis ausgerollt.

Voraussetzungen:

• Oracle Java: mind. Version 8
• Das Tool sollte nur verwendet werden, wenn der entsprechende FirstSpirit-Server heruntergefahren ist.
• Ausreichender Speicherplatz: Temporär wird potenziell der dreifache Festplattenspeicherplatz der größten zu konvertierenden Datenbank (ohne „blob“-Verzeichnis, dieses kann von der Berechnung ausgenommen werden) benötigt.

Wichtig: Auf Unix-Systemen muss die Konvertierung per BerkeleyUtil.jar mit dem Benutzer durchgeführt werden, der die Berkeley-Datenbanken später nutzen soll. In der Praxis ist dies der Benutzer, unter dem der FirstSpirit-Server bzw. der Application Server läuft.

Aufruf und Optionen:

java -jar BerkeleyUtil.jar COMMAND [OPTION]... PATH 

Zunächst muss mit -jar der Pfad angegeben werden, unter dem sich die Datei BerkeleyUtil.jar auf dem FirstSpirit-Server befindet, standardmäßig im „bin“-Verzeichnis., z. B.

java -jar firstspirit/bin/BerkeleyUtil.jar

Für den Platzhalter COMMAND können folgende Kommandos verwendet werden:

• -c, --convert: konvertiert alle Verwendungen unterhalb des angegebenen Verzeichnisses (siehe PATH unten) nach Berkeley DB Version 7 (kompletter FirstSpirit-Server)
  • --convert-acl: konvertiert alle ACL-Datenbanken nach Berkeley DB 7
  • --convert-project: konvertiert alle Projekt-Repositorys nach Berkeley DB 7
  • --convert-server: konvertiert alle internen Repositorys nach Berkeley DB 7
• -d, --dump: repariert das gewünschte Repository (Standardmodus I)
• --exclude: Angabe von Verzeichnissen, die von der Betrachtung und Konvertierung ausgenommen werden sollen. Die Verzeichnisse müssen als entsprechende RegEx angegeben werden. Auch alle Unterverzeichnisse werden ausgenommen. Beispiel:
  java -jar bin\BerkeleyUtil.jar --exclude webapps -l
  => schließt alle Verzeichnisse aus, in deren Namen die Zeichenfolge „webapps“ vorkommt
  Standardmäßig werden alle Verzeichnisse ausgeschlossen, die mit . beginnen.
• -h, --help: Anzeige der Hilfe
• -l, --list: listet die Namen, Version, Pfad und Größe aller Repositorys auf dem Server auf und gibt eine Zusammenfassung aller zu konvertierenden Datenmengen
• -r, --recover: versucht, das gewünschte Repository wiederherzustellen (Standardmodus II)
• -R, --RECOVER: versucht, das gewünschte Repository wiederherzustellen (mit erweiterten Fehlerkorrekturen)
• -t, --verify: prüft das gewünschte Repository

Die Kommandos können nicht kombiniert werden, d.h. jedes Kommando erfordert einen eigenen Aufruf.

Die Kommandos -d, -r bzw. -R sollten erst nach einer vorausgegangenen Analyse verwendet werden. Bitte kontaktieren Sie für eine Unterstützung den Technical Support.

Für den Platzhalter OPTION können folgende Werte verwendet werden:

• --dump-dir <directory>: Für die Konvertierung oder Wiederherstellung eines Repositorys wird zunächst eine Kopie erstellt, die anschließend wieder importiert wird. Über diesen Aufruf kann ein Verzeichnis angegeben werden, in das die temporäre Kopie erstellt werden soll.
  Hinweis: Der verfügbare Festplattenspeicherplatz des Volumes, in dem dieses Verzeichnis existiert, muss mindestens so groß sein wie die größte zu konvertierenden Datenbank (ohne „blob“-Verzeichnis, dieses kann von der Berechnung ausgenommen werden).
• -v, --verbose: erzeugt zusätzliche Log-Ausgaben, z. B der Stacktrace zu Fehlermeldungen
• -f, --fast: führt eine schnellere Inplace-Konvertierung von Projekt-Repositorys durch. Diese sollte aber nur durchgeführt werden, wenn ein aktuelles Backup vorliegt, da in seltenen Fällen bereits bestehende Probleme in einem Repository dazu führen können, dass dieses bei einer Konvertierung irreparabel beschädigt wird.
  Standardmäßig wird zunächst eine Kopie des zu konvertierenden Repositorys erstellt, mit -f wird auf diese Kopie verzichtet. Das Erstellen der Kopie erfordert zwar etwas mehr Zeit und temporären Festplattenspeicherplatz, ist aber sicherer. Zusätzlich wird auf diese Weise das zu konvertierende Repository optimiert, so dass es anschließend keine unnötigen Daten mehr beinhaltet.
• --no-log-file: Standardmäßig werden die Aktionen der Konvertierung in einer Log-Datei protokolliert. Das Erstellen dieser Log-Datei kann über diese Option deaktiviert werden.

Über PATH muss der Pfad zu dem Verzeichnis angegeben werden, das vom Tool berücksichtigt werden soll, z. B.

• zum Root-Verzeichnis des FirstSpirit-Servers: /firstspirit
• zum Verzeichnis einer Berkeley DB auf dem FirstSpirit-Server, z. B. /firstspirit/data/projects/project_123/repository (Repository eines Projekts), /tomcat/webapps/ROOT/WEB-INF/acl (ACL-Datenbank eines Live-Projekts)

Exemplarischer Aufruf:

java -jar firstspirit/bin/BerkeleyUtil.jar -l firstspirit

Dieser Aufruf listet alle Berkeley-Datenbanken des im Verzeichnis „firstspirit“ installierten FirstSpirit-Servers auf und gibt deren Versionen aus.
Standardmäßig werden alle Verzeichnisse ausgeschlossen, die mit . beginnen. Sollen andere Verzeichnisse ausgeschlossen werden, so müssen diese über den Parameter --exclude als entsprechende RegEx angegeben werden.
Beispiel:

java -jar bin\BerkeleyUtil.jar --exclude webapps -l 

=> schließt alle Verzeichnisse aus, in deren Namen die Zeichenfolge „webapps“ vorkommt.

Logging
Standardmäßig werden die Aktionen der Konvertierung in einer Log-Datei protokolliert. Name der Log-Datei ist berkeley_util_yyyyMMdd_HHmmss.log, also z. B.

berkeley_util_20180502_113208.log 

Bei der Konvertierung eines kompletten FirstSpirit-Servers wird die Datei im Verzeichnis log des Servers abgelegt, bei der Konvertierung einzelner Datenbanken in dem Verzeichnis, das als Startverzeichnis angegeben wurde (Parameter PATH).

Kalkulation des voraussichtlich benötigten Festplattenspeicherplatzes
Während der Konvertierung der Berkeley-Datenbanken eines FirstSpirit-Servers per Tool wird temporär potenziell der dreifache Speicherplatz der größten zu konvertierenden Datenbank benötigt. Vor der Konvertierung jeder Datenbank prüft das Tool, ob ausreichend freier Festplattenspeicher zur Verfügung steht. Ist dies nicht der Fall, wird die Konvertierung nicht ausgeführt. Die Konvertierung für diese Datenbank bricht dann mit einer Fehlermeldung Insufficient free space ab. In diesem Fall sollte mehr Platz geschaffen bzw. Dateien aus dem Verzeichnis entfernt und eine erneute Konvertierung gestartet werden.
Hinweis: In sehr seltenen Fällen kann das Konvertierungstool den benötigten Speicherplatz nicht zuverlässig kalkulieren. Ist in so einem Fall der zur Verfügung stehende Plattenplatz zu gering, bricht die Konvertierung mit einem entsprechenden Fehler ab: Error converting BerkeleyDB. Wenden Sie sich in diesem Fall bitte an den Technical Support.

Empfohlene Vorgehensweise für eine Konvertierung zu Berkeley DB 7

1) Der FirstSpirit-Server muss für eine Konvertierung per Konvertierungstool heruntergefahren sein. Daher sollte eine Konvertierung während eines Wartungsintervalls durchgeführt werden.

2) Folgenden exemplarischen Aufruf ausführen (angepasst an den Pfad des Root-Verzeichnisses des FirstSpirit-Servers):

java -jar -Xmx#m firstspirit/bin/BerkeleyUtil.jar -c /firstspirit

Der Konvertierungsprozess sollte mit ausreichend Speicher gestartet werden. Als Faustregel sollte hier mittels -Xmx#m derselbe Wert übergeben werden, der für den FirstSpirit-Server über den Parameter wrapper.java.maxmemory definiert wurde.

Der Konvertierungsprozess kann je nach Größe und Anzahl der auf dem FirstSpirit-Server vorhandenen Repositorys einige Zeit (maximal einige Stunden) in Anspruch nehmen. Während dieser Zeit sollte die Konvertierung nicht abgebrochen werden, da es sonst zu Datenverlust und Inkonsistenzen kommen kann! Im Falle eines Abbruchs des Prozesses erfolgt kein Rollback, sondern es ist ein manueller Eingriff erforderlich. Bitte wenden Sie sich an den Technical Support.

3) Wurde die Konvertierung erfolgreich durchgeführt, wird eine entsprechende Meldung im Log ausgegeben, z. B.

<timestamp> [INFO Bdb7Convert] BerkeleyDB version 7 conversion successful, marker 
   file written: firstspirit/data/server/berkeleydb.7

4) In der Datei fs-wrapper.conf muss folgender Parameter eingetragen werden:

-DBerkeleyDB7=1

5) Anschließend kann der FirstSpirit-Server gestartet und wie gewohnt verwendet werden.

Troubleshooting

Läuft eine Konvertierung nicht erfolgreich durch, wird eine entsprechende Meldung im Log ausgegeben, z. B.:

<timestamp> [WARN Bdb7Convert] BerkeleyDB version 7 marker file not written, 1 errors 
   during the conversion process.

In diesem Fall kann ein erneutes Durchführen der Konvertierung Abhilfe schaffen.
Ist dies nicht erfolgreich, wenden Sie sich bitte an den Technical Support. Gleiches gilt, wenn eine Konvertierung doch abgebrochen werden musste. Meldung im Log bei Server-Start:

FATAL <timestamp> (de.espirit.firstspirit.server.ServerManagerImpl): Incomplete 
   BerkeleyDB version 7 conversion detected

Steht nicht genügend Festplattenspeicher für die Konvertierung einer Datenbank zur Verfügung, bricht die Konvertierung mit einer Fehlermeldung Insufficient free space ab. Siehe dazu Abschnitt oben: „Kalkulation des voraussichtlich benötigten Festplattenspeicherplatzes“.

Für eine Unterstützung durch den Technical Support halten Sie bitte die Log-Datei der letzten Ausführung des Konvertierungstools bereit.

Speichern von Daten im Fehlerfall (Backup)

Kommt es bei einer Konvertierung zu Problemen, werden die Originaldaten der Datenbank in einem Backup-Verzeichnis auf dem FirstSpirit-Server gespeichert. Auf diese Weise können die Daten bei Bedarf später analysiert werden. Das Verzeichnis wird am gleichen Ort wie das Ursprungsverzeichnis erstellt. Der Name setzt sich zusammen aus dem Namen des Ursprungsverzeichnisses, dem Zusatz backup und dem Timestamp der Konvertierung.
Dieses Verzeichnis beinhaltet die nicht konvertierten Originaldaten. Sie können zu einem späteren Zeitpunkt gelöscht werden.

Hinweis: Bei einer Auflistung oder Prüfung der Datenbanken ( -l / --list bzw. -t / --verify) werden vorhandene Backup-Verzeichnisse als Warnung protokolliert:

<timestamp> [WARN BdbScanner] Incomplete conversion/restore detected: <path>...backup...