Configuration

Sovite reads one TOML file:

• $SOVITE_CONFIG, if set
• otherwise /etc/sovite/sovite.toml

Validate a file without starting the MTA:

sovitectl config check                 # default path
sovitectl config check ./sovite.toml   # explicit path

The command exits with 0 if the file is valid. Otherwise it prints every problem with the path of the bad key and exits with 1:

./sovite.toml: queue.directory: "spool" is not an absolute path
./sovite.toml: log.level: expected one of "debug", "info", "notice", "warning", "error", got "loud"

The MTA runs the same validation at startup and will not start with an invalid file. Unknown keys are errors, so typos are caught instead of being silently ignored.

Every setting is optional. A release ships a commented example at etc/sovite.toml.example.

[server]

[database]

Sovite keeps its own data (login users and the addresses they may send as) in a database, managed with Ecto. The schema is created and upgraded automatically at startup.

Sovite releases include the drivers for all three. (When Sovite is used as a library, postgrex and myxql are optional dependencies; sovitectl config check says so if one is missing.)

[queue]

The queue

Each message is one file in one of these directories:

Delivery results are appended to the message's file and fsynced as they come in. If Sovite stops for any reason, even kill -9 or a power failure, messages in active/ go back to incoming/ at startup and only the recipients without a recorded result are tried again. A recipient whose delivery was in progress may receive the message twice, which SMTP allows; a message is never lost.

[[listener]]

An array of tables: one per address and port to accept mail on. Without any [[listener]] table, Sovite listens on 0.0.0.0:25. Write listener = [] (before the first table) to listen nowhere.

[[listener]]            # MX: mail from the Internet
address = "0.0.0.0"
port = 25

[[listener]]            # mail clients, STARTTLS (RFC 6409)
address = "0.0.0.0"
mode = "submission"

[[listener]]            # mail clients, implicit TLS (RFC 8314)
address = "0.0.0.0"
mode = "submissions"

STARTTLS is offered on smtp and submission listeners whenever a certificate is configured in [tls]. A submissions listener starts TLS right after the connection opens, so it needs a certificate.

An lmtp listener speaks LMTP (RFC 2033) instead of SMTP, for use behind another MTA that hands mail over to Sovite: the client greets with LHLO, and gets one reply per recipient after the message. Its defaults are those of smtp (no AUTH, no required TLS), and it must not use port 25. Relay control and restrictions apply as on any other listener.

To let mail clients find the submission ports by themselves (RFC 6186), publish SRV records such as _submissions._tcp.example.com. SRV 0 1 465 mx.example.com. and _submission._tcp.example.com. SRV 10 1 587 mx.example.com.

[tls]

Certificates for STARTTLS and implicit TLS, and the TLS settings for all listeners. Only TLS 1.2 and 1.3 are enabled (RFC 8996), and only forward-secret AEAD cipher suites (BCP 195, RFC 9325): ECDHE with AES-GCM or ChaCha20-Poly1305. The server chooses the cipher, and renegotiation started by a client is refused.

[[tls.certificate]]
cert_file = "/etc/sovite/tls/mx.example.com.pem"   # certificate, then intermediates
key_file = "/etc/sovite/tls/mx.example.com.key"

[[tls.certificate]]                                 # another name, or an RSA twin of the one above
cert_file = "/etc/sovite/tls/mail.example.org.pem"
key_file = "/etc/sovite/tls/mail.example.org.key"

The default cipher list is TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256 (TLS 1.3), then ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305 (TLS 1.2). testssl.sh rates it A+ with a trusted certificate.

Choosing a certificate (SNI). A client that names the server it wants (SNI, RFC 6066) gets every certificate valid for that name; with both an RSA and an ECDSA certificate for a name, the client's preference decides. Wildcards match one label. Clients that send no name, or an unknown one, get the first certificate (and any other with exactly the same names).

[tls.acme]

Get and renew a certificate automatically from an ACME CA (RFC 8555), Let's Encrypt by default, with HTTP-01 challenges.

[tls.acme]
enabled = true
domains = ["mx.example.com", "mail.example.com"]
email = "postmaster@example.com"
accept_terms = true

The ACME certificate is used like the files in [[tls.certificate]], after them; with no other certificate it is the default.

[smtp]

Settings for all listeners. Limits apply per listener.

HTTP requests and header lines (cross-protocol attacks) close the session with 421 4.7.0.

ESMTP extensions

