Upgrade or fresh installation?
I recommend that you set up a new server and make sure that the new mail server is working correctly before you start migrating existing email users to it. You may argue that Debian can be upgraded easily using “apt-get dist-upgrade” but that is very dangerous on a live mail server. Automatic configuration changes may have evil side effects and you risk losing emails. At least you are causing a downtime for your users.
If you follow my advice then get a new server and install Debian Bullseye on it. Once the user mailboxes are migrated and all works well you can tear down the old server.
Once your new server is installed come back here.
Read before you type
Follow this guide to the end. Only then start attempting a migration. Inform your users about the migration and set a time when you intend to move email accounts to the new server. The change will require a DNS change which takes a while to be visible worldwide so your users will have a period when incoming email is delayed. If you proceed careful though not a single email will be lost.
So you have your new server up and running and did everything to make it a working mail server? You really read all the pages in this guide and did what they told you? Okay, then let’s start.
Turn down the TTL of your MX record
The DNS “MX” record for your domain contains the hostname of your mail server. When switching to the new server you need to change the MX record. Every DNS record has a TTL (time-to-live) that defines the period of time that a record will stay valid even after you change it. Usually that TTL is rather high like 86400 seconds (=1 day). This information is used by caching name servers that they can use the cached values for a day. Turn that TTL down temporarily to 60 seconds so that the rest of the internet will pick up your change quicker. However it will take a day.
Migrate the mailserver database
You need to copy the database that contains the control data about your email domains and accounts. Log into the old (Buster) server as root and back up the mailserver database. That is as easy as running…
mysqldump mailserver > mailserver.sql
Copy that file to the new server (using scp) and import it there:
mysql mailserver < mailserver.sql
Obviously any database changes on the old server from now on will have to be done on the new server as well until the migration is done.
Roundcube contacts
If your users are using Roundcube as a webmail interface then you should migrate their data like their contact lists. Dump the SQL from the old server:
mysqldump roundcube > roundcube.sql
Copy that file to the new server and import it:
mysql roundcube < roundcube.sql
One caveat though. To distinguish multiple mail servers Roundcube stores the server’s name in the mail_host column of the users table. So as a last step change that column if your new mail server has a new FQDN/hostname by running this SQL query on the new roundcube database:
ALTER users set mail_host='new.mail.server';
Migrate rspamd spam training data
If you have been using rspamd with the Redis backend then copy over the Redis database from your previous server. Details are found in the rspamd chapter.
Migrate the Maildirs hot
Fortunately Dovecot uses the maildir format that stores emails as plain files on disk. Login to the new (Bullseye) server and use rsync to copy over the mails from the old (Buster) mail server:
rsync -va busterserver:/var/vmail/ /var/vmail/
(Note the trailing slashes. Type them exactly as shown above or your files will end up in wrong places.)
There is no need to shut down Dovecot on your production Buster server. Copying the files while Dovecot is running will not break anything. This is called a “hot copy”. It may not be consistent but it will save time during the final synchronization.
Downtime
You told your users about the downtime, right? The time has come? Okay. Shut down Dovecot on both servers.
Migrate the emails cold
Let’s synchronize again. rsync will only copy those files that have changed which makes it much faster than the first sync. On your new server run:
rsync -va --delete stretch-server:/var/vmail/ /var/vmail/
(The “--delete” option makes sure that files that have been removed from the old server will also be deleted from the new server.)
Switch the DNS records
For all your domains you will have to change the DNS “MX” or “A” record to point to your new server.
Enable soft_bounce
Accidents happen. And you don’t want to lose emails. So run this command to enable your safety net on the new server:
postconf soft_bounce=yes
This makes Postfix always keep emails in the queue that it would otherwise reject. So you can fix any errors and the queue will empty. Start Postfix and Dovecot on the new server. Watch your /var/log/mail.log and run “mailq” from time to time to see what emails get stuck in the queue. If you are certain that emails can be removed from the queue then use “postsuper -d QUEUE-ID” (as shown in the “mailq” output).
Once you are certain that emails are properly received and sent you can switch off the soft_bounce mode again:
postconf soft_bounce=no
Shut down the old server
If possible do a final backup of the old server. If users are not complaining then dismiss the old system after a week.
A part about redis migration would be really nice!
Thanks for the hint. I explained that later in the rspamd chapter. But of course it should be mentioned here. So I just added it.
Hello.
First of all, congratulations for such a wonderful guide. I have doubts about how to perform the server migration. Right now I have the mail server running on Debian 9.13 at the URL mail.mydomain.
I have a “MX” dns record for mydomain that points to mail.mydomain and a “A” record for mail.mydomain pointing to IP. So to perform the migration I rent another vps where I install Debian Bullseye.
When I have to get a new certificate, will I have to ask for it for a new host name like webmail.mydomain?
But then my new server will be webmail.mydomain.
Maybe I don’t understand all this well, can you help me?
Hello Juan,
With your new VPS you receive a new IP-address that is valid for your new VPS, but not your old VPS. Therefor, after you have your new serverup and running and ready to take over as the live system you change the A record to your MX record to your new IP of your new VPS.
In example your current DNS:
example.com 60 IN MX 10 mail.example.com
mail.example.com 60 IN A 192.0.2.78
Your new mailserver shows in the DNS like this:
newserver.example.com 86400 IN A 198.51.100.9
Now you add to your DNS:
oldserver.example.com 86400 IN A 192.0.2.78
with this you can still reach your old server with an easy to remember hostname instead of its IP.
As the last step you change the IP for mail.example.com and the TTL for the MX and A record:
example.com 86400 IN MX 10 mail.example.com
mail.example.com 86400 IN A 198.51.100.9
Now the new server is the one the world will connect to to send you emails.
Greetings
Dennis
Hi Dennis.
Thanks for your help but I think I will need some more explanation.
Let’s assume that I currently have the following data for DNS:
example.com 60 IN MX 10 mail.example.com
mail.example.com 60 IN A 192.0.2.78
And that my new VPS has the following DNS A record:
webmail.example.com 86400 IN A 198.51.100.9
Then, in the chapter “Creating a TLS encryption key and certificate”, I run the following command to get a new certificate:
certbot certonly –webroot –webroot-path /var/www/webmail.example.com -d webmail.example.com
So at the end of my setup I will not have a certificate for mail.example.com but for webmail.example.org. Therefore when I change the A record of my old server to update to the new IP address, there will be no valid matching certificate for mail.example.com.
So will users have to change the configuration of their mail clients?
Right now, I don’t have more than a few test email accounts so I could start over and delete the existing accounts. I mean, I don’t need to do an actual migrating.
However I would like to understand this well for when I need it.
Greetings
Juan
Here you would probably want to point both webmail.example.com and mail.example.com to the VPS (assuming that’s where you’re hosting the mail server). The Let’s Encrypt certificate can be constructed to represent multiple machine (and domain) names.
The users would configure their client software for mail.domain.com as both the SMTP and IMAP/POP3 servers.
My current certificate covers four domains (i.e. mail.domain1.com, mail.domain2.com, mail.domain3.com and mail.domain4.com). It could be extended to cover the associated webmail sites (i.e. webmail.domain1.com – webmail.domain4.com).
I chose to go with mail.domain1.com as my initial cert (as opposed to webmail.domain1.com) and added the other domains/machines after everything was running.
There is one Stretch on this page which should be Buster and two “stretch”es which should be buster
Thanks for spotting that, Charles. No matter how hard I try, I always skip a few occurences when copy/pasting. 🙂
Following the tutorial from the start while setting up a new server (in order to migrate to it), I was a bit confused by the instruction to switch DNS record at this stage:
I don’t even have postfix installed at yet.
Looks like at least some of this should be postponed to a later stage in the tutorial.