Dovecot Pro
Search K

Appearance

Sieve Plugin (sieve) ​

Configuration ​

To use Sieve, you will first need to make sure you are using Dovecot LDA or LMTP Server for delivering incoming mail to users' mailboxes.

Then, you need to enable the Sieve plugin in your configuration:

protocol lda {
  mail_plugins = $mail_plugins sieve
}

protocol lmtp {
  mail_plugins = $mail_plugins sieve
}

Script Locations ​

The Sieve interpreter can retrieve Sieve scripts from several types of locations.

The default file location type is a directory containing one or more Sieve script files with a symlink pointing to the active one.

More complex setups can use other location types such as LDAP or dict to fetch Sieve scripts from remote databases.

All settings that specify the location of one or more Sieve scripts accept the following syntax:

<setting> = [<type>:]path[;<option>[=<value>][;...]]

If <type> is omitted, the script location type is file and the location is interpreted as a local filesystem path pointing to a Sieve script file or directory.

Common Settings ​

All location types support the following settings:

name=<script-name> ​

Set the name of the Sieve script that this location points to. If the name of the Sieve script is not contained in the location path and the location of a single script is specified, this option is required (e.g. for dict locations that must point to a particular script).

If the name of the script is contained in the location path, the value of the name option overrides the name retrieved from the location. If the Sieve interpreter explicitly queries for a specific name (e.g. to let the Sieve Sieve include extension retrieve a script from the sieve_global), this option has no effect.

bindir=<dirpath> ​

Points to the directory where the compiled binaries for this script location are stored. This directory is created automatically if possible.

If this option is omitted, the behavior depends on the location type.

Don't specify the same directory for different script locations, as this will result in undefined behavior. Multiple mail users can share a single script directory if the script location is the same and all users share the same system credentials (uid, gid).

File ​

The file location is used to retrieve Sieve scripts from the file system. This is the default type if the type specifier is omitted from the location specification.

The location can either point to a directory or to a regular file. If the location points to a directory, a script called name is retrieved by reading a file from that directory with the file name name.sieve.

When this location type is involved in a sieve_before or sieve_after script sequence, and the location points to a directory, all files in that directory with a .sieve extension are part of the sequence. The sequence order of the scripts in that directory is determined by the file names, using a normal 8bit per-character comparison.

Unless overridden using the ;bindir=<path> location option, compiled binaries for scripts retrieved from the file location type are by default stored in the same directory as where the script file was found if possible.

Configuration ​

The script location syntax is specified as follows:

location = file:<path>[;<option>[=<value>][;...]]

The location <path> is a file system path pointing to a directory containing one or more script files with names structured as <script-name>.sieve with the active option (default ~/.dovecot.sieve) specifying a symlink to the one that will be used, or without the active option specified, it may be a script file instead of a directory.

Settings ​

This location supports all settings described in Common Settings.

bindir ​

If the bindir setting is omitted, the binary is stored in the same directory as where the script file was found, if possible

active=<path> ​

When ManageSieve server is used, one script in the storage can be active; i.e., evaluated at delivery.

For the file location type, the active script in the storage directory is pointed to by a symbolic link.

This option configures where this symbolic link is located. If the file location path points to a regular file, this setting has no effect (and ManageSieve cannot be used).

Example ​
plugin {
   ...
   sieve = file:~/sieve;active=~/.dovecot.sieve
   sieve_default = file:/var/lib/dovecot/;name=default
}

Dict ​

To retrieve a Sieve script from a dictionary database, two lookups are performed.

First, the name of the Sieve script is queried from the dict path /priv/sieve/name/<name>. If the Sieve script exists, this yields a data ID which in turn points to the actual script text. The script text is subsequently queried from the dict path /priv/sieve/data/<dict-id>.

The second query is only necessary when no compiled binary is available or when the script has changed and needs to be recompiled. The data ID is used to detect changes in the dict's underlying database. Changing a Sieve script in the database must be done by first making a new script data item with a new data ID. Then, the mapping from name to data ID must be changed to point to the new script text, thereby changing the data ID returned from the name lookup, i.e. the first query mentioned above. Script binaries compiled from Sieve scripts contained in a dict database record the data ID. While the data ID contained in the binary is identical to the one returned from the dict lookup, the binary is assumed up-to-date. When the returned data ID is different, the new script text is retrieved using the second query and compiled into a new binary containing the updated data ID.

Configuration ​

The script location syntax is specified as follows:

sieve = dict:<dict-uri>[;<option>[=<value>][;...]]

The <dict-uri> path is a Dovecot dict uri.

If the name of the Script is left unspecified and is not otherwise provided by the Sieve interpreter, the name defaults to default.

