Welcome to the installation instructions for exiscan !


REQUIREMENTS
------------

First of all, exiscan requires some additional perl modules to run:

    You can get these on CPAN (www.cpan.org)

    - IO::Handle
      (IMPORTANT: the latest version ! I have it available here:
       http://duncanthrax.net/exiscan/IO-1.20.tar.gz )
      Recent Perl versions have it preinstalled, if you run a new
      distro you probably won't need it.
    - Mail::Internet
      (may require additional modules)
    - File::Copy  (usually pre-installed)
    - Unix::Syslog  (filename Syslog-X.XX.tar.gz)
      (NOTE - there is another package called Sys::Syslog,
       but you need Unix::Syslog. You can also have both
       installed)


Secondly, exiscan needs some external programs:

    - the exim MTA (you have it, I guess)
    
    - a virus scanner. McAfees uvscan, Sophos, RAV, NOD32
      and AVP Daemon are supported out-of-the box, but others
      can be easily implemented.
      Take a look at the configuration file.

    - the "ripmime" binary from http://www.pldaniels.com/ripmime/
      A very nice MIME unpacker. I recommend it. 

      Alternatively,  you can use the "reformime" binary from the
      "maildrop" package.

    - the "tnef" binary from http://world.std.com/~damned/software.html
      (OPTIONAL, BUT RECOMMENDED)
      This nifty program is able to unpack the evil Microsoft
      MS-TNEF wrapper format. Microsoft MUAs and MTAs use this
      to encapsulate already MIME-encoded messages.


Debian Users can fulfill some of the above requirements by installing
these precompiled packages:

	maildrop
	tnef
	libunix-syslog-perl
	libmailtools-perl



INSTALLATION STEPS
------------------

Step 1
------
Get and install all the stuff above if you don't already have it.


Step 2
------
Untar the exiscan-v2.XX.tar.gz package to a directory of your choice.


Step 3
------
Edit exiscanv2.cf (the configuration file).
Each option is documented. READ THESE TEXTS CAREFULLY to save yourself
the hassle of sorting out a mail mess later ...

HINT: Do not forget to change the $postmaster and $fromaddress settings.
      Thank you.


Step 4
------
Edit your exim configuration file and put the following line on top
of it:

  queue_only = true

This will make exim queue incoming messages only. It will now wait for
an explicit dequeue command to send out messages.


Step 5
------
Find the exim startup script. this could be

  /etc/rc.d/init.d/exim

if you replaced sendmail completely, or

  /etc/rc.d/init.d/sendmail

if you use the old sendmail startup file with a symlink from 
/usr/sbin/sendmail to exim

find the line where the daemon is started and remove the -qXX
parameter. This will disable automatic dequeuing.

Don't worry, exiscan will handle dequeueing for you now.
Restart the exim daemon.


Step 6
------
Run exiscan.

Syntax: /path/to/exiscanv2.pl <path_and_name_of_exiscanv2.cf>

(like "./exiscanv2.pl exiscanv2.cf")

I let it run as root. It does not open any ports
and i do not think that it is exploitable in any other way.

If you want to run it as a normal user, make sure it can write to
the exim queue and its own directory tree.



Step 7
------
Watch the exim and/or syslog logfiles while sending some mails. 

Test by sending a virus through your system.

Also remember to include exiscan in your system's startup procedure, so
it will be invoked at boot time.

Read README.LOCALUSERS to see if the problem described there applies to your
system.

Done ! :)

*** IMPORTANT: to make exiscan terminate cleanly, you must send it a HUP signal.
***            (Try "killall -HUP exiscan.pl"). Quitting with other signals
***            will not cause mail to be lost, but temporary files may not
***            be cleaned up correctly.


CONTACT ADDRESS
---------------
TROUBLE ? Contact me by mail: <tom@duncanthrax.net>
