Aegis documentation

#Mail database schema

The mail stack shares one database: Postfix reads domains, mailboxes, aliases and policies from it on every lookup, Dovecot authenticates against it, OpenDKIM stores its keys and the mail cube is the only thing that writes. Nothing is cached in files, so a row change is live immediately.

#Where it lives

BackendDatabaseRoleConfigured by
PostgreSQLmail.database.name (aegis_mail)mail.database.user (aegis_mail)aegis cubes postfix configure
MariaDBsamesamesame
SQLitemail.database.sqlite_path—same

The backend is chosen at install time ([apps.postfix] database) and can be changed later; the schema files below are per backend and idempotent.

text
storage/data/apps/postfix/schema/pgsql.sql     applied by the postfix cubestorage/data/apps/postfix/schema/mysql.sqlstorage/data/apps/postfix/schema/sqlite.sql

The role password is generated once and stored in config/server.toml under [mail.database] password; the cube re-applies it to the role on every configure, so the two can never drift apart.

#Ownership: who writes what

TableWritten byRead by
aegis_domainsmail domains …Postfix domain map, mail, opendkim, postsrsd
aegis_mailboxesmail mailboxes …Postfix mailbox/quota/login maps, Dovecot
aegis_aliases, aegis_forwardsmail aliases/forwards …Postfix alias map
aegis_relocatedmail relocated …Postfix relocated_maps
aegis_transportpanel/SQLPostfix transport map
aegis_relays, aegis_relay_domainspostfix relays …Postfix transport map + master.cf
aegis_tls_policymail tls …Postfix smtp_tls_policy_maps
aegis_security_rulespostfix security …compiled into header_checks and access maps
aegis_hookspostfix hooks …hook runner (hooks.json)
aegis_dkimopendkim (key material)not read by Postfix; the key files are
aegis_sender_bcc, aegis_recipient_bccpanel/SQLPostfix BCC maps
aegis_outbound_ips, aegis_access, aegis_admins, aegis_autorespondersreserved—

#Routing tables

#aegis_domains

The list of domains Postfix accepts mail for.

ColumnTypeMeaning
idserialprimary key
domaintext, uniquethe name, lowercase, no trailing dot
activeboolfalse = treat the domain as remote (MX lookup again)
transporttextdefault virtual; kept for non-LMTP setups
catch_alltextaddress that receives unmatched recipients
max_mailboxesintadvisory limit used by the panel
default_quota_bytesbigintquota for new mailboxes
max_quota_bytesbigintceiling for a single mailbox
dkim_selectortextselector OpenDKIM uses for this domain
created_at, updated_attimestampbookkeeping

#aegis_mailboxes

One row per usable address, including its Dovecot password and maildir.

ColumnTypeMeaning
addresstext, uniquefull address, lowercase
local_parttexteverything before @, duplicated for lookups
domaintext, FK → aegis_domains.domainON DELETE CASCADE
display_nametextfree text for the panel
passwordtextcrypt hash, never plaintext
password_schemetextSHA512-CRYPT (Dovecot 2.4 refuses MD5)
maildirtextabsolute path, also used as Dovecot home
quota_bytesbigintnull = domain default
activeboolfalse = no delivery, no login
disabled_reasontextwhy it was disabled
last_login_at, last_auth_attimestampreserved for the panel
created_at, updated_attimestampbookkeeping

Indexes: domain, active — the map queries filter on both.

#aegis_aliases

Plain redirects, one destination per row.

ColumnTypeMeaning
addresstext, uniquethe alias itself
destinationtextfull address, or a comma-separated list
owner_logintextlogin allowed to send as this address
activeboolfalse = ignored by the map

#aegis_forwards

Forwarding that can keep a local copy.

ColumnTypeMeaning
addresstextsource address
destinationtextexternal (or internal) target
owner_logintextlogin allowed to send as the source
keep_localbooltrue = deliver here and forward
activeboolfalse = ignored

UNIQUE (address, destination) allows several targets per address.

#aegis_relocated

Answers 551 User not local; please try <destination>.

ColumnTypeMeaning
addresstext, uniquethe old address
destinationtextwhere the user moved
activeboolfalse = no answer

#aegis_transport

Per-destination transport override, used before the relay routes.

ColumnTypeMeaning
destinationtext, uniquedomain or address
transporttextfor example lmtp:unix:…, smtp:[host]:25
activeboolfalse = ignored

#Relay tables

aegis_relays describes named outbound transports: each one becomes a service in master.cf with its own source address and HELO name.

ColumnTypeMeaning
nametext, uniquetransport name, aegis-<name> in master.cf
hosttext, nullsmarthost; null = deliver to the recipient's MX
portintsmarthost port, default 587
username, passwordtextSASL credentials for a smarthost
tlsboolrequire TLS towards a smarthost
bind_iptextsource address the transport binds
helo_nametextHELO/EHLO announced by the transport
syslog_nametexttag in the log, default aegis-<name>
priorityintdisplay order
activeboolfalse = not rendered