• CHUNKING and BINARYMIME (RFC 3030). A client may send BDAT <size> and the message in chunks of exactly that many bytes, the last one with BDAT <size> LAST, instead of DATA. There is no dot-stuffing; bare line endings get the bare_line_endings policy all the same. A chunk is always read to its end, also when it is refused, so its content is never taken for commands. With binarymime, MAIL FROM:<...> BODY=BINARYMIME announces a binary message, which must be sent with BDAT. When delivering, Sovite uses BDAT for servers that offer CHUNKING (delivery.chunking).
• DSN (RFC 3461). RCPT TO:<...> NOTIFY=SUCCESS,FAILURE,DELAY (or NOTIFY=NEVER) chooses which notifications the sender gets about that recipient, ORCPT=rfc822;address names the address it was originally sent to, MAIL FROM:<...> RET=FULL (or HDRS) asks for the whole message (or only its header fields) back in a failure notification, and ENVID=... gives an ID that notifications quote. Without NOTIFY, failures and delays are reported, as before. These parameters are passed on to next hops that support DSN. A recipient delivered to a mailbox here is reported as "delivered" when SUCCESS was asked for, and one delivered to a server without DSN as "relayed". An alias that forwards to one address passes the parameters on; one that expands to several passes them on without SUCCESS, and is itself reported as "expanded" (RFC 3461 §5.2.7.3).
• MT-PRIORITY (RFC 6710). MAIL FROM:<...> MT-PRIORITY=3 gives a message a priority from -9 to 9 (0 by default): messages to the same destination are sent in priority order, and the priority goes to next hops that support it. Clients that are neither trusted nor authenticated may lower it, not raise it. The Received: field shows it (PRIORITY 3).
• FUTURERELEASE (RFC 4865). On submission listeners, an authenticated client may send MAIL FROM:<...> HOLDFOR=3600 or HOLDUNTIL=2026-10-20T08:00:00Z: the message waits in the queue until then, up to submission.max_future_release ahead, and its queue.max_lifetime starts at its release.
• DELIVERBY (RFC 2852). MAIL FROM:<...> BY=3600;R asks for delivery within an hour, or the message is returned (5.4.7); it then only goes to next hops that support DELIVERBY, which get the time left. BY=3600;N sends a delay notification when the hour is up instead, and a "relayed" notification when the message goes to a server without DELIVERBY; T (BY=3600;RT) asks for "relayed" notifications on the way.
• RRVS (RFC 7293). RCPT TO:<...> RRVS=2014-04-03T23:01:00Z asks that the recipient's mailbox has had the same owner since then. A mailbox here that was added later (sovitectl mailbox add) gets 550 5.7.17; other local recipients, and role accounts such as postmaster, pass. For a relayed recipient the parameter goes to the next hop, which must support RRVS: otherwise it fails with 5.7.19, or with ;C goes on without.
• ETRN (RFC 1985). ETRN example.net retries the deferred mail for a relay domain now, ETRN @example.net for it and its subdomains, as a backup MX does when the primary comes back. Only for relay domains (domains.relay, or relay in the database), at most once a minute per domain; others get 459.

Internationalized mail

Sovite handles internationalized mail (RFC 6530–6533): addresses with UTF-8 local parts such as jürgen@example.de, internationalized domain names such as bücher.example, and UTF-8 header fields.

• Receiving. A client that sends MAIL FROM:<...> SMTPUTF8 may use internationalized addresses for the sender and recipients of that message, and UTF-8 header fields. Without the parameter, such an address gets 553 5.6.7. The Received: field says with UTF8SMTP (or UTF8SMTPS, UTF8SMTPSA, ...).
• Domains. Domain names are checked with IDNA2008 (RFC 5890–5893) and used in their A-label form (xn--bcher-kva.example) everywhere inside Sovite: in the queue, for routing, in DNS lookups, and in the database. Domains can be written either way in the config file and with sovitectl, so hosted = ["bücher.example"] and sovitectl alias add info@bücher.example ... work, and match mail sent to either form. Local parts are kept as they are written.
• Delivering. A message is sent with SMTPUTF8 when it needs it: when an address of the transaction is internationalized, or when it came with SMTPUTF8 and has UTF-8 header fields. Otherwise it goes out as plain mail. An internationalized message cannot be converted for a next hop that does not support SMTPUTF8 (RFC 6531 §3.2), so it is returned to the sender: 5.6.7 for internationalized addresses, 5.6.9 for UTF-8 header fields.
• Notifications. Delivery status notifications about internationalized mail are internationalized ones (RFC 6533): a message/global-delivery-status report that names internationalized addresses with the utf-8 type (Final-Recipient: utf-8; jürgen@example.de), the original header fields as message/global-headers, and a UTF-8 explanation.

Domains in addresses can be written in U-labels in From: and other header fields (RFC 6532); DMARC looks up their A-labels.

[domains]

Who may send what

Each recipient is checked when the client sends RCPT TO:

1. postmaster and abuse at a local domain, or a bare <Postmaster>, are always accepted (RFC 5321 §4.5.1, RFC 2142).
2. Local domain: accepted if local_recipients is unset or lists the address.
3. Relay domain: accepted.
4. Any other domain: accepted only from trusted_networks or after AUTH, otherwise 554 5.7.1 Relay access denied.

