Kopano-Mailmigration für LD2.0

Anleitung nur für LogoDIDACT 2.0

Die nachfolgenden Schritte beschreiben, wie Daten aus Kopano exportiert und in die IServ Schulplattform importiert werden können. Dies betrifft konkret:

E-Mail
Kalender

Voraussetzungen

Zur Migrationsdurchführung müssen zusätzliche Tools auf dem LogoDIDACT installiert werden. Da sich die LD-Instanz bereits im End of Life Stadium befinden könnte, werden die benötigten Ubuntu-Pakete als tar.gz-Archiv zum Download angeboten.
Vor dem Export muss eine externe Festplatte oder ein sonstiger Speicherort am ldhost angeschlossen und eingehängt werden. Aufgrund der einfachen Handhabung geht die Dokumentation im Folgenden davon aus, dass eine externe USB-Festplatte mit einem ext4 Linux-Dateisystem und dem Label "USB-Backup" verwendet wird. Eine Sicherung auf ein anderes Medium ist ebenfalls möglich.
Die Mailmigration wird in zwei Teilen gemacht: 2-3 Tage vor dem Umstellungstermin wird der erstmalige Export angestoßen. Am Tag der Umstellung wird derselbe Export erneut gestartet, hier erfolgt ein finaler Abgleich.

LogoDIDACT Postfach-Export vorbereiten

Zur Durchführung des Postfach-Datenexports werden verschiedene Tools und ergänzende Ubuntu-Pakete im LXC-Container kopano-g1 installiert. Auch im Konfigurationssystem puppeteer sind Einstellungen per YAML-Konfigurationsdatei festzulegen. Damit wird einleitend begonnen, eine SSH-Verbindung zum LogoDIDACT Server hergestellt und die nachfolgenden Konfigurationabschnitte im Puppeteer hinzugefügt.

ldhost
1	`ssh puppeteer`

Vorhandene Datei /etc/logodidact/hiera/custom.d/kopano-g1.yaml mit einem Texteditor bearbeiten
Zusätzliche Einstellungen zur YAML-Datei hinzufügen und die sonstigen, bereits vorhandenen Einstellungen unberührt lassen.

/etc/logodidact/hiera/custom.d/kopano-g1.yaml
# Restrict access to additional IMAP service to 'local' firewall zone
profile::network:
  interface:
    servernet:
      firewall:
        rules: {
          01_IMAP-BYPASSAUTH:  {prio: 91, action: 'ACCEPT', section: 'NEW', source: 'loc', dest: '$FW', proto: 'tcp', dport: '8143'},
          02_IMAP-BYPASSAUTH:  {prio: 92, action: 'DROP',   section: 'NEW', source: 'all', dest: '$FW', proto: 'tcp', dport: '8143'},
          03_IMAPS-BYPASSAUTH: {prio: 93, action: 'ACCEPT', section: 'NEW', source: 'loc', dest: '$FW', proto: 'tcp', dport: '8993'},
          04_IMAPS-BYPASSAUTH: {prio: 94, action: 'DROP',   section: 'NEW', source: 'all', dest: '$FW', proto: 'tcp', dport: '8993'},
          05_POP3-BYPASSAUTH:  {prio: 95, action: 'ACCEPT', section: 'NEW', source: 'loc', dest: '$FW', proto: 'tcp', dport: '8110'},
          06_POP3-BYPASSAUTH:  {prio: 96, action: 'DROP',   section: 'NEW', source: 'all', dest: '$FW', proto: 'tcp', dport: '8110'},
          07_POP3S-BYPASSAUTH: {prio: 97, action: 'ACCEPT', section: 'NEW', source: 'loc', dest: '$FW', proto: 'tcp', dport: '8995'},
          08_POP3S-BYPASSAUTH: {prio: 98, action: 'DROP',   section: 'NEW', source: 'all', dest: '$FW', proto: 'tcp', dport: '8995'}
        }

ld_kopano::openldap:
   headers:
      # Map extra user properties from the propmap file (LDAP employeeNumber -> Kopano "department" field)
      - '!propmap /etc/kopano/openldap.propmap.cfg'
   settings:
      ldap_fullname_attribute: uid

Hier wird eine Anpassung der OpenLDAP Attributsfelder vorgenommen, damit in den Kopano-Konten neben der Mailadresse auch der normale Linux-Accountname sowie die Unique-ID als Benutzereigenschaften zur Verfügung stehen. Außerdem wird ein zusätzlicher IMAP-Dienst am Server eingerichtet, der User-Postfächer an der Shell (ohne Angabe der einzelnen Benutzer-Kennwörter) exportierbar macht. Die obigen Firewall-Einstellungen begrenzen die Erreichbarkeit auf die lokale Zone (loopback Device).

Die Änderungen wie üblich unterhalb des Verzeichnis /etc/logodidact/ ins GIT speichern.

puppeteer
cd /etc/logodidact/
git commit -a -m "kopano-g1: Firewall-Einstellungen und Kopano UserAttribut-Mapping für Postfach-Export hinzugefügt"

Als Nächstes müssen zusätzliche Ubuntu-Pakete für den kopano-g1 LXC-Container heruntergeladen werden, um den Export zu ermöglichen. Diese werden als tar-Archiv zur Verfügung gestellt.

puppeteer
# Zusätzliche Ubuntu-Pakete im lokalen APT Repository des Servers verfügbar machen
wget https://files.sbe.de/kopano/migration/kopano-g1-exporttools-bundle.tgz -O /tmp/kopano-g1-exporttools-bundle.tgz
tar xf /tmp/kopano-g1-exporttools-bundle.tgz -C /srv/repos/xenial/
[ -f "/tmp/kopano-g1-exporttools-bundle.tgz" ] && rm -f "/tmp/kopano-g1-exporttools-bundle.tgz"
puppet-repo-build

Es folgt eine Anpassung im Puppet-Modul ld_kopano, um das Zurücksetzen der aktivierten apache2-sites im LXC-Container kopano-g1 zu verhindern.