Settings ​

This location supports all settings described in Common Settings.

bindir ​

By default, compiled binaries are not stored at all for Sieve scripts retrieved from a dict database. Thus, the Sieve binaries will be compiled each time they are called.

To improve performance, this setting should be specified to cache the compiled binaries on the local filesystem. For Example:

sieve = dict:file:/etc/dovecot/sieve.dict;name=keep;bindir=~/.sieve-bin
# or
#sieve = dict:file:/etc/dovecot/sieve.dict;name=keep;bindir=/var/sieve-scripts/%u

Note

Sieve uses the ID number as its cache index and to detect the need to compile. Therefore, if a script is changed, then its ID must also be changed for it to be reloaded.

user=<username> ​

Overrides the user name used for the dict lookup. Normally, the name of the user running the Sieve interpreter is used.

Examples ​
Flat File Backend ​

To retrieve the Sieve script named "keep" from the dict file /etc/dovecot/sieve.dict:

# Only the "keep" script will be used.
sieve = dict:file:/etc/dovecot/sieve.dict;name=keep
priv/sieve/name/keep
1
priv/sieve/name/discard
2
priv/sieve/data/1
keep;
priv/sieve/data/2
discard;

A more advanced example using the same config as above: notify an external email address when new mail has arrived.

Note that the script all needs to be on one line.

priv/sieve/name/notify
5
priv/sieve/data/5
require ["enotify", "variables"]; if header :matches "From" "*" { set "from" "${1}";} notify :importance "3" :message "New email from ${from}" "mailto:other@domain.com?body=New%20email%20has%20arrived.";
Using a SQL backend ​

For greater flexibility, it's possible to use a SQL backend for your dict scripts.

First, set up a configuration file (such as /etc/dovecot/dict-sieve-sql.conf) with your database configuration. Next, create a dict proxy service (/etc/dovecot/dovecot.conf). Finally, configure Sieve to check the dict to lookup up a script called "active" in the database:

# The database connection params
connect = host=localhost dbname=dovecot user=dovecot password=password

# The name mapping that yields the ID of the Sieve script
map {
  # The name of the script, as per the "sieve" config parameter
  pattern = priv/sieve/name/$script_name

  # The database table
  table = user_sieve_scripts

  # The field in the table to query on
  username_field = username

  # The field which contains the return value of the script ID
  value_field = id

  fields {
	# FIXME: The other database field to query?
    script_name = $script_name
  }
}

# The name mapping that yields the script content from ID
map {
  # The ID, obtained from above
  pattern = priv/sieve/data/$id

  # The database table
  table = user_sieve_scripts

  # The field in the table to query
  username_field = username

  # The field which contains the script
  value_field = script_data

  fields {
	# FIXME: The other database field to query?
    id = $id
  }
}
# dict proxy service
dict {
  sieve = pgsql:/etc/dovecot/dict-sieve-sql.conf.ext
}

# dict lookup
plugin {
  sieve = dict:proxy::sieve;name=active
}

As with the flat file, the database query will need to return the Sieve script all in one line, otherwise the subsequent lines will be ignored.

Note

You might need to configure the dict proxy permissions.

LDAP ​

The ldap location is used to retrieve Sieve scripts from an LDAP database. To retrieve a Sieve script from the LDAP database, at most two lookups are performed.

First, the LDAP entry containing the Sieve script is searched using the specified LDAP search filter. If the LDAP entry changed since it was last retrieved (or it was never retrieved before), the attribute containing the actual Sieve script is retrieved in a second lookup. In the first lookup, a special attribute is read and checked for changes. Usually, this is the modifyTimestamp attribute, but an alternative can be configured.

Depending on how Pigeonhole was configured and compiled (refer to INSTALL file for more information), LDAP support may only be available when a plugin called sieve_storage_ldap is loaded.

Configuration ​

If support for the ldap location type is compiled as a plugin, it needs to be added to the sieve_plugins setting before it can be used, e.g.:

sieve_plugins = sieve_storage_ldap

The ldap script location syntax is specified as follows:

location = ldap:<config-file>[;<option>[=<value>][;...]]

<config-file> is a filesystem path that points to a configuration file containing the actual configuration for this ldap script location.

If the name of the Script is left unspecified and not otherwise provided by the Sieve interpreter, the name defaults to default.

Settings ​

This location supports all settings described in Common Settings.

bindir ​

By default, compiled binaries are not stored at all for Sieve scripts retrieved from LDAP. Thus, the Sieve binaries will be compiled each time they are called.

To improve performance, this setting should be specified to cache the compiled binaries on the local filesystem. For Example:

sieve = ldap:/etc/dovecot/sieve.ldap;name=keep;bindir=~/.sieve-bin
# or
#sieve = ldap:/etc/dovecot/sieve.ldap;name=keep;bindir=/var/sieve-scripts/%u

Note

Sieve uses the ID number as its cache index and to detect the need to compile. Therefore, if a script is changed, then its ID must also be changed for it to be reloaded.

user=<username> ​

Overrides the user name used for the lookup. Normally, the name of the user running the Sieve interpreter is used.

LDAP Settings ​

The configuration file is based on the LDAP authentication. These parameters are specific to the Sieve ldap configuration:

sieve_ldap_filter ​
  • Default: (&(objectClass=posixAccount)(uid=%u))
  • Values: string

The LDAP search filter that is used to find the entry containing the Sieve script.

These variables can be used:

VariableLong NameDescription
%u%{user}username
%n%{username}user part in user@domain, same as %u if there's no domain
%d%domain part in user@domain, empty if user there's no domain
%{home}user's home directory
%{name}name of the Sieve script
sieve_ldap_script_attr ​
  • Default: mailSieveRuleSource
  • Values: string

The name of the attribute containing the Sieve script.

sieve_ldap_mod_attr ​
  • Default: modifyTimestamp
  • Values: string

The name of the attribute used to detect modifications to the LDAP entry.

Example ​
plugin {
  sieve = ldap:/etc/dovecot/sieve-ldap.conf;bindir=~/.sieve-bin/
}
# This file needs to be accessible by the Sieve interpreter running in LDA/LMTP.
# This requires access by the mail user. Don't use privileged LDAP credentials
# here as these may likely leak. Only search and read access is required.

# Space separated list of LDAP hosts to use. host:port is allowed too.
hosts = localhost

# Distinguished Name - the username used to login to the LDAP server.
# Leave it commented out to bind anonymously.
dn = cn=sieve,ou=Programs,dc=example,dc=org

# Password for LDAP server, if dn is specified.
dnpass = secret

# Simple binding.
sasl_bind = no

# No TLS
tls = no

# LDAP library debug level as specified by LDAP_DEBUG_* in ldap_log.h.
# -1 = everything. You may need to recompile OpenLDAP with debugging enabled
# to get enough output.
debug_level = 0

# LDAP protocol version to use. Likely 2 or 3.
ldap_version = 3

# LDAP base
base = dc=mail,dc=example,dc=org

# Dereference: never, searching, finding, always
deref = never

# Search scope: base, onelevel, subtree
scope = subtree

# Filter for user lookup. Some variables can be used:
#   %u      - username
#   %n      - user part in user@domain, same as %u if there's no domain
#   %d      - domain part in user@domain, empty if there's no domain
#   %{name} - name of the Sieve script
sieve_ldap_filter = (&(objectClass=posixAccount)(uid=%u))

# Attribute containing the Sieve script
sieve_ldap_script_attr = mailSieveRuleSource

# Attribute used for modification tracking
sieve_ldap_mod_attr = modifyTimestamp

Settings ​

managesieve_client_workarounds

Default[None]
Valuestring
Advanced Setting; this should not normally be changed.

Enables various workarounds for ManageSieve clients. Currently there are none.

managesieve_implementation_string

DefaultDovecot Pigeonhole
Valuestring
Advanced Setting; this should not normally be changed.

Sets the ManageSieve implementation string returned by the IMPLEMENTATION capability.

managesieve_logout_format

Defaultbytes=%i/%o
Valuestring

Specifies the string pattern used to compose the logout message of an authenticated session. The following substitutions are available:

Variable Substitution
%i Total number of bytes read from client.
%o Total number of bytes sent to client.

managesieve_max_compile_errors

Default5
Valueunsigned integer
Advanced Setting; this should not normally be changed.

The maximum number of compile errors that are returned to the client upon script upload or script verification.

managesieve_max_line_length

Default65536
Valueunsigned integer
Advanced Setting; this should not normally be changed.

The maximum ManageSieve command line length in bytes.

Since long command lines are very unlikely with ManageSieve, changing this will generally not be useful.

managesieve_notify_capability

Default<dynamically determined>
Valuestring
Advanced Setting; this should not normally be changed.

NOTIFY capabilities reported by the ManageSieve service before authentication.

If left unassigned, these will be assigned dynamically according to what the Sieve interpreter supports by default (after login this may differ depending on the authenticated user).

managesieve_sieve_capability

Defaultfileinto reject envelope encoded-character vacation subaddress comparator-i;ascii-numeric relational regex imap4flags copy include variables body enotify environment mailbox date index ihave duplicate mime foreverypart extracttext
Valuestring
Advanced Setting; this should not normally be changed.

