mirror of
https://gitlab.com/simple-nixos-mailserver/nixos-mailserver.git
synced 2025-12-25 04:10:52 +01:00
117 lines
4.1 KiB
ReStructuredText
117 lines
4.1 KiB
ReStructuredText
Migrations
|
|
==========
|
|
|
|
With mail server configuration best practices changing over time we might need
|
|
to make changes that require you to complete manual migration steps before you
|
|
can deploy a new version of NixOS mailserver.
|
|
|
|
The initial `mailserver.stateVersion` value should be copied from the setup
|
|
guide that you used to initially set up your mail server. If in doubt you can
|
|
always initialize it at `1` and walk through all assertions, that might apply
|
|
to your setup.
|
|
|
|
NixOS 25.11
|
|
-----------
|
|
|
|
#3 Dovecot mail directory migration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The way the Dovecot home directory for login accounts were previously set up
|
|
resulted in shared home directories for all those users. This is not a
|
|
supported Dovecot configuration.
|
|
|
|
To resolve this we migrated the home directory into the individual
|
|
`domain/localpart` subdirectory below the `mailserver.mailDirectory`.
|
|
|
|
But since this now overlaps with the location of the Maildir, it must be
|
|
migrated into the `mail/` directory below the home directory.
|
|
And while the LDAP home directory is not affected we use this migration to
|
|
keep the Maildir configurations of LDAP users in sync with those of local
|
|
accounts.
|
|
|
|
This is a big step forward, since we can now more cleanly colocate other
|
|
data directories, like sieve in the home directory, which in turn simplifies
|
|
backups.
|
|
|
|
This migration is required for every configuration.
|
|
|
|
For remediating this issue the following steps are required:
|
|
|
|
1. Copy the `migration script <https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/blob/master/migrations/nixos-mailserver-migration-03.py>`_ script to your mailserver
|
|
and make it executable:
|
|
|
|
.. code-block:: bash
|
|
|
|
wcurl https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/raw/master/migrations/nixos-mailserver-migration-03.py
|
|
chmod +x nixos-mailserver-migration-03.py
|
|
|
|
2. Stop the ``dovecot.service``.
|
|
|
|
.. code-block:: bash
|
|
|
|
systemctl stop dovecot.service
|
|
|
|
3. Create a backup or snapshot of your ``mailserver.mailDirectory``, so you can restore
|
|
should anything go wrong.
|
|
|
|
4. Run the migration script under your virtual mail user with the following arguments:
|
|
|
|
- ``--layout default`` unless ``useFSLayout`` is enabled, then ``--layout folder``
|
|
- The value of ``mailserver.mailDirectory``, which defaults to ``/var/vmail``
|
|
|
|
The script should be run under the user who owns the ``mailDirectory``.
|
|
If run as root it will try to switch into the appropriate user by itself.
|
|
|
|
The script will not modify your data unless called with ``--execute``.
|
|
|
|
Example:
|
|
|
|
.. code-block:: bash
|
|
|
|
./nixos-mailserver-migration-03.py --layout default /var/vmail
|
|
|
|
5. Review the commands. They should be
|
|
|
|
- create a ``mail`` directory for each account,
|
|
- move maildir contents from the parent directory into it,
|
|
- suggest removal of files that do not belong to the maildir
|
|
|
|
- their removal is not mandatory and the script **will not** remove them when called with ``--execute``
|
|
- review these items carefully if you want to remove them yourself
|
|
|
|
- remove obsolete files from the old home directory location
|
|
|
|
6. Rerun the command with ``--execute`` or run the commands manually.
|
|
|
|
7. Update the ``mailserver.stateVersion`` to ``3``.
|
|
|
|
#2 Dovecot LDAP home directory migration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The Dovecot configuration for LDAP home directories previously did not respect
|
|
the ``mailserver.mailDirectory`` setting.
|
|
|
|
This means that home directories were unconditionally located at
|
|
``/var/vmail/ldap/%{user}``.
|
|
|
|
This migration is required if you both:
|
|
|
|
* enabled the LDAP integration (``mailserver.ldap.enable``)
|
|
* and customized the default mail directory (``mailserver.mailDirectory != "/var/vmail"``)
|
|
|
|
For remediating this issue the following steps are required:
|
|
|
|
1. Stop ``dovecot.service``.
|
|
2. Move ``/var/vmail/ldap`` below your ``mailserver.mailDirectory``.
|
|
3. Update the ``mailserver.stateVersion`` to ``2``.
|
|
|
|
#1 Initialization
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
This option was introduced in the NixOS 25.11 release cycle, in which case you
|
|
can safely initialize its value at `1`.
|
|
|
|
.. code-block:: nix
|
|
|
|
mailserver.stateVersion = 1;
|
|
|