212 lines
8.4 KiB
Text
212 lines
8.4 KiB
Text
---
|
||
title: Upgrading from Debian Bookworm
|
||
lastUpdated: 2025-11-01
|
||
slug: ispmail-trixie/upgrading
|
||
sidebar:
|
||
order: 110
|
||
---
|
||
|
||
import { Aside } from "@astrojs/starlight/components";
|
||
|
||
<Aside type="tip">
|
||
This page is only relevant if you already built a mail server using the previous ISPmail guide for Debian Bookworm. If
|
||
you are starting from scratch, just skip to the next page.
|
||
</Aside>
|
||
|
||
Did you follow the ISPmail guide for Debian Bookworm to install your mail server? Then let's take it to Debian Trixie.
|
||
|
||
## 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.
|
||
|
||
## Version changes
|
||
|
||
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
|
||
|
||
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
|
||
|
||
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.
|
||
1. 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.
|
||
1. 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
|
||
|
||
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
|
||
|
||
Please check if any of your users have hashed passwords that are considered
|
||
[weak](https://doc.dovecot.org/2.4.2/core/config/auth/schemes.html) by Dovecot. Those passwords using a `PLAIN-MD5`
|
||
scheme are not accepted by Dovecot by default. But you can enable them again using:
|
||
|
||
```sh
|
||
cat > 99-ispmail-weak-schemes.conf << EOF
|
||
auth_allow_weak_schemes = yes
|
||
EOF
|
||
```
|
||
|
||
Your users should change their passwords using Roundcube. That way a new hash with a more secure schema is created.
|
||
|
||
## 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:
|
||
|
||
```sh
|
||
mariadb-dump roundcube > roundcube.sql
|
||
```
|
||
|
||
Copy that file to the new server and import it:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sql
|
||
UPDATE 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.
|
||
|
||
Stop rspamd on both the old and the new server. Then:
|
||
|
||
```sh
|
||
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
|
||
|
||
(**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](https://doc.dovecot.org/main/core/man/doveadm-sync.1.html) 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 certificates
|
||
|
||
Copy over everything in /etc/letsencrypt and /var/lib/rspamd/dkim from your old to the new server.
|
||
|
||
```sh
|
||
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
|
||
```
|
||
|
||
## Downtime
|
||
|
||
You told your users about the downtime, right? The time has come? Okay. Shut down Dovecot on both servers.
|
||
|
||
## 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:
|
||
|
||
```sh
|
||
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
|
||
|
||
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.
|
||
|
||
## Further issues
|
||
|
||
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.
|