Aegis documentation

#mail

The mail cube is the management surface of the mail database. It owns domains, mailboxes, aliases, forwards, relocated addresses, per-domain TLS policy and the virtual mail tree; it renders no daemon configuration. Rows go into the database the postfix cube bootstrapped (aegis_mail, on PostgreSQL, MariaDB or SQLite depending on apps.postfix.database), and the maildirs go under mail.vmail_base (/aegis/data/mail), one directory per domain and mailbox.

Postfix and Dovecot read those tables on every lookup, so a change is live immediately: there is no reload. configure only ensures the tree exists and registers the server's own domain. The cube is not an installed application, so expose reports installed n/a.

#Common commands

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

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

VerbEffect
configurecreate mail.vmail_base, then register setup.primary_domain when it is missing
validatecheck that the mail tree exists, count domains and mailboxes
reloadalways reports that there is nothing to reload
exposeprint the tree, the numeric mail uid and the counts
helpprint the command list with examples

There is no start, stop, status or restart: the daemons belong to the postfix and dovecot cubes.

#configure

bash
aegis cubes mail configureaegis --json cubes mail configure

Creates the mail tree if needed and adds setup.primary_domain as an active domain when it is not there yet.

text
✔ mail: 2 domains, 7 mailboxes at /aegis/data/mail; domain example.com present{"ok": true, "cube": "mail", "result": "2 domains, 7 mailboxes at /aegis/data/mail; domain example.com present"}

#validate

bash
aegis cubes mail validateaegis --json cubes mail validate

Checks the tree on disk and counts what the database holds; it does not test SMTP or IMAP.

text
✔ mail: 2 domains, 7 mailboxes at /aegis/data/mail{"ok": true, "cube": "mail", "result": "2 domains, 7 mailboxes at /aegis/data/mail"}

#reload

bash
aegis cubes mail reloadaegis --json cubes mail reload

Takes no options. The message says why nothing happens.

text
✔ mail: no daemon; Postfix and Dovecot read the database directly{"ok": true, "cube": "mail", "result": "no daemon; Postfix and Dovecot read the database directly"}

#expose

bash
aegis cubes mail exposeaegis --json cubes mail expose
text
cube           mailinstalled      n/aconfiguration  /aegis/data/mailmail tree      /aegis/data/mailmail uid       5000:5000domains        2mailboxes      7default quota  0
text
{"ok": true, "cube": "mail", "installed": "n/a", "configuration": "/aegis/data/mail", "mail tree": "/aegis/data/mail", "mail uid": "5000:5000", "domains": "2", "mailboxes": "7", "default quota": "0"}

#help

bash
aegis cubes mail helpaegis cubes help mail
text
ℹ Mail — Virtual domains, mailboxes, aliases and storageCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Create the mail tree and report its state  expose     Show where it is installed and how it runs  domains    Manage mail domains  mailboxes  Manage mailboxes

The list continues with aliases, forwards, relocated, tls, storage, demo and help, followed by the examples.

#Domains

A domain row is what makes Postfix accept mail for a name. Adding one also creates its directory and asks the opendkim cube for a DKIM key and TXT record; when openDKIM is not installed, the domain is still created and the result says DKIM was skipped.

text
aegis cubes mail domains  Manage mail domainsCommands  list       List domains  add        Create a domain  show       Show one domain  enable     Enable local delivery  disable    Disable local delivery  set        Change quota or mailbox limit  remove     Delete a domain  catch-all  Set or clear the catch-allRun 'aegis cubes mail domains <command> --help' for the options of one command.

#domains list

bash
aegis cubes mail domains listaegis --json cubes mail domains list

One entry per domain: mailbox count, alias count, catch-all address when set, and [disabled] when delivery is off. No options.

