KeyHelp: Postfächer mit imapsync von einem anderen Server übernehmen

Wer Kunden von einem anderen Mailserver auf einen KeyHelp-Server holt, will die vorhandenen E-Mails mitnehmen: mit allen Ordnern, Unterordnern und Gelesen-Markierungen. Das Werkzeug dafür ist imapsync. Es meldet sich per IMAP am alten und am neuen Server an und kopiert alles, was im Ziel noch fehlt. Diese Anleitung richtet sich an Administratoren eines eigenen KeyHelp-Servers, wie er in KeyHelp installieren und absichern beschrieben ist. Sie zeigt den Ablauf vom leeren Zielpostfach über Probelauf und Kopie bis zum Abgleich kurz vor der DNS-Umstellung, dazu die Fehlermeldungen, die Sie bei falschem Passwort oder zu kleinem Postfach bekommen.

Voraussetzungen

• KeyHelp mit Kundenkonto und Domain, getestet mit KeyHelp 26.1.1 (Build 3698) auf Debian 12. Im Beispiel gehört die Domain kunde1.example.de dem Kunden „kunde1“.
• IMAP-Zugang zum alten Server: Hostname, Port, Benutzername und Passwort des Quellpostfachs. Ohne funktionierenden IMAP-Login geht es nicht, ein reiner Webmail-Zugang reicht nicht.
• SSH-Zugang als root zum KeyHelp-Server, um imapsync zu installieren und zu starten.
• Genug Speicherplatz im Kundenkontingent für die Größe des alten Postfachs.

Schritt 1: Zielpostfach in KeyHelp anlegen

imapsync legt keine Postfächer an, nur Ordner und Mails darin. Das Zielpostfach muss es also vorher geben. Als Kunde oder als Admin in der Kundensicht öffnen Sie „E-Mail“, „E-Mail-Adressen“ und klicken auf „E-Mail-Konto hinzufügen“. Tragen Sie unter „E-Mail-Adresse“ den lokalen Teil ein, im Beispiel umzug, und wählen Sie die Domain. Ein Passwort erzeugen Sie mit „Generieren“ unter „Passwortvorschlag“ und übernehmen es in beide Passwortfelder. Wichtig ist die „Postfachgröße“: Sie muss für den Inhalt des alten Postfachs reichen. KeyHelp schlägt 1 GiB vor, das Feld ist eine Obergrenze und reserviert keinen Speicher.

Nach „Speichern“ meldet KeyHelp „Das E-Mail-Konto umzug@kunde1.example.de wurde erfolgreich angelegt.“ Im Hintergrund legt KeyHelp einen Benutzer in der eigenen Dovecot-Benutzerdatenbank an, das Maildir liegt unter /var/mail/vhosts/DOMAIN/NAME und gehört dem Systembenutzer vmail. Die Postfachgröße landet als Quota-Regel bei Dovecot.

Verifizieren: Auf dem Server zeigt doveadm user das neue Postfach mit Pfad und Quota:

doveadm user umzug@kunde1.example.de
# home        /var/mail/vhosts/kunde1.example.de/umzug
# mail        maildir:/var/mail/vhosts/kunde1.example.de/umzug
# quota_rule  *:bytes=1073741824

Schritt 2: imapsync auf dem KeyHelp-Server installieren

imapsync steht nicht in den Debian-Paketquellen. Die offizielle Installationsanleitung für Debian auf imapsync.lamiral.info nennt zwei Wege: ein fertiges Paket imapsync.deb von der Projektseite oder die Perl-Abhängigkeiten per apt und danach das Skript selbst. Im Test haben wir den zweiten Weg genommen, das Skript nach /usr/local/bin gelegt und imapsync 2.314 verwendet. Die Liste der rund 30 Perl-Pakete steht in der Installationsanleitung.

cd /tmp
wget -N https://imapsync.lamiral.info/imapsync
install -m 755 imapsync /usr/local/bin/imapsync
imapsync --version

Starten Sie imapsync auf dem neuen KeyHelp-Server. Dann läuft die Verbindung zum Ziel über 127.0.0.1, nur die Verbindung zum alten Server geht über das Internet.

Verifizieren: imapsync ohne Optionen prüft beim Start die Perl-Module und gibt eine Liste mit Versionsnummern aus. Fehlt ein Modul, steht das dort. Im Test begann die Ausgabe mit „Here is imapsync 2.314 /usr/local/bin/imapsync on host server.example.de“.

