amavisd-new consists of a daemon 'amavisd', and (in some setups) a helper
program, which is only needed with certain mail transport agents (MTA).
For Postfix, Exim-V4, and dual-sendmail setups no helper program is needed
for interfacing MTA with amavisd daemon .

Obtaining the software:
=======================

Fetch the tarball and unpack it:
  curl -O http://www.ijs.si/software/amavisd/amavisd-new-<version>.tar.gz
  gzip -d -c amavisd-new-<version>.tar.gz | tar xvf -
  cd amavisd-new-<version>

The most important files thus obtained are amavisd and amavisd.conf.

Start reading with AAAREADME.first, then RELEASE_NOTES if upgrading,
and INSTALL and README_FILES/<your-MTA> for new installations.

Check also the on-line documentation at:
    http://www.ijs.si/software/amavisd/
and http://www.ijs.si/software/amavisd/amavisd-new-docs.html


Prerequisites:
==============

file(1) utility is required, the most recent version is heartly recommended
(current version is 4.24 at the time of a release). There are a number of
security and robustness problems with older versions.

Archive::Zip   (Archive-Zip-x.xx) (1.14 or later, currently 1.30)
Compress::Zlib (Compress-Zlib-x.xx) (1.35 or later, currently 2.060)
Compress::Raw::Zlib (Compress-Raw-Zlib) (2.017 or later)
MIME::Base64   (MIME-Base64-x.xx)
MIME::Parser   (MIME-Tools-x.xxxx) (currently 5.504)
Mail::Internet (MailTools-1.58 or later have workarounds for Perl 5.8.0 bugs)
Net::Server    (Net-Server-x.xx) (version 2.0 adds support for IPv6)
Digest::MD5    (Digest-MD5-x.xx) (2.22 or later)
Time::HiRes    (Time-HiRes-x.xx) (1.49 or later)
Unix::Syslog   (Unix-Syslog-x.xxx)
Mail::DKIM     (Mail-DKIM-0.31 or later, currently 0.40)

The following external programs are used for decoding/dearchiving
if they are available:
  compress, gzip, bzip2, nomarch (or arc), lha, arj (or unarj), rar (or unrar),
  unzoo (or zoo), pax, cpio, lzop, freeze (or unfreeze or melt), ripole,
  tnef, cabextract.
Self-extracting archives (executables) can be of types zip, rar, lha or arj,
and are only recognized when the corresponding dearchiver is available.

optional Perl modules:
  Mail::SpamAssassin          for doing spam scanning (latest version)
  DBI with appropriate DBD::* if using SQL lookups or SQL logging/quarantining
  Net::LDAP                   if using LDAP lookups
  ZeroMQ or ZMQ::LibZMQ[2,3]  Perl module interface to libzmq

optional, but usually desired:
  virus scanners        external programs for doing virus scanning, like ClamAV

Some external programs may already be provided with the system, but it is
worth checking that their version is recent. The following lists the programs
and their distribution sites (not necessarily the only or the official).
The most crucial programs are marked with an asterisk:

* file:       ftp://ftp.astron.com/pub/file/
  compress:   ftp://ftp.warwick.ac.uk/pub/compression/
* gzip:       http://www.gzip.org/
  bzip2:      http://www.bzip.org/
  nomarch:    http://rus.members.beeb.net/nomarch.html
  arc:        ftp://ftp.kiarchive.ru/pub/unix/arcers/
  lha:        http://www2m.biglobe.ne.jp/~dolphin/lha/lha.htm
  7z:         http://p7zip.sourceforge.net/, http://www.7-zip.org/
  unarj:      ftp://ftp.kiarchive.ru/pub/unix/arcers/
  arj:        http://testcase.newmail.ru/files/ (arj is preferable to unarj)
  rar, unrar: http://www.rarsoft.com/, http://www.rarsoft.com/rar_add.htm,
              ftp://ftp.kiarchive.ru/pub/unix/arcers/ (rar preferred to unrar)
  unzoo:      http://critical.ch/distfiles/
  zoo:        ftp://ftp.kiarchive.ru/pub/unix/arcers/ (zoo preferred to unzoo)
  lzop:       http://www.lzop.org/download/
  freeze:     ftp://ftp.warwick.ac.uk/pub/compression/
  ripOLE:     http://www.pldaniels.com/ripole/
  tnef:       http://tnef.sourceforge.net/
