How to Move a qmail Installation

I was running a mail server (SMTP and POP3) for the domain example.com on the old.example.com host and needed to move it to new.example.com. Here's how to do this:

  1. Have your users use the mail.example.com address for accessing their POP3 mailboxes, or create a pop.example.com address for this purpose (this needs to be done weeks in advance!)

  2. Set the DNS TTL down to 15 minutes to allow a speedy transition. (If you're also moving the DNS, move it now and give the changes time to spread!)

  3. Recreate the old.example.com email account structure on new.example.com through Plesk, and cut and paste the hashed passwords from/to users/poppasswd. This seems sufficient for retrieving messages through POP3. To update users/cdb, you can run /var/qmail/bin/qmail-newu, but I don't know whether this is necessary.

    If you also need SMTP authorization and/or Plesk Control Panel access, then you'll have to fix the MySQL database as well. Look at the psa.mail table to get the account_id, and you'll find the encoded password in the psa.accounts table.

  4. Reconfigure qmail on old.example.com to start forwarding email to new.example.com:
    • Set control/smtproutes as
      example.com:new.example.com
    • Remove example.com from control/locals and control/virtualdomains, but keep it in control/rcpthosts
    • Restart qmail to get this to take effect

    From this point on, all email for someone@example.com is automatically relayed to someone's inbox at new.example.com.

  5. Be sure to test this; you may need to restart some daemon — I've simply restarted the server.

  6. If you want, you can tell your users to retrieve their email one last time from the old server. Change DNS of mail.example.com (and pop.example.com) from old.example.com to new.example.com — this will take some time to become effective, but no messages will get lost; they'll either go to example.com and be relayed to new.example.com, or they'll go directly to new.example.com.

  7. Process the remaining messages for each user under mailnames as follows:
    • Copy the attachments from @attachments, be sure to retain/restore ownership and access modes.
    • Copy the old unread emails in Maildir/new to a new Maildir/x directory, fix ownership and access modes (so they are the same as a newly arrived message on new.example.com, which is not necessarily what they were on old example.com!), and only then move them to the new Maildir/new directory.
      (BTW, emails on the old example.com have file names like NNNNNNNN.NNNN.example.com, and emails arriving on new.example.com have names like NNNNNNNN.NNNN.new.example.com, I don't whether this makes any difference...)
    • Copy any stored emails in Maildir/cur and fix these up, too.

This procedure should allow you to migrate a qmail MTA from one host to another without causing any problems for your users, even if they continue to retrieve their email as usual.

You'll find that some MTA's will continue to send email to old.example.com long after the DNS change should be completed, so if you can, keep the MTA on old.example.com running and forwarding for a few days or weeks. However, if you use qpsmtpd on new.example.com to reject spam, then you should either whitelist the old example.com or shut it down, because example.com would probably bounce undeliverable spam to innocent third parties, which is a BAD THING.

Lenti