SIEVE capabilities reported by the ManageSieve service before authentication.

If left unassigned, these will be assigned dynamically according to what the Sieve interpreter supports by default (after login this may differ depending on the authenticated user).

recipient_delimiter

Default+
Valuestring

The separator between the :user and :detail address parts.

sieve

Defaultfile:~/sieve;active=~/.dovecot.sieve
Valuestring
See Also

The location of the user's main Sieve script or script storage.

The LDA Sieve plugin uses this to find the active script for Sieve filtering at delivery.

The Sieve include extension uses this location for retrieving :personal scripts.

This location is also where the ManageSieve service will store the user's scripts, if supported by the location type.

For the file location type, the location will then be the path to the storage directory for all the user's personal Sieve scripts.

ManageSieve maintains a symbolic link pointing to the currently active script (the script executed at delivery). The location of this symbolic link can be configured using the ;active=<path> option.

sieve_after

Default[None]
Valuestring

This setting can be specified multiple times by adding a number after the setting name, such as sieve_after2 and so on.

Location of scripts that need to be executed after the user's personal script.

If a Sieve file storage location location path points to a directory, all the Sieve scripts contained therein (with the proper .sieve extension) are executed. The order of execution within that directory is determined by the file names, using a normal 8bit per-character comparison.

Multiple script locations can be specified by appending an increasing number to the setting name.

The Sieve scripts found from these locations are added to the script execution sequence in the specified order.

Reading the numbered sieve_before settings stops at the first missing setting, so no numbers may be skipped.

sieve_before

Default[None]
Valuestring
See Also

This setting can be specified multiple times by adding a number after the setting name, such as sieve_before2 and so on.

See sieve_after for configuration details, as this setting behaves the same way, except the scripts are run before user's personal scripts (instead of after).

sieve_default

Default[None]
Valuestring

Location of the default personal sieve script file which gets executed ONLY if user's private Sieve script does not exist, e.g. file:/var/lib/dovecot/default.sieve (check the multiscript section for instructions on running global Sieve scripts before and after the user's personal script).

This is usually a global script, so be sure to pre-compile the specified script manually in that case using the sievec command line tool, as explained by sievec(1).

sieve_default_name

Default[None]
Valuestring
See Also

The name by which the default Sieve script is visible to ManageSieve clients. Normally, it is not visible at all.

sieve_discard

Default[None]
Valuestring

The location of a Sieve script that is run for any message that is about to be discarded; i.e., it is not delivered anywhere by the normal Sieve execution.

This only happens when the "implicit keep" is canceled, by e.g. the "discard" action, and no actions that deliver the message are executed.

This "discard script" can prevent discarding the message, by executing alternative actions.

If the discard script does nothing, the message is still discarded as it would be when no discard script is configured.

sieve_duplicate_default_period

Default14d
Valuetime
See Also
Advanced Setting; this should not normally be changed.

Default period after which tracked values are purged from the duplicate tracking database.

sieve_duplicate_max_period

Default7d
Valuetime
See Also
Advanced Setting; this should not normally be changed.

Maximum period after which tracked values are purged from the duplicate tracking database.

sieve_editheader_forbid_add

Default[None]
Valuestring
See Also

A space-separated list of headers that cannot be added to the message header.

Addition of the Subject: header cannot be prohibited, as required by the RFC specification. Therefore, adding this header to this setting has no effect.

sieve_editheader_forbid_delete

Default[None]
Valuestring
See Also

A space-separated list of headers that cannot be deleted from the message header.

Deleting the Received: and Auto-Submitted: fields is always forbidden, while removing the Subject: header cannot be prohibited, as required by the RFC specification. Therefore, adding one of these headers to this setting has no effect.

sieve_editheader_max_header_size

Default2048
Valueunsigned integer
See Also

The maximum size in bytes of a header field value passed to the addheader command.

The minimum value for this setting is 1024 bytes.

sieve_extensions

Default<see description>
Valuestring

The Sieve language extensions available to users.

By default, all supported extensions are available, except for deprecated extensions, extensions that add the ability to change messages, extensions that require explicit configuration, or extensions that are still under development.

Some system administrators may want to disable certain Sieve extensions or enable those that are not available by default.

Supported extensions are listed at Sieve extensions.

This setting can use + and - to specify differences relative to the default.

Example:

# Enable the deprecated imapflags extension in addition to all
# extensions enabled by default.
plugin {
	sieve_extensions = +imapflags
}

sieve_global

Default[None]
Valuestring

Location for :global include scripts for the Sieve include extension.

sieve_global_extensions

Defaultsieve_extensions
Valuestring

