The more cynical amongst us may think that Dovecot are trying to shift more people onto paid support as the changes introduced in 2.4 break just about everything.  It isn’t particularly bad if you are installing a fresh, but upgrading can be a bit of a pain (particularly if you are using postifxadmin and perhaps still using MD5 for passwords like we were).

To get everything working as it was with 2.3 as instructed on this site you will need to make a small change to postfixadmin and more than likely renew all the passwords.  Allegedly you can tell it to use MD5 but then you have to prefix all the entries anyway (or use a sneaky SQL trick) so you might as well just upgrade to SHA512 and be done with it.

This guide was written after upgrading Debian to Trixie (which broke just about everything; but nothing quite as spectacularly as the email server).

This guide can be used for either Install or upgrade, albeit I nave not done a clean install with it yet.  The guide is assuming that you have Debian Trixie installed,

Postfixadmin

Upgrading postifxadmin itself is fairly painless but you do need to do the following: Find the line that says

 

$CONF['encrypt'] = 'md5crypt';

and change it to

 

$CONF['encrypt'] = 'dovecot:SHA512-CRYPT';

This will ensure that when you change all the passwords that they use SHA512 instead of MD5.

One small snag with doing this is that it creates a paradox as now when you try to log in to the interface you will no longer be able to do so because your password is not encrypted as expected so the next thing you need to do is generate a password.

To do this you can use a utility that bundles with dovecot called doveadm.  Type

doveadm pw -s SHA512-CRYPT

and you will be prompted for a password.  Follow the instructions, entering the password that you wish to use to log on to postfixadmin and you will then be presented with a sting that looks something like

{SHA512-CRYPT}$6$1VrbYvsGOfLwN4Tl$iQzUmw8kEimkrwHIY4yk.JejQLOf.SJyyj/..ZEF8Zx.eS4PWYiTr5QjFlUVMKdRiwyum5wiQlADdH/hdkzsa0

The postfixadmin portal has a table called admin which lists the administrative users and their passwords so now you will need to access that table from the postgresql command line and change the password.

For simplicity I am going to use this example to demonstrate accessing the postgresql command line, but your own login method may be different.  Remember however that you are going to need to login as a user that has write privileges on the database (the postfixro user does not).

psql -U postgres -d postfix

If you don’t know the user name you wish to change then you can

SELECT username FROM admin;

And you will see a list.

To update the password you simply

UPDATE admin SET password = {SHA512-CRYPT}$6$1VrbYvsGOfLwN4Tl$iQzUmw8kEimkrwHIY4yk.JejQLOf.SJyyj/..ZEF8Zx.eS4PWYiTr5QjFlUVMKdRiwyum5wiQlADdH/hdkzsa0 WHERE username = me@mydomain.com

Now if you go back to the postfixadmin interface you should be able to log in again.

IMPORTANT:  You will now have to reset the passwords for all the users.  You cannot get the users to change their own passwords at this point because the old passwords are stored using a now incompatibly cipher.  The user will be able to change their own password after you have changed it once, but this is the only way I have found to update the password scheme.

Now you have made postfixadmin compatible with dovecot you can move on to configuring dovecot itself.

Dovecot

If you don’t have dovecot installed then you need to do this first:

Installation

The first thing that we need to do is install a number of dovecot packages

dovecot-pgsql

dovecot-imapd

dovecot-lmtpd

dovecot-managesieved

 

#apt-get install dovecot-pgsql dovecot-imapd dovecot-lmtpd dovecot-managesieved

We are not going to bother with pop3 because I cannot thing of a single application where we would use it. Once everything is installed we can move on to the configuration

Configuration dovecot.conf

In /etc/dovecot/dovecot.conf first make sure you have the dovecot_config_version and dovecot_storage_version directives as the first entries in this file.  (I also like to enable debugging while getting it working and then comment it out when done).

If this is a new install of you have used the default config files from 2.4 then these lines will be in however if you are upgrading and using your old config files then they won’t.

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0
mail_debug = yes

Other than that make sure

 

