Add migration story for LDAP UUID home directories

docs/migrations.rst

@@ -5,10 +5,107 @@ 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.
+The initial :option:`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 26.05
+-----------
+
+#4 Dovecot LDAP UUID-based home directories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LDAP Support in NixOS mailserver was introduced during the 23.11 release cycle
+and came with a number of flaws that we are correcting now, three years later.
+
+This particular migration is needed because up until now we were
+relying on email addresses to construct the Dovecot home directory path
+(``var/vmail/ldap/user@example.com``) which is fragile: addresses can
+change, requiring manual homedir relocation. Switching to UUID-based homedirs
+(``/var/vmail/ldap/<uuid>``) ensures stable, unique paths and applies well-known
+best practices to mailserver management.
+
+1. Copy the migration script script to your mailserver and make it executable:
+
+   .. code-block:: console
+
+      cd /tmp
+      wcurl https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/blob/master/migrations/nixos-mailserver-migration-04.py
+      chmod +x nixos-mailserver-migration-04.py
+
+2. Stop the ``dovecot.service``.
+
+   .. code-block:: bash
+
+      systemctl stop dovecot.service
+
+3. Create a backup or snapshot of your :option:`mailserver.mailDirectory`, so
+   you can restore should anything go wrong.
+
+4. Run the migration script and pass the required arguments to enable LDAP lookups:
+
+   The script should be run under the user who owns the :option:`mailserver.mailDirectory`.
+   If run as root it will automatically switch into the appropriate user by itself.
+
+   The script will not modify your data unless called with ``--execute``.
+
+   The migration script finds all Dovecot home directories in
+   ``/var/vmail/ldap/`` (or any other :option:`mailserver.mailDirectory`),
+   for example that of bob at ``/var/vmail/ldap/bob@example.com``.
+   It then takes ``bob@example.com`` and queries the LDAP server for
+   ``mail=bob@example.com`` to retrieve the UUID attribute. Finally
+   it starts suggesting the neceessary move operations to arrive at
+   ``/var/vmail/ldap/f3b4e8ea-087f-42cc-95f0-cbfd99386092`` for bob.
+
+   Example:
+
+   .. code-block:: bash
+
+      ./nixos-mailserver-migration-04.py \
+        --ldap-uri ldaps://ldap1.example.com
+        --ldap-bind-dn cn=mail,ou=accounts,dc=example,dc=com \
+        --ldap-bind-pw-file /run/keys/ldap-bind-pw \
+        --ldap-base ou=people,ou=accounts,dc=example,dc=com \
+        --ldap-scope sub \
+        --ldap-filter "(mail=%s)" \
+        --ldap-attr-uuid entryUUID \
+         /var/vmail
+
+   For the ``--ldap-attr-uuid`` parameter we expect a long-term stable
+   identifier, ideally a UUID field. The exact attribute name depends on your
+   LDAP implementation, for example:
+
+   - Authentik: ``uid`` `[1]`_
+   - Kanidm: ``uuid`` `[2]`_
+   - Keycloak ``entryUUID``
+   - OpenLDAP: ``entryUUID`` (`RFC4530`_)
+
+   If yours LDAP provider isn't listed you can determine the correct
+   attribute by quering a user entry with ``ldapsearch``. Finally, configure
+   :option:`mailserver.ldap.attributes.uuid` accordingly.
+
+   Add ``--ldap-starttls`` if you use the the `ldap://` URI scheme and require
+   explicit TLS.
+
+   .. _[1]: https://docs.goauthentik.io/add-secure-apps/providers/ldap#users
+   .. _[2]: https://kanidm.github.io/kanidm/stable/integrations/ldap.html#data-mapping
+   .. _RFC4530: https://www.rfc-editor.org/rfc/rfc4530.html
+
+5. Review the script output.
+
+   It's primary job is to determine the UUID for an LDAP account, so that it
+   can rename the Dovecot home directory from mail address to UUID within the
+   same directory.
+
+   The script can highlight various inconsistencies and problems, that should
+   be reviewed and acted upon.
+
+   If in doubt, join our community chat for help before applying any changes.
+
+6. Rerun the command with ``--execute`` or run the proposed commands manually.
+
+7. Update the ``mailserver.stateVersion`` to ``4``.
 
 NixOS 25.11
 -----------