Debian notes:

1. Install amavisd-new-milter.

2.  The postinst script needs to add lines to one's sendmail.mc file that
tell it how to communicate with a milter program, e.g.:

define(`MILTER',1)
INPUT_MAIL_FILTER(`/usr/sbin/amavis-milter',`S=local:/var/lib/amavis/amavisd-new-milter.sock, F=T, T=S:10m;R:10m;E:10m')

Run sendmailconfig.

3.  Change/replace the following settings in /etc/amavis/amavisd.conf:

$unix_socketname = "/var/lib/amavis/amavisd.sock";
$forward_method = undef;
$notify_method = $notify_method = 'pipe:flags=q argv=/usr/sbin/sendmail -i -odd -f ${sender} -- ${recipient}';

Contributed and adapted from Susan Kleinmann <sgk@kleinmann.com>.
[End of Debian Notes]

===============================================================================
NOTE:
  A recommended sendmail setup is described in file README.sendmail-dual,
  which describes a dual-MTA setup. The sendmail milter setup as described
  in this file works as well, but with some functionality limitations.
  Please see the introduction section in README.sendmail-dual when deciding
  between milter setup and a dual-MTA setup.
===============================================================================

NOTE1:
  these instructions describe the amavisd-0.1 installation,
  but apply in large degree to amavisd-new as well.

  Don't forget to set the $forward_method to undef
  in amavisd.conf, and adjust the $notify_method.
  Also, the $final_*_destiny may use D_REJECT if desired.

NOTE2:
  a rewrite by Petr Rehor of the helper program amavis-milter.c to use
  the new AM.PDP protocol (README.protocol) is available as a separate
  project, see: http://sourceforge.net/projects/amavisd-milter/
  in FreeBSD ports collection: security/amavisd-milter

How To use AMaViS With sendmail/libmilter
*****************************************

General Notes
=============

By Rob MacGregor <rob.macgregor@techie.com>

SECURITY
   MILTER is designed such that milter applications do not need to
   run as root.  By not running amavis as root you improve security.
   Simply put, nothing that can run as an account other than root
   should be run as root.

   However, it's important to ensure that you run your virus scanners
   and both parts of amavis (amavisd and amavis-milter) as the same
   group.  It's worth giving daemonised virus scanners a different
   account, just to reduce the chance that the scanner modifies the
   message.  If you don't do this then you'll run into permission
   problems.  The account that you run amavis as *MUST* own the
   /var/amavis directory and the quarantine directory (usually
   /var/virusmails).

   Now, create the following account for amavisd and amavis milter:

         amavis (group amavis)

   If you use daemonised virus scanners then it is worth creating a
   separate account for them:

         vscan (group amavis)

GENERAL
   If you run into problems first check the FAQ at:
         http://www.amavis.org/amavis-faq.php3
   and the list archive at:
         http://marc.theaimsgroup.com/?l=amavis-user&r=1&w=2
   before asking questions on the list.  It's highly likely somebody
   has already come across the same problem and it's been solved.

   Oh, and don't forget to RTFM :-)

SOCKETS
   Amavis uses 2 sockets for communications.  One is for communication
   between sendmail and amavis-milter process (amavis-milter.sock).
   The protocol spoken over this socket is MILTER.

   The other is for communication between the 2 parts of amavis
   (amavisd.sock), i.e. between amavis-milter process and amavisd daemon.
   A protocol over this socket is _not_ MILTER, but a private amavis
   protocol.

   The first socket is fixed and cannot be changed (short of editing
   the source).  The second can be changed by the configure command.
   However if you set it to the same as the sendmail-amavis socket
   strange things will happen.  You should receive a message in the
   log of amavisd-new that indicates what the problem is, e.g.:
     RX_tempdir FAILED, retry: Invalid temporary directory '\000\000\000\rO'.
   Other versions of amavis may not produce any such warnings.

   The short version is:

      1) Don't change the socket details unless you know what you're
         doing.
      2) If you do change the socket name, don't use the name of the
         other socket.

