diff --git a/.rstcheck.cfg b/.rstcheck.cfg new file mode 100644 index 0000000..7d31766 --- /dev/null +++ b/.rstcheck.cfg @@ -0,0 +1,2 @@ +[rstcheck] +ignore_messages = Hyperlink target ".*" is not referenced. diff --git a/docs/dkim.rst b/docs/dkim.rst index f5c38a1..0837527 100644 --- a/docs/dkim.rst +++ b/docs/dkim.rst @@ -1,3 +1,5 @@ +.. _dkim: + DKIM Signing ============ @@ -54,6 +56,8 @@ if set) based on :option:`mailserver.dkim.defaults .. _25.11 release: release-notes.html#nixos-25-11 .. _RFC8301 3.2: https://www.rfc-editor.org/rfc/rfc8301#section-3.2 +.. _dkim-key-rotation: + DKIM Key Rotation ~~~~~~~~~~~~~~~~~ diff --git a/docs/ldap.rst b/docs/ldap.rst index a397bf4..023070c 100644 --- a/docs/ldap.rst +++ b/docs/ldap.rst @@ -1,3 +1,5 @@ +.. _ldap-top: + LDAP ==== diff --git a/docs/migrations.rst b/docs/migrations.rst index d6c9258..c8c8f5e 100644 --- a/docs/migrations.rst +++ b/docs/migrations.rst @@ -13,6 +13,8 @@ apply to your setup. NixOS 26.05 ----------- +.. _migration-5: + #5 Sieve script directory migration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -94,6 +96,8 @@ This migration is only required if you have :option:`mailserver.enableManageSiev 10. If you temporarily disabled :option:`mailserver.enableManageSieve` in step 1, re-enable it now by setting it back to ``true``. +.. _migration-4: + #4 Dovecot LDAP UUID-based home directories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/release-notes.rst b/docs/release-notes.rst index fd4f54d..e38a088 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -4,62 +4,90 @@ Release Notes NixOS 26.05 ----------- -- Certificate handling was simplified. We recommend setting - :option:`mailserver.x509.useACMEHost` to a ``security.acme.certs`` - configuration. If that does not fit your requirements, configure certificate - and private key using :option:`mailserver.x509.certificateFile` and - :option:`mailserver.x509.privateKeyFile` instead. Support for automatic - creation of self-signed certificates has been removed. - Check the updated `setup guide`_ for a basic ACME HTTP-01 example. -- `DKIM key management`_ is now available with multiple concurrent selectors per - domain enabling proper DKIM key rotation. While we still generate a default - key for backwards compatibility we now also support passing pre-created - key material. If your DKIM keys were automatically created before the 25.11 - release they are 1024 bit RSA keys and should be rotated out. - See :option:`mailserver.dkim.domains` for further relevant options. -- Cleartext password files can now be configured for login accounts. This - is an alternative to hashed passwords that integrates well with workflows - established by `agenix`_/`sops-nix`_ that instead rely on encryption. This - option prevents files from leaking in to the Nix store. - See :option:`mailserver.accounts..passwordFile`. -- TLS configurations have been updated: +Features +^^^^^^^^ - - TLSv1.2 cipher suites in Postfix now require `AEAD`_ and `ECDHE`_. - - Postfix and Dovecot allow for the ``SecP256r1MLKEM768`` - key exchange, as specified in the ongoing - `standardization effort `__. - - Postfix no longer supports uncommon, deprecated, and obsolete TLS signature - algorithms. +- :ref:`DKIM key management ` now supports multiple selectors per domain, + enabling :ref:`key rotation `. Pre-created key material is + also supported. Existing automatically generated DKIM keys from before 25.11 + use 1024-bit RSA and should be rotated. See :option:`mailserver.dkim.domains`. -- LDAP setups require a migration of Dovecot home directories to - `UUID based home directories`_. The exact UUID attribute can be customized - through :option:`mailserver.ldap.attributes.uuid`. -- The default login username for LDAP users has changed from the ``mail`` to - the ``uid`` attribute. This allows users to login with their account name - rather than their email address, which is more convenient and consistent - with typical LDAP practices. The exact attribute can be customized through +- Certificate handling was simplified. We recommend using the NixOS + ACME module (``security.acme.certs``) and referencing a certificate + configuration by name. Alternatively, certificate and private key can be + managed manually. Configure either :option:`mailserver.x509.useACMEHost` + or :option:`mailserver.x509.certificateFile` and + :option:`mailserver.x509.privateKeyFile`. See the updated :ref:`setup guide + ` for a basic ACME HTTP-01 example. + +- Local mail accounts can now use managed cleartext passwords. This integrates + well with secret management tools such as `agenix`_ and `sops-nix`_ while + avoiding password leakage into the world-readable Nix store. See + :option:`mailserver.accounts..passwordFile`. + +- Blocked sender responses can now be customized. This is useful if you require GDPR + compliance. See :option:`mailserver.rejectSenderMessage`. + +Security +^^^^^^^^ + +- TLSv1.2 cipher suites in Postfix now require `AEAD`_ and `ECDHE`_. + +- Postfix and Dovecot now support negotiation of the ``SecP256r1MLKEM768`` + key agreement mechanism. The `standardization process + `__ is ongoing. + +- Deprecated and obsolete TLS signature algorithms were removed from Postfix. + +Sieve +^^^^^ + +- **Migration**: When ManageSieve is enabled, user-created Sieve scripts must + be migrated into their Dovecot home directory. See the :ref:`migration guide + `. + +LDAP +^^^^ + +- **Migration**: Dovecot home directories for LDAP users must be migrated to + UUID-based directory names. The UUID attribute can be customized through + :option:`mailserver.ldap.attributes.uuid`. See the :ref:`migration guide + `. + +- The LDAP configuration has been revamped. Option names have been simplified, + examples and documentation improved. The :ref:`LDAP documentation ` + was written from the ground up. + +- The default LDAP login attribute changed from ``mail`` to ``uid``. + This allows users to login with their account name rather than + their email address, which is more convenient and consistent with + typical LDAP practices. The exact attribute can be customized through :option:`mailserver.ldap.attributes.username`. -- Local and LDAP accounts can now co-exist. For overlapping names and addresses + +- Local and LDAP accounts can now coexist. For overlapping accounts and addresses the local account will always win. -- Custom reject messages for blocked senders are now possible by setting - :option:`mailserver.rejectSenderMessage` to e.g. comply with GDPR. -- The following integrations are deprecated and will be removed before the next - release: - - :option:`mailserver.borgbackup.enable` - - :option:`mailserver.backup.enable` - - :option:`mailserver.monitoring.enable` -- Setups with :option:`mailserver.enableManageSieve` enabled require a - migration of the `Sieve script directories into Dovecot home directories`_. -.. _setup guide: setup-guide.html#setup-the-server -.. _DKIM key management: dkim.html +Internals +^^^^^^^^^ + +- Dovecot has been updated from 2.3 to 2.4 and now relies on the structured settings option. + +Deprecations +^^^^^^^^^^^^ + +The following integrations are deprecated and will be removed before the next +release: + +- :option:`mailserver.borgbackup.enable` +- :option:`mailserver.backup.enable` +- :option:`mailserver.monitoring.enable` + +.. _key rotation: dkim.html#dkim-key-rotation .. _agenix: https://github.com/ryantm/agenix .. _sops-nix: https://github.com/Mic92/sops-nix .. _AEAD: https://en.wikipedia.org/wiki/Authenticated_encryption .. _ECDHE: https://www.rfc-editor.org/rfc/rfc8422 -.. _UUID based home directories: migrations.html#dovecot-ldap-uuid-based-home-directories -.. _Sieve script directories into Dovecot home directories: migrations.html#sieve-script-directory-migration NixOS 25.11 ----------- diff --git a/docs/setup-guide.rst b/docs/setup-guide.rst index 0f4a41d..1c9a7a9 100644 --- a/docs/setup-guide.rst +++ b/docs/setup-guide.rst @@ -1,3 +1,5 @@ +.. _setup-guide: + Setup Guide ===========