text
✔ mail: example.com (3 boxes, 2 aliases, catch-all postmaster@example.com); example.org (1 boxes, 0 aliases) [disabled]{"ok": true, "cube": "mail", "result": "example.com (3 boxes, 2 aliases, catch-all postmaster@example.com); example.org (1 boxes, 0 aliases) [disabled]"}

#domains add

bash
aegis cubes mail domains add example.comaegis cubes mail domains add example.net --quota 5368709120 --max-mailboxes 50
OptionMeaning
namethe domain to create
--quotadefault mailbox quota in bytes; 0 falls back to mail.quota.default_bytes
--max-mailboxesmaximum mailboxes; 0 means unlimited

Creates the row, the domain directory owned by mail.vmail_uid, then generates and publishes the DKIM selector record.

text
✔ mail: domain example.com created; mail._domainkey.example.com published{"ok": true, "cube": "mail", "result": "domain example.net created; DKIM skipped (opendkim is not installed at /aegis/apps/mail/opendkim/2.11)"}

#domains show

bash
aegis cubes mail domains show example.comaegis --json cubes mail domains show example.com
ArgumentMeaning
namethe domain to print

Prints the row's limits, counters and selector in one line.

text
✔ mail: domain example.com, active=1, mailboxes=3, aliases=2, quota=0, max_quota=10737418240, max_mailboxes=50, selector=mail, catch_all=postmaster@example.com{"ok": true, "cube": "mail", "result": "domain example.com, active=1, mailboxes=3, aliases=2, quota=0, max_quota=10737418240, max_mailboxes=50, selector=mail, catch_all=postmaster@example.com"}

#domains enable / domains disable

bash
aegis cubes mail domains disable example.orgaegis cubes mail domains enable example.org
ArgumentMeaning
namethe domain whose delivery state changes

A disabled domain stops being a local destination; the rows and the maildirs stay.

text
✔ mail: domain example.org disabled{"ok": true, "cube": "mail", "result": "domain example.org enabled"}

#domains set

bash
aegis cubes mail domains set example.com --quota 5368709120aegis cubes mail domains set example.com --max-mailboxes 100
OptionMeaning
namethe domain to change
--quotanew default mailbox quota in bytes
--max-mailboxesnew mailbox limit

At least one of the two flags is required; with neither, the command fails with nothing to change: pass --quota or --max-mailboxes. Existing mailboxes keep their own quota.

text
✔ mail: domain example.com: default_quota_bytes = 5368709120{"ok": true, "cube": "mail", "result": "domain example.com: default_quota_bytes = 5368709120"}

#domains remove

Destructive. Deletes the domain row and, in the same run, every mailbox, alias, forward, relocated address and TLS policy that belongs to it. The directory under mail.vmail_base is not deleted: the messages stay on disk until removed by hand.

bash
aegis cubes mail domains remove example.netaegis --json cubes mail domains remove example.net
ArgumentMeaning
namethe domain to delete
text
✔ mail: domain example.net removed{"ok": true, "cube": "mail", "result": "domain example.net removed"}

#domains catch-all

bash
aegis cubes mail domains catch-all example.com postmaster@example.comaegis cubes mail domains catch-all example.com
ArgumentMeaning
namethe domain
targetaddress that receives mail for unknown local parts; omit to clear
text
✔ mail: catch-all for example.com -> postmaster@example.com{"ok": true, "cube": "mail", "result": "catch-all cleared for example.com"}

#Mailboxes

A mailbox owns a row, a SHA512-CRYPT password and a maildir with cur, new and tmp. www-style maildir names are not special here: the local part is the directory name.

text
aegis cubes mail mailboxes  Manage mailboxesCommands  list      List mailboxes  show      Show one mailbox  add       Create one or more mailboxes  remove    Delete a mailbox  password  Set a mailbox password  quota     Set a mailbox quota  enable    Enable a mailbox  disable   Disable a mailboxRun 'aegis cubes mail mailboxes <command> --help' for the options of one command.

#mailboxes list