puppeteer
# Die Kommandos können per Zwischenablage ins Terminal kopiert werden, um die mehrzeilige Variable festzulegen.
read -rd '' insertDirBlock <<'EOD' || :
\1'/etc/apache2/sites-available':\n
\1  ensure  => directory,\n
\1  mode   => 'u=rwx,g=rx,o=rx',\n
\1  purge   => false,\n
\1  ;\n
\1'/etc/apache2/sites-enabled':\n
\1  ensure  => directory,\n
\1  mode   => 'u=rwx,g=rx,o=rx',\n
\1  purge   => false,\n
\1  ;\n
\1\2\3 #patched, allow extra sites
EOD
sed -i -E "s@^([[:blank:]]*)(['\"]?/etc/apache2/sites-available/kopano-webapp\.conf['\"]?:)([^#]*)\$@${insertDirBlock//$'\n'/}@" /var/lib/ld-puppet/env.d/logodidact/modules/ld_kopano/manifests/init.pp
service apache2 restart
logout

Zurück im ldhost muss der LXC-Container kopano-g1 kurzzeitig angehalten werden. Dies dient dem Zweck, die Backup-Festplatte einzuhängen und im Namespace des LXCs verfügbar zu machen.

ldhost
systemctl stop lxc@kopano-g1; lxc-stop -n kopano-g1

ACHTUNG

Das Label oder der Pfad zur Backup-Partition muss auf Ihre Gegebenheiten angepasst werden.

ldhost
mount LABEL=USB-BACKUP /var/backups/lxc/kopano-g1
touch /var/backups/lxc/kopano-g1/.bind-mount
systemctl start lxc@kopano-g1
# Einhängepunkt aus dem normalen, nächtlichen Backup ausschließen
grep -sqi "/var/backups/lxc/kopano" /etc/logodidact/backup.exclude || echo -e "\n\n# Kopano export data\n/var/backups/lxc/kopano-g1/*\n/var/backups/lxc/kopano-g2/*">>/etc/logodidact/backup.exclude

Anschließend in den LXC-Container kopano-g1 wechseln und die Änderungen per prun anwenden.

ldhost
1	`ssh kopano-g1`

kopano-g1
1 2 3	`touch /etc/kopano/openldap.propmap.cfg apt update prun`

Nun erfolgt die Installation der zusätzlich benötigten Tools, die für den Export verwendet werden:

Info

Um den manuellen Aufwand zu reduzieren, steht hierzu ein Shell-Skript zur Verfügung, welches im Container heruntergeladen werden kann.

kopano-g1

mkdir -p /backup/ld-kopano-stores /root/migration
wget https://files.sbe.de/kopano/migration/latest/task1_setup-tools.sh -O /root/migration/task1_setup-tools.sh
chmod +x /root/migration/task1_setup-tools.sh
cd /root/migration

Innerhalb des Skriptes sind nun verschiedene Optionen wählbar. Diese können entweder einzeln oder gesammelt mit dem Parameter --all aufgerufen werden. Das Skript läuft diese Schritte automatisch ab, einzelne Schritte können jedoch über den genannten Weg wiederholt werden.

alt text

Nun wird die Installation angestoßen, bitte die Konsolenausgabe beachten.

kopano-g1
1	`/root/migration/task1_setup-tools.sh --all`

Neben der Installation von Paketen finden durch das Setup-Skript einige weitere Schritte automatisch statt. Es werden auch zusätzliche Migrationsskripte ins Verzeichnis /opt/export-tools/ entpackt, um den Vorgang zu vereinfachen. Ein gewisser Komplexitätsgrad bleibt beim Übertragen von E-Mail-Postfächern dennoch übrig, es muss in jedem Fall sehr sorgfältig gearbeitet werden. Durch das Entpacken weiterer Tools nach /opt/export-tools/ ist es möglich, Aktionen darin durch Feedback zu verbessern.

Der letzte Schritt 6 weist nach der Ausführung darauf hin, dass YAML-Einstellungen im puppeteer festgelegt werden müssen. Dies ist bereits geschehen, wenn man dieser Anleitung gefolgt ist. Daher muss lediglich noch der hinzugefügte systemd-Service kopano-gateway-bypassauth.service gestartet werden, um die Ergänzungen im Mail-Container abzuschließen.

kopano-g1
systemctl start kopano-gateway-bypassauth.service
systemctl status kopano-gateway-bypassauth.service

Sofern der Dienst nun als aktiv gekennzeichnet wird, sind die Vorbereitungen abgeschlossen und der eigentliche Export kann gestartet werden.

1. Ausführen des ersten Exportes

Info

Zur Durchführung des IMAP-Exportes wird ein weiteres, eigenständiges Shell-Skript task2_export-kopano-stores.sh zur Verfügung gestellt, um einen Teil der Aufgaben zu automatisieren. Es empfiehlt sich, diese in einer Screen-Sitzung auszuführen, um ungewollte Abbrüche zu verhindern.

Dies soll den Export vereinfachen, es ist davon auszugehen, dass der Postfach-Export viele Stunden zur Abarbeitung benötigt und das Shell-Skript soll hierbei unterstützen, damit diese Aktionen im Hintergrund, ohne weitere manuelle Eingriffe, stattfinden können.

ldhost
screen -S mbox_export
ssh kopano-g1

kopano-g1
[ -d ~/migration ] || mkdir ~/migration
cd ~/migration
wget https://files.sbe.de/kopano/migration/latest/task2_export-kopano-stores.sh -O /root/migration/task2_export-kopano-stores.sh
chmod +x /root/migration/task2_export-kopano-stores.sh

Analog zum Setup-Skript aus dem vorherigen Schritt, liefert auch das Export-Skript verschiedene Parameter mit, um einzelne Schritt gezielt auszuführen:

alt text

1.1 Übersicht der einzelnen Schalter

--step1

Erstellt bzw. erneuert ein Komplettbackup der gesamten Kopano-Installation in einem proprietären Kopano-Datenbankformat (MAPI-Objekte im Binärformat). Diese Daten sind ausschließlich als Fallback gedacht und werden nicht für die Migration nach IServ verwendet. Das Backup wird in einem Berkeley-DB-Format gespeichert und benötigt entsprechenden Speicherplatz.

--step2

Erstellt eine Kopano-Benutzerliste als kopano.userlist.csv (mit Kopano-Name, Linux-Account, IServ-Account). Grundlage für alle weiteren Exporte und das spätere Mapping nach IServ.

--step3

