<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  <title>Installing maildrop</title>
  <meta name="MSSmartTagsPreventParsing" content="TRUE" />
  <style type="text/css">
  /*<![CDATA[*/
  body {
  background-color: #FFFFFF;
  color: #000000;
  }
  :link { color: #0000EF }
  :visited { color: #51188E }
  :active { color: #FF0000 }
  /*]]>*/
  </style>
</head>
<body>
  <!-- Copyright 1998 - 2018 S. Varshavchik.  See COPYING for -->
  <!-- distribution information. -->
  <h1>Requirements</h1>
  <ul>
    <li>gcc that supports at least C++17 (<a href=
    "http://www.gnu.org/software/gcc/">http://www.gnu.org/software/gcc/</a>)
    </li>
    <li>GDBM/DB - optional.</li>
    <li>The PCRE2 library (<a href=
    "http://www.pcre.org">http:/www.pcre.org</a>) is required.</li>
    <li>The Courier Unicode Library (<a href=
    "https://www.courier-mta.org/unicode">https://www.courier-mta.org/unicode</a>)
    must be installed first.</li>
    <li>The <a href="https://www.gnu.org/software/libidn/">libidn2</a> library
    is required.</li>
    <li>
      <p>Courier Authentication Library - optional, for LDAP, MySQL, or
      PostgreSQL support.</p>
      <p>If the <code>configure</code> script detects that the Courier
      Authentication Library is installed, support for courier-authlib gets
      automatically compiled. Use the <code>--disable-authlib</code> option to
      manually disable courier-authlib support.</p>
      <p>When courier-authlib support is enabled, the <code>-d</code> option to
      maildrop will look up the account using the Courier Authentication
      Library, making it possible to store mail account configuration in an
      LDAP, MySQL, or a PostgreSQL database. See the courier-authlib
      documentation for more information.</p>
      <p>See <a href=
      "https://www.courier-mta.org/authlib/">https://www.courier-mta.org/authlib/</a>
      for more information.</p>
      <blockquote>
        <p><strong>NOTE:</strong></p>
        <p>When using the standalone maildrop build with courier-authlib, one
        of the following configurations must be used:</p>
        <ul>
          <li>Your mail server must invoke maildrop as the root user (the
          <code>-d</code> flag reads the mail account's uid and gid, then drops
          root).</li>
          <li>Manually change the permissions on the maildrop binary to be
          setuid root.</li>
          <li>Manually change the permissions on the courier-authlib's socket
          directory (<code>/usr/local/var/spool/authdaemon</code> by default)
          to be globally readable or executable.</li>
        </ul>
        <p>The default permissions on courier-authlib's socket directory blocks
        world-access to the filesystem socket connected to courier-authlib's
        authentication daemon process. In order for maildrop to connect to the
        authentication library, maildrop must either have root privileges
        (which will be temporary, as soon as maildrop determines the account's
        userid and groupid, it will drop root, before reading the
        <code>maildroprc</code> file), or courier-authlib's socket directory
        must have world read and execute permission.</p>
        <p>Note that if the permissions on the socket directory are changed,
        anyone on the system can connect and obtain any account's password!</p>
        <p>It is the system administrator's responsibility to choose the
        appropriate security policy when using the Courier Authentication
        Library.</p>
      </blockquote>
      <blockquote>
        <p><strong>NOTE:</strong></p>
        <p>When using the option to have maildrop invoked as root, an
        additional option to automatically create a new account's home
        directory becomes possible.</p>
        <p>This uses the <b>AUTH_MKHOMEDIR_SKEL</b> environment variable. If
        this environment variable is set, it must point to a template directory
        such as <code>/etc/skel</code>. If the environment variable is set, and
        the authenticated account's home directory does not exist, the contents
        of the template directory get recursively copied into the new home
        directory. The permissions of <b>AUTH_MKHOMEDIR_SKEL</b> and its
        contents are preserved, and the owner userid and groupid is set to the
        authenticated account's userid and groupid.</p>
        <p>Consult your mail server's documentation for more information on how
        to initialize the mail delivery agent's environment variables.</p>
      </blockquote>
    </li>
  </ul>
  <h1>Installing maildrop</h1>
  <h2>rpm and deb packages</h2>
  <p>These are not the same packages as the ones from various distributions'
  repositories. These packages carry a higher internal revision level in order
  to prevent them from getting upgraded by the distribution packaging, and
  their installation layout may differ from the distributions' preferred
  package installation layout. This packaging exists in order to have a
  convenient way of updating after a release without waiting for the
  distribution's package to get built, and to have a better correspondence with
  the documentation.</p>
  <p><b>NOTE:</b> If a distribution package is already installed it should be
  removed completely before switching to the upstream version (<span class=
  "c1">dnf remove</span> or <span class="c1">apt purge</span>). Preserve any
  existing configuration files, beforehand, in order to restore it after
  switching packages. This applies to all Courier packages. A switch to this
  maildrop package requires switching the courier-unicode package (and
  possibility courier-authlib package) too.</p>
  <p><b>NOTE:</b> These packages use their own, generic, installation layout
  that may deviate slightly from the package installation conventions preferred
  by the distributions.</p>
  <h2>rpm</h2>
  <p>Run <code>dnf install rpm-build</code> if it's not installed already,
  then:</p>
  <pre>rpmbuild -ta maildrop-VERSION.tar.bz2</pre>
  <p>If this fails due to any missing dependencies, install them.</p>
  <h3>Rocky/RHEL 8/9 notes</h3>
  <p>Courier packages require C++17 support, but the default version
  of gcc does not fully support it, and a newer gcc is needed:</p>
  <pre>dnf install --enablerepo=crb -y gcc-toolset-14
scl enable gcc-toolset-14 "rpmbuild -ta maildrop-VERSION.tar.bz2"</pre>
  <h2>deb</h2>
  <p>Run "apt install devscripts debhelper", if they're not installed already.
  Create an empty directory and copy/move the tarball into it:</p>
  <pre>
$ mkdir tmp
$ mv maildrop-VERSION.tar.bz2 tmp
$ cd tmp</pre>
  <p>Unpack the tarball and cd into the unpacked subdirectory:</p>
  <pre>
$ tar xvf maildrop-VERSION.tar.bz2
$ cd maildrop-VERSION</pre>
  <p>Run the <code>courier-debuild</code> script, this is a wrapper for
  <code>debuild</code>, and it forwards its parameters to it:</p>
  <pre>$ ./courier-debuild -us -uc</pre>
  <p>NOTE: the above steps must be followed strictly. The
  <tt>courier-debuild</tt> script expects the distributed tarball in its parent
  directory.</p>
  <p>NOTE: if the courier-debuild script stops with an error complaining about
    missing dependencies, then use "apt install" to install them, then try
    again.</p>
  <pre>$ DEBGCC=10 ./courier-debuild -us -uc</pre>
  <p>Setting the <code>DEBGCC</code> environment variable selects a non-default
  gcc version.</p>
  <p>NOTE: All Courier packages should be built with the same version of gcc,
  which is selected by the <code>DEBGCC</code> environment variable before
  running <code>courier-debuild</code>. <a href=
  "https://www.courier-mta.org/unicode/INSTALL.html">See
  <i>courier-unicode</i>'s <i>INSTALL</i> for more information</a>.</p>
  <h3>Ubuntu and Debian</h3>
  <p>Courier packages require C++17 support, but the default version
  of gcc on Ubuntu does not fully support it, and a newer gcc is needed:</p>
  <pre>$ sudo apt install -y gcc-10 g++-10
$ DEBGCC=10 ./courier-debuild -us -uc</pre>
  <p><code>make check</code> requires both the ISO-8859-1 based
    <code>en_US</code> locale in addition to the default
    <code>en_US.UTF-8</code>, on all versions of Ubuntu and Debian.</p>
  <h2>Maintainer Mode (see README in the git repository to set up)</h2>
  <p><tt>make rpm</tt> or <tt>make deb</tt>, as appropriate, will:</p>
  <ol>
    <li>
      <p>Increment an internal release number.</p>
    </li>
    <li>
      <p>Run <tt>make dist</tt>.</p>
    </li>
    <li>
      <p>Proceed and build a new release, creating the native packages in the
      rpm or deb subdirectory.</p>
    </li>
  </ol>
  <h2>Manual installation</h2>
  <p>The typical sequence of commands to install <i>maildrop</i> is as follows.
  You will likely need to use the GNU version of make. Other makes may not
  work. See below for definition of various options to the
  <code>configure</code> script:</p>
  <pre>
<code>   ./configure [options]
   make
   make install-strip
   make install-man</code>
</pre>
  <p>If the make command stops with syntax error in any Makefile, you probably
  have an older make utility. See if you have a <code>gmake</code> command
  available. If so, rerun <code>configure</code> as follows:<br /></p>
  <pre>
./configure [options] MAKE=gmake
</pre>
  <p>Then execute the remaining commands, replacing <code>make</code> with
  <code>gmake</code> every time.</p>
  <p>If <code>make install-strip</code> fails, try <code>make
  install</code>.</p>
  <p>The <i>configure</i> script creates <code>Makefile</code>, and
  <code>config.h</code>. After running <i>configure</i>, you may want to edit
  <code>xconfig.h</code>, and <code>config.h</code> in order to make minor
  adjustments to the configuration.</p>
  <p>Some versions of <code>make</code> may have problems handling the
  Makefile. If your <code>make</code> gives you errors, try using the
  <code>gmake</code> command instead - the GNU make.</p>
  <p>NOTE: <i>configure</i> attempts to automatically configure the following
  options for <i>maildrop</i> according to your specific system. After running
  <i>configure</i>, you should review these options and make any necessary
  adjustments.</p>
  <h2>WHAT GETS INSTALLED</h2>
  <p>If you're upgrading, read UPGRADING below.</p>
  <p>The following assumes that the default options are used. The usual GNU
  toolchain options can be used to relocate files from their default locations
  (run <code>./configure --help</code> for more information).</p>
  <ul>
    <li><code>/usr/local/bin</code> - A number of binaries will be installed
    here, starting with the main binary, <code>maildrop</code>, as well as
    additional utilities: <code>dotlock</code>, <code>maildirmake</code>,
    <code>makemime</code>, <code>reformail</code>, and <code>reformime</code>.
    If certain options are selected, some additional binaries may be installed
    here as well.<br />
    <br /></li>
    <li><code>/usr/local/man</code> - manual pages.<br />
    <br /></li>
    <li><code>/usr/local/include</code> - C header files, for development, if
    the <code>--with-devel</code> option is specified to the
    <code>configure</code> script.<br />
    <br /></li>
    <li><code>/usr/local/lib</code> - C libraries, for development, if the
    <code>--with-devel</code> option is specified to the <code>configure</code>
    script.<br />
    <br /></li>
    <li><code>/usr/local/share/maildrop/html</code> - HTML versions of manual
    pages installed in <code>/usr/local/man</code>.</li>
  </ul>
  <p>These are the default directories. The defaults can be changed using the
  standard <code>autoconf</code> options, run <code>./configure --help</code>
  for more information.</p>
  <h2>UPGRADING</h2>
  <h4>From version 1.1 or earlier.</h4>
  <p>Read <a href="UPGRADE.html">UPGRADE</a> for some important notes. The
  default installation directory/layout has changed.</p>
  <h4>From version 0.70 or earlier.</h4>
  <p>The --with-gdbm option has been renamed to --with-db. Its functionality
  remains the same. The name change is due to some internal housekeeping.</p>
  <h4>From version 0.65, or earlier.</h4>
  <p>If possible, use a prebuilt package on platforms with a package manager
  (rpm on Red Hat and derived distributions, deb on Debian, etc). If you've
  been compiling and instaling maildrop manually, be aware of the following
  changes when upgrading from 0.65 or earlier.</p>
  <ul>
    <li>The <i>makegdbm</i> utility has been renamed as makedat, to better
    reflect the fact that it can be compiled with DB as well as GDBM database
    support.<br />
    <br /></li>
    <li>Config scripts from earlier versions usually created a Makefile that
    automatically gzipped all manual pages during installation. This code has
    been taken out. <i>make install</i> now installs uncompressed manual pages
    only. If you do a <i>make install</i>, you'll need to go in and manually
    remove gzipped manual pages from the previous version of
    <i>maildrop</i>.<br />
    <br /></li>
    <li>You will need to have Perl 5 available to complete the compilation and
    installation process.<br />
    <br /></li>
  </ul>
  <h2>Operating system specific notes</h2>This section will list any
  platform-depended issues.
  <h4>Solaris</h4>This problem has been reported for Solaris 2.6. Other Solaris
  versions or related platforms can be affected. Symptom - trying to run
  <code>maildrop</code> results in an error message saying that libstdc++
  cannot be opened.
  <p>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 <code>/usr/local/lib.</code> Solaris's runtime
  linker will only open shared libraries in <code>/usr/lib</code> for programs
  with the setuid or setgid bit set.</p>
  <p><code>Maildrop</code> is installed with the setuid and setgid bits set, so
  that <code>maildrop</code> can change to the recipient's userid and group id.
  There are three easy workarounds.</p>
  <ol>
    <li>If you can configure your mail transport agent to set the correct user
    and group IDs before running <code>maildrop</code>, <code>maildrop</code>
    will not need the setuid and setgid privileges. After running <code>make
    install-strip</code>, go ahead and manually turn these bits off for the
    <code>maildrop</code>, <code>dotlock</code>, and
    <code>reformail</code>.<br />
    <br /></li>
    <li>Create a soft link from <code>/usr/lib/local</code>to
    <code>/usr/local/lib</code>, and add /usr/lib/local to the
    <code>LD_LIBRARY_PATH</code> environment variable.<br />
    <br /></li>
    <li>Create a soft link to libstdc++ from <code>/usr/lib</code>to
    <code>/usr/local/lib</code></li>
  </ol>
  <h4>Any sendmail platform</h4>There are two quirks that anyone installing
  <code>maildrop</code> on a sendmail-based system should be aware of.
  <ul>
    <li>Unlike other mail transport agents, most sendmails completely discard
    error messages from the local delivery agent. Therefore, you should use the
    <code>--enable-syslog=1</code> flag to <code>configure</code> on systems
    running sendmail, unless you are very familiar with <code>maildrop</code>.
    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 <code>maildrop</code> will report an
    error message, sendmail will discard the message without recording it
    anywhere. With the <code>--enable-syslog=1</code> 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.<br />
    <br /></li>
    <li>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 <code>maildrop</code>'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 <code>maildrop</code> with the userid set to
    the sender, and the -d option specifying the recipient. The default
    <code>maildrop</code> configuration allows only certain "trusted" users to
    use the -d option. What will happen is that <code>maildrop</code> 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.</li>
  </ul>
  <p>Note that this applies ONLY if you have <code>maildrop</code> defined as
  the local delivery agent in <code>sendmail.cf</code>. This will happen if
  <code>maildrop</code> is invoked from a <code>.forward</code> 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 <code>sendmail.cf</code>) to queue messages; or, you can specify
  <code>--enable-restrict-trusted=0</code> option to <code>configure</code>,
  and lift the restriction on the -d option. However, keep in mind that the
  <code>--enable-restrict-trusted=0</code> 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
  <code>maildrop</code> 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.</p>
  <h4>Any AFS platform</h4>
  <p>If you're using AFS, it is possible that daemon processes will not even
  have the read privileges on their effective userid's home directory. maildrop
  likes to keep its temporary files in <code>$HOME/.tmp</code>, instead of
  creating them in a shared public directory. You will need to specify the
  --disable-tempdir flag when running configure, which configures maildrop to
  use /tmp or /var/tmp for temporary file storage. (NOTE - this is already a
  default option effective with maildrop 1.1)</p>
  <h2>Options to configure</h2>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:<br />
  &nbsp;
  <ul>
    <li><code>--enable-DEBUG</code> - specifying this parameter to configure
    enables some debugging code. Used only by those who know how to use it.
    :-)<br />
    <br /></li>
    <li><code>--without-db</code> - do not compile support for GDBM or DB
    databases. Because supporting GDBM/DB databases significantly increases the
    size of <i>maildrop</i>, GDBM/DB support can be omitted. If you do not have
    GDBM/DB libraries, <i>configure</i> automatically disables GDBM/DB support.
    Specifying <code>--without-db</code> disables the <code>gdbmopen</code>,
    <code>gdbmclose</code>, <code>gdbmfetch</code>, and <code>gdbmstore</code>
    functions, and does not compile or install the
    <code>maildrop.makedat</code> utility.<br />
    <br /></li>
    <li><code>--with-db=db</code> - use the Berkeley DB library instead of
    GDBM. This option will transparently use libdb.a instead of libgdbm.a. The
    <code>gdbmopen</code>, <code>gdbmclose</code>, <code>gdbmfetch</code>, and
    <code>gdbmstore</code> functions work exactly the same, but they will use
    libdb instead of libgdbm.<br />
    <br /></li>
    <li><code>--with-etcdir=<i>directory</i></code> - use the specified
    directory instead of <code>/etc</code>, which is where <i>maildrop</i>
    expects to find some configuration files and directories.<br />
    <br /></li>
    <li><code>--enable-syslog=1</code> - 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.<br />
    <br /></li>
    <li><code>--enable-maildrop-uid=<b>root</b></code> and
    <code>--enable-maildrop-gid=<i>mail</i></code> - sets the userid and the
    groupid for the <code>maildrop</code>, <code>maildirmake</code>, and
    <code>dotlock</code> programs. If not specified, they default to "root" and
    "mail" respectively. See <code>MAILBOX_MODE</code> and
    <code>RESET_GID</code> below for more information.<br />
    <br /></li>
    <li><code>--with-devel</code> - install development libraries and include
    files. This option causes <code>make install</code> to copy over and
    install libraries, include files, and manual pages, that are used by
    maildrop to parse and process E-mail messages.<br />
    <br /></li>
  </ul>Most systems invoke the mail delivery agent and specify the account to
  which the message is addressed. The mail delivery agent is a program that's
  owned by root, and has the set-user-id bit set. The mail delivery agent then
  immediately resets its userid to whomever the message is addressed to.
  <p>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 set-user-id bit after installing <i>maildrop</i>.</p>
  <p>Some mail systems may use group privileges in order to write to the system
  mailbox directory. <i>maildrop</i> is installed with the set-group-id bit set
  as well, and the mail group is assumed to be 'mail'.&nbsp; If a mail group
  other than 'mail' is used, specify it via the <code>--enable-maildrop-gid
  option</code>. 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, <i>maildrop</i>
  will drop any acquired group ID right away, so its not necessary to remove
  the setgid bit. <i>maildrop</i> attempts to detect if this is the case, but
  you always need to confirm this.<br />
  &nbsp;</p>
  <ul>
    <li><code>--enable-sendmail=<i>program</i></code> - sets the initial value
    for the SENDMAIL environment variable for <code>maildrop</code> recipes.
    This is the pathname to the default mail delivery agent. If this option is
    not specified, <code>configure</code> will try to find it itself.<br />
    <br /></li>
    <li><code>--enable-lockext-def=<i>extension</i></code> - sets the initial
    value for the <code>LOCKEXT</code> environment variable in maildrop. This
    is the filename extension of dotlock files. The default is ".lock".<br />
    <br /></li>
    <li><code>--enable-locksleep-def=<i>seconds</i></code> - sets the initial
    value for the <code>LOCKSLEEP</code> environment variable. This is how long
    <i>maildrop</i> waits before trying to create a dotlock file again, if the
    dotlock file already exists. The default is 5 seconds.<br />
    <br /></li>
    <li><code>--enable-locktimeout-def=<i>seconds</i></code> - sets the initial
    value for the <code>LOCKTIMEOUT</code> environment variable. This is how
    long <i>maildrop</i> waits before removing a stale dotlock file. The
    default is 60 seconds.<br />
    <br /></li>
    <li><code>--enable-lockrefresh-def=<i>seconds</i></code>- sets the initial
    value for the <code>LOCKREFRESH</code> environment variable. This is how
    often <i>maildrop</i> refreshes its own dotlock files, to keep them from
    going stale. The default is 15 seconds.</li>
  </ul><a href="maildropfilter.html#predefined">See the manual page for
  maildropfilter</a> for more information on these variables.
  <ul>
    <li><code>--enable-tempdir=<i>directory</i></code> - sets the name of a
    subdirectory in each user's home directory where <i>maildrop</i> writes
    temporary files. <i>maildrop</i> will create this directory, if missing.
    The default is <code>.tmp</code>.<br />
    <br /></li>
    <li><code>--disable-tempdir</code> - do not use a subdirectory, instead
    create temporary files in a shared /tmp or /var/tmp directory. May be
    required on systems where daemon processes execute without privileges to
    access shared filesystems. This is now the default option starting with
    maildrop 1.1.<br />
    <br /></li>
    <li><code>--enable-smallmsg=<i>bytes</i></code> - sets the size of a
    message, in bytes, before <i>maildrop</i> 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, <i>maildrop</i> saves larger messages in a temporary file.
    If the standard input to <i>maildrop</i> is a file, a temporary file is not
    necessary. The default is 8192 bytes.<br />
    <br /></li>
    <li><code>--enable-global-timeout=<i>seconds</i></code> - sets numbers of
    seconds that <i>maildrop</i> is willing to spend in order to deliver a
    single message. This value becomes a hard coded limit. When the time
    expires, <i>maildrop</i> terminates with an <code>EX_TEMPFAIL</code> error
    code. This is intended to stop runaway mail filters. The default is 300
    seconds (five minutes).<br />
    <br /></li>
    <li><code>--enable-restrict-trusted=<i>flag</i></code> - if set to 1,
    <i>maildrop</i> permits only certain "trusted" user or group 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.<br />
    <br /></li>
    <li><code>--enable-keep-fromline=<i>flag</i></code> - if set to 1, when
    <i>maildrop</i> saves a message to a mailbox file, it will use the same
    <code>From_</code>line address which was present in the original message.
    If the original message lacked a <code>From_</code> line, <i>maildrop</i>
    will use the name of the user running <i>maildrop</i>. If set to 0,
    <i>maildrop</i> will keep the original <code>From_</code> line address only
    if invoked by root, and reset it otherwise. The default value of this
    option is the value of the <code>--enable-restrict-trusted</code> option.
    Note that this option is new to <i>maildrop</i> version 0.54b. The logic in
    the previous version of <i>maildrop</i> was always the same as if this
    option was 0. Therefore, depending upon the value of the
    <code>--enable-restrict-trusted</code> flag, you may find that
    <i>maildrop</i> behavior changes with version 0.54b. This option also
    controls the semantics of the <code>-f</code> option to <i>maildrop</i>
    (see below).<br />
    <br /></li>
    <li><code>--enable-trusted-users=<i>'...'</i></code> - sets the list of
    users allowed to use the -d option if
    <code>--enable-restrict-trusted</code> is set to 1. If
    <code>--enable-restrict-trusted</code> 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
    <i>maildrop</i> as the local delivery agent this list must include the
    userid that the mail transport agent runs as. If this option is not
    specified, <i>maildrop</i> attempts to put together a list including common
    mail system user ids.<br />
    <br /></li>
    <li><code>--enable-trusted-groups=<i>'...'</i></code> - this is similar to
    the <code>--enable-trusted-users</code> option, but specifies a list of
    group IDs instead of user IDs. If <code>--enable-restrict-trusted</code>
    option is used, the <code>-d</code> option will be permitted only if the
    real userid, of whoever's invoking <code>maildrop</code>, is included in
    the trusted users list, OR if the real groupid is included in the trusted
    groups list, OR if the effective groupid is included in the trusted groups
    list.<br />
    <br />
    CAUTION: the default configuration script installs <code>maildrop</code>
    with the set group ID bit set, so that the effective groupid will always be
    the same in the default maildrop configuration. If this group ID is
    included in the trusted groups list, this effectively will allow everyone
    to use the <code>-d</code> option.<br />
    <br />
    The trusted groups feature has been implemented in order to add additional
    flexibility in setting up a secure <code>maildrop</code> environment. If
    the <code>--enable-trusted-groups</code> option is not used, the trusted
    groups list is empty, so that the semantics of the trusted users option
    remains the same as with previous versions of <code>maildrop</code>.<br />
    <br /></li>
    <li><code>--enable-use-flock=<i>flag</i></code> - if this option is set to
    1, maildrop will use either the <code>flock()</code>, the
    <code>lockf()</code>, or the <code>fcntl()</code> system call to lock a
    mailbox file when delivering a message. On most systems, all three use
    compatible locking mechanisms. In some very isolated cases,
    <code>flock()</code>, <code>lockf()</code>, and <code>fcntl()</code>, are
    different, incompatible, locking mechanisms. <i>maildrop</i> <b>must use
    the same locking mechanism</b> as any mail reading programs. The
    configuration script will run some tests to determine what locking function
    calls are available, and will choose one by itself. The
    <code>--with-locking-method</code> can be used to manually choose the
    locking function call to use.<br />
    <br /></li>
    <li><code>--with-locking-method=<i>name</i></code> - manually select a
    locking function call. <i>name</i> is either "fcntl", "flock", or "lockf".
    Otherwise the configuration script will pick one by itself.<br />
    <br /></li>
    <li><code>--enable-use-dotlock=<i>flag</i></code> - if this option is set
    to 1, <i>maildrop</i> will create <code>.lock</code> files in order to gain
    access to the system mailbox file. If this option is set to 0, maildrop
    will not use .<code>lock</code> files automatically. However, the
    <code>dotlock</code> command can still be used to manually create .lock
    files. The default value for this option is 1, <b>unless
    <code>maildrop</code> detects that the system mailbox directory does not
    have the sticky bit set</b> (set below), in which case the default option
    is 0. <code>maildrop</code> 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 <code>--enable-use-flock</code>and
    -<code>-enable-use-dotlock</code> to be set to 1, in which case both
    locking mechanisms are used simultaneously.<br />
    <br /></li>
    <li><code>--with-trashquota</code> - include deleted messages, and the
    Trash folder, in the estimated quota usage for maildirs. This should be
    used if related packages (SqWebMail, Courier-IMAP) were also compiled with
    the <code>--with-trashquota</code> option.<br />
    <br /></li>
    <li><code>--with-dirsync</code> - after delivering a new message to a
    maildir explicitly sync the maildir's <code>directory</code> directory.
    There's a school of thought which believes that the Linux ext2 filesystem
    requires the parent directory to be synced, in addition to the new message
    file that's just been written to disk. There's another school of thought
    that thinks that this issue is completely blown out of proportion, and is
    really nothing more than a tempest in a teapot. However -- to accomodate
    the former school of thought -- this option adds a little bit of extra code
    to sync the parent directory.<br />
    <br /></li>
  </ul>
  <h3>Selecting an alternate C++ compiler</h3><i>maildrop</i> is written in
  C++. Some systems may have more than one C++ compiler available. If the
  default C++ compiler that's selected by the <code>configure</code> 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
  <code>./configure</code>, set the <code>CXX</code> environment variable to
  the C++ compiler to be used. For example, to select the <code>CC</code>
  compiler:
  <pre>

$ CXX=CC
$ export CXX
$ ./configure [options]
</pre>Then proceed as usual. The <code>CXXFLAGS</code> environment variable can
also be used to override compiler flags that <code>configure</code> selects.
  <h3>Configuring the location of the system mailbox</h3>When <i>maildrop</i>
  has a message to deliver to a user, <i>maildrop</i> must know where user's
  mailbox is. Different systems use different places to store E-mail, and
  different mechanisms to access it. And even on the same operating system you
  may have variations due to different mail software.
  <p>Here are just some of the possible scenarios that may exist that
  <i>maildrop</i> knows how to handle:<br />
  &nbsp;</p>
  <ul>
    <li>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 partitioned into a hierarchical tree, based upon
    the initial letters of the user name. For example, the mailbox for the user
    jtomas is <code>/var/mail/j/jt/jthomas</code>; mail for sjones is stored in
    <code>/var/mail/s/sj/sjones</code>.<br />
    <br /></li>
    <li>Instead of storing mail in a separate directory, the system may store
    incoming mail in each user's home directory.<br />
    <br /></li>
    <li>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 <i>maildrop</i> as your local delivery agent
    you may implement the maildir format without having to use Qmail itself.
    Maildir is a much more efficient mail storage format which requires far
    less overhead. No locking of any kind is needed; multiple instances of
    <i>maildrop</i> can dump mail into the same maildir at the same time.<br />
    <br /></li>
    <li>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 <code>flock()</code> function on the mailbox
    file itself. <i>maildrop</i>, by default, uses both mechanisms, <i>except
    in one case</i> (see the <code>--enable-use-dotlock</code> option to
    configure, above), but one or the other can always be selected to be used
    exclusively.<br />
    <br /></li>
    <li>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. An alternative 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. The mail delivery agent runs under the user
    id, and the mail group id. This allows the mail delivery agent to create
    new mailboxes, and have the write permission on the user's mailbox. The
    <code>flock()</code> function is used to lock an individual mailbox.</li>
  </ul>As you can see, there is a lot of variation in possible mail setups. It
  is important that <i>maildrop</i> is configured to match your existing mail
  setup.&nbsp; The <code>configure</code> script tries to automatically figure
  out the correct settings, but you MUST always verify the output file,
  <code>config.h</code>, to make sure that the settings are correct.
  Description of each variable defined in <code>config.h</code>follows. In
  addition, there are certain variables defined in a different file,
  x<code>config.h</code>. These are settings that <code>config.h</code> cannot
  automatically determine.
  <h4>DEFAULT_DEF</h4>This variable specifies the initial setting for the
  <code>DEFAULT</code> variable in <i>maildrop</i>, which should be the
  location of the system default mailbox. If <code>DEFAULT_DEF</code> begins
  with a slash, it should refer to a directory, and <i>maildrop</i> will
  automatically append the user's name.
  <p>If it doesn't begin with a slash, <i>maildrop</i> will prepend the user's
  home directory to <code>DEFAULT_DEF</code>. To use <i>maildrop</i> with
  qmail, which normally delivers to <code>$HOME/Mailbox</code>, set
  <code>DEFAULT_DEF</code> to <b><code>./Mailbox</code></b>.</p>
  <p>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 <code>/var/mail/j/jo/john</code>
  and mail to user "root" is delivered to <code>/var/mail/r/ro/root</code>,
  <code>DEFAULT_DEF</code> should be set to <b><code>/var/mail/=/==</code></b>
  (<i>maildrop</i> automatically appends the full user name as the last
  component).</p>
  <p>If the <code>DEFAULT_DEF/DEFAULT</code> variable refers to a directory,
  <i>maildrop</i> assumes that it is delivering the message to a maildir,
  otherwise <i>maildrop</i> will deliver mail to a mailbox file, creating a new
  file if necessary. <i>maildrop</i> <b>does not</b> deliver mail to flat
  directory, like procmail. If you need to save messages in a directory, use
  the included program, <code>maildirmake</code>, to create a maildir
  directory.</p>
  <h4>MAILBOX_MODE and RESET_GID</h4>Here are the required setting in two of
  the most common mailbox environments:<br />
  &nbsp;
  <ul>
    <li>Mailbox spool directory has the sticky bit set, mailboxes are readable
    and writable by the user only - set <code>MAILBOX_MODE</code> to 0600, and
    <code>RESET_GID</code> to 1.<br />
    <br /></li>
    <li>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 ID -
    set <code>MAILBOX_MODE</code> to 0600, and <code>RESET_GID</code> to
    0.</li>
  </ul><code>MAILBOX_MODE</code> are the permissions maildrop uses to create
  new mailbox files. If a mailbox file already exists, maildrop is not going to
  change its permissions.
  <p><code>RESET_GID</code> indicates whether <i>maildrop</i> should
  immediately drop any set-group-id privileges. <i>maildrop</i> is installed
  with the set-group-id bit set with <i>maildrop</i>'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 <code>RESET_GID</code> to 0 to keep the mail group ID,
  and <b>specify the mail group</b>using the <code>--enable-maildrop-gid</code>
  flag to configure (see above).</p>
  <h4>TRUSTED_USERS</h4>If <code>--enable-restrict-trusted</code> option given
  to the <code>configure</code> script is set to 1 (this is the default),
  <i>maildrop</i> 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.
  <p>Mail can be delivered in two different ways:<br />
  &nbsp;</p>
  <ul>
    <li>The mail transport agent runs with root privileges. To deliver mail to
    a local user, the mail transport agent runs <i>maildrop</i> after changing
    the user id to the local user. In this case the -d option is not
    needed.<br />
    <br /></li>
    <li>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
    <code>TRUSTED_USERS</code> variable.</li>
  </ul>If <code>--enable-restrict-trusted</code> option given to the
  <code>configure</code> 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.
  <h3>Other configuration variables</h3>The <code>configure</code> script also
  sets the following variables in <code>autoconf.h</code>. After running the
  <code>configure</code> script, you may need to make some adjustments to these
  variables also.
  <h4>DEFAULT_PATH</h4>This variable in "autoconf.h" sets the initial contents
  of the <code>PATH</code> variable, which is the initial system search path
  for commands invoked by <i>maildrop</i> as child processes.
  <h4>SENDMAIL_DEF</h4>This variable in "autoconf.h" sets the initial contents
  of the <code>SENDMAIL</code> variable, which is the local mail transport
  agent. <i>maildrop</i> runs this program when instructed to deliver mail to a
  mailbox whose name begins with the forwarding "!" character.
  <h4>Other variables in autoconf.h</h4>All the other variables are self
  explanatory, and rarely need to be changed.
  <h2>Using maildrop with sendmail</h2>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
  &lt;ejs<code>@</code>bfd.com&gt;:
  <pre>

Mlocal,         P=/usr/local/bin/maildrop, F=lsAw5:/|@SPfhn, S=10/30, R=20/40,
                T=DNS/RFC822/X-Unix,
                A=maildrop -d $u
</pre>You may also consider including the D, F, and M flags as well.
  <h2>The -f option to maildrop</h2>The -f option is new to version 0.55. The
  -f option sets the initial value of the <code>FROM</code> variable. If no -f
  option is given, <i>maildrop</i> looks at any <code>From_</code> line in the
  message being delivered, otherwise it defaults to the name of the user who
  invoked maildrop.
  <p>If the <code>--enable-keep-fromline</code> option is set to 0, anyone may
  use the -f option. If <code>--enable-keep-fromline</code> is set to 1, only
  "trusted" users (as defined by --enable-trusted-users) may use the -f option
  (ignored for everyone else).</p>
  <p>The initial value of the <code>FROM</code> variable is also used in the
  <code>From_</code> line for the message when <i>maildrop</i> saves it in a
  mailbox file. Although a recipe may change the contents of the
  <code>FROM</code> variable, only the initial value gets saved in the
  <code>From_</code> line.<br /></p>
  <h3>Maildirs</h3>
  <p><i>maildrop</i> supports an alternative mail storage format called
  "maildir". Unlike regular mailboxes, maildirs do not require locking, and are
  much faster to use. Support for maildirs is not universal, but the number of
  software packages that understands maildirs is constantly growing.</p>
  <p>A maildir is a specially formatted directory, where messages are stored as
  individual files, according to certain conventions. Use the
  <code>maildirmake</code> command to create a maildir, with its structure and
  permissions properly set:</p>
  <p><code>maildirmake ./Maildir</code></p>
  <p>This creates a subdirectory in the current directory called "Maildir",
  which is then prepared to store E-mail messages.</p>
  <h3>Maildir folder extension</h3>
  <p>This version of <i>maildrop</i> supports two extensions to the traditional
  maidlir format: folders and quotas. The standard maildir format does not
  support any kind of a folder hierarchy, and depends on the underlying
  filesystem to enforce maximum usage quotas.</p>
  <p>It is important to note that at this time <strong>not all maildir software
  supports these extensions</strong>. Support is implemented mainly in other
  Courier packages. Descriptions of these extension are freely available,
  hopefully other software packages will add support for these extensions
  too.</p>
  <p>Names of folders are limited by the maximum filename size of your
  filesystem, and the names may not start with a period. Use the -f option to
  maildirmake to create a new folder:</p>
  <p><code>maildirmake -f Important ./Maildir</code></p>
  <p>"<code>./Maildir</code>" must already be an existing maildir. The -f flag
  creates a folder inside an existing maildir. A folder is just a subdirectory
  within a maildir that is itself a maildir. The name of the subdirectory is
  the folder name prefixed by a period. Also, the folder subdirectory contains
  a zero-length file called "maildirfolder".</p>
  <p><i>Maildrop</i> can deliver to folders just like to regular maildirs:</p>
  <p><code>to "./Maildir/.Important"</code></p>
  <p>Anywhere <i>maildrop</i> can deliver to a maildir, it can also deliver to
  a maildir folder.</p>
  <p>See the manual page for <code>maildirmake</code> for more information.</p>
  <h3>Maildir quota extension</h3>
  <p>The quota extension allows maximum maildir quotas to be enforced where
  filesystem-based quotas are not available, or cannot be used. This quota
  mechanism has a number of limitations which are discussed in the manual page
  for <code>maildirquota</code>, which contains more information.</p>
  <p>Quota enforcement can be implemented by setting the
  <code>MAILDIRQUOTA</code> variable in <i>maildrop</i>, as described in the
  <code>maildirquota</code> manual page.</p>
  <p>Of course, quotas will be enforced only when <i>maildrop</i> is used to
  deliver mail. Other applications, that do not understand the quota
  enhancement, will not enforce any quotas. Mail delivered to a maildir by
  other applications will not figure in quota calculation for some period of
  time. Eventually, a regularly scheduled quota recalculation will pick them up
  and include them in the current maildir quota.</p>
</body>
</html>