Domains are compared case-insensitively, and only the domain of the parsed address counts: tricks like user%other.example@local or source routes never relay. The default config trusts no one, so a fresh install is never an open relay.

A message is accepted with 250 2.0.0 Ok: queued as <queue ID> only after it is written and fsynced in the queue directory.

Transports

Each recipient's domain class picks a transport from [routing]: local_transport (default "local") for domains.local, mailbox_transport ("mailbox") for hosted domains, relay_transport and remote_transport ("smtp") for relay and all other domains. The transports table (sovitectl transport) can override it per address or domain.

LMTP, Maildir, and pipe deliveries are final. A message whose Delivered-To: field already names the recipient has been here before, and fails for that recipient as a mail loop (5.4.6, RFC 9228). Maildir and pipe deliveries add Return-Path: and Delivered-To: at the top (RFC 5321 §4.4); an LMTP server adds its own.

A typical Dovecot setup:

[domains]
hosted = ["example.com"]

[routing]
mailbox_transport = "lmtp:unix:/run/dovecot/lmtp"

[maildir]

Maildir delivery for the local and mailbox transports. Without a folder for a transport, its mail is deferred with 4.3.5.

Templates are absolute paths with {user} (the lower-cased local part without its extension), {domain}, and {address} (user@domain). An address that would not be a safe path component (with /, or . and ..) fails with 5.1.3. Folders are created as needed with mode 0700, and must be writable by the Sovite user. Messages are written to tmp/, flushed to disk, and then moved into new/.

[pipe.NAME]

Commands the pipe:NAME transport runs, once per recipient, with the message on standard input. Names may use letters, digits, _, and -.

[routing]
local_transport = "pipe:procmail"

[pipe.procmail]
command = ["/usr/bin/procmail", "-a", "{extension}", "-d", "{user}"]
sandbox = ["/usr/bin/systemd-run", "--quiet", "--pipe", "--wait", "--collect", "-p", "DynamicUser=yes"]

The command is run directly, never through a shell: placeholders in arguments are replaced, and each argument reaches the command as it is. Placeholders: {sender}, {recipient}, {user}, {extension} (without the delimiter), {domain}, and {queue_id}. Addresses can start with -, so put -- before them if the command takes options. The environment is empty apart from PATH, env, and SENDER, RECIPIENT, USER, EXTENSION, DOMAIN, and QUEUE_ID.

The exit status decides the result, as in Postfix: 0 is delivered, 75 (EX_TEMPFAIL) and other temporary sysexits.h codes are retried, 67 (EX_NOUSER) and other permanent codes bounce, as does any other status. A command killed by a signal is retried. The first line of its output goes into the bounce.

Sovite cannot switch users, so the command runs as the Sovite user unless sandbox changes that.

[delivery]

Outbound delivery over SMTP, for the smtp transport.

How mail is delivered

For each recipient domain, Sovite looks up the MX records, tries the hosts from the best preference down (hosts with the same preference in random order), and each host's addresses in ip_versions order. A domain without MX records is its own mail host. A connection failure, a rejected greeting, or a connection lost before the message is sent moves on to the next address.

Recipients at the same destination share a transaction, and other recipients of the same message are unaffected by one recipient's result. An idle connection is reused for the next message to the same destination.

Outbound TLS

With may and dane, mail to a domain's MX hosts also follows the domain's MTA-STS policy (RFC 8461), see [mta_sts]. DANE wins: for an MX host with usable TLSA records, the MTA-STS policy is not used.

When TLS is required and cannot be used, that address is skipped (4.7.4 not offered, 4.7.5 handshake or certificate failure) and the message is retried later. A relay host on port 465 is reached with implicit TLS. Delivery log lines show the TLS version and cipher (tls=TLSv1.3 with cipher ...).

A message with a TLS-Required: No header field (RFC 8689 §5) asks to be delivered even when TLS fails: DANE and MTA-STS policies are ignored for it, and it is sent with may. Levels set in tls and tls_policy other than dane still apply.

REQUIRETLS

A client that sends MAIL FROM:<...> REQUIRETLS (RFC 8689) asks that its message is only ever sent over TLS with a verified certificate. Sovite then delivers it only:

• to an MX host covered by DANE, or by the domain's MTA-STS policy (in testing mode too, which is enforced for these messages), or to the relay host with a certificate valid for its name;
• over TLS, to a server that offers REQUIRETLS itself, so it passes the requirement on.

Otherwise the message bounces with 5.7.30. The bounce is sent with REQUIRETLS too, and as always contains only the message's header fields.

[dns]

The DNS resolver for all lookups. Unset keys use the system's settings (/etc/resolv.conf).

DANE needs a validating resolver on this host. With Unbound, for example:

# /etc/unbound/unbound.conf
server:
    interface: 127.0.0.1
    auto-trust-anchor-file: "/var/lib/unbound/root.key"

