$Id: README,v 1.7.2.2.2.2 2002/05/17 06:08:54 bengen Exp $

AMaViS -- "Next Generation"
===========================


What is this, anyway?
---------------------

AMaViS-ng is a rewrite of amavisd/amavis-perl which was started by
Hilko Bengen after he had gotten fed up with trying to hack the
amavis-perl codebase into a Exim (+embedded Perl) system filter setup,
which neither amavisd nor amavis-perl had been designed for in the
first place.

Due to a modular design, it is possible to allow for (at least) three
different kinds of setup:

(1) The "old-fashioned" setup in which amavis is called directly by
the MTA, receives the message via STDIN, and resends it after the
virus-scanner hasn't found anything.

(2) A setup where amavis works as a long-running forking daemon
(mostly like amavisd) and where it gets its instructions via sockets. 
This has so far been implemented as an SMTP daemon.

(3) The Exim message filter setup as mentioned above where the amavis
code actually runs inside the MTA.


Required programs and packages
------------------------------

The following Perl modules are absolutely needed:

* File::MMagic (tested with 1.13, 1.15)

    Version 1.13 and prior detect some text/plain files which have
    mail headers _somewhere_ in them as message/rfc822. There is a
    workaround for this in AMAVIS.pm, but this may be removed in the
    future.

* Config::Inifiles (tested with 2.14)
* MIME::Tools (>= 5.411)

    A patch is included for MIME-Tools that fixes a problem with
    recent broken MIME messages sent by the Klez worm.

The following Perl modules and external programs can be used for
unpacking parts of the messages:

* Convert::TNEF (tested with 0.06)
* Convert::UUlib (not yet implemented)
* Compress::Zlib (tested with 1.14)
* Archive::Tar
* Archive::Zip

* unrar
* zoo
* arc
* lha
* unarj (only the patched 2.63 version from http://amavis.org/contrib
         is supported, due to security concerns.)

For virus-scanning, support for the following products has been
implemented so far:

* F-Secure Antivirus
* Kaspersky Antivirus
* H+BEDV AntiVir
* Sophos Sweep
* Sophie
* File::Scan (a free Perl module)
* Bitdefender
* F-Prot
* H+B EDV Antivir
* MKS
* NAI uvscan
* Norman Virus Control
* Panda Antivirus
* CLAM Antivirus (GPL'd)
* Trend vscan

In contrast to amavis-perl, amavisd, the existence of these modules
and external programs is not checked during installation.


Installation
------------

After unpacking and reading these instructions, do a

$ perl Makefile.PL

which will create a Makefile for you. Then do a

$ make

$ su -c make\ install

This will install the Perl modules, and extra scripts. You will have
to copy the configuration file and the documentation (if needed) by
hand.

If you want to log to AMaViS' messages to a log file, create this file
beforehand with proper permissions so that AMaViS will be able to
write to it.


Build / installation on Debian systems
--------------------------------------

On the build system, install 
    dpkg-dev, fakeroot, perl, debhelper.

In the amavis-ng-${version} directory, do a 

$ dpkg-buildpackage -rfakeroot -uc -us

You will then get a amavis-ng_${version}-${debianversion}_all.deb.

On the system where AMaViS will be installed, instell
    perl, logrotate, libfile-mmagic-perl, libconfig-inifiles-perl,
    libmime-perl, libconvert-tnef-perl, libconvert-uulib-perl,
    libcompress-zlib-perl, libarchive-tar-perl, libarchive-zip-perl.

The packages
    unarj, unrar, zoo, arc, lha, libfile-scan-perl

will also be useful.

Then install the freshly built AMaViS package.

The author can provide those packages mentioned above which are not in
the Debian distribution.

Configuration
-------------

All configuration is done via a Windows INI style file
/etc/amavis/amavis.conf.

In the [global] section, at least the mail-transfer-agent keyword has
to be set. Moreover, different extraction methods, virus scanners, and
notifying modules can be selected.

Special attention should be paid to the "Mail" extractor. It is
responsible for extracting MIME messages and should be always
configured, otherwise AMaViS doesn't make much sense.

The "mail-transfer-agent", "virus-scanner", "extractors", "notifier"
configuration options result in the corresponding Perl modules being
included at runtime. For every kind of module, a module called
"Example.pm" is provided, thus (hopefully) making it easier to write
custom extensions to AMaViS.

,----
| [paths]
| 
| unpack = /tmp/
| 
| [logging]
| 
| syslog faculty = mail|info
| syslog loglevel = 7
| ; file = /var/log/amavis.log,1
| ; file = /var/log/amavis.debug,10
| logfile = /tmp/amavis.log
| logfile loglevel = 6
`----

These keywords should speak for themselves. Loglevels can be set from
0 (log nothing) to 7 (log debugging messages). This part of the setup
is bound to change in the near future.

,----
| [Notify]
| 
| local domain = .*mydomain\.com
| 
| mail from = postmaster@mydomain.com
| admin = postmaster@mydomain.com
`----

The local domain statement is used by the "Recipients" notifier. If a
virus is found, only those recipients of the message are notified
whose address match the given regular expression.

The paths to external programs should be specified in the [external]
section.

Every MTA module and almoset every virus scanner module hs its own
options. See the MTA-specific README files and the provided example
configuration file for details.


Testing
-------

For testing puropses, there is a pseudo MTA module called DebugMTA. It
can be dropped in for the usual MTA in order to test the other
configuration. See README.debugging for details.


Hacking
-------

For those who want to modify or extend the existing code (i.e. add
extractor or antivirus modules), some hints on what happens behind the
scenes are provided in README.hacking.


Where To Report Problems
------------------------

There is a mailing list amavis-user which is there for discussion
about setting up AMaViS. To subscribe to this list, visit
http://lists.sourceforge.net/lists/listinfo/amavis-user


Thanks
------

Work on AMaViS-ng was (and is being) funded by 

    toplink-plannet GmbH, Karlsruhe, Germany.
    http://www.toplink-plannet.de


Author
------
Hilko Bengen <bengen@users.sourceforge.net>