bash
aegis cubes mail mailboxes listaegis cubes mail mailboxes list --domain example.com
OptionMeaning
--domainrestrict the list to one domain
text
✔ mail: postmaster@example.com (5368709120 bytes); sales@example.com (1073741824 bytes, disabled){"ok": true, "cube": "mail", "result": "postmaster@example.com (5368709120 bytes); sales@example.com (1073741824 bytes, disabled)"}

#mailboxes show

bash
aegis cubes mail mailboxes show postmaster@example.comaegis --json cubes mail mailboxes show sales@example.com
ArgumentMeaning
addressthe mailbox to print

The size on disk is measured with du on that mailbox only.

text
✔ mail: postmaster@example.com: maildir=/aegis/data/mail/example.com/postmaster, used=48234496 of 5368709120, active=1, scheme=SHA512-CRYPT{"ok": true, "cube": "mail", "result": "sales@example.com: maildir=/aegis/data/mail/example.com/sales, used=7340032 of 1073741824, active=0, scheme=SHA512-CRYPT"}

#mailboxes add

bash
aegis cubes mail mailboxes add postmaster@example.com --password 'secret123'aegis cubes mail mailboxes add a@example.com b@example.com --password 'secret123' --quota 5368709120
OptionMeaning
addressone or more addresses; one mailbox is created per address
--passwordrequired; at least 8 characters, stored as SHA512-CRYPT
--quotaquota in bytes; 0 uses the domain default, then mail.quota.default_bytes
--namedisplay name stored with the mailbox

The domain must exist, and a domain max_mailboxes limit is enforced before anything is created. Failures per address are collected instead of aborting the batch.

text
✔ mail: 2 created{"ok": true, "cube": "mail", "result": "1 created; failed: bad@@example.com: invalid address: bad@@example.com"}

#mailboxes remove

Destructive. Deletes the mailbox row. The maildir is kept on disk, so the messages can still be recovered. With --purge the maildir is deleted too.

bash
aegis cubes mail mailboxes remove old@example.comaegis cubes mail mailboxes remove old@example.com --purge --yes
OptionMeaning
addressthe mailbox to delete
--purgealso delete the maildir
--yesrequired together with --purge; without it the command refuses to run

The maildir is checked to be inside mail.vmail_base before anything is deleted.

text
✔ mail: mailbox old@example.com removed (maildir left in place){"ok": true, "cube": "mail", "result": "mailbox old@example.com removed with its maildir"}

#mailboxes password

bash
aegis cubes mail mailboxes password postmaster@example.com --password 'new-secret'aegis --json cubes mail mailboxes password sales@example.com --password 'new-secret'
OptionMeaning
addressthe mailbox
--passwordrequired; at least 8 characters
text
✔ mail: password updated for postmaster@example.com{"ok": true, "cube": "mail", "result": "password updated for sales@example.com"}

#mailboxes quota

bash
aegis cubes mail mailboxes quota postmaster@example.com 5368709120aegis --json cubes mail mailboxes quota sales@example.com 1073741824
ArgumentMeaning
addressthe mailbox
bytesnew quota in bytes; 0 means unlimited
text
✔ mail: quota for postmaster@example.com set to 5368709120 bytes{"ok": true, "cube": "mail", "result": "quota for sales@example.com set to 1073741824 bytes"}

#mailboxes enable / mailboxes disable

bash
aegis cubes mail mailboxes disable sales@example.comaegis cubes mail mailboxes enable sales@example.com
ArgumentMeaning
addressthe mailbox whose login and delivery state changes
text
✔ mail: mailbox sales@example.com disabled{"ok": true, "cube": "mail", "result": "mailbox sales@example.com enabled"}

#Aliases

An alias is a plain redirect from one address to another. Both end up in the Postfix alias map, so no reload is needed. This group requires its action: bare aegis cubes mail aliases is an argparse error, unlike domains.

#aliases list