Erzeugt auf Basis der kopano.userlist.csv Konfigurationsdateien für die Export-Tools (z. B. offlineimap/vdirsyncer). Muss erneut ausgeführt werden, wenn sich die kopano.userlist.csv geändert hat.

--step4 (Kalender)

Exportiert bzw. aktualisiert die Kalenderdaten (ICS-Dateien) der Benutzer auf der Backup-Festplatte.

--step5 (Kontakte)

Exportiert bzw. aktualisiert die Kontaktdaten (VCF-Dateien) der Benutzer auf der Backup-Festplatte.

--step6

Erzeugt oder aktualisiert weitere Konfigurationsdateien für die verwendeten Tools (Import/Export), ebenfalls auf Basis der aktuellen kopano.userlist.csv. Nach Änderungen an der CSV erneut ausführen.

--step7

Exportiert bzw. aktualisiert die E-Mail-Nachrichten (Maildir-Struktur) der Benutzer auf der Backup-Festplatte.

Besonderer Hinweis!

In Kombination mit --use-imapsync können Mails direkt von Kopano zu IServ synchronisiert werden (Echtzeit, ohne Zwischenspeicher). Beide Systeme müssen parallel laufen und sich per Netzwerk erreichen!

--step8

Erstellt zusätzliche Metadaten, z. B. die Datei kopano.userlist-extra.yaml mit Alias-Adressen und Verteilerlisten („Distribution Lists“). Hilfreich, um Aliasse und Verteiler später in IServ manuell nachzubilden.

1.2 Funktionsweise von task2_export-kopano-stores.sh

Das Shell-Skript verwendet für den E-Mail-Nachrichtenexport das IMAP-Tool offlineimap3. Es ist so aufgebaut, dass es mehrfach aufgerufen werden kann, um nachträglich neue Nachrichten (differenziell) zu synchronisieren.

Bei sehr großen E-Mail-Postfächern kann der Export entsprechende Zeit in Anspruch nehmen. offlineimap3 ermöglicht zwar das parallele Exportieren mehrerer Postfächer (Threads), das Exportieren eines einzelnen großen Postfachs kann trotzdem mehrere Stunden in Anspruch nehmen.

Daher ist es empfehlenswert, den Export der IMAP-Postfächer bereits einige Tage vor dem vereinbarten Migrationstermin zu starten und zum eigentlichen Migrationstermin nur noch die zwischenzeitlich neu eingegangenen Nachrichten nachzusynchronisieren.

Dem Hilfetext des Skripts ist außerdem zu entnehmen, dass vor dem Nachrichtenexport weitere Schritte ausgeführt werden, z. B.:

Export von Kalenderobjekten
Export von Kontaktobjekten

Diese Exporte erfolgen über das Tool kopano-rfcdump.py in den Schritten 4 und 5. Sie sind bewusst vorgezogen, da sie im Vergleich zum Nachrichtenexport deutlich schneller ablaufen.

1.3 Konfigurationsdatei für task2_export-kopano-stores.sh

Das Skript task2_export-kopano-stores.sh benötigt zwingend eine individuelle Konfigurationsdatei. Darin werden unter anderem folgende Angaben hinterlegt:

Pfade für den Datenexport auf die bereits eingehängte Backup-Festplatte.
ein LogoDIDACT-Admin (für den Export),
ein IServ-Admin (für den späteren Import).

Wichtig

Diese Admin-Konten sind keine generischen Accounts; sie müssen über die nötigen Rechte verfügen, um auf alle Postfächer zugreifen zu können.

Die Konfigurationsdatei sollte im gleichen Verzeichnis liegen wie das Skript, also im Ordner /root/migration/ im LXC-Container kopano-g1. Der Dateiname sollte kopano_backup.config lauten, wie in der dazugehörigen Abbildung gezeigt.

Solange diese Konfigurationsdatei nicht existiert, bricht das Skript beim Start mit einem Fehler ab und gibt Beispielzeilen für eine Konfiguration auf der Konsole aus. Zunächst eine Beispiel-Konfigurationsdatei erzeugen durch Aufruf des folgenden Kommandos:

kopano-g1
1	`./task2_export-kopano-stores.sh --save-examplecfg`

Die erzeugte Konfigurationsdatei kopano_backup.config muss nun mit einem Texteditor bearbeitet, mit sinnvollen Werten ergänzt und anschließend wieder abgespeichert werden.

Im unteren Bereich der Konfigurationsdatei werden die Zugangsdaten für den LogoDIDACT-Admin und den IServ-Admin eingetragen.

Die konkrete Vergabe der notwendigen Rechte für den IServ-Admin wird später in der Anleitung beschrieben. Für den Export der Postfachdaten unter LogoDIDACT sind jedoch bereits jetzt die korrekten Rechte des LogoDIDACT-Admins entscheidend.

alt text

1.4 Kopano-Adminrechte des LogoDIDACT-Admins prüfen und setzen

Ob der LogoDIDACT-Admin die benötigten Kopano-Adminrechte besitzt, kann im LXC-Container mit dem Kommandozeilen-Tool kopano-admin geprüft werden.

kopano-g1
kopano-admin --sync

kopano-admin --details [username-des-admin]

(meistens 'admin')

In der Ausgabe muss ersichtlich sein, dass der betreffende Benutzer Kopano-Administrator ist:

alt text

1.5 Nachträglichen Kopano-Admin einrichten

Wichtig

Dieser Schritt muss lediglich dann erfolgen, wenn keine Administratorberechtigungen gelistet sind.

logosrv
# Ins OpenLDAP des Benutzerkontos das Attribut zarafaadmin=1 speichern, um das Konto zum Kopano-Administrator hochzustufen
# Username im Pfad bei uid= ggf. austauschen, falls admin nicht auf die Umgebung zutrifft
echo 1 >/var/lds/ldap/ou=users/uid=admin/zarafaadmin

kopano-g1
# Änderung anwenden durch Synchronisierung der LDAP-Einstellungen
kopano-admin --sync

# Kontrollieren, dass Konto nun Kopano-Administrator ist
kopano-admin --details [username-des-admin]

1.6 Erster vollständiger Export aller Kopano-Postfächer

