For Postfix and Exim you don't need amavis client,
just ignore its setup - see README.postfix and README.exim.

For sendmail the supported configuration is via its libmilter
interface, which is implemented by amavis-milter.c, it interfaces
sendmail to amavisd. A dual MTA configuration (see below) is also
possible, but not described.

For other mailers the recommended setup would be a two-mail
configuration: MTA1 -> (SMTP) -> amavisd -> (SMTP) -> MTA2.
Depending on the MTA configurability, MTA1 and MTA2 can be
the same server.
- set up MX DNS record to point to MTA1, so that MTA1 will receive
  all incoming mail; also set your mail PC clients to send mail to MTA1;
- set MTA1 to forward all its outgoing mail via SMTP to amavisd
  (e.g. via its smart-host or relayhost or default transport configuration);
- set up amavisd to return checked mail via SMTP to MTA2
- set up MTA2 to only accept mail from amavisd and do a normal delivery.

For qmail try the new amavis-qmail-client.c by Lars Hecking,
or try to figure out how to do something like suggested above.

Testing:

No special provisions. Just set up your configuration and try it out.
For a first time use it is recommended to run amavisd interactively.
Set $DEBUG="yes" in amavisd (or in amavisd.conf), 'su' to the desired user,
and run amavisd, which will write all its logging to the terminal.

To test virus scanners use the standardized EICAR test pattern
which all virus scanners should recognize and report, although it
is not a true virus. To prevent this package transfer being blocked
by some too-eager firewall, we obfuscate it: just join the following
four lines into one long line, remove all spaces, add training newline,
and name it EICAR.COM:

  X5O!P%@A P[4\PZX54
  (P^)7CC) 7}$EICAR-
  STANDARD -ANTIVIRU
  S-TEST-F ILE!$H+H*


The rest of this file is somewhat out of date.

  Mark Martinec

----------------------------------------------------------------------

                       AMaViS - A Mail Virus Scanner 
                               Daemon version

Contents

  What is it?
  Software Requirements
  Perl Modules
  Installation
  Testing

What is it?
===========

  AMaViS is a script that interfaces a mail transport agent (MTA) with
one or more virus scanners.

  The original version of the software up to and including 0.2.x was
written as bash/Bourne shell script. It was then rewritten in perl and
released as development version, amavis-perl. This branch of the software
is now replacing the shell script version and will become amavis 0.3.x.

  After the release of amavis-perl-10, another development branch was
set up that transformed amavis into a client-server package. The amavis
scanning script now runs as a daemon, and it communicates with the MTA
through sockets and a small, compact client program.

  The currently supported MTAs are exim, postfix, and sendmail.
Please refer to the corresponding README.${mta} file in this directory.

Software Requirements
=====================

  The idea is to use perl modules where ever possible so that the script can
be as self-contained and independent as possible.  This should hopefully
make it much more portable and reduce the number of hacks required to deal
with subtle differences between commands on different UNIX systems.

  But some perl modules are not ready for prime time yet, so we still
require a number of external commands.

  The configure script will stop with an error message if the following
external commands/programs are not found. See doc/amavis.txt, or the
amavis web site at http://www.amavis.org/ for information on where to
get these.

 o perl (obviously)
 o virus scanner software (obviously)
 o file
   A file command that recognises TNEF is now required! Some Unices, in
   particular Solaris, ship with a very limited file command, which does
   not rewcognise TNEF files. We recommend to install the latest release
   from ftp://ftp.astron.com/pub/file/. The Linux and *BSD distributions
   usually come with a sufficiently recent file command.
 o arc
 o bunzip2 (part of the bzip2 package)
 o lha (version 1.14g or later!)
 o unarj
 o uncompress (standard on Unix and Unix-like systems)
 o unrar
 o zoo

  procmail is only required if amavis is configured for use as local mailer
(/etc/postfix/main.cf:$mailbox_command) with postfix. See README.postfix
for details. [This configuration is not supported anymore.]

  If you install these commands from source, some of them may not compile
on all systems without modification. We have collected some patches in
http://www.amavis.org/contrib/ to address this.

Perl Modules
============

  In order to run this script you need the following perl modules installed.
They are all available from CPAN (http://www.cpan.org/). Some of these
modules require patching to work properly with amavis. Please check out
http://www.amavis.org/contrib/ for details.

IO-stringy
Unix-Syslog
MailTools
MIME-Base64
MIME-tools version 5.313 or better (!!)
Convert-UUlib version 0.111 or 0.201 (0.2 is broken!)
Convert-TNEF 0.06 or better (!!)
Compress-Zlib 1.14 or better
Archive-Tar
Archive-Zip 1.0 or better
libnet

  If you have the CPAN module installed, the most convenient way to install
these modules is to launch the CPAN shell with

  perl -MCPAN -e shell

and tell it to:

  install Unix::Syslog
  install Convert::UUlib
  install Convert::TNEF
  install Compress::Zlib
  install Archive::Tar
  install Archive::Zip
  install G/GB/GBARR/MailTools-1.15.tar.gz
  install MIME::Tools
  install libnet

  The CPAN shell will automatically install modules which are required
by those you requested (e.g. MIME-Base64, required by MIME-tools), and
it also takes care of updating older modules.

  The libnet module is only required for the postfix content filter interface
(--enable-smtp configure option). Configure checks for it separately,
although MailTools suggests to install libnet first.

  The Archive::Tar module must be patched to disable handling of compressed
archives. This was broken in earlier versions of the module, and there are
also performance considerations. Compressed/gzip'ed files are handled by 
amavis directly. The Archive::Tar patch previously found here is now at
http://www.amavis.org/contrib/.

Installation
============

./configure [options]
make

make check does not and cannot work properly with amavisd. See tests/README
for some guidelines.

[make check

  The final step checks whether the generated amavis script was configured
properly, and whether it can actually detect viruses. One of the tests
executed by make check uses the EICAR.COM virus scanner test pattern.
]

For a complete list of configure options, type

./configure --help

A detailed explanation of these options is in INSTALL.

  After making the software, either install it by running "make install"
(make sure to back up the presently version of amavis, if any), or perform
the following steps manually:

 - mkdir /var/amavis (or the directory specified via --with-runtime-dir)
   chmod 700 /var/amavis
   chown $amavisuser /var/amavis, where $amavisuser is either qmailq, vscan,
   or whatever spefified via --with-amavisuser;
   in case of qmail, the directory must also be chgrp qmail
 - if you used --with-logdir to specify a logging directory separate from
   the default, create it just like /var/amavis
 - the same instructions apply to the virus quarantine directory
 - copy amavisd, amavis (or amavis-milter) to /usr/sbin
 - copy amavisd.conf to /etc (or, alternatively, to the directory specified
   with --sysconfdir at configure time)
 - make sure that "virusalert" (or whatever address is configured as $mailto
   in /etc/amavisd.conf) exists in your aliases file or is a valid email
   account

  Both amavisd and the client program (amavis) must run as the same user
who owns /var/amavis. The default for this user id is MTA-dependent, but
it can be configured using the --with-amavisuser configure option.

  amavisd should be started before the mail system. This is important for
system startup scripts.

 su - $amavisuser /usr/sbin/amavisd >/dev/null 2>&1   # detaches itself from
                                                      # the controling terminal
 /etc/init.d/$MTA start

Testing
=======

No special provisions. Just set up your configuration and try it out.
For a first time use it is recommended to run amavisd interactively.
Set $DEBUG="yes" in amavisd (or in amavisd.conf), 'su' to the desired user,
and run amavisd, which will write all its logging to the terminal.
