===============================================================================
NOTE:
  this file is rather old and not well maintained.

  A recommended sendmail setup is described in file README.sendmail-dual,
  which describes a dual-MTA setup. The sendmail milter setup as described
  in README.milter works as well, but with some functionality limitations.
===============================================================================


AMaViS & sendmail
*****************

Scanning only incoming mail
---------------------------

The amavis script is designed to be used in the sendmail.cf configuration
file in a similar way to how tcpd is used in /etc/inetd.conf.

Amavis helper program receives sender ($f) and recipients ($u) from the
command line, and the other arguments after '--' should be the original
local delivery agent with original arguments.  Amavis will run the original
command after scanning for viruses if mail is clean.

As most people generate sendmail.cf from a m4 file (we assume sendmail.mc),
you should add the following just before the MAILER definitions:

MODIFY_MAILER_FLAGS(`LOCAL',`-r')dnl
define(`LOCAL_MAILER_ARGS',`amavis $f $u --' LOCAL_MAILER_PATH `-d $u')dnl
define(`LOCAL_MAILER_PATH',`/usr/local/sbin/amavis')dnl

The resulting Mlocal mailer entry could look like:

Mlocal,	P=/usr/local/sbin/amavis, F=lsDFMAw5:/|@qPmn9S,
	S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
	T=DNS/RFC822/X-Unix, U=root:amavis,
	A=amavis $f $u -- /usr/libexec/mail.local -d $u

The user and group may be specified with the U option to the mailer.
The group name in 'U=root:amavis' should match the chosen group name
of the daemon amavisd(-new).

This setup is probably the trickiest of them all to get right
because of the conflicting daemon UID and file permission requirements
of the different components in play. The amavisd daemon should not be
running as root for security reasons, whereas the mail.local LDA needs
privileges to access user mailboxes. Running amavis helper program
as root:amavis retains root privileges for the helper program, while
still alowing amavisd daemon process to access the temporary directory
in the same group, even if not running as root.


Scanning incoming/outgoing and relayed mail
-------------------------------------------

  The concept for scanning incoming/outgoing and relayed mail is
different from the concept described in the AMaViS documentation.
If you are running a newer version of sendmail (8.10.0 or better),
we recommend to use the milter API. See README.milter for details.

  We use two different setups (.cf files) for sendmail, one is the original
configuration, the second has a different Queue-Directory, another status
file and most important a changed Rule Set 0 and the Mailer Definition AMaViS,
so that AMaViS is always called first. If no virus is detected, we pass
the mail to sendmail again, but advise it to use the original configuration.

  Note: I assume that sendmail.cf is in /etc - on your system it may be
in /etc/mail

  Setting it up in easy 5 steps (without the m4 way)
(please *read* the example configuration section below, too!):

Step 1: Copy your /etc/sendmail.cf file to /etc/sendmail.orig.cf
Step 2: Change sendmail.cf manually

a) open /etc/sendmail.cf in your favorite editor

b) change the queue directory, i.e. to
O QueueDirectory=/var/spool/mqamavis

c) change the status file, i.e. to
O StatusFile=/var/log/amavis.st

d) change rule set 0 to
R$*		$: $>Parse0 $1		initial parsing
R<@>		$#local $: <@>		special case error msgs
R$*		$: $>98 $1		handle local hacks
R$*		$#amavis $:$1
#R$*		$: $>Parse1 $1		final parsing

Be careful of tabs, so here's the code again, instead of [tab] press
the tab key :-)

R$*[tab][tab]$: $>Parse0 $1[tab][tab]initial parsing
R<@>[tab][tab]$#local $: <@>[tab][tab]special case error msgs
R$*[tab][tab]$: $>98 $1[tab][tab]handle local hacks
R$*[tab][tab]$#amavis $:$1
#R$*[tab][tab]$: $>Parse1 $1[tab][tab]final parsing

Add the new mailer definition:
Mamavis,	P=/usr/sbin/amavis, F=nmlsACDFMS5:/|@qhP, S=0, R=0,
		T=DNS/RFC822/X-Unix, U=amavis:amavis,
		A=amavis $f $u

[Step 3, with older amavis: do a ./configure --enable-relay --enable-sendmail,
 make and make install (you may add some more flags to configure)]