!include_try /usr/share/dovecot/protocols.d/*.protocol

and

listen =*, ::

 

Configuration dovecot-sql.conf.ext

dovecot-sql.conf.ext is no longer used so if you have got it then just delete; all the sql configuration is now done in ./conf.d/auth-sql.conf.ext

The rest of the configuration files are in the folder /etc/dovecot/conf.d. Navigate to that folder now and edit the following files

Configuration auth-sql.conf.ext

This is what replaces dovecot-sql.conf.ext and it is a full on reinvention of the wheel with a few things thrown in to catch you out such as %{user} replacing %u and the driver directive now being called sql_driver instead.  The connection string is also gone, replaced by nested brackets.

If you are interested in what exactly it does then the 2.3 guide explains it, but if you just want to make it work then just paste the following in it (don’t forget to change your password)

sql_driver = pgsql

pgsql localhost {
  parameters {
    user = postfixro
    password = mysecretpassword
    dbname = postfix
  }
}

passdb_default_password_scheme = SHA512-CRYPT

userdb sql {
        query = \
                SELECT '/mailstore/'||maildir AS home, '*:bytes='||quota AS quota_rule \
                FROM mailbox \
                WHERE username = '%{user}' \
                AND active = TRUE
}

passdb sql {
        query = \
                SELECT '/mailstore/'||maildir AS userdb_home, username AS user, password, '*:bytes='||quota AS userdb_quota_rule \
                FROM mailbox \
                WHERE username = '%{user}' \
                AND active = TRUE
}

As you can see the syntax is a little different, also this is where we tell dovecot that we wish to use SHA512 instead of MD5.

Configuration 10-mail.conf

Here dovecot gives us another new wheel as we no longer have a “mail_location” directive.  This is broken into 4 new lines

mail_driver = maildir
mail_path = ~/
mail_home = /mailstore/%{user | domain }/%{user | username }

One thing that may be confusing is the mail_path directive.  Don’t think it is pointing to the user’s home directory as it isn’t, it is pointing to the mail_home directory but I had to put it in as it would not work without it.

 

The rest of the configuration of 10-mail.conf is the same as 2.3

The following directives all relate to the userid and groupid that will have access to the mailstore directory. If you remember, when we configured postfix we also created the /home/mailstore directory and a user and group both called mailer that were granted ownership of the directory. We then ran the id command to obtain the uid and gid of the mailer user which was 1001 for both the user and the group. Now we need to tell dovecot what uid and gid will be required to access this directory.

mail_uid = 1001 
mail_gid = 1001 
first_valid_uid = 1001 
last_valid_uid = 1001 
first_valid_gid = 1001 
last_valid_gid = 1001

The only other thing we need to do is tell dovecot that we want to enable the quota plugin

mail_plugins = quota

Configuration 15-mailboxes.conf

I did not alter this configuration file from 2.3 to 2.4 so am assuming it is the same as everything seems to work as it did.

This is optional, but if you want to autocreate folders for junk, trash and sent, or even some other folder the first time that a user logs on then this is where you do it. There is good documentation within the file but in brief, if you want to enable the auto creation of a particular folder then add

auto=subscribe

within its stanza.

If you want to create a folder inside another then you need to use a period “.” as a separator. The period “.” after INBOX will cause dovecot to create the Junk folder inside INBOX.

mailbox INBOX.Junk { 
    auto=subscribe 
    special_use = \Junk 
}

Configuration 20-lmtp.conf

Within the protocol lmtp stanza you need to add the following

lmtp_rcpt_check_quota = yes

protocol lmtp {
    mail_plugins {
        quota = yes
        sieve = yes
    }
    postmaster_address=postmaster@fqdn.suffix 
    hostname=server.fqdn.suffix
}

Again this is not particuarly different to the 2.3 version however it is different enough to stop it working.

Configuration 20-imap.conf

Here once again we have another reinvented wheel as we replace “mail_plugins = $mail_plugins imap_quota” with

protocol imap {
  mail_plugins {
    imap_quota = yes
    imap_sieve = yes
  }
}

Configuration 10-master.conf

Most of the configuration of 10-master.conf is the same with the exception of the service auth-worker directive that now requires an explicit user change the unix_listner auth-userdb directives within the “service auth” stanza to

unix_listener auth-userdb { 
    mode = 0600 
    user = mailer 
    group = mailer 
}

and add the following, also within the service auth stanza

unix_listener /var/spool/postfix/private/auth { 
    mode = 0666 
    user = postfix 
    group = postfix 
}

In the service auth-worker stanza add

service auth-worker { 
    user = mailer
}

 

Configuration 10-auth.conf

There are a few changes here, the first being “disable_plaintext_auth” is no longer used however you can just comment out or remove this line as dovecot now defaults to automatically disabling plain text authentication (which can only be a good thing).  If for some reason you want to enable it then you need to set auth_allow_cleartext instead, but this is NOT recommended.

Other than that you need to ensure you have all the includes commented out except for “auth-sql.conf.ext“.

#!include auth-deny.conf.ext
#!include auth-master.conf.ext
#!include auth-system.conf.ext
!include auth-sql.conf.ext
#!include auth-ldap.conf.ext
#!include auth-passwdfile.conf.ext
#!include auth-checkpassword.conf.ext
#!include auth-vpopmail.conf.ext
#!include auth-static.conf.ext

Configuration 15-lda.conf

I did not alter 15-lda.conf at so it simply has

postmaster_address = postmaster@domain.net protocol 
lda { 
    mail_plugins = $mail_plugins sieve 
}

 

Configuration 90-plugin.conf

Now we need to provide some information about sieve; this is quite a bit different to 2.3 as it now appears to be in 3 separate scopes.

sieve_script personal {
  driver = file
  path = ~/sieve
  active_path = ~/.dovecot.sieve
}

sieve_script global_default {
  sieve_script_type = global
  path = /var/lib/dovecot/sieve/default.sieve
}

sieve_script global_dir {
  sieve_script_type = global
  path = /var/lib/dovecot/sieve/global/
}

We also need to create the /var/lib/dovecot/sieve directory and change the owner to mailer:mailer

mkdir /var/lib/dovecot/sieve 
chown –R mailer:mailer /var/lib/dovecot/sieve

Configuration 10-ssl.conf

The final configuration file is the ssl configuration that tells dovecot where to look for the certificates. We need to tell dovecot that we want to use ssl so we need to change “ssl =” to yes

ssl = yes

Other than that we are telling the server what certificates to use.  As we are using certbot ours are

ssl_server_cert_file = /etc/letsencrypt/live/mydomain.com/fullchain.pem
ssl_server_key_file = /etc/letsencrypt/live/mydomain.com/privkey.pem

Previously the ssl_cert and ssl_key directives had an unusual syntax, but now it is just the same as setting any other directive, if you are upgrading however remember to delete the “<”

Next you need to generate the The The Diffie-Hellman (DH) key exchange.  The name of the directive has changed to ssl_server_dh_file

ssl_server_dh_file = /etc/dovecot/dh.pem

Of course you need to generate this file if to does not yet exist

openssl dhparam -out /etc/dovecot/dh.pem 4096

This could take some time.

Final actions           

The final step is to tell Postfix to use this socket for final delivery, in this case in a virtual user scenario. All you have to do is add

virtual_transport = lmtp:unix:private/dovecot-lmtp

to the end of /etc/postfix/main.cf

You should now be able to restart dovecot and provided that you have added a domain and user you should be able to connect to the server using a client.

Enable debugging and check the logs. At the top of /etc/dovecot/dovecot.conf add

mail_debug = yes

You will want to remove this when you are sure your configuration is ok

If for some reason the server is not working as it should, check the log file for errors

#tail –f /var/log/mail.log

The postgresql logs may also help

tail -f /var/log/postgresql/postgresql-XX-main.log

as might journalctl -f

If you need authentication and password related debug message, turn on related settings and restart dovecot service.

auth_verbose = yes 
auth_debug = yes 
auth_debug_passwords = yes 
auth_verbose_passwords = yes

If you see many error message (like dovecot fails, spawning too quickly) in Dovecot error log while restarting Dovecot, there might be something wrong in Dovecot config file. Please try to start it on command line manually, it will report configuration error if any, fix them and start it again:

dovecot -c /etc/dovecot/dovecot.conf

A useful tool for checking your configuration is

doveconf

To test authentication

doveadm auth test user@example.com TestPass123

Doing this while monitoring the mail and SQL logs will usually give you a good idea of what is going wrong if dovecot is actually running.

openssl s_client -connect localhost:143 -starttls imap

Will check the certificate and give you a prompt where you can type your login username and password

a me@mydomain.com mysecretpassword

which should return something like

* CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE REPLACE SNIPPET=FUZZY PREVIEW=FUZZY PREVIEW SPECIAL-USE STATUS=SIZE SAVEDATE COMPRESS=DEFLATE INPROGRESS NOTIFY LITERAL+ QUOTA
a OK Logged in

type

b logout

to exit the interface.

At the time of writing the postfix configuration is completely unchanged.

 

 

Acknowledgement and credit is quite rightly given to:

https://www2.techtalkhawke.com/news/postfix-dovecot-postgresql-and-sogo-webmail-on-debian-13

and

https://monospace.games/posts/20250815-dovecot-24.html