
                              Installing maildrop
                                       
   The typical sequence of commands to install maildrop is as follows:

   ./configure [options]
   make autoconf.h
   make config.h
   make
   make install-strip

   The configure script creates Makefile, and autoconf.h. After running
   configure, you may want to edit autoconf.h, and config.h in order to
   make minor adjustments to the configuration.
   
   The first two make commands are required to resolve some dependency
   idiosynchronies in the automake-generated Makefile.  The third make
   compiles maildrop, and the last make installs stripped executables.
   
   When you run configure, you may get some warning messages asking you
   to install automake, autoconf, or even perl packages. These warning
   messages can be safely ignored.
   
   Some versions of make may have problems handling the Makefile. If your
   make gives you errors, try using the gmake command instead - the GNU
   make.
   
   NOTE: configure attempts to automatically configure the following
   options for maildrop according to your specific UNIX system. After
   running configure, you should review these options and make any
   necessary adjustments.
   
Operating system specific notes

   This section will list any platform-depended issues.
   
    Solaris
    
   This problem has been reported for Solaris 2.6. Other Solaris versions
   or related platforms can be affected. Symptom - trying to run maildrop
   results in an error message saying that libstdc++ cannot be opened.
   
   Solaris's run time linker has a problem running C++ applications which
   have the setuid or setgid bit set. On Solaris, libstdc++ (the runtime
   C++ library) is installed in /usr/local/lib. Solaris's runtime linker
   will only open shared libraries in /usr/lib for programs with the
   setuid or setgid bit set.
   
   Maildrop is installed with the setuid and setgid bits set, so that
   maildrop can change to the recipient's userid and group id. There are
   three easy workarounds.
    1. If you can configure your mail transport agent to set the correct
       user and group IDs before running maildrop, maildrop will not need
       the setuid and setgid privileges. After running make
       install-strip, go ahead and manually turn these bits off for the
       maildrop, dotlock, and reformail.
       
    2. Create a soft link from /usr/lib/local to /usr/local/lib, and add
       /usr/lib/local to the LD_LIBRARY_PATH environment variable.
       
    3. Create a soft link to libstdc++ from /usr/lib to /usr/local/lib
       
    Any sendmail platform
    
   There are two quirks that anyone installing maildrop on a
   sendmail-based system should be aware of.
     * Unlike other mail transport agents, most sendmails completely
       discard error messages from the local delivery agent. Therefore,
       you should use the --enable-syslog=1 flag to configure on systems
       running sendmail, unless you are very familiar with maildrop.
       Without this flag, if you have any problems and maildrop is not
       installed correctly, you will end up with a bunch of deferred
       mail, and absolutely nothing to indicate why. Although maildrop
       will report an error message, sendmail will discard the message
       without recording it anywhere. With the --enable-syslog=1 option
       enabled, you at least get to see the error messages in your
       syslog. However, please note that syslog will now show any fatal
       maildrop errors resulting from botched user recipe files.
       
     * Interactive or background delivery mode. Usually the default
       sendmail delivery mode is i - interactive, or b - background. It
       appears that some versions of sendmail have a minor conflict with
       maildrop's default security level. The conflict arises in a
       situation where a local user sends a message to another local
       user. It appears that at least some versions of sendmail invoke
       maildrop with the userid set to the sender, and the -d option
       specifying the recipient. The default maildrop configuration
       allows only certain "trusted" users to use the -d option. What
       will happen is that maildrop will report an error, and return an
       exit code to sendmail indicating a temporary error. The message
       will be deferred, and on the next queue run, sendmail will attempt
       to re-deliver it. But now, sendmail will do a queue run as root,
       and root is allowed to use the -d option, so the message is
       delivered.
       
       
       
       
       Note that this applies ONLY if you have maildrop defined as the
       local delivery agent in sendmail.cf. This will happen if maildrop
       is invoked from a .forward file. There are three possible
       solutions: do nothing, since no real harm is done, local mail
       simply gets delivered with some delay; you can change the default
       queueing method (in sendmail.cf) to queue messages; or, you can
       specify --enable-restrict-trusted=0 option to configure, and lift
       the restriction on the -d option. However, keep in mind that the
       --enable-restrict-trusted=0 option allows a malicious user use the
       -d option to mailbomb another local user's mailbox. This is why
       the option is enabled by default. Of course, the same can also be
       accomplished by funneling the mailbomb through sendmail, instead
       of running maildrop directly. However, I can only tighten things
       up on my end; I presume that throttling mechanisms are in place in
       sendmail to block that avenue of attack.
       
