Dovecot

https://github.com/dovecot/documentation
Admin
Dovecot is a secure and reliable open-source IMAP and POP3 mail server software that provides email...
Tokens:468,621
Snippets:3,967
Trust Score:9.1
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install Dovecot under home directory

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/rootless.md

Build and install Dovecot under the user's home directory. Run these commands from the Dovecot source directory. After installation, Dovecot is started with ~/dovecot/sbin/dovecot and an example configuration is placed in ~/dovecot/etc/dovecot/dovecot.conf.

```sh
./configure --prefix=$HOME/dovecot
make
make install
```

--------------------------------

### Expected directory permissions after setup

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/shared_mailboxes.md

Example directory permissions after applying the group-suid setup. The domain directory is group-writable with setgid, while the user subdirectory is private to the user.

```text
drwxrwsr-x 3 user dovemail 60 Oct 24 12:04 domain.example.com/
drwx--S--- 3 user user 60 Oct 24 12:04 domain.example.com/user/
```

--------------------------------

### Insert example values

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Insert example data for domains and users.

```sql
insert into transport (domain, transport) values ('domain.org', 'virtual:');
insert into transport (domain, transport) values ('foo.org', 'virtual:');
insert into users (userid, uid, gid, home) values ('user@domain.org', 1001, 1001, 'domain.org/mails/user');
insert into users (userid, uid, gid, home) values ('user2@domain.org', 1001, 1001, 'domain.org/mails/user2');
insert into users (userid, uid, gid, home) values ('user@foo.org', 1002, 1002, 'foo.org/mails/user');
insert into virtual (address, userid) values ('foo@foo.org', 'user@foo.org');
```

--------------------------------

### Basic compilation from source

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/installation.md

Standard build steps for Dovecot from source. Installs under /usr/local with configuration at /usr/local/etc/dovecot.conf and logging to syslog's mail facility.

```sh
./configure
make
sudo make install
```

--------------------------------

### Configuration: Example master user setup

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/master_users.md

Sets up master user authentication with a passwd-file passdb, enabling master login and continuing to verify the login user's existence. Must be placed in dovecot.conf. Also includes userdb configuration.

```doveconf
auth_master_user_separator = *

passdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd.masterusers
  master = yes
  result_success = continue
}

userdb passwd {
}

```

--------------------------------

### AUTHENTICATE command example with response

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Example of the AUTHENTICATE command and the server's response after successful login.

```text
AUTHENTICATE "PLAIN" "<base64-encoded credentials>"
OK "Logged in."
```

--------------------------------

### Configuration Example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/push_notification_lua.md

Example configuration for enabling the Lua push notification plugin in Dovecot.

```APIDOC
## Configuration Example

### Description
Example configuration for enabling the Lua push notification plugin in Dovecot.

### Configuration

```doveconf[dovecot.conf]
mail_plugins {
  mail_lua = yes
  notify = yes
  push_notification = yes
  push_notification_lua = yes
}

push_notification lua {
  lua_file = /path/to/lua/script
  lua_settings {
    extra_param = %{userdb:extra_param}
  }
}
```
```

--------------------------------

### Install dependencies with npm install

Source: https://github.com/dovecot/documentation/blob/main/README.md

Installs the project dependencies. Use any compatible package manager like pnpm, yarn, or bun instead of npm if preferred.

```sh
npm install
```

--------------------------------

### Update from Git

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/installation.md

Update an existing Git checkout and rebuild. Pull latest changes, then make and install.

```sh
git pull
make
sudo make install
```

--------------------------------

### Set up Python environment and install dependencies

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/design/dcrypt.md

Sets up a local Python environment and installs the required dependencies (asn1 and cryptography) for running dcrypt-decrypt.py.

```sh
# Optional but recommended: Create a virtual environment for the necessary
# python dependencies to run this script.
python -m venv venv
source venv/bin/activate
# Install the dependencies.
pip install asn1 cryptography
```

--------------------------------

### Lua script for %{lua_file} example (get_home.lua)

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/mail_lua.md

Example Lua script that defines a get_home function returning a home directory path. The comment warns this is not a good practice and is for example purposes only.

```lua
-- This is not a good way to do this, provided here for example
-- purposes only. Do not use this.

local function get_home(user)
  return "/home/" .. user
end
```

--------------------------------

### Linux /etc/pam.d/dovecot example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/pam.md

Example PAM configuration for Linux using pam_unix.so for authentication and account management. Place this in /etc/pam.d/dovecot.

```pam
auth      required        pam_unix.so nullok
account   required        pam_unix.so
```

--------------------------------

### static passdb with allow_nets and local keyword

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/passdb.md

Static password database example for a Postfix/LMTP delivery setup. The 'local' keyword is required so Postfix can verify email accounts over Unix sockets, avoiding the error about user not existing.

```doveconf
passdb static {
  password = test
  fields {
    allow_nets = local,127.0.0.1/32
  }
}
```

--------------------------------

### userdb static example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/static.md

Example static userdb configuration that sets uid, gid, and home directory using a variable for the username.

```doveconf
userdb static {
  fields {
    uid = 500
    gid = 500
    home = /home/%{user}
  }
}
```

--------------------------------