Which Sieve language extensions are only available in global scripts.

This can be used to restrict the use of certain Sieve extensions to administrator control, for instance when these extensions can cause security concerns.

This setting has higher precedence than sieve_extensions, meaning that the extensions enabled with this setting are never available to the user's personal script no matter what is specified for the sieve_extensions setting.

The syntax of this setting is similar to sieve_extensions, with the difference that extensions are enabled or disabled for exclusive use in global scripts.

Currently, no extensions are marked as such by default.

sieve_implicit_extensions

Default[None]
Valuestring

WARNING

Do not use this setting unless you really need to!

The Sieve language extensions implicitly available to users.

The extensions listed in this setting do not need to be enabled explicitly using the Sieve "require" command.

This behavior directly violates the Sieve standard, but can be necessary for compatibility with some existing implementations of Sieve (notably jSieve).

The syntax and semantics of this setting are otherwise identical to sieve_extensions.

sieve_include_max_includes

Default255
Valueunsigned integer
See Also
Advanced Setting; this should not normally be changed.

The maximum number of scripts that may be included. This is the total number of scripts involved in the include tree.

sieve_include_max_nesting_depth

Default10
Valueunsigned integer
See Also
Advanced Setting; this should not normally be changed.

The maximum nesting depth for the include tree.

sieve_max_actions

Default32
Valueunsigned integer

The maximum number of actions that can be performed during a single script execution.

If set to 0, no limit on the total number of actions is enforced.

sieve_max_cpu_time

Default30s
Valuetime

The maximum amount of CPU time that a Sieve script is allowed to use while executing. If the execution exceeds this resource limit, the script ends with an error, causing the implicit "keep" action to be executed.

This limit is not only enforced for a single script execution, but also cumulatively for the last executions within a configurable timeout (see sieve_resource_usage_timeout).

sieve_max_redirects

Default4
Valueunsigned integer

The maximum number of redirect actions that can be performed during a single script execution.

0 means redirect is prohibited.

sieve_max_script_size

Default1M
Valuesize
Advanced Setting; this should not normally be changed.

The maximum size of a Sieve script. The compiler will refuse to compile any script larger than this limit.

If set to 0, no limit on the script size is enforced.

sieve_plugins

Default[None]
Valuestring

The Pigeonhole Sieve interpreter can have plugins of its own.

Using this setting, the used plugins can be specified. Plugin names should be space-separated in the setting.

Check Sieve plugins for available plugins.

sieve_quota_max_scripts

Default[None]
Valueunsigned integer

The maximum number of personal Sieve scripts a single user can have.

Default is 0, which is unlimited.

sieve_quota_max_storage

Default[None]
Valueunsigned integer

The maximum amount of disk storage a single user's scripts may occupy.

Default is 0, which is unlimited.

sieve_redirect_envelope_from

Defaultsender
Valuestring

Specifies what envelope sender address is used for redirected messages.

Normally, the Sieve redirect command copies the sender address for the redirected message from the processed message So, the redirected message appears to originate from the original sender.

The following options are supported for this setting:

Option Description
sender The sender address is used
recipient The final recipient address is used
orig_recipient The original recipient is used
user_email The user's primary address is used. This is configured with the sieve_user_email setting. If that setting is not configured, user_email is equal to sender.
postmaster The postmaster_address configured for LDA/LMTP.
<user@domain> Redirected messages are always sent from user@domain. The angle brackets are mandatory. The null <> address is also supported.

When the envelope sender of the processed message is the null address <>, the envelope sender of the redirected message is also always <>, irrespective of what is configured for this setting.

sieve_resource_usage_timeout

Default1h
Valuetime

To prevent abuse, the Sieve interpreter can record resource usage of a Sieve script execution in the compiled binary if it is significant. Currently, this happens when CPU system + user time exceeds 1.5 seconds for one execution. Such high resource usage is summed over time in the binary and once that cumulative resource usage exceeds the limits (sieve_max_cpu_time), the Sieve script is disabled in the binary for future execution, even if an individual execution exceeded no limits.

If the last time high resource usage was recorded is older than sieve_resource_usage_timeout, the resource usage in the binary is reset. This means that the Sieve script is only disabled when the limits are cumulatively exceeded within this timeout. With the default configuration this means that the Sieve script is only disabled when the total CPU time of Sieve executions that lasted more than 1.5 seconds exceeds 30 seconds in the last hour.

A disabled Sieve script can be reactivated by the user by uploading a new version of the Sieve script after the excessive resource usage times out. An administrator can force reactivation by forcing a script compile (e.g. using the sievec command line tool).

sieve_spamtest_max_header

Default10
Valuestring
See Also

