📖 References

Read these documents carefully before installing or upgrading your mail server:

• Build Email Server from Scratch (Debian, Postfix, SMTP)
• Install Dovecot IMAP Server on Debian
• PostfixAdmin: Create Virtual Mailboxes on Debian
• Dovecot Official Upgrade Guide (2.3 → 2.4)

⚠️ Upgrade Notes

• It is recommended to allow the new Dovecot configuration files to overwrite your existing v2.3 files during the upgrade.
• Always backup your current configuration before upgrading.

1. Backup Existing Configuration

Before making any changes, back up your current Dovecot configuration:

mkdir -p /root/backup-dovecot-$(date +%F)
cp -a /etc/dovecot /root/backup-dovecot-$(date +%F)/

2. Verify Installed Version

After upgrading your distribution, check that the new version of Dovecot is installed correctly:Check if the new version is correctly installed after the distri upgrade:

sudo dovecot –version
2.4.1-4 (7d8c0e5759)

3. Configure Protocols

Edit the main configuration file:

sudo nano /etc/dovecot/dovecot.conf

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0

#protocols = imap pop3 lmtp
protocols = imap pop3 lmtp

4. Configure Mail Storage (Virtual Mailbox Domains)

Edit the mail configuration file:

sudo nano /etc/dovecot/conf.d/10-mail.conf

#mail_driver = mbox
mail_driver = maildir
#mail_home = /home/%{user | username}
mail_home = /var/vmail/%{user|domain }/%{user|username}
#mail_path = %{home}/mail
mail_path = %{home}/Maildir
#mail_inbox_path = /var/mail/%{user}

# ...

# System user and group used to access mails. If you use multiple, userdb
# can override these by returning uid or gid fields. You can use either numbers
# or names. <https://doc.dovecot.org/latest/core/config/system_users.html#uids>
#mail_uid =
#mail_gid =
mail_uid = vmail
mail_gid = vmail

5. Configure LMTP Service

Edit the master configuration file:

sudo nano /etc/dovecot/conf.d/10-master.conf

service lmtp {
 unix_listener /var/spool/postfix/private/dovecot-lmtp {
   mode = 0600
   user = postfix
   group = postfix
  }
}

6. Configure Authentication

Edit the authentication configuration file: Update authentication to allow login with full email addresses:

sudo nano /etc/dovecot/conf.d/10-auth.conf

# Enable LOGIN command and all other plaintext authentications even if
# SSL/TLS is not used (LOGINDISABLED capability). Note that if the remote IP
# matches the local IP (ie. you're connecting from the same computer), the
# connection is considered secure and plaintext authentication is allowed,
# unless ssl = required.
auth_allow_cleartext = no

# Default realm/domain to use if none was specified. This is used for both
# SASL realms and appending @domain to username in plaintext logins.
auth_default_domain = example.com

#auth_mechanisms = plain login
auth_mechanisms = plain login

# Username formatting before it's looked up from databases.
auth_username_format = %{user|lower}

#!include auth-deny.conf.ext
#!include auth-master.conf.ext
#!include auth-oauth2.conf.ext

#!include auth-system.conf.ext
!include auth-sql.conf.ext
#!include auth-ldap.conf.ext
#!include auth-passwdfile.conf.ext
#!include auth-static.conf.ext

# Debugging (optional)
log_debug = category=auth

7. Configure SSL/TLS

To enforce encryption, change ssl = yes to ssl = required. It is also recommended to prefer the server’s cipher order over the client’s.

sudo nano /etc/dovecot/conf.d/10-ssl.conf
ssl = required
# Preferred permissions: root:root 0444
ssl_server_cert_file = /etc/letsencrypt/live/mail.example.com/fullchain.pem
# Preferred permissions: root:root 0400
ssl_server_key_file = /etc/letsencrypt/live/mail.example.com/privkey.pem

# ...

ssl_server_prefer_ciphers = server
ssl_min_protocol = TLSv1.2  #default

8. Configure Postfix Authentication

Edit the master configuration file to secure Postfix authentication:

sudo nano /etc/dovecot/conf.d/10-master.conf

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

9. Enable statistics in Dovecot

sudo nano /etc/dovecot/conf.d/10-master.conf

service stats {
    unix_listener stats-reader {
    user = www-data
    group = www-data
    mode = 0660
}

unix_listener stats-writer {
    user = www-data
    group = www-data
    mode = 0660
  }
}

10. SQL Authentication

Configure SQL authentication with MySQL:

We will use userdb static instead of userdb sql because we are using a fixed home directory for all domains /var/vmail/. Both will work, however, with slightly lower performance for userdb sql.

sudo nano /etc/dovecot/conf.d/auth-sql.conf.ext

# Database driver: mysql, pgsql, sqlite
sql_driver = mysql

mysql localhost {
  dbname = postfixadmin
  password = #hidden
  user = postfixadmin
}

passdb sql {
  default_password_scheme = ARGON2I
  query = SELECT username AS user, password FROM mailbox WHERE username = '%{user}' AND active='1'
}

# uid and gid defined in 10-mail.conf (mail_uid and mail_gid)

userdb static {
  fields {
    home = /var/vmail/%{user|domain}/%{user|username}
  }
}

#userdb sql {
#  iterate_query = SELECT username AS user FROM mailbox
#  query = SELECT CONCAT('/var/vmail/', `maildir`) AS home FROM mailbox WHERE username = '%{user}' AND active='1'
#}

Note

• userdb static is used here for simplicity and performance.
• userdb sql can also be used if you prefer dynamic lookups.

11. Restart Dovecot

Finally, restart Dovecot to apply all changes:

sudo service dovecot restart

Best Practices

• Always back up configuration files before making changes.
• Use strong password schemes (e.g., ARGON2I or SHA512).
• Enforce TLS 1.2 or higher for secure communication.
• Regularly test authentication and mail delivery after configuration changes.
• Monitor logs (/var/log/dovecot.log) for errors or warnings.