This version is not semver in that the upgrade from 2.3.x to 2.4.x is a breaking change (Migration guide).

Build-time failure

Presently building DMS image there is support to opt-in to the community repo which will install Dovecot with 2.4.x release:

docker build --build-arg DOVECOT_COMMUNITY_REPO=1 --tag localhost/dms .

• Build fails compiling FTS Xapian plugin 1.9.0 (due to Dovecot 2.4.0 changes). This is an easy fix resolved upstream with the 1.9.1 release (compatible with earlier Dovecot versions).

Run-time failure (with current Dovecot 2.3.x config)

Anything that runs doveconf or triggers Dovecot to parse the config will trigger the following failures. This is not a complete list of migration changes required.

docker run --rm -itd --hostname beta.example.test --name dms-beta localhost/dms

• Auth:
  setup email add [email protected] secret to provision the initial account creates postfix-accounts.cf (thus DMS continues setup), but Dovecot logs an error due to /etc/dovecot/conf.d/auth-passwdfile.inc:

  doveconf: Fatal: Error in configuration file /etc/dovecot/conf.d/auth-passwdfile.inc line 10: passdb { } is missing section name
  

  Current file content as of DMS v15.0.2:

  passdb {
    driver = passwd-file
    mechanisms = plain login
    args = scheme=SHA512-CRYPT username_format=%u /etc/dovecot/userdb
  }
  
  userdb {
    driver = passwd-file
    args = username_format=%u /etc/dovecot/userdb
    default_fields = uid=docker gid=docker home=/var/mail/%d/%u/home/
  }
  

  Seems to require passdb passwd-file {, despite the driver field being set which is documented as being used when the section name is missing. This is part of the config syntax changes.

  UPDATE: The migration guide covers this concern specifically, if the driver is not specified it can instead be any other value as a name/scope. EDIT: userdb needs this too.

  After resolving that, more errors are output regarding our passwd-file PassDB driver config, then the UserDB equivalent.

  • PassDB:

    • args is no longer valid for this PassDB driver, it has separate fields.
      • %u variable is dropped (as is any other single letter variable). This value should now be %{user}, providing the value [email protected], whereas the similar %n filters to only the local-part would now be: %{user | username}.
      • The 1st arg (scheme) for the default password scheme is now the default_password_scheme field.
      • The 2nd arg (username_format) is now the auth_username_format field.
      • The final arg (the passwd file path) is now the passwd_file_path field.
    • mechanisms was renamed to mechanisms_filter.

    Thus we get the following:

    passdb passwd-file {
      driver = passwd-file
      mechanisms_filter = plain login
      default_password_scheme = SHA512-CRYPT
      auth_username_format = %{user}
      passwd_file_path = /etc/dovecot/userdb
    }
    

  • UserDB:

    Now the associated UserDB in that file also needs to apply similar changes. default_fields was changed to fields, with separate subfields and different syntax:

    userdb passwd-file {
      driver = passwd-file
      auth_username_format = %{user}
      passwd_file_path = /etc/dovecot/userdb
      # Defaults field values for an entry if they're missing in `/etc/dovecot/userdb`.
      # NOTE: That file is created from `postfix-accounts.cf` + `postfix-virtual.cf`
      fields {
        uid:default = docker
        gid:default = docker
        # NOTE: The `%{user}` segment should technically be `%{user | username}`:
        home:default = /var/mail/%{user | domain}/%{user}/home/
      }
    }
    

    NOTE: Since DMS creates /etc/dovecot/userdb, the home field shouldn't be empty, hence no bug reports about the usage of %u, but it seems like that would have inserted the full email address. I think we also have a default global fallback configured here (via mail_location / mail_home) where the expected%n is actually used.

  • /etc/dovecot/conf.d/10-auth.conf is the next failure:

    doveconf: Fatal: Error in configuration file /etc/dovecot/conf.d/10-auth.conf line 10: disable_plaintext_auth: Unknown setting: disable_plaintext_auth
    

    The disable_plaintext_auth setting has been renamed to auth_allow_cleartext, this is inverted.

    That setting has a related DMS script to update to reflect the changes:

    docker-mailserver/target/scripts/helpers/ssl.sh

    Lines 354 to 359 in 23bb1c8

    	# no => insecure auth allowed, yes (default) => plaintext auth only allowed over a secure connection (insecure connection acceptable for non-plaintext auth)
    	local DISABLE_PLAINTEXT_AUTH='no'
    	# no => disabled, yes => optional (secure connections not required), required (default) => mandatory (only secure connections allowed)
    	local DOVECOT_SSL_ENABLED='no'
    	sed -i -r "s|^#?(disable_plaintext_auth =).*|\1 ${DISABLE_PLAINTEXT_AUTH}|" /etc/dovecot/conf.d/10-auth.conf
    	sed -i -r "s|^(ssl =).*|\1 ${DOVECOT_SSL_ENABLED}|" "${DOVECOT_CONFIG_SSL}"

    NOTE: Only applied when SSL_TYPE is not set which is unlikely to affect most users.

• Logging:

  doveconf: Fatal: Error in configuration file /etc/dovecot/conf.d/10-logging.conf line 45: verbose_ssl: Unknown setting: verbose_ssl
  

  verbose_ssl => log_debug = category=ssl. We have this set as verbose_ssl = no, but nothing in scripts seems to use it, nor any documentation related to it. It was committed 9 years ago as part of the switch to Dovecot from Courier.

  The next error is about the empty plugin section, which was committed at the same time as verbose_ssl. We'd have to go over any interactions with DMS there, but notably in Dovecot 2.4.x the plugin section itself was removed.

• General mail settings:
  /etc/dovecot/conf.d/10-mail.conf fails with mail_location = maildir:/var/mail/%d/%n, which was split into multiple settings (Ref: equivalent Dovecot 2.3.x docs with dedicated Mail Location page).

  Looking at the 2.4.0 Quick-start config example it looks like mail_driver + mail_path are all we're using for mail_location.

• SSL:
  /etc/dovecot/conf.d/10-ssl.conf - Many SSL settings were renamed, one is for server-side cipher preference which we have set to yes, the bool was changed to client / server string values instead, so we'd change this to ssl_server_prefer_ciphers = server.

  NOTE: After the changes are run, once doveconf is run you'll be able to use dovecot ssl_server to query these related settings with the ssl_server prefix:

  $ dovecot ssl_server
  
  ssl_server {
    cert_file = </etc/ssl/certs/ssl-cert-snakeoil.pem
    dh_file = </etc/dovecot/dh.pem
    key_file = </etc/ssl/private/ssl-cert-snakeoil.key
    prefer_ciphers = server
  }

  Being able to customize each individually with the prefix as part of the setting name is a Dovecot 2.4.0 feature known as Named Filters / Named List Filters.

  For DMS it's a bit awkward to modify nested settings via sed, so we typically use an approach to toggle via comments. This new feature makes it easier to override specific settings without requiring multiple lines or more complicated sed matching (if the setting name is too generic).

• Plugins:

  • Dovecot Quota:
    • /etc/dovecot/conf.d/90-quota.conf has a plugin section.
    • Since Dovecot 2.4.0 removed the plugin section from config syntax, all it's fields are now meant to be global settings.
    • Some fields don't seem to exist anymore in the 2.4.0 docs, nor were they mentioned in the quota docs page. May need to investigate. The migration page notes various changes to quota settings / renames too.
    • Reminder: Quota test-suite coverage has been disabled for some time due to CI issues previously encountered (may no longer be an issue).
  • Dovecot Sieve:
    • /etc/dovecot/conf.d/90-sieve.conf also has a plugin section.
    • Like with quota plugin, various changes in settings names and changes. This will need further investigation.
    • sieve_extensions is configured with +notify +imapflags (deprecated Sieve extensions) which have been removed.

This does detail all required changes to migrate

I removed the quota + sieve config files which finally got doveconf to work without any more errors output. This does not mean the above is all that needs to be changed.

For example, these variables (%d / %n) did not raise any error:

$ doveconf mail_home
mail_home = /var/mail/%d/%n/home/

I've not gone over the various feature permutations of DMS either, we have LDAP and OAuth features for example. The migration docs have a fair bit noted about the OAuth changes too.

This at least documents the initial set of changes we'll need to resolve for the migration (assuming Dovecot 2.4.x is part of the next Debian 13 Trixie release).