doc/doc-txt/README.SIEVE

   1 $Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.12 2008/01/28 12:26:31 michael Exp $
   2
   3               Notes on the Sieve implementation for Exim
   4
   5 Exim Filter Versus Sieve Filter
   6
   7 Exim supports two incompatible filters: The traditional Exim filter and
   8 the Sieve filter. Since Sieve is a extensible language, it is important
   9 to understand "Sieve" in this context as "the specific implementation
  10 of Sieve for Exim".
  11
  12 The Exim filter contains more features, such as variable expansion, and
  13 better integration with the host environment, like external processes
  14 and pipes.
  15
  16 Sieve is a standard for interoperable filters, defined in RFC 5228,
  17 with multiple implementations around. If interoperability is important,
  18 then there is no way around it.
  19
  20
  21 Exim Implementation
  22
  23 The Exim Sieve implementation offers the core as defined by RFC 5228,
  24 the "encoded-character" extension (RFC 5228), the "envelope" test (RFC
  25 5228), the "fileinto" action (5228), the "copy" parameter (RFC 3894), the
  26 "vacation" action (5230), the "notify" action (draft-ietf-sieve-notify-12)
  27 with mailto URIs (draft-ietf-sieve-notify-mailto-05), the
  28 "i;ascii-numeric" comparator (RFC 2244) and the subaddress parameter
  29 (RFC 5233).
  30
  31 The Sieve filter is integrated in Exim and works very similar to the
  32 Exim filter: Sieve scripts are recognized by the first line containing
  33 "# sieve filter".  When using "keep" or "fileinto" to save a mail into a
  34 folder, the resulting string is available as the variable $address_file
  35 in the transport that stores it.  The following routers and transport
  36 show a typical use of Sieve:
  37
  38 begin routers
  39
  40 localuser_verify:
  41   driver = accept
  42   domains = +localdomains
  43   local_part_suffix = "-*"
  44   local_part_suffix_optional
  45   check_local_user
  46   require_files = $home/.forward
  47   verify_only = true
  48
  49 localuser_deliver:
  50   driver = redirect
  51   domains = +localdomains
  52   local_part_suffix = "-*"
  53   local_part_suffix_optional
  54   sieve_subaddress = "${sg{$local_part_suffix}{^-}{}}"
  55   sieve_useraddress = "$local_part"
  56   check_local_user
  57   require_files = $home/.forward
  58   file = $home/.forward
  59   check_ancestor
  60   allow_filter
  61   file_transport = localuser
  62   reply_transport = vacation
  63   sieve_vacation_directory = $home/mail/vacation
  64   verify = false
  65
  66 begin transports
  67
  68 localuser:
  69   driver = appendfile
  70   file = ${if eq{$address_file}{inbox} \
  71               {/var/mail/$local_part} \
  72               {${if eq{${substr_0_1:$address_file}}{/} \
  73                     {$address_file} \
  74                     {$home/mail/$address_file} \
  75               }} \
  76          }
  77   delivery_date_add
  78   envelope_to_add
  79   return_path_add
  80   mode = 0600
  81
  82 vacation:
  83   driver = autoreply
  84
  85 Absolute files are stored where specified, relative files are stored
  86 relative to $home/mail and "inbox" goes to the standard mailbox location.
  87 To enable "vacation", sieve_vacation_directory is set to the directory
  88 where vacation databases are held (don't put anything else in that
  89 directory) and point reply_transport to an autoreply transport.
  90 Setting the Sieve useraddress and subaddress allows to use the subaddress
  91 extension.
  92
  93
  94 RFC Compliance
  95
  96 Exim requires the first line to be "# sieve filter".  Of course the RFC
  97 does not enforce that line.  Don't expect examples to work without adding
  98 it, though.
  99
 100 RFC 5228 requires using CRLF to terminate the end of a line.
 101 The rationale was that CRLF is universally used in network protocols
 102 to mark the end of the line.  This implementation does not embed Sieve
 103 in a network protocol, but uses Sieve scripts as part of the Exim MTA.
 104 Since all parts of Exim use \n as newline character, this implementation
 105 does, too.  You can change this by defining the macro RFC_EOL at compile
 106 time to enforce CRLF being used.
 107
 108 The folder specified by "fileinto" must not contain the character
 109 sequence ".." to avoid security problems.  RFC 5228 does not specify the
 110 syntax of folders apart from keep being equivalent to fileinto "INBOX".
 111 This implementation uses "inbox" instead.
 112
 113 Sieve script errors currently cause that messages are silently filed into
 114 "inbox".  RFC 5228 requires that the user is notified of that condition.
 115 This may be implemented in future by adding a header line to mails that
 116 are filed into "inbox" due to an error in the filter.
 117
 118 The automatic replies generated by "vacation" do not contain an updated
 119 "references" header field.
 120
 121
 122 Semantics Of Keep
 123
 124 The keep command is equivalent to fileinto "inbox": It saves the
 125 message and resets the implicit keep flag.  It does not set the
 126 implicit keep flag; there is no command to set it once it has
 127 been reset.
 128
 129
 130 Semantics Of Fileinto
 131
 132 RFC 5228 does not specify if "fileinto" tries to create a mail folder,
 133 in case it does not exist.  This implementation allows to configure
 134 that aspect using the appendfile transport options "create_directory",
 135 "create_file" and "file_must_exist".  See the appendfile transport in
 136 the Exim specification for details.
 137
 138
 139 Allof And Anyof Test
 140
 141 RFC 5228 does not specify if these tests use shortcut/lazy evaluation.
 142 Exim uses shortcut evaluation.
 143
 144
 145 Action Reordering
 146
 147 RFC 5228 does not specify if actions may be executed out of order.
 148 Exim may execute them out of order, e.g. messages may be filed to
 149 folders or forwarded in a different order than specified, because
 150 those actions only setup delivery, but do not execute it themselves.
 151
 152
 153 Sieve Syntax And Semantics
 154
 155 RFC 5228 uses a generic grammar as syntax for commands and tests and
 156 performs many checks during semantic analysis.  Syntax is specified
 157 by grammar rules, semantics by natural language.  The intention is to
 158 provide a framework for the syntax that describes current commands as
 159 well as future extensions, and describing commands by semantics.
 160
 161 The following replacement for section 8.2 gives a grammar for specific
 162 commands of this implementation, thus removing most of the semantic
 163 analysis.  Since the parser can not parse unsupported extensions, the
 164 result is strict error checking of any executed and not executed code
 165 until "stop" is executed or the end of the script is reached.
 166
 167 8.2. Grammar
 168
 169 The grammar is specified in ABNF with two extensions to describe tagged
 170 arguments that can be reordered and grammar extensions: { } denotes a
 171 sequence of symbols that may appear in any order.  Example:
 172
 173   options = a b c
 174   start   = { options }
 175
 176 is equivalent to:
 177
 178   start   =  ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
 179
 180 The symbol =) is used to append to a rule:
 181
 182   start =  a
 183   start =) b
 184
 185 is equivalent to
 186
 187   start =  a b
 188
 189 The basic Sieve commands are specified using the following grammar, which
 190 language is a subset of the generic grammar above.  The start symbol is
 191 "start".
 192
 193   address-part     =  ":localpart" / ":domain" / ":all"
 194   comparator       =  ":comparator" string
 195   match-type       =  ":is" / ":contains" / ":matches"
 196   string           =  quoted-string / multi-line
 197   string-list      =  "[" string *("," string) "]" / string
 198   address-test     =  "address" { [address-part] [comparator] [match-type] }
 199                       string-list string-list
 200   test-list        =  "(" test *("," test) ")"
 201   allof-test       =  "allof" test-list
 202   anyof-test       =  "anyof" test-list
 203   exists-test      =  "exists" string-list
 204   false-test       =  "false"
 205   true=test        =  "true"
 206   header-test      =  "header" { [comparator] [match-type] }
 207                       string-list string-list
 208   not-test         =  "not" test
 209   relop            =  ":over" / ":under"
 210   size-test        =  "size" relop number
 211   block            =  "{" commands "}"
 212   if-command       =  "if" test block *( "elsif" test block ) [ "else" block ]
 213   stop-command     =  "stop" { stop-options } ";"
 214   stop-options     =
 215   keep-command     =  "keep" { keep-options } ";"
 216   keep-options     =
 217   discard-command  =  "discard" { discard-options } ";"
 218   discard-options  =
 219   redirect-command =  "redirect" { redirect-options } string ";"
 220   redirect-options =
 221   require-command  =  "require" { require-options } string-list ";"
 222   require-options  =
 223   test             =  address-test / allof-test / anyof-test / exists-test
 224                       / false-test / true-test / header-test / not-test
 225                       / size-test
 226   command          =  if-command / stop-command / keep-command
 227                       / discard-command / redirect-command
 228   commands         =  *command
 229   start            =  *require-command commands
 230
 231 The extensions "envelope" and "fileinto" are specified using the following
 232 grammar extension.
 233
 234   envelope-test    =  "envelope" { [comparator] [address-part] [match-type] }
 235                       string-list string-list
 236   test             =/ envelope-test
 237
 238   fileinto-command =  "fileinto" { fileinto-options } string ";"
 239   fileinto-options =
 240   command          =/ fileinto-command
 241
 242 The extension "copy" is specified as:
 243
 244   fileinto-options =) ":copy"
 245   redirect-options =) ":copy"
 246
 247
 248 The i;ascii-numeric Comparator
 249
 250 RFC 2244 describes this comparator and specifies that non-numeric strings
 251 are considered equal with an ordinal value higher than any numeric string.
 252 Although not stated explicitly, this includes the empty string.  A range
 253 of at least 2^31 is required.  This implementation does not limit the
 254 range, because it does not convert numbers to binary representation
 255 before comparing them.
 256
 257
 258 The vacation extension
 259
 260 The extension "vacation" is specified using the following grammar
 261 extension.
 262
 263   vacation-command =  "vacation" { vacation-options } <reason: string>
 264   vacation-options =  [":days" number]
 265                       [":subject" string]
 266                       [":from" string]
 267                       [":addresses" string-list]
 268                       [":mime"]
 269                       [":handle" string]
 270   command          =/ vacation-command
 271
 272
 273 Semantics Of ":mime"
 274
 275 The draft does not specify how strings using MIME entities are used
 276 to compose messages.  As a result, different implementations generate
 277 different mails.  The Exim Sieve implementation splits the reason into
 278 header and body.  It adds the header to the mail header and uses the body
 279 as mail body.  Be aware, that other imlementations compose a multipart
 280 structure with the reason as only part.  Both conform to the specification
 281 (or lack thereof).
 282
 283
 284 Semantics Of Not Using ":mime"
 285
 286 Sieve scripts are written in UTF-8, so is the reason string in this
 287 case.  This implementation adds MIME headers to indicate that.  This
 288 is not required by the vacation draft, which does not specify how
 289 the UTF-8 reason is processed to compose the resulting message.
 290
 291
 292 Default Subject
 293
 294 RFC 5230 specifies that the default message subject is "Auto: " plus
 295 the old subject.  Using this subject is dangerous, because many mailing
 296 lists verify addresses by sending a secret key in the subject of a
 297 message, asking to reply to the message for confirmation.  Using the
 298 default vacation subject confirms any subscription request of this kind,
 299 allowing to subscribe a third party to any mailing list, either to annoy
 300 the user or to declare spam as legitimate mail by proving to use opt-in.
 301
 302
 303 Rate Limiting Responses
 304
 305 In absence of a handle, this implementation hashes the reason,
 306 ":subject" option, ":mime" option and ":from" option and uses the hex
 307 string representation as filename within the "sieve_vacation_directory"
 308 to store the recipient addresses for this vacation parameter set.
 309
 310 The draft specifies that sites may define a minimum ":days" value than 1.
 311 This implementation uses 1.  The maximum value MUST greater than 7,
 312 and SHOULD be greater than 30.  This implementation uses a maximum of 31.
 313
 314 Vacation recipient address databases older than 31 days are automatically
 315 removed.  Users do not have to remove them manually when modifying their
 316 scripts.  Don't put anything but vacation databases in that directory
 317 or you risk that it will be removed, too!
 318
 319
 320 Global Reply Address Blacklist
 321
 322 The draft requires that each implementation offers a global black list
 323 of addresses that will never be replied to.  Exim offers this as option
 324 "never_mail" in the autoreply transport.
 325
 326
 327 The enotify extension
 328
 329 The extension "enotify" is specified using the following grammar
 330 extension.
 331
 332   notify-command =  "notify" { notify-options } <method: string>
 333   notify-options =  [":from" string]
 334                     [":importance" <"1" / "2" / "3">]
 335                     [":options" 1*(string-list / number)]
 336                     [":message" string]
 337
 338   command          =/ notify-command
 339
 340   valid_notify_method = "valid_notify_method"
 341                         <notification-uris: string-list>
 342
 343   test             =/ valid_notify_method
 344
 345 Only the mailto URI scheme is implemented.