180 lines
7.2 KiB
Text
180 lines
7.2 KiB
Text
---
|
||
title: Upgrading from Debian Bookworm
|
||
lastUpdated: 2025-08-09
|
||
slug: ispmail-trixie/upgrading
|
||
sidebar:
|
||
order: 110
|
||
---
|
||
|
||
import { Aside } from "@astrojs/starlight/components";
|
||
|
||
<Aside type="caution">
|
||
This page is only relevant if you already built a mail server using the 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
|
||
|
||
In the past I tried 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. However this time I decided to
|
||
change a few things because I reckon that an average mail server is used for friends and family or maybe a small
|
||
organisation. So I replaced resource-hungry components by more lightweight software:
|
||
|
||
- Apache and PHP were needed to run Roundcube as a webmail service. Apache is pretty heavy and no fun to configure. This
|
||
guide uses _Caddy_ instead – a very lightweight web server that also handles the job of _certbot_ to get you an
|
||
HTTPS/TLS certificate from Let's Encrypt automatically.
|
||
- MySQL/MariaDB was used to store control data about your domains, the email accounts and aliases. That is quite a lot
|
||
of RAM wasted for this little amount of data we need to store. So this guide uses _SQLite_ instead.
|
||
- 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.
|
||
|
||
# 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. In this guide we will turn off _chroot_ mode though to simplify
|
||
things a bit. The author of Postfix does not recommend it anyway.
|
||
- 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
|
||
|
||
Please do not try to upgrade your previous server using `apt-get dist-upgrade`. It is very hard to do the upgrade
|
||
without losing mails. Set up a new server instead. Once you are ready, come back here.
|
||
|
||
## 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…
|
||
|
||
(TODO: sqlite)
|
||
|
||
```
|
||
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
|
||
|
||
(TODO: sqlite)
|
||
|
||
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:
|
||
|
||
```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.
|
||
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 (Bookworm)
|
||
server and use *rsync* to copy over the mails from the old (Bullseye) 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 Bullseye 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.
|
||
|
||
## Copy certificates
|
||
|
||
(TODO: ignore with Caddy)
|
||
|
||
Copy over everything in /etc/letsencrypt and /var/lib/rspamd/dkim from your old to the new server.
|
||
|
||
```
|
||
rsync -va oldserver:/etc/letsencrypt/ /etc/letsencrypt/
|
||
rsync -va oldserver:/var/lib/rspamd/dkim/ /var/lib/rspamd/dkim/
|
||
```
|
||
|
||
## 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 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.
|