
                   Mail Avenger Installation Instructions

   The following is a brief list of things to do to install and configure
   Mail Avenger.

   Installation: Follow these steps to compile and install Mail Avenger
   from source. If your operating system comes with a port or package of
   mail avenger, you can skip ahead to Configuration.

    0. Install BerkeleyDB database version 4.1 or later, if you do not
       already have it. Most operating systems come with an optional
       port/package for BerkeleyDB, making it easy to install. (Check for
       a package name like "db" or"db4".) Alternatively, you can download
       and install BerkeleyDB from http://www.sleepycat.com/.

    1. Compile the software using the standard GNU autoconf script,
       which requires running the following commands:

                gzip -dc avenger-x.x.tar.gz | tar xvf -
                cd avenger-x.x
                ./configure
                make

       Note that if you want Mail Avenger to support SASL authentication,
       you should first install the Cyrus SASL2 library from
       ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/, then, when following
       the above instructions, configure Mail Avenger using the command:

                ./configure --enable-sasl

    2. Install the software by running the following command as root:

                make install

   Configuration: Once Mail Avenger is installed, you must configure
   asmtpd, the avenger SMTP daemon.

    3. Create a user called avenger on your system. This is the user ID
       under which system-wide avenger scripts will run. (If you wish to
       use a name other than "avenger", you can put the directive
       "AvengerUser " in the asmtpd.conf configuration file when you
       create that.)

    4. If you run sendmail, make sure the avenger user you just created
       has permission to read the sendmail alias database (by default
       /etc/mail/aliases.db). On some systems, sendmail will stubbornly
       keep changing the alias database so that it is only readable by
       group wheel, in which case you must add the avenger user to the
       wheel group.

    5. Create the directory /etc/avenger and populate it with sample
       configuration files with the following commands:

                mkdir /etc/avenger
                cp /usr/local/share/avenger/asmtpd.conf /etc/avenger/
                cp /usr/local/share/avenger/unknown /etc/avenger/

    6. Edit the file /etc/avenger/asmtpd.conf. By default, it is
       configured for sendmail. You will almost certainly need to edit it
       if you are using another MTA, and even with sendmail you will
       probably want to look over all the configuration options anyway.
       See the asmtpd.conf(5) man page for more information about the
       format of this file.

    7. Edit the file /etc/avenger/unknown to handle unknown users
       properly. This script governs what happens to mail for users who
       are not in the password file, who have uid 0, or who don't have
       valid shells.

          + If you are running sendmail and your alias file is
            /etc/mail/aliases.db, the sample file is okay as long as the
            avenger user can read the aliases.db file.

          + If you are running qmail, you must uncomment the QMAIL_OPT
            line. However, this only works if you are not using the qmail
            users/assign file.

          + If you are running any other MTA, or are using qmail with the
            users/assign file, you will have to write your own, custom
            /etc/avenger/unknown script.
            You can alternatively just delete /etc/avenger/unknown
            entirely. You won't lose mail, but your system will then send
            back bounce messages for unknown users, which is less
            efficient than rejecting mail during the SMTP transaction.
            (Of course, asmtpd will still use SPF to reject forged mail
            outright.)

    8. Create a file /etc/avenger/domains. List each domain for which you
       would like to receive mail, followed by a colon, one per line. For
       example:

                my.first.domain:
                my.second.domain:

    9. Fire it up! Run the command asmtpd as root. You may also want to
       set things up to run this command automatically on system startup.

   Optional steps: Once you have the Avenger SMTP daemon up and running,
   you may wish to do any of the following.

     * Publish SPF records for your domains, if you haven't already. See
       http://spf.pobox.com/ or the handy configuration wizard at
       http://spf.pobox.com/wizard.html for more information on SPF.

     * Play with more scripts. Read the man page for avenger(1),
       create a .avenger/rcpt file in your home directory, and maybe
       create a site-wide default file /etc/avenger/default.

     * Configure the avenger local delivery agent, avenger.local. (See
       the avenger.local(8) man page for more information.)

          + If you use sendmail, include
            /usr/local/share/avenger/avsendmail.m4 towards the end of
            the ".mc" file you use to generate sendmail.cf with the
            following line:

                include(`/usr/local/share/avenger/avsendmail.m4')

          + If you use postfix, add the following lines to
            /etc/postfix/mail.cf, but be sure to substitute the correct
            path for mail.local:

                prepend_delivered_header = forward, file
                mailbox_command = /usr/local/libexec/avenger.local
                                  --fallback /usr/libexec/mail.local
                                  -D "$RECIPIENT" -d "$LOCAL"

          + If you use qmail, you don't really need to install
            avenger.local, because qmail already has a similar mechanism
            for delivering extension addresses.