Value format: <header-field> [ ":" <regexp> ]

Some spam scanners include the maximum score value in one of their status headers. Using this setting, this maximum can be extracted from the message itself instead of specifying the maximum manually using the setting sieve_spamtest_max_value.

The syntax is identical to the sieve_spamtest_status_header setting.

sieve_spamtest_status_header

Default[None]
Valuestring
See Also

Value format: <header-field> [ ":" <regexp> ]

This specifies the header field that contains the result information of the spam scanner and it may express the syntax of the content of the header.

If no matching header is found in the message, the spamtest command will match against 0.

This is a structured setting. The first part specifies the header field name. Optionally, a POSIX regular expression follows the header field name, separated by a colon. Any white space directly following the colon is not part of the regular expression. If the regular expression is omitted, any header content is accepted and the full header value is used. When a regular expression is used, it must specify one match value (inside brackets) that yields the desired spam scanner result.

If the header does not match the regular expression or if no value match is found, the spamtest test will match against 0 during Sieve script execution.

sieve_spamtest_status_type

Default[None]
Valuestring
Allowed Valuesscorestrlentext
See Also

This specifies the type of status result that the spam/virus scanner produces.

This can either be a numeric score (score), a string of identical characters (strlen), e.g. '*******', or a textual description (text), e.g. 'Spam' or 'Not Spam'.

sieve_spamtest_text_value<X>

Default[None]
Valuestring
See Also

When the sieve_spamtest_status_type setting is set to text, these settings specify that the spamtest test will match against the value <X> when the specified string is equal to the text (extracted) from the status header.

For spamtest and spamtestplus, values of X between 0 and 10 are recognized, while virustest only uses values between 0 and 5.

sieve_trace_addresses

Defaultno
Valueboolean
See Also

Enables showing byte code addresses in the trace output, rather than only the source line numbers.

sieve_trace_debug

Defaultno
Valueboolean
See Also

Enables highly verbose debugging messages that are usually only useful for developers.

sieve_trace_dir

Default[None]
Valuestring
See Also

The directory where trace files are written.

Trace debugging is disabled if this setting is not configured or if the directory does not exist.

If the path is relative or it starts with ~/ it is interpreted relative to the current user's home directory.

sieve_trace_level

Default[None]
Valuestring
See Also

The verbosity level of the trace messages. Trace debugging is disabled if this setting is not configured. Options are:

Option Description
actions Only print executed action commands, like keep, fileinto, reject, and redirect.
commands Print any executed command, excluding test commands.
tests Print all executed commands and performed tests.
matching Print all executed commands, performed tests and the values matched in those tests.

sieve_user_email

Default[None]
Valuestring

The primary e-mail address for the user.

This is used as a default when no other appropriate address is available for sending messages.

If this setting is not configured, either the postmaster or null <> address is used as a sender, depending on the action involved.

This setting is important when there is no message envelope to extract addresses from, such as when the script is executed in IMAP.

sieve_user_log

Default[None]
Valuestring

The path to the file where the user log file is written. a default location is used.

If the main user's personal Sieve (as configured with sieve is a file, the logfile is set to <filename>.log by default.

If it is not a file, the default user log file is ~/.dovecot.sieve.log.

sieve_vacation_dont_check_recipient

Defaultno
Valueboolean
See Also

This disables the checks for implicit delivery entirely. This means that the vacation command does not verify that the message is explicitly addressed at the recipient.

Use this option with caution. Specifying yes will violate the Sieve standards and can cause vacation replies to be sent for messages not directly addressed at the recipient.

sieve_vacation_max_period

Default[None]
Valuetime
See Also

Specifies the maximum period that can be specified for the :days tag of the vacation command.

The configured value must be larger than sieve_vacation_min_period.

A value of 0 has a special meaning: it indicates that there is no upper limit.

sieve_vacation_min_period

Default1d
Valuetime
See Also

Specifies the minimum period that can be specified for the :days and :seconds tags of the vacation command.

A minimum of 0 indicates that users are allowed to make the Sieve interpreter send a vacation response message for every incoming message that meets the other reply criteria (refer to RFC 5230). A value of zero is not recommended.

sieve_vacation_send_from_receipt

Defaultno
Valueboolean
See Also

This setting determines whether vacation messages are sent with the SMTP MAIL FROM envelope address set to the recipient address of the Sieve script owner.

Normally this is set to <>, which is the default as recommended in the specification. This is meant to prevent mail loops. However, there are situations for which a valid sender address is required and this setting can be used to accommodate for those.

sieve_vacation_use_original_recipient

Defaultno
Valueboolean
See Also

This specifies whether the original envelope recipient should be used in the check for implicit delivery.

