Configuration

A node’s configuration file holds what the node needs before it can open its store: its name, its roles, where its data lives, its certificate, its listeners, and a few ceilings that belong to the machine. Everything else — domains, accounts, per-tenant policies, and ceilings you change during an incident — lives in the store and is changed through the API. See Runtime settings for those.

The file

A key the server does not know is refused rather than ignored in the top level and in the [limits], [outbound], [mta_sts], [admin], [filter], [dns] and [telemetry] tables, so a typing mistake cannot silently turn a setting off.

Values from the environment

Three values may name an environment variable as ${NAME}, which is replaced with the variable’s value when the node starts:

A variable that is not set becomes an empty string. An empty node stops the node from starting.

Minimal example

This is the file init writes for --hostname mail.example.com --domain example.com:

node = "mail.example.com"
hostname = "mail.example.com"

[store]
kind = "sqlite"
path = "/var/lib/versealx-server/store.db"

[blobs]
kind = "filesystem"
path = "/var/lib/versealx-server/blobs"

[keys]
kind = "file"
path = "/var/lib/versealx-server/kek"

[tls]
kind = "files"
certificate = "/var/lib/versealx-server/tls/certificate.pem"
key = "/var/lib/versealx-server/tls/key.pem"

[admin]
socket = "/var/lib/versealx-server/admin.sock"

[mta_sts]
mode = "testing"

With --relay, it also writes an [outbound.relay] table.

Top-level keys

Roles

roles = ["mx", "submission", "relay", "filter", "store", "deliver", "dav", "admin", "serve"]

Every accepted message goes on a queue that the relay role works through: it delivers to other servers itself and hands mail for local recipients to the deliver role. So at least one node sharing the store must run relay and at least one must run deliver, or accepted mail waits. A node with kind = "acme" needs serve.

[store]

Where the metadata lives: the directory, mailboxes, message index, queues, settings, audit log and keys.

SQLite

[store]
kind = "sqlite"
path = "/var/lib/versealx-server/store.db"

PostgreSQL

[store]
kind = "postgres"
url = "${VERSEALX_STORE_URL}"

[blobs]

Where message bodies live. Every message is encrypted with its tenant’s key before it is written.

A directory

[blobs]
kind = "filesystem"
path = "/var/lib/versealx-server/blobs"

An S3-compatible bucket

[blobs]
kind = "s3"
bucket = "mail-blobs"
endpoint = "https://s3.storage.example.net"
region = "eu-1"

The access key and secret come from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. If either is missing the node does not start, with blobs: AWS_ACCESS_KEY_ID is not set or blobs: AWS_SECRET_ACCESS_KEY is not set.

[organisation_blobs]

How a node reaches the places organisations keep their mail in apart from its own, set with tenant storage. Which organisation is where is kept in the store, so every node needs the same settings here.

A node that cannot reach an organisation’s place, for example because its credentials are not set, does not start and says which organisation’s place it could not open, so no mail is written anywhere else.

[keys]

Where the key-encryption key comes from. Each tenant’s data key is stored wrapped by this key, and each message is encrypted with its tenant’s data key.

[keys]
kind = "file"
path = "/var/lib/versealx-server/kek"

If the file does not exist when the node starts, the node generates a new key, writes it with mode 0600, and logs generated a new key-encryption key; back it up. The node refuses to use a file that its group or other users can read, with keys: bad key material: <path> is readable by others (mode 640); chmod 600 it.

A key in AWS KMS

[keys]
kind = "kms"
key_id = "arn:aws:kms:eu-west-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"

With a KMS, the key-encryption key is never on disk as itself. The store keeps the KMS’s ciphertext of it, and each node asks the KMS to unwrap it when it starts, so a disk, a backup or a copy of the store holds nothing that opens anything without the KMS.

The first node to start on an empty store has the KMS make the key, and every node after it unwraps that one. A node the KMS refuses — access denied, the key disabled, or a ciphertext wrapped by another key — does not start, and says why. Every call carries the encryption context versealx-server: key-encryption-key, so each unwrap is recorded under that name in your account’s KMS audit trail.

Credentials come from the environment (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, with AWS_SESSION_TOKEN for temporary ones), then a container’s task role, then the instance’s role. The key’s policy must allow the node kms:GenerateDataKey and kms:Decrypt, and kms:Encrypt for keys wrap.