CENTRALISING SCANNING (From Dibo <dibo@users.sourceforge.net>)
    If you want to place milter-amavis along with amavis daemon
    on another host, or just prefer inet sockets to Unix sockets,
    pick a free port number above 1024, and change:

    - in file sendmail.mc in the call to the macro INPUT_MAIL_FILTER
        replace:  S=local:/var/amavis/amavis-milter.sock
        with:     S=inet:port@hostname

      (substituting 'port' with your chosen port number,
      and substituting host name or IP address in place of 'hostname'
      to specify the host on which milter-amavis daemon is running)

    - when starting milter-amavis process, change the value of
      it's option -p:
        replace   -p local:/var/amavis/amavis-milter.sock
        with:     -p inet:port@0.0.0.0

      (substituting 'port' with your chosen port number,
      and optionally limiting the bind address (0.0.0.0) with the
      desired interface, e.g. 127.0.0.1 to limit bind to the
      loopback address)


Sendmail 8.12.x
===============

By Rob MacGregor <rob.macgregor@techie.com>

NOTE: Ensure you're running Sendmail 8.12.10 or later.  Earlier
      versions all have a remotely exploitable vulnerability
      (see CERT Advisory CA-2003-25 and other advisories).

Add the following to <sendmail source>/devtools/Site/site.config.m4:

	APPENDDEF(`confENVDEF', `-DMILTER')

Then build sendmail.  If you've already built sendmail, clean the old
tree by doing "rm -fr obj.*" in the sendmail source directory, or run
"./Build -c".  Once sendmail has finished building go into the
following directories under the sendmail source directory and do a
"make" and "make install":

	libmilter
	libsm
	libsmutil

Copy the .a files from under obj.*/libsm and obj.*/libsmutil to
somewhere the linker can find them (/usr/lib, /usr/local/lib or
similar).


Building AMAVIS(d)
==================

IMPORTANT: Versions of AMAVISd before 0.1 use a different configure
	command line.  If you're running an older version then UPGRADE.

Assuming you've copied the libraries to /usr/lib configure amavis(d)
with "--enable-milter --with-milter-includes=/usr/include
--with-milter-libs=/usr/lib" DO NOT USE the "--enable-relay",
"--enable-smtp" or "--with-origconf" options.

IMPORTANT: Unless you REALLY understand EXACTLY what you're doing,
	leave the --with-sockname option alone.  The default is correct
	and changing it may cause you problems.

When you run configure check that you see the following lines:

	checking for sm_errstring in -lsm... yes
	checking for sm_strlcpy in -lsm... yes
	checking for libmilter/mfapi.h... yes
	checking for smfi_main in -lmilter... yes
	We will use libmilter as the MTA

The summary should include:

	Configured for use with:    libmilter
	Configuration type:         sendmail/milter

If you don't see this, check that you've put the libmilter.a, libsm.a
and libsmutil.a files in a location the linker can find (see above).
Check that you've specified the correct paths to the libraries and
header files.

For building amavisd-new, see files README, INSTALL, and
helper-progs/README in its distribution.


Finishing Sendmail 8.12.x
=========================

In the sendmail.mc file add the following two entries (the first one
is mandatory):

	INPUT_MAIL_FILTER(`milter-amavis',
	    `S=local:/var/amavis/amavis-milter.sock, F=T, T=S:10m;R:10m;E:10m')
        define(`confMILTER_MACROS_ENVFROM',
            confMILTER_MACROS_ENVFROM`, r, b') # supply macros b,r to helper

Now rebuild your sendmail.cf file and install it (usually
/etc/mail/sendmail.cf).

Start amavisd and then sendmail.  Below is a suitable amavis startup
script for a Linux type system.  Check syslog for messages (probably
/var/log/mail or /var/log/mail/info).  You should see something like:

Oct 18 16:45:19 host amavis[24606]: starting.  amavisd 0.1 Sat Jul 28 10:03:56 UTC 2001
Oct 18 16:45:20 host sm-msp-queue[24618]: starting daemon (8.12.9): queueing@01:00:00
Oct 18 16:45:26 host sm-mta[24631]: starting daemon (8.12.9): SMTP+queueing@01:00:00

The following options can be passed to amavis-milter (0.1.1 or later)
to change the default behaviour:

    -x            From 0.1.1 this DISABLES the X_HEADER insertion.
    -d            Disable automatic daemonising of the client.
			All logging is now performed to stderr instead of stdout.
    -v            Increases the verbosity of the logging, can be repeated
                  for greater verbosity
    -g <group>    Sets the group the client runs as (the amavis account,
                  or your chosen account, MUST be a member of this group).
                  Normally this group will be "smmsp".  This is designed
                  for when you run sendmail as non-root and isn't
                  normally required.  See the amavis-milter(1) man page
                  for full details.


PERFORMANCE NOTES
=================

Ok, strictly speaking generic, but always useful.

You can (possibly) boost performance in a number of simple ways:

   * Use a daemonised scanner.  This way a new copy of the scanner doesn't
     have to be launched for every message.  Examples include Sophos+Sophie,
     Trend+Trophie and ClamAV.

   * Use separate disks/controllers for the amavis spool (/var/amavis) and
     the sendmail spool (/var/spool/...).

   * Put amavis on another system (assuming you've got a fast network).  This
     is particularly useful if your mail server is already I/O or processor
     bound.

   * Use memory based file systems (TMPFS in Linux and Solaris, MFS in
     (Free)BSD) for the amavis spool (/var/amavis).  Don't do this for the
     quarantine directory and don't do it for the sendmail spool without
     reading the tuning section in the Sendmail (Bat) book (3rd edition)
     by O'Reilly.

   * It's worth doing some simple checks to see if you're running out of
     memory or maxing out the processor or disk I/O.  The "top" command
     gives you a start on gathering this information.


>>>START /etc/rc.d/init.d/amavisd (or wherever it lives on your system)>>>
#!/bin/sh
#
# chkconfig: 2345 70 30
# description: AMAVISd is an anti-virus scanning interface for \
#		common mail servers.

# Source amavis configureation.
if [ -f /etc/sysconfig/amavis ] ; then
        . /etc/sysconfig/amavis
    else
        AMAVIS_ACCOUNT=amavis
        MILTER_SOCKET=/var/amavis/amavis-milter.sock
        MILTER_FLAGS=""		# Set the options you want passed to amavis-milter
fi

# See how we were called.
case "$1" in
  start)
        # Start daemons.
        echo -n "Starting amavis-milter: "
        rm -fr /var/amavis/amavis*.sock
        su - ${AMAVIS_ACCOUNT} -c /usr/sbin/amavisd
        sleep 5
        su - ${AMAVIS_ACCOUNT} -c "/usr/sbin/amavis-milter ${MILTER_FLAGS} -p local:${MILTER_SOCKET}"
        RETVAL=$?
        if [ $RETVAL -eq 0 ]; then
                echo " [  OK  ] "
                touch /var/lock/subsys/amavis
            else
                echo " [ FAIL ] "
        fi
        ;;
  stop)
        # Stop daemons.
        echo -n "Shutting down amavis-milter: "
        if [ -f /var/amavis/amavisd.pid ]; then
                # *** PAY ATTENTION ***
                # pkill only seems to exist in LINUX, whereas the -m option to killall only exists in BSD.
                # You may have to modify the following commands depending on your system.
                if [ -e /usr/bin/pkill ]; then
                        /usr/bin/pkill amavis-milter
                    else
                        killall -m amavis-milter
                fi
		su - ${AMAVIS_ACCOUNT} -c /usr/sbin/amavisd stop
                echo " [  OK  ] "
            else
                echo " [ FAIL ] "
        fi

        rm -f /var/lock/subsys/amavis
        ;;
  restart|reload)
        $0 stop
        $0 start
        RETVAL=$?
        ;;
  *)
        echo "Usage: amavis {start|stop|restart}"
        exit 1
esac
<<<END<<<

References:
[1] http://www.sendmail.com/partner/resources/development/milter_api/installation.html


        Last updated 3 October 2003 by Rob MacGregor <rob.macgregor@techie.com>
        Last updated 8 March 2004 by Mark Martinec (added milter macro {b})