and nameservers = ["127.0.0.1"] (or nameserver 127.0.0.1 in /etc/resolv.conf). At startup, Sovite checks that the resolver validates and logs a warning if not. sovitectl dns check runs the same check.

[mta_sts]

MTA-STS (RFC 8461) lets a domain say that mail to it must use TLS with a valid certificate: it publishes a TXT record at _mta-sts.<domain> and a policy at https://mta-sts.<domain>/.well-known/mta-sts.txt listing its MX hosts.

Sending. Before delivering to a domain, Sovite looks up its record, fetches the policy when the record's id changed, and keeps it in the database for the policy's max_age. If the record disappears or the fetch fails, a cached policy is still used until it expires, so an attacker who blocks DNS or HTTPS cannot turn it off. Policies apply with the may and dane levels (the default), to MX deliveries, not to relay hosts:

Receiving. To publish a policy for your own domains, Sovite can serve it (serve = true), or any web server can. sovitectl dns records example.com prints the policy and the TXT record; the record's id is derived from the policy, so it changes exactly when the policy does. To serve it with Sovite, point mta-sts.example.com at this server, and include that name in the TLS certificate (in tls.acme.domains, or the certificate files).

[tls_rpt]

TLS-RPT (RFC 8460) reports tell a domain whether servers sending mail to it could use TLS. Domains ask for them with a TXT record at _smtp._tls.<domain>.

With reports = true, Sovite records the outcome of each session to a domain's MX hosts: which policy applied (DANE, MTA-STS, or none), and whether TLS worked or why not. Every report_interval it sends one report per domain that asks for them, gzipped JSON, by mail to its mailto: addresses (DKIM signed when report_from's domain has a [[dkim.key]]) and to its https: addresses. Outcomes are kept in the database until then.

For your own domains, sovitectl dns records prints a TLS-RPT record that sends the reports of others to postmaster@<domain>.

Anti-abuse

Checks of clients that send mail to this server, in the order they run. None of them apply to smtp.trusted_networks, and the screen and greylisting only run on listeners with screen (by default, smtp ones).

[screen]

A postscreen-like score for each client. The client's address is looked up in the DNS lists below while the greeting is held back for greet_delay; each list it is on adds that list's weight. A client that talks before the greeting is an early talker, a typical spam bot, and adds early_talker_weight. At EHLO and MAIL, the RHSBL lists add the weights of the EHLO name and the sender's domain.

A client that reaches threshold is refused: before the greeting with 554 5.7.1 Service unavailable; client [192.0.2.1] blocked: listed by zen.spamhaus.org, and the connection is closed; at EHLO or MAIL, that command gets 554 5.7.1. A client at or below allow_threshold, such as one on a DNSWL list with a negative weight, skips the RHSBL lists and greylisting. A client that passed (no early talking, no failed lookup) is remembered for cache_time: its next connections are not delayed or looked up again.

[screen]
greet_delay = "6s"

[[screen.dnsbl]]
zone = "zen.spamhaus.org"
weight = 2
codes = ["127.0.0.[2..11]"]

[[screen.dnsbl]]
zone = "bl.spamcop.net"
weight = 1

[[screen.dnsbl]]
zone = "list.dnswl.org"
weight = -2
codes = ["127.0.[0..255].[1..3]"]

[[screen.rhsbl]]
zone = "dbl.spamhaus.org"
weight = 2
codes = ["127.0.1.[2..99]"]

Each list has:

Replies outside 127.0.0.0/8 are ignored, and 127.255.255.0/24 replies (list errors, such as Spamhaus refusing queries from public resolvers) count as failed lookups and are logged. Most lists only answer your own resolver, so use one on this host (see [dns]).

Restrictions for EHLO names and reverse DNS

These checks can be added to the [restrictions] chains (Sovite.Core.Restrictions lists all checks):

When DNS fails, they reply 450 instead, so no client is refused for a temporary problem. For example:

[restrictions]
helo = ["permit_trusted", "permit_authenticated", "reject_forged_helo", "require_fqdn_helo"]
mail = ["permit_trusted", "permit_authenticated", "require_reverse_hostname"]

[rate_limit]

Limits over a sliding window, as "count/duration", such as "100/1h". Unset limits do not apply. Client limits count per client address (per /64 for IPv6), and authenticated clients only count against the user limits. Counts are kept in memory.

[greylist]

Greylisting: a valid recipient from an unknown client network (/24 or /64) and sender gets 450 4.7.1 ... Greylisted, try again in 300s. Real mail servers try again, and are let through after delay; most spam bots never retry. Once a client network, sender, and recipient have passed, they pass at once until they go unused for max_age. Authenticated and allow-listed clients skip it. Triplets are kept in the database; if it fails, mail passes.

[outbound]

