
                       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
   Although the requirement that the file command understand the -b option
   (brief mode) has been dropped, we still recommend e.g. the one from
   ftp://ftp.astron.com/pub/file/ because of the number of known formats.
   Some of the Linux and *BSD distributions may include a more or less
   recent version of it. Some other Unices, notably Solaris, come with a
   version of the file command that is not usable by amavis because
   /etc/magic is missing lots of entries compared to the Zoulas version
   (from astron).
 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
Convert-TNEF 0.06 or better (!!)
Compress-Zlib 1.14 or better
Archive-Tar
Archive-Zip
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
=======

  The standard "make check" procedure does not work with amavisd. The main
reason is that if mail messages are processed normally, regardless whether
they contain viruses or not, the client will always return zero (success).
It will return non-zero if processing aborts abnormally. The tests/README
document contains some hints how to test amavisd without installing it.

