Zum Inhalt

Daten von Kopano Groupware migrieren

Achtung

Dieses Feature ist standardmäßig deaktiviert und muss vom Systemadministrator konfiguriert werden.

Ein Migrationstool steht zur Verfügung, um Daten aus einer Kopano Groupware-Installation zu importieren. Der Import darf nur aus vertrauenswürdigen Quellen, die über ihre IP-Adresse verifiziert sind, erfolgen.

Voraussetzungen

Achtung

Das Migrationstool unterstützt keine partiellen oder inkrementellen Migrationen. Wiederholte Migrationen werden nicht empfohlen, da dies zu doppelten Einträgen führt.

Die Anforderungen für das Migrationstool sind:

  1. Ziel-Benutzer müssen bereits existieren
    1. Diese können entweder
      1. Manuell erstellt
      2. Oder über ad-connect synchronisiert werden
    2. Sie müssen inaktiv sein, damit das Postfach während des Imports nicht verwendet wird
  2. Quell-Benutzer müssen entweder
    1. Einen vollqualifizierten Benutzerprincipalnamen (mit Domain) besitzen
    2. Oder die Mapping-Konfiguration beim Import muss diese zusätzlichen Informationen bereitstellen
  3. Leseberechtigung auf die Kopano Groupware-Datenbank (MySQL oder MariaDB)
  4. Leseberechtigung auf das Kopano-Groupware-Anhangsverzeichnis (direkt oder via Netzwerkmount)
  5. Zugriff auf den Exchange4all-Server-Importer-Endpunkt (Quell-IP muss auf der Whitelist stehen)
  6. Das kgdump-Tool unterstützt das Kopano-Datenbankschema ab Revision 63
    1. Dies entspricht dem ersten öffentlichen Release von Kopano Groupware (8.0) und schließt auch Zarafa Groupware 7.1 ein
  7. Das kgdump-Tool arbeitet direkt auf Datenbankebene und verarbeitet daher auch als gelöscht markierte, aber noch nicht gelöschte Nachrichten (Soft-Deleted-Nachrichten)
    1. Es wird empfohlen, Soft-Deleted-Nachrichten vor dem Export zu löschen
      1. z. B. durch Ausführen von kopano-admin --purge-softdelete 0
Tipp

Es wird empfohlen, einen schnellen dedizierten Host zu verwenden, auf dem sowohl der Dump als auch die Migration laufen. Dies stellt sicher, dass keine Ressourcen auf Quell- oder Zielsystem zusätzlich belastet werden, was bei großen Datenmengen für beste Performance sorgt.

Ein geeignetes Migrationssystem sollte mindestens haben:

  1. 8 CPU-Kerne

  2. 16 GiB RAM

Der benötigte Speicherplatz hängt von der zu übertragenden Datenmenge ab. Wird der Dump mit Concurrency 1 ausgeführt, entspricht der maximale benötigte temporäre Speicherplatz der Größe des Dumps.

Serverseitige Konfiguration

Um eine IP-Adresse auf die Import-Whitelist zu setzen, trage sie in der Datei /storage/config.yaml wie folgt ein:

e4a:
  adminrpc:
    importer:
      ip_white_lists:
        - 198.51.100.5
        - 203.0.113.19
````

## Download des Migrationstools

Die **aktuellste Version** des Tools wird immer mit dem **Container** ausgeliefert. Sie kann über `https://your-server/download/service/kg-migration/e4a-kg-migration-latest-linux-amd64.tar.gz` heruntergeladen werden. Weitere **Dokumentation** und **Beispielkonfigurationen** finden sich im **Archiv**.

## Beispiele zur Ausführung des Migrationstools

Das **Migrationstool** besteht aus zwei Komponenten, `kg-dump` und `migrate`.

1. Das Tool `kg-dump` **verbindet** sich mit der Kopano-Datenbank und dem Anhangsverzeichnis und **erzeugt einen Exportstream**.
2. Das Tool `migrate` liest den Exportstream ein, ordnet die Daten den Zielbenutzern zu und überträgt diese über eine TLS-Verbindung an den neuen Server.

Da Dump und Import längere Zeit dauern können, wird empfohlen, die Migration innerhalb von Tools wie `screen` oder `tmux` auszuführen. Diese sorgen dafür, dass der Prozess auch bei einem unerwarteten Schließen der Konsole weiterläuft und Logs erhalten bleiben.

!!! info "Wichtig"
Der Importer läuft standardmäßig im Dry-Run-Modus, es werden also keine Änderungen durchgeführt. Um eine tatsächliche Migration zu starten, setze .settings.dry_run in deiner config.yml auf false. 
### Umgebung vorbereiten

Es wird empfohlen, die Umgebung für den Import in einem dedizierten Verzeichnis mit einer `.env`-Datei einzurichten.

Beispiel:

```bash
FOLDER=migrate-$(date -I)
mkdir "$FOLDER" \
&& cat <<EOF > "$FOLDER/.env"
export LOG_LEVEL=info
export DUMP_MYSQL_DSN=mysql://localhost/kopano?socket=/tmp/mysql.sock
export DUMP_ATTACHMENT_STORAGE=files_v1-10-20
export DUMP_ATTACHMENT_STORAGE_URI=file:///kopano/attachments
export IMPORTER_CONFIG=migrate-import-config.yaml
export IMPORTER_IMPORT_URL=https://exchange4all.local/e4a.importer_d1.v1.importer/import
EOF
cd "$FOLDER" && source ./.env

Verschiedene Szenarien zum Exportieren von Daten

Es gibt drei Szenarien zum Dumpen von Daten, die jeweils ihre eigenen Vor- und Nachteile haben.

Wichtiger Hinweis

Bitte prüfe sorgfältig, welches Szenario zu deiner Situation passt, und lese die Beispiele genau durch. Beim Migrieren können Daten verloren gehen, die nicht wiederherstellbar sind. Das Tool verhindert dies weitgehend, aber falsche oder unvollständige Befehle können zu Datenverlust führen.

Direktes Dumpen und Piping in den Import

Dieses Beispiel geht davon aus, dass das System, auf dem die Migrationstools laufen, sowohl die Quelldatenbank als auch den Ziel-Importer-Endpunkt erreichen kann.

screen -L -Logfile kg-e4a-migrate-$(date -I'second').log -dmS kg-e4a-migrate sh -c "../bin/kgdump dump --stdout | ../bin/migrate import --stdin"

Dumpen und direktes Piping in den Remote-Import über SSH

Dieses Vorgehen wird empfohlen, wenn es keine Maschine gibt, die sowohl Quell- als auch Zielsystem erreichen kann. Dafür müssen die Migrationstools und die Konfigurationsdatei auf dem SSH_TARGET verfügbar sein.

SSH_TARGET=target.url
screen -L -Logfile kg-e4a-migrate-$(date -I'second').log -dmS kg-e4a-migrate sh -c "../bin/kgdump dump --stdout | ssh ${SSH_TARGET} env DEBUG_LEVEL=${DEBUG_LEVEL} IMPORTER_CONFIG=${IMPORTER_CONFIG} IMPORTER_IMPORT_URL=${IMPORTER_IMPORT_URL} ../bin/migrate import --stdin"

Dumpen in eine Datei, Datei übertragen, aus Datei importieren

Für große Datenmengen nicht empfohlen, da es doppelt so lange dauert und großen Speicherplatz benötigt. In einigen Fällen können die Daten aber auf einen Wechseldatenträger geschrieben und zwischen Quell- und Zielsystem transferiert werden.

Zuerst Dump in eine Datei erzeugen:

DUMPFILE=kgdump-yourserver-$(date -I'seconds').d1
../bin/kgdump dump --output="${DUMPFILE}"

Danach Datei auf das Zielsystem übertragen und Import lokal ausführen:

../bin/migrate import --input="${DUMPFILE}"

Nachbereitung der Migration

Nach dem Import können die Benutzer wieder aktiviert werden, wodurch ihre Postfächer nutzbar werden.

Es gibt bestimmte MAPI-Eigenschaften, die zu Problemen mit dem Outlook-Cache-Modus führen können. Um diese zu bereinigen, kann das Admin-Skript clear-unregistered-named-properties verwendet werden:

e4a service admin clear-unregistered-named-properties

[ConsoleKit\ConsoleException]
Usage: clear-unregistered-named-properties [--all|<username>] [--organization-id=<organization ID>] [--maildir] [--dry-run]

Errata

Bekannte Probleme und Verbesserungen:

  • #39 Exportfilter in Kopano können verwirrend sein, da Stores beim Export nach User-ID ausgewählt, beim Import aber nach Store-ID gefiltert werden.
  • #46 Migration von "Regeln" nicht implementiert.
  • #47 Migration von "ACLs" und "Berechtigungen" nicht implementiert.
  • #48 Migration von "Abwesenheitsnotizen" nicht implementiert.
  • #49 Migration von "E-Mail-Signaturen" nicht implementiert.
  • #64, #67, #69 Benutzerreferenzen aus dem globalen Adressbuch werden in SMTP-Mailadressen konvertiert.
  • #66 Manche alte Termineinladungen im "Gesendet"-Ordner lassen sich nicht öffnen.
  • #71 Anhänge werden nur durch direkten Export übertragen.
  • #72 Import überschreitet Mailbox-Quota, Postfach muss ggf. vom Admin vergrößert werden.
  • #73 Import-Logs zeigen die Attachments nicht in der Größenangabe, daher kann die reale Postfachgröße größer sein.
  • #75 Nachrichtengröße entspricht der im Quellsystem gespeicherten Größe, kann sich aber bei Änderungen nach dem Import leicht verändern.
  • #479 Arbeitsspeicherverbrauch beim Import hängt direkt von der Zahl der Anhänge ab. Millionen Anhänge können mehrere Gigabyte RAM erfordern.
  • #480 Nachrichtenklassen-Whitelist: Nicht unterstützte Klassen werden im Serverlog mit „message class not supported yet“ protokolliert.