bash
aegis cubes mail aliases listaegis --json cubes mail aliases list
text
✔ mail: info@example.com -> postmaster@example.com{"ok": true, "cube": "mail", "result": "info@example.com -> postmaster@example.com"}

#aliases add

bash
aegis cubes mail aliases add info@example.com postmaster@example.comaegis cubes mail aliases add billing@example.com finance@example.com --owner admin
OptionMeaning
sourcethe address being redirected
destinationa full address, or a local name that becomes <name>@localhost
--owneroptional owner login stored with the alias

An existing source is refused with alias already exists.

text
✔ mail: alias info@example.com -> postmaster@example.com{"ok": true, "cube": "mail", "result": "alias billing@example.com -> finance@example.com"}

#aliases remove

Destructive. Deletes the alias row; mail to the source starts bouncing as unknown.

bash
aegis cubes mail aliases remove info@example.comaegis --json cubes mail aliases remove billing@example.com
ArgumentMeaning
sourcethe alias address
text
✔ mail: alias info@example.com removed{"ok": true, "cube": "mail", "result": "alias billing@example.com removed"}

#Forwards

A forward sends a copy to another address and, unless --no-copy is given, keeps the local copy. It is a row in the same map as aliases.

#forwards list

bash
aegis cubes mail forwards listaegis --json cubes mail forwards list
text
✔ mail: sales@example.com -> person@gmail.com (keep local){"ok": true, "cube": "mail", "result": "sales@example.com -> person@gmail.com (keep local)"}

#forwards add

bash
aegis cubes mail forwards add sales@example.com person@gmail.comaegis cubes mail forwards add sales@example.com person@gmail.com --no-copy
OptionMeaning
sourcethe local address
destinationthe address that receives the copy
--no-copydo not keep a local copy; the local mailbox no longer receives it

Adding the same pair twice replaces the previous row, so the command is also the way to switch the copy behaviour.

text
✔ mail: forward sales@example.com -> person@gmail.com (keeping a local copy){"ok": true, "cube": "mail", "result": "forward sales@example.com -> person@gmail.com (without a local copy)"}

#forwards remove

Destructive. Removes one forward, or every forward of the source when --destination is omitted.

bash
aegis cubes mail forwards remove sales@example.com --destination person@gmail.comaegis cubes mail forwards remove sales@example.com
OptionMeaning
sourcethe local address
--destinationnarrow the removal to one target
text
✔ mail: forward removed for sales@example.com{"ok": true, "cube": "mail", "result": "forward removed for sales@example.com"}

#Relocated addresses

A relocated address answers SMTP with 551 and points the sender at a new address; it does not forward anything.

#relocated list

bash
aegis cubes mail relocated listaegis --json cubes mail relocated list
text
✔ mail: old@example.com -> new@example.com{"ok": true, "cube": "mail", "result": "old@example.com -> new@example.com"}

#relocated add

bash
aegis cubes mail relocated add old@example.com new@example.comaegis --json cubes mail relocated add old@example.com new@example.com
ArgumentMeaning
sourcethe address that moved
destinationthe address senders are told about

One row per source: adding again replaces the previous destination.

text
✔ mail: relocated old@example.com -> new@example.com{"ok": true, "cube": "mail", "result": "relocated old@example.com -> new@example.com"}

#relocated remove

Destructive. Forgets the move; the old address starts bouncing as unknown unless a mailbox or alias exists for it.

bash
aegis cubes mail relocated remove old@example.comaegis --json cubes mail relocated remove old@example.com
text
✔ mail: relocated old@example.com removed{"ok": true, "cube": "mail", "result": "relocated old@example.com removed"}

#Outbound TLS policy

aegis_tls_policy is read by Postfix through smtp_tls_policy_maps. The policy decides how strictly mail to one domain must be encrypted.

#tls list

bash
aegis cubes mail tls listaegis --json cubes mail tls list
text
✔ mail: example.com: encrypt{"ok": true, "cube": "mail", "result": "example.com: encrypt"}