### fts-flatcurve configuration example with optional settings

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/fts_flatcurve.md

Full configuration example showing all optional settings with their default values. These are listed for documentation; most users should not need to override them. Note substring_search defaults to no in this example, but the plugin supports substring matches on by default.

```doveconf
mail_plugins {
  fts = yes
  fts_flatcurve = yes
}

fts flatcurve {
  # All of these are optional, and indicate the default values.
  # They are listed here for documentation purposes; most people should not
  # need to define/override in their config.
  commit_limit = 500
  min_term_size = 2
  optimize_limit = 10
  rotate_count = 5000
  rotate_time = 5000
  substring_search = no
}
```

--------------------------------

### Request examples for /doveadm/v1

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/doveadm.md

Two equivalent ways to send an authenticated GET request to the /doveadm/v1 endpoint using Basic authentication.

```sh
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>" http://host:port/doveadm/v1
```

```sh
curl -u doveadm:password http://host:port/doveadm/v1
```

--------------------------------

### EC parameters header example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/mail_crypt.md

Example of EC parameters that may appear before the private key.

```text
-----BEGIN EC PARAMETERS-----
BgUrgQQACg==
-----END EC PARAMETERS-----
```

--------------------------------

### Example /doveadm/v1 response

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/doveadm.md

Example JSON response from the /doveadm/v1 endpoint, showing the command list and their parameters.

```json
[
  {
    "command": "reload",
    "parameters": []
  },
  {
    "command": "statsDump",
    "parameters": [
      {"name": "socketPath", "type": "string"},
      {"name": "reset", "type": "boolean"},
      {"name": "fields", "type": "string"}
    ]
  },
  {
    "command": "fsDelete",
    "parameters": [
      {"name": "recursive", "type": "boolean"},
      {"name": "maxParallel", "type": "integer"},
      {"name": "filterName", "type": "string"},
      {"name": "path", "type": "array"}
    ]
  }
]
```

--------------------------------

### Example Configuration for push-notification-lua

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/push_notification_lua.md

Configuration example showing how to enable the required plugins (mail_lua, notify, push_notification, push_notification_lua) and define a push_notification lua block with lua_file and lua_settings. The lua_settings passes an extra_param from userdb.

```doveconf
mail_plugins {
  mail_lua = yes
  notify = yes
  push_notification = yes
  push_notification_lua = yes
}

push_notification lua {
  lua_file = /path/to/lua/script
  lua_settings {
    extra_param = %{userdb:extra_param}
  }
}
```

--------------------------------

### Start imap in PREAUTH mode

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/debugging.md

These commands start the imap executable in PREAUTH mode, bypassing login and authorization. Use the appropriate path for your installation or source tree. This also works for pop3 and managesieve.

```sh
/usr/libexec/dovecot/imap -u <username>
```

```sh
src/imap/imap -u <username>
```

```sh
doveadm exec imap -u <username>
```

--------------------------------

### LISTSCRIPTS command example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Lists the scripts on the server. After a successful upload, the script should be listed.

```text
LISTSCRIPTS
"example"
OK "Listscripts completed."
```

--------------------------------

### Mac OS X /etc/pam.d/dovecot example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/pam.md

Example PAM configuration for Mac OS X using pam_opendirectory.so and pam_nologin.so. Place in /etc/pam.d/dovecot.

```pam
auth        required       pam_opendirectory.so try_first_pass
account     required       pam_nologin.so
account     required       pam_opendirectory.so
password    required       pam_opendirectory.so
```

--------------------------------

### Run Dovecot imap binary with gdb

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/debugging.md

Starts the imap binary under gdb and enables interactive debugging. After a crash, use 'bt full' to get a backtrace.

```text
# gdb --args /usr/local/libexec/dovecot/imap -u user@domain

...

(gdb) r
Starting program: /usr/local/libexec/dovecot/imap
* PREAUTH [CAPABILITY IMAP4rev1 SORT THREAD=REFERENCES MULTIAPPEND UNSELECT
LITERAL+ IDLE CHILDREN LISTEXT LIST-SUBSCRIBED] Logged in as user
```

--------------------------------

### Install required packages

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Install Postfix, SASL, PostgreSQL, and Dovecot packages on Debian.

```sh
apt-get install postfix-pgsql sasl2-bin libsasl2-modules postgresql \
  libpam-pgsql dovecot-pgsql dovecot-imapd dovecot-pop3d
```

--------------------------------

### Running a command: quota get

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/design/doveadm_protocol.md

Command format: flags<tab>username<tab>command name[<tab>parameter...]. Flags can be empty, 'v' (verbose), or 'D' (debug). Example gets quota for user tss; server replies with values and '+'.

```protocol
C: <TAB>tss<TAB>quota<TAB>get
S: user STORAGE 1814    -       0       user    MESSAGE 6       -       0
S: +
```

--------------------------------

### Maildir filename example with flags

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/mailbox_formats/maildir.md

Example of a Maildir filename with timestamp, size, and flags, including IMAP keywords.

```text
1491941793.M41850P8566V0000000000000015I0000000004F3030E_0.mx1.example.com,S=10956:2,STln
```

--------------------------------

### Example configuration for imapsieve plugin

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/imap_sieve.md

