Aegis documentation

#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.

text
Postfix smtpd ──AUTH──▶ auth-client socket ──▶ passdb sql ──▶ aegis_mailboxesPostfix lmtp  ────────▶ lmtp socket ────────▶ userdb sql ──▶ maildir + quotaIMAP client   ────────▶ :143/:993  ─────────▶ same SQL, same files

In the panel: Mail → the Dovecot settings page. Every write there is a task.

#Configuration

toml
[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
KeyDefaultMeaning
dovecot.config_dir/aegis/config/dovecotdovecot.conf and sql.conf.ext
dovecot.base_dir/aegis/run/dovecotsockets and master.pid; listener names are relative to it
dovecot.log_dir/aegis/logs/dovecotdovecot.log, dovecot-info.log
dovecot.sasl_socket…/auth-clientSASL socket Postfix authenticates against
dovecot.lmtp_socket…/lmtpLMTP socket Postfix delivers to
mail.hostnameemptycertificate name for IMAPS
mail.vmail_uid, mail.vmail_gid5000uid/gid written into userdb
mail.vmail_base/aegis/data/mailwhere the maildirs live
apps.dovecot.databasepgsqlbackend the SQL include is rendered for

The database credentials are read from the postfix cube ([mail.database]), so they are configured once.

#Files

text
<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 disconnects

dovecot.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

  • creates the dovecot and dovenull operating-system accounts — the master
  • runs as root and drops to them, so they must exist even though the mailbox files belong to the numeric mail uid;

  • renders sql.conf.ext (mode 0600, it contains the database password) and
  • dovecot.conf (mode 0644);

  • validates with doveconf -n;
  • starts the master through the keeper.
  • #Commands

    bash
    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 expose

    Every 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

    ini
    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
    PieceMeaning
    passdbwhat Dovecot compares the password with; active makes disabling a mailbox an authentication failure
    userdb.querywhere the mailbox lives and which uid/gid own it; maildir becomes home, and mail_path = ~ makes that directory the maildir itself
    iterate_querythe list of users for doveadm and quota reports
    passdb_default_password_schemeapplies 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

    SocketOwner / modeUsed by
    auth-clientpostfix, 0660smtpd_sasl_path in Postfix
    lmtppostfix, 0600virtual_transport = lmtp:unix:…
    auth-userdbdovecot, 0666internal auth lookups
    auth-masterroot, 0600doveadm 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.
  • Dovecot's LMTP service asks 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

    ini
    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

    bash
    # 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 -dates

    A minimal IMAP session, without a client:

    bash
    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/null

    And LMTP directly:

    bash
    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.32.4
    —dovecot_config_version / dovecot_storage_version must be the first settings
    disable_plaintext_authauth_allow_cleartext
    ssl_certssl_server_cert_file
    unix_listener /absolute/pathpath relative to base_dir, otherwise duplicate listener
    mail_location = maildir:~/Maildirmail_driver = maildir + mail_path = ~
    MD5-CRYPT acceptedrefused 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.logCauseFix
    The first setting must be dovecot_config_version2.4 requires the version firstkeep the two lines at the top
    duplicate listener: …absolute unix_listener path with base_dir setuse the socket name only
    Weak password scheme 'MD5-CRYPT' used and refusedold hash in the databaseaegis cubes mail mailboxes password <address> --password …
    sql: Invalid password in passdbscheme mismatch or wrong DB rowdoveadm auth test, then check aegis_mailboxes
    auth failed while the row looks rightmailbox active = falseaegis cubes mail mailboxes enable <address>
    Permission denied on LMTPthe socket is not owned by postfixconfigure, then restart
    maildir: …: No such file or directorythe maildir was never createdaegis cubes mail mailboxes add created it; check maildir column
    IMAP login works, SMTP AUTH does notPostfix built without SASL, or the wrong socket pathsee postfix.md
    bash
    tail -f /aegis/logs/dovecot/dovecot.logtail -f /aegis/logs/dovecot/dovecot-info.log     # loginsaegis cubes dovecot validate

    #Process

    toml
    [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

    bash
    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

  • The dovecot and dovenull accounts are created by the cube; a missing one
  • makes the master exit immediately with a log line naming it.

  • Maildirs are created by the mail cube, not here: Dovecot only reads the
  • maildir column and uses it as home.

  • A stop with an SASL request still in flight has been seen to trip an assertion
  • in auths_free (Dovecot 2.4.5). It does not survive a restart; if it becomes reproducible, report it upstream.