Adding upstream version 1:2.3.19.1+dfsg1.upstream/1%2.3.19.1+dfsg1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 298 insertions, 0 deletions

diff --git a/doc/wiki/LDA.txt b/doc/wiki/LDA.txt
new file mode 100644
index 0000000..80e2ee6
--- /dev/null
+++ b/doc/wiki/LDA.txt
@@ -0,0 +1,298 @@
+Dovecot LDA
+===========
+
+The Dovecot LDA is a <local delivery agent> [MDA.txt], which takes mail from an
+<MTA.txt> and delivers it to a user's mailbox, while keeping Dovecot index
+files up to date. Nowadays you should probably use the <LMTP server> [LMTP.txt]
+instead, because it's somewhat easier to configure (especially related to
+permissions) and gives better performance.
+
+This page describes the common settings required to make LDA work. You should
+read it first, and then the MTA specific pages:
+
+ * <LDA.Postfix.txt>
+ * <LDA.Exim.txt>
+ * <LDA.Sendmail.txt>
+ * <LDA.Qmail.txt>
+ * <LDA.ZMailer.txt>
+
+Main features of Dovecot LDA
+----------------------------
+
+ * <Mailbox indexing during mail delivery> [LDA.Indexing.txt], providing faster
+   mailbox access later
+ * <Quota enforcing by a plugin> [Quota.txt]
+ * <Sieve language support by a plugin> [Pigeonhole.Sieve.txt]
+    * Mail filtering
+    * Mail forwarding
+    * Vacation auto-reply
+
+Common configuration
+--------------------
+
+The settings are listed in the example 'conf.d/15-lda.conf' file. 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/sbin/sendmail', which doesn't necessarily work the same as
+   '/usr/lib/sendmail'.
+    * Alternatively you can use 'submission_host' to send mails via the
+      specified SMTP server.
+ * 'auth_socket_path' specifies the UNIX socket to auth-userdb where LDA can
+   lookup userdb information when '-d' parameter is used. See below how to
+   configure Dovecot to configure the socket.
+
+Note that the config files must be world readable to enable dovecot-lda process
+read them, while running with user privileges. You can put password related
+settings to a separate file, which you include with '!include_try' and
+dovecot-lda skips them.
+
+Parameters
+----------
+
+Parameters accepted by dovecot-lda:
+
+ * '-d <username>': Destination username. If given, the user information is
+   looked up from dovecot-auth. Typically used with virtual users, but not
+   necessarily with system users.
+ * '-a <address>': Original envelope recipient address (e.g. user+ext@domain),
+   typically same as SMTP's RCPT TO: value. If not specified, it's taken from
+   header specified by 'lda_original_recipient_header' setting (v2.0.3+). If
+   the header doesn't exist either, defaults to same as username.
+ * '-r <address>': Final envelope recipient address. Defaults to -a address,
+   but may differ if e.g. aliases are used or when dropping the +ext part.
+   (v2.0.3+)
+ * '-f <address>': Envelope sender address. If not specified and message data
+   begins with a valid mbox-style "From " line, the address is taken from it.
+ * '-c <path>': Alternative configuration file path.
+ * '-m <mailbox>': Destination mailbox (default is INBOX). If the mailbox
+   doesn't exist, it will not be created (unless the lda_mailbox_autocreate
+   setting is set to yes). 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.
+    * Deliveries to namespace prefix will result in saving the mail to INBOX
+      instead. For example if you have "Mail/" namespace, this allows you to
+      specify 'dovecot-lda -m Mail/$mailbox' where mail is stored to
+      Mail/$mailbox or to INBOX if $mailbox is empty.
+    * The mailbox name is specified the same as it's visible in IMAP client.
+      For example if you've a Maildir with '.box.sub/' directory and your
+      namespace configuration is 'prefix=INBOX/', 'separator=/', the correct
+      way to deliver mail there is to use '-m INBOX/box/sub'
+ * '-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.
+ * '-k': Don't clear all environment at startup.
+ * '-p <path>': Path to the mail to be delivered instead of reading from stdin.
+   If using maildir the file is hard linked to the destination if possible.
+   This allows a single mail to be delivered to multiple users using hard
+   links, but currently it also prevents dovecot-lda from updating cache file
+   so it shouldn't be used unless really necessary.
+ * '-o name=value': Override a setting from dovecot.conf. You can give this
+   parameter multiple times.
+
+Return values
+-------------
+
+dovecot-lda will exit with one of the following values:
+
+ * 0 (EX_OK): Delivery was successful.
+ * 64 (EX_USAGE): Invalid parameter given.
+ * 67 (EX_NOUSER): The destination username was not found.
+ * 77 (EX_NOPERM): -e parameter was used and mail was rejected. Typically this
+   happens when user is over quota and 'quota_full_tempfail=no'.
+ * 75 (EX_TEMPFAIL): A temporary failure. This is returned for almost all
+   failures. See the log file for details.
+
+System users
+------------
+
+You can use LDA with a few selected system users (ie. user is found from
+'/etc/passwd' / NSS) by calling dovecot-lda in the user's '~/.forward' file:
+
+---%<-------------------------------------------------------------------------
+| "/usr/local/libexec/dovecot/dovecot-lda"
+---%<-------------------------------------------------------------------------
+
+This should work with any MTA which supports per-user '.forward' files.  For
+qmail's per-user setup, see <LDA.Qmail.txt>.
+
+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 dovecot-lda with '-d' parameter, for example:
+
+---%<-------------------------------------------------------------------------
+dovecot-lda -f $FROM_ENVELOPE -d $DEST_USERNAME
+---%<-------------------------------------------------------------------------
+
+You'll need to set up a auth-userdb socket for dovecot-lda so it knows where to
+find mailboxes for the users:
+
+---%<-------------------------------------------------------------------------
+service auth {
+  unix_listener auth-userdb {
+    mode = 0600
+    user = vmail # User running dovecot-lda
+    #group = vmail # Or alternatively mode 0660 + dovecot-lda user in this
+group
+  }
+}
+---%<-------------------------------------------------------------------------
+
+The auth-userdb socket can be used to do <userdb> [UserDatabase.txt] lookups
+for given usernames or get a list of all users. 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 dovecot-lda similar to how it's run for system
+users:
+
+---%<-------------------------------------------------------------------------
+HOME=/path/to/user/homedir dovecot-lda -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 dovecot-lda, otherwise you'll end
+up having mail delivered to nonexistent users as well.
+
+You must have set the proper UID (and GID) before running dovecot-lda. It's not
+possible to run dovecot-lda as root without '-d' parameter.
+
+Multiple UIDs
+-------------
+
+If you're using more than one UID for users, you're going to have problems
+running dovecot-lda, as most MTAs won't let you run dovecot-lda as root. Best
+solution is to use <LMTP.txt> instead, but if you can't do that, there are two
+ways to work around this problem:
+
+ 1. Make dovecot-lda setuid-root.
+ 2. Use sudo to wrap the invocation of dovecot-lda.
+
+Making dovecot-lda setuid-root:
+-------------------------------
+
+Beware: *it's insecure to make dovecot-lda setuid-root*, especially if you have
+untrusted users in your system.*Setuid-root dovecot-lda can be used to gain
+root privileges*. 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 making
+sure only your MTA has execution access to it. For example:
+
+---%<-------------------------------------------------------------------------
+# chgrp secmail /usr/local/libexec/dovecot/dovecot-lda
+# chmod 04750 /usr/local/libexec/dovecot/dovecot-lda
+# ls -l /usr/local/libexec/dovecot/dovecot-lda
+-rwsr-x--- 1 root secmail 4023932 2010-06-15 16:23 dovecot-lda
+---%<-------------------------------------------------------------------------
+
+Then start dovecot-lda as a user that belongs to secmail group. Note that you
+have to recreate these rights after each update of dovecot.
+
+Using sudo:
+-----------
+
+Alternatively, you can use sudo to wrap the invocation of dovecot-lda. This has
+the advantage that updates will not clobber the setuid bit, but note that *it
+is just as insecure being able to run dovecot-lda via sudo as setuid-root*.
+Make sure you only give your MTA the ability to invoke dovecot-lda via sudo.
+
+First configure sudo to allow 'dovelda' user to invoke dovecot-lda by adding
+the following to your '/etc/sudoers':
+
+---%<-------------------------------------------------------------------------
+Defaults:dovelda !syslog
+dovelda          ALL=NOPASSWD:/usr/local/libexec/dovecot/dovecot-lda
+---%<-------------------------------------------------------------------------
+
+Then configure your MTA to invoke dovecot-lda as user 'dovelda' and via sudo:
+
+---%<-------------------------------------------------------------------------
+/usr/bin/sudo /usr/local/libexec/dovecot/dovecot-lda
+---%<-------------------------------------------------------------------------
+
+instead of just plain '/usr/local/libexec/dovecot/dovecot-lda'.
+
+Problems with dovecot-lda
+-------------------------
+
+ * If you are using <prefetch userdb> [UserDatabase.Prefetch.txt], keep in mind
+   that 'dovecot-lda' does not make a password query and thus will not work if
+   '-d' parameter is used. The <UserDatabase.Prefetch.txt> page explains how to
+   fix this.
+    * See <Checkpassword> [PasswordDatabase.CheckPassword.txt] for how to make
+      dovecot-lda work with checkpassword.
+
+Logging
+-------
+
+ * Normally Dovecot logs everything through its log process, which is running
+   as root. dovecot-lda doesn't, which means that you might need some special
+   configuration for it to log anything at all.
+ * If dovecot-lda fails to write to log files it exits with temporary failure.
+ * If you have trouble finding where Dovecot logs by default, see
+   <Logging.txt>.
+ * Note that Postfix's 'mailbox_size_limit' setting applies to all files that
+   are written to. So if you have a limit of 50 MB, dovecot-lda can't write to
+   log files larger than 50 MB and you'll start getting temporary failures.
+
+If you want dovecot-lda to keep using Dovecot's the default log files:
+
+ * If you're logging to syslog, make sure the syslog socket (usually
+   '/dev/log') has enough write permissions for dovecot-lda. For example set it
+   world-read/writable:'chmod a+rw /dev/log'.
+ * If you're logging to Dovecot's default log files again you'll need to give
+   enough write permissions to the log files for dovecot-lda.
+
+You can also specify different log files for dovecot-lda. This way you don't
+have to give any extra write permissions to other log files or the syslog
+socket. You can do this by overriding the 'log_path' and 'info_log_path'
+settings:
+
+---%<-------------------------------------------------------------------------
+protocol lda {
+ ..
+  # remember to give proper permissions for these files as well
+  log_path = /var/log/dovecot-lda-errors.log
+  info_log_path = /var/log/dovecot-lda.log
+}
+---%<-------------------------------------------------------------------------
+
+For using syslog with dovecot-lda, 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> [Plugins.txt] work with dovecot-lda.
+ * Virtual quota can be enforced using <Quota plugin> [Quota.txt].
+ * Sieve language support can be added with the <Pigeonhole Sieve plugin>
+   [Pigeonhole.Sieve.txt].
+
+(This file was created from the wiki on 2019-06-19 12:42)