Example configuration showing how to set up sieve_script blocks for the imapsieve plugin, with type 'before' and cause 'copy' for both ham and spam mailboxes.

```doveconf
imapsieve_from Spam {
  sieve_script ham {
    type = before
    cause = copy
    path = /etc/dovecot/sieve/ham.sieve
  }
}
mailbox Spam {
  sieve_script spam {
    type = before
    cause = copy
    path = /etc/dovecot/sieve/spam.sieve
  }
}
```

--------------------------------

### Solaris /etc/pam.conf example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/pam.md

Working PAM configuration for Solaris, edited in /etc/pam.conf. Uses service names 'imap' and 'pop3' with various PAM modules. This example uses service_name setting to specify the service.

```pam
imap    auth       requisite   pam_authtok_get.so.1
imap    auth       required    pam_unix_auth.so.1
imap    account    requisite   pam_roles.so.1
imap    account    required    pam_unix_account.so.1
imap    session    required    pam_unix_session.so.1
pop3    auth       requisite   pam_authtok_get.so.1
pop3    auth       required    pam_unix_auth.so.1
pop3    account    requisite   pam_roles.so.1
pop3    account    required    pam_unix_account.so.1
pop3    session    required    pam_unix_session.so.1
```

--------------------------------

### GETSCRIPT command example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Downloads a script by name. The response includes the script content and its length.

```text
GETSCRIPT "example"
{6}
keep;
OK "Getscript completed."
```

--------------------------------

### Run local development server with npm run docs:dev

Source: https://github.com/dovecot/documentation/blob/main/README.md

Starts the VitePress local development server with real-time updates. Must be run from the base of the project. Some features like search will not work in dev mode and require a static build.

```sh
npm run docs:dev
```

--------------------------------

### Test IMAP proxy with openssl

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/imapc_proxy.md

Starts a TLS connection to the proxy using STARTTLS on port 143. Expect SSL information and a final line '. OK Pre-login capabilities listed, post-login capabilities have more.'

```sh
openssl s_client -connect machine.example.org:143 -starttls imap
```

--------------------------------

### Lua API: HTTP Client Example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/lua/lib_lua.md

Example Lua code demonstrating the use of the HTTP client object to make a POST request and handle the response.

```APIDOC
## Example HTTP Client Code

### Description
Example Lua code showing how to use the `dovecot.http.client` object to send a POST request and process the response.

### Code
```lua
local json = require "json"
local http_client = dovecot.http.client {
    timeout = 10000;
    max_attempts = 3;
    debug = true;
}

function auth_password_verify(request, password)
    local auth_request = http_client:request {
        url = "https://endpoint/";
        method = "POST";
    }
    local req = {user=request.user, password=password}
    auth_request:set_payload(json.encode(req))
    local auth_response = auth_request:submit()
    local resp_status = auth_response:status()

    if resp_status == 200
    then
        return dovecot.auth.PASSDB_RESULT_OK, ""
    else
        return dovecot.auth.PASSDB_RESULT_PASSWORD_MISMATCH, ""
    end
end
```
```

--------------------------------

### Request Attributes Configuration Example 1

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/policy.md

Shows how to configure request attributes using key=value pairs with slashes for nested JSON objects. The example includes placeholders for username, password hash, remote IP, and custom attributes.

```text
login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip} attrs/ja3=%{ssl_ja3_hash} attrs/extra=value
```

```json
{
    "login": "john.doe",
    "pwhash": "1234",
    "remote": "127.0.0.1",
    "attrs": {
      "extra":"value",
      "ja3":"md5 hash"
    }
}
```

--------------------------------

### PAM imap file with pam_listfile.so

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/restrict_access.md

Example /etc/pam.d/imap configuration using pam_listfile.so to allow IMAP access only for users listed in /etc/imapusers.

```pam
# allow IMAP access only for users in /etc/imapusers file
auth    required        pam_listfile.so item=user sense=allow file=/etc/imapusers onerr=fail
```

--------------------------------

### EC private key header example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/mail_crypt.md

Example header of an EC private key that may need conversion to pkey format.

```text
-----BEGIN EC PRIVATE KEY-----
```

--------------------------------

### Example output of doveadm stats dump

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/statistics.md

Example output showing the `duration` field for `imap_command_finished` events. The table below explains each column.

```text
metric_name          field      count  sum       min  max     avg      median stddev %95
imap_commands        duration   35     1190122   162  340477  34003    244    31215  188637
```

--------------------------------

### Line Wrapping Example in C

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/coding_style.md

Example of line wrapping and indentation for a for loop with nested if statements. Demonstrates the use of hard tabs for indentation and wrapping to match the indentation of the previous line.

```c
for (i = 0, used = 0; i < *gid_count; i++) {
        if (gid_list[i] >= set->first_valid_gid &&
            (set->last_valid_gid == 0 ||
             gid_list[i] <= set->last_valid_gid)) {
                if (gid_list[i] == 0)
                    *have_root_group = TRUE;
                gid_list[used++] = gid_list[i];
        }
}
```

--------------------------------

### Time variable examples with unix, epoch, date, from_epoch, iso8601

Source: https://github.com/dovecot/documentation/blob/main/docs/core/settings/variables.md

