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.

[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

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

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

[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).

[log]

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.