aegis_relay_domains routes destinations through one of those transports:

ColumnTypeMeaning
destinationtextdomain or address
relaytext, FK → aegis_relays.nameON DELETE CASCADE
activeboolfalse = ignored

aegis_outbound_ips is a reservation for the multi-IP panel page: it lists the addresses a server may send from (address, label, is_default, active) without duplicating what aegis_relays.bind_ip already does.

#Policy tables

TableColumnsUsed for
aegis_sender_bccaddress, destination, activeblind copy of mail from an address
aegis_recipient_bccaddress, destination, activeblind copy of mail to an address
aegis_accesspattern, action, activereserved for the anti-abuse access lists
aegis_tls_policydomain, policy, activeoutbound TLS: may, encrypt, secure, verify, none

#Signing and content

#aegis_dkim

One row per domain and selector. The private key stays on disk; this table is the record of what was generated and when.

ColumnTypeMeaning
domain, selectortextunique together
private_keytextreserved; the cube keeps keys under opendkim.key_dir
public_keytextreserved
activeboolfalse = not published

#aegis_security_rules

Compiled into Postfix check files by postfix configure.

ColumnTypeMeaning
kindtextheader, body, sender, helo, rbl
patterntextregexp, or a blocklist zone for rbl
actiontextreject, defer, discard, warn
messagetexttext shown to the sender
priorityintorder inside the generated file
activeboolfalse = not compiled

#aegis_hooks

Mail hooks executed by the pipe runner.

ColumnTypeMeaning
nametext, uniquehook identifier
enabledboolfalse = skipped by the runner
directiontextinbound, outbound, both
match_typetextall, domain, address
match_valuetextdomain or address for the two specific matches
handler_typetextscript or webhook
handler_valuetextshell command, or URL for a webhook
timeout_secinthow long the handler may run

#aegis_autoresponders

Reserved for vacation replies: address, subject, body, active, starts_at, ends_at. The table exists so the panel can store the text; the Sieve side is not implemented yet.

#aegis_admins

Reserved for postmaster accounts that log into the panel rather than receive mail: username, password, active.

#Views read by the maps

ViewReturnsUsed by
aegis_mail_forwardingone row per address, destinations joined with ,virtual_alias_maps
aegis_transport_mapdestination → transporttransport_maps
aegis_mail_quotaaddress → effective quotareference only (Dovecot enforces)
aegis_sender_loginaddress → allowed loginssmtpd_sender_login_maps

aegis_mail_forwarding merges aliases and forwards; keep_local adds the address itself to the destination list, which is what delivers a copy locally before forwarding.

aegis_transport_map turns a relay route into aegis-<relay>:, the service name the postfix cube writes into master.cf.

#Map files → queries

Each file under config/postfix/maps/ holds a driver, the connection details and one SQL query; %s is the lookup key.

Map filePostfix parameter
domains.cfvirtual_mailbox_domains
mailboxes.cfvirtual_mailbox_maps
aliases.cfvirtual_alias_maps (exact match or catch-all)
transport.cftransport_maps
relocated.cfrelocated_maps
sender_bcc.cf, recipient_bcc.cfsender_bcc_maps, recipient_bcc_maps
sender_login.cfsmtpd_sender_login_maps
tls_policy.cfsmtp_tls_policy_maps
quota.cfreference only

The alias map is the only one with two branches, and it uses UNION rather than UNION ALL so an address that is both an alias and covered by the catch-all resolves once:

sql
SELECT destination FROM aegis_mail_forwarding WHERE address = '%s'UNIONSELECT catch_all FROM aegis_domainsWHERE domain = split_part('%s', '@', 2) AND catch_all IS NOT NULL AND active

#Inspecting the data

bash
# as the mail role, over TCPpsql -h 127.0.0.1 -U aegis_mail -d aegis_mail# who has mailboxes, how many, how muchSELECT d.domain countm.id AS boxes       pg_size_prettysumCOALESCEm.quota_bytes d.default_quota_bytesFROM aegis_domains dLEFT JOIN aegis_mailboxes m ON m.domain = d.domain AND m.activeGROUP BY d.domain ORDER BY d.domain;# what the alias map returns for one addressSELECT  FROM aegis_mail_forwarding WHERE address = 'info@example.com';# which domains are signed with which selectorSELECT domain dkim_selector FROM aegis_domains WHERE active;

The CLI wraps all of it: aegis cubes mail domains list|show, mailboxes show, storage list, postfix security list, opendkim keys list.

#Changing the schema

The files are applied with CREATE … IF NOT EXISTS on every configure, so a new table is a safe addition. A new column on an existing table needs an ALTER TABLE … ADD COLUMN IF NOT EXISTS for PostgreSQL and MariaDB (SQLite has no such clause: the column is added to the CREATE TABLE and existing SQLite installs must be recreated or altered by hand). Columns added after the first release are grouped together in each file, next to a comment saying why.