Options to configure

   Although most configuration is done as described in the following
   section, I am migrating them to the configure script. Currently,
   configure support the following options:
   
     * --enable-DEBUG - specifying this parameter to configure enables
       some debugging code. Used only by those who know how to use it.
       :-)
       
     * --enable-syslog=1 - if specified, maildrop will log all fatal
       errors to syslog(3). This is recommended for sendmail, which does
       not log error messages for delivery agents.
       
     * --enable-maildrop-uid=root and --enable-maildrop-gid=mail - sets
       the userid and the groupid for the maildrop, maildirmake, and
       dotlock programs. These programs installed with the setuid and
       setgid permissions bits set. These options set the actual user id
       and the group id to use. If not specified, they default to "root"
       and "mail" respectively. See MAILBOX_MODE and RESET_GID below for
       more information.
       
   Early UNIX systems invoked the mail delivery agent and specified the
   account to which the message is addressed. The mail delivery agent is
   a program that's owned by root, and the set-user-id bit set. The mail
   delivery agent would then immediately reset its userid to whomever the
   message is addressed to.
   
   Some mail systems run the delivery agent without specifying the
   recipient on the command line. The user id is set by the mail system
   before running the mail delivery agent. In this case, root privileges
   are not required, and you may manually remove the setuid bit after
   installing maildrop.
   
   Some mail systems may use group privileges in order to write to the
   system mailbox directory. maildrop is installed with the set-group-id
   bit set as well, and the mail group is assumed to be 'mail'.  If a
   mail group other than 'mail' is used, specify it via the
   --enable-maildrop-gid option. You will also need to set the RESET_GID
   variable to 0 (see below). If RESET_GID is left alone to its default
   value of 1, maildrop will drop any acquired group ID right away, so
   its not necessary to remove the setgid bit. maildrop attempts to
   detect if this is the case, but you always need to confirm this.
   
     * --enable-sendmail=program - sets the initial value for the
       SENDMAIL environment variable for maildrop recipes. This is the
       pathname to the default mail delivery agent. If this option is not
       specified, configure will try to find it itself.
       
     * --enable-lockext-def=extension - sets the initial value for the
       LOCKEXT environment variable in maildrop. This is the filename
       extension of dotlock files. The default is ".lock".
       
     * --enable-locksleep-def=seconds - sets the initial value for the
       LOCKSLEEP environment variable. This is how long maildrop waits
       before trying to create a dotlock file again, if the dotlock file
       already exists. The default is 5 seconds.
       
     * --enable-locktimeout-def=seconds - sets the initial value for the
       LOCKTIMEOUT environment variable. This is how long maildrop waits
       before removing a stale dotlock file. The default is 60 seconds.
       
     * --enable-lockrefresh-def=seconds - sets the initial value for the
       LOCKREFRESH environment variable. This is how often maildrop
       refreshes its own dotlock files, to keep them from going stale.
       The default is 15 seconds.
       
   See the manual page for maildropfilter for more information on these
   variables.
   
     * --enable-tempdir=directory - sets the name of a subdirectory in
       each user's home directory where maildrop writes temporary files.
       maildrop will create this directory, if missing. The default is
       .tmp.
       
     * --enable-smallmsg=bytes - sets the size of a message, in bytes,
       before maildrop saves the message in a temporary file. Smaller
       messages are read in memory, and filtered and delivered directly
       from memory. In order to avoid consuming excessive amounts of
       expensive RAM, maildrop saves larger messages in a temporary file.
       If the standard input to maildrop is a file, a temporary file is
       not necessary. The default is 8192 bytes.
       
     * --enable-global-timeout=seconds - sets numbers of seconds that
       maildrop is willing to spend in order to deliver a single message.
       This value becomes a hard coded limit. When the time expires,
       maildrop terminates with an EX_TEMPFAIL error code. This is
       intended to stop runaway mail filters. The default is 300 seconds
       (five minutes).
       
     * --enable-crlf-term=flag - if set to 1, maildrop saves messages in
       the mailbox with each line terminated by a carriage return/line
       feed sequence. When set to 0, lines will be terminated by the
       linefeed character only. The default value is 0.
       
     * --enable-restrict-trusted=flag - if set to 1, maildrop permits
       only certain "trusted" user IDs to use the -d option. Setting this
       variable to 0 allows anyone to use the -d option (provided that
       maildrop has set-userid-to-root privileges). This allows certain
       denial-of-service attacks, so this setting is not recommended. The
       default value is 1.
       
     * --enable-keep-fromline=flag - if set to 1, when maildrop saves a
       message to a mailbox file, it will use the same From_ line address
       which was present in the original message. If the original message
       lacked a From_ line, maildrop will use the name of the user
       running maildrop. If set to 0, maildrop will keep the original
       From_ line address only if invoked by root, and reset it
       otherwise. The default value of this option is the value of the
       --enable-restrict-trusted option. Note that this option is new to
       maildrop version 0.54b. The logic in the previous version of
       maildrop was always the same as if this option was 0. Therefore,
       depending upon the value of the --enable-restrict-trusted flag,
       you may find that maildrop behavior changes with version 0.54b.
       This option also controls the semantics of the -f option to
       maildrop (see below).
       
     * --enable-trusted-users='...' - sets the list of users allowed to
       use the -d option if --enable-restrict-trusted is set to 1. If
       --enable-restrict-trusted is set to 0, this option is not used.
       Put a list of user IDs allowed to use the -d option between the
       apostrophes, separated by single spaces. If your mail transport
       agent uses maildrop as the local delivery agent this list must
       include the userid that the mail transport agent runs as. If this
       option is not specified, maildrop attempts to put together a list
       including common mail system user ids.
       
     * --enable-gzipped-man=flag - if this option is set to 1, 'make
       install' will install gzipped manual pages. If this option is set
       to 0, 'make install' will not compress manual pages using gzip.
       The default is 1, therefore if you do not have gzip, or if your
       man command does not support gzipped manual pages, you must
       manually set this option to 0.
       
     * --enable-use-flock=flag - if this option is set to 1, maildrop
       will use either the flock() or the lockf() system call to lock the
       mailbox file when delivering a message. On most UNIX systems, both
       of them implement an equivalent locking mechanism. In some very
       isolated cases, flock() and lockf() are different, incompatible,
       locking mechanisms. maildrop must use the same locking mechanism
       as the mail reading programs. If necessary, you can manually
       specify which one to use by editing autoconf.h after running
       configure (see below), and setting the HAS_LOCKF and HAS_FLOCK
       variables. If this option is set to 0, maildrop will not use any
       locking system calls. The default value for this option is 1. If
       this option is set to 0, the flock command can still be used to
       manually lock files.
       
     * --enable-use-dotlock=flag - if this option is set to 1, maildrop
       will create .lock files in order to gain access to the system
       mailbox file. If this option is set to 0, maildrop will not use
       .lock files automatically. However, the dotlock command can still
       be used to manually create .lock files. The default value for this
       option is 1, unless maildrop detects that the system mailbox
       directory does not have the sticky bit set (set below), in which
       case the default option is 0. maildrop attempts to figure out what
       the locking mechanism is used by the mail reading programs. A mail
       reading program can only create dotlock files in the system
       mailbox directory if the sticky bit is set. Note, it is possible
       for both --enable-use-flock and --enable-use-dotlock to be set to
       1, in which case both locking mechanisms are used simultaneously.
       
  Selecting an alternate C++ compiler
  
   maildrop is written in C++. Some systems may have more than one C++
   compiler available. If the default C++ compiler that's selected by the
   configure script doesn't work, you may try an alternate C++ compiler.
   First, you must extract the tarball again, into a different directory.
   Then, before running ./configure, set the CXX environment variable to
   the C++ compiler to be used. For example, to select the CC compiler:

$ CXX=CC
$ export CXX
$ ./configure [options]

   Then proceed as usual. The CXXFLAGS environment variable can also be
   used to override compiler flags that configure selects.
   
  Configuring the location of the system mailbox
  
   When maildrop has a message to deliver to a user, maildrop must know
   where users mailboxes are Different UNIX systems use different places
   to store E-mail, and different mechanisms to access it. And even on
   the same UNIX system you may have variations due to different mail
   software being used.
   
   Here are just some of the possible scenarios that may exist that
   maildrop knows how to handle:
   
     * All users' mailboxes usually are stored in a single directory, and
       the name of the mailbox is the user name. On systems with many
       mailboxes, the mailbox directory can be split in a hierarchical
       tree, based upon the initial letters of the user name. For
       example, the mailbox for the user jtomas is
       /var/spool/mail/j/jt/jthomas; mail for sjones is stored in
       /var/spool/mail/s/sj/sjones.
       
     * Instead of storing mail in a separate directory, the system may
       store incoming mail in each user's home directory.
       
     * Instead of storing mail in a traditional mailbox file, the system
       may implement a directory based format called maildir, that was
       introduced in the Qmail mail server. With maildrop as your local
       delivery agent you may implement the maildir format without having
       to use Qmail itself.
       
     * When mail is saved in a traditional mailbox file, only one program
       may access the file at the same time. In order to synchronize
       access to the mailbox file, the traditional mechanism uses a
       separate dot-lock file. Newer systems may also use the flock()
       function on the mailbox file itself. maildrop, by default, uses
       both mechanisms, except in one case (see the --enable-use-dotlock
       option to configure, above), but one or the other can always be
       selected to be used exclusively.
       
     * Traditionally, the directory where system mailboxes reside has the
       sticky bit set; all individual files are owned by their respective
       users, with read/write permissions set for the user only, and
       dot-locking is used to lock the mailbox. A newer, more secure
       arrangement is to remove the sticky bit from the directory, the
       directory has the mail group ownership, and each mailbox is owned
       by the user, and the mail group, with read/write privileges given
       to the owner and the mail group. The mail delivery agent runs in
       the mail group. This allows the mail delivery agent to create new
       mailboxes, and have the write permission to everyone's mailbox.
       The flock() function is used to lock an individual mailbox.
       
   As you can see, there is a lot of variation in possible mail setups.
   It is important that maildrop is configured to match your existing
   mail setup.  The configure script tries to automatically figure out
   the correct settings, but you MUST always verify the output file,
   autoconf.h, to make sure that the settings are correct. Description of
   each variable defined in autoconf.h follows. In addition, there are
   certain variables defined in a different file, config.h. These are
   settings that autoconf.h cannot automatically determine.
   
    DEFAULT_DEF
    
   This variable specifies the initial setting for the DEFAULT variable
   in maildrop, which should be the location of the system default
   mailbox. If DEFAULT_DEF begins with a slash, it should refer to a
   directory, and maildrop will automatically append the user's name.
   
   If it doesn't begin with a slash, maildrop will prepend the user's
   home directory to DEFAULT_DEF. To use maildrop with qmail, which
   normally delivers to $HOME/Mailbox, set DEFAULT_DEF to ./Mailbox.
   
   The '=' character in DEFAULT_DEF gets replaced by progressive
   characters from the user name of the user whose mail is being
   delivered. For example, if mail to the user name "john" is delivered
   to /var/spool/mail/j/jo/john and mail to user "root" is delivered to
   /var/spool/mail/r/ro/root, DEFAULT_DEF should be set to
   /var/spool/mail/=/== (maildrop automatically appends the full user
   name as the last component).
   
   If the DEFAULT_DEF/DEFAULT variable refers to a directory, maildrop
   assumes that it is delivering the message to a maildir, otherwise
   maildrop will deliver mail to a mailbox file, creating a new file if
   necessary. maildrop does not deliver mail to flat directory, like
   procmail. If you need to save messages in a directory, use the
   included program, maildirmake, to create a maildir directory.
   
    MAILBOX_MODE and RESET_GID
    
   Here are the required setting in two of the most common mailbox
   environments:
   
     * Mailbox spool directory has the sticky bit set, mailboxes are
       readable and writable by the user only - set MAILBOX_MODE to 0600,
       and RESET_GID to 1.
       
     * Mailbox spool directory does not have the sticky bit set, is
       writable by the mail group ID, mailboxes are readable and writable
       by the user and the mail group ID - set MAILBOX_MODE to 0660, and
       RESET_GID to 0.
       
   MAILBOX_MODE are the permissions maildrop uses to create new mailbox
   files. If a mailbox file already exists, maildrop is not going to
   change its permissions.
   
   RESET_GID indicates whether maildrop should immediately drop any
   set-group-id privileges. maildrop is installed with the set-group-id
   bit set with maildrop's group id set to the mail group. If system
   mailbox files have read/write access by both the user and the mail
   group, set RESET_GID to 0 to keep the mail group ID, and specify the
   mail group using the --enable-maildrop-gid flag to configure (see
   above).
   
    TRUSTED_USERS
    
   If --enable-restrict-trusted option given to the configure script is
   set to 1 (this is the default), maildrop allows only the users listed
   in this environment variable to use the -d option. See the online
   documentation for the description of the -d option.
   
   Mail can be delivered in two different ways:
   
     * The mail transport agent runs with root privileges. To deliver
       mail to a local user, the mail transport agent runs maildrop after
       changing the user id to the local user. In this case the -d option
       is not needed.
       
     * The mail transport agent runs as a non-privileged user. To deliver
       mail to a local user, the mail transport agent runs the mail
       delivery agent and specifies the user name with the -d option. The
       mail delivery agent is expected to be a program with root
       privileges, and it immediately must change its userid to the one
       specified by the -d option. If this is the case, you must include
       the mail transport agent's userid in the TRUSTED_USERS variable.
       
   If --enable-restrict-trusted option given to the configure script is
   set to 0, anyone can use the -d option. That is not recommended, it
   leaves open a possibility for certain denial-of-service attacks.
   
  Other configuration variables
  
   The configure script also sets the following variables in autoconf.h.
   After running the configure script, you may need to make some
   adjustments to these variables also.
   
    DEFAULT_PATH
    
   This variable in "autoconf.h" sets the initial contents of the PATH
   variable, which is the initial system search path for commands invoked
   by maildrop as child processes.
   
    SENDMAIL_DEF
    
   This variable in "autoconf.h" sets the initial contents of the
   SENDMAIL variable, which is the local mail transport agent. maildrop
   runs this program when instructed to deliver mail to a mailbox whose
   name begins with the forwarding "!" character.
   
    Other variables in autoconf.h
    
   All the other variables are self explanatory, and rarely need to be
   changed.
   
Using maildrop with sendmail

   Maildrop can be easily used as sendmail's local delivery agent,
   instead of procmail. Here is the suggested entry for sendmail.cf,
   courtesy of Eric J. Schwertfeger <ejs@bfd.com>:

Mlocal,         P=/usr/local/bin/maildrop, F=lsAw5:/|@SPfhn, S=10/30, R=20/40,
                T=DNS/RFC822/X-Unix,
                A=maildrop -d $u

   You may also consider including the D, F, and M flags as well.
   
The -f option to maildrop

   The -f option is new to version 0.55. The -f option sets the initial
   value of the FROM variable. If no -f option is given, maildrop looks
   at any From_ line in the message being delivered, otherwise it
   defaults to the name of the user who invoked maildrop.
   
   If the --enable-keep-fromline option is set to 0, anyone may use the
   -f option. If --enable-keep-fromline is set to 1, only "trusted" users
   (as defined by --enable-trusted-users) may use the -f option (ignored
   for everyone else).
   
   The initial value of the FROM variable is also used in the From_ line
   for the message when maildrop saves it in a mailbox file. Although a
   recipe may change the contents of the FROM variable, only the initial
   value gets saved in the From_ line.