Sind Konfigurationsdatei und Rechte korrekt eingerichtet, kann der erste vollständige Export gestartet werden. Um alle Kopano-Benutzer zu exportieren, wird das Skript mit dem Schalter --all aufgerufen.

Gefährlich

Um ungewollte Abbrüche zu verhindern, sollte das Skript in einer Screen-Sitzung gestartet werden!

1.7 Skript ausführen

kopano-g1
./task2_export-kopano-stores.sh -c /root/migration/kopano_backup.config --all

Nach erfolgreichem Durchlauf befinden sich die exportierten Daten im Verzeichnis /backup/ld-kopano-stores/ (wie in der Konfiguration angegeben).

Die Exportstruktur ist typischerweise:

mailboxes/ – E-Mail-Nachrichten im Maildir-Format
calendars/ – Kalenderdaten im ICS-Format (*.ics)
contacts/ – Kontakte im vCard-Format (*.vcf)

Zur Zuordnung der Inhalte sind jeweils Unterordner pro Kopano-Benutzer vorhanden, und zwar sowohl unter mailboxes/ als auch unter calendars/ und contacts/

alt text

Im Rahmen von Schritt --step8 legt das Skript zusätzlich die Datei kopano.userlist-extra.yaml auf der Backup-Festplatte ab.

Diese Datei enthält:

Informationen zu E-Mail-Aliasadressen,
Informationen zu Kopano-Verteilergruppen (Distribution Lists).

Diese Informationen sind hilfreich, zum Beispiel wenn:

Benutzer in IServ wieder mit Mail-Aliasadressen ausgestattet werden sollen,
Verteilerlisten in IServ manuell neu angelegt werden müssen.

Ein Automatismus für die Rekonstruktion von Verteilern in IServ existiert nicht, die Neuanlage kann aber über den entsprechenden Menüpunkt erfolgen (sofern das Modul "Verteilerlisten" installiert ist).

Zur Veranschaulichung ist der Export aller Kopano-Postfächer in einem Video demonstriert.

Hinweis!

In produktiv genutzten LogoDIDACT Installationen ist - anders als im Demo-Video - davon auszugehen, dass jeder Schritt sehr viel mehr Zeit in Anspruch nehmen wird. Speziell der Schritt 7 "IMAP-Nachrichtenexport" unter Umständen beim ersten Durchlauf auch mehr als 1 Tag, falls extrem große Postfächer existieren.

2. Weitere Exportdurchläufe (differentielle Nachsynchronisierung)

Wenn zwischen dem ersten Export und dem finalen Migrationstermin noch Zeit liegt, kann das Skript später erneut ausgeführt werden, um geänderte Daten nachzuziehen. Dabei können einzelne Schritte ausgelassen werden, die bereits erledigt wurden.

Typischer Ablauf für einen zweiten oder weiteren Export:

ldhost
screen -S mbox_export
ssh kopano-g1
cd ~/migration
# Hier ist nun das Export-Skript sowie die zugehörige Config bereits ableget.
# Eine kopano.userlist.csv Datei sollte ebenfalls aus dem ersten Durchlauf bereits existieren.

Hinweise

Statt einen Komplettablauf mit --all zu wiederholen, können nun gezielt einzelne Schritte des Skripts genutzt werden (z. B. --step4 für Kalender, --step5 für Kontakte, --step7 für E-Mails).

Die Neuerstellung der Kopano-Benutzerliste (Schritt --step2) ist nur notwendig, wenn seit dem ersten Export neue Benutzer auf dem LD-Server angelegt wurden. Andernfalls kann auf die bestehende kopano.userlist.csv zurückgegriffen werden.

Diese CSV-Datei kann auch im Texteditor bearbeitet werden, um Konten zu entfernen, deren Daten nicht nach IServ migriert werden sollen.

alt text

3. Abschließende Arbeiten unter LogoDIDACT zum Migrationszeitpunkt

Sobald alle Kopano-Exportdaten auf dem gewünschten Stand sind und die Umschaltung des Mailsystems bevorsteht, werden folgende Schritte durchgeführt.

Achtung

Ab diesem Zeitpunkt dürfen die Export-Tools nicht mehr verwendet werden!

3.1 Abruf von neuen Nachrichten per POP3 am Server deaktivieren

Das Tool getmail wird samt zugehörigen Konfigurationsdateien aus dem LXC-Container kopano-g1 entfernt. So ist sichergestellt, dass neuen Nachrichten nicht mehr vom CatchAll-Postfach abgerufen werden.

ldhost
1	`ssh puppeteer`

puppeteer
# Abruf von neuen Nachrichten per POP3-Abruf am Server deaktivieren
cd /etc/logodidact/
# ld_multidrop Einstellung von 'present' auf 'absent' ändern
sed -i -E 's/^(ld_multidrop::ensure: *)present/\1absent/g' /etc/logodidact/hiera/custom.d/kopano-g1.yaml
# Die Änderungen wieder ins git speichern
git commit -a -m "getmail Service im kopano-g1 Container deaktiviert"

ldhost
1	`ssh kopano-g1`

kopano-g1
# Zugangsdaten POP3-Abruf zur Sicherheit entfernen
rm /etc/getmailrc.*
systemctl restart getmail.service
# Änderung aus Puppet anwenden (deinstalliert getmail Paket)
prun

3.2 Exportierte Daten an IServ anpassen

Dies läuft über ein weiteres Skript, welches in Python umgesetzt ist.

kopano-g1
1	`/opt/export-tools/kopano-folders/migrate_mailboxes.py`

Das Skript übernimmt unter anderem:

Umwandlung von IMAP-UTF7-Ordnernamen nach UTF-8 (wichtig für Umlaute und Sonderzeichen),
Umbenennung deutscher Standardordner in englische Standardordner (passend zu IServ),
Entfernung ungültiger Sonderzeichen in Ordnernamen,
weitere Umbenennungen für die Zuordnung, z. B. Benutzername/calendar in Benutzername/home.

Vor jeder Umbenennung werden die geplanten Aktionen angezeigt und müssen bestätigt werden. Die Änderungen werden in Logdateien unterhalb von /backup/ld-kopano-stores/logs/ protokolliert.

Nach Abschluss werden zusätzlich Kalender-Ordnernamen normalisiert (--calendars) und vorgeschlagene Kontakte mit einem weiteren Aufruf von migrate_mailboxes.py bei Bedarf gelöscht (--delete-suggested-contacts).

