Upgrading Dovecot from 2.3 to 2.4/3.0

About version numbers

With 2.4 / 3.0 release, the CE and Pro releases have different major version numbers. In documentation any reference to 2.4 applies to 3.0 as well, and usually (but not always) vice versa.

Upgrade path

Before upgrading, please look at the list of removed features carefully.

If you are doing in-place upgrade, ensure that you first upgrade to latest 2.3 release, and then upgrade to 2.4/3.0.

Alternatively, you can migrate your data to new setup.

See also

Migrating mailboxes.

Deprecated features and their replacements

Feature	Notes
fs-sis	Saving new mails’ attachments via fs-sis is disabled, but reading SIS attachments is still supported. Missing SIS attachments are replaced with files filled with spaces.

Removed features and their replacements

Feature	Notes
Dict quota Dirsize quota	The dict and dirsize backends are removed. You should use count instead along with quota_clone plugin. Note that switching to quota count can cause all user’s indexes to update, so reserve time for this.
XZ Compression	You need to perform migration using different plugin. With maildir, you can try uncompressing all your mail and compressing them with another algorithm while Dovecot is not running.
auth_worker_max_count	Use service-specific process limit.
fts-lucene fts-squat	Use Flatcurve FTS or Solr FTS.
Weak password schemes	Weak password schemes are disabled by default, you need to use auth_allow_weak_schemes to enable them.
Global ACL directory	Use Global ACL file instead. Check Use Global ACL Files instead of Global ACL Directories for details on migration.
ssl-parameters.dat	This file is no longer converted automatically by config process, you need to set ssl_dh setting if you need non-ECC Diffie-Hellman.
License plugin	This plugin has been removed and license_checksum setting is marked obsolete. Plugin setting license_checksum has been also removed.
shadow auth driver	Use PAM instead.
old-stats plugin	Use new stats instead. auth_stats setting has been removed too.
Memcached dict driver	Use redis instead.
dsync: Remove -D parameter	Parameter for disabling mailbox rename syncing removed. It hasn’t been necessary for a long time, and it is broken.
dsync	Use doveadm sync instead. dsync has been a symlink to doveadm already, this release removed the symlink completely.
login_access_sockets	Use Lua based authentication instead. Dovecot will fail to start if this setting is present in configuration.
TCP wrapper support	Use Lua based authentication instead.
checkpassword auth database	Use Lua based authentication instead.
IPC process	Has been merged to anvil.
auth_debug	Use log_debug filter instead. Example: log_debug=category=auth
auth_client_cache_flush_started auth_client_cache_flush_finished	These events were removed.
OpenSSL support for older than 1.0.2	Older versions are not supported anymore.
imap-zlib plugin	The IMAP COMPRESS extension is now automatically enabled. See IMAP Compression.
Renamed zlib plugin and relevant configuration items	Use mail-compress plugin - with the configuration items mail_compress_save as well as mail_compress_save_level - instead.
Support for obsoleted Key-value authentication (dict) database settings passdb_key and userdb_key was removed.	Use non-obsolete key {} syntax.
mailbox-alias plugin	Depending on the use case, non-direct may be the namespace/mailbox/special_use mailbox setting and/or Sieve filters.
obox_allow_inconsistency	The setting has been removed as it caused problems with caching IMAP clients, which may lose emails permanently or otherwise become confused about their internal state.
metacache_disable_merging	Use metacache_index_merging=none instead.
disable_plaintext_auth	This has been replaced with auth_allow_cleartext setting.
ssl=required	Connections from login_trusted_networks are now also required to be SSL/TLS encrypted with this setting. See also secured connections.
absolute_timeout_msecs	Deprecated HTTP-storage parameter. Use absolute_timeout setting instead.
connect_timeout_msecs	Deprecated HTTP-storage parameter. Use connect_timeout setting instead.
delete_timeout_msecs	Deprecated HTTP-storage parameter. Use delete_timeout setting instead.
read_timeout_msecs	Deprecated HTTP-storage parameter. Use read_timeout setting instead.
slow_warn_msecs	Deprecated HTTP-storage parameter. Use slow_warn setting instead.
timeout_msecs	Deprecated HTTP-storage parameter. Use timeout setting instead.
write_timeout_msecs	Deprecated HTTP-storage parameter. Use write_timeout setting instead.
dict_db_config	Berkeley DB is not supported anymore.
idle_msecs	Deprecated dict proxy parameter. Use idle_timeout setting instead.
warn_slow_msecs	Deprecated dict proxy parameter. Use slow_warn setting instead.
Dovecot director role	This has been replaced with Dovecot Cluster, which is Pro-only feature. For community version, see Run director with Lua on proxy.
imap_id_log setting.	Replaced by the imap_id_received event.
no-cleanup-uncertain	Previously cleanup-uncertain needed to be explicitly enabled, now it is enabled by default. It can be disabled by no-cleanup-uncertain - see Dictmap Parameters for more details.
replicator	Use NFS or some other shared filesystem instead.
size.virtual	size.virtual field is no longer written to dovecot.index.cache file as it is duplicating vsize record in dovecot.index file. Reading of the field from old files is supported.

