diff --git a/.gitignore b/.gitignore index 12b66ae79..aed384744 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,9 @@ *.html bun.lockb node_modules/ +lib/data/*.mjs .vitepress/cache/ .vitepress/dist/ .vitepress/local.js +.vitepress/.temp /man/ diff --git a/docs/installation/upgrade/2.3-to-2.4.md b/docs/installation/upgrade/2.3-to-2.4.md index c4336fefd..e3cdf913c 100644 --- a/docs/installation/upgrade/2.3-to-2.4.md +++ b/docs/installation/upgrade/2.3-to-2.4.md @@ -21,11 +21,37 @@ setup. ## Dovecot CE +### Configuration Changes + + + + + + + + + + + +### Added Features + + + + + + + + + +#### Settings + + + ### Deprecated Features | 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 @@ -36,6 +62,33 @@ setup. | dsync | Use `doveadm sync` instead. `dsync` has been a symlink to `doveadm` already, this release removed the symlink completely. | | director | Support for the Dovecot Director architecture has been removed. For a small-scale, unsupported replacement, see [[link,lua_director]]. | | replicator | Use [[link,nfs]] or some other shared filesystem instead. | + + + + + + +### Changed Features + + + + + + + +#### Default Settings + +| Setting | Old Default | New Default | Notes | +| ------- | ----------- | ----------- | ----- | + + + + + + +### Service defaults + + ### Event Changes @@ -50,5 +103,16 @@ setup. | [[event,fts_flatcurve_query]] | This event was added. | | [[event,fts_flatcurve_rescan]] | This event was added. | | [[event,fts_flatcurve_rotate]] | This event was added. | + + + + + + + + +### Doveadm + + - + diff --git a/docs/installation/upgrade/include/2.3-to-2.4.inc b/docs/installation/upgrade/include/2.3-to-2.4.inc deleted file mode 100644 index a555ae413..000000000 --- a/docs/installation/upgrade/include/2.3-to-2.4.inc +++ /dev/null @@ -1,442 +0,0 @@ -## Dovecot Core - -### 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 -[[setting,dovecot_config_version]]. This helps to avoid unexpected -configuration changes in the future. - -Another new required setting is [[setting,dovecot_storage_version]]. This helps -to avoid unexpected storage file format incompatibilities. - -#### Directory hashing - -If you have been using `/home/%2.256N/%u` or similar constructs: - -* How to replace `%N` in new format: - - * `%2.256Nu` becomes `%{ user | md5 | substr(0, 8) % 256 | hex(2)}` to return maximum 256 different hashes in range `00..ff`. - - * `%256Nu` becomes `%{ user | md5 | substr(0, 8) % 256 | hex}` to return maximum 256 different hashes in range `0..ff` (without 0-padding in the front). - -* How to replace '%M' in new format: - - * `%1Mu/%2.1Mu/%u` becomes `%{user | md5 | hexlify(1)}/%{user | md5 | hexlify | substr(2,1)}/%{user}` to returns directories from `0/0/user` to - `f/f/user`. - -* There is no way to use '%H' anymore. - -#### passdb/userdb Section Naming - -[[link,passdb]] and [[link,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. - -#### Unknown/Invalid Variables - -Unknown/invalid `%{variables}` cause Dovecot errors. This may cause, -e.g., authentication failures if the old (broken) behavior was relied on. - -#### base64url Hash Modifier - -Added base64url format to hash modifier in variable expansion. Example: -`%{sha1;format=base64url:username}`. See [[link,settings_variables_modifiers]]. - -#### fs-crypt - -[[link,mail_crypt_fs_crypt]] now requires encryption keys by default. - -#### Event Filters - -Size units are allowed when specifying event filter values. For example, -`100kb` is accepted as equivalent to `102400`. - -Interval units are allowed when specifying event filter values. For -example, `1min` is accepted as equivalent to `60000000`. - -Event filters support escaping wildcard `*` and `?` characters by prefixing -them with `\`. - -#### Changed types for FTS header settings - -| Setting Name | Update | -| --- | --- | -| [[setting,fts_header_excludes]] | Changed to [[link,settings_types_boollist]]. | -| [[setting,fts_header_includes]] | Changed to [[link,settings_types_boollist]]. | - -### Added Features - -#### Settings - -* [[setting,auth_internal_failure_delay]] -* [[setting,fts_message_max_size]] -* [[setting,login_socket_path]] -* [[setting,quota_mailbox_count]] -* [[setting,quota_mailbox_message_count]] -* [[setting,submission_add_received_header]] - -#### Auth Policy Parameters - -See [[link,auth_policy]]. - -| Parameter | Notes | -| --------- | ----- | -| `fail_type` parameter to [[setting,auth_policy_request_attributes]] | Parameter was added. | - -#### Cassandra Parameters - -See [[link,sql_cassandra]]. - -| Parameter | Notes | -| --------- | ----- | -| `log_retries` | Parameter 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 | [[plugin,mail-crypt]] and [[link,mail_crypt_fs_crypt]] now support these curves. | - -#### LDAP Parameters - -See [[link,auth_ldap]]. - -| Feature | Notes | -| ------- | ----- | -| `%{ldap_multi}` variable | Variable was added to LDAP configuration file to allow for fetching a multi-valued attribute. | - -#### imapc_features Parameters - -See [[setting,imapc_features]]. - -| Feature | Notes | -| ------- | ----- | -| `no-qresync` | Parameter was added. | - -### Removed Features - -#### Backends and Plugins - -| Backend | Notes | -| ------- | ----- | -| checkpassword auth database | Use [[link,auth_lua]] instead. | -| Dict passdb & userdb driver | Use [[link,auth_lua]] instead. | -| Dict quota; Dirsize quota | These drivers are removed. You should use [[link,quota_driver_count]] instead along with [[plugin,quota-clone]].
Note that switching to quota count can cause all user's indexes to update, so reserve time for this. | -| imap-zlib plugin | The IMAP `COMPRESS` extension is now automatically enabled. | -| mailbox-alias plugin | Depending on the use case, replacement may be the [[setting,mailbox_special_use]] mailbox setting and/or [[link,sieve]] filters. | -| Memcached dict driver | Use [[link,dict_redis]] instead. | -| old-stats plugin | Use [[link,stats]] instead. `auth_stats` setting has been removed too. | -| shadow auth driver | Use [[link,auth_pam]] instead. | -| XZ Compression | You need to perform migration using a different compression format. With [[link,maildir]], you can try uncompressing all your mail and compressing them with another algorithm while Dovecot is not running. | -| zlib plugin | Use [[plugin,mail-compress]] with the [[setting,mail_compress_write_method]] setting instead. | - -#### Settings - -| Setting | Notes | -| ------- | ----- | -| `auth_debug` | Use [[setting,log_debug]] filter instead. Example: `log_debug=category=auth`. | -| `auth_default_realm` | Replaced by [[setting,auth_default_domain]]. | -| `auth_stats` | | -| `auth_worker_max_count` | Use [[link,service_configuration,service-specific process limit]]. | -| `dict_db_config` | Berkeley DB is not supported anymore. | -| `disable_plaintext_auth` | Replaced by [[setting,auth_allow_cleartext]]. | -| `imap_id_log` | Replaced by the [[event,imap_id_received]] event. | -| `login_access_sockets` | Use [[link,auth_lua]] instead. Dovecot will fail to start if this setting is present in configuration. | -| `push_notification_backend` | Use [[setting,push_notification_driver]] instead. | -| `quota_set` | | -| `sieve_dir` | See [[link,sieve_file]] and [[link,sieve_location]]. | -| `sieve_global_dir` | See [[link,sieve_file]] and [[link,sieve_location]]. | -| `sieve_global_path` | See [[link,sieve_file]] and [[link,sieve_location]]. | -| `sieve_vacation_max_subject_codepoints` | | -| `auth_policy_server_timeout_msecs` | See: [[link,auth_policy_configuration]]. | -| `mail_crypt_require_encrypted_user_key` | Replaced by [[setting,crypt_user_key_require_encrypted]], [[setting,crypt_user_key_password]] and [[setting,crypt_user_key_encryption_key]]. | -| `verbose_ssl` | Use [[setting,log_debug,category=ssl]] instead. | -| `mail_location` setting & `mail` userdb field | Split into multiple [[link,mail_location,mail_*]] settings. | -| `listescape` plugin | [[setting,mailbox_list_storage_escape_char]] setting. | -| `fts` | Replaced by [[setting,fts]] named filter. | -| `fts_autoindex_exclude` | Replaced by boolean property [[setting,fts_autoindex]], nested inside [[setting,mailbox]] blocks. Note that the values are inverted as compared to those in the old `fts_autoindex_exclude`. | -| `fts_decoder` | Replaced by [[setting,fts_decoder_driver]] and [[setting,fts_decoder_script_socket_path]]. | -| `fts_solr` | Replaced by [[setting,fts_solr_url]], [[setting,fts_solr_batch_size]], [[setting,fts_solr_soft_commit]], and [[setting,http_client_rawlog_dir]] settings. | -| `fts_tika` | Replaced by [[setting,fts_decoder_driver]] and [[setting,fts_decoder_tika_url]]. | -| `fts_language_config` | Renamed to [[setting,textcat_config_path]]. | -| `fts_languages` | Converted into [[setting,language]] blocks. | -| `fts_filters` | Split into [[setting,language_filters]], [[setting,language_filter_normalizer_icu_id]], [[setting,language_filter_stopwords_dir]]. | -| `fts_tokenizers` | Split into [[setting,language_tokenizers]], [[setting,language_tokenizer_address_token_maxlen]], [[setting,language_tokenizer_generic_algorithm]], [[setting,language_tokenizer_generic_token_maxlen]], [[setting,language_tokenizer_generic_wb5a]], [[setting,language_tokenizer_kuromoji_icu_id]], [[setting,language_tokenizer_kuromoji_split_compounds]], [[setting,language_tokenizer_kuromoji_token_maxlen]]. | -| `service_count` | Renamed to [[setting,service_restart_request_count]]. The default value is set to `unlimited`. Value `0` is now a configuration error. | -| passdb/userdb `:protected` | Renamed to `:default` | -| `passdb_default_fields`, `passdb_override_fields` | Replaced by [[setting,passdb_fields]] | -| `userdb_default_fields`, `userdb_override_fields` | Replaced by [[setting,userdb_fields]] | -| `quota`, `quota_rule` | Split into separate [[plugin,quota,quota settings]]. | -| `quota_grace` | Renamed to [[setting,quota_storage_grace]]. | -| `quota_over_flag` | Renamed to [[setting,quota_over_status_current]]. | -| `quota_over_flag_lazy_check` | Renamed to [[setting,quota_over_status_lazy_check]]. | -| `quota_over_flag_value` | Renamed to [[setting,quota_over_status_mask]]. | -| `quota_over_script` | Replaced by [[setting,quota_over_status]] named filter with [[setting,execute]]. | -| `quota_max_mail_size` | Renamed to [[setting,quota_mail_size]]. The default value is set to `unlimited`. | - -#### Other Features - -| Feature | Notes | -| ------- | ----- | -| Dovecot director role | Replaced with the [Dovecot Pro Palomar architecture](https://doc.dovecotpro.com/). | -| Global ACL directory | Use [[link,acl_global_file]] instead. See [below](#use-global-acl-files-instead-of-global-acl-directories) 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. | -| "size.virtual" index record | 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. | -| `ssl-parameters.dat` | This file is no longer converted automatically by config process, you need to set [[setting,ssl_dh_file]] setting if you need non-ECC Diffie-Hellman. | -| TCP wrapper support | Use [[link,auth_lua]] instead. | -| Weak password schemes | Weak password schemes are disabled by default; you need to use [[setting,auth_allow_weak_schemes]] to enable them. | -| Global ACL directory | See [ACLs](#acls) below. | - -#### dict Proxy Parameters - -See [[link,dict_proxy]]. - -| Parameter | Notes | -| --------- | ----- | -| `idle_msecs` | Deprecated dict proxy parameter. Use [[link,dict_idle_timeout]] setting instead. | -| `warn_slow_msecs` | Deprecated dict proxy parameter. Use [[link,dict_slow_warn]] setting instead. | - -#### Cassandra Parameters - -See [[link,sql_cassandra]]. - -| 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. | - -### Changed Features - -#### Settings - -| Setting | Notes | -| ------- | ------- | -| [[setting,ssl]] | Connections from [[setting,login_trusted_networks]] are now also required to be SSL/TLS encrypted with the setting `ssl=required`. | -| [[setting,ssl_min_protocol]] | The `SSLv3` option was removed, as it is no longer secure. | - -#### Default Settings - -| Setting | Old Default | New Default | Notes | -| ------- | ----------- | ----------- | ----- | -| [[setting,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. | -| [[setting,mail_cache_max_headers_count]] | unlimited | 100 | New feature, explicitly set to `0` for the old behavior. | -| [[setting,mail_cache_max_header_name_length]] | unlimited | 100 | New feature, explicitly set to `0` for the old behavior. | -| [[setting,mail_log_prefix]] | `%s(%u)<%{pid}><%{session}>:` | `%s(%u)<%{process:pid}><%{session}>:` | Uses new process key. | -| [[setting,mailbox_list_drop_noselect]] | `no` | `yes` | `\NoSelect` folders are now dropped by default. | -| `service/anvil/chroot` | empty | \ | Anvil is no longer chrooted. | -| `service/anvil/user` | $default_internal_user | \ | Anvil runs as root. | -| `service/auth-worker/process_limit` | 1 | 30 | | - -#### Service Defaults - -##### LMTP - -Default LMTP proxy destination port is now `24`. - -### 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 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. - -#### --no-userdb-lookup parameter - -Added the `--no-userdb-lookup` parameter to doveadm mail commands. - -### ACLs - -#### 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 [[link,acl_global_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. - -##### Example - -With the following starting configuration: - -::: code-group -```[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 ACLs to `dovecot.conf`: - -```[dovecot.conf] -namespace inbox { - # previously from /etc/dovecot/acls/INBOX - mailbox INBOX { - acl owner { - rights = lrwstipekxa - } - acl anyone { - rights = lr - } - acl user=kim { - rights = l - } - } - # previously from /etc/dovecot/acls/foo/.DEFAULT - mailbox INBOX/foo { - acl user=timo { - rights = lr - } - acl user=kim { - rights = lrw - } - } - # previously from /etc/dovecot/acls/foo/bar - mailbox INBOX/foo/bar { - acl user=kim { - rights = lrw - } - } -``` - -Note that at this point you could simplify specific rules, e.g. use mailbox -name wildcards to replace lines for a specific user: - -```[dovecot.conf] -mailbox INBOX/* { - acl user=kim { - rights = lrw - } -} -``` - -And re-configure the ACL plugin: - -```[dovecot.conf] -acl_driver = vfile -acl_globals_only = yes -``` - -Afterwards you can remove the old global ACL directory parent: - -```sh -rm -rf /etc/dovecot/acls/ -``` - -### Event Changes - -#### Core Events - -| Event | Change | -| ----- | ------ | -| `auth_client_cache_flush_started` | Event was removed. | -| `auth_client_cache_flush_finished` | Event was removed. | -| [[event,imap_id_received]] | Event was added. | -| [[event,login_aborted]] | Event was added. | -| [[event,mail_metadata_accessed]] | Event was added. | -| [[event,pop3_command_finished]] | Event was added. | - -#### Event Fields - -| Event | Field | Change | -| ----- | ----- | ------ | -| [[event,dns_worker_request_finished]] | `cached` | Field was added. | -| Mail user events | `service` | Field was added. | -| [[event,proxy_session_finished]] | `error_code` | Field was added. | -| [[event,proxy_session_finished]] | `idle_usecs` | Field was changed from `idle_secs`. | -| [[event,smtp_server_transaction_rcpt_finished]] | `dest_host` | Field was added. | -| [[event,smtp_server_transaction_rcpt_finished]] | `dest_ip` | Field was added. | -| [[event,sql_query_finished]] | `consistency` | Field was added. | -| [[event,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 [[link,secured_connections]]. | - -#### Exports - -Events can now be exported to a local file or a unix socket. See -[[link,event_export_drivers]]. - -### 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. - -### Lua Authentication - -Lua passdb/userdb now passes all args key/values to an initialization function. -See [[link,auth_lua_initialization]]. diff --git a/docs/installation/upgrade/include/2.4-acls.inc b/docs/installation/upgrade/include/2.4-acls.inc new file mode 100644 index 000000000..7fd30dfed --- /dev/null +++ b/docs/installation/upgrade/include/2.4-acls.inc @@ -0,0 +1,90 @@ +### ACLs + +#### Use ACL settings instead of Global ACL Directories or Global ACL File + +With the following starting configuration: + +::: code-group +```[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 ACLs to `dovecot.conf`: + +```[dovecot.conf] +namespace inbox { + # previously from /etc/dovecot/acls/INBOX + mailbox INBOX { + acl owner { + rights = lrwstipekxa + } + acl anyone { + rights = lr + } + acl user=kim { + rights = l + } + } + # previously from /etc/dovecot/acls/foo/.DEFAULT + mailbox INBOX/foo { + acl user=timo { + rights = lr + } + acl user=kim { + rights = lrw + } + } + # previously from /etc/dovecot/acls/foo/bar + mailbox INBOX/foo/bar { + acl user=kim { + rights = lrw + } + } +``` + +Note that at this point you could simplify specific rules, e.g. use mailbox +name wildcards to replace lines for a specific user: + +```[dovecot.conf] +mailbox INBOX/* { + acl user=kim { + rights = lrw + } +} +``` + +And re-configure the ACL plugin: + +```[dovecot.conf] +acl_driver = vfile +acl_globals_only = yes +``` + +Afterwards you can remove the old global ACL directory parent: + +```sh +rm -rf /etc/dovecot/acls/ +``` diff --git a/docs/installation/upgrade/include/2.4-added-auth-policy-parameters.inc b/docs/installation/upgrade/include/2.4-added-auth-policy-parameters.inc new file mode 100644 index 000000000..f8b6d2f60 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-added-auth-policy-parameters.inc @@ -0,0 +1,7 @@ +#### Auth Policy Parameters + +See [[link,auth_policy]]. + +| Parameter | Notes | +| --------- | ----- | +| `%{fail_type}` variable to [[setting,auth_policy_request_attributes]] | Variable was added. | diff --git a/docs/installation/upgrade/include/2.4-added-cryptographic-features.inc b/docs/installation/upgrade/include/2.4-added-cryptographic-features.inc new file mode 100644 index 000000000..e2fe0d4cc --- /dev/null +++ b/docs/installation/upgrade/include/2.4-added-cryptographic-features.inc @@ -0,0 +1,7 @@ +#### 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 | [[plugin,mail-crypt]] and [[link,mail_crypt_fs_crypt]] now support these curves. | diff --git a/docs/installation/upgrade/include/2.4-added-imapc_features-parameters.inc b/docs/installation/upgrade/include/2.4-added-imapc_features-parameters.inc new file mode 100644 index 000000000..a8f9c45fc --- /dev/null +++ b/docs/installation/upgrade/include/2.4-added-imapc_features-parameters.inc @@ -0,0 +1,8 @@ +#### imapc_features Parameters + +See [[setting,imapc_features]]. + +| Feature | Notes | +| ------- | ----- | +| `no-qresync` | Parameter was added. | + diff --git a/docs/installation/upgrade/include/2.4-added-settings.inc b/docs/installation/upgrade/include/2.4-added-settings.inc new file mode 100644 index 000000000..0b0be164e --- /dev/null +++ b/docs/installation/upgrade/include/2.4-added-settings.inc @@ -0,0 +1,7 @@ +* [[setting,auth_internal_failure_delay]] +* [[setting,fts_message_max_size]] +* [[setting,login_socket_path]] +* [[setting,quota_mailbox_count]] +* [[setting,quota_mailbox_message_count]] +* [[setting,submission_add_received_header]] +* [[setting,cassandra_log_retries]] diff --git a/docs/installation/upgrade/include/2.4-changed-settings.inc b/docs/installation/upgrade/include/2.4-changed-settings.inc new file mode 100644 index 000000000..fcd38863f --- /dev/null +++ b/docs/installation/upgrade/include/2.4-changed-settings.inc @@ -0,0 +1,6 @@ +#### Settings + +| Setting | Notes | +| ------- | ------- | +| [[setting,ssl]] | Connections from [[setting,login_trusted_networks]] are now also required to be SSL/TLS encrypted with the setting `ssl=required`. | +| [[setting,ssl_min_protocol]] | The `SSLv3` option was removed, as it is no longer secure. | diff --git a/docs/installation/upgrade/include/2.4-converted-settings.inc b/docs/installation/upgrade/include/2.4-converted-settings.inc new file mode 100644 index 000000000..23cde4445 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-converted-settings.inc @@ -0,0 +1,33 @@ +#### Converted Settings + +| Setting | Notes | +| ------- | ----- | +| `auth_debug` | Use [[setting,log_debug]] filter instead. Example: `log_debug=category=auth`. | +| `auth_default_realm` | Replaced by [[setting,auth_default_domain]]. | +| `auth_worker_max_count` | Use [[link,service_configuration,service-specific process limit]]. | +| `disable_plaintext_auth` | Replaced by [[setting,auth_allow_cleartext]]. | +| `push_notification_backend` | Use [[setting,push_notification_driver]] instead. | +| `auth_policy_server_timeout_msecs` | See: [[link,auth_policy_configuration]]. | +| `mail_crypt_require_encrypted_user_key` | Replaced by [[setting,crypt_user_key_require_encrypted]], [[setting,crypt_user_key_password]] and [[setting,crypt_user_key_encryption_key]]. | +| `verbose_ssl` | Use [[setting,log_debug,category=ssl]] instead. | +| `mail_location` setting & `mail` userdb field | Split into multiple [[link,mail_location,mail_*]] settings. | +| `fts` | Replaced by [[setting,fts]] named filter. | +| `fts_autoindex_exclude` | Replaced by boolean property [[setting,fts_autoindex]], nested inside [[setting,mailbox]] blocks. Note that the values are inverted as compared to those in the old `fts_autoindex_exclude`. | +| `fts_decoder` | Replaced by [[setting,fts_decoder_driver]] and [[setting,fts_decoder_script_socket_path]]. | +| `fts_solr` | Replaced by [[setting,fts_solr_url]], [[setting,fts_solr_batch_size]], [[setting,fts_solr_soft_commit]], and [[setting,http_client_rawlog_dir]] settings. | +| `fts_tika` | Replaced by [[setting,fts_decoder_driver]] and [[setting,fts_decoder_tika_url]]. | +| `fts_language_config` | Renamed to [[setting,textcat_config_path]]. | +| `fts_languages` | Converted into [[setting,language]] blocks. | +| `fts_filters` | Split into [[setting,language_filters]], [[setting,language_filter_normalizer_icu_id]], [[setting,language_filter_stopwords_dir]]. | +| `fts_tokenizers` | Split into [[setting,language_tokenizers]], [[setting,language_tokenizer_address_token_maxlen]], [[setting,language_tokenizer_generic_algorithm]], [[setting,language_tokenizer_generic_token_maxlen]], [[setting,language_tokenizer_generic_wb5a]], [[setting,language_tokenizer_kuromoji_icu_id]], [[setting,language_tokenizer_kuromoji_split_compounds]], [[setting,language_tokenizer_kuromoji_token_maxlen]]. | +| `service_count` | Renamed to [[setting,service_restart_request_count]]. The default value is set to `unlimited`. Value `0` is now a configuration error. | +| passdb/userdb `:protected` | Renamed to `:default` | +| `passdb { default_fields`, `override_fields` } | Replaced by [[setting,passdb_fields]] | +| `userdb { default_fields`, `override_fields` } | Replaced by [[setting,userdb_fields]] | +| `quota`, `quota_rule` | Split into separate [[plugin,quota,quota settings]]. | +| `quota_grace` | Renamed to [[setting,quota_storage_grace]]. | +| `quota_over_flag` | Renamed to [[setting,quota_over_status_current]]. | +| `quota_over_flag_lazy_check` | Renamed to [[setting,quota_over_status_lazy_check]]. | +| `quota_over_flag_value` | Renamed to [[setting,quota_over_status_mask]]. | +| `quota_over_script` | Replaced by [[setting,quota_over_status]] named filter with [[setting,execute]]. | +| `quota_max_mail_size` | Renamed to [[setting,quota_mail_size]]. The default value is set to `unlimited`. | diff --git a/docs/installation/upgrade/include/2.4-core-events.inc b/docs/installation/upgrade/include/2.4-core-events.inc new file mode 100644 index 000000000..1bc5b4628 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-core-events.inc @@ -0,0 +1,22 @@ +| `auth_client_cache_flush_started` | Event was removed. | +| `auth_client_cache_flush_finished` | Event was removed. | +| [[event,imap_id_received]] | Event was added. | +| [[event,login_aborted]] | Event was added. | +| [[event,mail_metadata_accessed]] | Event was added. | +| [[event,pop3_command_finished]] | Event was added. | + +#### Event Fields + +| Event | Field | Change | +| ----- | ----- | ------ | +| [[event,dns_worker_request_finished]] | `cached` | Field was added. | +| Mail user events | `service` | Field was added. | +| [[event,proxy_session_finished]] | `error_code` | Field was added. | +| [[event,proxy_session_finished]] | `idle_usecs` | Field was changed from `idle_secs`. | +| [[event,smtp_server_transaction_rcpt_finished]] | `dest_host` | Field was added. | +| [[event,smtp_server_transaction_rcpt_finished]] | `dest_ip` | Field was added. | +| [[event,sql_query_finished]] | `consistency` | Field was added. | +| [[event,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 [[link,secured_connections]]. | diff --git a/docs/installation/upgrade/include/2.4-default-settings.inc b/docs/installation/upgrade/include/2.4-default-settings.inc new file mode 100644 index 000000000..0ce34c2ef --- /dev/null +++ b/docs/installation/upgrade/include/2.4-default-settings.inc @@ -0,0 +1,8 @@ +| [[setting,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. | +| [[setting,mail_cache_max_headers_count]] | unlimited | 100 | New feature, explicitly set to `0` for the old behavior. | +| [[setting,mail_cache_max_header_name_length]] | unlimited | 100 | New feature, explicitly set to `0` for the old behavior. | +| [[setting,mail_log_prefix]] | `%s(%u)<%{pid}><%{session}>:` | `%{protocol}(%{user})<%{process:pid}><%{session}>:` | New variable expansion syntax. | +| [[setting,mailbox_list_drop_noselect]] | `no` | `yes` | `\NoSelect` folders are now dropped by default. | +| `service/anvil/chroot` | empty | \ | Anvil is no longer chrooted. | +| `service/anvil/user` | $default_internal_user | \ | Anvil runs as root. | +| `service/auth-worker/process_limit` | 1 | 30 | | diff --git a/docs/installation/upgrade/include/2.4-deprecated-global-acl-file.inc b/docs/installation/upgrade/include/2.4-deprecated-global-acl-file.inc new file mode 100644 index 000000000..805227c2e --- /dev/null +++ b/docs/installation/upgrade/include/2.4-deprecated-global-acl-file.inc @@ -0,0 +1 @@ +| [[setting,acl_global_path]] | Using ACL file is deprecated, see [below](#use-acl-settings-instead-of-global-acl-directories-or-global-acl-file) for details on migration. | diff --git a/docs/installation/upgrade/include/2.4-deprecated-sis.inc b/docs/installation/upgrade/include/2.4-deprecated-sis.inc new file mode 100644 index 000000000..cb6e000cf --- /dev/null +++ b/docs/installation/upgrade/include/2.4-deprecated-sis.inc @@ -0,0 +1 @@ +| 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. | diff --git a/docs/installation/upgrade/include/2.4-dict-proxy-parameters.inc b/docs/installation/upgrade/include/2.4-dict-proxy-parameters.inc new file mode 100644 index 000000000..5017f80ed --- /dev/null +++ b/docs/installation/upgrade/include/2.4-dict-proxy-parameters.inc @@ -0,0 +1,8 @@ +#### dict Proxy Parameters + +See [[link,dict_proxy]]. + +| Parameter | Notes | +| --------- | ----- | +| `idle_msecs` | Use [[link,dict_idle_timeout]] setting instead. | +| `warn_slow_msecs` | Use [[link,dict_slow_warn]] setting instead. | diff --git a/docs/installation/upgrade/include/2.4-directory-hashing.inc b/docs/installation/upgrade/include/2.4-directory-hashing.inc new file mode 100644 index 000000000..4a4ec83b5 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-directory-hashing.inc @@ -0,0 +1,17 @@ + +#### Directory hashing + +If you have been using `/home/%2.256N/%u` or similar constructs: + +* How to replace `%N` in new format: + + * `%2.256Nu` becomes `%{ user | md5 | substr(0, 8) % 256 | hex(2)}` to return maximum 256 different hashes in range `00..ff`. + + * `%256Nu` becomes `%{ user | md5 | substr(0, 8) % 256 | hex}` to return maximum 256 different hashes in range `0..ff` (without 0-padding in the front). + +* How to replace '%M' in new format: + + * `%1Mu/%2.1Mu/%u` becomes `%{user | md5 | hexlify(1)}/%{user | md5 | hexlify | substr(2,1)}/%{user}` to returns directories from `0/0/user` to + `f/f/user`. + +* There is no way to use '%H' anymore. diff --git a/docs/installation/upgrade/include/2.4-doveadm.inc b/docs/installation/upgrade/include/2.4-doveadm.inc new file mode 100644 index 000000000..743deb2de --- /dev/null +++ b/docs/installation/upgrade/include/2.4-doveadm.inc @@ -0,0 +1,28 @@ +#### 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. diff --git a/docs/installation/upgrade/include/2.4-empty-userdb-variables.inc b/docs/installation/upgrade/include/2.4-empty-userdb-variables.inc new file mode 100644 index 000000000..1784545bb --- /dev/null +++ b/docs/installation/upgrade/include/2.4-empty-userdb-variables.inc @@ -0,0 +1,5 @@ +#### Empty userdb Variables + +userdb fields can be set to empty value. Previously they became changed +to `yes` value. + diff --git a/docs/installation/upgrade/include/2.4-event-filters.inc b/docs/installation/upgrade/include/2.4-event-filters.inc new file mode 100644 index 000000000..d4550af51 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-event-filters.inc @@ -0,0 +1,10 @@ +#### Event Filters + +Size units are allowed when specifying event filter values. For example, +`100kb` is accepted as equivalent to `102400`. + +Interval units are allowed when specifying event filter values. For +example, `1min` is accepted as equivalent to `60000000`. + +Event filters support escaping wildcard `*` and `?` characters by prefixing +them with `\`. diff --git a/docs/installation/upgrade/include/2.4-exports.inc b/docs/installation/upgrade/include/2.4-exports.inc new file mode 100644 index 000000000..2dc2b358c --- /dev/null +++ b/docs/installation/upgrade/include/2.4-exports.inc @@ -0,0 +1,5 @@ + +#### Exports + +Events can now be exported to a local file or a unix socket. See +[[link,event_export_drivers]]. diff --git a/docs/installation/upgrade/include/2.4-fs-crypt.inc b/docs/installation/upgrade/include/2.4-fs-crypt.inc new file mode 100644 index 000000000..3d05343d4 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-fs-crypt.inc @@ -0,0 +1,3 @@ +#### fs-crypt + +[[link,mail_crypt_fs_crypt]] now requires encryption keys by default. diff --git a/docs/installation/upgrade/include/2.4-fts-header-settings.inc b/docs/installation/upgrade/include/2.4-fts-header-settings.inc new file mode 100644 index 000000000..343fa476d --- /dev/null +++ b/docs/installation/upgrade/include/2.4-fts-header-settings.inc @@ -0,0 +1,7 @@ +#### Changed types for FTS header settings + +| Setting Name | Update | +| --- | --- | +| [[setting,fts_header_excludes]] | Changed to [[link,settings_types_boollist]]. | +| [[setting,fts_header_includes]] | Changed to [[link,settings_types_boollist]]. | + diff --git a/docs/installation/upgrade/include/2.4-other.inc b/docs/installation/upgrade/include/2.4-other.inc new file mode 100644 index 000000000..a2347c3b9 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-other.inc @@ -0,0 +1,12 @@ + +### 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. + +### Lua Authentication + +Lua passdb/userdb now passes all args key/values to an initialization function. +See [[link,auth_lua_initialization]]. diff --git a/docs/installation/upgrade/include/2.4-redesign.inc b/docs/installation/upgrade/include/2.4-redesign.inc new file mode 100644 index 000000000..bc5edff73 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-redesign.inc @@ -0,0 +1,16 @@ +::: 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 +[[setting,dovecot_config_version]]. This helps to avoid unexpected +configuration changes in the future. + +Another new required setting is [[setting,dovecot_storage_version]]. This helps +to avoid unexpected storage file format incompatibilities. + +Note that the configuration syntax has been changed, and your old configuration **will not** work +without changes. diff --git a/docs/installation/upgrade/include/2.4-removed-other-features.inc b/docs/installation/upgrade/include/2.4-removed-other-features.inc new file mode 100644 index 000000000..2eef8b661 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-removed-other-features.inc @@ -0,0 +1,17 @@ +| Dovecot director role | Replaced with the [Dovecot Pro Palomar architecture](https://doc.dovecotpro.com/). | +| Global ACL directory | Use [[setting,acl]] instead. See [below](#use-acl-settings-instead-of-global-acl-directories-or-global-acl-file) 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 [[setting,ssl_dh_file]] setting if you need non-ECC Diffie-Hellman. | +| TCP wrapper support | Use [[link,auth_lua]] instead. | +| Weak password schemes | Weak password schemes are disabled by default; you need to use [[setting,auth_allow_weak_schemes]] to enable them. | + +#### Cassandra Parameters + +See [[link,sql_cassandra]]. + +| 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. | diff --git a/docs/installation/upgrade/include/2.4-removed-plugins.inc b/docs/installation/upgrade/include/2.4-removed-plugins.inc new file mode 100644 index 000000000..db8cea7da --- /dev/null +++ b/docs/installation/upgrade/include/2.4-removed-plugins.inc @@ -0,0 +1,15 @@ +#### Backends and Plugins + +| Backend | Notes | +| ------- | ----- | +| checkpassword auth database | Use [[link,auth_lua]] instead. | +| Dict passdb & userdb driver | Use [[link,auth_lua]] instead. | +| Dict quota; Dirsize quota | These drivers are removed. You should use [[link,quota_driver_count]] instead along with [[plugin,quota-clone]].
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 [[setting,mailbox_list_storage_escape_char]] instead. | +| mailbox-alias plugin | Depending on the use case, replacement may be the [[setting,mailbox_special_use]] mailbox setting and/or [[link,sieve]] filters. | +| Memcached dict driver | Use [[link,dict_redis]] instead. | +| old-stats plugin | Use [[link,stats]] instead. `auth_stats` setting has been removed too. | +| shadow auth driver | Use [[link,auth_pam]] instead. | +| XZ Compression | You need to perform migration using a different compression format. With [[link,maildir]], you can try uncompressing all your mail and compressing them with another algorithm while Dovecot is not running. | +| zlib plugin | Use [[plugin,mail-compress]] with the [[setting,mail_compress_write_method]] setting instead. | diff --git a/docs/installation/upgrade/include/2.4-removed-settings.inc b/docs/installation/upgrade/include/2.4-removed-settings.inc new file mode 100644 index 000000000..3b1848b78 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-removed-settings.inc @@ -0,0 +1,13 @@ +#### Settings + +| Setting | Notes | +| ------- | ----- | +| `auth_stats` | | +| `dict_db_config` | Berkeley DB is not supported anymore. | +| `imap_id_log` | Replaced by the [[event,imap_id_received]] event. | +| `login_access_sockets` | Use [[link,auth_lua]] instead. Dovecot will fail to start if this setting is present in configuration. | +| `quota_set` | | +| `sieve_dir` | See [[link,sieve_file]] and [[link,sieve_location]]. | +| `sieve_global_dir` | See [[link,sieve_file]] and [[link,sieve_location]]. | +| `sieve_global_path` | See [[link,sieve_file]] and [[link,sieve_location]]. | +| `sieve_vacation_max_subject_codepoints` | | diff --git a/docs/installation/upgrade/include/2.4-section-naming.inc b/docs/installation/upgrade/include/2.4-section-naming.inc new file mode 100644 index 000000000..8d29bafd8 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-section-naming.inc @@ -0,0 +1,14 @@ +#### passdb/userdb Section Naming + +[[link,passdb]] and [[link,userdb]] sections now require a name, i.e.: + +``` +# This gives an error: +passdb { + ... +} + +# Use this instead: +passdb some_name { +} +``` diff --git a/docs/installation/upgrade/include/2.4-service-defaults.inc b/docs/installation/upgrade/include/2.4-service-defaults.inc new file mode 100644 index 000000000..94f787150 --- /dev/null +++ b/docs/installation/upgrade/include/2.4-service-defaults.inc @@ -0,0 +1,3 @@ +##### LMTP + +Default LMTP proxy destination port is now `24`. diff --git a/docs/installation/upgrade/include/2.4-unknown-invalid-variables.inc b/docs/installation/upgrade/include/2.4-unknown-invalid-variables.inc new file mode 100644 index 000000000..a46f57f0c --- /dev/null +++ b/docs/installation/upgrade/include/2.4-unknown-invalid-variables.inc @@ -0,0 +1,5 @@ +#### Unknown/Invalid Variables + +Unknown/invalid `%{variables}` cause Dovecot errors. This may cause, +e.g., authentication failures if the old (broken) behavior was relied on. +