3.3 Ausführung

ldhost
1	`ssh kopano-g1`

kopano-g1
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv python install python3.8
cd /opt/export-tools/kopano-folders
uv sync
for folder in /backup/ld-kopano-stores/mailboxes/ /backup/ld-kopano-stores/calendars/ /backup/ld-kopano-stores/contacts/; do \
  uv run migrate_mailboxes.py --dir $folder --step normalize --log-path /backup/ld-kopano-stores/logs/ ; \
  uv run migrate_mailboxes.py --dir $folder --step translate --log-path /backup/ld-kopano-stores/logs/ ; \
done
uv run migrate_mailboxes.py --dir /backup/ld-kopano-stores/calendars/ --calendars --log-path /backup/ld-kopano-stores/logs/
uv run migrate_mailboxes.py --dir /backup/ld-kopano-stores/contacts/ --delete-suggested-contacts --log-path /backup/ld-kopano-stores/logs/

3.4 Backup-Festplatte trennen

ldhost
systemctl stop lxc@kopano-g1; lxc-stop -n kopano-g1

Die Backup-Festplatte vom Mountpunkt /var/backups/lxc/kopano-g1 aushängen.

ldhost
1	`umount /var/backups/lxc/kopano-g1`

Danach den Kopano-LXC wieder starten oder den LD-Server herunterfahren – abhängig vom geplanten Migrationsszenario.

4. DNS-Anpassungen für den Umstieg auf IServ

Für einen reibungslosen Umstieg müssen:

alle bisherigen Mailadressen in IServ wieder so angelegt werden, wie sie zuvor existiert haben
passende Zielpostfächer für den Import der Kopano-Daten bereitstehen.

Im DNS der verwendeten Maildomäne müssen insbesondere folgende Einträge angepasst werden:

MX-Record (Zustellung eingehender E-Mails),
TXT-SPF-Record (Autorisierung der IServ-Mailrelay-Server).

4.1 Beispiel MX-Anpassung

Vorher:

meine-schul-maildomain.de MX 10 pmg.schulkennung.logoip.de

Nachher:

meine-schul-maildomain.de MX 10 iserv-hostname.xyz

meine-schul-maildomain.de MX 50 offline.iserv.eu

Wichtig

iserv-hostname.xyz muss durch den tatsächlichen IServ-Hostname der Schule ersetzt werden.

Eventuell vorhandene zusätzliche MX-Records sollten entfernt werden, sofern sie nicht mehr benötigt werden.

4.2 Beispiel SPF-Anpassung

Vorher:

meine-schul-maildomain.de TXT "v=spf1 a mx -all"

Nachher:

meine-schul-maildomain.de TXT v=spf1 a mx a:relay1.iserv.eu a:relay2.iserv.eu a:relay3.iserv.eu a:relaybs.iserv.eu ?all"

Info

Je nach TTL und DNS-Infrastruktur können die Änderungen typischerweise zwischen einer Stunde und einem Tag benötigen, bis sie weltweit wirksam sind. Die Einlieferung neuer E-Mails in die Domain ist unabhängig von den bereits migrierten Postfachdaten. Bereits importierte Nachrichten bleiben erhalten.

Weiterführende Informationen zur DNS-Konfiguration können Sie hier finden: IServ DNS Doku

5. Mail-Import in IServ

Hinweis

Vor dem Import müssen in der IServ-Verwaltung alle Benutzerkonten angelegt sein, für die Kopano-E-Maildaten wiederhergestellt werden sollen. Ohne diese Benutzer existieren keine Zielpostfächer.

In der IServ-Dokumentation finden Sie alle Hinweise zum Importieren von Benutzern: IServ Benutzer Import

Alternativ finden Sie unter LD-User-Export (Nutzerübernahme) eine Anleitung zur Übernahme der Konten direkt aus LogoDIDACT.

5.1 IServ vorbreiten

Nun wird die Festplatte an den Server angeschlossen, im IServ nach /mnt gemountet und anschließend die benötigten Importtools über den apt-Paketmanager hinzugefügt.

IServ
mount LABEL=USB-BACKUP -o noatime /mnt
cd /mnt/ld-kopano-mailimport/
# Benötigte Tools installieren
apt install git offlineimap python3-rfc6555 vdirsyncer

Hinweis

Der Pfad zur Partition der Backup-Disk muss ggf. angepasst werden.

5.2 Identitätsabgleich

Im eingehängten Pfad /mnt/ld-kopano-stores/ befindet sich die Datei kopano.userlist.csv mit drei Spalten:

Kopano-Benutzername (LogoDIDACT),
Linux-Accountname (LogoDIDACT),
IServ-Benutzername (Zielkonto).

Wir gehen im Weiteren davon aus, dass die IServ-Benutzernamen dem Schema vorname.nachname entsprechen. Bei Abweichungen (Lehrerkürzel, sehr lange Namen etc.) muss die Datei angepasst werden.

Alt Text

Mittels des Skriptes ld-iserv-usermapping.sh kann nun die Mapping-Datei kopano.userlist.csv verarbeitet/angepasst werden.

Wichtig

Es empfiehlt sich, den Modus --check unter Angabe der CSV-Mappingdatei /mnt/ld-kopano-stores/kopano.userlist.csv mindestens einmal auszuführen. Dabei prüft das Skript, ob alle IServ-Benutzernamen (aus Spalte 3) bereits angelegt sind. Sollten Benutzer fehlen, gibt das Skript einen Fehler aus und listet die Zeile des fehlenden Benutzers auf.

alt text

Zur Überprüfung der Benutzernamen also den Check-Modus aufrufen.

IServ
cd /mnt/ld-kopano-stores/
bash ld-iserv-usermapping.sh --check -m kopano.userlist.csv

5.3 Beispielausgabe nach Fehlermeldung

Das nachfolgende Bild zeigt, dass der Nutzer "tte" nicht gefunden werden konnte. Es handelt sich möglicherweise um ein Lehrerkonto, welches in LogoDIDACT mittels Lehrerkürzel als Accountnamen importiert wurde und innerhalb der IServ Schulplattform unter dem Schema Vorname.Nachname angelegt wurde:

alt text

