Runtime settings

Some settings are too important to wait for a restart: a destination that has started deferring your mail, a flood of oversized messages, a tenant ready to enforce its MTA-STS policy. Those live in the server’s store rather than in the configuration file, and a running node picks up a change within seconds.

The file stays the floor. A node with nothing set in the store behaves exactly as its configuration file says; a setting in the store wins while it is there; remove it, and the file’s value comes back.

Documents and scopes

Settings are kept as one document per scope:

Some keys can only be set for the whole server; they are marked Server below. For the other keys, the value is looked up in this order, and the first one found is used:

1. The tenant’s document.
2. The whole server’s document.
3. The node’s configuration file, where the key has a counterpart there.
4. The built-in default.

Every document has a version. Each write increases it, keeps the previous version in the history, and writes an audit line with the document before and after.

Floors and locks

For some security controls, the operator can set a floor that every organisation must keep. An organisation’s own value is used only when it is at least as strict. The operator can also lock a control, so every organisation uses the operator’s value.

versealx-server admin security floor security.second_factor required
versealx-server admin security floor audit.keep_days 365
versealx-server admin security floor mdn.send inside --lock
versealx-server admin security floors
versealx-server admin security unfloor mdn.send

Wherever the server reads a floored setting for an organisation, a weaker or unset value is read as the floor. When the setting’s default is stricter than the floor, the default applies. An organisation that tries to save a weaker value is refused, and the error names the floor. A value it saved before the floor was set keeps working until the organisation changes it, but it is read as the floor. Through the API, the operator uses GET and PUT /api/v1/security/floors.

Floors for domains and people

An organisation can set floors of its own below the installation’s: for one of its domains, for all its people, or for the people of one domain. A domain’s administrators can set floors for their domain’s people. Each level is read under every floor above it, so the installation’s floors and locks win over the organisation’s, and the organisation’s over a domain’s.

These floors are taken only for the controls the server reads per domain or per person: security.second_factor, for domains and people, and mta_sts.mode, for domains, which is then the mode the domain publishes. A floor on any other control is refused, since nothing would hold it.

vsx admin security levels
vsx admin security floor-domain finance.example.com security.second_factor required
vsx admin security floor-domain finance.example.com mta_sts.mode enforce
vsx admin security floor-people security.second_factor required
vsx admin security floor-domain-people example.com security.second_factor required
vsx admin security unfloor-domain finance.example.com mta_sts.mode

A change under a floor is refused, naming the floor and who set it. A person whose floor requires a second step cannot remove their last one. The posture lists every floor with whom it is for and whether it holds: for MTA-STS, what the domain’s DNS last showed, and for a second step, how many people it covers still have none. A floor that does not hold is named in the drift alert. On the console, the organisation’s floors are on the Security posture card, and each domain’s page has a Security floors card, where the domain’s administrators set and remove the floors for its people. Through the API, they are GET and PUT /api/v1/tenants/<id>/security/floors, and PUT /api/v1/tenants/<id>/security/floors/<domain> for a domain.

Security posture

An organisation’s administrators and auditors can see how its controls stand against the Strict profile, including any floors the installation sets. Use the Security posture card on Settings, run versealx-server admin security posture, or call GET /api/v1/tenants/<id>/security/posture.

Strict asks for:

• a second step for everyone
• the strict leaked-password check
• passwords of at least 14 characters
• no self-service recovery
• a recent sign-in, within 10 minutes, before anything that can’t be undone
• a year of audit

The posture also checks what is actually true, not only what the settings say:

• every listener that serves TLS, connected to on the server itself the way a client would, serves at least TLS 1.2 and a certificate with at least 14 days left. A listener that couldn’t be reached is shown as not checked, never as passing;
• each of the organisation’s domains publishes DMARC at p=reject, as DNS last showed it;
• each domain publishes and serves MTA-STS in enforce mode;
• everyone has a second step;
• every administrator has a second step;
• every node refuses to send mail in the clear (BSI TR-03108 04-M);
• each domain’s MX hosts publish DANE TLSA records, in a signed zone, that match the certificate the server serves (05-M);
• each domain publishes a TLS reporting record with a report address (10-M);
• the server’s certificate comes from an issuer the operator lists in posture.trusted_issuers (12-R). With no list, this is not checked.

A check the server could not make, such as a zone that is not signed or a lookup that failed, is shown as not checked, never as passing. The domain checks use the server’s last DNS look at each domain, which it refreshes every few hours and whenever someone asks from the domain’s page. The people who have no second step are named, up to ten per check.

The operator can raise the listeners’ floor, for example to TLS 1.3 or 30 days, on the console’s Listeners’ TLS page under System, which also shows each listener as good, out of profile with why, or not checked, or with GET and PUT /api/v1/security/listener-tls. Each listener is checked hourly.

To be told when a control falls short, turn on the below-strict alert. For each setting short of Strict it says who set its value and when, and the settings version that did it, so you can see that change in the settings history and set it back; a setting nobody changed is marked as its default.

Exceptions

Sometimes a control can’t meet Strict for a while, for a good reason: shared terminals in a call centre that can’t take a second step until new ones arrive, say. An administrator can record an exception to that control, with the reason and the day it ends, at most a year away.

An exception is a record, not a switch. It changes no setting and no floor. While it stands:

• the posture and the security report show it beside the control, with who granted it and why;
• the below-strict alert lists the control as excepted until its day instead of short.

When the day passes, the control counts against Strict again, and the alert says so.

On the Security posture card, use Exceptions to grant one, and End to end one early. Or run:

vsx admin security except security.second_factor 2027-03-31 'the call centre terminals, until they are replaced'
vsx admin security unexcept security.second_factor

Over the API, PUT /api/v1/tenants/<id>/security/exceptions/<control> with {"reason": "…", "until": <Unix milliseconds>} grants one, and DELETE on the same path ends it. The control is a setting’s name, or one of dmarc-reject, mta-sts-enforce, second-step-everyone and second-step-administrators. Each change is recorded in the audit log. Only the organisation’s administrators can grant or end one.

Security report

An auditor, or a customer’s security questionnaire, often asks how the organisation stands against a framework. The security report prints the same controls under the clauses of one:

• NIS2: the cybersecurity measures of Article 21(2) of the NIS2 Directive, points (a) to (j);
• ISO 27001: the ISO/IEC 27001:2022 Annex A controls that the organisation’s settings serve, such as secure authentication (A.8.5), logging (A.8.15) and use of cryptography (A.8.24);
• BSI TR-03108: the 16 requirements of the BSI’s Secure E-Mail Transport guideline, version 2.0, each under its own title with its MUST or SHOULD. The server checks inbound MTA-STS (TR-03108-07-R) itself. Each of the others is listed as not checked by the server, with the reason, such as the listeners’ TLS, DANE or the certificates’ issuer, so you know what to show some other way.

Under each clause the report lists the controls that serve it, each with its value now or what its check found, and how many of those Strict asks about meet it. For NIS2 it also names the points that no setting of the organisation shows, such as business continuity, so you know to cover them in your own documents. The report shows how your controls stand. It does not say that you meet a framework.

Use the Security report card on Settings, which shows both frameworks, or run these with the vsx shell function from the Quick start:

vsx admin security report nis2
vsx admin security report iso-27001
vsx admin security report bsi-tr-03108

Over the API, call GET /api/v1/tenants/<id>/security/report?framework=nis2, framework=iso-27001 or framework=bsi-tr-03108. Administrators and auditors can read it.

A signed report

A report can be handed to somebody who checks it without trusting whoever passed it on. Download signed JSON on the card, --signed, or &signed=true gives the report with when it was made, for which organisation, against which framework and by which node, signed with the server’s own signing key:

vsx admin security report nis2 --signed report.json
vsx admin security verify-report report.json

verify-report checks the signature against this server’s key. Anybody else can check it too: the file holds the signature as a JWS and the address of the server’s published keys (/.well-known/jwks.json). Its header names the key, and the signature is Ed25519 over the first two parts. A report and a sign-in token can never be taken for each other.

Every setting’s default is its strictest value: a setting an organisation has not chosen reads as the strictest, and its administrators can change it within the installation’s floors. Two are the exceptions, each for a reason: mta_sts.mode defaults to testing, since enforce would stop mail from senders the moment a certificate goes wrong, and approvals are required by default only once an organisation has two administrators, since one cannot approve their own requests.

An organisation that had left a setting unset when these defaults became the strictest now reads it as the strictest. versealx-server doctor names each such organisation and the settings that changed for it, and so does its security posture (unsetNowStricter); setting the old value back keeps things as they were.

Every setting

A key that is not in this table is refused. In the outbound.destination keys, <domain> is a destination written as the file writes one — gmail.com, or .google.com (with its leading dot) for everything under a domain — using the ASCII form of the name and at least two labels.

When a change takes effect

Reading settings

These examples use the vsx shell function from the Quick start, which runs versealx-server as the service user with the configuration path.

vsx admin get tenants/0/settings

{
  "by": "operator 0/-",
  "settings": {
    "limits.message_size": 10485760,
    "outbound.destination.outlook.com.messages_per_minute": 120
  },
  "updated_at": 1789387200000,
  "version": 3
}

versealx-server explain prints what the configuration file says; admin get tenants/0/settings prints what the store says over it.

Changing some settings

PATCH changes the keys you give and leaves the rest. A key set to null is removed.

# Lower the message size ceiling for the whole server
vsx admin patch tenants/0/settings limits.message_size=10485760

# Remove it again, so the file's value applies
vsx admin patch tenants/0/settings limits.message_size=null

# Slow one destination down during an incident
vsx admin patch tenants/0/settings outbound.destination.outlook.com.messages_per_minute=120

# Everything under google.com: note the two dots
vsx admin patch tenants/0/settings outbound.destination..google.com.connections=4

# Enforce MTA-STS for tenant 1's domains
vsx admin patch tenants/1/settings mta_sts.mode=enforce

The answer is the new document. A patch that changes nothing returns the current document and writes nothing.

To make sure nobody else changed the document since you read it, include the version you read. The write is refused with 409 Conflict if it is no longer current:

vsx admin patch tenants/1/settings mta_sts.mode=enforce version=3

Replacing the whole document

PUT replaces the document with the one you send, which is how you import an exported document or put back an earlier version:

vsx admin put tenants/1/settings 'settings={"mta_sts.mode":"enforce","mta_sts.max_age":1209600}' version=3

Keys you leave out of settings are removed.

Exporting and importing

1. Export: vsx admin get tenants/1/settings > tenant-1-settings.json.
2. Keep the file in version control if you like.
3. Import: take the settings object from the file and send it with PUT, as above. Include version to avoid overwriting a change made in the meantime.

History

vsx admin get tenants/1/settings/history limit=5
vsx admin get tenants/1/settings/history/2

The first lists versions newest first, each with version, updated_at and by — 20 unless you give limit, at most 200. The second returns one earlier version whole, ready to PUT back.

Errors