Schritt 3: Passwörter in Dateien ablegen

imapsync kann Passwörter mit --password1 und --password2 direkt auf der Kommandozeile annehmen. Die imapsync-Dokumentation rät davon ab: Unter Linux sieht jeder Benutzer des Servers die Kommandozeile mit ps auxwwww. Sicherer sind --passfile1 und --passfile2 mit je einer Datei, deren erste Zeile das Passwort enthält, lesbar nur für root.

install -m 600 /dev/null /root/imap-alt.pw
install -m 600 /dev/null /root/imap-neu.pw
nano /root/imap-alt.pw   # Passwort des alten Postfachs, eine Zeile
nano /root/imap-neu.pw   # Passwort des neuen Postfachs aus KeyHelp

Verifizieren: ls -l /root/imap-*.pw zeigt -rw------- und root als Besitzer. In den Logdateien von imapsync tauchte das Passwort im Test nicht auf, eine Suche mit grep -F nach dem Passwort in allen Logs und Ausgaben lieferte keinen Treffer.

Schritt 4: Probelauf mit --dry und --justfolders

Die imapsync-Dokumentation empfiehlt für den Anfang die Kombination --dry --justfolders: Das Werkzeug meldet sich an beiden Servern an, liest die Ordnerlisten und zeigt, was es anlegen würde, ändert aber nichts. Im Test lief der Quellserver auf Port 10143 desselben Rechners. Bei einem echten Umzug setzen Sie unter --host1 den Namen des alten Mailservers ein und lassen --port1 meist weg; imapsync prüft selbst, ob der Server verschlüsselt antwortet, und nutzt dann SSL/TLS.

cd /root
imapsync \
  --host1 127.0.0.1 --port1 10143 \
  --user1 info@altserver.example.net --passfile1 /root/imap-alt.pw \
  --host2 127.0.0.1 --port2 993 --ssl2 \
  --user2 umzug@kunde1.example.de --passfile2 /root/imap-neu.pw \
  --dry --justfolders

Für das Ziel haben wir Port 993 mit --ssl2 gewählt. imapsync prüft das Zertifikat dabei standardmäßig nicht („SSL_VERIFY_NONE“), das ist bei 127.0.0.1 unkritisch. In der Ausgabe stehen die gefundenen Ordner des Quellservers und der Hinweis „does not exist yet“ für jeden Ordner, der im Ziel noch fehlt. Ordnernamen mit Umlauten zeigt imapsync doppelt, im IMAP-Format und lesbar: [Rechnungen B&APw-ro] = [Rechnungen Büro]. Am Ende steht eine Statistik mit „Messages transferred : 0 (could be 9 without --dry mode)“.

Wichtig für KeyHelp ist eine Zeile weiter oben im Log: Der Quellserver im Test trennte Ordner mit /, Dovecot in KeyHelp nutzt . („Host2: separator given by NAMESPACE: [.]“). imapsync rechnet das automatisch um, aus Projekte/2026 wird im Ziel Projekte.2026, in Roundcube erscheint daraus wieder der Unterordner „2026“ unter „Projekte“.

Verifizieren: Die letzte Zeile lautet „Exiting with return value 0 (EX_OK: successful termination)“, und „Host1 Nb folders“ nennt die erwartete Anzahl. Im Test waren es 7 Ordner und 14 Mails. Das Log liegt unter /root/LOG_imapsync/.

Schritt 5: Die eigentliche Kopie

Ist der Probelauf sauber, starten Sie denselben Befehl ohne --dry --justfolders. imapsync legt die fehlenden Ordner an („Created folder [Projekte.2026] on host2“) und kopiert jede Mail mit Datum und Markierungen. Das Ankunftsdatum übernimmt es ebenfalls („turned ON syncinternaldates“), sodass die Mails im neuen Postfach in der richtigen Reihenfolge stehen.

imapsync \
  --host1 127.0.0.1 --port1 10143 \
  --user1 info@altserver.example.net --passfile1 /root/imap-alt.pw \
  --host2 127.0.0.1 --port2 993 --ssl2 \
  --user2 umzug@kunde1.example.de --passfile2 /root/imap-neu.pw