The vacation command checks headers of the incoming message, such as To: and Cc: for the address of the recipient, to verify that the message is explicitly addressed at the recipient. If the recipient address is not found, the vacation action will not trigger a response to prevent sending a reply when it is not appropriate.

Normally only the final recipient address is used in this check. This setting allows including the original recipient specified in the SMTP session if available.

This is useful to handle mail accounts with aliases. Use this option with caution: if you are using aliases that point to more than a single account, as senders can get multiple vacation responses for a single message.

Use the LDA -a option or the LMTP/LDA lda_original_recipient_header setting to make the original SMTP recipient available to Sieve.

sieve_variables_max_scope_size

Default255
Valueunsigned integer
See Also
Advanced Setting; this should not normally be changed.

The maximum number of variables that can be declared in a scope.

There are currently two variable scopes: the normal script scope and the global scope created by the Sieve include extension.

The minimum value for this setting is 128.

sieve_variables_max_variable_size

Default4k
Valuesize
See Also
Advanced Setting; this should not normally be changed.

The maximum allowed size for the value of a variable. If exceeded at runtime, the value is always truncated to the configured maximum.

The minimum value for this setting is 4000 bytes.

sieve_virustest_max_header

Default[None]
Valuestring
See Also

Value Format: <header-field> [ ":" <regexp> ]

Some spam scanners include the maximum score value in one of their status headers. Using this setting, this maximum can be extracted from the message itself instead of specifying the maximum manually using the setting sieve_virustest_max_value.

The syntax is identical to sieve_virustest_status_header.

sieve_virustest_status_header

Default[None]
Valuestring
See Also

Value Format: <header-field> [ ":" <regexp> ]

This specifies the header field that contains the result information of the spam scanner and it may express the syntax of the content of the header.

If no matching header is found in the message, the spamtest command will match against 0.

This is a structured setting. The first part specifies the header field name. Optionally, a POSIX regular expression follows the header field name, separated by a colon. Any white space directly following the colon is not part of the regular expression. If the regular expression is omitted, any header content is accepted and the full header value is used. When a regular expression is used, it must specify one match value (inside brackets) that yields the desired spam scanner result.

If the header does not match the regular expression or if no value match is found, the spamtest test will match against 0 during Sieve script execution.

sieve_virustest_status_type

Default[None]
Valuestring
Allowed Valuesscorestrlentext
See Also

This specifies the type of status result that the spam/virus scanner produces.

This can either be a numeric score (score), a string of identical characters (strlen), e.g. '*******', or a textual description (text), e.g. 'Spam' or 'Not Spam'.

sieve_virustest_text_value<X>

Default[None]
Valuestring
See Also

When the sieve_virustest_status_type setting is set to text, these settings specify that the spamtest test will match against the value <X> when the specified string is equal to the text (extracted) from the status header.

For spamtest and spamtestplus, values of X between 0 and 10 are recognized, while virustest only uses values between 0 and 5.

Extension-specific Configuration ​

Sieve language extensions may have specific configuration.

See Sieve extensions for a list of extensions and links to their configuration pages.

Per-user Sieve script location ​

By default, the Dovecot Sieve plugin looks for the user's Sieve script file in the user's home directory (~/.dovecot.sieve). This requires that the home directories for virtual users is set for the user.

If you want to store the script elsewhere, you can override the default using the sieve setting, which specifies the path to the user's script file. This can be done in two ways:

  1. Define the sieve setting in the plugin section of dovecot.conf.

  2. Return sieve extra field from userdb extra fields.

For example, to use a Sieve script file named <username>.sieve in /var/sieve-scripts, use:

plugin {
  ...
  sieve = /var/sieve-scripts/%u.sieve
}

You may use templates like %u, as shown in the example. See Config variables.

A relative path (or just a filename) will be interpreted to point under the user's home directory.

Executing Multiple Scripts Sequentially ​

The Dovecot Sieve plugin allows executing multiple Sieve scripts sequentially. The extra scripts can be executed before and after the user's private script. For example, this allows executing global Sieve policies before the user's script. This is not possible using the sieve_default setting because that is only used when the user's private script does not exist.

See sieve_before and sieve_after for details on how to configure the execution sequence.

The script execution ends when the currently executing script in the sequence does not yield a "keep" result: when the script terminates, the next script is only executed if an implicit or explicit "keep" is in effect. Thus, to end all script execution, a script must not execute keep and it must cancel the implicit keep, e.g. by executing discard; stop;.

This means that the command keep; has different semantics when used in a sequence of scripts. For normal Sieve execution, keep; is equivalent to fileinto "INBOX";, because both cause the message to be stored in INBOX.