Um nun die Datenmigration zu ermöglichen, muss die Mapping-Datei bearbeitet werden um darin in der Zeile des betroffenen Benutzers (line 6) einen gültigen IServ Account in der Spalte 3 (Zielkonto) zu hinterlegen.

Dieser Vorgang wird nun wiederholt, bis --check keine Fehlermeldung mehr anzeigt. Anschließend kann mittels des Parameters --patch die Korrektur überführt werden.

Hinweis

Bei Unklarheiten existiert im Backup-Pfad (/mnt/ld-kopano-stores/) eine zusätzliche YAML-Datei kopano.userlist.yaml, welche ausführliche Informationen zu den LogoDIDACT Benutzerkonten beinhaltet. Diese Datei muss nicht bearbeitet werden, sie dient ausschließlich dem Heranziehen zusätzlicher Informationen.

5.4 Import-Konfigurationsdateien patchen

Sind alle Namen korrekt, wird der Modus --patch verwendet, um die Importkonfigurationen anzupassen:

IServ
cd /mnt/ld-kopano-stores/
bash ld-iserv-usermapping.sh --patch=all -m kopano.userlist.csv --backupdir=/mnt/ld-kopano-stores/

Betroffene Dateien im Backupverzeichnis /mnt/ld-kopano-stores/:

offlineimap.iserv.mailboxes.importlist.config – wird für den IMAP-Mailimport verwendet. Die Datei wird durch die Schalter --patch=mailboxes sowie --patch=all aktualisiert.
vdirsyncer.iserv.calendars.importlist.config – wird für den Kalenderimport per CalDAV verwendet. Die Datei wird durch die Schalter --patch=calendars sowie --patch=all aktualisiert.

Hinweis

Der Patch-Modus sollte auch dann einmal aufgerufen werden, wenn keine Änderungen in der Mapping-Datei kopano.userlist.csv erfolgt sind. Im Patch-Modus wird nämlich auch nach Konten gesucht, die ggf. nicht im IServ angelegt sind, beispielsweise weil es sich um ausgeschiedene Benutzer handelt. Solche Konten können im Patch-Modus auskommentiert werden durch eine Abfrage während der Verarbeitung.

Die erste Anpassung, für die Postfach Import-Konfigurationsdatei: alt text

Die zweite Anpassung, für die Kalender Import-Konfigurationsdatei: alt text

6. Importieren der IMAP-Postfächer mittels Import-Skript

Die nachfolgenden Schritte beschreiben den Import der Postfächer in die IServ Schulplattform. Für den Datenimport wird u.a. auf das Tool offlineimap3 zurückgegriffen.

6.1 Einbinden der Backup-Festplatte vor dem Postfach-Import

Hinweis

Dieser Schritt kann übersprungen werden, wenn dieser Dokumentation chronologisch gefolgt wurde, da das Backup-Verzeichnis in diesem Fall schon eingehängt ist.

(Label/Pfad zur Backup-Partition ggf. anpassen)

IServ
mount LABEL=USB-BACKUP -o noatime /mnt
cd /mnt/ld-kopano-mailimport/
# Benötigte Tools ggf. nachinstallieren
apt install git offlineimap python3-rfc6555

6.2 Import der Postfächer mittels import-to-iserv-helper.sh

Es wird ein Import-Skript import-to-iserv-helper.sh zur Verfügung gestellt, welches den Import aus den Kopano-Backupdaten ins IServ ermöglicht. Das Skript besitzt mehrere Modi, die über den Hilfe-Text eingesehen werden können und abhängig vom Modus unterschiedliche, zusätzliche Angaben erfordern.

alt text

Wichtig

Vor diesem Schritt muss der Identitätsabgleich, also das Mapping der Benutzeraccounts aus dem vorherigen Abschnitt 5. ohne Fehler durchgelaufen sein, damit alle Postfächer den ursprünglichen Nutzern zurückgespielt werden können! Ebenfalls muss der Patch-Modus aufgerufen worden sein, um die Zielkonten in der Import-Konfigurationsdatei offlineimap.iserv.mailboxes.importlist.config zu aktualisieren.

Für den Nachrichtenimport der Postfächer gibt es im Import-Skript import-to-iserv-helper.sh einen eigenen Ausführungsmodus. Das Skript arbeitet darin folgende Schritte ab:

Es dient als Wrapper for offlineimap3 und führt einige Vorbereitungen im IServ automatisch durch, bevor der Datenimport erfolgt.
Vorab wird automatisch ein temporärer Import-Benutzer iserv-ld-maildata-import angelegt, der administrative Rechte für den Zugriff auf Postfächer + Kalender von Benutzern erhält.
Ebenfalls werden die Verbindungsdaten in der Konfigurationsdatei offlineimap.iserv.mailboxes.importlist.config ausgetauscht, damit sie zur lokalen IServ Installation passen.

Der Import benötigt (abhängig von der Postfachgröße und Benutzeranzahl) einiges an Zeit, deswegen muss der Aufruf innerhalb einer Screen-Session stattfinden.

IServ
screen -S kopano_import
cd /mnt/ld-kopano-stores/

Zum Importieren der IMAP-Postfächer wird der Ausführungmodus --run=mailboxes verwendet und zusätzlich die Import-Konfigurationsdatei über ein Argument mitgegeben.

IServ
bash import-to-iserv-helper.sh --run=mailboxes \
 --importconfig=/mnt/ld-kopano-stores/offlineimap.iserv.mailboxes.importlist.config

Nach Bestätigung des Aufrufs startet der Mailbox-Import, parallel für die Anzahl an Postfächern, so wie im Parameter maxsyncaccounts des ConfigFile angegeben. Der Standardwert liegt hier bei 4 parallelen Importprozessen. In großen Umgebungen kann eine Anhebung auf 8 Worker-Prozesse den Vorgang beschleunigen.
Es werden während der Ausführung Logdateien generiert, die im Verzeichnis /root/ld-kopano-mailimport/importlogs/ gespeichert liegen.
Der Vorgang kann beliebig oft wiederholt werden, sollten beim Import vereinzelte Fehler auftreten.
Im oberen Abschnitt [general] des ConfigFile sind unter accounts= alle Konten gelistet, die beim Import verarbeitet werden. Diese Liste kann auf einzelne Konten reduziert werden, um bei einer Wiederholung den Import auf gezielte IMAP-Postfächer zu beschränken.

