Debian Codegraph @

doc/html/_sources/imap/reference/admin/sieve.rst.txt

raw
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>`_.