Detects accounts that are probably compromised. Each recipient an authenticated user's message is queued for counts as sent, and each one that fails for good as failed. A user with at least min_failures failures in the last window, making up at least max_failure_percent of what they sent, is suspended for suspend_time: their MAIL commands get 550 5.7.1, and a warning is logged (outbound.suspended). Suspensions are kept in memory, so restarting Sovite lifts them. Cap the volume a user can send with the user_* limits in [rate_limit].

Ecosystem

Sovite works with the tools a Postfix setup uses: milters such as Rspamd and OpenDKIM, policy servers such as postgrey, after-queue content filters such as amavis, proxies, and programs that call sendmail. sovitectl migrate postfix turns a Postfix configuration into a Sovite one, see Migrating from Postfix.

[[milter]]

Mail filters that speak Sendmail's milter protocol (version 6), as Postfix's smtpd_milters: Rspamd, OpenDKIM, OpenDMARC, ClamAV-milter, and others. Each listener runs the milters in milters (by default all of them, except on lmtp and reinjection listeners), each with its own connection per SMTP session, after Sovite's own checks of each stage.

[[milter]]
name = "rspamd"
address = "inet:127.0.0.1:11332"
default_action = "accept"

[[milter]]
name = "opendkim"
address = "unix:/run/opendkim/opendkim.sock"

A milter can reject the client, a command, a recipient, or the message (550 5.7.1 Command rejected, 451 4.7.1 Service unavailable - try again later, or its own reply), discard or quarantine the message (it goes to the hold queue), and at the end of the message add, insert, change, and delete header fields, add and remove recipients, change the sender, and replace the body. The milters see the message as it was received, including Sovite's Received: field, and their changes are applied in order. Sovite's own DKIM signatures and Authentication-Results: cover the message before those changes, so sign in one place only: with Sovite's [dkim] keys, or with the milter.

Milters get the macros Postfix sends by default, such as i (the queue ID), {client_addr}, {auth_authen}, and {daemon_name} (the listener).

Policy servers: [policy]

check_policy_service ADDRESS in any [restrictions] chain asks a Postfix policy server (the SMTPD access policy delegation protocol), such as postgrey or policyd-spf, with the attributes Postfix sends. ADDRESS is inet:host:port, unix:/path, or spawn:/path/to/program args... for programs that only talk on their standard input and output, as Postfix's spawn(8) runs policyd-spf (Sovite starts one per request, as its own user).

[restrictions]
rcpt = [
  "permit_trusted",
  "permit_authenticated",
  "check_policy_service inet:127.0.0.1:10023",       # postgrey
  "check_policy_service spawn:/usr/bin/policyd-spf",
]

The reply counts as an access rule: OK, DUNNO, REJECT, DEFER, DEFER_IF_PERMIT, 4NN/5NN replies, HOLD, DISCARD, WARN, and INFO, as well as PREPEND (a header field at the top of the message), REDIRECT address, BCC address, and FILTER transport:nexthop (a content filter for this message). DEFER_IF_REJECT counts as DUNNO.

Sovite checks SPF itself (see [spf]), so policyd-spf is only needed to keep its exact behaviour.

Content filters

An after-queue content filter, such as amavis, gets every message received on a listener with a content_filter before it is delivered, as with Postfix's content_filter: the queue sends it, with all its recipients and its original sender, to the filter over SMTP or LMTP, and the filter sends it back to a reinjection listener. Filters that offer XFORWARD are told the original client, HELO name, and queue ID; trust them with xforward_networks, so the message keeps them.

[smtp]
content_filter = "smtp:[127.0.0.1]:10024"
trusted_networks = ["127.0.0.1"]   # the filter relays its mail back
xforward_networks = ["127.0.0.1"]

[[listener]]
port = 25

[[listener]]                       # where amavis sends mail back
address = "127.0.0.1"
port = 10025
reinjection = true

The filter is a next hop of its own: delivery to it does not use REQUIRETLS, and a filter that is down keeps the mail in the queue as any next hop does. Messages a policy server sends to a FILTER go to that filter instead.

Proxies: PROXY protocol, XCLIENT, and XFORWARD

Behind HAProxy or a load balancer, a listener with proxy_protocol = true reads a PROXY protocol header (version 1 or 2) at the start of each connection, and treats the client it names as the client: restrictions, the screen, SPF, and logs see the real address. A connection without a valid header in smtp.proxy_timeout is closed. With smtp.proxy_networks, only connections from those addresses must send one, and others are served directly. Connection limits (max_connections_per_ip) count the proxy.

[smtp]
proxy_networks = ["10.0.0.5"]       # the load balancer

[[listener]]
port = 25
proxy_protocol = true

# haproxy.cfg
backend sovite
    mode tcp
    server mx1 10.0.0.10:25 send-proxy-v2