Shows how to use the `time:unix` variable and related filters (`epoch`, `from_epoch`, `date`, `iso8601`) to format timestamps. The examples include converting to milliseconds, formatting in UTC or local timezone, and converting millisecond timestamps from input.

```plaintext
# Current time as a UNIX timestamp with nanosecond precision:
%{time:unix}                                 -> 1749379200.123456789
# Current time in milliseconds:
%{time:unix | epoch('ms')}                   -> 1749379200123
# Format an arbitrary UNIX timestamp variable in UTC:
%{mytimestamp | date('%Y-%m-%d %H:%M:%S')}   -> 2025-06-08 10:40:00
# ...or in the local timezone:
%{mytimestamp | date('%H:%M', 'local')}
# Convert a millisecond timestamp from input and format it:
%{ms_timestamp | from_epoch('ms') | date('%Y-%m-%d')}
# Current time as an ISO 8601 / RFC 3339 string:
%{time:unix | iso8601}                        -> 2025-06-08T10:40:00Z
```

--------------------------------

### Connect to ManageSieve with gnutls-cli --starttls

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Use this command to start a plain text connection to the ManageSieve server, which will present its capabilities. If STARTTLS is listed, you can proceed with the STARTTLS command.

```sh
gnutls-cli --starttls -p <port> <host>
```

--------------------------------

### Build from Git with maintainer mode

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/installation.md

Build Dovecot from a Git checkout. Run ./autogen.sh first, then configure with --enable-maintainer-mode, make, and install.

```sh
./autogen.sh
./configure --enable-maintainer-mode
make
sudo make install
```

--------------------------------

### Preview static documentation locally with npm run docs:preview

Source: https://github.com/dovecot/documentation/blob/main/README.md

Displays the statically generated documentation locally.

```sh
npm run docs:preview
```

--------------------------------

### SETACTIVE and LISTSCRIPTS example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Activates a script and then lists scripts to show the active one. Only one script can be active at a time.

```text
SETACTIVE "example"
OK "Setactive completed."
LISTSCRIPTS
"example" ACTIVE
OK "Listscripts completed.
```

--------------------------------

### LDAP storage driver example configuration

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/sieve.md

Complete example of the ldap storage driver configuration, showing LDAP connection parameters and script attribute settings. The ldap_filter uses variables like %{user} and %{name}.

```doveconf
sieve_script personal {
  driver = ldap
  bin_path = ~/.sieve-bin/

  # Don't use privileged LDAP credentials here as these may likely leak. Only
  # search and read access is required.

  # Space separated list of LDAP URIs to use.
  ldap_uris = ldap://localhost

  # Distinguished Name - the username used to login to the LDAP server.
  # Leave it commented out to bind anonymously.
  ldap_auth_dn = cn=sieve,ou=Programs,dc=example,dc=org

  # Password for LDAP server, if dn is specified.
  ldap_auth_dn_password = secret

  # LDAP base
  ldap_base = dc=mail,dc=example,dc=org

  # Dereference: never, searching, finding, always
  ldap_deref = never

  # Search scope: base, onelevel, subtree
  ldap_scope = subtree

  # Filter for user lookup. Some variables can be used:
  #   %{user}      - username
  #   %{user | username}      - user part in user@domain, same as %{user} if there's no domain
  #   %{user | domain}      - domain part in user@domain, empty if there's no domain
  #   %{name} - name of the Sieve script
  ldap_filter = (&(objectClass=posixAccount)(uid=%{user}))

  # Attribute containing the Sieve script
  ldap_script_attribute = mailSieveRuleSource

  # Attribute used for modification tracking
  ldap_modified_attribute = modifyTimestamp
}
```

--------------------------------

### Clone Dovecot from Git

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/installation.md

Clone the Dovecot core repository from GitHub. After cloning, run ./autogen.sh to generate the configure script.

```sh
git clone https://github.com/dovecot/core.git dovecot
```

--------------------------------

### Example configuration for mail-log plugin

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/mail_log.md

Enables the notify and mail_log plugins globally, and sets mail_log_events, mail_log_fields, and mail_log_cached_only.

```doveconf
# Enable the plugin globally for all services
mail_plugins {
  notify = yes
  mail_log = yes
}

mail_log_events = delete undelete expunge mailbox_delete mailbox_rename
mail_log_fields = uid box msgid size from
mail_log_cached_only = yes
```

--------------------------------

### MySQL table creation for master users

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/master_users.md

Creates the 'users' and 'ownership' tables used in the advanced SQL master user examples.

```sql
CREATE TABLE `users` (
    `uid` int(4) NOT NULL AUTO_INCREMENT,
    `user_name` varchar(80) NOT NULL,
    `domain_name` varchar(80) NOT NULL,
    `password` varchar(60) DEFAULT NULL,
    `last_login` datetime DEFAULT NULL,
    `masteradmin` tinyint(1) NOT NULL DEFAULT '0',
    `owns_domain` tinyint(1) NOT NULL DEFAULT '0',
    UNIQUE KEY `emaillookup` (`domain_name`,`user_name`),
    UNIQUE KEY `uid` (`uid`)
) ENGINE=InnoDB AUTO_INCREMENT=995 DEFAULT CHARSET=utf8

CREATE TABLE `ownership` (
    `login_id` varchar(128) NOT NULL,
    `owned_object` varchar(128) NOT NULL,
    UNIQUE KEY `login_id_full` (`login_id`,`owned_object`),
    KEY `login_id` (`login_id`),
    KEY `owned_object` (`owned_object`),
    KEY `login_id_index` (`login_id`),
    KEY `owned_object_index` (`owned_object`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
```

