How to migrate Maildir emails from a Plesk server to an ISPConfig server

Prerequisites

Before proceeding with this migration guide, ensure the following assumptions and preparations are in place:

• This process assumes the use of Debian GNU/Linux 12 (bookworm) as the operating system, Plesk Obsidian 18.0.71 Update #2 on the source server, and ISPConfig 3.3.0p2 on the destination server. Variations in versions or distributions may require adjustments.
• All destination mailboxes must have been created through the ISPConfig graphical user interface (GUI) prior to migration to establish necessary database records and directory structures. For adding mailboxes in bulk via the command-line interface (CLI), refer to a separate article on ISPConfig bulk mailbox creation using the remote API or scripts.
• Users must replace any referenced Linux usernames (e.g., source, root) and hostnames (e.g., plesk, ispconfig.test.co.za) with their own server-specific credentials and identifiers.
• Users must replace the example domain name (test.co.za) with their actual domain name throughout the commands and paths.

This guide provides step-by-step instructions to migrate Maildir email accounts from a Plesk server to an ISPConfig server, ensuring all email data, including user mailboxes, is transferred correctly. The process includes stopping services, using rsync for file transfer, restarting services, reindexing mailboxes, and troubleshooting common issues. It is divided into two main sections: one for migrating individual users one by one, and another for bulk migration of all users.

Section 1: Migrating Individual Users (One by One)

In this section, the migration is performed for a single user at a time, allowing for targeted verification and troubleshooting. This approach is recommended for smaller-scale migrations or when testing the process.

1. Stop Mail Services:
   • On the source (Plesk) server: systemctl stop qmail
   • On the destination (ISPConfig) server: systemctl stop dovecot

   Stopping services prevents data corruption during the transfer.

2. Rsync Commands:
   • From Source Shell (Plesk Server):

     Run the following command on the Plesk server to push the data to the ISPConfig server:

     rsync -avz --chown=vmail:vmail --exclude '@attachments' /var/qmail/mailnames/test.co.za/test/ root@ispconfig.test.co.za:/var/vmail/test.co.za/test/

     Replace root@ispconfig.test.co.za with the actual ISPConfig server credentials and hostname/IP.

   • From Destination Shell (ISPConfig Server):

     Run the following command on the ISPConfig server to pull the data from the Plesk server:

     rsync -avz --chown=vmail:vmail --exclude '@attachments' source@plesk:/var/qmail/mailnames/test.co.za/test/ /var/vmail/test.co.za/test/

     Replace source@plesk with the Plesk server username and hostname/IP.

3. Start Mail Services:

   On the destination (ISPConfig) server: systemctl start dovecot

   Restarting the service ensures the new data is recognized by the mail system.

4. Reindex Mailboxes:

   Run the following command on the ISPConfig server to rebuild Dovecot indices:

   doveadm -v index -u test@test.co.za '*'

   This step synchronizes the mailbox indices with the transferred data, resolving potential access issues.

5. Verify and Troubleshoot:
   • Check Logs: Monitor the mail log for errors: tail -f /var/log/mail.log
   • Test IMAP Login: Verify access by logging into the IMAP account for test@test.co.za.
   • Fix Permissions (if needed):
     • Correct ownership: chown -R vmail:vmail /var/vmail/test.co.za/test/Maildir
     • Adjust permissions: chmod -R u+rwx /var/vmail/test.co.za/test/Maildir

     These commands ensure the vmail user has full access to the Maildir structure, fixing potential permission-denied errors.

Notes:

• Exclusion of @attachments: The @attachments directory is specific to Plesk’s webmail interface and contains temporary files for email attachments. It is not required for email functionality in ISPConfig and can cause unnecessary clutter or permission conflicts if copied. Excluding it with --exclude '@attachments' keeps the migration clean and focused on essential email data.
• maildirfolder and maildirsize: These files serve important roles in the Maildir structure. maildirfolder is a Dovecot-specific file that tracks metadata for mail folders, ensuring proper folder organization and access. It may appear in migrated data but will be recreated or updated by Dovecot if missing or inconsistent. maildirsize records the quota usage for the mailbox, allowing Dovecot to enforce storage limits. When migrating, these files are preserved from the source, but ISPConfig and Dovecot will regenerate or adjust them during reindexing to match the destination environment. There’s no need to delete them; reindexing with doveadm -v index ensures they align with the new setup. If quotas are misreported, check with doveadm quota get -u test@test.co.za and adjust ISPConfig quota settings if necessary.

Repeat for Other Users:

Apply the same process for additional users by adjusting the paths (e.g., replace test with other usernames under /var/qmail/mailnames/test.co.za/) and updating the email address in the doveadm command accordingly.

Section 2: Migrating All Users in Bulk

This section addresses migrating all email users under /var/qmail/mailnames/ on the Plesk server to the ISPConfig server in a bulk operation. It assumes that all email domains and user mailboxes have already been created in the ISPConfig control panel (or via API) to ensure proper database entries for authentication and directory structure (/var/vmail/domain/user). This prerequisite ensures that the destination directories exist and are correctly configured before data transfer.

• Account Existence Requirement: This process requires that all mailboxes exist on the ISPConfig server prior to migration. Without pre-existing accounts, the rsync command will fail to populate the correct directories, and authentication will not work due to missing database records (e.g., in the mail_user table of the ISPConfig MySQL database). To prepare:
  • Create all email domains and users manually in the ISPConfig panel under "Email" > "Email Domains" and "Email Mailbox," replicating settings from Plesk (e.g., quotas, aliases).
  • For bulk creation, use ISPConfig's remote API with a script (e.g., PHP-based) to automate user addition, adapting community examples that list emails and call mail_user_add. Enable API access in ISPConfig under "System" > "Remote Users."

1. Stop Mail Services:
   • On the source (Plesk) server: systemctl stop qmail
   • On the destination (ISPConfig) server: systemctl stop dovecot

   Stopping services prevents data corruption during the transfer.

2. Bulk Rsync (From Destination Shell Example):

   Use a for loop to rsync all user directories:

   for user in $(ssh source@plesk "ls /var/qmail/mailnames/test.co.za/"); do
       rsync -avz --chown=vmail:vmail --exclude '@attachments' source@plesk:/var/qmail/mailnames/test.co.za/$user/ /var/vmail/test.co.za/$user/
   done

   Replace source@plesk with Plesk credentials and adjust for multiple domains if needed (e.g., nest loops for domains).

3. Bulk Fix Permissions:

   After rsync, apply ownership and permissions to all users:

   for user in $(ls /var/vmail/test.co.za/); do
       chown -R vmail:vmail /var/vmail/test.co.za/$user/Maildir
       chmod -R u+rwx /var/vmail/test.co.za/$user/Maildir
   done

4. Bulk Reindex Mailboxes:

   Reindex all users (assumes users match directory names):

   for user in $(ls /var/vmail/test.co.za/); do
       doveadm -v index -u $user@test.co.za '*'
   done

   This ensures indices are rebuilt for every migrated mailbox.

5. Start Mail Services:

   On the destination (ISPConfig) server: systemctl start dovecot

   Restarting the service ensures the new data is recognized by the mail system.

6. Verify and Troubleshoot:
   • Check Logs: Monitor the mail log for errors: tail -f /var/log/mail.log
   • Test IMAP Login: Verify access by logging into selected IMAP accounts.
   • Refer to the notes in Section 1 for details on @attachments, maildirfolder, and maildirsize.

This procedure ensures a complete and functional migration while addressing potential discrepancies between Plesk and ISPConfig Maildir setups. For large-scale migrations, ensure all accounts are pre-created in ISPConfig to avoid data mismatches.