

Dovecot Sieve plugin
====================





 1. Dovecot Sieve plugin

 1. Getting the sources
 2. Compiling
 3. Configuring
 4. Per-user Sieve script location
 5. Script compiling and errors
 6. Features
 7. ManageSieve server
 8. Vacation auto-reply
 9. Example scripts

 1. SpamAssassin tagged mail filtering
 2. Mail filtering by various headers
 3. Vacation auto-reply
 4. Include scripts
 * Migration from Procmail

 


Getting the sources
===================


The Sieve plugin is distributed in a separate package. You can get it from Dovecot's download page [None]. 


Compiling
=========


Use '--with-dovecot=<path>' to point to 'dovecot-config' file's directory. There are two possibilities where this could exist: 

 1. If you configured Dovecot with '--enable-header-install', you'll have 'dovecot-config' installed in '$prefix/lib/dovecot/' directory. 
 2. Compiled Dovecot sources' root directory. 
So for example: 

---%<-------------------------------------------------------------------------
./configure --with-dovecot=/usr/local/lib/dovecot
make
sudo make install
---%<-------------------------------------------------------------------------

'sievec' and 'sieved' binaries are built only if you use method 2, because they need to link with Dovecot's libraries. They can be used to compile and decompile Sieve scripts. You probably don't need these, except when using the Python managesieve server (it uses 'sievec' to verify uploaded scripts). 


Configuring
===========


First, you'll need to make sure you're using Dovecot's >>deliver<< to deliver incoming mail to users' mailboxes.   Then you need to enable the cmusieve plugin: 

---%<-------------------------------------------------------------------------
protocol lda {
..
  # If there is no user-specific Sieve-script, global Sieve script is
  # executed if set. (v1.0.1 and older used "global_script_path")
  #sieve_global_path =
  # Support for dynamically loadable plugins. mail_plugins is a space separated
  # list of plugins to load.
  mail_plugins = cmusieve # ... other plugins like quota
}
---%<-------------------------------------------------------------------------

In this context /script path/ refers to a filename, not just a directory. 
 

Per-user Sieve script location
==============================


