Trusted Interpreter

The trusted interpreter runs Sieve scripts invoked by the SMTP server. These scripts are created by the system administrator and are considered privileged. Stalwart compiles all defined Sieve scripts at start-up and executes them on demand through the Sieve runtime.

Configuration

Interpreter settings and resource limits are configured on the SieveSystemInterpreter singleton (found in the WebUI under Settings › Sieve › System Interpreter). The main fields are:

• defaultFromName: default name used in the From header of email notifications sent from a Sieve script. Default "'Automated Message'".
• defaultFromAddress: default address used in the From header of email notifications sent from a Sieve script. Default "'MAILER-DAEMON@' + system('domain')".
• defaultReturnPath: default return path applied to email notifications sent from a Sieve script.
• dkimSignDomain: domain whose DKIM signatures are applied to email notifications sent from a Sieve script. Default "system('domain')".
• messageIdHostname: local hostname used when generating the Message-Id header. When unset, the server hostname is used.
• noCapabilityCheck: when true, language extensions can be used without being declared through a require statement. Default true.

The dkimSignDomain expression resolves to a single domain name; all DKIM signatures associated with that domain are then applied to outgoing notifications. A domain can have one or multiple DKIM signatures associated through its DkimSignature records.

Limits

Resource limits protect the server from scripts that exceed reasonable bounds. The relevant fields on SieveSystemInterpreter are:

• maxRedirects: maximum number of redirect commands per script. Default 3.
• maxOutMessages: maximum number of outgoing messages a script may send. Default 5.
• maxReceivedHeaders: maximum number of Received headers allowed in a message. Default 50.
• maxCpuCycles: maximum number of instructions a script can execute. Default 1048576.
• maxNestedIncludes: maximum number of nested include instructions. Default 5.
• duplicateExpiry: default expiration time for identifiers stored by the duplicate extension. Default "7d".
• maxVarSize: maximum size of a variable, in bytes. Default 52428800.

Example

{
  "defaultFromName": {"else": "'Automated Message'"},
  "defaultFromAddress": {"else": "'[email protected]'"},
  "defaultReturnPath": {"else": "''"},
  "messageIdHostname": "mx.example.org",
  "dkimSignDomain": {"else": "system('domain')"},
  "maxRedirects": 3,
  "maxOutMessages": 5,
  "maxReceivedHeaders": 50,
  "maxCpuCycles": 10000,
  "maxNestedIncludes": 5,
  "duplicateExpiry": "7d"
}

Scripts

Trusted Sieve scripts are stored as SieveSystemScript records (found in the WebUI under Settings › Sieve › System Scripts). Each record carries a name, an optional description, an isActive flag, and the script body in contents.

A trusted script is invoked from an SMTP stage by setting the stage's script expression to the script's name. For example, the script field on MtaStageRcpt, MtaStageEhlo, or MtaStageData. Trusted scripts can also import each other using the include command.

For example, a system script that rejects messages from blocklisted HELO domains:

{
  "name": "script_one",
  "description": "Reject blocklisted HELO domains",
  "isActive": true,
  "contents": "require [\"variables\", \"extlists\", \"reject\"];\n\nif string :list \"${env.helo_domain}\" \"list/blocked-domains\" {\n    reject \"551 5.1.1 Your domain '${env.helo_domain}' has been blocklisted.\";\n}\n"
}

The contents field holds the full script text; loading the script body from an external file is not supported.