INSTALL
author Stephan Bosch <stephan@rename-it.nl>
Tue Oct 28 01:39:14 2014 +0100 (2014-10-28)
changeset 1940 b3303f675157
parent 1888 8a793175f4ab
child 2027 5547d6d1778c
permissions -rw-r--r--
Released v0.4.4 for Dovecot v2.2.15.
     1 Compiling
     2 =========
     3 
     4 If you downloaded the sources using Mercurial, you will need to execute
     5 ./autogen.sh first to build the automake structure in your source tree. This
     6 process requires autotools and libtool to be installed.
     7 
     8 If you installed Dovecot from sources, Pigeonhole's configure script should be
     9 able to find the installed dovecot-config automatically:
    10 
    11 ./configure
    12 make
    13 sudo make install
    14 
    15 If your system uses a $prefix different than the default /usr/local, the
    16 configure script can still find the installed dovecot-config automatically when
    17 supplied with the proper --prefix argument:
    18 
    19 ./configure --prefix=/usr
    20 make
    21 sudo make install
    22 
    23 If this doesn't work, you can use --with-dovecot=<path> configure option, where
    24 the path points to a directory containing dovecot-config file. This can point to
    25 an installed file:
    26 
    27 ./configure --with-dovecot=/usr/local/lib/dovecot
    28 make
    29 sudo make install
    30 
    31 or to a Dovecot source directory that is already compiled:
    32 
    33 ./configure --with-dovecot=../dovecot-2.1.0
    34 make
    35 sudo make install
    36 
    37 The following additional parameters may be of interest for the configuration of
    38 the Pigeonhole build:
    39 
    40  --with-managesieve=yes
    41    Controls whether Pigeonhole ManageSieve is compiled and installed, which is
    42    the default.
    43 
    44  --with-unfinished-features=no
    45    Controls whether unfinished features and extensions are built. Enabling this
    46    will enable the compilation of code that is considered unfinished and highly
    47    experimental and may therefore introduce bugs and unexpected behavior.
    48    In fact, it may not compile at all. Enable this only when you are eager to
    49    test some of the new development functionality.
    50 
    51  --with-ldap=no
    52    Controls wether Sieve LDAP support is built. This allows retrieving Sieve
    53    scripts from an LDAP database. When set to `yes', support is built in. When
    54    set to `plugin', LDAP support is compiled into a Sieve plugin called
    55    `sieve_storage_ldap'.
    56 
    57 Configuration
    58 =============
    59 
    60 The Pigeonhole package provides the following items:
    61 
    62   - The Sieve interpreter plugin for Dovecot's Local Delivery Agent (LDA): This
    63     facilitates the actual Sieve filtering upon delivery.
    64 
    65   - The ManageSieve Service: This implements the ManageSieve protocol through
    66     which users can remotely manage Sieve scripts on the server.
    67 
    68 The functionality of these items is described in more detail in the README file.
    69 In this file and in this section their configuration is described. Example
    70 configuration files are provided in the doc/example-config directory of this
    71 package.
    72 
    73 Sieve Interpreter - Script Locations
    74 ------------------------------------
    75 
    76 The Sieve interpreter can retrieve Sieve scripts from several types of
    77 locations. The default `file' location type is a local filesystem path pointing
    78 to a Sieve script file or a directory containing multiple Sieve script files.
    79 More complex setups can use other location types such as `ldap' or `dict' to
    80 fetch Sieve scripts from remote databases.
    81 
    82 All settings that specify the location of one ore more Sieve scripts accept the
    83 following syntax:
    84 
    85 location = [<type>:]path[;<option>[=<value>][;...]]
    86 
    87 The following script location types are implemented by default:
    88 
    89   file    - The location path is a file system path pointing to the script file
    90             or a directory containing script files with names structured as
    91             `<script-name>.sieve'.
    92   dict    - Dovecot dict lookup. The location path is a dict uri. Read
    93             doc/scipt-location-dict.txt for more information and examples.
    94   ldap    - LDAP database lookup. The location path is a configuration file with
    95             LDAP options. Read doc/scipt-location-ldap.txt for more information
    96             and examples.
    97 
    98 If the type prefix is omitted, the script location type is 'file' and the 
    99 location is interpreted as a local filesystem path pointing to a Sieve script
   100 file or directory.
   101 
   102 The following options are defined for all location types:
   103 
   104   name=<script-name>
   105     Set the name of the Sieve script that this location points to. If the name
   106     of the Sieve script is not contained in the location path and the
   107     location of a single script is specified, this option is required
   108     (e.g. for dict locations that must point to a particular script).
   109     If the name of the script is contained in the location path, the value of
   110     the name option overrides the name retrieved from the location. If the Sieve
   111     interpreter explicitly queries for a specific name (e.g. to let the Sieve
   112     "include" extension retrieve a script from the sieve_global= location),
   113     this option has no effect.
   114 
   115   bindir=<dirpath>
   116     Points to the directory where the compiled binaries for this script location
   117     are stored. This directory is created automatically if possible. If this
   118     option is omitted, the behavior depends on the location type. For `file'
   119     type locations, the binary is then stored in the same directory as where the
   120     script file was found if possible. For `dict' type locations, the binary is
   121     not stored at all in that case. Don't specify the same directory for
   122     different script locations, as this will result in undefined behavior.
   123     Multiple mail users can share a single script directory if the script
   124     location is the same and all users share the same system credentials (uid,
   125     gid).
   126 
   127 Sieve Interpreter - Basic Configuration
   128 ---------------------------------------
   129 
   130 To use Sieve, you will first need to make sure you are using Dovecot LDA
   131 or Dovecot LMTP for delivering incoming mail to users' mailboxes. Then, you need
   132 to enable the Sieve interpreter plugin for LDA/LMTP in your dovecot.conf:
   133 
   134 protocol lda {
   135 ..
   136   mail_plugins = sieve # ... other plugins like quota
   137 }
   138 
   139 protocol lmtp {
   140 ..
   141   mail_plugins = sieve # ... other plugins like quota
   142 }
   143 
   144 The Sieve interpreter recognizes the following configuration options in the
   145 plugin section of the config file (default values are shown if applicable):
   146 
   147  sieve = ~/.dovecot.sieve
   148    The location of the user's main Sieve script or script storage. The LDA
   149    Sieve plugin uses this to find the active script for Sieve filtering at
   150    delivery. The "include" extension uses this location for retrieving
   151    :personal" scripts. This is also where the  ManageSieve service will store
   152    the user's scripts, if supported by the location type.
   153 
   154  sieve_default =
   155    The location of the default personal sieve script file, which gets executed
   156    ONLY if user's private Sieve script does not exist, e.g.
   157    /var/lib/dovecot/default.sieve. This is usually a global script, so be sure
   158    to pre-compile this script manually using the sievec command line tool, as
   159    explained in the README file. This setting used to be called
   160    `sieve_global_path', but that name is now deprecated.
   161 
   162  sieve_global =
   163    Location for :global include scripts for the Sieve include extension. This
   164    setting used to be called `sieve_global_dir', but that name is now
   165    deprecated.
   166 
   167  sieve_extensions =
   168    Which Sieve language extensions are available to users. By default, all
   169    supported extensions are available, except for deprecated extensions or those
   170    that are still under development. Some system administrators may want to
   171    disable certain Sieve extensions or enable those that are not available by
   172    default. This setting can use '+' and '-' to specify differences relative to
   173    the default. For example `sieve_extensions = +imapflags' will enable the
   174    deprecated imapflags extension in addition to all extensions were already
   175    enabled by default.
   176 
   177  sieve_global_extensions =
   178    Which Sieve language extensions are ONLY avalable in global scripts. This can
   179    be used to restrict the use of certain Sieve extensions to administrator
   180    control, for instance when these extensions can cause security concerns. This
   181    setting has higher precedence than the `sieve_extensions' setting (above),
   182    meaning that the extensions enabled with this setting are never available to
   183    the user's personal script no matter what is specified for the
   184    `sieve_extensions' setting. The syntax of this setting is similar to
   185    the `sieve_extensions' setting, with the difference that extensions are
   186    enabled or disabled for exclusive use in global scripts. Currently, no
   187    extensions are marked as such by default.
   188 
   189  sieve_plugins =
   190    The Pigeonhole Sieve interpreter can have plugins of its own. Using this
   191    setting, the used plugins can be specified. Check the Dovecot wiki
   192    (wiki2.dovecot.org) or the pigeonhole website (http://pigeonhole.dovecot.org)
   193    for available plugins. The `sieve_extprograms' plugin is included in this
   194    release. LDAP support may also be compiled as a plugin called
   195    `sieve_storage_ldap'.
   196 
   197  sieve_user_log =
   198    The path to the file where the user log file is written. If not configured, a
   199    default location is used. If the main user's personal Sieve (as configured
   200    with sieve=) is a file, the logfile is set to <filename>.log by default. If
   201    it is not a file, the default user log file is ~/.dovecot.sieve.log.
   202 
   203  recipient_delimiter = +
   204    The separator that is expected between the :user and :detail address parts
   205    introduced by the subaddress extension. This may also be a sequence of
   206    characters (e.g. '--'). The current implementation looks for the separator
   207    from the left of the localpart and uses the first one encountered. The :user
   208    part is left of the separator and the :detail part is right. This setting is
   209    also used by Dovecot's LMTP service.
   210 
   211  sieve_redirect_envelope_from = sender
   212    Specifies what envelope sender address is used for redirected messages.
   213    Normally, the Sieve "redirect" command copies the sender address for the
   214    redirected message from the  processed message. So, the redirected message
   215    appears to originate from the original sender. The following values are
   216    supported for this setting:
   217    
   218      "sender"         - The sender address is used (default)
   219      "recipient"      - The final recipient address is used
   220      "orig_recipient" - The original recipient is used
   221      "<user@domain>"  - Redirected messages are always sent from user@domain.
   222                         The angle brackets are mandatory. The null "<>" address
   223                         is also supported.
   224 
   225 	 When the envelope sender of the processed message is the null address "<>",
   226    the envelope sender of the redirected message is also always "<>",
   227    irrespective of what is configured for this setting. 
   228 
   229 For example:
   230 
   231 plugin {
   232 ...
   233   # The include extension fetches the :personal scripts from this
   234   # directory. When ManageSieve is used, this is also where scripts
   235   # are uploaded.
   236   sieve = file:~/sieve
   237 
   238   # If the user has no personal active script (i.e. if the location
   239   # indicated in sieve= settings does have and active script or does not exist),
   240   # use this one:
   241   sieve_default = /var/lib/dovecot/sieve/default.sieve
   242 
   243   # The include extension fetches the :global scripts from this
   244   # directory.
   245   sieve_global = /var/lib/dovecot/sieve/global/
   246 }
   247 
   248 Sieve Interpreter - Configurable Limits
   249 ---------------------------------------
   250 
   251  sieve_max_script_size = 1M
   252    The maximum size of a Sieve script. The compiler will refuse to compile any
   253    script larger than this limit. If set to 0, no limit on the script size is
   254    enforced.
   255 
   256  sieve_max_actions = 32
   257    The maximum number of actions that can be performed during a single script
   258    execution. If set to 0, no limit on the total number of actions is enforced.
   259 
   260  sieve_max_redirects = 4
   261    The maximum number of redirect actions that can be performed during a single
   262    script execution. If set to 0, no redirect actions are allowed.
   263 
   264 Sieve Interpreter - Per-user Sieve Script Location
   265 --------------------------------------------------
   266 
   267 By default, the Pigeonhole LDA Sieve plugin looks for the user's Sieve script
   268 file in the user's home directory (~/.dovecot.sieve). This requires that the
   269 home directory is set for the user.
   270 
   271 If you want to store the script elsewhere, you can override the default using
   272 the sieve= setting, which specifies the location of the user's script file. This
   273 can be done in two ways:
   274 
   275  1. Define the sieve setting in the plugin section of dovecot.conf.
   276  2. Return sieve extra field from userdb extra fields.
   277 
   278 For example, to use a Sieve script file named <username>.sieve in
   279 /var/sieve-scripts, use:
   280 
   281 plugin {
   282 ...
   283 
   284  sieve = /var/sieve-scripts/%u.sieve
   285 }
   286 
   287 You may use templates like %u, as shown in the example. Refer to
   288 http://wiki.dovecot.org/Variables for more information.
   289 
   290 A relative path (or just a filename) will be interpreted to point under the
   291 user's home directory.
   292 
   293 Sieve Interpreter - Executing Multiple Scripts Sequentially
   294 -----------------------------------------------------------
   295 
   296 Pigeonhole's Sieve interpreter allows executing multiple Sieve scripts
   297 sequentially. The extra scripts can be executed before and after the user's
   298 private script. For example, this allows executing global Sieve policies before
   299 the user's script. The following settings in the plugin section of the Dovecot
   300 config file control the execution sequence:
   301 
   302  sieve_before =
   303  sieve_before2 =
   304  sieve_before3 = (etc..)
   305    Location Sieve of scripts that need to be executed before the user's personal
   306    script. If a 'file' location path points to a directory, all the Sieve
   307    scripts contained therein (with the proper `.sieve' extension) are executed.
   308    The order of execution within that directory is determined by the file names,
   309    using a normal 8bit per-character comparison.
   310 
   311    Multiple script locations can be specified by appending an increasing number
   312    to the setting name. The Sieve scripts found from these locations are added
   313    to the script execution sequence in the specified order. Reading the numbered
   314    sieve_before settings stops at the first missing setting, so no numbers may
   315    be skipped.
   316 
   317  sieve_after =
   318  sieve_after2 =
   319  sieve_after3 = (etc..)
   320    Identical to sieve_before, but the specified scripts are executed after the
   321    user's script (only when keep is still in effect, as explained below).
   322 
   323 The script execution ends when the currently executing script in the sequence
   324 does not yield a "keep" result: when the script terminates, the next script is
   325 only executed if an implicit or explicit "keep" is in effect. Thus, to end all
   326 script execution, a script must not execute keep and it must cancel the implicit
   327 keep, e.g. by executing "discard; stop;". This means that the command "keep;"
   328 has different semantics when used in a sequence of scripts. For normal Sieve
   329 execution, "keep;" is equivalent to "fileinto "INBOX";", because both cause the
   330 message to be stored in INBOX. However, in sequential script execution, it only
   331 controls whether the next script is executed. Storing the message into INBOX
   332 (the default folder) is not done until the last script in the sequence executes
   333 (implicit) keep. To force storing the message into INBOX earlier in the
   334 sequence, the fileinto command can be used (with ":copy" or together with
   335 "keep;").
   336 
   337 Apart from the keep action, all actions triggered in a script in the sequence
   338 are executed before continuing to the next script. This means that when a script
   339 in the sequence encounters an error, actions from earlier executed scripts are
   340 not affected. The sequence is broken however, meaning that the script execution
   341 of the offending script is aborted and no further scripts are executed. An
   342 implicit keep is executed instead if necessary, meaning that the interpreter
   343 makes sure that the message is at least stored in the default folder (INBOX).
   344 
   345 Just as for executing a single script the normal way, the Pigeonhole LDA Sieve
   346 plugin takes care never to duplicate deliveries, forwards or responses. When
   347 vacation actions are executed multiple times in different scripts, the usual
   348 error is not triggered: the subsequent duplicate vacation actions are simply
   349 discarded.
   350 
   351 For example:
   352 
   353 plugin {
   354 ...
   355    # Global scripts executed before the user's personal script.
   356    #   E.g. handling messages marked as dangerous
   357    sieve_before = /var/lib/dovecot/sieve/discard-virusses.sieve
   358 
   359    # Domain-level scripts retrieved from LDAP
   360    sieve_before2 = ldap:/etc/dovecot/sieve-ldap.conf;name=ldap-domain
   361 
   362    # User-specific scripts executed before the user's personal script.
   363    #   E.g. a vacation script managed through a non-ManageSieve GUI.
   364    sieve_before3 = /var/vmail/%d/%n/sieve-before
   365 
   366    # User-specific scripts executed after the user's personal script.
   367    # (if keep is still in effect)
   368    #   E.g. user-specific default mail filing rules
   369    sieve_after = /var/vmail/%d/%n/sieve-after
   370 
   371    # Global scripts executed after the user's personal script
   372    # (if keep is still in effect)
   373    #   E.g. default mail filing rules.
   374    sieve_after2 = /var/lib/dovecot/sieve/after.d/
   375 }
   376 
   377 IMPORTANT: The scripts specified by sieve_before and sieve_after are often
   378 located in global locations to which the Sieve interpreter has no write access
   379 to store the compiled binaries. In that case, be sure to manually pre-compile
   380 those scripts using the sievec tool, as explained in the README file.
   381 
   382 Sieve Interpreter - Extension Configuration
   383 -------------------------------------------
   384 
   385 - Editheader extension:
   386 
   387   The editheader extension [RFC5293] enables sieve scripts to interact with
   388   other components that consume or produce header fields by allowing the script
   389   to delete and add header fields.
   390 
   391   The editheader extension requires explicit configuration and is not enabled
   392   for use by default. Refer to doc/extensions/editheader.txt for configuration
   393   information.
   394 
   395 - Vacation extension:
   396 
   397   The Sieve vacation extension [RFC5230] defines a mechanism to generate
   398   automatic replies to incoming email messages.
   399 
   400   The vacation extension is available by default, but it has its own specific
   401   configuration options. Refer to doc/extensions/vacation.txt for settings
   402   specific to the vacation extension.
   403 
   404 - Include extension:
   405 
   406   The Sieve include extension (draft) permits users to include one Sieve script
   407   into another.
   408 
   409   The include extension is available by default, but it has its own specific
   410   configuration options. Refer to doc/extensions/include.txt for settings
   411   specific to the include extension.
   412 
   413 - Spamtest and virustest extensions:
   414 
   415   Using the spamtest and virustest extensions (RFC 5235), the Sieve language
   416   provides a uniform and standardized command interface for evaluating spam and
   417   virus tests performed on the message. Users no longer need to know what headers
   418   need to be checked and how the scanner's verdict is represented in the header
   419   field value. They only need to know how to use the spamtest (spamtestplus) and
   420   virustest extensions. This also gives GUI-based Sieve editors the means to
   421   provide a portable and easy to install interface for spam and virus filter
   422   configuration.
   423 
   424   The spamtest, spamtestplus and virustest extensions require explicit
   425   configuration and are not enabled for use by default. Refer to
   426   doc/extensions/spamtest-virustest.txt for configuration information.
   427 
   428 - Vnd.dovecot.duplicate extension:
   429 
   430   The vnd.dovecot.duplicate extension augments the Sieve filtering
   431   implementation with a test that allows detecting and handling duplicate
   432   message deliveries, e.g. as caused by mailinglists when people reply both to
   433   the mailinglist and the user directly.
   434 
   435   The vnd.dovecot.duplicate extension requires explicit configuration and is not
   436   enabled for use by default. Refer to doc/extensions/vnd.dovecot.duplicate.txt
   437   for configuration information.
   438 
   439 - Extprograms plugin;
   440     vnd.dovovecot.pipe, vnd.dovecot.filter, vnd.dovecot.execute extensions:
   441 
   442   The "sieve_extprograms" plugin provides extensions to the Sieve filtering
   443   language adding new action commands for invoking a predefined set of external
   444   programs. Messages can be piped to or filtered through those programs	and
   445   string data can be input to and retrieved from those programs.
   446 
   447   This plugin and the extensions it provides require explicit configuration and
   448   are not enabled for use by default. Refer to doc/plugins/sieve_extprograms.txt
   449 	for more information.
   450 
   451 Sieve Interpreter - Migration from CMUSieve (Dovecot v1.0/v1.1)
   452 ---------------------------------------------------------------
   453 
   454 For the most part, migration from CMUSieve to the Pigeonhole LDA Sieve plugin is
   455 just a matter of changing the used plugin name from 'cmusieve' to 'sieve' in the
   456 mail_plugins option in the protocol lda section of the config file (as explained
   457 above). However, there are a few important differences:
   458 
   459  * The imapflags extension is now called imap4flags. The CMUSieve implementation
   460    is based on an old draft specification that is not completely compatible.
   461    Particularly, the mark and unmark commands were removed from the new
   462    specification. For backwards compatibility, support for the old imapflags
   463    extension can be enabled using the sieve_extensions setting (as explained
   464    above). This is disabled by default.
   465 
   466  * The notify extension is now called enotify. The CMUSieve implementation is
   467    based on an old draft specification that is not completely compatible.
   468    Particularly, the denotify command and $text$ substitutions were removed from
   469    the new specification. For backwards compatibility, support for the old
   470    imapflags extension can be enabled using the sieve_extensions setting (as
   471    explained above). This is disabled by default.
   472 
   473  * The include extension now requires your script file names to end with
   474    ".sieve". This means that ` include :personal "myscript"; ' won't work unless
   475    you rename "myscript" to "myscript.sieve"
   476 
   477 Sieve Interpreter - Migration from Dovecot Sieve v0.1.x (Dovecot v1.2)
   478 ----------------------------------------------------------------------
   479 
   480  * Dovecot v2.0 adds support for LMTP. Much like the Dovecot LDA, it can make
   481    use of the Pigeonhole Sieve plugin. Since the LMTP service has its own
   482    prototocol lmtp section in the config file, you need to add the Sieve plugin
   483    to the mail_plugins setting there too when you decide to use LMTP.
   484  * The 'sieve_subaddress_sep' setting for the Sieve subaddress extension is now
   485    known as 'recipient_delimiter'. Although sieve_subaddress_sep is still
   486    recognized for backwards compatibility, it is recommended to update the
   487    setting to the new name, since the LMTP service also uses the
   488    recipient_delimiter setting.
   489 
   490 ManageSieve Service - Basic Configuration
   491 -----------------------------------------
   492 
   493 IMPORTANT:
   494 
   495   If you have used the LDA Sieve plugin without ManageSieve before and you have
   496   .dovecot.sieve files in user directories, you are advised to make a backup
   497   before installing ManageSieve. Although the ManageSieve service takes care to
   498   move these files to the Sieve directory before it is substituted with a
   499   symbolic link, this is not a very well tested operation, meaning that there is
   500   a slim possibility that existing Sieve scripts get lost.
   501 
   502 Just like all other binaries that Dovecot uses, the managesieve and
   503 managesieve-login binaries are installed during make install.
   504 
   505 There are two things that have be done to activate the ManageSieve support in
   506 Dovecot:
   507 
   508  * The first step is to add `sieve' to the protocols= configuration line in
   509    your dovecot.conf.
   510 
   511  * The next step is specifying an additional service type for the ManageSieve
   512    service. This could be done in Dovecot's conf.d/master.conf or you can use
   513    the 20-managesieve.conf file from the doc/example-config/conf.d directory of
   514    this package.
   515 
   516    For example:
   517 
   518     service managesieve-login {
   519       inet_listener sieve {
   520         port = 4190
   521       }
   522     }
   523 
   524 Because the implementation of the ManageSieve daemon is largely based on the
   525 original IMAP implementation, it is very similar in terms of configuration. The
   526 following settings can be configured in the 'protocol sieve' section:
   527 
   528  managesieve_max_line_length = 65536
   529    The maximum ManageSieve command line length in bytes. This setting is
   530    directly borrowed from IMAP. But, since long command lines are very unlikely
   531    with ManageSieve, changing this will not be very useful.
   532 
   533  managesieve_logout_format = bytes=%i/%o
   534    Specifies the string pattern used to compose the logout message of an
   535    authenticated session. The following substitutions are available:
   536 
   537      %i - total number of bytes read from client
   538      %o - total number of bytes sent to client
   539 
   540  managesieve_implementation_string = Dovecot Pigeonhole
   541    To fool ManageSieve clients that are focused on CMU's timesieved, you can
   542    specify the IMPLEMENTATION capability that the Dovecot reports to clients
   543    (e.g. 'Cyrus timsieved v2.2.13').
   544 
   545  managesieve_max_compile_errors = 5
   546    The maximum number of compile errors that are returned to the client upon
   547    script upload or script verification.
   548 
   549  managesieve_sieve_capability =
   550  managesieve_notify_capability =
   551    Respectively the SIEVE and NOTIFY capabilities reported by the ManageSieve
   552    service before authentication. If left unassigned these will be assigned
   553    dynamically according to what the Sieve interpreter supports by default
   554    (after login this may differ depending on the authenticated user).
   555 
   556 Additionally, the ManageSieve service uses the following settings from the
   557 plugin section of the config file. These settings are the same ones used by
   558 the LDA Sieve plugin.
   559 
   560  sieve_dir = ~/sieve
   561    This specifies the path to the directory where the uploaded scripts are
   562    stored. Scripts are stored as separate files with extension '.sieve'. All
   563    other files are ignored when scripts are listed by a ManageSieve client. The
   564    Sieve interpreter also uses this setting to locate the user's personal
   565    scripts for use with the Sieve include extension. A storage location
   566    specified by sieve_dir is always generated automatically if it does not exist
   567    (as far as the system permits the user to do so; no root privileges are
   568    used). This is similar to the behavior of the mail daemons regarding the
   569    mail_location configuration.
   570 
   571  sieve = ~/.dovecot.sieve
   572    This specifies the location of the symbolic link pointing to the active
   573    script in the Sieve storage directory. The Sieve interpreter uses this
   574    setting to locate the main script file that needs to be executed upon
   575    delivery. When using ManageSieve, this is a symbolic link managed by the
   576    ManageSieve service. ManageSieve thereby determines which script (if any) in
   577    the sieve_dir directory is executed for incoming messages. If a regular file
   578    already exists at the location specified by the sieve setting, it is moved to
   579    the sieve_dir location before the symbolic link is installed. It is renamed
   580    to dovecot.orig.sieve and therefore listed as `dovecot.orig' by a ManageSieve
   581    client.
   582 
   583 The following provides an example configuration for Sieve and ManageSieve. Only
   584 sections and settings relevant to ManageSieve are shown. Refer to
   585 20-managesieve.conf in the doc/example-config/conf.d directory for a full
   586 example with comments, but don't forget to configure Sieve and add sieve to the
   587 'protocols = ...' setting if you use it.
   588 
   589 # *** conf.d/20-managesieve.conf ***
   590 
   591 service managesieve-login {
   592   inet_listener sieve {
   593     # Bind the daemon only to the specified address(es)
   594     # (default: *, ::)
   595     address = 127.0.0.1
   596     # Specify an alternative port the daemon must listen on
   597     # (default: 4190)
   598     port = 2000
   599   }
   600 }
   601 
   602 protocol sieve {
   603   managesieve_max_compile_errors = 10
   604 }
   605 
   606 # ***  conf.d/90-sieve.conf ***
   607 
   608 plugin {
   609   sieve=~/.dovecot.sieve
   610   sieve_dir=~/sieve
   611 }
   612 
   613 # *** dovecot.conf ***
   614 
   615 # .... (other config items)
   616 
   617 # Start imap, pop3, lmtp and managesieve services
   618 protocols = imap pop3 lmtp sieve
   619 
   620 # .... (other config items)
   621 
   622 ManageSieve Service - Quota Support
   623 -----------------------------------
   624 
   625 By default, users can manage an unlimited number of Sieve scripts on the server
   626 through ManageSieve. However, ManageSieve can be configured to enforce limits on
   627 the number of personal Sieve scripts per user and/or the amount of disk storage
   628 used by these scripts. The maximum size of individual uploaded scripts is
   629 dictated by the configuration of the Sieve plugin. The limits are configured in
   630 the plugin section of the Dovecot configuration as follows:
   631 
   632  sieve_max_script_size = 1M
   633    The maximum size of a Sieve script. If set to 0, no limit on the script size
   634    is enforced.
   635 
   636  sieve_quota_max_scripts = 0
   637    The maximum number of personal Sieve scripts a single user can have. If set
   638    to 0, no limit on the number of scripts is enforced.
   639 
   640  sieve_quota_max_storage = 0
   641    The maximum amount of disk storage a single user's scripts may occupy. If set
   642    to 0, no limit on the used amount of disk storage is enforced.
   643 
   644 ManageSieve Service - Proxying
   645 ------------------------------
   646 
   647 Like Dovecot's imapd, the ManageSieve login daemon supports proxying to multiple
   648 backend servers. Although the underlying code is copied from the imapd sources
   649 for the most part, it has some ManageSieve-specifics that have not seen much
   650 testing.
   651 
   652 The proxy configuration wiki page for POP3 and IMAP should apply to ManageSieve
   653 as well:
   654 
   655 http://wiki.dovecot.org/PasswordDatabase/ExtraFields/Proxy
   656 
   657 ManageSieve Service - Migration
   658 -------------------------------
   659 
   660 The following has changed since the ManageSieve releases for Dovecot v1.x:
   661 
   662  * For Dovecot v1.0 and v1.1, the sieve_dir setting used by ManageSieve was
   663    called sieve_storage. Also, the sieve and sieve_storage settings were located
   664    inside the 'protocol managesieve' section of the configuration. As per
   665    Dovecot v1.2, these settings are shared with the Sieve plugin and located in
   666    the 'plugin' section of the configuration. Make sure you have updated the
   667    name of the sieve_dir setting and the location of both these settings if you
   668    are upgrading from ManageSieve for Dovecot v1.0/v1.1.
   669  * Pigeonhole ManageSieve does not use the mail_location configuration as a
   670    fall-back anymore to determine a default location for storing Sieve scripts.
   671    It always uses the sieve_dir setting, with default value ~/sieve.
   672  * The Pigeonhole ManageSieve service now binds to TCP port 4190 by default due
   673    to the IANA port assignment for the ManageSieve service. When upgrading from
   674    v1.x, this should be taken into account. For a smooth transition, the service
   675    can be configured manually to listen on both port 2000 and port 4190, as
   676    demonstrated in the example above.
   677  * The Dovecot configuration now calls the ManageSieve protocol 'sieve' instead
   678    of 'managesieve' because it is registered as such with IANA. The binaries and
   679    the services are still called 'managesieve' and 'managesieve-login'. The
   680    example above demonstrates how this affects the configuration.
   681 
   682 Test Suite
   683 ==========
   684 
   685 This package includes a test suite to verify the basic processing of the Sieve
   686 interpreter on your particular platform. Note that the test suite is not
   687 available when this package is compiled against the Dovecot headers only. The
   688 test suite executes a list of test cases and halts when one of them fails. If it
   689 executes all test cases successfully, the test suite finishes. You can execute
   690 the basic test suite using `make test`, which does not include the plugins. You
   691 can test the plugins using `make test-plugins`.
   692 
   693 A failing test case is always a bug and a report is greatly appreciated.
   694