README.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 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 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.


........ BEGIN WARNING : Postfix + Dovecot SASL ........

If you use Postfix + Dovecot SASL, a common scenario places
the client socket inside the Postfix chroot area, as
/var/spool/postfix/private/auth where the private directory
is accessible only by the postfix user. 
You MUST move it to a different, public, directory if you want
to use pysieved with Dovecot authentication and restricted
uid/gid. 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.

........ END WARNING : Postfix + Dovecot SASL ........


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.

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 Phillipe
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