--------------------------------

### Example metrics configuration and exported OpenMetrics data

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/statistics.md

This example shows a Dovecot configuration defining metrics for auth_success, imap_command, smtp_command, and mail_delivery, followed by the corresponding OpenMetrics data that Dovecot exports. The configuration uses filters and group_by clauses; the exported data demonstrates the metric naming conventions and histogram behavior.

```doveconf
metric auth_success {
  filter = (event=auth_request_finished AND success=yes)
}

metric imap_command {
  filter = event=imap_command_finished
  group_by cmd_name {
  }
  group_by tagged_reply_state {
  }
}

metric smtp_command {
  filter = event=smtp_server_command_finished
  group_by cmd_name {
  }
  group_by status_code {
  }
  group_by duration {
    method exponential {
      min_magnitude = 1
      max_magnitude = 5
    }
  }
}

metric mail_delivery {
  filter = event=mail_delivery_finished
  group_by duration {
    method exponential {
      min_magnitude = 1
      max_magnitude = 5
    }
  }
}
```

```OpenMetrics Data
# HELP process_start_time_seconds Timestamp of service start
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1606393397
# HELP dovecot_build Dovecot build information
# TYPE dovecot_build info
dovecot_build_info{version="2.4.devel",revision="38ecc424a"} 1
# HELP dovecot_auth_success Total number of all events of this kind
# TYPE dovecot_auth_success counter
dovecot_auth_success_total 892
# HELP dovecot_auth_success_duration_seconds Total duration of all events of this kind
# TYPE dovecot_auth_success_duration_seconds counter
dovecot_auth_success_duration_seconds_total 0.085479
# HELP dovecot_imap_command Total number of all events of this kind
# TYPE dovecot_imap_command counter
dovecot_imap_command_total{cmd_name="LIST"} 423
dovecot_imap_command_total{cmd_name="LIST",tagged_reply_state="OK"} 423
dovecot_imap_command_total{cmd_name="STATUS"} 468
dovecot_imap_command_total{cmd_name="STATUS",tagged_reply_state="OK"} 468
dovecot_imap_command_total{cmd_name="SELECT"} 890
dovecot_imap_command_total{cmd_name="SELECT",tagged_reply_state="OK"} 890
dovecot_imap_command_total{cmd_name="APPEND"} 449
dovecot_imap_command_total{cmd_name="APPEND",tagged_reply_state="OK"} 449
dovecot_imap_command_total{cmd_name="LOGOUT"} 892
dovecot_imap_command_total{cmd_name="LOGOUT",tagged_reply_state="OK"} 892
dovecot_imap_command_total{cmd_name="UID FETCH"} 888
dovecot_imap_command_total{cmd_name="UID FETCH",tagged_reply_state="OK"} 888
dovecot_imap_command_total{cmd_name="FETCH"} 2148
dovecot_imap_command_total{cmd_name="FETCH",tagged_reply_state="OK"} 2148
dovecot_imap_command_total{cmd_name="STORE"} 794
dovecot_imap_command_total{cmd_name="STORE",tagged_reply_state="OK"} 794
dovecot_imap_command_total{cmd_name="EXPUNGE"} 888
dovecot_imap_command_total{cmd_name="EXPUNGE",tagged_reply_state="OK"} 888
dovecot_imap_command_count 7840
# HELP dovecot_imap_command_duration_seconds Total duration of all events of this kind
# TYPE dovecot_imap_command_duration_seconds counter
dovecot_imap_command_duration_seconds_total{cmd_name="LIST"} 0.099115
dovecot_imap_command_duration_seconds_total{cmd_name="LIST",tagged_reply_state="OK"} 0.099115
dovecot_imap_command_duration_seconds_total{cmd_name="STATUS"} 0.161195
dovecot_imap_command_duration_seconds_total{cmd_name="STATUS",tagged_reply_state="OK"} 0.161195
dovecot_imap_command_duration_seconds_total{cmd_name="SELECT"} 0.184907
dovecot_imap_command_duration_seconds_total{cmd_name="SELECT",tagged_reply_state="OK"} 0.184907
dovecot_imap_command_duration_seconds_total{cmd_name="APPEND"} 0.273893
```

--------------------------------

### Lua Authentication Script

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/lua.md

Example of a Lua authentication script with initialization and passdb lookup functions.

```APIDOC
## Lua Authentication Script

### Description
Example of a Lua script for passdb authentication, including initialization and lookup functions.

### Functions

#### `script_init(args)`
- **Description**: Called when the script is initialized. Can be used to pass arguments from `lua_settings`.
- **Parameters**:
  - `args` (table) - Contains settings passed from Dovecot.
- **Returns**: `0` on success.

#### `auth_passdb_lookup(req)`
- **Description**: Called during authentication to perform passdb lookup.
- **Parameters**:
  - `req` (table) - Auth request object.
- **Returns**: Result constant and a table with password field.

#### `auth_passdb_get_cache_key()`
- **Description**: Returns the cache key for the passdb.
- **Returns**: String cache key.

### Example
```lua
local password = nil

