

Dovecot LDA
===========


The Dovecot LDA, called *'deliver'*, is a >>local delivery agent<< which takes mail from an >>MTA<< and delivers it to a user's mailbox, while keeping Dovecot index files up to date. 
This page describes the common settings required to make deliver work. You should read it first, and then the MTA specific pages: 

 * >>LDA/Postfix<< 
 * >>LDA/Exim<< 
 * >>LDA/Sendmail<< 
 * >>LDA/Qmail<< 


Main features of Dovecot LDA
============================



 * >>Mailbox indexing during mail delivery<<, providing faster mailbox access later 
 * >>Quota enforcing by a plugin<< 
 * >>Sieve language support by a plugin<< 

 * Mail filtering 
 * Mail forwarding 
 * Vacation auto-reply 



Common configuration
====================


The configuration is done in the /protocol lda/ section in 'dovecot.conf'. The important settings are: 

 * 'postmaster_address' is used as the From: header address in bounce mails 
 * 'hostname' is used in generated Message-IDs and in Reporting-UA: header in bounce mails 
 * 'sendmail_path' is used to send mails. Note that the default is '/usr/lib/sendmail', which doesn't necessarily work the same as '/usr/sbin/sendmail'. 
 * 'auth_socket_path' specifies the UNIX socket to dovecot-auth where deliver can lookup userdb information when '-d' parameter is used. 


Parameters
==========


Parameters accepted by deliver: 

 * '-d <username>': Destination username. If given, the user information is looked up from dovecot-auth. 
 * '-a <address>': Destination address (e.g. user+ext@domain). Default is the same as username. (v1.1+ only) 
 * '-f <address>': Envelope sender address. Currently this is used only for writing mbox's From_-header. The default is "MAILER-DAEMON". 
 * '-c <path>': Alternative configuration file path. 
 * '-m <mailbox>': Destination mailbox (default is INBOX). If the mailbox doesn't exist, it's created (unless -n is used). If message couldn't be saved to the mailbox for any reason, it's delivered to INBOX instead. 

 * If Sieve plugin is used, this mailbox is used as the "keep" action's mailbox. It's also used if there is no Sieve script or if the script fails for some reason. 

 * '-n': If the destination mailbox doesn't exist, don't create it. This affects both '-m' parameter and 'fileinfo' action in Sieve scripts. The fallback is to deliver mail to INBOX. 
 * '-e': If mail gets rejected, write the rejection reason to stderr and exit with EX_NOPERM. The default is to send a rejection mail ourself (v1.0.1+). 
 * '-k': Don't clear all environment at startup (v1.1+, v1.0 doesn't clear the environment). 


System users
============


You can use deliver with a few selected system users (ie. user is found from '/etc/passwd' / NSS) by calling deliver in the user's '~/.forward' file: 

---%<-------------------------------------------------------------------------
| "/usr/local/libexec/dovecot/deliver"
---%<-------------------------------------------------------------------------

This should work with any MTA which supports per-user '.forward' files.  For qmail's per-user setup, see >>LDA/Qmail<<. 
This method doesn't require the authentication socket explained below since it's executed as the user itself. 


Virtual users
=============




With a lookup
=============


Give the destination username to deliver with '-d' parameter, for example: 

---%<-------------------------------------------------------------------------
deliver -f $FROM_ENVELOPE -d $DEST_USERNAME
---%<-------------------------------------------------------------------------

You'll need to set up a master authentication socket for deliver so it knows where to find mailboxes for the users: 

---%<-------------------------------------------------------------------------
protocol lda {
..
  # UNIX socket path to master authentication server to find users.
  #auth_socket_path = /var/run/dovecot/auth-master
}
auth default {
..
  socket listen {
    # Note that we're setting a master socket. SMTP AUTH for Postfix and Exim uses client sockets.
    master {
      path = /var/run/dovecot/auth-master
      # Auth master socket can be used to look up userdb information for
      # given usernames. This probably isn't very sensitive information
      # for most systems, but still try to restrict the socket access if possible.
      mode = 0600
      user = vmail # User running deliver
      #group = mail # Or alternatively mode 0660 + deliver user in this group
    }
  }
..
}
---%<-------------------------------------------------------------------------

The master socket can be used to do >>userdb<< lookups for given usernames. Typically the result will contain the user's UID, GID and home directory, but depending on your configuration it may return other information as well. So the information is similar to what can be found from eg. '/etc/passwd' for system users. This means that it's probably not a problem to use mode=0666 for the socket, but you should try to restrict it more just to be safe. 


Without a lookup
================


If you have already looked up the user's home directory and you don't need a userdb lookup for any other reason either (such as overriding settings for specific users), you can run deliver similar to how it's run for system users: 

---%<-------------------------------------------------------------------------
HOME=/path/to/user/homedir deliver -f $FROM_ENVELOPE
---%<-------------------------------------------------------------------------

This way you don't need to have a master listener socket. Note that you should verify the user's existence prior to running deliver, otherwise you'll end up having mail delivered to non-existing users as well. 
You must have set the proper UID (and GID) before running deliver. It's not possible to run deliver as root without '-d' parameter. 


Multiple UIDs
=============


If you're using more than one UID for users, you're going to have problems running deliver. Most MTAs won't let you run deliver as root, so for now you'll need to make it setuid root. However *deliver isn't designed to be run as setuid-root*, so you should take extra steps to make sure that untrusted users can't run it and potentially gain root privileges. You can do this by placing deliver into a directory where only your MTA has execution access. For example: 

---%<-------------------------------------------------------------------------
# ls -la /usr/local/libexec/dovecot/lda/
drwx------ 2 postfix staff      20 2007-03-22 01:39 ./
drwxr--r-x 3 root    staff    4096 2007-03-22 01:39 ../
-rwsr-xr-x 1 root    staff 2618498 2007-03-21 20:31 deliver*
---%<-------------------------------------------------------------------------

Then start deliver as postfix user. 


Problems with deliver
=====================



 * Currently 'deliver' doesn't support >>namespaces<<. The mails can be delivered only to mailboxes specified by the >>mail_location<< setting. 
 * If you are using >>prefetch userdb<<, keep in mind that 'deliver' does not make a password query and thus will not work if '-d' parameter is used. The >>UserDatabase/Prefetch<< page explains how to fix this. 

 * See >>Checkpassword<< for how to make deliver work with checkpassword. 



Logging
=======


Normally Dovecot logs everything through its master process, which is running as root. Deliver however doesn't, which means that you might need some special configuration for it to log anything at all. There are two ways to solve this: Either give deliver enough permissions to log to standard locations, or set up separate log files for it. If you're not using a single UID for all users, then you'll practically have to make the log files (or the syslog socket) world-writable. 
For using separate deliver logs, you can do: 

---%<-------------------------------------------------------------------------
protocol lda {
 ..
  # remember to give proper permissions for these files as well
  log_path = /var/log/dovecot-deliver.log
  info_log_path = /var/log/dovecot-deliver.log
}
---%<-------------------------------------------------------------------------

For using syslog with deliver, set the paths empty: 

---%<-------------------------------------------------------------------------
protocol lda {
 ..
  log_path =
  info_log_path =
  # You can also override the default syslog_facility:
  #syslog_facility = mail
}
---%<-------------------------------------------------------------------------



Plugins
=======



 * Most of the >>Dovecot plugins<< work with deliver. 
 * Virtual quota can be enforced using >>Quota plugin<<. 
 * Sieve language support can be added with >>Sieve plugin<<. 

(This file was created from the wiki on 2007-12-11 04:42)