#tls set

bash
aegis cubes mail tls set example.com encryptaegis cubes mail tls set bank.example verify
ArgumentValue
domainthe recipient domain
policymay, encrypt, secure, verify or none

Setting a policy replaces the row for that domain.

text
✔ mail: policy for example.com: encrypt{"ok": true, "cube": "mail", "result": "policy for bank.example: verify"}

#tls remove

Destructive. Drops the policy row; delivery to that domain falls back to the global Postfix policy.

bash
aegis cubes mail tls remove example.comaegis --json cubes mail tls remove example.com
text
✔ mail: policy removed for example.com{"ok": true, "cube": "mail", "result": "policy removed for example.com"}

#Storage

Usage is measured on the filesystem with du, not read from the database.

#storage usage

bash
aegis cubes mail storage usageaegis --json cubes mail storage usage

One line: mailbox count, total size and the root it measured.

text
✔ mail: 7 mailboxes, 1.2G under /aegis/data/mail{"ok": true, "cube": "mail", "result": "7 mailboxes, 1.2G under /aegis/data/mail"}

#storage list

bash
aegis cubes mail storage list --limit 10aegis --json cubes mail storage list
OptionMeaning
--limitshow only the N biggest mailboxes; 0 (default) shows all
text
✔ mail: postmaster@example.com 128.0M/5.0G (2%); sales@example.com 7.0M/1.0G (0%){"ok": true, "cube": "mail", "result": "postmaster@example.com 128.0M/5.0G (2%); sales@example.com 7.0M/1.0G (0%)"}

#storage purge

Destructive. Deletes every file in new, cur and tmp of one maildir. The directory and Dovecot's index files stay, so the mailbox keeps working. --yes is mandatory.

bash
aegis cubes mail storage purge sales@example.com --yesaegis --json cubes mail storage purge sales@example.com --yes
OptionMeaning
addressthe mailbox to empty
--yesrequired; without it the command refuses to delete mail
text
✔ mail: purged 312 messages from sales@example.com{"ok": true, "cube": "mail", "result": "purged 312 messages from sales@example.com"}

#Demo

demo writes two hook scripts, registers one inbound and one outbound hook through the postfix cube, and sends a message through submission so both directions fire. It is the quickest end-to-end check of SMTP AUTH, the queue, the milter and the hooks. The default directory is /var/aegis/demo, overridable with mail.demo.dir; the submission port is mail.demo.port (default 587). The PHP cube must be built, because the inbound hook runs through the bundled PHP.

#demo prepare

bash
aegis cubes mail demo prepare --domain example.com --email demo@example.comaegis --json cubes mail demo prepare --domain example.com --email demo@example.com
OptionMeaning
--domainrequired; created when the mail database lacks it
--emailrequired; the demo account, created with a random password

Writes demo-php-hook.php, demo-python-hook.py and account.json (mode 0600), creates the log directory and adds hooks demo-in (inbound) and demo-out (outbound).

text
✔ mail: demo ready in /var/aegis/demo; account demo@example.com; hooks demo-in/demo-out -> logs/hooks.log{"ok": true, "cube": "mail", "result": "demo ready in /var/aegis/demo; account demo@example.com; hooks demo-in/demo-out -> logs/hooks.log"}

#demo run

bash
aegis cubes mail demo run --to postmaster@example.comaegis cubes mail demo run --to postmaster@example.com --subject 'Hook check'
OptionMeaning
--torequired; the recipient
--subjectoptional subject; a timestamped one is generated when empty

Logs in with the account written by demo prepare, so that command must have run first.

text
✔ mail: sent to postmaster@example.com from demo@example.com; hooks log /var/aegis/demo/logs/hooks.log{"ok": true, "cube": "mail", "result": "sent to postmaster@example.com from demo@example.com; hooks log /var/aegis/demo/logs/hooks.log"}