Pysieved integration with Dovecot
=================================

Dovecot authentication
----------------------

If you want to use Dovecot authentication, set the mux config item
in the [Dovecot] session to the path to a client socket as defined
in dovecot.conf, e.g. :

dovecot.conf :
    auth default {
      socket listen {
        client {
          path = /var/run/dovecot/auth-client
          mode = 0666
        }
      }
    }

pysieved.ini :
    [Dovecot]
    mux = /var/run/dovecot/auth-client



Dovecot userdb lookup
---------------------

If you don't place user filters in their home directory but use
the dovecot-sieve plugin's "sieve" variable to define their
location, skip to the next section.

If you want to use Dovecot userdb to get the uid/gid/home of the
user, set the master config item in the [Dovecot] session to the
path to a master socket as defined in dovecot.conf, e.g. :

dovecot.conf :
    auth default {
      socket listen {
        master {
          path = /var/run/dovecot/auth-master
          mode = 0600
        }
      }
    }

pysieved.ini :
    [Dovecot]
    master = /var/run/dovecot/auth-master



Dovecot SIEVE without a home directory
--------------------------------------

Some people do not define a home directory for "virtual" dovecot accounts.
Instead, they use a common directory containing per-use filters,

e.g. in dovecot.conf :
    plugin {
        ...
        sieve = /var/sieve-scripts/%u.sieve
    }

In that case, pysieved's virtual plugin is more appropriate for
userdb lookups.

Please note that pysieved supports different substitution
variables, described in the sample pysieved.ini. For instance,
you can use the template above as-is if you login with a
simple username (no @ sign), but if you use a full e-mail
address, the corresponding path setting would be :

pysieved.ini:
    [Virtual]
    path = /var/sieve-scripts/%u@%d.sieve



Dovecot socket permissions
--------------------------

In an environment where all users are virtual and share the same
uid/gid, it is possible to run pysieved as non-root by specifying
NUMERIC uid/gid values in the [Dovecot] section, e.g. :

pysieved.ini :
    [Dovecot]
    uid=1000
    gid=100

If you do not intend to run pysieved as non-root, skip directly
to the next section.

Otherwise, special care may be needed so that pysieved can access
the 'mux' and 'master' sockets (and write the pidfile) : read on !


The pidfile can be moved to a directory that is writeable by the
specified uid/gid, e.g. :

pysieved.ini :
    [main]
    pidfile = /var/run/pysieved/pysieved.pid


The Dovecot client socket (mux) can safely be exported with 0666
permissions if the default value of 0660 does not work.


As for the master socket, it can have restrictive permissions,
as recommended in the Dovecot documentation, if you make it
owned by the same user who owns the mail storage (which works
out well if using the Dovecot deliver LDA with Postfix). E.g. :

dovecot.conf :
    auth default {
      socket listen {
        master {
          path = /var/run/dovecot/auth-master
          mode = 0600
          user = vmail
          group = vmail
        }
      }
    }

pysieved.ini :
    [Dovecot]
    master = /var/run/dovecot/auth-master

master.cf :
    dovecot         unix    -       n       n       -       -       pipe
      flags=DRhu user=vmail:vmail
      argv=/usr/local/libexec/dovecot/deliver -f $sender -d $recipient

User vmail and group vmail should be replaced with the correct names for
the uid/gid that owns the virtual mail storage.  Pysieved should also
run with this uid/gid.



Sharing the Dovecot's authentication socket with Postfix
--------------------------------------------------------

If you use Postfix + Dovecot SASL, a common scenario places
the client socket inside the Postfix chroot area, such as
/var/spool/postfix/private/auth where the private directory
is accessible only by the postfix user.

If you also want to run pysieved with restricted uid/gid as
described in the previous section (this is not necessary if
you run pysieved with root privileges), you will have to
make a few changes to the standard configuration.


### Using multiple authentication sockets

If your version of Dovecot will allow the definition of
multiple authentication sockets, the easiest way to
accomodate both Postfix and pysieved is to use 2
different ones.

The following example has been reported by David Ramsden
to work with Dovecot 1.1.11, and may be fine for earlier
1.1 versions.

dovecot.conf :
    auth default {
      socket listen {
        master {
          ...
        }
        client {
          path = /var/spool/postfix/private/auth
          ...
        }
      }
      socket listen {
        client {
          path = /var/run/dovecot/auth-client
          ...
        }
      }
    }


### Using a single authentication socket

If you must use the same socket for Postfix and pysieved
running with restricted uid/gid, you MUST move it to a
different, public, directory.

E.g. :

dovecot.conf :
    auth default {
      socket listen {
        client {
          path = /var/run/dovecot/auth-client
          mode = 0666
        }
      }
    }

pysieved.ini :
    [Dovecot]
    mux = /var/run/dovecot/auth-client

main.cf :
    smtpd_sasl_type = dovecot
    smtpd_sasl_path = /var/run/dovecot/auth-client

master.cf:
    # service type  private unpriv  chroot  wakeup  maxproc command + args
    smtp    inet    n       -       n       -       -       smtpd

Note that if the socket is not under /var/spool/postfix you
cannot chroot smtpd, hence the master.cf line above.

If you insist on chrooting smtpd, place the socket under
/var/spool/postfix but outside of the private directory
and use a relative smtpd_sasl_path. E.g. :

smtpd_sasl_path = auth/dovecot

for a socket located at /var/spool/postfix/auth/dovecot.



If the home directory is the Maildir
------------------------------------

You may have a setup where your users' home directories are their
Maildirs.  In this case, dovecot IMAPd will show "pysieved" and
"dovecot.sieve" folders.  There are several solutions to this problem,
as detailed in [this email by Philippe Levan](http://woozle.org/list-archives/pysieved/msg00155.html):

> A few options to not show a .dovecot.sieve file :
>
> 1. define a Dovecot home directory != mail directory
>    e.g. :
>        home resolved via userdb and
>        mail_location = maildir:~/Maildir
>    (http://wiki.dovecot.org/VirtualUsers#homedirs)
>
> 2. configure a "sieve" variable or return a "sieve" extra field
>    during userdb lookup pointing to an alternate name/location
>    e.g. :
>        plugin {
>                sieve = dovecot.sieve
>        }
>    (http://wiki.dovecot.org/LDA/Sieve)
>
> 3. hack the code in dovecot-sieve-X.X.X/src/cmusieve-plugin.c line 11
>    e.g. :
>        #define SIEVE_SCRIPT_PATH "~/dovecot.sieve"

The latter two require modifying the "active" value in the [Dovecot]
section of the configuration file:

    [Dovecot]
    active = dovecot.sieve