A node that has run on a key file moves to a KMS with keys wrap: set [keys] as above, stop the nodes, and run versealx-server keys wrap --file <the old key file>. It checks the file’s key against the store first and changes nothing if it is not this store’s.

[tls]

The certificate every listener uses. TLS certificates explains both kinds in full.

Certificate files

[tls]
kind = "files"
certificate = "/var/lib/versealx-server/tls/certificate.pem"
key = "/var/lib/versealx-server/tls/key.pem"

ACME

[tls]
kind = "acme"
names = ["mail.example.com", "mta-sts.example.com"]
contact = "postmaster@example.com"

[listeners]

Every listener has a default address. Add a [listeners.<name>] table only to change one.

[listeners.mx]
bind = "0.0.0.0:25"
proxy_protocol = true

[listeners.imaps]
bind = "[2001:db8::10]:993"

Listeners whose role the node does not run are not started. jmap, dav, admin and serve on the same address share one HTTPS listener; give them different addresses and each gets its own.

The ports mail apps are told about in autoconfig and Autodiscover follow the listeners, so moving imaps to another port moves it there too. The SRV records versealx-server dns prints always use the default ports; if you move a listener, change the SRV record you publish.

check refuses a table for a listener that does not exist, and a table for a listener whose role the node does not run.

Connection ceilings

The mail listeners — mx, submission, submissions, imap, imaps, pop3, pop3s and managesieve — limit how many connections one address and one network may hold at once, and can limit how fast they open them. A network is an IPv4 /24 or an IPv6 /48; an IPv4 client that reaches an IPv6 socket counts as its IPv4 address. Behind a load balancer with proxy_protocol, the client’s own address is the one counted.

[listeners.mx]
bind = "0.0.0.0:25"
max_per_network = 100
rate_per_ip = "30/minute"
rate_per_network = "300/minute"
exempt = ["192.0.2.0/24", "2001:db8:10::/48"]

A rate lets a client open as many connections as it allows at once after a quiet spell, and then one more each time its share of the period has passed: at "60/minute", one a second. A connection over any ceiling is told why before anything is read from it, in the protocol’s own words, and closed. For example:

The words name the address or the network, and a rate adds ; try again later. vsx_sessions_closed_total counts the refusals by listener and reason: per-address, per-network, address-rate or network-rate. versealx-server explain prints the ceilings each listener runs with.

Rates are off unless you set them. On port 25 a rate too low for a large sender’s burst asks its mail to come back later, so set them from what your logs show.

check refuses a ceiling of 0, a rate or an exempt entry it cannot read, and ceilings on jmap, dav, serve, admin or acme, which share their socket and keep none.

[limits]

Ceilings on one message, and on everything arriving at once. message_size and recipients can only be lowered: the built-in numbers are what the server promises in its SMTP greeting.

[limits]
message_size = 10485760
recipients = 50

The runtime settings limits.message_size and limits.recipients override these without a restart, and removing them brings the file’s numbers back. A connection keeps the numbers it was told when it connected.

[outbound]

How this node delivers mail: how many deliveries run at once, how hard each destination is pushed, which relay to use, and which certificates to trust.

[outbound]
concurrency = 16

[outbound.destinations."gmail.com"]
connections = 16
messages_per_minute = 3000

[outbound.destinations.".partner.example"]
connections = 1
messages_per_minute = 30

A destination key is a domain, such as "gmail.com", or a domain with a leading dot, such as ".google.com", for everything under it. The most specific key wins.

Destination ceilings

Used in [outbound.default] and [outbound.destinations."<domain>"].

A key you leave out keeps what the built-in table, or [outbound.default], says for that destination.

Built-in ceilings:

These sit well inside what those providers publish, so a new server is paced rather than refused. Raise them once your server has a reputation. The runtime settings outbound.destination.<domain>.* override the file for one destination without a restart; see Runtime settings.

[outbound.relay]

[outbound.relay]
host = "smtp.relay.example.net"
port = 587
tls = "required"
user = "postmaster@example.com"
password = "${VERSEALX_RELAY_PASSWORD}"

The node authenticates with AUTH PLAIN, falling back to LOGIN. It never sends the credentials over an unencrypted connection, whatever the relay offers, and never writes the password to a log.

[outbound.transport]

[outbound.transport.".corp.example"]
host = "hub.corp.example"
port = 25
tls = "opportunistic"

Takes the same keys as [outbound.relay]. The key is a domain, or a domain with a leading dot for everything under it.

The route for a message is chosen in this order:

1. A local domain: delivered into mailboxes on this server.
2. A matching [outbound.transport] entry.
3. [outbound.relay], when there is one.
4. The recipient domain’s own MX.

The set of local domains is refreshed every second, so a domain added through the API is delivered locally at once.

[outbound.premises]

[outbound.premises.onprem]
host = "mail.onprem.example"
port = 25
tls = "required"
certificate = "/etc/versealx/cloud.pem"
key = "/etc/versealx/cloud.key"

The other premises of a domain whose mailboxes are in two places, by the name the directory gives them: mail for somebody whose mailbox is there goes to that premises’ MX rather than being filed here. Takes the same keys as [outbound.relay]. Its site is where the mailboxes there rest, checked against each organisation’s residency. A name is letters, digits and hyphens. See One domain, mailboxes in two places.

[[relay_domains]]

Domains this node takes mail for and passes on, because their mailboxes are elsewhere: an edge in front of another server, or a backup MX. Repeat the table for each domain. See Edges and two premises.

[edge]

The edge in front of this node, whose checks the mail it passes on keeps. See Trusting the edge in front of you.

[[relay_devices]]

Devices that send without signing in: printers, scanners, appliances that cannot hold a password. Repeat the table for each device. See Devices that cannot sign in.

[[relay_devices]]
name = "scanner-floor-2"
from = ["192.0.2.40", "192.0.2.48/29"]
sender = "scanner@example.com"
recipients = ["@example.com", "facilities@example.net"]

A device is never counted as guessing at addresses: a refusal it meets is about its own configuration.

[mta_sts]

The MTA-STS policy this node publishes for a verified domain whose tenant has not set one in the runtime settings.

[mta_sts]
mode = "testing"
mx = ["mx2.example.com"]

The policy’s max_age is a week unless the runtime setting mta_sts.max_age says otherwise.

[admin]

[admin]
socket = "/var/lib/versealx-server/admin.sock"
trace_days = 30

[passwords]

Whether this node checks new passwords against the ones known to have leaked in data breaches, and whom it asks. Each organisation decides whether leaked passwords are refused, with the passwords.refuse_breached runtime setting; this table decides whether the node can ask at all. See Passwords that have leaked.

[passwords]
breach_check = true
breach_api = "https://api.pwnedpasswords.com/range/"
breach_timeout_ms = 3000

Only the first five characters of a password’s SHA-1 hash are ever sent, never the password. versealx-server doctor asks the service once and reports it as leaked-password check, with how long it took to answer.

[filter]

External helpers for the filter pipeline. The built-in stages — authentication results and the attachment policy — always run; this table adds a virus scanner and milters after them. See Spam and malware filtering.

[filter]
budget_seconds = 15

[filter.clamav]
socket = "/run/clamav/clamd.ctl"
on_unavailable = "accept"

[[filter.milters]]
name = "rspamd"
socket = "127.0.0.1:11332"
timeout_seconds = 10

[filter.clamav]

[[filter.blocklists]]

Repeat the table for each list. See DNS blocklists.

A zone may be named once for each kind.

[filter.greylist]

See Greylisting. Unset, nobody is greylisted.

[filter.arc]

See Mailing lists and forwarders you trust.

[[filter.milters]]

Repeat the table for each milter. They are asked in the order written, after the scanner.

[bimi]

Checks the BIMI logos of mail you receive. See Logos on mail you receive. Without this table, no logo is checked.

A logo whose certificate chains to none of the trusted roots is not shown.

[smime]

The roots an S/MIME signer’s certificate is chained to (see S/MIME signatures). Without this table, the roots Mozilla trusts for email are used.

versealx-server trust roots smime lists the roots in force, and doctor warns a year before one expires.

[rdap]

The list of which registry answers for which domain ending, used to learn how new a link’s domain is (see How new a link’s domain is). Without this table, the copy of IANA’s list that ships with the server is used.

doctor says when the file does not read, and warns when the list in use was published more than 90 days ago.

[lookalike_watch]

How the server finds look-alikes of each organisation’s domains before their first message (see Look-alike domains found before their first message).

[lookalike_watch]
logs = ["https://ct.googleapis.com/logs/us1/argon2026h2/"]
entries_per_hour = 20000

Each certificate in a log is about 6 KB, so the default reading is about 120 MB an hour for each log; check says what yours comes to. The newest entries are read first: a log is read from where it stands when it is first named, and one that runs more than a day ahead of the reading is caught up to its newest hour, so what is found is always recent.