function script_init(args)
  password = args["password"]
  return 0
end

function auth_passdb_lookup(req)
  return dovecot.auth.PASSDB_RESULT_OK, { ["password"]=password }
end

function auth_passdb_get_cache_key()
  return "%{user | username}\t%{protocol}"
end
```
```

--------------------------------

### Configure with custom CPPFLAGS and LDFLAGS

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/installation.md

Pass custom include and library paths to configure using CPPFLAGS and LDFLAGS environment variables, e.g., for OpenSSL in a non-standard location.

```sh
CPPFLAGS="-I/opt/openssl/include" LDFLAGS="-L/opt/openssl/lib" ./configure
```

--------------------------------

### Run Dovecot executable with libtool for debugging

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/debugging.md

Use libtool to run an executable from the source tree without installing. The example runs gdb on src/imap/imap. An alias for libtool's execute mode is also provided.

```sh
libtool e gdb --args src/imap/imap
```

```bash
alias lgdb='libtool --mode=execute gdb'
```

--------------------------------

### Create tables and views

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Create the transport, users, and virtual tables, and the postfix_mailboxes and postfix_virtual views.

```sql
CREATE TABLE transport (
    domain VARCHAR(128) NOT NULL,
    transport VARCHAR(128) NOT NULL,
    PRIMARY KEY (domain)
);

CREATE TABLE users (
    userid VARCHAR(128) NOT NULL,
    password VARCHAR(128),
    realname VARCHAR(128),
    uid INTEGER NOT NULL,
    gid INTEGER NOT NULL,
    home VARCHAR(128),
    mail VARCHAR(255),
    PRIMARY KEY (userid)
);

CREATE TABLE virtual (
    address VARCHAR(255) NOT NULL,
    userid VARCHAR(255) NOT NULL,
    PRIMARY KEY (address)
);

create view postfix_mailboxes as
    select userid, home||'/' as mailbox from users
    union all
    select domain as userid, 'dummy' as mailbox from transport;

create view postfix_virtual as
    select userid, userid as address from users
    union all
     select userid, address from virtual;
```

--------------------------------

### Search by mailbox-guid with doveadm search

Source: https://github.com/dovecot/documentation/blob/main/docs/core/man/doveadm-search-query.7.md

Use the mailbox-guid keyword with the mailbox's globally unique identifier to search a specific mailbox. This finds all messages in the mailbox with GUID 44f68b13ce97044b837f000035ca9452.

```sh
doveadm search mailbox-guid 44f68b13ce97044b837f000035ca9452 ALL
```

--------------------------------

### Build static documentation with npm run docs:build

Source: https://github.com/dovecot/documentation/blob/main/README.md

Generates the static documentation into the docs/.vitepress/dist directory.

```sh
npm run docs:build
```

--------------------------------

### IMAP Command Statistics - dovecot.conf metric definitions

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/statistics.md

Example configuration for IMAP command statistics. Defines metrics for IMAP SELECT failures, storage HTTP GETs, and per-command metrics for successful commands using `group_by`.

```doveconf
metric imap_select_no {
  filter = event=imap_command_finished AND cmd_name=SELECT AND \
      tagged_reply_state=NO
}

metric imap_select_no_notfound {
  filter = event=imap_command_finished AND cmd_name=SELECT AND \
      tagged_reply="NO*Mailbox doesn't exist:*"
}

metric storage_http_gets {
  filter = event=http_request_finished AND category=storage AND \
      method=get
}

# generate per-command metrics on successful commands
metric imap_command {
  filter = event=imap_command_finished AND tagged_reply_state=OK
  group_by cmd_name {
  }
}
```

--------------------------------

### Passwd-file as passdb

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/passwd_file.md

Example passwd-file content when used only as a passdb, with plaintext passwords.

```text
user:{plain}password
user2:{plain}password2
```

--------------------------------

### Starting configuration: ACLs in dovecot.conf and ACL files

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/upgrade/2.3-to-2.4.md

Initial setup with namespace inbox and ACL plugin using vfile backend, plus ACL files for INBOX, INBOX/foo/.DEFAULT, and INBOX/foo/bar.

```doveconf
namespace inbox {
  prefix = INBOX/
  separator = /
}

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

```text
owner lrwstipekxa
anyone lr
user=kim l
```

```text
user=timo lr
user=kim lrw
```

```text
user=kim lrw
```

--------------------------------

### Enable and configure extlists in dovecot.conf

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/extensions/extlists.md

Configuration example for enabling the extlists extension and setting up external lists with dict proxies. Includes a global max lookup size and a per-list override. The list 'tag:example.com,2025-02-26:BadFileExts' limits lookups to 10 bytes.

```doveconf
# Use extlists
sieve_extensions {
  extlists = yes
}

# No value looked up from a list may exceed 512 bytes, or it will forcibly not
# match
sieve_extlists_list_max_lookup_size = 512

# The default addressbook stored in a proxied dict
sieve_extlists_list :addrbook:default {
  dict proxy {
    name = addressbook
  }
}

