From a7ce01ede0582f33c7c327bc1b9296010532204e Mon Sep 17 00:00:00 2001
From: Stephan Bosch <stephan@rename-it.nl>
Date: Fri, 6 Jan 2012 23:03:12 +0100
Subject: [PATCH] Updated documentation and example config.
---
doc/editheader.txt | 4 +-
doc/example-config/conf.d/20-managesieve.conf | 27 +++---
doc/example-config/conf.d/90-sieve.conf | 60 +++++++++---
doc/spamtest-virustest.txt | 27 +++---
doc/vacation.txt | 92 +++++++++----------
5 files changed, 119 insertions(+), 91 deletions(-)
diff --git a/doc/editheader.txt b/doc/editheader.txt
index cc8cde912..b8a61c072 100644
--- a/doc/editheader.txt
+++ b/doc/editheader.txt
@@ -23,14 +23,14 @@ values are indicated):
sieve_editheader_max_header_size = 2048
The maximum size in bytes of a header field value passed to the addheader
- command. The minumum value for this setting is 1024 bytes. The value is in
+ command. The minimum value for this setting is 1024 bytes. The value is in
bytes, unless followed by a k(ilo).
sieve_editheader_protected =
A space-separated list of headers that cannot be added to nor removed from the
message header. The `Received:' and `Auto-Submitted:' fields are always
protected and the `Subject:' header cannot be protected, as required by the
- RFC specificiation; adding one of these headers to this setting has no effect.
+ RFC specification; adding one of these headers to this setting has no effect.
Invalid values for the settings above will make the Sieve interpreter log
a warning and revert to the default values.
diff --git a/doc/example-config/conf.d/20-managesieve.conf b/doc/example-config/conf.d/20-managesieve.conf
index 3dd24d9dc..995b8e0ed 100644
--- a/doc/example-config/conf.d/20-managesieve.conf
+++ b/doc/example-config/conf.d/20-managesieve.conf
@@ -37,16 +37,17 @@ service managesieve {
protocol sieve {
# Maximum ManageSieve command line length in bytes. ManageSieve usually does
- # not involve overly long command lines, so this setting will not normally need
- # adjustment
+ # not involve overly long command lines, so this setting will not normally
+ # need adjustment
#managesieve_max_line_length = 65536
- # Maximum number of ManageSieve connections allowed for a user from each IP address.
+ # Maximum number of ManageSieve connections allowed for a user from each IP
+ # address.
# NOTE: The username is compared case-sensitively.
#mail_max_userip_connections = 10
- # Space separated list of plugins to load (none known to be useful so far). Do NOT
- # try to load IMAP plugins here.
+ # Space separated list of plugins to load (none known to be useful so far).
+ # Do NOT try to load IMAP plugins here.
#mail_plugins =
# MANAGESIEVE logout format string:
@@ -54,20 +55,20 @@ protocol sieve {
# %o - total number of bytes sent to client
#managesieve_logout_format = bytes=%i/%o
- # To fool ManageSieve clients that are focused on CMU's timesieved you can specify
- # the IMPLEMENTATION capability that the dovecot reports to clients.
+ # To fool ManageSieve clients that are focused on CMU's timesieved you can
+ # specify the IMPLEMENTATION capability that Dovecot reports to clients.
# For example: 'Cyrus timsieved v2.2.13'
#managesieve_implementation_string = Dovecot Pigeonhole
- # Explicitly specify the SIEVE and NOTIFY capability reported by the server before
- # login. If left unassigned these will be reported dynamically according to what
- # the Sieve interpreter supports by default (after login this may differ depending
- # on the user).
+ # Explicitly specify the SIEVE and NOTIFY capability reported by the server
+ # before login. If left unassigned these will be reported dynamically
+ # according to what the Sieve interpreter supports by default (after login
+ # this may differ depending on the user).
#managesieve_sieve_capability =
#managesieve_notify_capability =
- # The maximum number of compile errors that are returned to the client upon script
- # upload or script verification.
+ # The maximum number of compile errors that are returned to the client upon
+ # script upload or script verification.
#managesieve_max_compile_errors = 5
# Refer to 90-sieve.conf for script quota configuration and configuration of
diff --git a/doc/example-config/conf.d/90-sieve.conf b/doc/example-config/conf.d/90-sieve.conf
index 2129aaaa3..725086db8 100644
--- a/doc/example-config/conf.d/90-sieve.conf
+++ b/doc/example-config/conf.d/90-sieve.conf
@@ -6,32 +6,64 @@
# by adding it to the respective mail_plugins= settings.
plugin {
- # The path to the user's main active script.
+ # The path to the user's main active script. If ManageSieve is used, this the
+ # location of the symbolic link controlled by ManageSieve.
sieve = ~/.dovecot.sieve
- # A path to a global sieve script file, which gets executed ONLY
- # if user's private Sieve script doesn't exist. Be sure to
- # pre-compile this script manually using the sievec command line
- # tool.
+ # The default Sieve script when the user has none. This is a path to a global
+ # sieve script file, which gets executed ONLY if user's private Sieve script
+ # doesn't exist. Be sure to pre-compile this script manually using the sievec
+ # command line tool.
+ # --> See sieve_before fore executing scripts before the user's personal
+ # script.
#sieve_global_path = /var/lib/dovecot/sieve/default.sieve
- # Directory for :personal include scripts for the include extension.
+ # Directory for :personal include scripts for the include extension. This
+ # is also where the ManageSieve service stores the user's scripts.
sieve_dir = ~/sieve
# Directory for :global include scripts for the include extension.
#sieve_global_dir =
- # Which Sieve language extensions are available to users. By default,
- # all supported extensions are available, except for deprecated
- # extensions or those that are still under development. Some system
- # administrators may want to disable certain Sieve extensions or
- # enable those that are not available by default. This setting can
- # use '+' and '-' to specify differences relative to the default.
- # For example `sieve_extensions = +imapflags' will enable the
- # deprecated imapflags extension in addition to all extensions
+ # Path to a script file or a directory containing script files that need to be
+ # executed before the user's script. If the path points to a directory, all
+ # the Sieve scripts contained therein (with the proper .sieve extension) are
+ # executed. The order of execution is determined by the file names, using a
+ # normal 8bit per-character comparison.
+ #sieve_before =
+
+ # Identical to sieve_before, only the specified scripts are executed after the
+ # user's script (only when keep is still in effect!).
+ #sieve_after =
+
+ # Which Sieve language extensions are available to users. By default, all
+ # supported extensions are available, except for deprecated extensions or
+ # those that are still under development. Some system administrators may want
+ # to disable certain Sieve extensions or enable those that are not available
+ # by default. This setting can use '+' and '-' to specify differences relative
+ # to the default. For example `sieve_extensions = +imapflags' will enable the
+ # deprecated imapflags extension in addition to all extensions were already
# enabled by default.
#sieve_extensions = +notify +imapflags
+ # Which Sieve language extensions are ONLY available in global scripts. This
+ # can be used to restrict the use of certain Sieve extensions to administrator
+ # control, for instance when these extensions can cause security concerns.
+ # This setting has higher precedence than the `sieve_extensions' setting
+ # (above), meaning that the extensions enabled with this setting are never
+ # available to the user's personal script no matter what is specified for the
+ # `sieve_extensions' setting. The syntax of this setting is similar to the
+ # `sieve_extensions' setting, with the difference that extensions are
+ # enabled or disabled for exclusive use in global scripts. Currently, no
+ # extensions are marked as such by default.
+ #sieve_global_extensions =
+
+ # The Pigeonhole Sieve interpreter can have plugins of its own. Using this
+ # setting, the used plugins can be specified. Check the Dovecot wiki
+ # (wiki2.dovecot.org) or the pigeonhole website
+ # (http://pigeonhole.dovecot.org) for available plugins.
+ #sieve_plugins =
+
# The separator that is expected between the :user and :detail
# address parts introduced by the subaddress extension. This may
# also be a sequence of characters (e.g. '--'). The current
diff --git a/doc/spamtest-virustest.txt b/doc/spamtest-virustest.txt
index c70da7559..4920c9962 100644
--- a/doc/spamtest-virustest.txt
+++ b/doc/spamtest-virustest.txt
@@ -15,8 +15,8 @@ need to be checked and how the scanner's verdict is represented in the header
field value. They only need to know how to use the spamtest (spamtestplus) and
virustest extensions. This also gives GUI-based Sieve editors the means to
provide a portable and easy to install interface for spam and virus filter
-configuration. The burden of specifying which headers need to be checked and
-how the scanner output is represented falls onto the Sieve administrator.
+configuration. The burden of specifying which headers need to be checked and how
+the scanner output is represented falls onto the Sieve administrator.
Configuration
=============
@@ -37,14 +37,14 @@ sieve_spamtest_status_type = "score" / "strlen" / "text"
sieve_spamtest_status_header = <header-field> [ ":" <regexp> ]
This specifies the header field that contains the result information of the
- spam scanner and it may express the syntax of the content of the header. If
- no matching header is found in the message, the spamtest command will match
+ spam scanner and it may express the syntax of the content of the header. If no
+ matching header is found in the message, the spamtest command will match
against "0".
This is a structured setting. The first part specifies the header field name.
- Optionally, a POSIX regular expression follows the header field name,
+ Optionally, a POSIX regular expression follows the header field name,
separated by a colon. Any whitespace directly following the colon is not part
- of the regular expression. If the regular expression is ommitted, any header
+ of the regular expression. If the regular expression is omitted, any header
content is accepted and the full header value is used. When a regular
expression is used, it must specify one match value (inside brackets) that
yields the desired spam scanner result. If the header does not match the
@@ -62,18 +62,17 @@ sieve_spamtest_max_header = <header-field> [ ":" <regexp> ]
`sieve_spamtext_status_header' setting.
sieve_spamtest_text_valueX =
- When the `sieve_spamtest_status_type' setting is set to "text", these
- settings specify that the spamtest command will match against "X" when
- the specified string is equal to the text (extracted) from the status
- header. For spamtest, values of X between 0 and 10 are recognized, while
- virustest only uses values between 0 and 5.
+ When the `sieve_spamtest_status_type' setting is set to "text", these settings
+ specify that the spamtest command will match against "X" when the specified
+ string is equal to the text (extracted) from the status header. For spamtest,
+ values of X between 0 and 10 are recognized, while virustest only uses values
+ between 0 and 5.
Examples
========
-This section shows several configuration examples. Each example shows a
-specimen of valid virus/spam test headers that the given configuration will
-work on.
+This section shows several configuration examples. Each example shows a specimen
+of valid virus/spam test headers that the given configuration will work on.
Example 1
---------
diff --git a/doc/vacation.txt b/doc/vacation.txt
index 1424ab19b..703c14cae 100644
--- a/doc/vacation.txt
+++ b/doc/vacation.txt
@@ -9,76 +9,72 @@ Relevant specifications
Description
===========
-The Sieve vacation extension [RFC5230] defines a mechanism to generate
-automatic replies to incoming email messages. It takes various
-precautions to make sure replies are only sent when appropriate. Script
-authors specify how often replies are sent to a particular contact.
-In the original vacation extension, this interval is specified in days
-with a minimum of one day. When more granularity is necessary and
-particularly when replies must be sent more frequently than one day,
-the vacation-seconds extension [RFC6131] can be used. This allows
-specifying the minimum reply interval in seconds with a minimum of zero
-(reply is then always sent), depending on administrator configuration.
+The Sieve vacation extension [RFC5230] defines a mechanism to generate automatic
+replies to incoming email messages. It takes various precautions to make sure
+replies are only sent when appropriate. Script authors specify how often replies
+are sent to a particular contact. In the original vacation extension, this
+interval is specified in days with a minimum of one day. When more granularity
+is necessary and particularly when replies must be sent more frequently than one
+day, the vacation-seconds extension [RFC6131] can be used. This allows
+specifying the minimum reply interval in seconds with a minimum of zero (reply
+is then always sent), depending on administrator configuration.
Configuration
=============
The vacation extension is available by default. In contrast, the
-vacation-seconds extension - which implies the vacation extension when
-used - is not available by default and needs to be enabled explicitly by
-adding it to the sieve_extensions setting. The configuration also needs
-to be adjusted accordingly to allow a non-reply period of less than a
-day.
+vacation-seconds extension - which implies the vacation extension when used - is
+not available by default and needs to be enabled explicitly by adding it to the
+sieve_extensions setting. The configuration also needs to be adjusted
+accordingly to allow a non-reply period of less than a day.
-The vacation and vacation-seconds extensions have their own specific
-settings. The settings that specify a period are specified in
-s(econds), unless followed by a d(ay), h(our) or m(inute) specifier
-character.
+The vacation and vacation-seconds extensions have their own specific settings.
+The settings that specify a period are specified in s(econds), unless followed
+by a d(ay), h(our) or m(inute) specifier character.
The following settings can be configured for the vacation extension (default
values are indicated):
sieve_vacation_min_period = 1d
- This specifies the minimum period that can be specified for the :days
- and :seconds tags of the vacation command. A minimum of 0 indicates that
- users are allowed to make the Sieve interpreter send a vacation response
- message for every incoming message that meets the other reply criteria
- (refer to RFC5230). A value of zero is however not recommended.
+ This specifies the minimum period that can be specified for the :days and
+ :seconds tags of the vacation command. A minimum of 0 indicates that users are
+ allowed to make the Sieve interpreter send a vacation response message for
+ every incoming message that meets the other reply criteria (refer to RFC5230).
+ A value of zero is however not recommended.
sieve_vacation_max_period = 0
- This specifies the maximum period that can be specified for the :days tag
- of the vacation command. The configured value must be larger than the
+ This specifies the maximum period that can be specified for the :days tag of
+ the vacation command. The configured value must be larger than the
sieve_vacation_min_period setting. A value of 0 has a special meaning: it
indicates that there is no upper limit.
sieve_vacation_default_period = 7d
- This specifies the default period that is used when no :days or :seconds
- tag is specified. The configured value must lie between the
+ This specifies the default period that is used when no :days or :seconds tag
+ is specified. The configured value must lie between the
sieve_vacation_min_period and sieve_vacation_max_period.
sieve_vacation_use_original_recipient = no
- This specifies whether the original envelope recipient should be used in
- the check for implicit delivery. The vacation command checks headers of
- the incoming message, such as To: and Cc: for the address of the
- recipient, to verify that the message is explicitly addressed at the
- recipient. If the recipient address is not found, the vacation action
- will not trigger a response to prevent sending a reply when it is not
- appropriate. Normally only the final recipient address is used in this
- check. This setting allows including the original recipient specified in
- the SMTP session if available. This is useful to handle mail accounts
- with aliases. Use this option with caution: if you are using aliases that
- point to more than a single account, senders can get multiple vacation
- responses for a single message.
+ This specifies whether the original envelope recipient should be used in the
+ check for implicit delivery. The vacation command checks headers of the
+ incoming message, such as To: and Cc: for the address of the recipient, to
+ verify that the message is explicitly addressed at the recipient. If the
+ recipient address is not found, the vacation action will not trigger a
+ response to prevent sending a reply when it is not appropriate. Normally only
+ the final recipient address is used in this check. This setting allows
+ including the original recipient specified in the SMTP session if available.
+ This is useful to handle mail accounts with aliases. Use this option with
+ caution: if you are using aliases that point to more than a single account,
+ senders can get multiple vacation responses for a single message.
sieve_vacation_dont_check_recipient = no
- This disables the checks for implicit delivery entirely. This means that
- the vacation command does not verify that the message is explicitly
- addressed at the recipient. Use this option with caution. Specifying
- 'yes' will violate the Sieve standards and can cause vacation replies to
- be sent for messages not directly addressed at the recipient.
-
-Invalid values for the settings above will make the Sieve interpreter log
-a warning and revert to the default values.
+ This disables the checks for implicit delivery entirely. This means that the
+ vacation command does not verify that the message is explicitly addressed at
+ the recipient. Use this option with caution. Specifying 'yes' will violate the
+ Sieve standards and can cause vacation replies to be sent for messages not
+ directly addressed at the recipient.
+
+Invalid values for the settings above will make the Sieve interpreter log a
+warning and revert to the default values.
Example
=======
--
GitLab