Did you follow the ISPmail guide for Debian Bookworm to install your mail server? Then let’s take it to Debian Trixie.

Architectural changes

Section titled “Architectural changes”

I always try to keep things similar to previous versions of this guide. Most of us are happy with their mail servers and want to change as little as possible when a new Debian release comes along. Just a few changes that come with the newer software versions:

• rsyslogd was a classic choice to write log files like /var/log/mail.log. As Debian is using systemd we no longer need rsyslogd and logrotate. The logs can be read using journalctl instead. If you miss log files, just apt install rsyslog.
• smtpd_tls_security_level is now only enabled for the submission service. That disables authentication for SMTP connections on port 25. This emphasizes the separation of TCP 25 for server-to-server connections (without authentication) and TCP 587 for human-to-server connections (with authentication – for relaying).
• certbot is now using the python3-certbot-apache package. Getting and renewing certificates is now handled magically by Apache without any downtime or additional configuration.

A new Debian stable release comes with newer software versions. So I checked the changelogs to determine what we will have to change:

• Postfix 3.7.6 -> 3.10.3. No breaking changes.
• Dovecot 2.3.19 -> 2.4.1. Various deprecations of the configuration. This guide uses the new syntax.
• PHP 8.2 -> 8.4. Roundcube has no issues with the newer PHP version.
• rspamd 3.4.1 -> 3.12.1. No breaking changes.
• Roundcube 1.6.1 -> 1.6.11. No breaking changes.

Fresh installation

Section titled “Fresh installation”

Do not try to upgrade your existing server using apt-get dist-upgrade. There are too many changes especially with Dovecot. Start with a fresh installation on another server and then migrate.

Preparing the DNS/IP switch

Section titled “Preparing the DNS/IP switch”

At some point during the migration, you need switch your DNS record to point to the new server. There are a couple of options:

1. Lower the TTL of your MX record. The TTL (time-to-live) defines how long your record can be cached. If you lower that value to 60 seconds, you can change the MX record and other servers will pick it up quickly.
2. If your data center allows it, move your IP address over. Some offer reserved addresses that you can assign to a server. That way there will be no delay in the switch-over. And other servers on the internet will recognize your server as a mail server already, because some companies attach a reputation to an IP address.
3. Add a second MX record pointing to your new server. Assign the same priority. That way you can safely switch off your old server and later remove its MX record.

Migrate the mailserver database

Section titled “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 (Bookworm) server as root and back up the mailserver database. That is as easy as running…

mariadb-dump mailserver > mailserver.sql

Copy that file to the new server (using scp) and import it there:

mariadb 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.

Weak password schemes

Section titled “Weak password schemes”

Please check if any of your users have hashed passwords that are considered weak by Dovecot. Those passwords using a PLAIN-MD5 scheme are not accepted by Dovecot by default. But you can enable them again using:

cat > 99-ispmail-weak-schemes.conf << EOFauth_allow_weak_schemes = yesEOF

Your users should change their passwords using Roundcube. That way a new hash with a more secure schema is created.

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:

mariadb-dump roundcube > roundcube.sql

Copy that file to the new server and import it:

mariadb 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:

UPDATE users SET mail_host='new.mail.server';

Migrate rspamd spam training data

Section titled “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.

Stop rspamd on both the old and the new server. Then:

rsync -va oldserver:/var/lib/redis/ /var/lib/redis/

Once the redis database is started again on the new server, rspamc stat should show you that the training data is found.

Migrate the Maildirs hot

Section titled “Migrate the Maildirs hot”

(Hot means: copy the files why they are still in use and potentially change while you do that.) Fortunately Dovecot uses the maildir format that stores emails as plain files on disk. Login to the new (Trixie) server and use rsync to copy over the mails from the old (Bookworm) mail server:

rsync -va oldserver:/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 Bookworm 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.

Another way to copy over the emails is using Dovecot’s doveadm-sync command. It may be especially handy if you need to copy emails from another server where you only have IMAP access but cannot access the files directly.

Copy over everything in /etc/letsencrypt and /var/lib/rspamd/dkim from your old to the new server.

rsync -va oldserver:/etc/letsencrypt/archive/ /etc/letsencrypt/archive/rsync -va oldserver:/var/lib/rspamd/dkim/ /var/lib/rspamd/dkim/rsync -v oldserver:/etc/rspamd/dkim_selectors.map /etc/rspamd

You told your users about the downtime, right? The time has come? Okay. Shut down Dovecot on both servers.

Migrate the emails cold

Section titled “Migrate the emails cold”

(Cold means: the processes have stopped or you made sure that there is no user activity so that the files can be copied consistently.) 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 oldserver:/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. So if a user has deleted an email it will be deleted on the new server as well.)

Switch the DNS records

Section titled “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

Section titled “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

Section titled “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.

You may see error messages like:

Error: sieve: binary /var/vmail/example.org/user/.dovecot.svbin: read: binary stored with different major version 2.0 (!= 3.0; automatically fixed when re-compiled)

You may need to run sievec on those files.