[backup]

Daily backups of the running node, sealed with a key of their own. See Daily backups.

[backup]
to = "/var/backups/versealx"
key_file = "/etc/versealx-server/backup.key"
at = "02:00"

check refuses a to that is not absolute, a to with no key_file, an at that is not a time of day, and a keep_daily of 0.

[dr]

This site’s part in disaster recovery; see A standby site.

[dr.failover]

Automatic failover by a witness. See Taking over automatically.

[dr.dns]

The record mail is pointed at, so that a promotion says what to change, or changes it. See How mail finds the site that leads.

[dr.dns]
name = "mx.example.com"
address = "198.51.100.20"

[cluster]

This node’s cluster. See Nodes of a cluster.

[links]

Where the server keeps each link’s files when it renews them; see Linking the two sides by code.

[migrations]

Which old servers the migrations your organisations’ administrators start may reach; see Moving everybody at once.

[push]

Where the server may send phone pushes; see Push to phones.

[storage]

What the node does as its disks fill. See When a disk fills.

[storage]
reserve_percent = 95

[integrity]

The integrity scrub, which reads all stored mail back on a schedule. See Checking stored mail.

[integrity]
scrub = true
scrub_days = 30
standby_blobs = "s3://mail-standby"
standby_region = "eu-west-1"

[confinement]

At start, the node takes away from itself what it does not need. On Linux, with Landlock, it can then read and write only the files and directories its configuration names, bind only its listeners’ ports, and run no other program, so a process somebody took over cannot read the rest of the machine.

[confinement]
landlock = "best-effort"

Landlock needs Linux 5.13 or later, with landlock among the kernel’s security modules (the lsm= kernel parameter). versealx-server doctor tries the node’s own rules on a thread of its own and reports what the kernel enforces, as confinement.

[dns]

The resolver comes from /etc/resolv.conf and always validates DNSSEC against the root trust anchors.

[dns]
trust_anchors = ["/etc/versealx-server/corp.example.dnskey"]

Put the zone’s whole DNSKEY set in the file, not only its key-signing key; with the key-signing key alone, nothing under the zone validates. Nothing else may answer for the zone: a resolver in front that answers some of its names from its own table makes those answers look forged. check refuses a file that cannot be read or holds no DNSKEY record.

[telemetry]

[telemetry]
metrics_bind = "127.0.0.1:9187"

See Monitoring.

More examples

A node that sends through a relay

node = "mail-1"
hostname = "mail.example.com"
roles = ["mx", "submission", "relay", "filter", "store", "deliver", "serve", "admin"]

[store]
kind = "sqlite"
path = "/var/lib/versealx-server/store.db"

[blobs]
kind = "filesystem"
path = "/var/lib/versealx-server/blobs"

[keys]
kind = "file"
path = "/var/lib/versealx-server/kek"

[tls]
kind = "acme"
names = ["mail.example.com", "autoconfig.example.com", "mta-sts.example.com"]
contact = "postmaster@example.com"

[admin]
socket = "/var/lib/versealx-server/admin.sock"

[outbound.relay]
host = "smtp.relay.example.net"
port = 587
tls = "required"
user = "postmaster@example.com"
password = "${VERSEALX_RELAY_PASSWORD}"

[mta_sts]
mode = "testing"

For the packaged service, put VERSEALX_RELAY_PASSWORD in a systemd drop-in, for example with sudo systemctl edit versealx-server and an Environment= line, rather than in this file.

An inbound edge node behind a load balancer

node = "${HOSTNAME}"
hostname = "mx1.example.com"
roles = ["mx", "relay", "filter"]

[store]
kind = "postgres"
url = "${VERSEALX_STORE_URL}"

[blobs]
kind = "s3"
bucket = "mail-blobs"
endpoint = "https://s3.storage.example.net"

[keys]
kind = "file"
path = "/var/lib/versealx-server/kek"

[tls]
kind = "files"
certificate = "/etc/versealx-server/chain.pem"
key = "/etc/versealx-server/key.pem"

[listeners.mx]
bind = "0.0.0.0:25"
proxy_protocol = true

[telemetry]
metrics_bind = "192.0.2.5:9187"

Every node sharing a store must use the same key file.

Messages from check

check and run print versealx-server: refusing to start: followed by one of these.

Problems check cannot see, such as a missing certificate file or an unreadable key file, stop run instead. Troubleshooting lists those messages.