Upgrading from OX Dovecot Pro 2.3.x to Dovecot Pro 3.0.x

Dovecot Pro

Configuration Changes

WARNING

Dovecot 2.3.x settings will NOT work unless the configuration is changed as described in this section.

Required Settings

The first setting in dovecot.conf MUST now be dovecot_config_version. This helps to avoid unexpected configuration changes in the future.

Another new required setting is dovecot_storage_version. This helps to avoid unexpected storage file format incompatibilities.

Using dovecot_storage_version = 2.3.20 disables the new fts.S file format (the old fts_dovecot_message_count_stats=no).

Unknown/Invalid Variables

Unknown/invalid %{variables} cause Dovecot errors. This may cause, e.g., authentication failures if the old (broken) behavior was relied on.

passdb/userdb Section Naming

passdb and userdb sections now require a name, i.e.:

# This gives an error:
passdb {
  ...
}

# Use this instead:
passdb some_name {
}

Empty userdb Variables

userdb fields can be set to empty value. Previously they became changed to yes value.

Product Changes

• The Director architecture has been deprecated and removed. Dovecot Pro 3.x only supports the new Dovecot Pro Palomar architecture.
  • See Transition from OX Dovecot Pro 2.3.x Architecture.
• AWS S3 Storage no longer can use object listings. Instead, Dictmap must be used.
  • See Migration from Dovecot Pro 2.3.x.
• sdbox and mdbox are no longer supported for NFS installations. Dovecot Pro 3.x only supports the obox mailbox format. Dovecot Pro 2.3.x NFS/dbox installations MUST migrate users to obox for 3.x.
  • See Obox: NFS.

Added Features

Auth Policy Parameters

See Authentication Policy.

Parameter	Notes
%{fail_type} variable to auth_policy_request_attributes	Variable was added.

Cryptographic Features

Feature	Notes
ARGON2 password scheme	Support for the ARGON2 password scheme was added.
SCRAM-SHA-1, SCRAM-SHA-256	Support SASL mechanisms for outgoing connections.
X25519, X448	mail-crypt plugin and Mail Crypt Plugin: fs-crypt now support these curves.
ML-KEM	Changed: 3.2.0 mail-crypt plugin and Mail Crypt Plugin: fs-crypt support ML-KEM keys with OpenSSL 3.3+.

imapc_features Parameters

See imapc_features.

Feature	Notes
no-qresync	Parameter was added.

LDAP Parameters

See LDAP authentication.

Feature	Notes
%{ldap_multi} variable	Variable was added to LDAP configuration file to allow for fetching a multi-valued attribute.

base64url Hash Modifier

Added base64url format to hash modifier in variable expansion. Example: %{sha1;format=base64url:username}. See Variable Modifiers.

Cassandra Parameters

See Cassandra configuration.

Parameter	Notes
log_retries	Parameter was added.

Settings

• metacache_forced_refresh_interval
• auth_internal_failure_delay
• fts_message_max_size
• login_socket_path
• quota_mailbox_count
• quota_mailbox_message_count
• submission_add_received_header
• cassandra_log_retries

Removed Features

Feature	Replacement
License Plugin	Plugin has been removed and the license_checksum setting is marked obsolete.
Dovecot director role	Replaced with the Dovecot Pro Palomar architecture.
Global ACL directory	Use acl instead. See below for details on migration.
IMAP SETQUOTA command	Quota limits can no longer be modified using the IMAP SETQUOTA command. The set_quota setting has been removed.
IPC process	Has been merged to anvil.
OpenSSL support for older than 1.0.2	Older versions are not supported anymore.
Sieve extensions: notify, imapflags, vnd.dovecot.duplicate	These deprecated Sieve extensions have been removed.
ssl-parameters.dat	This file is no longer converted automatically by config process, you need to set ssl_server_dh_file setting if you need non-ECC Diffie-Hellman.
TCP wrapper support	Use Lua authentication database instead.
Weak password schemes	Weak password schemes are disabled by default; you need to use auth_allow_weak_schemes to enable them.
local_name "multiple names" { ... }	List each name as a separate local_name { ... }

Cassandra Parameters

See Cassandra configuration.

Parameter	Notes
Cassandra ssl_verify=cert-dns setting	Removed, as it was deprecated by Cassandra cpp-driver due to it being insecure against MITM attacks.

Settings

Setting	Notes
auth_stats
dict_db_config	Berkeley DB is not supported anymore.
imap_id_log	Replaced by the imap_id_received event.
login_access_sockets	Use Lua authentication database instead. Dovecot will fail to start if this setting is present in configuration.
quota_set
sieve_dir	See Script storage.
sieve_global_dir	See Script storage.
sieve_global_path	See Script storage.
sieve_editheader_protected	Replaced by sieve_editheader_header_forbid_add and sieve_editheader_header_forbid_delete.
sieve_vacation_max_subject_codepoints

Backends and Plugins

