diff options
Diffstat (limited to 'doc/wiki/Pigeonhole.Sieve.txt')
| -rw-r--r-- | doc/wiki/Pigeonhole.Sieve.txt | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/doc/wiki/Pigeonhole.Sieve.txt b/doc/wiki/Pigeonhole.Sieve.txt new file mode 100644 index 0000000..43e9578 --- /dev/null +++ b/doc/wiki/Pigeonhole.Sieve.txt @@ -0,0 +1,290 @@ +Pigeonhole Sieve Interpreter +============================ + +The <Pigeonhole project> [Pigeonhole.txt] provides Sieve support as a plugin +for Dovecot's <Local Delivery Agent (LDA)> [LDA.txt] and also for its +<LMTP.txt> service. The plugin implements a Sieve [http://www.sieve.info] +interpreter, which filters incoming messages using a script specified in the +Sieve language (RFC 5228 [http://tools.ietf.org/html/rfc5228/]). The Sieve +script is provided by the user and, using that Sieve script, the user can +customize how incoming messages are handled. Messages can be delivered to +specific folders, forwarded, rejected, discarded, etc. + +Configuration and Use +--------------------- + + * <Download and Installation> [Pigeonhole.Installation.txt] + * <Sieve Interpreter Configuration> [Pigeonhole.Sieve.Configuration.txt] + * <Sieve Usage Information> [Pigeonhole.Sieve.Usage.txt] + * <Sieve Script Examples> [Pigeonhole.Sieve.Examples.txt] + * <Sieve Interpreter Plugins> [Pigeonhole.Sieve.Plugins.txt] + * <Sieve Troubleshooting> [Pigeonhole.Sieve.Troubleshooting.txt] + +Supported Features +------------------ + +Sieve language has various <extensions> [Pigeonhole.Sieve.Extensions.txt]. You +can find more information about the extensions from the Sieve Mail Filtering +Language Charter [http://www.ietf.org/html.charters/sieve-charter.html] or the +Sieve.info wiki page [http://www.sieve.info/]. + +Note that Sieve doesn't support running external programs. + +The Pigeonhole Sieve interpreter recognizes the following Sieve extensions: + + * ++-----------------------------------------------------------------+------------+----------+----------------+ +| *Extension* | *Support | *Default | *Purpose* | +| | Status* | Enabled* | | ++-----------------------------------------------------------------+------------+----------+----------------+ +| body [http://tools.ietf.org/html/rfc5173/] | supported | yes | Allows | +| | | | evaluating the | +| | | | body of a | +| | | | message | ++-----------------------------------------------------------------+------------+----------+----------------+ +| copy [http://tools.ietf.org/html/rfc3894/] | supported | yes | Allows storing | +| | | | and forwarding | +| | | | messages | +| | | | without | +| | | | canceling the | +| | | | implicit keep | ++-----------------------------------------------------------------+------------+----------+----------------+ +| date [http://tools.ietf.org/html/rfc5260#section-4] | supported | yes | Adds the | +| | (v0.1.12+) | | ability to test| +| | | | date and time | +| | | | values in | +| | | | various ways | ++-----------------------------------------------------------------+------------+----------+----------------+ +| duplicate [http://tools.ietf.org/html/rfc7352] | supported | yes | Allows | +| | (v0.4.3+) | | detecting | +| | | | duplicate | +| | | | message | +| | | | deliveries | ++-----------------------------------------------------------------+------------+----------+----------------+ +| editheader [http://tools.ietf.org/html/rfc5293/] | supported | no | Adds the | +| | (v0.3.0+) | | ability to add | +| | | | and remove | +| | | | message header | +| | | | fields | ++-----------------------------------------------------------------+------------+----------+----------------+ +| encoded-character | supported | yes | Allows encoding| +| [http://tools.ietf.org/html/rfc5228#section-2.4.2.4] | | | special | +| | | | characters | +| | | | numerically | ++-----------------------------------------------------------------+------------+----------+----------------+ +| enotify [http://tools.ietf.org/html/rfc5435/] | supported | yes | Provides the | +| | (v0.1.3+) | | ability to send| +| | | | notifications | +| | | | by various | +| | | | means | +| | | | (currently only| +| | | | mailto) | ++-----------------------------------------------------------------+------------+----------+----------------+ +| envelope [http://tools.ietf.org/html/rfc5228#section-5.4] | supported | yes | Allows | +| | | | evaluating | +| | | | envelope parts,| +| | | | i.e. sender and| +| | | | recipient | ++-----------------------------------------------------------------+------------+----------+----------------+ +| environment [http://tools.ietf.org/html/rfc5183/] | supported | yes | Allows testing | +| | (v0.4.0+) | | against various| +| | | | labeled values | +| | | | from the | +| | | | execution | +| | | | environment | ++-----------------------------------------------------------------+------------+----------+----------------+ +| fileinto [http://tools.ietf.org/html/rfc5228#section-4.1] | supported | yes | Allows storing | +| | | | messages in | +| | | | folders other | +| | | | than INBOX | ++-----------------------------------------------------------------+------------+----------+----------------+ +| foreverypart [http://tools.ietf.org/html/rfc5703#section-3] | supported | yes | Allows | +| | (v0.4.14+) | | iterating | +| | | | through the | +| | | | message's MIME | +| | | | parts | ++-----------------------------------------------------------------+------------+----------+----------------+ +| ihave [http://tools.ietf.org/html/rfc5463/] | supported | yes | Adds the | +| | (v0.2.4+) | | ability to test| +| | | | for support of | +| | | | Sieve | +| | | | extensions and | +| | | | dynamically | +| | | | invoke their use| ++-----------------------------------------------------------------+------------+----------+----------------+ +| imap4flags [http://tools.ietf.org/html/rfc5232/] | supported | yes | Allows adding | +| | | | IMAP flags to | +| | | | stored messages| ++-----------------------------------------------------------------+------------+----------+----------------+ +| imapsieve [http://tools.ietf.org/html/rfc6785/] | supported | no | Provides access| +| | (v0.4.14+) | (plugin) | to special | +| | | | environment | +| | | | items when | +| | | | executing at | +| | | | IMAP events | ++-----------------------------------------------------------------+------------+----------+----------------+ +| include [http://tools.ietf.org/html/rfc6609/] | supported | yes | Allows | +| | (v0.4.0+) | | including other| +| | | | Sieve scripts | ++-----------------------------------------------------------------+------------+----------+----------------+ +| index [http://tools.ietf.org/html/rfc5260#section-6] | supported | yes | Allows matching| +| | (v0.4.7+) | | specific header| +| | | | field instances| +| | | | by index | ++-----------------------------------------------------------------+------------+----------+----------------+ +| mailbox [http://tools.ietf.org/html/rfc5490#section-3] | supported | yes | Provides a | +| | (v0.1.10+) | | mailbox | +| | | | existence check| +| | | | and allows | +| | | | creating | +| | | | mailboxes upon | +| | | | fileinto | ++-----------------------------------------------------------------+------------+----------+----------------+ +| mboxmetadata [http://tools.ietf.org/html/rfc5490] | supported | no | Provides access| +| | (v0.4.7+) | | to mailbox | +| | | | METADATA entries| ++-----------------------------------------------------------------+------------+----------+----------------+ +| mime [http://tools.ietf.org/html/rfc5703#section-4] | supported | yes | Allows testing | +| | (v0.4.14+) | | parts of | +| | | | structured MIME| +| | | | header fields | ++-----------------------------------------------------------------+------------+----------+----------------+ +| extracttext [http://tools.ietf.org/html/rfc5703#section-7] | supported | yes | Allows | +| | (v0.4.14+) | | extracting text| +| | | | from individual| +| | | | message MIME | +| | | | parts | ++-----------------------------------------------------------------+------------+----------+----------------+ +| regex | supported | yes | Provides | +| [http://tools.ietf.org/html/draft-murchison-sieve-regex-08/] | | | regular | +| | | | expression | +| | | | match support | ++-----------------------------------------------------------------+------------+----------+----------------+ +| reject [http://tools.ietf.org/html/rfc5429#section-2.2] | supported | yes | Allows | +| | | | rejecting | +| | | | messages with a| +| | | | rejection | +| | | | bounce message | ++-----------------------------------------------------------------+------------+----------+----------------+ +| relational [http://tools.ietf.org/html/rfc5231/] | supported | yes | Provides | +| | | | relational | +| | | | match support | ++-----------------------------------------------------------------+------------+----------+----------------+ +| servermetadata [http://tools.ietf.org/html/rfc5490] | supported | no | Provides access| +| | (v0.4.7+) | | to server | +| | | | METADATA entries| ++-----------------------------------------------------------------+------------+----------+----------------+ +| spamtest [http://tools.ietf.org/html/rfc5235/] | supported | no | Implements a | +| | (v0.1.16+) | | uniform way to | +| | | | test against | +| | | | headers added | +| | | | by spam filters| ++-----------------------------------------------------------------+------------+----------+----------------+ +| subaddress [http://tools.ietf.org/html/rfc5233/] | supported | yes | Allows testing | +| | | | against | +| | | | delimited | +| | | | elements of the| +| | | | local part of | +| | | | addresses | ++-----------------------------------------------------------------+------------+----------+----------------+ +| vacation [http://tools.ietf.org/html/rfc5230/] | supported | yes | Provides | +| | | | auto-responder | +| | | | functionality, | +| | | | e.g. for when | +| | | | the user is on | +| | | | vacation | ++-----------------------------------------------------------------+------------+----------+----------------+ +| vacation-seconds [http://tools.ietf.org/html/rfc6131/] | supported | no | Extends | +| | (0.2.3+) | | vacation | +| | | | extension with | +| | | | the ability to | +| | | | send vacation | +| | | | responses with | +| | | | intervals of | +| | | | seconds rather | +| | | | than days | ++-----------------------------------------------------------------+------------+----------+----------------+ +| variables [http://tools.ietf.org/html/rfc5229/] | supported | yes | Adds variables | +| | | | support to the | +| | | | language | ++-----------------------------------------------------------------+------------+----------+----------------+ +| virustest [http://tools.ietf.org/html/rfc5235/] | supported | no | Implements a | +| | (v0.1.16+) | | uniform way to | +| | | | test against | +| | | | headers added | +| | | | by virus | +| | | | scanners | ++-----------------------------------------------------------------+------------+----------+----------------+ +| imapflags(obsolete draft | deprecated | no | Old version of | +| [http://tools.ietf.org/html/draft-melnikov-sieve-imapflags-03]) | | | imap4flags (for| +| | | | backwards | +| | | | compatibility | +| | | | with CMU Sieve)| ++-----------------------------------------------------------------+------------+----------+----------------+ +| notify (obsolete draft | deprecated | no | Old version of | +| [http://tools.ietf.org/html/draft-martin-sieve-notify-01]) | | | enotify (for | +| | | | backwards | +| | | | compatibility | +| | | | with CMU Sieve)| ++-----------------------------------------------------------------+------------+----------+----------------+ + +The following Dovecot-specific Sieve extensions are available for the +Pigeonhole Sieve interpreter: + + * ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| *Extension* | *Support Status* | *Default | *Purpose* | +| | | Enabled* | | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.debug | supported (v0.3.0+) | no | Allows logging debug messages | +| [https://raw.githubusercontent.com/dovecot/pigeonhole/master/doc/rfc/spec-bosch-sieve-debug.txt] | | | | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.environment | supported (v0.4.14+) | no | Extends the standard "environment" | +| [https://raw.githubusercontent.com/dovecot/pigeonhole/master/doc/rfc/spec-bosch-sieve-dovecot-environment.txt] | | | extension with extra items and a | +| | | | variables namespace for direct access | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.execute | <plugin> | no | Implements executing a pre-defined set | +| [https://raw.githubusercontent.com/dovecot/pigeonhole/master/doc/rfc/spec-bosch-sieve-extprograms.txt] | [Pigeonhole.Sieve.Plugins.Extprograms.txt] | | of external programs with the option to| +| | (v0.3+) | | process string data through the | +| | | | external program | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.extdata | <plugin> | no | Allows a Sieve script to lookup | +| [http://hg.rename-it.nl/pigeonhole-0.2-sieve-extdata/raw-file/tip/doc/rfc/spec-bosch-sieve-external-data.txt] | [Pigeonhole.Sieve.Plugins.Extdata.txt] | | information from a datasource external | +| | | | to the script | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.filter | <plugin> | no | Implements filtering messages through a| +| [https://raw.githubusercontent.com/dovecot/pigeonhole/master/doc/rfc/spec-bosch-sieve-extprograms.txt] | [Pigeonhole.Sieve.Plugins.Extprograms.txt] | | pre-defined set of external programs | +| | (v0.3+) | | | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.pipe | <plugin> | no | Implements piping messages to a | +| [https://raw.githubusercontent.com/dovecot/pigeonhole/master/doc/rfc/spec-bosch-sieve-extprograms.txt] | [Pigeonhole.Sieve.Plugins.Pipe.txt] (v0.2),| | pre-defined set of external programs | +| | <plugin> | | | +| | [Pigeonhole.Sieve.Plugins.Extprograms.txt] | | | +| | (v0.3+) | | | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ +| vnd.dovecot.report | supported (v0.4.14+) | no | Implements sending Messaging Abuse | +| [https://raw.githubusercontent.com/dovecot/pigeonhole/master/doc/rfc/spec-bosch-sieve-report.txt] | | | Reporting Format (MARF) reports (RFC | +| | | | 5965 | +| | | | [http://tools.ietf.org/html/rfc5965/]) | ++----------------------------------------------------------------------------------------------------------------+--------------------------------------------+----------+----------------------------------------+ + +Please note that not all extensions are enabled by default, as shown in the +table above. Deprecated extensions, extensions that add the ability to change +messages, extensions that require explicit configuration and extensions that +are still under development are not enabled without explicit <configuration> +[Pigeonhole.Sieve.Configuration.txt]. This means that the 'sieve_extensions' or +'sieve_global_extensions' settings need to be adjusted accordingly. Also, for +<plugins> [Pigeonhole.Sieve.Plugins.txt] it is not enough to add the plugin +name to the 'sieve_plugins' setting; the extensions introduced by the plugin +also need to be enabled explicitly. + +ManageSieve server +------------------ + +To give users the ability to upload their own Sieve scripts to your server, +i.e. without the need for shell or FTP access, you can use the Manage ''Sieve +protocol. This is also provided by the <Pigeonhole.txt> project. It is +available as a separate Dovecot service. Its configuration and use is explained +on the <Pigeonhole ManageSieve page> [Pigeonhole.ManageSieve.txt]. + +(This file was created from the wiki on 2019-06-19 12:42) |