mirror of
https://github.com/chatmail/relay.git
synced 2026-05-10 16:04:37 +00:00
99630e4d1b
* docs: update migration guide after nine migration * use $OLD_IP4 and $NEW_IP4 to make docs more readable. Also streamline "set TTL to 5 minute" phrasing a bit. * fix tar commands * refactor: streamline and refactor the migration guide to provide more clarity and focus * recommend a "higher TTL" concrete value Co-authored-by: missytake <missytake@systemli.org> * scriptify another location --------- Co-authored-by: missytake <missytake@systemli.org>
99 lines
3.1 KiB
ReStructuredText
99 lines
3.1 KiB
ReStructuredText
|
||
Migrating to a new machine
|
||
===========================
|
||
|
||
This migration tutorial provides a step-wise approach
|
||
to safely migrate a chatmail relay from one remote machine to another.
|
||
|
||
Preliminary notes and assumptions
|
||
---------------------------------
|
||
|
||
- If the migration is a planned move,
|
||
it's recommended to lower the Time To Live (TTL) of your DNS records to a value such as 300 (5 minutes),
|
||
at best much earlier than the actual planned migration.
|
||
This speeds up propagation of DNS changes in the Internet after the migration is complete.
|
||
|
||
- The migration steps were tested with a Linux laptop; you might need to adjust some of the steps to your local environment.
|
||
|
||
- Your ``mail_domain`` is ``mail.example.org``.
|
||
|
||
- All remote machines run Debian 12.
|
||
|
||
- The old site’s IP version 4 address is ``$OLD_IP4``.
|
||
|
||
- The new site’s IP addresses are ``$NEW_IP4`` and ``$NEW_IPV6``.
|
||
|
||
|
||
The six steps to migrate
|
||
------------------------
|
||
|
||
Note that during some of the following steps you might get a warning about changed SSH Host keys;
|
||
in this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended.
|
||
|
||
|
||
1. **Initially transfer mailboxes from old to new site.**
|
||
|
||
Login to old site, forwarding your ssh-agent with ``ssh -A``
|
||
to allow using ssh to directly copy files from old to new site.
|
||
::
|
||
|
||
ssh -A root@$OLD_IP4
|
||
tar c /home/vmail/mail | ssh root@$NEW_IP4 "tar x -C /"
|
||
|
||
|
||
2. **Pre-configure the new site but keep it inactive until step 6**
|
||
::
|
||
|
||
CMDEPLOY_STAGES=install,configure scripts/cmdeploy run --ssh-host $NEW_IP4
|
||
|
||
|
||
3. **It's getting serious: disable mail services on the old site.**
|
||
Users will not be able to send or receive messages until all steps are completed.
|
||
Other relays and mail servers will retry delivering messages from time to time,
|
||
so nothing is lost for users.
|
||
|
||
::
|
||
|
||
scripts/cmdeploy run --disable-mail --ssh-host $OLD_IP4
|
||
|
||
|
||
4. **Final synchronization of TLS/DKIM secrets, mail queues and mailboxes.**
|
||
Again we use ssh-agent forwarding (``-A``) to allow transfering all important data directly
|
||
from the old to the new site.
|
||
::
|
||
|
||
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/
|
||
|
||
Login to the new site and ensure file ownerships are correctly set:
|
||
|
||
::
|
||
|
||
ssh root@$NEW_IP4
|
||
chown root: -R /var/lib/acme
|
||
chown opendkim: -R /etc/dkimkeys
|
||
chown vmail: -R /home/vmail/mail
|
||
|
||
|
||
5. **Update the DNS entries to point to the new site.**
|
||
You only need to change the ``A`` and ``AAAA`` records, for example:
|
||
|
||
::
|
||
|
||
mail.example.org. IN A $NEW_IP4
|
||
mail.example.org. IN AAAA $NEW_IP6
|
||
|
||
|
||
6. **Activate chatmail relay on new site.**
|
||
|
||
::
|
||
|
||
CMDEPLOY_STAGES=activate scripts/cmdeploy run --ssh-host $NEW_IP4
|
||
|
||
Voilà!
|
||
Users will be able to use the relay as soon as the DNS changes have propagated.
|
||
If you have lowered the Time-to-Live for DNS records in step 1,
|
||
better use a higher value again (between 14400 and 86400 seconds) once you are sure everything works.
|
||
|