Step 3, with amavisd-new: change the settings of $forward_method and
$notify_method in /etc/amavisd.conf:
  $forward_method= 'pipe:flags=q argv=/usr/sbin/sendmail -i -f ${sender} -- ${recipient}';
  $notify_method = 'pipe:flags=q argv=/usr/sbin/sendmail -i -f ${sender} -- ${recipient}';

Step 4: Create /var/spool/mqamavis with the same permissions as
/var/spool/mqueue but owner and group should be amavis

Step 5: Restart sendmail, i.e. killall -HUP sendmail or with SuSE Linux
rcsendmail restart



  Setting it up in easy 7 steps - doing it the m4 way
  (please *read* the example configuration section below, too!)

Step 1: Copy your /etc/sendmail.cf file to /etc/sendmail.orig.cf
Step 2: Copy the provided doc/amavis.m4 file to /usr/share/sendmail/mailer
        (this is the location for a SuSE Linux system ... please have a
         look at your .mc file for the "include" macro. It tells you
         in which path your sendmail m4 stuff is located. Don't forget
         to put amavis.m4 into the mailer/ directory and not the m4/ dir)
Step 3: Copy your .mc file, used for generating sendmail.cf, to amavis.mc
Step 4: Change amavis.mc

a) in front of the OSTYPE definition, add
define(`QUEUE_DIR',`/var/spool/mqamavis')dnl
define(`STATUS_FILE',`/var/log/amavis.st')dnl

b) add the amavis mailer to the MAILER definitions
MAILER(`amavis')dnl

[Step 5, with older amavis: do a ./configure --enable-relay --enable-sendmail,
 make and make install (you may add some more flags to configure) ]

Step 5, with amavisd-new: change the settings of $forward_method and
$notify_method in /etc/amavisd.conf:
  $forward_method= 'pipe:flags=q argv=/usr/sbin/sendmail -i -f ${sender} -- ${recipient}';
  $notify_method = 'pipe:flags=q argv=/usr/sbin/sendmail -i -f ${sender} -- ${recipient}';

Step 6: Create /var/spool/mqamavis with the same permissions as
/var/spool/mqueue but owner and group should be amavis

Step 7: Restart sendmail, i.e. killall -HUP sendmail or with SuSE Linux
rcsendmail restart



Additional information (please read!)
*************************************

NOTE: If you decided to copy your original sendmail.cf to another
filename than sendmail.orig.cf, you have to specificy the filename
with --with-orig-conf=<filename>

NOTE: This configuration could be made simpler if /etc/sendmail.cf remained
untouched, and sendmail could be started simply with
sendmail -bd -C/etc/amavis.cf.  But for security reasons, sendmail refuses
the -C flag if started as root. Therefore, we have to patch sendmail.cf
and rename the original file.

IMPORTANT NOTE: please have closer look at the mailer definition, especially
the F equate (the mailer flags). You may copy the F= stuff out from your
original sendmail.cf file, but be careful! You must not use the f flag.
You may also add the A flag, otherwise "newaliases" will yell "cannot alias
non-local names".

NOTE: This concept should be considered *experimental*.

NOTE: If mail is deferred, it may get stuck in the queue (this may happen
if a delivery attemp fails). Calling
/usr/sbin/sendmail -C /etc/sendmail.orig.cf -q via cron is a good idea.
Another solution is to call
/usr/sbin/sendmail -q5m -C /etc/mail/sendmail.orig.cf
In this example, the mail queue is flushed every 5 minutes.


EXAMPLE CONFIGURATION (sendmail 8.9.3)
--------------------------------------

Here's the configuration I use on my SuSE Linux system with sendmail 8.9.3
(for sendmail 8.11 see below).
AMaViS is run as user amavis, group amavis and therfore /var/spool/mqamavis
is owned by amavis:amavis

/etc/sendmail.cf:


* I use the following mailer defintion
Mamavis,        P=/usr/sbin/amavis, F=nmlsACDFMS5:/|@qhP, S=0, R=0,
                T=DNS/RFC822/X-Unix, U=amavis:amavis,
                A=amavis $f $u


/etc/sendmail.orig.cf:
* to get rid off the X-Authentification-Warning "Processed by amavis
with -C /etc/sendmail.orig" and "Processed from queue /var/spool/mqueue"
I removed authwarnings from PrivacyOptions, so
O PrivacyOptions=novrfy,noexpn

NOTE: The "goaway" option is another PrivacyOption. The "goaway" option
implies the "authwarnings" option, so with "goaway" you'll get the
X-Authentification-Warning.


/var/spool/mqueue and /var/spool/mqamavis is owned by amavis.

NOTE: as amavis is run as user amavis, /var/virusmails must be owned
by amavis and you have to specify a location for the AMaViS logfile
that is writable by user amavis, if writing to a log file directly
(not via syslog).

NOTE: As sendmail will perform most tasks as user amavis now, it may
not be able to read the users .forward file anymore! You may consider
changing the permissions for the home directories, i.e. access rights
for others.


EXAMPLE CONFIGURATION (sendmail 8.11)
--------------------------------------

Here's the configuration I use on my SuSE Linux system with sendmail 8.11.
AMaViS is run as user amavis, group amavis.

/etc/mail/sendmail.cf:


* I use the following mailer defintion
Mamavis,        P=/usr/sbin/amavis, F=nmlsACDFMS5:/|@qhP, S=0, R=0,
                T=DNS/RFC822/X-Unix, U=amavis:amavis,
                A=amavis $f $u


Note: The following entry does *NOT* work
Mamavis,        P=/usr/sbin/amavis, F=sDFMAw5:/|@qPfhn9, S=0, R=0,
                T=DNS/RFC822/X-Unix,
                A=amavis $f $u

Hint: F=C (specifies that @domain has to be added to recipient) is needed
otherwise you'll get an "user unknown" error.


/etc/sendmail.orig.cf:
* to get rid off the X-Authentification-Warning "Processed by amavis
with -C /etc/sendmail.orig" and "Processed from queue /var/spool/mqueue"
I removed authwarnings from PrivacyOptions, so
O PrivacyOptions=novrfy,noexpn

NOTE: The "goaway" option is another PrivacyOption. The "goaway" option
implies the "authwarnings" option, so with "goaway" you'll get the
X-Authentification-Warning.



The Mlocal entry looks like this
Mlocal,    P=/usr/bin/procmail, F=lsDFMAw5:/|@qPfhn9,
           S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
           T=DNS/RFC822/X-Unix,
           A=procmail -Y -a $h -d $u

(it seems that in the F= flags neiter the "o" nor "S"
must be set ...)

The permission of /var/spool/mqueue and /var/spool/mqamavis are
the following:

drwxrwxr-x   2 amavis   root	     1024 Sep  2 16:41 mqamavis
drwxrwxr-x   2 amavis   root         1024 Sep  2 16:41 mqueue


As I use procmail als Local Delivery Agent, the setuid-bit
for procmail has to be set! (d'oh ...)

Note: For some reasons I'm not aware of, the notification messages generated
by amavis are not sent immediately. Two solutions do exist for that
(the latter one is the one I would recommend)

* calling sendmail -C /etc/mail/sendmail.orig.cf -q via a cron job

* or (prefered)
change the delivery mode in /etc/mail/sendmail.orig.cf to
# default delivery mode
O DeliveryMode=i
# i       Deliver interactively (synchronously)


NOTE: as amavis is run as amavis /var/virusmails must be owned
by amavis and you have to specify a another location for the AMaViS
logfile (normally /var/amavis/amavis.log) to which amavis has
write access to.

NOTE: As sendmail will perform most tasks as user amavis now, it may
not be able to read the users .forward file anymore! You may consider
changing the permissions for the home directories, i.e. access rights
for others.


TODO/BUGS
---------
* huh? nothing?! that's unbelieveable :-)


The author
----------
This stuff was written and tested by Rainer Link
Rainer Link <link@suse.de>, http://rainer.w3.to/


Credits
-------
This stuff is based on a patch from gody@master.slon.net and is itself
based on the concept from Inflex. Thanks to Paul L. Daniels and
(indirectly) to Steve Kehelet via the P.L.Daniels's Inflex scanner.
Thanks to Yan Seiner for the m4 stuff, which our amavis.m4 is based upon.
Section 'Scanning only incoming mail' updated by Mark Martinec.


Thanks
------
Thanks to everyone who reported bugs or problems directly
to me or the AMaViS user mailing list, and provided us/me
with patches or additional information.
