
                       AMaViS - A Mail Virus Scanner 
                               Version 0.3.12

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.

  The currently supported MTAs are courier, exim, qmail, 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 recognise 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

  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 amavis 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 0.31 or newer
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
============

  See INSTALL.

Configuration
=============

  Most configuration options should have been taken care of by configure,
but it is of course also possible to make manual changes to the generated
amavis script. If you switch to a different MTA, you must re-run configure
because amavis contains only code for the MTA it was configured for.

  If you change virus scanners, you must re-run configure because amavis
contains only code for the AV scanners it was configured for. Exception:
amavis was configured with --enable-all.

  All customisable variables in amavis are enclosed between two comments,
"Customisable variable from here on", and "End of customisation section",
resp. These variables should be sufficiently commented to explain their
meaning.

  Amavis has couple of built-in defences against Denial of Service (DoS)
attacks. Currently, amavis takes no special action if these defences are
triggered, it simply requeues the offending messages (putting them on hold
and notifying the admin might be better). There are four variables which
can be customised for fine-tuning:

  - $MAXLEVELS [Default: 20]

    This variable sets the maximum overall recursion level for extraction
    and decoding. If it is set to zero, no extraction and decoding takes
    place at all, so careful.

  - $MAX_ARCHIVE_NESTING [Default: 3]

    This variable sets the maximum nesting level for archive formats with
    compression (e.g. zip within zip within zip; arj within tar; etc.).
    The feature can be disabled by setting the value to zero.

  - $MAXFILES [Default: 500]

    This variable sets the maximum number of extracted files. If set to
    zero, the feature is disabled.

  - $threshold [Default: 14]

    This is an empirical value to check the number of extracted parts/files
    against the number of extracted parts/files at the previous iteration
    level. If the threshold value is exceeded twice (meaning that the number
    of extracted files increased at least 14x14=196 times within two iteration
    steps), the message is deferred. If set to zero, this feature is
    disabled, but we strongly recommend not to touch it at all.

Testing
=======

  A very basic and rudimentary set of tests is executed on "make check".
The test suite does not work with qmail. See tests/README for details.

