# 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 <username>" 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.