#Cube: dovecot
Dovecot 2.4 does three jobs in this stack: it authenticates SMTP clients for Postfix (SASL socket), it receives mail over LMTP and writes it into the maildir, and it serves IMAP/IMAPS to the users. All three use the same mail database, so a mailbox has one password and one location.
Postfix smtpd ──AUTH──▶ auth-client socket ──▶ passdb sql ──▶ aegis_mailboxesPostfix lmtp ────────▶ lmtp socket ────────▶ userdb sql ──▶ maildir + quotaIMAP client ────────▶ :143/:993 ─────────▶ same SQL, same filesIn the panel: Mail → the Dovecot settings page. Every write there is a task.
#Configuration
[dovecot]config_dir = "/aegis/config/dovecot"base_dir = "/aegis/run/dovecot"log_dir = "/aegis/logs/dovecot"sasl_socket = "/aegis/run/dovecot/auth-client"lmtp_socket = "/aegis/run/dovecot/lmtp"[mail]hostname = "" # certificate name; empty uses setup.hostnamevmail_uid = 5000vmail_gid = 5000vmail_base = "/aegis/data/mail"[apps.dovecot]database = "pgsql" # pgsql | mysql | sqlite| Key | Default | Meaning |
|---|---|---|
dovecot.config_dir | /aegis/config/dovecot | dovecot.conf and sql.conf.ext |
dovecot.base_dir | /aegis/run/dovecot | sockets and master.pid; listener names are relative to it |
dovecot.log_dir | /aegis/logs/dovecot | dovecot.log, dovecot-info.log |
dovecot.sasl_socket | …/auth-client | SASL socket Postfix authenticates against |
dovecot.lmtp_socket | …/lmtp | LMTP socket Postfix delivers to |
mail.hostname | empty | certificate name for IMAPS |
mail.vmail_uid, mail.vmail_gid | 5000 | uid/gid written into userdb |
mail.vmail_base | /aegis/data/mail | where the maildirs live |
apps.dovecot.database | pgsql | backend the SQL include is rendered for |
The database credentials are read from the postfix cube ([mail.database]), so they are configured once.
#Files
<dovecot.config_dir>/├── dovecot.conf main configuration (0644)└── sql.conf.ext passdb/userdb queries, holds the password (0600)<dovecot.base_dir>/├── master.pid pid file the keeper watches├── auth-client SASL socket for Postfix (owner: postfix)├── lmtp LMTP socket for Postfix (owner: postfix)├── auth-userdb, auth-master, auth-worker, anvil, … internal sockets└── login/ per-connection sockets and state<dovecot.log_dir>/├── dovecot.log errors and startup└── dovecot-info.log logins and disconnectsdovecot.conf is rendered from storage/data/apps/dovecot/templates/dovecot.conf; the SQL include comes from the profile of the configured backend (profiles/pgsql.toml and siblings).
#First run: what configure does
dovecot and dovenull operating-system accounts — the masterruns as root and drops to them, so they must exist even though the mailbox files belong to the numeric mail uid;
sql.conf.ext (mode 0600, it contains the database password) anddovecot.conf (mode 0644);
doveconf -n;#Commands
aegis cubes dovecot configure # accounts, SQL include, dovecot.conf, validateaegis cubes dovecot validate # doveconf -c … -naegis cubes dovecot reload # dovecot reloadaegis cubes dovecot start|stop|restart|statusaegis cubes dovecot exposeEvery configuration change needs a reload or a restart: Dovecot reads dovecot.conf once. The SQL queries themselves are read per lookup, so adding a mailbox needs nothing.
#The SQL include
sql_driver = pgsqlpgsql 127.0.0.1 parameters user = aegis_mail password = "…" dbname = aegis_mail passdb_default_password_scheme = SHA512-CRYPTpassdb sql query = SELECT address AS user password FROM aegis_mailboxes WHERE address = '%{user}' AND activeuserdb sql query = SELECT maildir AS home 5000 AS uid 5000 AS gid FROM aegis_mailboxes WHERE address = '%{user}' AND active iterate_query = SELECT address AS user FROM aegis_mailboxes WHERE active| Piece | Meaning |
|---|---|
passdb | what Dovecot compares the password with; active makes disabling a mailbox an authentication failure |
userdb.query | where the mailbox lives and which uid/gid own it; maildir becomes home, and mail_path = ~ makes that directory the maildir itself |
iterate_query | the list of users for doveadm and quota reports |
passdb_default_password_scheme | applies when a stored hash has no {SCHEME} prefix; the schema stores plain $6$…, i.e. SHA512-CRYPT |
uid and gid are constants from mail.vmail_uid / mail.vmail_gid, not columns: every mailbox belongs to the same unprivileged account.
The credentials come from the mail database the postfix cube created — the driver, user, password and database name are read through it, so they are never configured twice.
#Sockets and permissions
| Socket | Owner / mode | Used by |
|---|---|---|
auth-client | postfix, 0660 | smtpd_sasl_path in Postfix |
lmtp | postfix, 0600 | virtual_transport = lmtp:unix:… |
auth-userdb | dovecot, 0666 | internal auth lookups |
auth-master | root, 0600 | doveadm as root |
The listener paths in dovecot.conf are relative to base_dir (2.4 rejects absolute paths that repeat it). The absolute path only appears in Postfix's configuration.
#Delivery path
smtpd accepts the message and runs the SQL maps.cleanup rewrites aliases and adds the BCC copies.qmgr picks virtual_transport → lmtp:unix:<base_dir>/lmtp.userdb for the mailbox, writes the file into<maildir>/new/ as uid 5000, and enforces the quota on the way.
Quota is Dovecot's job, not Postfix's: the quota.cf map exists for reference, but the limit is applied when the message is appended. A mailbox over quota answers 552 5.2.2 Mailbox is full, which the sender sees as a normal bounce.
#IMAP and TLS
protocols = imap lmtpssl = requiredssl_server_cert_file = /aegis/config/ssl/ssl_server_key_file = /aegis/config/ssl/ssl_min_protocol = TLSv1.2service imap-login inet_listener imap port = 143 inet_listener imaps port = 993 ssl = yes The certificate is resolved for mail.hostname (or the server hostname) through the ssl module, so a Let's Encrypt certificate is used as soon as one exists and a local self-signed one otherwise. ssl = required means plaintext IMAP is only offered on 143 for the STARTTLS upgrade, never for credentials.
#Testing it
# configuration as Dovecot parsed itdoveconf -c /aegis/config/dovecot/dovecot.conf -n | head -30# does the password in the database work?doveadm auth test postmaster@example.com 'secret123'# which maildir does Dovecot think the user has?doveadm user postmaster@example.com# what is in the mailbox, and how much quota is left?doveadm mailbox list -u postmaster@example.comdoveadm quota get -u postmaster@example.com# is IMAPS serving the right certificate?openssl s_client -connect 127.0.0.1:993 -servername mail.example.com </dev/null | openssl x509 -noout -subject -datesA minimal IMAP session, without a client:
printf 'a1 LOGIN postmaster@example.com secret123\r\na2 LIST "" "*"\r\na3 LOGOUT\r\n' | openssl s_client -quiet -connect 127.0.0.1:993 2>/dev/nullAnd LMTP directly:
printf 'LHLO test\r\nMAIL FROM:<a@example.org>\r\nRCPT TO:<postmaster@example.com>\r\nDATA\r\n' | socat - UNIX-CONNECT:/aegis/run/dovecot/lmtp#Dovecot 2.4 differences that matter
2.4 renamed and re-scoped a lot; the templates already account for it, and the old names fail loudly rather than silently.
| 2.3 | 2.4 |
|---|---|
| — | dovecot_config_version / dovecot_storage_version must be the first settings |
disable_plaintext_auth | auth_allow_cleartext |
ssl_cert | ssl_server_cert_file |
unix_listener /absolute/path | path relative to base_dir, otherwise duplicate listener |
mail_location = maildir:~/Maildir | mail_driver = maildir + mail_path = ~ |
| MD5-CRYPT accepted | refused as a weak scheme |
Because of the last row the mail schema hashes passwords with SHA512-CRYPT (openssl passwd -6), which 2.4 accepts without enabling weak schemes.
#Troubleshooting
Message in dovecot.log | Cause | Fix |
|---|---|---|
The first setting must be dovecot_config_version | 2.4 requires the version first | keep the two lines at the top |
duplicate listener: … | absolute unix_listener path with base_dir set | use the socket name only |
Weak password scheme 'MD5-CRYPT' used and refused | old hash in the database | aegis cubes mail mailboxes password <address> --password … |
sql: Invalid password in passdb | scheme mismatch or wrong DB row | doveadm auth test, then check aegis_mailboxes |
auth failed while the row looks right | mailbox active = false | aegis cubes mail mailboxes enable <address> |
Permission denied on LMTP | the socket is not owned by postfix | configure, then restart |
maildir: …: No such file or directory | the maildir was never created | aegis cubes mail mailboxes add created it; check maildir column |
| IMAP login works, SMTP AUTH does not | Postfix built without SASL, or the wrong socket path | see postfix.md |
tail -f /aegis/logs/dovecot/dovecot.logtail -f /aegis/logs/dovecot/dovecot-info.log # loginsaegis cubes dovecot validate#Process
[services.dovecot]command = <prefix>/sbin/dovecot -F -c <config_dir>/dovecot.confpid_file = <base_dir>/master.pid-F keeps the master in the foreground so the keeper owns it; Dovecot still writes master.pid in its base directory. The master runs as root and drops to dovecot / dovenull for its own processes, while message files are written as the mail uid.
#expose
aegis cubes dovecot exposecube dovecotinstalled /aegis/apps/mail/dovecot/2.4configuration /aegis/config/dovecotstate running pid 768650log /aegis/logs/dovecot/dovecot.logconfig /aegis/config/dovecot/dovecot.confsql /aegis/config/dovecot/sql.conf.extbase /aegis/run/dovecotsasl socket /aegis/run/dovecot/auth-clientlmtp socket /aegis/run/dovecot/lmtp#Sieve and vacation
Pigeonhole is built (mail/pigeonhole) and Dovecot 2.4 loads it when it is present, but this cube does not render sieve configuration yet: there is no sieve_before/sieve_after and no per-user script management. The aegis_autoresponders table exists in the mail schema for that feature; until the Sieve side is written, vacation replies are not delivered.
#Notes
dovecot and dovenull accounts are created by the cube; a missing onemakes the master exit immediately with a log line naming it.
mail cube, not here: Dovecot only reads themaildir column and uses it as home.
in auths_free (Dovecot 2.4.5). It does not survive a restart; if it becomes reproducible, report it upstream.