Backend	Notes
checkpassword auth database	Use Lua authentication database instead.
Dict passdb & userdb driver	Use Lua authentication database instead.
Dict quota; Dirsize quota	These drivers are removed. You should use Quota Driver: Count instead along with quota-clone plugin. Note that switching to quota count can cause all users' indexes to update, so reserve time for this.
imap-zlib plugin	The IMAP COMPRESS extension is now automatically enabled.
listescape plugin	Use mailbox_list_storage_escape_char instead.
mailbox-alias plugin	Depending on the use case, replacement may be the mailbox_special_use mailbox setting and/or Sieve filters.
Memcached dict driver	Use Redis instead.
old-stats plugin	Use Statistics instead. auth_stats setting has been removed too.
shadow auth driver	Use PAM authentication database instead.
XZ Compression	You need to perform migration using a different compression format. With Maildir, you can try uncompressing all your mail and compressing them with another algorithm while Dovecot is not running.
zlib plugin	Use mail-compress plugin with the mail_compress_write_method setting instead.

Dictmap Settings

Dictmap configuration has been replaced by Dictmap: Settings.

Parameter	Description
cleanup-uncertain	Previously, this parameter needed to be explicitly enabled. It is now called fs_dictmap_cleanup_uncertain, which is enabled by default.
max-parallel-iter	Previously the default was 1. This parameter has been replaced by the fs_dictmap_max_parallel_iter, which defaults to 10. now.

Obox Parameters

See obox.

Parameter	Description
absolute_timeout_msecs	Use absolute_timeout instead.
connect_timeout_msecs	Use connect_timeout instead.
delete_timeout_msecs	Use delete_timeout instead.
read_timeout_msecs	Use read_timeout instead.
slow_warn_msecs	Use slow_warn instead.
timeout_msecs	Use timeout setting instead.
write_timeout_msecs	Use write_timeout setting instead.

Changed Features

Settings

Setting	Notes
ssl	Connections from login_trusted_networks are now also required to be SSL/TLS encrypted with the setting ssl=required.
ssl_min_protocol	The SSLv3 option was removed, as it is no longer secure.

fs-crypt

Mail Crypt Plugin: fs-crypt now requires encryption keys by default.

Default Settings

Setting	Old Default	New Default	Notes
fts_dovecot_mail_flush_interval	0	10
fts_dovecot_max_triplets	0	200
imapc_features	Features "delay-login", "search", "fetch-headers", "fetch-bodystructure", "fetch-size" by default. Enable "acl" and "modseq" by default, if the remote server supports it.
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.
mailbox_list_drop_noselect	no	yes	\NoSelect folders are now dropped by default.
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

Renamed Settings

Old Setting	New Setting
metacache_disable_bundle_list_cache	metacache_bundle_list_cache
metacache_disable_secondary_indexes	metacache_secondary_indexes
obox_refresh_index_once_after	metacache_refresh_index_once_after
obox_rescan_mails_once_after	metacache_rescan_mails_once_after
obox_no_pop3_backend_uidls	obox_pop3_backend_uidls
obox_dont_use_object_ids	obox_use_object_ids

Service Defaults

IMAP Hibernation

IMAP Hibernation is now enabled by default.

metacache UNIX socket listener

New default:

service metacache {
  unix_listener metacache {
    mode = 0660
    group = $default_internal_group
  }
}

LMTP

Default LMTP proxy destination port is now 24.

Event Changes

Events

Event	Change
fs_object_write_uncertain	Event was added.
auth_client_cache_flush_started	Event was removed.
auth_client_cache_flush_finished	Event was removed.
imap_id_received	Event was added.
login_aborted	Event was added.
mail_metadata_accessed	Event was added.
pop3_command_finished	Event was added.

Event Fields

Event	Field	Change
dns_worker_request_finished	cached	Field was added.
Mail user events	service	Field was added.
proxy_session_finished	error_code	Field was added.
proxy_session_finished	idle_usecs	Field was changed from idle_secs.
smtp_server_transaction_rcpt_finished	dest_host	Field was added.
smtp_server_transaction_rcpt_finished	dest_ip	Field was added.
sql_query_finished	consistency	Field was added.
sql_query_finished	error_consistency	Field was added.
Various	net_bytes_in	Field was changed from bytes_in.
Various	net_bytes_out	Field was changed from bytes_out.
Various	transport	transport=trusted was changed to transport=secured. See also secured connections.

Exports

Events can now be exported to a local file or a unix socket. See Event Export: Drivers.

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.
4. Remove the old ACL directory parent.

Doveadm

doveadm batch

The doveadm batch command was removed.

doveadm fs

doveadm fs put can now put metadata also.

doveadm indexer

Added doveadm indexer command.

doveadm save

Added -r received-date parameter. See doveadm save.

dsync

The dsync command symlink was removed. Use doveadm sync or doveadm backup commands directly instead.

Mailbox Commands

USER environment variable can be used only with --no-userdb-lookup parameter.

All mail commands require providing -u, -F, -A parameter or --no-userdb-lookup parameter. This will always be subject to user database lookup and requires access to auth userdb socket, unless --no-userdb-lookup was used.

doveadm metacache pull

Added doveadm metacache pull command.

Doveadm HTTP API

Boolean Request Values

The doveadm HTTP API now requires valid boolean values. Providing invalid boolean values will result in a 400 response.