sieve_extlists_list tag:example.com,2025-02-26:BadFileExts {
  dict proxy {
    name = bad_file_extensions
  }

  # Limit lookups to 10 bytes
  max_lookup_size = 10B
}

```

--------------------------------

### Segmentation fault output from dovecot -F

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/running.md

Example output shown when Dovecot crashes while running with 'dovecot -F'. This indicates a bug in Dovecot and should be reported along with the configuration file.

```bash
sh: segmentation fault (core dumped) dovecot -F
```

--------------------------------

### Sample Dovecot init.d script

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/startup_scripts.md

Place this script in /etc/init.d/dovecot and change the DAEMON path if needed. It supports start, stop, reload, restart, and force-reload actions, and uses the master.pid file to determine if Dovecot is running. The script is public domain and should work in all operating systems.

```bash
### BEGIN INIT INFO
# Provides:          dovecot
# Required-Start:    $local_fs $remote_fs $network $syslog $time
# Required-Stop:     $local_fs $remote_fs $network $syslog
# Should-Start:      postgresql mysql slapd winbind
# Should-Stop:       postgresql mysql slapd winbind
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Dovecot init script
# Description:       Init script for dovecot services
### END INIT INFO

# Example /etc/init.d/dovecot script. Change DAEMON if necessary.
# License is public domain.

DAEMON=/usr/local/sbin/dovecot

# Uncomment to allow Dovecot daemons to produce core dumps.
#ulimit -c unlimited

test -x $DAEMON || exit 1
set -e

base_dir=`$DAEMON config -h base_dir`
pidfile=$base_dir/master.pid

if test -f $pidfile; then
  running=yes
else
  running=no
fi

case "$1" in
start)
  echo -n "Starting Dovecot"
  $DAEMON
  echo "."
  ;;
stop)
  if test $running = yes; then
    echo "Stopping Dovecot"
    kill `cat $pidfile`
    echo "."
  else
    echo "Dovecot is already stopped."
  fi
  ;;
reload)
  if test $running = yes; then
    echo -n "Reloading Dovecot configuration"
    kill -HUP `cat $pidfile`
    echo "."
  else
    echo "Dovecot isn't running."
  fi
  ;;
restart|force-reload)
  echo -n "Restarting Dovecot"
  if test $running = yes; then
    kill `cat $pidfile`
    sleep 1
  fi
  $DAEMON
  echo "."
  ;;
*)
  echo "Usage: /etc/init.d/dovecot {start|stop|reload|restart|force-reload}" >&2
  exit 1
  ;;
esac

exit 0
```

--------------------------------

### Configuration: SQL master passdb example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/master_users.md

Shows configuring a master passdb using an SQL query. The master user is selected from the users table where master_user is true. Also includes base SQL driver and userdb. Replace the query with a valid query and configure the SQL driver.

```doveconf
sql_driver = mysql
mysql localhost {
}

auth_master_user_separator = *

passdb db1 {
  driver = sql
  query = SELECT password FROM users WHERE userid = '%{user}' and master_user = true
  master = yes
  result_success = continue
}

passdb db2 {
  driver = sql
  query = # ...
}

userdb sql {
  query = # ...
}

```

--------------------------------

### Example Virtual User Home Directory Structure

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postfix.md

Shows the expected files and directories in a virtual user's home directory under /var/vmail/<domain>/<user>/.

```text
-rw------- 1 vmail vmail 1489 2010-03-03 19:30 .dovecot.sieve
-rw------- 1 vmail vmail 2897 2010-03-14 12:22 .dovecot.svbin
drwx--S--- 4 vmail vmail 4096 2010-03-17 20:15 maildir
drwx--S--- 4 vmail vmail 4096 2010-03-14 13:31 public
```

--------------------------------

### Create database and connect

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Create the mails database and connect to it using psql.

```sh
sudo su postgres
createdb mails
psql mails
```

--------------------------------

### POP3 UIDL format using GUIDs

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/virtual.md

Set pop3_uidl_format to %{guid} to avoid accidental POP3 UIDL changes. Using GUIDs (with Maildir the same as base filename) prevents UIDL instability.

```doveconf
pop3_uidl_format = %{guid}
```

--------------------------------

### Create database users and grant permissions

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Create separate users for read and write accesses. Postfix and Dovecot need only read access.

```sql
CREATE USER mailreader PASSWORD 'secret';
grant select on transport, users, virtual, postfix_mailboxes, postfix_virtual to mailreader;