alt text

Nach dem Durchlaufen des Importskriptes kann zur Kontrolle die zugehörige Logdatei /root/ld-kopano-mailimport/importlogs/offlineimap.iserv.mailboxes.import.log gesichtet werden.

alt text

Darin findet man pro Zielkonto folgende Information:

Finished Account (username) in xx:xx (Zeitangabe in Min)

Der Ablauf zum Importieren der Benutzer-Postfächer ins IServ ist zur Veranschaulichung in einem Beispiel-Video festgehalten.

6.3 Zurücksetzen besonderer IServ-Einstellungen nach dem Postfach-Import

Sofern keine weiteren Kopano-Daten mehr importiert werden sollen, bitte abschließend mit Abschnitt 9. fortfahren zum Entfernen der temporären IServ Einstellungen.

Hinweis

Falls jedoch auch noch Kalender-Daten oder Kontakte importiert werden sollen, weiterhin chronologisch dieser Anleitung folgen und mit den Abschnitten 7. bzw. 8. fortsetzen.

7. Importieren der Kalenderdaten

Die nachfolgenden Schritte beschreiben den Import der Kalenderdaten in die IServ Schulplattform. Für den Datenimport wird u.a. auf das Tool vdirsyncer zurückgegriffen.

7.1 Einbinden der Backup-Festplatte vor dem Kalender-Import

Hinweis

Dieser Schritt kann übersprungen werden, wenn dieser Dokumentation chronologisch gefolgt wurde, da das Backup-Verzeichnis in diesem Fall schon eingehängt ist.

(Label/Pfad zur Backup-Partition ggf. anpassen)

IServ
mount LABEL=USB-BACKUP -o noatime /mnt
cd /mnt/ld-kopano-mailimport/
# Benötigte Tools ggf. nachinstallieren
apt install vdirsyncer

7.2 Import der Kalender mittels import-to-iserv-helper.sh

Für den Kalender-Import wird wieder auf das Import-Skript import-to-iserv-helper.sh zurückgegriffen. Dieses besitzt auch einen Kalender-Ausführungsmodus, der im Hilfe-Text mit einem entsprechenden Beispiel aufgeführt ist.

Wichtig

Vor diesem Schritt muss der Identitätsabgleich, also das Mapping der Benutzeraccounts aus dem vorherigen Abschnitt 5. ohne Fehler durchgelaufen sein, damit alle Kalenderdaten den ursprünglichen Nutzern zurückgespielt werden können! Ebenfalls muss der Patch-Modus aufgerufen worden sein, um die Zielkonten in der Import-Konfigurationsdatei vdirsyncer.iserv.calendars.importlist.config zu aktualisieren.

Es ist möglich, dass Benutzer unter Kopano zusätzliche Kalender (sog. Collections) für sich selbst angelegt haben. Das Führen von mehreren Kalendern wird auch in IServ unterstützt. Solche zusätzliche Kalender können in der IServ Weboberfläche unter "Kalender verwalten" → "Eigene Kalender" bei Bedarf von Benutzern angelegt werden, sie lassen sich in der Kalenderverwaltung auch gruppieren.

Das Import-Skript import-to-iserv-helper.sh arbeitet im Kalender-Modus nach folgender Funktionsweise:

Der Kalender-Import ist in zwei Phasen unterteilt, die automatisch nacheinander ausgeführt werden.
In der ersten Phase werden innerhalb der Kalender-Benutzerverzeichnisse die Unterordner gelistet, die aus Kopano exportiert wurden und somit Collections darstellen.
Mit diesen Namen werden die zusätzlichen Collections über http-Requests bzw. Datenbank-Inserts für die Benutzerkonten erstellt, die in der CSV Mapping-Datei kopano.userlist.csv aufgeführt sind.
Es handelt sich zunächst lediglich um "Hüllen", damit die zusätzlichen Kalender in der IServ Oberfläche sichtbar und für Benutzer anwählbar sind.
Sofern die Erstellung der Kalender in Phase 1 fehlerfrei abgearbeitet wurde, wird automatisch mit Phase 2 fortgesetzt. Beim Auftreten eines Fehlers bricht das Skript hingegen ab und liefert eine entsprechende Warnmeldung an der Shell.
In Phase 2 dient das Import-Skript als Wrapper für vdirsyncer, um die eigentlichen Kalenderdaten per CalDAV-Protokoll pro Benutzer zu importieren.
In der Konfigurationsdatei vdirsyncer.iserv.calendars.importlist.config werden die Verbindungsdaten ausgetauscht, damit sie zur lokalen IServ Installation passen.
Sofern noch nicht durch den vorherigen Postfach-Import geschehen, wird ein temporärer Import-Benutzer iserv-ld-maildata-import angelegt, der administrative Rechte auf die Kalender von Benutzern erhält.
Falls in den Backup-Daten vorhanden, werden neben den Benutzer-Kalendern zusätzlich die .ics Dateien aus ./public/calendar/ in den Öffentlichen Kalender des IServ importiert.

Der Import benötigt (abhängig von der Anzahl an Kalendern und Terminen) wieder einiges an Zeit, deswegen muss der Aufruf innerhalb einer Screen-Session stattfinden.

IServ
screen -S kopano_import
cd /mnt/ld-kopano-stores/

Zum Importieren der Kalender wird wie erläutert der Ausführungmodus --run=calendars verwendet und zusätzlich die Import-Konfigurationsdatei, die Mapping-Datei kopano.userlist.csv sowie das Kalender-Quellverzeichnis auf der Backup-Disk über entsprechende Argumente mitgegeben.

IServ
bash import-to-iserv-helper.sh --run=calendars \
 --importconfig=/mnt/ld-kopano-stores/vdirsyncer.iserv.calendars.importlist.config \
 --mapfile=/mnt/ld-kopano-stores/kopano.userlist.csv \
 --sourcedir=/mnt/ld-kopano-stores/calendars/

Hinweis

Auch dieser Importmodus kann mehrfach ausgeführt werden, um Kalenderinhalte für IServ-Konten zu importieren.

alt text

Es werden Logdateien für die Erstellung und den Import der Kalender erzeugt.

