diff --git a/.hydra/declarative-jobsets.nix b/.hydra/declarative-jobsets.nix index 41db7e1..589e204 100644 --- a/.hydra/declarative-jobsets.nix +++ b/.hydra/declarative-jobsets.nix @@ -31,6 +31,7 @@ let desc = prJobsets // { "main" = mkFlakeJobset "main"; + "nixos-26.05" = mkFlakeJobset "nixos-26.05"; "nixos-25.11" = mkFlakeJobset "nixos-25.11"; }; 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/README.md b/README.md index 05b6327..dd930e6 100644 --- a/README.md +++ b/README.md @@ -5,19 +5,15 @@ ## Release branches -For each NixOS release, we publish a branch. You then have to use the -SNM branch corresponding to your NixOS version. +We publish a branch for each NixOS release. Only matching branch versions are +supported. -* For NixOS 25.11 - * Use the [SNM branch `nixos-25.11`](https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/tree/nixos-25.11) - * [Documentation](https://nixos-mailserver.readthedocs.io/en/nixos-25.11/) - * [Release notes](https://nixos-mailserver.readthedocs.io/en/nixos-25.11/release-notes.html#nixos-25-11) -* For NixOS 25.05 - * Use the [SNM branch `nixos-25.05`](https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/tree/nixos-25.05) - * [Documentation](https://nixos-mailserver.readthedocs.io/en/nixos-25.05/) - * [Release notes](https://nixos-mailserver.readthedocs.io/en/nixos-25.05/release-notes.html#nixos-25-05) +* For NixOS 26.05 + * Use the [`nixos-26.05`](https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/tree/nixos-25.11) branch + * [Documentation](https://nixos-mailserver.readthedocs.io/en/nixos-26.05/) + * [Release notes](https://nixos-mailserver.readthedocs.io/en/nixos-26.05/release-notes.html#nixos-26-05) * For NixOS unstable - * Use the [SNM branch `main`](https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/tree/main) + * Use the [`main`](https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/tree/main) branch * [Documentation](https://nixos-mailserver.readthedocs.io/en/latest/) ## Features diff --git a/default.nix b/default.nix index d8e5dd1..cc56700 100644 --- a/default.nix +++ b/default.nix @@ -425,6 +425,11 @@ in example = "/run/my-secret"; description = '' File containing the password required to bind against the LDAP server. + + :::{warning} + The password file is read verbatim. Any trailing newline will become + part of the password and may cause authentication failures. + ::: ''; }; }; 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/flakes.nix b/docs/flakes.nix index a74bdfa..5e0d0e7 100644 --- a/docs/flakes.nix +++ b/docs/flakes.nix @@ -2,9 +2,9 @@ description = "NixOS configuration"; inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11-small"; + nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05-small"; - simple-nixos-mailserver.url = "gitlab:simple-nixos-mailserver/nixos-mailserver/nixos-25.11"; + simple-nixos-mailserver.url = "gitlab:simple-nixos-mailserver/nixos-mailserver/nixos-26.05"; simple-nixos-mailserver.inputs.nixpkgs.follows = "nixpkgs"; }; 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..a3cb360 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -162,7 +166,7 @@ best practices to mailserver management. - Keycloak ``entryUUID`` - OpenLDAP: ``entryUUID`` (`RFC4530`_) - If yours LDAP provider isn't listed you can determine the correct + If your LDAP provider isn't listed you can determine the correct attribute by querying a user entry with ``ldapsearch``. Finally, configure :option:`mailserver.ldap.attributes.uuid` accordingly. diff --git a/docs/release-notes.rst b/docs/release-notes.rst index fd4f54d..a120f20 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -4,62 +4,93 @@ 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 + +- The LDAP bind password is now read verbatim without trimming whitespace. Any + trailing newline is now preserved and may cause authentication failures. + +- 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-example.nix b/docs/setup-example.nix index c2b4dd0..32f62c2 100644 --- a/docs/setup-example.nix +++ b/docs/setup-example.nix @@ -10,10 +10,10 @@ # or flakes. # URL to the tarball for the release matching your NixOS release - url = "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/nixos-25.11/nixos-mailserver-nixos-25.11.tar.gz"; + url = "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/nixos-26.05/nixos-mailserver-nixos-26.05.tar.gz"; # Hash of the unpacked tarball, run the following command to retrieve it - # release="nixos-25.11" nix-prefetch-url "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/${release}/nixos-mailserver-${release}.tar.gz" --unpack + # release="nixos-26.05" nix-prefetch-url "https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/archive/${release}/nixos-mailserver-${release}.tar.gz" --unpack sha256 = "0000000000000000000000000000000000000000000000000000"; }) ]; 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 ===========