There are two choices: 

 1. 'sieve' variable can contain the script path (absolute or relative to the user's home directory). 
 2. If 'sieve' isn't found, '.dovecot.sieve' is used under home directory. 
Usually you want to use '~/.dovecot.sieve', which means that your >>userdb<< lookup must return a home directory. See >>VirtualUsers#homedirs<<. 
'sieve' variable can be set in two ways: 

 1. Return it from userdb >>extra fields<<. 
 2. Use a template in plugin section. 
The template can be set like: 

---%<-------------------------------------------------------------------------
plugin {
  # NOTE: %variable expansion works only with Dovecot v1.0.2+
  sieve = /var/sieve-scripts/%u/sieve
}
---%<-------------------------------------------------------------------------

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


Script compiling and errors
===========================


When the Sieve script is executed for the first time (or after it has been changed), it's compiled into into a binary form. The binary is stored by appending "c" letter after the script name (e.g. ".dovecot.sievec"). If there are errors in the script, the error messages are stored into ".err" file (e.g. ".dovecot.sieve.err"). This means that deliver must have write access to the directory where the script is stored. 
Global scripts have the same problem. Either allow deliver to write to the global script's directory, or compile the script before deliver sees it. Scripts can be compiled using 'sievec' binary. 


Features
========


The Sieve plugin v1.0.x code is taken from Cyrus IMAP v2.2.12. The Sieve plugin v1.1.x code is taken from Cyrus IMAP v2.3.8. Whatever information you can find about those versions of Cyrus Sieve, it should also apply to Dovecot. 
The supported Sieve features are: 

 * fileinto 
 * reject 
 * envelope 
 * vacation 
 * imapflags 
 * notify 
 * regex 
 * subaddress 
 * relational 
 * copy (v1.1 only) 
 * body (v1.1 only) 
 * include (v1.1 only) 
You can find more information about these at the Sieve Mail Filtering Language Charter [None]. 
NB: Sieve doesn't support running external programs. 


ManageSieve server
==================



 * Python implementation: http://woozle.org/~neale/src/pysieved/ 
 * Dovecot patch: http://dovecot.org/pipermail/dovecot/2007-November/026785.html 
The Dovecot patch will most likely be added to Dovecot v2.0 version. 


Vacation auto-reply
===================


The vacation replies are sent to the envelope sender. Currently this is taken from the Return-Path: header in the message. 
List of autoreplied senders is stored in '.dovecot.lda-dupes' file in user's home directory. When you're testing the vacation feature, it's easy to forget that the reply is sent only once in the number of configured days. If you've problems getting the vacation reply, try deleting this file. If that didn't help, make sure the problem isn't related to sending mails in general by trying the "reject" Sieve command. 
The automatic replies aren't sent if any of the following is true: 

 * Auto-Submitted: header exists with any value except "no" 
 * Precedence: header exists with value "junk", "bulk" or "list" 
 * The envelope sender 

 * begins with "MAILER-DAEMON" (case-insensitive) 
 * begins with "LISTSERV" (case-insensitive) 
 * begins with "majordomo" (case-insensitive) 
 * begins with "owner-" (case-sensitive) 
 * contains the string "-request" anywhere within it (case-sensitive) 

 * The envelope sender and envelope recipient are the same 
 * The envelope recipient is not found in the message To:, Cc: or Bcc: fields. 
The envelope sender is taken from a Return-Path: header in the message. The envelope recipient is taken from the recipient user (-d parameter with virtual user setup). A bare username without a domain gets canonicalised by the libsieve code to "<username>@unspecified-domain", which means it is highly unlikely to pass the last two tests in the list above. 


Example scripts
===============


Below are some simple Sieve code examples, more can be found from http://libsieve.sourceforge.net/script1.php and http://wiki.fastmail.fm/index.php/SieveExamples. 


SpamAssassin tagged mail filtering
==================================


Redirect >>SpamAssassin<< tagged mails into mbox folder "spam": 

---%<-------------------------------------------------------------------------
require "fileinto";
if exists "X-Spam-Flag" {
  fileinto "spam";
} ---%<-------------------------------------------------------------------------

Discard >>SpamAssassin<< tagged mails: 

---%<-------------------------------------------------------------------------
if exists "X-Spam-Flag" {
  discard;
} ---%<-------------------------------------------------------------------------



Mail filtering by various headers
=================================


Use if/elsif/else to store messages into various folders/subfolders: 

 * 
---%<-------------------------------------------------------------------------
require "fileinto";
if address :is "to" "dovecot@dovecot.org" {
  fileinto "Dovecot-list";
} elsif address :is "Return-path" "owner-cipe-l@inka.de" {
  fileinto "lists.cipe";
} elsif anyof (header :contains "X-listname" "lugog@cip.rz.fh-offenburg.de",
               header :contains "List-Id" "Linux User Group Offenburg") {
  fileinto "ml.lugog";
} else {
  # The rest goes into INBOX
  # default is "implicit keep", we do it explicitly here
  keep;
} ---%<-------------------------------------------------------------------------
"anyof" means logical OR, "allof" is AND. 
Forward mails with "order" or "buy" in their subject to another address: 

 * 
---%<-------------------------------------------------------------------------
if header :contains "subject" ["order", "buy"] {
  redirect "orders@company.dom";
} ---%<-------------------------------------------------------------------------

Message-ID and recipient of forwarded message are stored in a '.dovecot.lda-dupes' at users home directory to prevent mail loops. 


Vacation auto-reply
===================



---%<-------------------------------------------------------------------------
require ["fileinto", "vacation"];
# Move spam to spam folder
if exists "X-Spam-Flag" {
  fileinto "spam";
  # Stop here so that we do not reply on spams
  stop;
}
vacation
  # Reply at most once a day to a same sender
  :days 1
  :subject "Out of office reply"
  # List of allowed recipient addresses from auto reply should be sent.
  :addresses ["j.doe@company.dom", "john.doe@company.dom"]
"I'm out of office, please contact Joan Doe instead.
Best regards
John Doe"; ---%<-------------------------------------------------------------------------



Include scripts
===============


With v1.1 it's possible to include other Sieve scripts in your script: 

---%<-------------------------------------------------------------------------
require ["include"];
include :global "global-spam.sieve";
include :personal "my-own-spam.sieve";
---%<-------------------------------------------------------------------------

If you want to use global scripts, you'll need to set up the global script directory: 

---%<-------------------------------------------------------------------------
protocol lda {
  # ..
  sieve_global_dir = /etc/dovecot/sieve/
}
---%<-------------------------------------------------------------------------

Personal scripts are looked up from 'sieve_dir' if it's returned in >>userdb extra fields<<, or home directory if not. If neither is known, the include fails. 
It's not currently possible to use subdirectories for the scripts. Having a '/' character in the script name always fails the include. This is just an extra check to avoid potential problems with including scripts within mail directories. 


Migration from Procmail
=======================


There exists a script which attempts to translate simple Procmail rules into Sieve rules: http://www.earth.ox.ac.uk/~steve/sieve/procmail2sieve.pl 
Here's the original post announcing it: http://dovecot.org/list/dovecot/2007-March/020895.html 
(This file was created from the wiki on 2007-12-11 04:42)
