| 1 |
.. _cyrus-sieve: |
| 2 |
|
| 3 |
=========== |
| 4 |
Cyrus Sieve |
| 5 |
=========== |
| 6 |
|
| 7 |
.. contents:: |
| 8 |
|
| 9 |
|
| 10 |
Introduction |
| 11 |
============ |
| 12 |
|
| 13 |
Cyrus Sieve is an implementation of the Sieve mail filtering language |
| 14 |
( :rfc:`3028` ). It allows a series of tests to be applied against an incoming |
| 15 |
message, with actions to take place if there is a match. |
| 16 |
|
| 17 |
Mail filtering occurs on delivery of the message (within lmtpd). |
| 18 |
|
| 19 |
Cyrus compiles sieve scripts to bytecode to reduce the overhead of parsing the |
| 20 |
scripts fully inside of lmtpd. This occurs automatically if |
| 21 |
:cyrusman:`sieveshell(1)` is used to place the scripts on the server. |
| 22 |
|
| 23 |
Sieve scripts can be placed either by the :cyrusman:`timsieved(8)` daemon |
| 24 |
(implementing the ManageSieve protocol :rfc:`5804`; this is the preferred |
| 25 |
options since it allows for syntax checking) or in the user's home directory |
| 26 |
as a .sieve file. |
| 27 |
|
| 28 |
Installing Sieve |
| 29 |
================ |
| 30 |
|
| 31 |
This section assumes that you :ref:`compiled Cyrus <compiling>` with sieve |
| 32 |
support. If you specified ``--disable-sieve`` when running ``./configure``, |
| 33 |
you did NOT compile the server with sieve support. |
| 34 |
|
| 35 |
Configure sieve |
| 36 |
--------------- |
| 37 |
|
| 38 |
Depending on what's in your ``/etc/services`` file, sieve will usually be set |
| 39 |
to listen on port 2000 (old convention) or port 4190 (as specified by :rfc:`5804`). |
| 40 |
|
| 41 |
Add lines to the SERVICES section of :cyrusman:`cyrus.conf(5)` to make the |
| 42 |
server listen to the right ports for sieveshell commands:: |
| 43 |
|
| 44 |
sieve cmd="timsieved" listen="servername:sieve" prefork=0 |
| 45 |
managesieve cmd="timsieved" listen="servername:4190" prefork=0 |
| 46 |
|
| 47 |
Sieve scripts are stored in the directory hierarchy specified by the |
| 48 |
**sievedir** :cyrusman:`imapd.conf(5)` option (default: ``/usr/sieve``). |
| 49 |
This directory must exist and be writeable by the cyrus user for ``timsieved`` |
| 50 |
to function, so organise that now. |
| 51 |
|
| 52 |
Configure outgoing mail |
| 53 |
----------------------- |
| 54 |
|
| 55 |
Some Sieve actions (redirect, vacation) can send outgoing mail. |
| 56 |
|
| 57 |
You'll need to make sure that lmtpd can send outgoing messages. Currently, it |
| 58 |
invokes ``/usr/lib/sendmail`` by default to send messages. Change this by |
| 59 |
adding a line like:: |
| 60 |
|
| 61 |
sendmail: /usr/sbin/sendmail |
| 62 |
|
| 63 |
in your :cyrusman:`imapd.conf(5)`. If you're using Postfix or another MTA, make |
| 64 |
sure that the sendmail referenced in "/etc/imapd.conf" is Sendmail-compatible. |
| 65 |
|
| 66 |
Managing Sieve Scripts |
| 67 |
====================== |
| 68 |
|
| 69 |
Since Cyrus is based around the concept of a sealed-server, the normal way for |
| 70 |
users to manipulate Sieve scripts is through the :cyrusman:`sieveshell(1)` |
| 71 |
utility, in communication with the :cyrusman:`timsieved(8)` service. |
| 72 |
|
| 73 |
If, for some reason, you do have user home directories on the server, you can |
| 74 |
use the **sieveusehomedir** option in :cyrusman:`imapd.conf(5)` and have the |
| 75 |
sieve script stored in the home directory of the user as ``~/.sieve``. |
| 76 |
|
| 77 |
Sieve scripts in shared folders |
| 78 |
------------------------------- |
| 79 |
|
| 80 |
Cyrus has two types of repositories where Sieve scripts can live: |
| 81 |
|
| 82 |
1. **Personal** is per user and |
| 83 |
2. **Global** is for every user. Global scripts aren't applied on incoming |
| 84 |
messages by default: users must include them in their scripts. Note that |
| 85 |
there are two types of Global scripts: **global** and **global per domain**. |
| 86 |
|
| 87 |
When you log into Cyrus IMAP with :cyrusman:`sieveshell(1)` you have the |
| 88 |
following combinations (Assuming there is ``manager`` and |
| 89 |
``[email protected]`` as admin in :cyrusman:`imapd.conf(5)`): |
| 90 |
|
| 91 |
* ``sieveshell -a manager -u manager localhost`` - To edit global scripts. |
| 92 |
* ``sieveshell -a [email protected] -u [email protected] localhost`` - To |
| 93 |
edit global script of example.com domain. |
| 94 |
* ``sieveshell -a [email protected] -u [email protected] localhost`` - To edit |
| 95 |
personal scripts of some user. |
| 96 |
|
| 97 |
Scripts for shared folders work different from user scripts. The last ones are |
| 98 |
loaded to the user's repository and attached to the inbox when activated. The |
| 99 |
first ones must be loaded to the global domain repository and attached to a |
| 100 |
shared folder by a user that has permission on it. Use the second combination |
| 101 |
listed above to load them and cyradm (or another compatible client) to do the |
| 102 |
attach:: |
| 103 |
|
| 104 |
|
| 105 |
sieveshell -u [email protected] -a [email protected] localhost |
| 106 |
> put /tmp/my_script my_script |
| 107 |
cyradm -u [email protected] localhost |
| 108 |
localhost.localdomain> mboxcfg [email protected] sieve my_script |
| 109 |
|
| 110 |
|
| 111 |
Testing the Sieve Server |
| 112 |
======================== |
| 113 |
|
| 114 |
The Sieve server, :cyrusman:`timsieved(8)`, is used for transporting user Sieve |
| 115 |
scripts to the sealed IMAP server. It is incompatible with the |
| 116 |
**sieveusehomedir** option. It is named after the principal author, Tim Martin, |
| 117 |
who desperately wanted something named after him in the Cyrus distribution. |
| 118 |
|
| 119 |
From your normal account, telnet to the sieve port on the server you're setting |
| 120 |
up:: |
| 121 |
|
| 122 |
telnet servername sieve |
| 123 |
|
| 124 |
If your server is running, you'll get a message similar to the following one:: |
| 125 |
|
| 126 |
Trying 128.2.10.192... |
| 127 |
Connected to servername.domain.tld. |
| 128 |
Escape character is '^]'. |
| 129 |
"IMPLEMENTATION" "Cyrus timsieved v3.8.3" |
| 130 |
"VERSION" "1.0" |
| 131 |
"SASL" "ANONYMOUS PLAIN GSSAPI" |
| 132 |
"SIEVE" "fileinto reject envelope vacation imapflags notify subaddress regex" |
| 133 |
"NOTIFY" "mailto" |
| 134 |
"UNAUTHENTICATE" |
| 135 |
OK |
| 136 |
|
| 137 |
Any message other than one similar to the one above means there is a problem. |
| 138 |
Make sure all of authentication methods you wish to support are listed. This |
| 139 |
list should be identical to the one listed by "imapd" earlier. Next terminate |
| 140 |
the connection, by typing:: |
| 141 |
|
| 142 |
logout |
| 143 |
|
| 144 |
Next test authenticating to the sieve server. To do this run the |
| 145 |
:cyrusman:`sieveshell(1)` utility. You must specify the server. If you run this |
| 146 |
utility from a different machine without the "sieve" entry in "/etc/services", |
| 147 |
port 2000 will be used. |
| 148 |
|
| 149 |
:: |
| 150 |
|
| 151 |
sieveshell servername |
| 152 |
Please enter your password: ****** |
| 153 |
> quit |
| 154 |
|
| 155 |
This should produce the message "Authentication failed" with a description of |
| 156 |
the failure if there was a problem. |
| 157 |
|
| 158 |
Next you should attempt to place a sieve script on the server. To do this |
| 159 |
create a file named ``myscript.script`` with the following lines. Replace |
| 160 |
"[email protected]" with an email address you can send mail from, but that is |
| 161 |
not the one you are working on now. |
| 162 |
|
| 163 |
:: |
| 164 |
|
| 165 |
require ["reject","fileinto"]; |
| 166 |
if address :is :all "From" "[email protected]" |
| 167 |
{ |
| 168 |
reject "testing"; |
| 169 |
} |
| 170 |
|
| 171 |
To place this script on the server run the following command:: |
| 172 |
|
| 173 |
sieveshell servername |
| 174 |
Please enter your password: ****** |
| 175 |
> put myscript.script |
| 176 |
> activate myscript |
| 177 |
> quit |
| 178 |
|
| 179 |
This should place your script on the server and make it the active script. |
| 180 |
|
| 181 |
Test that the sieve script is actually run. Send a message to the address |
| 182 |
you're working on from the address mentioned in the sieve script. The message |
| 183 |
should be rejected. |
| 184 |
|
| 185 |
When you're done, don't forget to delete your testing script:: |
| 186 |
|
| 187 |
sieveshell servername |
| 188 |
Please enter your password: ****** |
| 189 |
> delete myscript.script |
| 190 |
> quit |
| 191 |
|
| 192 |
Cyrus Sieve Support |
| 193 |
=================== |
| 194 |
|
| 195 |
.. _cyrus-sieve-specialuse: |
| 196 |
|
| 197 |
Special use folders |
| 198 |
------------------- |
| 199 |
|
| 200 |
Some mail clients allow users to rename the system folders, such as Archive and |
| 201 |
Trash. This can make sieve scripts break if they are using folder names |
| 202 |
explicitly. Fortunately such folders have a special use flag, allowing you to |
| 203 |
access them from sieve without needing to know their current titles. |
| 204 |
|
| 205 |
* \\Archive |
| 206 |
* \\Drafts |
| 207 |
* \\Junk - also known as the Spam folder |
| 208 |
* \\Sent |
| 209 |
* \\Trash |
| 210 |
|
| 211 |
.. _cyrus-sieve-extensions: |
| 212 |
|
| 213 |
Supported extensions |
| 214 |
-------------------- |
| 215 |
Sieve has a lot of |
| 216 |
`extensions <http://www.iana.org/assignments/sieve-extensions/sieve-extensions.xhtml>`_. |
| 217 |
Cyrus supports a subset of these: |
| 218 |
|
| 219 |
* Sieve language reference :rfc:`5228` |
| 220 |
* Vacation Extension :rfc:`5230` |
| 221 |
* Vacation Seconds :rfc:`6131` |
| 222 |
* Relational Tests :rfc:`5231` |
| 223 |
* Subaddress Extension :rfc:`5233` |
| 224 |
* Copying Without Side Effects :rfc:`3894` |
| 225 |
* Regular Expression Extension :draft:`draft-ietf-sieve-regex` |
| 226 |
* Checking Mailbox Status and Accessing Mailbox Metadata :rfc:`5490` |
| 227 |
* Notify Extension :rfc:`5435` |
| 228 |
* Include :rfc:`6609` |
| 229 |
* Date :rfc:`5260` |
| 230 |
* Index :rfc:`5260` |
| 231 |
* Variables :rfc:`5229` |
| 232 |
* Editheader Extension :rfc:`5293` |
| 233 |
* Reject and Extended Reject :rfc:`5429` |
| 234 |
* Externally Stored Lists :rfc:`6134` |
| 235 |
* Duplicate Extension :rfc:`7352` |
| 236 |
* Ihave Extension :rfc:`5463` |
| 237 |
* Delivering to Special-Use Mailboxes :rfc:`8579` |
| 238 |
* IMAP flag Extension :rfc:`5232` |
| 239 |
* Body Extension :rfc:`5173` |
| 240 |
|
| 241 |
Cyrus IMAP Specific Extensions |
| 242 |
------------------------------ |
| 243 |
|
| 244 |
.. _vnd.cyrus.log: |
| 245 |
|
| 246 |
log |
| 247 |
^^^ |
| 248 |
|
| 249 |
Usage:: |
| 250 |
|
| 251 |
require "vnd.cyrus.log"; |
| 252 |
log <string>; |
| 253 |
|
| 254 |
The **log** action sends the string to syslog with INFO priority. |
| 255 |
|
| 256 |
.. _processimip: |
| 257 |
|
| 258 |
processimip |
| 259 |
^^^^^^^^^^^ |
| 260 |
|
| 261 |
Usage:: |
| 262 |
|
| 263 |
require "vnd.cyrus.imip"; |
| 264 |
processimip [ ":invitesonly" / ":deletecanceled" ] [ ":outcome" <string> ] [ ":errstr" <string> ] [ ":calendarid" <string> ]; |
| 265 |
processimip ":updatesonly" [ ":deletecanceled" ] [ ":outcome" <string> ] [ ":errstr" <string> ]; |
| 266 |
|
| 267 |
The **processimip** action processes iMIP messages during LMTP delivery. It handles the first possibly nested *text/calendar* MIME part and ignores the *application/ics* MIME part. |
| 268 |
|
| 269 |
If present, the variable pointed after the ``:outcome`` parameter contains the enacted action. Problems are communicated with the variable named after the ``:errstr`` parameter. The ``:errstr`` and ``:outcome`` parameters can be used only with ``require "variables";``. |
| 270 |
|
| 271 |
**processimip** does not affect the implicit keep. The action sends to syslog with INFO priority *outcome* and *errstr*, even when these parameters were not used. **processimip** does not change the *PARTSTAT* property parameter value and in turn does not send replies to the *ORGANIZER*. **processimip** does not produce runtime errors, if it is used together with the *[e]reject* action. The handled *text/calendar* MIME part is stored in the scheduling Inbox. |
| 272 |
|
| 273 |
The string after the ``:calendarid`` parameter indicates in which calendar to create new iCalendar messages. The default destination depends on the scheduling Inbox’s **CALDAV:schedule-default-calendar-URL** WebDAV property. |
| 274 |
|
| 275 |
When method CANCEL is received, by default the iCalendar object is retained and its STATUS property is changed to CANCELLED. With parameter ``:deletecanceled`` the iCalendar object is deleted on method CANCEL. |
| 276 |
|
| 277 |
.. code-block:: none |
| 278 |
:caption: Example |
| 279 |
|
| 280 |
require ["ereject", "variables", "vnd.cyrus.imip"]; |
| 281 |
if envelope "to" "me+imip@domain" { |
| 282 |
processimip :outcome "outcome" :errstr "errstr"; |
| 283 |
if string "${outcome}" "error" { |
| 284 |
ereject "iMIP handling failed: ${errstr}"; |
| 285 |
} |
| 286 |
} |
| 287 |
|
| 288 |
After **processimip** returns the *outcome* and *errstr* variables have one of these values: |
| 289 |
|
| 290 |
========= =========================================== ======= |
| 291 |
outcome errstr Remark |
| 292 |
========= =========================================== ======= |
| 293 |
error could not autoprovision calendars Default calendars cannot be created. |
| 294 |
error no component to schedule |
| 295 |
error missing UID property |
| 296 |
error invalid iCalendar data: … |
| 297 |
error missing ORGANIZER property When method is ADD, CANCEL, POLLSTATUS or REQUEST. |
| 298 |
error missing ATTENDEE property When method is REPLY. |
| 299 |
error unsupported method: … E.g. when VPOLL component is used with method ADD. |
| 300 |
error unsupported component: … |
| 301 |
error failed to deliver iMIP message: … |
| 302 |
error could not find matching ATTENDEE property When method is ADD, CANCEL, POLLSTATUS, PUBLISH or REQUEST. |
| 303 |
no_action unable to parse iMIP message The email cannot be parsed. |
| 304 |
no_action unable to find & parse text/calendar part |
| 305 |
no_action missing METHOD property |
| 306 |
no_action configured to NOT process updates When method is ADD, CANCEL or POLLSTATUS and ``:invitesonly`` is provided. |
| 307 |
no_action configured to NOT process replies When method is REPLY and ``:invitesonly`` is provided. |
| 308 |
no_action |
| 309 |
added |
| 310 |
updated Also on method CANCEL. |
| 311 |
========= =========================================== ======= |
| 312 |
|
| 313 |
Sieve Tools |
| 314 |
----------- |
| 315 |
|
| 316 |
* :cyrusman:`timsieved(8)` - server side daemon to accept requests from |
| 317 |
sieveshell |
| 318 |
* :cyrusman:`sievec(8)` - compile a script into bytecode. See sieved. |
| 319 |
* :cyrusman:`sieved(8)` - decompile a script back from bytecode. See sievec. |
| 320 |
* :cyrusman:`masssievec(8)` - compiles all the scripts in **sievedir** from |
| 321 |
``imapd.conf``. |
| 322 |
* :cyrusman:`sivtest(1)` - authenticate and test against a MANAGESIEVE server |
| 323 |
such as timsieved. |
| 324 |
* :cyrusman:`sieveshell(1)` - allow users to manage scripts on a remote server, |
| 325 |
via MANAGESIEVE |
| 326 |
* :cyrusman:`translatesieve(8)` - utility script to translate sieve scripts to |
| 327 |
use **unixhierarchysep** and/or **altnamespace** |
| 328 |
|
| 329 |
Writing Sieve |
| 330 |
============= |
| 331 |
|
| 332 |
Sieve scripts can be used to automatically delete or forward messages; to send |
| 333 |
autoreplies; to sort them in folders; to mark messages as read or flagged; to |
| 334 |
test messages for spam or viruses; or to reject messages at or after delivery. |
| 335 |
`Sieve.info <http://sieve.info>`_ has more information on sieve and its uses. |
| 336 |
|
| 337 |
There's a `good sieve reference <http://thsmi.github.io/sieve-reference/en/index.html>`_ |
| 338 |
online which describes the language. |
| 339 |
|
| 340 |
For those who prefer a client to write code in, Sieve.info has a |
| 341 |
`list of desktop, web and command line clients <http://sieve.info/clients>`_. |