Im Test meldete imapsync „Folders synced : 7/7 synced“, „Messages transferred : 14“ und „Detected 0 errors“. Ordner, die es im Ziel schon gibt, nutzt imapsync weiter: „Sent“ und „Trash“ heißen bei Dovecot in KeyHelp genauso, deshalb landeten die gesendeten Mails im vorhandenen Ordner „Gesendet“. Heißen die Sonderordner auf dem alten Server anders, etwa „Gesendete Objekte“, hilft die Option --automap, die laut Dokumentation bekannte Sonderordner zuordnet. Das haben wir nicht getestet, prüfen Sie es vorher mit --dry.

Verifizieren: doveadm mailbox status zählt die Mails je Ordner im Ziel. Die Zahlen müssen zu „Host1 Nb messages“ passen:

doveadm mailbox status -u umzug@kunde1.example.de messages '*'
# Sent messages=2
# Rechnungen Büro messages=3
# Projekte messages=1
# Projekte.2026 messages=2
# Archiv messages=1
# Trash messages=0
# INBOX messages=6

Im Posteingang standen 6 statt 5 Mails: KeyHelp legt beim Anlegen eines Postfachs eine Begrüßungsmail „Ihr Postfach wurde erfolgreich eingerichtet“ ab. imapsync lässt Mails, die nur im Ziel liegen, unangetastet.

Schritt 6: Zweiter Lauf vor der DNS-Umstellung

Zwischen erster Kopie und Umstellung der MX-Einträge kommen auf dem alten Server weiter Mails an. Deshalb starten Sie denselben Befehl ein zweites Mal, am besten unmittelbar nach der DNS-Änderung und noch einmal, wenn die alten Einträge abgelaufen sind. imapsync erkennt bereits kopierte Mails an Kopfzeilen wie Message-ID und überträgt nur, was fehlt. Im Test kamen nach dem ersten Lauf zwei Mails hinzu; der zweite Lauf meldete „Messages transferred : 2“, „Messages skipped : 14“ und brauchte 0,3 Sekunden.

Gelöschte Mails löscht imapsync im Ziel nicht. Laut Dokumentation gibt es keine Löschungen, solange Sie nicht ausdrücklich --delete2 setzen. Für einen Umzug ist das der sichere Standard.

Verifizieren: In der Statistik steht „Messages found in host1 not in host2 : 0 messages“, und Roundcube zeigt alle Ordner mit den erwarteten Zahlen. Melden Sie sich unter „Webmail“ mit dem neuen Postfach an.

Schritt 7: Umzug im Panel abschließen

Die Belegung des Postfachs zeigt KeyHelp unter „E-Mail-Adressen“ in der Spalte „Postfachgröße“. Die Anzeige wird nicht sofort aktualisiert: Direkt nach dem Umzug stand dort im Test noch „0 B / 1,00 GiB“, während Dovecot bereits rund 2 MB belegt meldete. Verlassen Sie sich für die Kontrolle deshalb auf doveadm quota get. Unter „Verbindungsdaten“, „Anzeigen“ liefert KeyHelp die Server- und Portangaben, die Ihr Kunde für sein Mailprogramm braucht. Wie Mailprogramme diese Daten selbst finden, steht in KeyHelp: E-Mail-Programme mit Autokonfiguration einrichten.

Verifizieren: doveadm quota get -u umzug@kunde1.example.de zeigt Speicher und Anzahl der Mails. Im Test standen dort 18 Nachrichten bei 2001 KiB. Löschen Sie nach dem Umzug die Passwortdateien mit rm /root/imap-*.pw. Die Logs unter /root/LOG_imapsync/ enthalten Betreffzeilen und Adressen; löschen Sie sie, sobald der Umzug abgeschlossen ist.

Typische Fehler

Falsches Passwort für den alten Server

imapsync bricht sofort ab und nennt die betroffene Seite. Im Test mit falscher Passwortdatei lautete die Meldung:

Host1 failure: Error login on [127.0.0.1] with user [info@altserver.example.net] auth [LOGIN]: 2 NO [AUTHENTICATIONFAILED] Authentication failed.
The most frequent error is ERR_AUTHENTICATION_FAILURE_USER1. Check the credentials for info@altserver.example.net.
Exiting with return value 161 (EXIT_AUTHENTICATION_FAILURE_USER1)

„Host1“ und „USER1“ stehen immer für die Quelle, „Host2“ für KeyHelp. Prüfen Sie, ob die Passwortdatei nur das Passwort in der ersten Zeile enthält.