* pax:        http://www.gnu.org/software/paxutils/
                or: http://heirloom.sourceforge.net/
  cpio:       http://www.gnu.org/software/cpio/
                or: http://heirloom.sourceforge.net/
  cabextract: http://www.kyz.uklinux.net/cabextract.php
* ClamAV:     http://clamav.elektrapro.com/  (open source virus scanner)
  dspam:      http://www.nuclearelephant.com/projects/dspam/

  bdb:        http://www.sleepycat.com/ (Berkeley db libr. used via BerkeleyDB)
  p0f:        http://lcamtuf.coredump.cx/p0f.shtml

Optional third-party utilities:
  MailZu:     http://www.mailzu.net/  (quarantine management web UI)
  amavisd-milter: http://sourceforge.net/projects/amavisd-milter/
              (alternative sendmail milter helper program supporting the
               new AM.PDP protocol)

  See also:   http://www.ijs.si/software/amavisd/#contrib


Installing the daemon:
======================

- Perl version 5.8.2 or later is recommended. While 5.6.1 may theoretically
  still be the lowest usable version, a bunch of problems were resolved in
  later Perl versions which were reported to show in certain environments.
  Some examples: taint bugs, socket descriptors not closed on exec,
  Net::Server looping waiting for a socket connect, problems with handling
  of UTF8/Unicode in Perl;

- create (or choose) a Unix group dedicated to run amavisd daemon and
  possibly virus scanners. This should NOT be one of user or system groups
  and should NOT be shared with other applications such as mail or www
  (except possibly virus scanners). It is customary to name the group
  'amavis' (or perhaps 'vscan' or 'sweep');
    (edit /etc/group, or use system-specific tools, such as vigr)

- create (or choose) a Unix account (username and its UID) dedicated to run
  amavisd daemon and possibly virus scanners. This should NOT be one of user
  or system accounts and should NOT be shared with other applications such
  as mail or www (except possibly virus scanners). Most certainly do NOT use
  "root", and do NOT use "nobody" nor an account used by mailer, such as
  "postfix", "mail", "smmsp" or "mailnull"). It is customary to name the
  user "amavis" or "vscan";

  Choose a home directory (e.g. /var/amavis or /var/lib/amavis) for this user.

    (use vipw, or system-specific tools to add a user)

  Create its home directory, unless account creation procedure already did it:
    mkdir /var/amavis

  Create the following subdirectories:
    mkdir /var/amavis/tmp /var/amavis/var /var/amavis/db /var/amavis/home

  Check or set the ownership and protection of the directories to be readable
  and writable by the chosen UID, and not writable by other non-privileged
  users;
    chown -R amavis:amavis /var/amavis
    chmod -R 750 /var/amavis

- unpack the amavisd-new source distribution (see 'Obtaining the software'
  above) wherever desired (/usr/local/src or elsewhere), and cd to that
  directory;

- copy file amavisd to wherever you want it to reside,
  such as /usr/local/sbin, and make sure its protection setting allows it
  to be executed and read, but not overwritten by non-privileged users.
  This is a Perl source, so it is readable by any text viewer if needed.
    cp amavisd /usr/local/sbin/
    chown root /usr/local/sbin/amavisd
    chmod 755  /usr/local/sbin/amavisd

- copy file amavisd.conf to wherever you want it to reside such as /etc, and
  make sure it is not writable by non-privileged users, not even by amavis;
    cp amavisd.conf /etc/
    chown root:amavis /etc/amavisd.conf
    chmod 640 /etc/amavisd.conf

  (if the file contains sensitive information like a password for accessing
  a SQL database, it should not be world-readable)

  Some sites prefer location /etc/amavis/ or /usr/local/etc/. If using
  a non-default location, one may use a command line option -c when
  starting the daemon to specify a non-default configuration file,
  or provide a soft link at the default location. Multiple -c options
  are permitted and enable splitting the config file into sections such
  as site-specific and general sections;

