From 35867153af9653407fd6cf85502b7de6b1ec8575 Mon Sep 17 00:00:00 2001 From: missytake Date: Tue, 16 Dec 2025 10:27:40 +0100 Subject: [PATCH 1/3] docs: update migration guide after nine migration --- doc/source/migrate.rst | 75 +++++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 27 deletions(-) diff --git a/doc/source/migrate.rst b/doc/source/migrate.rst index d88f363f..972c326e 100644 --- a/doc/source/migrate.rst +++ b/doc/source/migrate.rst @@ -8,7 +8,7 @@ you might need to adjust some of the steps to your environment. Let’s assume that your ``mail_domain`` is ``mail.example.org``, all involved machines run Debian 12, your old site’s IP address is -``13.37.13.37``, and your new site’s IP address is ``13.12.23.42``. +``13.12.13.12``, and your new site’s IP address is ``45.54.45.54``. Note, you should lower the TTLs of your DNS records to a value such as 300 (5 minutes) so the migration happens as smoothly as possible. @@ -16,57 +16,78 @@ Note, you should lower the TTLs of your DNS records to a value such as During the guide you might get a warning about changed SSH Host keys; in this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. -1. First, disable mail services on the old site. +1. First, to make the downtime during the migration shorter, + let's transfer the current state of the mailboxes. + Login to your old machine (while forwarding your ssh-agent with ``ssh -A``) + so you can copy directly from the old to the new site with your SSH + key: :: - cmdeploy run --disable-mail --ssh-host 13.37.13.37 + ssh -A root@13.12.13.12 + tar c - /home/vmail/mail | ssh root@45.54.45.54 "tar x -C /" - Now your users will notice the migration and will not be able to send - or receive messages until the migration is completed. + This saves us time during the downtime, + at least the mailboxes are there already. + They contain user passwords, encrypted push notification tokens, + messages which might not have been fetched by all devices of the user yet, + and dovecot indexes which track the state of the mailbox. -2. Now we want to copy ``/home/vmail``, ``/var/lib/acme``, - ``/etc/dkimkeys``, and ``/var/spool/postfix`` to - the new site. Login to the old site while forwarding your SSH agent - so you can copy directly from the old to the new site with your SSH - key: +2. Then, from your local machine, install chatmail on the new machine, but don't activate it yet: :: - ssh -A root@13.37.13.37 - tar c - /home/vmail/mail /var/lib/acme /etc/dkimkeys /var/spool/postfix | ssh root@13.12.23.42 "tar x -C /" + CMDEPLOY_STAGES=install,configure cmdeploy run --ssh-host 45.54.45.54 - This transfers all addresses, the TLS certificate, - and DKIM keys (so DKIM DNS record remains valid). - It also preserves the Postfix mail spool so any messages - pending delivery will still be delivered. + The services are disabled for now; we will enable them later. + We first need to make the new site fully operational. -3. Install chatmail on the new machine: +3. Now it's getting serious: disable the mail services on the old site. :: - cmdeploy run --disable-mail --ssh-host 13.12.23.42 + cmdeploy run --disable-mail --ssh-host 13.12.13.12 - Postfix and Dovecot are disabled for now; we will enable them later. - We first need to make the new site fully operational. + Your users will start to notice the migration and will not be able to send + or receive messages until the migration is completed. + Other relays and mail servers will wait with delivering messages + until your relay is reachable again. -4. On the new site, run the following to ensure the ownership is correct +4. Now we want to copy ``/home/vmail``, ``/var/lib/acme``, + ``/etc/dkimkeys``, and ``/var/spool/postfix`` to + the new site. Let's forward the SSH agent again to copy the files directly. + This time, we copy ``/home/vmail/mail`` with rsync to only copy the recent changes: + + :: + + ssh -A root@13.12.13.12 + tar c - /var/lib/acme /etc/dkimkeys /var/spool/postfix | ssh root@45.54.45.54 "tar x -C /" + rsync -azH /home/vmail/mail root@45.54.45.54:/home/vmail/ + + This transfers all addresses, messages which have not been fetched yet, the TLS certificate, + and DKIM keys (so DKIM DNS record remains valid). + It also preserves the Postfix mail spool so any messages + pending delivery will still be delivered. + +5. Now login to the new site and run the following to ensure the ownership is correct in case UIDs/GIDs changed: :: + ssh root@45.54.45.54 chown root: -R /var/lib/acme chown opendkim: -R /etc/dkimkeys chown vmail: -R /home/vmail/mail -5. Now, update DNS entries. +6. Now, update the DNS entries. + You only need to change the ``A`` and ``AAAA`` records, for example: + + :: - If other MTAs try to deliver messages to your chatmail domain they - may fail intermittently, as DNS catches up with the new site settings - but normally will retry delivering messages for at least a week, so - messages will not be lost. + mail.example.org. IN A 45.54.45.54 + mail.example.org. IN AAAA 45:ac:1312:ab::1 -6. Finally, you can execute ``cmdeploy run --ssh-host 13.12.23.42`` to +7. Finally, you can execute ``CMDEPLOY_STAGES=activate cmdeploy run --ssh-host 45.54.45.54`` to turn on chatmail on the new relay. Your users will be able to use the chatmail relay as soon as the DNS changes have propagated. Voilà! From bf371e7b6d2c9357f810c541c2c69597065987b8 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Thu, 18 Dec 2025 16:58:05 +0100 Subject: [PATCH 2/3] use $OLD_IP4 and $NEW_IP4 to make docs more readable. Also streamline "set TTL to 5 minute" phrasing a bit. --- doc/source/migrate.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/doc/source/migrate.rst b/doc/source/migrate.rst index 972c326e..189353b8 100644 --- a/doc/source/migrate.rst +++ b/doc/source/migrate.rst @@ -7,11 +7,12 @@ machine, you can use these steps. They were tested with a Linux laptop; you might need to adjust some of the steps to your environment. Let’s assume that your ``mail_domain`` is ``mail.example.org``, all -involved machines run Debian 12, your old site’s IP address is -``13.12.13.12``, and your new site’s IP address is ``45.54.45.54``. +involved machines run Debian 12, your old site’s IP version 4 address is +``$OLD_IP4``, and your new site’s IP4 address is ``$NEW_IP4``. -Note, you should lower the TTLs of your DNS records to a value such as -300 (5 minutes) so the migration happens as smoothly as possible. +First of all, you should lower the Time To Live (TTL) of your DNS records +to a value such as 300 (5 minutes). +Short TTL values allow to change DNS records during the migration more timely. During the guide you might get a warning about changed SSH Host keys; in this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. @@ -24,8 +25,8 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: - ssh -A root@13.12.13.12 - tar c - /home/vmail/mail | ssh root@45.54.45.54 "tar x -C /" + ssh -A root@$OLD_IP4 + tar c - /home/vmail/mail | ssh root@$NEW_IP4 "tar x -C /" This saves us time during the downtime, at least the mailboxes are there already. @@ -37,7 +38,7 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: - CMDEPLOY_STAGES=install,configure cmdeploy run --ssh-host 45.54.45.54 + CMDEPLOY_STAGES=install,configure cmdeploy run --ssh-host $NEW_IP4 The services are disabled for now; we will enable them later. We first need to make the new site fully operational. @@ -46,7 +47,7 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: - cmdeploy run --disable-mail --ssh-host 13.12.13.12 + cmdeploy run --disable-mail --ssh-host $OLD_IP4 Your users will start to notice the migration and will not be able to send or receive messages until the migration is completed. @@ -60,9 +61,9 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: - ssh -A root@13.12.13.12 - tar c - /var/lib/acme /etc/dkimkeys /var/spool/postfix | ssh root@45.54.45.54 "tar x -C /" - rsync -azH /home/vmail/mail root@45.54.45.54:/home/vmail/ + ssh -A root@$OLD_IP4 + tar c - /var/lib/acme /etc/dkimkeys /var/spool/postfix | ssh root@$NEW_IP4 "tar x -C /" + rsync -azH /home/vmail/mail root@$NEW_IP4:/home/vmail/ This transfers all addresses, messages which have not been fetched yet, the TLS certificate, and DKIM keys (so DKIM DNS record remains valid). @@ -74,7 +75,7 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: - ssh root@45.54.45.54 + ssh root@$NEW_IP4 chown root: -R /var/lib/acme chown opendkim: -R /etc/dkimkeys chown vmail: -R /home/vmail/mail @@ -84,10 +85,10 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: - mail.example.org. IN A 45.54.45.54 - mail.example.org. IN AAAA 45:ac:1312:ab::1 + mail.example.org. IN A $NEW_IP4 + mail.example.org. IN AAAA $NEW_IP6 -7. Finally, you can execute ``CMDEPLOY_STAGES=activate cmdeploy run --ssh-host 45.54.45.54`` to +7. Finally, you can execute ``CMDEPLOY_STAGES=activate cmdeploy run --ssh-host $NEW_IP4`` to turn on chatmail on the new relay. Your users will be able to use the chatmail relay as soon as the DNS changes have propagated. Voilà! From c849036d0b7511e8a736e5064a4c404340705fbe Mon Sep 17 00:00:00 2001 From: holger krekel Date: Thu, 18 Dec 2025 23:40:20 +0100 Subject: [PATCH 3/3] fix tar commands --- doc/source/migrate.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/migrate.rst b/doc/source/migrate.rst index 189353b8..768c9c37 100644 --- a/doc/source/migrate.rst +++ b/doc/source/migrate.rst @@ -26,7 +26,7 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: ssh -A root@$OLD_IP4 - tar c - /home/vmail/mail | ssh root@$NEW_IP4 "tar x -C /" + tar c /home/vmail/mail | ssh root@$NEW_IP4 "tar x -C /" This saves us time during the downtime, at least the mailboxes are there already. @@ -62,10 +62,10 @@ this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended. :: ssh -A root@$OLD_IP4 - tar c - /var/lib/acme /etc/dkimkeys /var/spool/postfix | ssh root@$NEW_IP4 "tar x -C /" + tar c /var/lib/acme /etc/dkimkeys /var/spool/postfix | ssh root@$NEW_IP4 "tar x -C /" rsync -azH /home/vmail/mail root@$NEW_IP4:/home/vmail/ - This transfers all addresses, messages which have not been fetched yet, the TLS certificate, + This transfers all messages which have not been fetched yet, the TLS certificate, and DKIM keys (so DKIM DNS record remains valid). It also preserves the Postfix mail spool so any messages pending delivery will still be delivered.