für die Erstellung der Collections in Phase 1 sind pro Benutzer im Ordner /root/ld-kopano-stores/importlogs/create_calendars/ Logs gespeichert
der Kalender-Datenimport in Phase 2 generiert ebenfalls eine Logdatei, der Pfad hierzu lautet /root/ld-kopano-stores/importlogs/vdirsyncer.iserv.calendars.import.log

alt text

Anbei exemplarisch eine mögliche Fehlermeldung des vdirsyncer Tools aus Phase 2, die jedoch als unkritisch zu betrachten ist, weil es um bereits vorhandene Kalendereinträge beim IServ Zielbenutzer geht und der Import wiederholend aufgerufen wurde.

alt text

Der Ablauf zum Importieren der Benutzer-Kalender ins IServ ist ebenfalls in einem Beispiel-Video festgehalten.

7.3 Zurücksetzen besonderer IServ-Einstellungen nach dem Kalender-Import

Sofern keine weiteren Kopano-Daten mehr importiert werden sollen, bitte abschließend mit Abschnitt 9. fortfahren zum Entfernen der temporären IServ Einstellungen.

Hinweis

Falls jedoch auch noch Kontakte importiert werden sollen, weiterhin chronologisch dieser Anleitung folgen und mit dem Abschnitt 8. fortsetzen.

8. Importieren der Kontaktdaten

Die nachfolgenden Schritte beschreiben den Import der Kontaktdaten in die IServ Schulplattform.

8.1 Einbinden der Backup-Festplatte vor dem Kontakte-Import

Hinweis

Dieser Schritt kann übersprungen werden, wenn dieser Dokumentation chronologisch gefolgt wurde, da das Backup-Verzeichnis in diesem Fall schon eingehängt ist.

(Label/Pfad zur Backup-Partition ggf. anpassen)

IServ
mount LABEL=USB-BACKUP -o noatime /mnt
cd /mnt/ld-kopano-mailimport/

8.2 Import der Kontakte mittels import-to-iserv-helper.sh

Es wird wieder auf das Import-Skript import-to-iserv-helper.sh zurückgegriffen, welches auch einen Kontakte-Modus hat und zum Importieren der Backup-Daten vorgesehen ist.

Wichtig

Vor diesem Schritt muss der Identitätsabgleich, also das Mapping der Benutzeraccounts aus dem vorherigen Abschnitt 5. ohne Fehler durchgelaufen sein, damit alle Kontakte den ursprünglichen Nutzern zurückgespielt werden können! Der Patch-Modus zum Ändern einer Import-Konfigurationsdatei ist im Falle der Kontaktdaten nicht erforderlich, die .vcf Dateien werden direkt per http-Requests mit curl importiert.

Das Import-Skript wird nun mit den notwendigen Schaltern aufgerufen und dadurch ein Import der .vcf Kontaktdateien für die zugehörigen IServ Zielbenutzer angestoßen. Es gelten hierbei folgende Regeln:

der Import findet lediglich für Benutzer statt, die in der Mapping-Datei kopano.userlist.csv enthalten sind
in der angegebenen Kontakte-Datenquelle /mnt/ld-kopano-stores/contacts/ liegen Unterordner für die jeweiligen Benutzer. Hier werden .vcf Dateien gesucht und ggf. importiert, sofern Dateien vorhanden sind.
alle Kontakte werden in das IServ "Eigenes Adressbuch" importiert, unabhängig davon, wie sie vorher unter Kopano abgespeichert waren (z.B. verschachtelt oder aufgeteilt in mehrere Adressbücher)
bei mehrfachem Aufruf des Import-Skripts werden bereits importierte Kontakte nicht überschrieben, sondern der Import dieser Elemente dann ignoriert

Der Import benötigt (abhängig von der Anzahl an Kontaktdaten) wieder etwas Zeit zur Verarbeitung. Deswegen muss der Aufruf innerhalb einer Screen-Session stattfinden.

IServ
screen -S kopano_import
cd /mnt/ld-kopano-stores/

Der Import der Kontakte kann durch Selektion des Modus --run=contacts sowie den notwendigen Angaben zur Mapping-Datei kopano.userlist.yaml und des Kontakte-Quellverzeichnis über die entsprechenden Schalter gestartet werden.

IServ
bash import-to-iserv-helper.sh --run=contacts \
 --mapfile=/mnt/ld-kopano-stores/kopano.userlist.csv \
 --sourcedir=/mnt/ld-kopano-stores/contacts/

alt text

Hier im Beispiel ist während des Kontakte-Import alles fehlerfrei abgearbeitet worden. Zwecks Nachvollziehbarkeit werden Logdateien für die Vorgänge generiert, pro Benutzer eine Logdatei. Die Protokolleinträge sind im Verzeichnis /root/ld-kopano-stores/importlogs/contacts/ gespeichert und beinhalten neben der Menge importierter Kontakte einen Zeitstempel.

alt text

Der Ausführungsmodus zum Importieren der Kontakte kann ebenfalls in einem Demo-Video angesehen werden.

Für den Import der .vcf Kontaktdateien wurden keine besonderen Rechte am Server festgelegt. Falls noch nicht in den vorherigen Schritten geschehen, sollte abschließend dennoch der Cleanup-Modus des Import-Skript aufgerufen werden. Im Demo-Video findet dieser Abschlusschritt ebenfalls statt.

9. Zurücksetzen besonderer IServ Import-Einstellungen (ACL-Reset)

Über das Import-Skript import-to-iserv-helper.sh sollte abschließend der Cleanup-Modus aufgerufen werden, um alle temporären Einstellungen und den Import-Benutzer aus der IServ Installation zu entfernen.

IServ
cd /mnt/ld-kopano-stores/
bash import-to-iserv-helper.sh --run=cleanup

Die zugehörigen Einstellungen, die hierbei auf die Standards zurückgesetzt werden, listet der Cleanup-Modus vorab an der Shell auf.

alt text

Nach Ausführung des Cleanup-Modus sind die IServ-Einstellungen in Bezug zum Cyrus IMAP-Server und den DAViCal Rollen zurückgesetzt und der temporäre Account iserv-ld-maildata-import ist wieder vom Server entfernt. Der Cleanup-Modus führt abschließend auch noch iservchk aus.