Changed default settings

Key	Old	New	Notes
service/anvil/chroot	empty	<no value>	Anvil is no longer chrooted
service/anvil/user	$default_internal_user	<no value>	Anvil runs as root
service/auth-worker/process_limit	1	30	Behaviour of process limit has changed for auth-worker, it now behaves as it was supposed to.
mail_location		NO-NOSELECT	NO-NOSELECT is the new default behavior. To revert to the old default specify KEEP-NOSELECT.
fts_dovecot_mail_flush_interval	0	10
fts_dovecot_max_triplets	0	200
max-parallel-iter	1	10
mail_cache_max_headers_count	unlimited	100	New feature, explicitly set to 0 for the old behavior
mail_cache_max_header_name_length	unlimited	100	New feature, explicitly set to 0 for the old behavior
mail_log_prefix	%s(%u)<%{pid}><%{session}>:	%s(%u)<%{process:pid}><%{session}>:	Uses new process key

Doveadm mailbox commands

USER `` environment variable is no longer supported. All mail commands require providing ``-u, -F or -A parameter. This will always be subject to user database lookup and requires access to auth userdb socket.

Use Global ACL Files instead of Global ACL Directories

To migrate the ACL directories into their respective files you have to do the following:

1. create a new consolidated Global ACL file,

2. for each subdirectory in the currently configured ACL directory add a line starting with the mailbox name followed by the appropriate content,

3. change the vfile parameter to the new ACL file, and finally

4. remove the old ACL directory parent.

Example

With the following starting configuration:

# dovecot.conf

namespace {
  prefix = INBOX/
  separator = /
}

plugin {
  acl = vfile:/etc/dovecot/acls/
}

# /etc/dovecot/acls/INBOX

owner lrwstipekxa
anyone lr
user=kim l

# /etc/dovecot/acls/INBOX/foo/.DEFAULT

user=timo lr
user=kim lrw

# /etc/dovecot/acls/INBOX/foo/bar

user=kim lrw

You have to create the new ACL file:

# /etc/dovecot/dovecot-acl

# previously from /etc/dovecot/acls/INBOX
INBOX owner lrwstipekxa
INBOX anyone lr
INBOX user=kim l
# previously from /etc/dovecot/acls/foo/.DEFAULT
INBOX/foo user=timo lr
INBOX/foo user=kim lrw
# previously from /etc/dovecot/acls/foo/bar
INBOX/foo/bar user=kim lrw

Note that at this point you could simplify specific rules, e.g. use mailbox name wildcards to replace lines for a specific user: INBOX/* user=kim lrw.

And re-configure the ACL plugin:

# dovecot.conf

plugin {
  acl = vfile:/etc/dovecot/dovecot-acl
}

Afterwards you can remove the old global ACL directory parent:

rm -rf /etc/dovecot/acls/

Changes to statistics

• The bytes_in and bytes_out field in several events have been renamed as net_in_bytes and net_out_bytes. Check Events for details.