Zielpostfach zu klein

Ist die Postfachgröße in KeyHelp kleiner als der Inhalt des alten Postfachs, lehnt Dovecot weitere Mails ab. Wir haben das Postfach testweise auf 1 MiB gesetzt und eine Mail mit rund 2 MB kopiert:

- msg Archiv/2 {2052864} could not append ( Subject:[Testmail 17 (grosser Anhang)] ... ) to folder Archiv:
  ... 38 NO [OVERQUOTA] Quota exceeded (mailbox for user is full)
The most frequent error is ERR_OVERQUOTA. The destination mailbox is 100% full, get free space on it and then resume the sync.
Exiting with return value 113 (EXIT_OVERQUOTA)

Erhöhen Sie die „Postfachgröße“ im Panel und starten Sie imapsync erneut. Die Änderung braucht laut Panel „wenige Augenblicke“; im Test war sie nach rund 20 Sekunden bei Dovecot angekommen, der nächste Lauf übertrug die fehlende Mail und übersprang den Rest. imapsync zeigt die Quota des Ziels übrigens schon zu Beginn an („Host2: Quota current storage is … Limit is …“), ein Blick darauf vor dem Start spart den Fehlschlag.

Ordner doppelt oder an der falschen Stelle

Benutzt der alte Server ein Präfix wie INBOX. vor allen Ordnern, landen die Ordner im Ziel unter „Posteingang“. Die Zeilen „prefix given by NAMESPACE“ im Log zeigen, was imapsync erkannt hat. Ein Probelauf mit --dry --justfolders deckt solche Fälle auf, bevor Mails kopiert werden.

Häufige Fragen

Muss der Kunde während des Umzugs auf E-Mails verzichten?

Nein. Der erste Lauf kann tagelang vor der Umstellung stattfinden, der alte Server bleibt in Betrieb. Nach der Änderung der MX-Einträge fangen die weiteren Läufe die Mails ab, die in der Übergangszeit noch beim alten Server angekommen sind.

Werden Gelesen-Markierungen übernommen?

Ja. Die Dokumentation nennt ausdrücklich die Flags wie gelesen, beantwortet und markiert. Bei weiteren Läufen gleicht imapsync die Markierungen bereits kopierter Mails erneut ab („will resync flags for already transferred messages“).

Braucht das Zielpostfach einen eigenen DNS-Eintrag?

Für die Kopie nicht, imapsync spricht KeyHelp über 127.0.0.1 an. Für den Mailempfang müssen MX und die Absenderprüfung stimmen, siehe SPF, DKIM und DMARC für Kundendomains.

Testumfang

Wir haben auf KeyHelp 26.1.1 ein Postfach mit 7 Ordnern, Unterordner und Umlaut-Ordner von einem zweiten Dovecot per imapsync 2.314 übernommen, mit Probelauf, Kopie, inkrementellem Lauf, falschem Passwort und zu kleiner Quota. Auffällig: Die Belegungsanzeige im Panel hinkt hinterher. Fremde Quellserver wie Exchange oder Gmail haben wir nicht getestet. Machen Sie bei jedem Umzug zuerst den Probelauf.

Fazit

Mit imapsync wird ein Postfachumzug nach KeyHelp planbar: Zielpostfach anlegen, Probelauf, Kopie und kurz vor sowie nach der DNS-Umstellung ein weiterer Lauf. Das Werkzeug kümmert sich um unterschiedliche Ordnertrenner und Umlaute und löscht im Ziel nichts. Die beiden häufigsten Stolpersteine, falsche Zugangsdaten und eine zu knappe Postfachgröße, meldet es eindeutig mit eigenem Rückgabewert. Passwörter gehören dabei in Dateien und nicht auf die Kommandozeile.

Weiterführende Anleitungen und Quellen

• KeyHelp installieren und absichern
• KeyHelp: Roundcube mit Abwesenheitsnotiz, Filtern und Weiterleitung
• KeyHelp: E-Mail-Programme mit Autokonfiguration einrichten
• KeyHelp: SPF, DKIM und DMARC für Kundendomains
• imapsync: Dokumentation (README) mit allen Optionen
• imapsync: Installation unter Debian
• KeyHelp-Wissensdatenbank: Allgemeine E-Mail-Client-Konfiguration
• Keyweb: KeyHelp, alle Funktionen im Überblick