Aegis documentation

#Dovecot

The Dovecot cube owns IMAP, LMTP delivery and SMTP authentication. It renders dovecot.conf and sql.conf.ext (mode 0600) under dovecot.config_dir (/aegis/config/dovecot), and creates the runtime tree under dovecot.base_dir (/aegis/run/dovecot) that holds the master pid, the SASL socket Postfix authenticates against and the LMTP socket Postfix delivers to.

It keeps no data of its own: users, passwords, quotas and maildirs are read from the mail database and the tree owned by the mail cube. The SQL include is chosen from apps.postfix.database, so both daemons always talk to the same backend. The daemon runs as the keeper service aegis-dovecot with dovecot -F -c <dovecot.conf>; configure creates the dovecot and dovenull accounts before the first start.

#Common commands

Cube operations share one wrapper: ✔ dovecot: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "dovecot", "result": "<detail>"} with global --json.

expose is the only verb that prints a block instead of that line.

VerbEffect
configurecreate the service accounts, render both files, validate, start when stopped
validaterun doveconf -c <dovecot.conf> -n
reloadrun dovecot -c <dovecot.conf> reload
statusread base_dir/master.pid: running (pid N) or stopped
startstart the master in the foreground under the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint the config, socket and base paths, then publish the Dovecot tools
helpprint the command list with examples

#configure

bash
aegis cubes dovecot configureaegis --json cubes dovecot configure

Creates the dovecot and dovenull group and user when missing, renders the SQL include with mode 0600 and the main file with 0644, validates, and starts the master if it is not running. The TLS certificate comes from the ssl module for the mail hostname.

text
✔ dovecot: configuration is valid{"ok": true, "cube": "dovecot", "result": "configuration is valid"}

#validate

bash
aegis cubes dovecot validateaegis --json cubes dovecot validate

Runs doveconf -n, which parses the file and prints the non-default settings. The last ten lines of its output are shown when parsing fails.

text
✔ dovecot: configuration is valid{"ok": true, "cube": "dovecot", "result": "configuration is valid"}

#reload

bash
aegis cubes dovecot reloadaegis --json cubes dovecot reload

Asks the running master to re-read the configuration; existing IMAP sessions survive.

text
✔ dovecot: configuration reloaded{"ok": true, "cube": "dovecot", "result": "configuration reloaded"}

#status

bash
aegis cubes dovecot statusaegis --json cubes dovecot status
text
✔ dovecot: running (pid 1320){"ok": true, "cube": "dovecot", "result": "running (pid 1320)"}

#start

bash
aegis cubes dovecot startaegis --json cubes dovecot start

Without Dovecot running, Postfix cannot authenticate submitters and cannot deliver to local mailboxes.

text
✔ dovecot: started (pid 1320){"ok": true, "cube": "dovecot", "result": "started (pid 1320)"}

#stop

bash
aegis cubes dovecot stopaegis --json cubes dovecot stop
text
✔ dovecot: stopped (pid 1320){"ok": true, "cube": "dovecot", "result": "stopped (pid 1320)"}

#restart

bash
aegis cubes dovecot restartaegis --json cubes dovecot restart
text
✔ dovecot: stopped (pid 1320), started (pid 1347){"ok": true, "cube": "dovecot", "result": "stopped (pid 1320), started (pid 1347)"}

#expose

bash
aegis cubes dovecot exposeaegis --json cubes dovecot expose
text
cube           dovecotinstalled      /aegis/apps/mail/dovecot/2.4configuration  /aegis/config/dovecotstate          running (pid 1320)pid            1320log            /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/lmtppublished      /aegis/bin/dovecot, /aegis/bin/doveadm, /aegis/bin/doveconf
text
{"ok": true, "cube": "dovecot", "installed": "/aegis/apps/mail/dovecot/2.4", "configuration": "/aegis/config/dovecot", "state": "running (pid 1320)", "pid": "1320", "log": "/aegis/logs/dovecot/dovecot.log", "config": "/aegis/config/dovecot/dovecot.conf", "sql": "/aegis/config/dovecot/sql.conf.ext", "base": "/aegis/run/dovecot", "sasl socket": "/aegis/run/dovecot/auth-client", "lmtp socket": "/aegis/run/dovecot/lmtp", "published": "/aegis/bin/dovecot, /aegis/bin/doveadm, /aegis/bin/doveconf"}

#help

bash
aegis cubes dovecot helpaegis cubes help dovecot
text
ℹ Dovecot — IMAP, LMTP delivery and SMTP authenticationCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Write the configuration and validate it  start      Start the master process  stop       Stop the master process  status     Show whether the master process runs  restart    Restart the master process  expose     Show where it is installed and how it runs  help       Show every command with examples

The examples block follows.