create user mailwriter password 'secret';
grant select, insert, update, delete on transport, users, virtual, postfix_mailboxes, postfix_virtual to mailwriter;
```

--------------------------------

### Build and run unit tests with make check

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/development.md

Build and run unit tests with code coverage, skipping valgrind.

```sh
make check NOVALGRIND=1
```

--------------------------------

### Sieve include scripts example

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/sieve.md

Shows how to include other Sieve scripts using the 'include' extension. Includes a global script 'global-spam' and a personal script 'my-own-spam'.

```sieve
require ["include"];
include :global "global-spam";
include :personal "my-own-spam";
```

--------------------------------

### SQL table for proxy_maybe with SQL

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/proxy/overview.md

Creates the 'users' table used by the proxy_maybe SQL example. It stores user, domain, password, host, and home fields.

```sql
CREATE TABLE users (
    user varchar(255) NOT NULL,
    domain varchar(255) NOT NULL,
    password varchar(100) NOT NULL,
    host varchar(16) NOT NULL,
    home varchar(100) NOT NULL,
    PRIMARY KEY (user)
);
```

--------------------------------

### Default namespace configuration example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/namespaces.md

Example configuration for the default inbox namespace, setting the separator to '.', an empty prefix, and marking it as the inbox.

```doveconf
namespace inbox {
  separator = .
  prefix =
  inbox = yes
}
```

--------------------------------

### Configure PAM for Kerberos

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/mechanisms/kerberos.md

Create the /etc/pam.d/dovecot file to enable the pam_krb5 module for authentication and account management.

```text
auth sufficient pam_krb5.so
account sufficient pam_krb5.so
```

--------------------------------

### Example PAM failure message output

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/pam.md

Example output from a PAM failure message when using pam_opie, showing the one-time password challenge.

```text
1 LOGIN username otp
1 NO otp-md5 324 0x1578 ext, Response:
```

--------------------------------

### Issue STARTTLS command and server response

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

After connecting, issue the STARTTLS command. The server responds with an OK message if TLS negotiation can begin. Then press Ctrl-D to start the TLS negotiation.

```text
STARTTLS
OK "Begin TLS negotiation now."
```

--------------------------------

### Compile Pigeonhole with automatic dovecot-config detection

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/sieve.md

Compile and install Pigeonhole when Dovecot was installed from sources and the configure script finds dovecot-config automatically.

```sh
./configure
make
sudo make install
```

--------------------------------

### Filter using size units (KB, GB, TB) and time units (mins)

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/events/filter.md

A complicated example using size matching with units like 1KB, 1gb, and 1tB, and a time duration with 1mins. Size units are case-insensitive and default to B if unspecified.

```doveconf
(category=debug AND NOT (net_in_bytes<1KB OR net_out_bytes<1KB)) OR \
    (event=abc AND (message_size>1gb and message_size<1tB)) OR \
    (event=def AND (duration<1mins))
```

--------------------------------

### Example LMTP Delivery Log Entry

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/testing.md

This is an example log entry produced by the LMTP delivery logging configuration. It shows the message details and delivery timing.

```log
Oct 06 12:40:13 lmtp(testuser_717@example.com)<iQBSCwulE1ZXMwAA0J78UA>: Info: iQBSCwulE1ZXMwAA0J78UA: msgid=unspecified from=<sender@example.com> size=155980 vsize=157963 session=161ms delivery=134ms: saved mail to INBOX
```

--------------------------------

### Configure mailbox_directory_name with mbox (incomplete)

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/mailbox_formats/mbox.md

Incomplete example showing how to use mailbox_directory_name with mbox. Do not use as-is because it leaves Dovecot unable to place index files, which can cause performance issues or obstruct mbox file creation.

```doveconf
# Incomplete example. Do not use!
mail_driver = mbox
mail_path = ~/mail
mailbox_directory_name = mBoX-MeSsAgEs
```

--------------------------------

### Configure quota and Sieve plugins

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postfix.md

Set up quota and Sieve plugin settings. Defines a 1GB storage quota, a Trash mailbox with 110% storage percentage, and a personal Sieve script path.

```doveconf
quota_storage_size = 1GB
quota user {
}
mailbox Trash {
  quota_storage_percentage = 110
}
sieve_script personal {
  path = ~/.dovecot.sieve
}
```

--------------------------------

### Clone the documentation repository

Source: https://github.com/dovecot/documentation/blob/main/docs/contributing.md

Clone your forked repository to your local machine to begin making changes.

```shell
git clone https://github.com/YOUR_USERNAME/documentation.git
cd documentation
```

--------------------------------

### BEGIN

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/design/dict_protocol.md

Starts a dict transaction with the given ID. After a successful start, transaction operations such as SET, UNSET, ATOMIC_INC, and TIMESTAMP can be used.

```APIDOC
## BEGIN

### Description
Begins a dict transaction with the given ID.

### Command Format
```
C: B<id>TAB<user>
```

### Notes
- Transaction commands don't have replies with the exception of `COMMIT`.
- After a transaction is successfully started, transaction operations i.e. `SET`, `UNSET`, `ATOMIC_INC`, and `TIMESTAMP` can be used.
```

--------------------------------

### Test custom CA installation with openssl s_client

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/ldap.md

Command to verify that a custom CA is correctly installed for LDAP over TLS. Expect 'Verify return code: 0 (ok)'.

```sh
$ openssl s_client -connect yourldap.example.org:636 \
      -CApath /etc/openldap/certs -showcerts
```

--------------------------------

### Create Keytab with kadmin

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/mechanisms/gssapi.md

Generates a keytab file containing the service principals. The resulting keytab should be placed in /etc/dovecot with mode 0440 and ownership root:dovecot.

```sh
kadmin -q 'ktadd -k /root/keytab imap/fully.qualified.host@REALM'
kadmin -q 'ktadd -k /root/keytab IMAP/fully.qualified.host@REALM'

```
Tokens:
Raw