- create a directory (e.g. /var/virusmails) to be used by amavisd-new
  as a quarantine area (if quarantining to files is desired).
  Set ownership and protection of the directory to be readable and
  writable by the chosen UID, and not writable by other non-privileged
  users;
    mkdir /var/virusmails
    chown amavis:amavis /var/virusmails
    chmod 750 /var/virusmails

- edit file /etc/amavisd.conf and adjust variables $daemon_group
  and $daemon_user to match the chosen group and user name,
  adjust variables $MYHOME, $TEMPBASE, $db_home and $QUARANTINEDIR
  to match the directories just created, then check/adjust other variables,
  for example:

    $MYHOME   = '/var/amavis';
    $TEMPBASE = "$MYHOME/tmp";
    $db_home  = "$MYHOME/db";

  Optionally, if $MYHOME is preferred uncluttered and for extra security
  owned by root (not modifyable by user amavis):
    $MYHOME = '/var/amavis';
    $helpers_home = "$MYHOME/home";
    $pid_file  = "$helpers_home/amavisd.pid";
    $lock_file = "$helpers_home/amavisd.lock";
  in which case the ownership of /var/amavisd should be changed to root
  and ownership of /var/amavis/home must be amavis:
    chown root /var/amavis
    chown -R amavis:amavis /var/amavis/home
    chmod 750 /var/amavis /var/amavis/home

  If $TEMPBASE resides on a dedicated file system, it may be prudent to
  specify mount options: noexec,nosuid,nodev.

- install virus scanners (if they are to be used), and Perl module
  Mail::SpamAssassin (if desired), and adjust variables in /etc/amavisd.conf.
  There are several other Perl modules needed by amavisd daemon
  (see 'Prerequisites') - if they are not yet installed, a list
  of missing modules will be logged when amavisd is started;

- some virus scanners run as daemons or change UID when checking files.
  It is easiest to run such virus scanners under the same UID/GID (or at least
  within the same group) as amavisd, to avoid file permission problems
  when virus scanner reads files prepared for checking by amavisd daemon.
  Some virus scanners may require write permission to the $TEMPBASE directory
  to be able to create auxiliary files there.

  If a different UID is preferred for an AV scanner, a solution for ClamAV
  is to add user clamav to the amavis group (e.g.:  vscan:*:110:clamav
  in a file /etc/group), and then add:  AllowSupplementaryGroups yes
  to clamd.conf.

- start the program 'amavisd', either as root (possibly with option
  -u user), or with su(1) as the user chosen above. It should
  start up, and (if root) change its GID/UID to the setting provided.
  It is wise to start it up for the first time with a 'debug' option:
    /usr/local/sbin/amavisd -u vscan debug
  or:
    /usr/local/sbin/amavisd debug
  When checking SpamAssassin operations, the following can be useful:
    /usr/local/sbin/amavisd debug-sa

- later when everything has been tested and works, a shell script
  amavisd_init.sh or similar may be made to run at system startup/shutdown
  time;

- depending on the mailer used, read the appropriate README.* file
  and follow instructions there. With some mailers (Postfix, Exim V4
  or a dual-MTA setup with any SMTP-capable mailers, including sendmail)
  no helper program is needed.

  With some other mailers (sendmail milter, or historical sendmail invoking
  content filter via local delivery agent) one of the supplied helper
  programs is needed: amavisd-milter.c, or amavis.c respectively. These are
  available from the helper-progs subdirectory. The helper-progs/config.h.in
  may need to be adjusted to match the system and amavisd configuration
  settings. See also alternative sendmail milter supporting the new AM.PDP
  protocol at http://sourceforge.net/projects/amavisd-milter/ .


NOTE:
  Check amavisd-new web page at http://www.ijs.si/software/amavisd/
  if there are any patches needed for external components, such as
  Net::Server module or Razor agents.



Testing the daemon:
===================

Initial checkout is described in MTA-specific README.* file,
please follow instructions there.

The subdirectory test-messages contains a couple of sample mail messages,
and brief instructions for testing are in file README there.
