Manage Per-User Sieve Scripts Safely with doveadm

You will use doveadm sieve to inspect and manage one user's Sieve scripts: list them, upload a new script from standard input, retrieve a copy, rename it, and control which script is active. Allow about 15 minutes for a first run, plus time to check the script's effect on a test mailbox. These commands change mail filtering, so do the inspection steps before activation or deletion.

1. Check the installation and version boundary

The commands are supplied by Pigeonhole, the Dovecot project component that adds Sieve and ManageSieve support. The local manual page is labelled Pigeonhole for Dovecot v2.4, while the installed dovecot-core package on this machine is version 2.3.21+dfsg1-2ubuntu6.5. A manual page and binary from different releases can have different options.

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveadm help 2>&1 | grep -E '^  sieve[[:space:]]' || echo 'sieve is not listed'

The installed help on the reference machine does not list a Sieve command and the command also reports a permission error while trying to reach a Dovecot statistics socket. That is evidence that this dovecot-core-only installation is not ready to run these examples. Install or enable the matching Pigeonhole package and configure Dovecot before continuing. Use the manual page shipped with that installation if its version differs.

Run the next check as the account that will administer the mailbox. Use sudo only when your Dovecot socket or configuration permissions require it; running every command as root can hide ownership and access problems.

2. Select one user and list the scripts

Use -u for a single mailbox. The value is a Dovecot user name, often an email address. The script name is the name visible to ManageSieve clients. For scripts stored on disk, the manpage says to omit the .sieve suffix.

$ doveadm sieve list -u '[email protected]'
$ doveadm -f table sieve list -u '[email protected]'

The first form requests an overview of the user's existing scripts. The second asks for table formatting, which is easier to scan when the command supports that formatter. Do not guess a script name from a filename: use the list result, then copy the exact name into later commands.

3. Retrieve a backup before changing a script

sieve get writes the named script to standard output. Redirect it to a new local file, and avoid a destination that already contains your only backup.

$ umask 077
$ doveadm sieve get -u '[email protected]' 'vacation' > /tmp/alice-vacation.sieve
$ test -s /tmp/alice-vacation.sieve && echo 'backup written'
backup written

The umask makes a newly created backup private to its owner. Treat the file as sensitive: Sieve rules can reveal addresses, subjects and business processes. Keep it only as long as needed, then remove it deliberately with rm -- /tmp/alice-vacation.sieve. That removal is irreversible, so verify the backup is readable before deleting any server-side script.

4. Upload a new script, optionally making it active

sieve put reads the script from standard input and stores it under the supplied name only if it compiles successfully. Start with a new name while testing. The -a option makes the uploaded script active immediately, which changes filtering at delivery.

$ cat > /tmp/alice-test.sieve <<'SIEVE'
require ["fileinto"];
if header :contains "X-Training-Mail" "yes" {
  fileinto "Training";
}
SIEVE
$ doveadm sieve put -u '[email protected]' 'training-test' < /tmp/alice-test.sieve
$ doveadm sieve list -u '[email protected]'

There is no need to run sudo for the local temporary file. The final command is the verification step: confirm that training-test appears. A compile failure should leave the new script unapplied; fix the Sieve source and retry. Do not add -a until you have tested the script and confirmed that its name is correct.

When you are ready to switch delivery to an existing script, activate it explicitly:

$ doveadm sieve activate -u '[email protected]' 'training-test'
$ doveadm sieve list -u '[email protected]'

To undo that choice, activate the previously working script by its exact listed name. If no script should run, use doveadm sieve deactivate -u '[email protected]' 'training-test'. The command deactivates Sieve processing; it does not delete the script.

5. Rename or delete only after checking the active state

Renaming preserves the script while changing the name clients and later commands use:

$ doveadm sieve rename -u '[email protected]' 'training-test' 'training'
$ doveadm sieve list -u '[email protected]'

If you need to undo the rename, reverse the two names. Before deletion, retrieve a backup and confirm that the target is not active. The normal command refuses to delete an active script. The -a option overrides that protection, so treat it as a destructive, service-affecting action.

$ doveadm sieve get -u '[email protected]' 'old-test' > /tmp/alice-old-test.sieve
$ doveadm sieve delete -u '[email protected]' 'old-test'
$ doveadm sieve list -u '[email protected]'

Do not use -a in a cleanup command unless you have deliberately chosen what should happen to newly delivered mail. There is no general undelete command in this interface. Recovery means uploading a retained copy under a new script name, then activating it if appropriate.

6. Work across users only with an explicit plan

-A runs a command for all users discovered through the user database. The manual warns that iterating SQL or LDAP users depends on correctly configured iteration queries or filters. It also warns against combining -A with a system-user database that includes low-UID accounts. Prefer a tested -u command for one mailbox, and review the user database before any bulk operation.

-S selects a local Unix socket or a remote hostname:port. Treat a remote endpoint as security-sensitive: verify the socket, transport and access controls before sending script contents or making changes. Global -D enables debug output, while -v adds verbosity and a progress counter. Keep debug output out of shared logs if it may expose mailbox names or configuration.