However, in sequential script execution, it only controls whether the next script is executed. Storing the message into INBOX (the default folder) is not done until the last script in the sequence executes (implicit) keep.

To force storing the message into INBOX earlier in the sequence, the fileinto command can be used (with :copy or together with keep;).

Apart from the keep action, all actions triggered in a script in the sequence are executed before continuing to the next script. This means that when a script in the sequence encounters an error, actions from earlier executed scripts are not affected. The sequence is broken however, meaning that the script execution of the offending script is aborted and no further scripts are executed. An implicit keep is executed in stead.

Just as for executing a single script the normal way, the Dovecot Sieve plugin takes care never to duplicate deliveries, forwards or responses. When vacation actions are executed multiple times in different scripts, the usual error is not triggered: the subsequent duplicate vacation actions are simply discarded.

For example:

plugin {
  # Global scripts executed before the user's personal script.
  #   E.g. handling messages marked as dangerous
  sieve_before = /var/lib/dovecot/sieve/discard-viruses.sieve

  # Domain-level scripts retrieved from LDAP
  sieve_before2 = ldap:/etc/dovecot/sieve-ldap.conf;name=ldap-domain

  # User-specific scripts executed before the user's personal script.
  #   E.g. a vacation script managed through a non-ManageSieve GUI.
  sieve_before3 = /var/vmail/%d/%n/sieve-before

  # User-specific scripts executed after the user's personal script.
  # (if keep is still in effect)
  #   E.g. user-specific default mail filing rules
  sieve_after = /var/vmail/%d/%n/sieve-after

  # Global scripts executed after the user's personal script
  # (if keep is still in effect)
  #   E.g. default mail filing rules.
  sieve_after2 = /var/lib/dovecot/sieve/after.d/
}

Note

Be sure to manually pre-compile the scripts specified by sieve_before and sieve_after by using the sievec tool.

Visible Default Script ​

The sieve_default setting specifies the location of a default script that is executed when the user has no active personal script.

Normally, this default script is invisible to the user; i.e., it is not listed in ManageSieve server.

To give the user the ability to see and read the default script, it is possible to make it visible under a specific configurable name using sieve_default_name. The sieve_default setting needs to point to a valid script location as well for this to work. If the default script does not exist at the indicated location, it is not shown.

ManageSieve will magically list the default script under that name, even though it does not actually exist in the user's normal script storage location. This way, the ManageSieve client can see that it exists and it can retrieve its contents. If no normal script is active, the default is always listed as active. The user can replace the default with a custom script, by uploading it under the default script's name. If that custom script is ever deleted, the default script will reappear from the shadows implicitly.

This way, ManageSieve clients will not need any special handling for this feature. If the name of the default script is equal to the name the client uses for the main script, it will initially see and read the default script when the user account is freshly created. The user can edit the script, and when the edited script is saved through the ManageSieve client, it will override the default script. If the user ever wants to revert to the default, the user only needs to delete the edited script and the default will reappear.

plugin {
  sieve = file:~/sieve;active=~/.dovecot.sieve

  sieve_default = /var/lib/dovecot/sieve/default.sieve
  sieve_default_name = roundcube
}

Trace Debugging ​

Trace debugging provides detailed insight in the operations performed by the Sieve script. Messages about what the Sieve script is doing are written to the specified directory.

WARNING

On a busy server, this functionality can quickly fill up the trace directory with a lot of trace files. Enable this only temporarily and as selective as possible; e.g., enable this only for a few users by returning the settings below from userdb as userdb extra fields rather than enabling these for everyone.

Settings ​

These settings apply to both the Sieve plugin and imap-sieve plugin.

sieve_trace_addresses

Defaultno
Valueboolean
See Also

Enables showing byte code addresses in the trace output, rather than only the source line numbers.

sieve_trace_debug

Defaultno
Valueboolean
See Also

Enables highly verbose debugging messages that are usually only useful for developers.

sieve_trace_dir

Default[None]
Valuestring
See Also

The directory where trace files are written.

Trace debugging is disabled if this setting is not configured or if the directory does not exist.

If the path is relative or it starts with ~/ it is interpreted relative to the current user's home directory.

sieve_trace_level

Default[None]
Valuestring
See Also

The verbosity level of the trace messages. Trace debugging is disabled if this setting is not configured. Options are:

Option Description
actions Only print executed action commands, like keep, fileinto, reject, and redirect.
commands Print any executed command, excluding test commands.
tests Print all executed commands and performed tests.
matching Print all executed commands, performed tests and the values matched in those tests.

Revision: 8489194

Last updated:

Copyright © Open-Xchange GmbH