summaryrefslogtreecommitdiffstats
path: root/doc/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/README65
-rw-r--r--doc/README.SIEVE343
2 files changed, 408 insertions, 0 deletions
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..a019ab8
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,65 @@
+Exim Documentation
+------------------
+
+This directory should contain the following files:
+
+ ChangeLog most recent log of all changes to Exim
+ NewStuff features that haven't made it to the manual yet,
+ and/or a list of newly-added functionality
+ OptionLists.txt lists of all Exim's options
+ README this document
+ README.SIEVE notes on the Sieve support
+ Exim3.upgrade information about upgrading from release 2.12 to 3.00
+ Exim4.upgrade information about upgrading from release 3.33 to 4.00
+ dbm.discuss.txt discussion of DBM libraries
+ filter.txt specification of filter file contents
+ spec.txt main specification of Exim
+ experimental-spec.txt specification of experimental features
+
+
+PostScript
+----------
+
+The Exim specifications are also available in PostScript. This is not included
+in the main distribution because not everyone wants it. Wherever you got this
+distribution from should also have carried another file called
+exim-postscript-<version>.tar.gz which contains the PostScript documentation.
+When de-tarred it creates a directory called exim-postscript-<version> into
+which it places the files doc/filter.ps and doc/spec.ps.
+
+
+HTML
+----
+
+A conversion from the original sources into HTML is done to create the online
+documentation at http://www.exim.org. This set of files is also available for
+installation on other servers. Wherever you got this distribution from should
+also have carried another file called exim-html-<version>.tar.gz which contains
+the HTML documentation. When de-tarred it creates a directory called
+exim-html-<version> into which it places a directory called doc/html containing
+the set of HTML files. The kick off point is the traditional index.html.
+
+
+PDF
+---
+
+The Exim specifications are available in Portable Document Format. Wherever you
+got this distribution from should also have carried another file called
+exim-pdf-<version>.tar.gz which contains the PDF documentation. When de-tarred
+it creates a directory called exim-pdf-<version> into which it places the files
+doc/filter.pdf and doc/spec.pdf.
+
+
+TeXinfo
+-------
+
+A version of the documentation that has been converted to TeXinfo format is
+available in the distribution file exim-texinfo-<version>.gz. When de-tarred it
+creates a directory called exim-texinfo-<version> into which it places the
+files doc/filter.texinfo and doc/spec.texinfo.
+
+The conversion process is automatic, so the result isn't as nice as
+hand-maintained TeXinfo files would be, and some information is lost; for
+example, TeXinfo does not support the use of change bars.
+
+-- End --
diff --git a/doc/README.SIEVE b/doc/README.SIEVE
new file mode 100644
index 0000000..d36998f
--- /dev/null
+++ b/doc/README.SIEVE
@@ -0,0 +1,343 @@
+ Notes on the Sieve implementation for Exim
+
+Exim Filter Versus Sieve Filter
+
+Exim supports two incompatible filters: The traditional Exim filter and
+the Sieve filter. Since Sieve is a extensible language, it is important
+to understand "Sieve" in this context as "the specific implementation
+of Sieve for Exim".
+
+The Exim filter contains more features, such as variable expansion, and
+better integration with the host environment, like external processes
+and pipes.
+
+Sieve is a standard for interoperable filters, defined in RFC 5228,
+with multiple implementations around. If interoperability is important,
+then there is no way around it.
+
+
+Exim Implementation
+
+The Exim Sieve implementation offers the core as defined by RFC 5228,
+the "encoded-character" extension (RFC 5228), the "envelope" test (RFC
+5228), the "fileinto" action (5228), the "copy" parameter (RFC 3894), the
+"vacation" action (5230), the "notify" action (draft-ietf-sieve-notify-12)
+with mailto URIs (draft-ietf-sieve-notify-mailto-05), the
+"i;ascii-numeric" comparator (RFC 2244) and the subaddress parameter
+(RFC 5233).
+
+The Sieve filter is integrated in Exim and works very similar to the
+Exim filter: Sieve scripts are recognized by the first line containing
+"# sieve filter". When using "keep" or "fileinto" to save a mail into a
+folder, the resulting string is available as the variable $address_file
+in the transport that stores it. The following routers and transport
+show a typical use of Sieve:
+
+begin routers
+
+localuser_verify:
+ driver = accept
+ domains = +localdomains
+ local_part_suffix = "-*"
+ local_part_suffix_optional
+ check_local_user
+ require_files = $home/.forward
+ verify_only = true
+
+localuser_deliver:
+ driver = redirect
+ domains = +localdomains
+ local_part_suffix = "-*"
+ local_part_suffix_optional
+ sieve_subaddress = "${sg{$local_part_suffix}{^-}{}}"
+ sieve_useraddress = "$local_part"
+ check_local_user
+ require_files = $home/.forward
+ file = $home/.forward
+ check_ancestor
+ allow_filter
+ file_transport = localuser
+ reply_transport = vacation
+ sieve_vacation_directory = $home/mail/vacation
+ verify = false
+
+begin transports
+
+localuser:
+ driver = appendfile
+ file = ${if eq{$address_file}{inbox} \
+ {/var/mail/$local_part} \
+ {${if eq{${substr_0_1:$address_file}}{/} \
+ {$address_file} \
+ {$home/mail/$address_file} \
+ }} \
+ }
+ delivery_date_add
+ envelope_to_add
+ return_path_add
+ mode = 0600
+
+vacation:
+ driver = autoreply
+
+Absolute files are stored where specified, relative files are stored
+relative to $home/mail and "inbox" goes to the standard mailbox location.
+To enable "vacation", sieve_vacation_directory is set to the directory
+where vacation databases are held (don't put anything else in that
+directory) and point reply_transport to an autoreply transport.
+Setting the Sieve useraddress and subaddress allows to use the subaddress
+extension.
+
+
+RFC Compliance
+
+Exim requires the first line to be "# sieve filter". Of course the RFC
+does not enforce that line. Don't expect examples to work without adding
+it, though.
+
+RFC 5228 requires using CRLF to terminate the end of a line.
+The rationale was that CRLF is universally used in network protocols
+to mark the end of the line. This implementation does not embed Sieve
+in a network protocol, but uses Sieve scripts as part of the Exim MTA.
+Since all parts of Exim use \n as newline character, this implementation
+does, too. You can change this by defining the macro RFC_EOL at compile
+time to enforce CRLF being used.
+
+The folder specified by "fileinto" must not contain the character
+sequence ".." to avoid security problems. RFC 5228 does not specify the
+syntax of folders apart from keep being equivalent to fileinto "INBOX".
+This implementation uses "inbox" instead.
+
+Sieve script errors currently cause that messages are silently filed into
+"inbox". RFC 5228 requires that the user is notified of that condition.
+This may be implemented in future by adding a header line to mails that
+are filed into "inbox" due to an error in the filter.
+
+The automatic replies generated by "vacation" do not contain an updated
+"references" header field.
+
+
+Semantics Of Keep
+
+The keep command is equivalent to fileinto "inbox": It saves the
+message and resets the implicit keep flag. It does not set the
+implicit keep flag; there is no command to set it once it has
+been reset.
+
+
+Semantics Of Fileinto
+
+RFC 5228 does not specify if "fileinto" tries to create a mail folder,
+in case it does not exist. This implementation allows to configure
+that aspect using the appendfile transport options "create_directory",
+"create_file" and "file_must_exist". See the appendfile transport in
+the Exim specification for details.
+
+
+Allof And Anyof Test
+
+RFC 5228 does not specify if these tests use shortcut/lazy evaluation.
+Exim uses shortcut evaluation.
+
+
+Action Reordering
+
+RFC 5228 does not specify if actions may be executed out of order.
+Exim may execute them out of order, e.g. messages may be filed to
+folders or forwarded in a different order than specified, because
+those actions only setup delivery, but do not execute it themselves.
+
+
+Sieve Syntax And Semantics
+
+RFC 5228 uses a generic grammar as syntax for commands and tests and
+performs many checks during semantic analysis. Syntax is specified
+by grammar rules, semantics by natural language. The intention is to
+provide a framework for the syntax that describes current commands as
+well as future extensions, and describing commands by semantics.
+
+The following replacement for section 8.2 gives a grammar for specific
+commands of this implementation, thus removing most of the semantic
+analysis. Since the parser can not parse unsupported extensions, the
+result is strict error checking of any executed and not executed code
+until "stop" is executed or the end of the script is reached.
+
+8.2. Grammar
+
+The grammar is specified in ABNF with two extensions to describe tagged
+arguments that can be reordered and grammar extensions: { } denotes a
+sequence of symbols that may appear in any order. Example:
+
+ options = a b c
+ start = { options }
+
+is equivalent to:
+
+ start = ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
+
+The symbol =) is used to append to a rule:
+
+ start = a
+ start =) b
+
+is equivalent to
+
+ start = a b
+
+The basic Sieve commands are specified using the following grammar, which
+language is a subset of the generic grammar above. The start symbol is
+"start".
+
+ address-part = ":localpart" / ":domain" / ":all"
+ comparator = ":comparator" string
+ match-type = ":is" / ":contains" / ":matches"
+ string = quoted-string / multi-line
+ string-list = "[" string *("," string) "]" / string
+ address-test = "address" { [address-part] [comparator] [match-type] }
+ string-list string-list
+ test-list = "(" test *("," test) ")"
+ allof-test = "allof" test-list
+ anyof-test = "anyof" test-list
+ exists-test = "exists" string-list
+ false-test = "false"
+ true=test = "true"
+ header-test = "header" { [comparator] [match-type] }
+ string-list string-list
+ not-test = "not" test
+ relop = ":over" / ":under"
+ size-test = "size" relop number
+ block = "{" commands "}"
+ if-command = "if" test block *( "elsif" test block ) [ "else" block ]
+ stop-command = "stop" { stop-options } ";"
+ stop-options =
+ keep-command = "keep" { keep-options } ";"
+ keep-options =
+ discard-command = "discard" { discard-options } ";"
+ discard-options =
+ redirect-command = "redirect" { redirect-options } string ";"
+ redirect-options =
+ require-command = "require" { require-options } string-list ";"
+ require-options =
+ test = address-test / allof-test / anyof-test / exists-test
+ / false-test / true-test / header-test / not-test
+ / size-test
+ command = if-command / stop-command / keep-command
+ / discard-command / redirect-command
+ commands = *command
+ start = *require-command commands
+
+The extensions "envelope" and "fileinto" are specified using the following
+grammar extension.
+
+ envelope-test = "envelope" { [comparator] [address-part] [match-type] }
+ string-list string-list
+ test =/ envelope-test
+
+ fileinto-command = "fileinto" { fileinto-options } string ";"
+ fileinto-options =
+ command =/ fileinto-command
+
+The extension "copy" is specified as:
+
+ fileinto-options =) ":copy"
+ redirect-options =) ":copy"
+
+
+The i;ascii-numeric Comparator
+
+RFC 2244 describes this comparator and specifies that non-numeric strings
+are considered equal with an ordinal value higher than any numeric string.
+Although not stated explicitly, this includes the empty string. A range
+of at least 2^31 is required. This implementation does not limit the
+range, because it does not convert numbers to binary representation
+before comparing them.
+
+
+The vacation extension
+
+The extension "vacation" is specified using the following grammar
+extension.
+
+ vacation-command = "vacation" { vacation-options } <reason: string>
+ vacation-options = [":days" number]
+ [":subject" string]
+ [":from" string]
+ [":addresses" string-list]
+ [":mime"]
+ [":handle" string]
+ command =/ vacation-command
+
+
+Semantics Of ":mime"
+
+The draft does not specify how strings using MIME entities are used
+to compose messages. As a result, different implementations generate
+different mails. The Exim Sieve implementation splits the reason into
+header and body. It adds the header to the mail header and uses the body
+as mail body. Be aware, that other implementations compose a multipart
+structure with the reason as only part. Both conform to the specification
+(or lack thereof).
+
+
+Semantics Of Not Using ":mime"
+
+Sieve scripts are written in UTF-8, so is the reason string in this
+case. This implementation adds MIME headers to indicate that. This
+is not required by the vacation draft, which does not specify how
+the UTF-8 reason is processed to compose the resulting message.
+
+
+Default Subject
+
+RFC 5230 specifies that the default message subject is "Auto: " plus
+the old subject. Using this subject is dangerous, because many mailing
+lists verify addresses by sending a secret key in the subject of a
+message, asking to reply to the message for confirmation. Using the
+default vacation subject confirms any subscription request of this kind,
+allowing to subscribe a third party to any mailing list, either to annoy
+the user or to declare spam as legitimate mail by proving to use opt-in.
+
+
+Rate Limiting Responses
+
+In absence of a handle, this implementation hashes the reason,
+":subject" option, ":mime" option and ":from" option and uses the hex
+string representation as filename within the "sieve_vacation_directory"
+to store the recipient addresses for this vacation parameter set.
+
+The draft specifies that sites may define a minimum ":days" value than 1.
+This implementation uses 1. The maximum value MUST greater than 7,
+and SHOULD be greater than 30. This implementation uses a maximum of 31.
+
+Vacation recipient address databases older than 31 days are automatically
+removed. Users do not have to remove them manually when modifying their
+scripts. Don't put anything but vacation databases in that directory
+or you risk that it will be removed, too!
+
+
+Global Reply Address Blacklist
+
+The draft requires that each implementation offers a global black list
+of addresses that will never be replied to. Exim offers this as option
+"never_mail" in the autoreply transport.
+
+
+The enotify extension
+
+The extension "enotify" is specified using the following grammar
+extension.
+
+ notify-command = "notify" { notify-options } <method: string>
+ notify-options = [":from" string]
+ [":importance" <"1" / "2" / "3">]
+ [":options" 1*(string-list / number)]
+ [":message" string]
+
+ command =/ notify-command
+
+ valid_notify_method = "valid_notify_method"
+ <notification-uris: string-list>
+
+ test =/ valid_notify_method
+
+Only the mailto URI scheme is implemented.