Clients in smtp.xclient_networks may use Postfix's XCLIENT command, as the nginx mail proxy does: it names the client (ADDR, PORT, NAME, HELO, PROTO, LOGIN, ...), and the session starts over as if that client had connected; a LOGIN counts as authenticated. XFORWARD (smtp.xforward_networks) only describes the original client of the next message, for content filters.

[sendmail]

Releases include bin/sendmail, bin/mailq, and bin/newaliases for local programs and cron jobs. Link them where programs look for them:

ln -s /opt/sovite/bin/sendmail /usr/sbin/sendmail
ln -s /opt/sovite/bin/mailq /usr/bin/mailq
ln -s /opt/sovite/bin/newaliases /usr/bin/newaliases

sendmail takes the usual options (-t, -f, -F, -i/-oi, -bp, -bi, ...; see Sovite.Core.Sendmail) and sends the message over SMTP to server, waiting until it is queued, so the exit status tells whether that worked (75 when Sovite is not running). The listener must let local programs relay: add 127.0.0.1 to smtp.trusted_networks. Addresses without a domain get @origin. mailq lists the queue (as root or the Sovite user, since it reads the queue directory). newaliases does nothing: aliases are in the database.

The settings are read from the config file when the user running sendmail can read it; otherwise the defaults apply.

Migrating from Postfix

sovitectl migrate postfix reads a Postfix configuration and writes what Sovite needs to replace it. It changes nothing on the system: it only reads the Postfix files, and writes three files to the output directory.

sovitectl migrate postfix /etc/postfix --output /root/sovite

The directory defaults to /etc/postfix, and the output to the current directory. Existing files are not overwritten without --force. --root DIR reads the files the configuration names, such as /etc/aliases, under DIR: use it on a copy of another server's /etc.

What it converts:

• main.cf: the host name and origin; the domain classes (mydestination, virtual_mailbox_domains, virtual_alias_domains, relay_domains) and mynetworks; certificates and TLS versions; Dovecot SASL; outbound TLS levels and policies; the relay host with its login; transports (virtual_transport, mailbox_transport, and services of master.cf they name, including pipe(8) commands, which become [pipe.NAME] sections); milters with their timeouts and default actions; smtpd_*_restrictions (merged into Sovite's stages, with reject_rbl_client and the like becoming [screen] lists); policy servers, including programs master.cf runs with spawn(8); postscreen's DNS lists, threshold, and greeting delay; the content filter; XFORWARD, XCLIENT, and PROXY protocol settings; queue lifetimes, size and rate limits, and other limits and timers.
• master.cf: one [[listener]] per inet smtpd or postscreen service and address of inet_interfaces, with its mode (submission, submissions for smtps or smtpd_tls_wrappermode), and the -o overrides that have listener keys: smtpd_sasl_auth_enable, smtpd_tls_security_level=encrypt, permit_sasl_authenticated, reject lists (require_auth), smtpd_milters, content_filter (an empty one makes the reinjection listener of an after-queue filter), and the PROXY protocol.

Lookup tables are read from their text source files (hash:/etc/postfix/virtual reads /etc/postfix/virtual, so run postmap sources only), as are inline: and static: tables. SQL, LDAP, regexp, PCRE, CIDR, and other tables are reported, for their entries to be added by hand.

A typical Postfix with Dovecot and Rspamd migrates to a config that works as it is, apart from steps in the report such as these:

• Postfix's sockets for Dovecot (private/auth, private/dovecot-lmtp) are in its queue directory, which goes away with Postfix: give Sovite its own listeners in Dovecot's 10-master.conf, such as /run/dovecot/auth-client and /run/dovecot/lmtp, and change auth.dovecot.socket and the LMTP transport.
• Sovite reads the TLS key as its own user, not as root.
• Programs master.cf ran as another user (user=) run as the Sovite user, unless a [pipe.NAME] has a sandbox. For policyd-spf, Sovite's own SPF check ([spf] reject_fail = true) can replace it.

[auth]

SMTP authentication (AUTH, RFC 4954) for mail clients on listeners with auth = true. An authenticated client may relay to any domain, but only from the addresses its login maps to.

Sender login maps. An authenticated user may use as MAIL FROM their login (when it is an address), and any address matching a pattern listed for the login in auth.senders or added with sovitectl user sender add. A pattern is an address, @domain for every address at a domain, or * for any address. Anything else gets 553 5.7.1 Sender address rejected: not owned by user. The null sender <> is always allowed.

[auth.senders]
"alice@example.com" = ["sales@example.com", "@example.org"]
"relay-bot" = ["*"]

Messages from authenticated clients are fixed up as RFC 6409 §8 allows: a missing Date: or Message-ID: is added, and the fields in submission.strip_headers are removed. Their Received: header uses ESMTPSA and shows the TLS version and cipher.

database backend

Users are kept in the database. Passwords are stored as SCRAM-SHA-256 hashes, so all three password mechanisms work. Manage them with sovitectl:

sovitectl user add alice@example.com            # asks for the password
sovitectl user passwd alice@example.com
sovitectl user disable alice@example.com        # or enable
sovitectl user sender add alice@example.com @example.org
sovitectl user sender remove alice@example.com @example.org
sovitectl user list
sovitectl user delete alice@example.com

User names are compared case-insensitively. The commands work whether or not the MTA is running.

file backend: [auth.file]

One user per line, name:hash, compatible with Dovecot's passwd-file (more fields after the hash are ignored, # starts a comment). Make hashes with sovitectl hash-password, which reads the password from standard input. Supported hashes: {SCRAM-SHA-256}... (the default, works with every mechanism), $6$... / {SHA512-CRYPT} and $5$... / {SHA256-CRYPT} (only PLAIN and LOGIN), and {PLAIN}password (not recommended).

alice@example.com:{SCRAM-SHA-256}4096,dGhpc2lzc2FsdA==,...
bob@example.com:$6$rounds=5000$saltsalt$...

ldap backend: [auth.ldap]

Checks passwords by binding to the directory as the user. Only PLAIN and LOGIN work.

An empty password is always refused, since LDAP treats it as an anonymous bind.

dovecot backend: [auth.dovecot]

Hands authentication to Dovecot's auth service, like Postfix's smtpd_sasl_type = dovecot. Dovecot then decides which users exist and checks their credentials.

In Dovecot, give Sovite's user access to the socket:

service auth {
  unix_listener auth-client {
    mode = 0660
    user = sovite
  }
}

Set auth.mechanisms to what Dovecot offers if it is more than PLAIN and LOGIN.

[auth.oauth]

OAUTHBEARER (RFC 7628): clients log in with an OAuth 2.0 access token from your identity provider, checked by token introspection (RFC 7662).

[submission]

Email authentication

Mail from outside (clients that are neither in smtp.trusted_networks nor authenticated, on listeners other than LMTP) is checked:

1. SPF (RFC 7208) when the client sends MAIL: may the client's address send mail for the MAIL FROM domain, and for the HELO name? At most 10 DNS-querying terms and 2 void lookups are followed, as the RFC says.
2. DKIM (RFC 6376) signatures, while the message is received. RSA-SHA256 and Ed25519-SHA256 (RFC 8463) are accepted; RSA-SHA1 signatures and RSA keys shorter than 1024 bits never pass (RFC 8301). At most 10 signatures per message are checked.
3. ARC (RFC 8617): the chain of seals forwarders and mailing lists added.
4. DMARC (RFC 7489) at the end of the data: does SPF or DKIM pass for a domain aligned with the From: domain? The policy is found by walking up the DNS tree from the From: domain (as DMARCbis does), so no public suffix list is needed.

The results go into an Authentication-Results: field at the top of the message:

Authentication-Results: mx.example.org;
	spf=pass smtp.mailfrom=alice@example.com;
	spf=pass smtp.helo=mail.example.com;
	dkim=pass header.d=example.com header.i=@example.com header.s=s2026 header.a=rsa-sha256 header.b=Xw3qPg5R;
	arc=none;
	dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=example.com

Mail from users (trusted or authenticated clients) is DKIM signed instead, with every key of [[dkim.key]] for the From: domain, or for its closest parent domain that has keys.

To publish the DNS records a domain needs, run sovitectl dns records example.com. It prints the MX, SPF, DKIM, DMARC, MTA-STS, and TLS-RPT records for this server's settings, and TLSA records for DANE when a certificate is configured. sovitectl dkim generate example.com s2026 /etc/sovite/dkim/example.com.pem makes a new key (rsa, rsa:4096, or ed25519 as a last argument) and prints its record.

[spf]

[dkim]

Each [[dkim.key]] is one key:

[[dkim.key]]
domain = "example.com"
selector = "s2026r"
file = "/etc/sovite/dkim/example.com.s2026r.pem"

[[dkim.key]]
domain = "example.com"
selector = "s2026e"
file = "/etc/sovite/dkim/example.com.s2026e.pem"   # an Ed25519 key: mail gets both signatures

To rotate a key: add the new key with sign = false, publish its record, and wait for DNS caches (a day is plenty). Then set sign = true on the new key and sign = false on the old one. Remove the old key and its record a week or so later, once no mail signed with it is waiting to be checked.

[arc]

[dmarc]

[srs]

The Sender Rewriting Scheme lets this server forward mail without breaking SPF at the destination. When an alias sends mail from outside on to another domain, that delivery uses a sender such as SRS0=HHHH=TT=example.com=alice@mx.example.org instead of alice@example.com. Bounces to it come back here, are checked, and are sent on to alice@example.com. The original sender stays in the queue: bounces from this server go to it directly, and local deliveries still see it.

[bounce]

Delivery status notifications (RFC 3464) are sent from MAILER-DAEMON@<server.hostname> with the null sender <>. They contain an explanation, a machine-readable report, and the headers of the original message (not its body). A failure notification about a message sent with RET=FULL (see ESMTP extensions) returns the whole message instead, unless it is larger than size_limit, binary, or was sent with REQUIRETLS. Which recipients are reported depends on their NOTIFY parameters.

[log]

[admin]

The web server: the web UI at /, the admin API at /api, which sovitectl uses to act on the running server (queue changes, reloads, status), and the Prometheus metrics at /metrics. It listens on the loopback address only, and every API request needs the token in token_file. See Operations for the requests and the protections.

[metrics]

# prometheus.yml
scrape_configs:
  - job_name: sovite
    authorization:
      credentials_file: /var/lib/sovite/admin.token
    static_configs:
      - targets: ["127.0.0.1:9025"]

[tracing]

OpenTelemetry traces of SMTP sessions and deliveries, sent with OTLP over HTTP (JSON) to a collector such as the OpenTelemetry Collector, Jaeger, or Grafana Tempo. See Sovite.Core.Tracing for the spans.

Clusters: [cluster]

Several Sovite servers can run as one cluster: they share their configuration, their rate limits, bans, and greylisting, keep copies of each other's queues, and deliver the mail of a node that stays down. Nodes talk over Partisan, not Distributed Erlang, on their own TCP port, with TLS 1.3 and mutual authentication. See Operations for setting one up.

[cluster]
enabled = true
node_name = "mx1@10.0.0.1"
address = "10.0.0.1"
seeds = ["mx2@10.0.0.2", "mx3@10.0.0.3"]
cert_file = "/etc/sovite/cluster/mx1.pem"
key_file = "/etc/sovite/cluster/mx1.key"
ca_file = "/etc/sovite/cluster/ca.pem"
shared_config = "/var/lib/sovite/cluster.toml"

All but seeds, join_interval, sync_interval, shared_config, queue_replicas, handover_after, and destination_affinity need a restart.

Rate limits shared by a cluster count by the wall clock, so keep the nodes' clocks in sync (NTP). Nodes with their own SQLite databases share greylist entries; nodes that share a PostgreSQL or MySQL database share every table already, which is the way to share domains, users, aliases, and the rest.

The shared configuration

With shared_config, the settings of that file come first, and those of the node's own file override them: tables are merged key by key, other values replaced. Keep in the node's file what is its own ([server], [[listener]], [cluster], [database], paths), and put the rest in the shared file. sovitectl cluster config push FILE sends a new version of it to every node; each checks it with its own file, stores it, and reloads. A node that comes back or joins later gets the newest version. The shared file cannot have a [cluster] table.

Tenants: [[tenant]]

Tenants are customers whose mail one server or cluster hosts, each with its own limits, DKIM keys, and IP pool.

[[tenant]]
name = "acme"
domains = ["acme.example"]
users = ["relay-acme"]
ip_pool = "acme"
messages = "10000/1d"
recipients = "50000/1d"
max_message_size = "10M"
max_recipients = 500

A message belongs to a tenant when the client logged in as one of its users, or with a login in one of its domains, or, for clients that logged in or are in smtp.trusted_networks, when the sender's domain is one of its domains. Mail from the internet belongs to no tenant.

The DKIM keys ([[dkim.key]]) of a tenant's domains sign only that tenant's mail, so one customer cannot sign as another. Tenant limits come on top of [rate_limit], and are shared by a cluster.

IP pools: [[ip_pool]]

The source addresses mail goes out from, with warm-up schedules and daily limits for new addresses. SMTP deliveries use the pool of their tenant, else delivery.ip_pool; the sender relays table comes first.

[[ip_pool]]
name = "shared"
overflow = "spare"

[[ip_pool.address]]
address = "192.0.2.10"
helo = "mta1.example.com"

[[ip_pool.address]]
address = "192.0.2.11"
helo = "mta2.example.com"
warmup_start = 2026-10-01
warmup = [50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000]
daily_limit = 100000

Each [[ip_pool.address]]:

Each connection picks one IPv4 and one IPv6 address with room left today (UTC), the one with the most room left as a share of its limit first. A message counts once for the address it went out from. Counts are kept in the database (ip_address_counts), and shown by sovitectl ip-pool status, the web UI, and the sovite_ip_pool_sent_today metric.

Starting the MTA

The :sovite OTP application starts the MTA only when the :start_mta application env is true:

• Production releases (MIX_ENV=prod) set it in config/runtime.exs.
• In development: SOVITE_START_MTA=1 SOVITE_CONFIG=./sovite.toml iex -S mix.
• When Sovite is a dependency of another project, the MTA never starts on its own. To embed it, add {Sovite.Core.Supervisor, config_path: "..."} to your supervision tree.