
                      AntiVir for UNIX - Version 2.1.11

                       Copyright (c) 2007 Avira GmbH

                            http://www.avira.com



============
 Disclaimer
============

AntiVir for UNIX utilizes Dazuko (http://www.dazuko.org), a
free software project that provides a simple interface for
3rd-party file access control. Dazuko is used as the basis
for AvGuard, the on-access scanner available with the
AntiVir for UNIX package. Avira GmbH will take no
responsibility for ANY problems related to Dazuko itself.
By building and/or installing Dazuko in order to utilize
AvGuard's on-access features, you are choosing to do so
at your own risk.



===========================
 What is AntiVir for UNIX?
===========================

AntiVir for UNIX is an anti-virus package for your UNIX
system. It is also able to identify unwanted software
on your system. It is comprised of a resident (on-access)
scanner, an automatic internet updater, and a command line
scanner. The resident scanner is referred to as AntiVir Guard
(or AvGuard for short).

AvGuard is based on Dazuko, a free software project.
Dazuko consists of a device driver that captures file access
operations and passes this information to one of the
running AvGuard daemons. The daemon scans the file and if no
viruses are found and if the file is not an unwanted file,
allows the operation to proceed.

You can configure AvGuard to scan files as they are opened,
closed, and/or executed. Concerning files can be cleaned,
renamed or moved to another directory for further analysis.
All scanning activity is logged through syslog, sent as a
notification through email, logged into a specified file,
or a combination thereof. If a virus or unwanted file is
found and cannot be removed, access to the file is blocked.


The automatic internet updater runs as a daemon and has
the responsibility of making sure your AntiVir software is
up-to-date (internet access is required). The automatic
internet updater can be configured to check for updates at
specific times and intervals. It can also be configured to
send email or simply log update activity. Updates include
both data files and the AntiVir programs themselves.

Although the automatic internet updater is provided with
AntiVir for UNIX, it is also possible to start updates
manually using a command line instruction. This is
done with the --update argument. Checking for updates
manually is EXACTLY the same as using the automatic
internet updater. This means that users may choose to
use the command line version in a cronjob as opposed to
using the automatic internet updater. Cron is a much
more flexible and configurable scheduling daemon than
the automatic internet updater.

The features of AntiVir for UNIX include:
  + scan files on OPEN/CLOSE/EXECUTE (requires Dazuko)
  + configurable path protection (requires Dazuko)
  + block access to concerning files (requires Dazuko)
  + log/email alert notification
  + repair/move/rename concerning files
  + automatic internet updates (requires internet access)
  + command line scanner

Extra Server-specific features include:
  + scanning within compressed files (requires Dazuko)

NOTE: Without a valid key, AntiVir for UNIX will run in DEMO
      mode. This means that it will only report concerning files
      through syslog and will not block access or handle the
      concerning files in any way. Compressed files will not be
      scanned and updates will not be available.



==========================
 AntiVir Personal Edition
==========================

An estimated 57 percent of virus infections within companies can
be traced back to an unprotected data transfer between private
and business environments. The resulting data losses and computer
system failures take a high annual toll on firms and authorities.

The number of virus infections on systems used for business
purposes can be reduced by catching them in time on private
computers.

For this reason, we offer AntiVir for UNIX Workstation
free of charge for private (individual, non-commercial) use.

NOTE: Only the Workstation edition is available free of
      charge for non-commercial use.



==============
 Installation
==============

If you have any key files, you can put them in the same
directory as the AntiVir for UNIX install files and they
will be copied into /usr/lib/AntiVir automatically. Make
sure that the permissions of the key files are correct.

Login as root, change to the directory containing the
AntiVir for UNIX install files and run the install script.

./install

The script will do the following
- copy files to /usr/lib/AntiVir
- copy configuration files to /etc
- create links in /usr/bin and /usr/sbin (if desired)
- create links in rc.d directory (if desired)
- run a configuration script (if desired)

AvGuard:
In order to install AvGuard, you first need to compile
a Dazuko module. Information on how to do this can be
found in the contrib/dazuko/HOWTO-Dazuko file.  Your
distributor may already have shipped a module you can
use.



===========
 Upgrading
===========

If you are upgrading from a previous installation,
simply run the install script (as if you were
installing for the first time).

./install

The install script will identify a previous
installation and automatically update necessary
components.



==============================
 Running/Configuring Software
==============================

The automatic internet updater is started and stopped by
running the avupdater script with the "start" and "stop"
arguments. Using the "status" argument will show the
current status of the automatic internet updater.

/usr/lib/AntiVir/avupdater start
/usr/lib/AntiVir/avupdater stop
/usr/lib/AntiVir/avupdater status

You can configure the automatic internet updater at any
time using the provided script:

/usr/lib/AntiVir/configantivir

NOTE: You do not need to install the automatic internet
      updater in order to make internet updates. It is
      also possible to make internet updates using the
      --update argument on the command line.
      This gives users the freedom to use scripts and/or
      cron jobs for updates.

AvGuard is started and stopped by running the avguard script
with the "start" and "stop" arguments. Using the "status"
argument will show the current status of AvGuard.

/usr/lib/AntiVir/avguard start
/usr/lib/AntiVir/avguard stop
/usr/lib/AntiVir/avguard status

**********************************************************
* NOTE: You need to configure AvGuard to fit your needs. *
*       The default settings are more than likely not    *
*       what you want. Configuration can be done with    *
*       the GUI or by editing the avguard.conf file      *
*       with the directives as described in the PDF doc  *
*       and the RELEASE_NOTES.                           *
**********************************************************



======================
 Manual Configuration
======================

Although the Java GUI allows to configure AntiVir for UNIX,
users may choose to manually set options.

If you prefer to manually configure AntiVir for UNIX
instead of using the provided GUI setup frontend, it
is very simple. Two configuration files are read by the
AntiVir programs on startup. Empty lines and lines
starting with "#" are ignored.

- /etc/avupdater.conf
  This file contains all the flags and options specific
  to the updater. You should edit this file to suit your
  needs. Important directives to change would be:

  HTTPProxyServer, HTTPProxyPort, HTTPProxyUsername, and
  HTTPProxyPassword in case you need to use a proxy to
  access the internet

  AutoUpdateEvery... to setup the update interval (in case
  you use the updater daemon instead of a cron job)

- /etc/avguard.conf
  This file contains all the flags and options specific
  to AvGuard. You should edit this file to suit your
  needs.  Important directives to change would be:

  NumDaemons  - specifies how many scan daemons will
                run in parallel (to balance workload
		and to increase throughput)

  AccessMask  - specifies what events cause a scan

  InlucdePath - specifies a path for AvGuard to watch
                (all sub-dirs are also watched)

  ExcludePath - specifies a path under the included paths
                that AvGuard should ignore (all sub-dirs
                are also ignored)

Both configuration files may take the following options
to specify where their respective log messages and email
notifications should be sent to:

  EmailTo - specifies where email notifications are sent
            (your server must be configured as a mail
            server if you want to use external email
            addresses)

  LogFile - specifies a specific file for log data

If you change any of the configuration files, the AntiVir programs
must be restarted. This can be done by restarting the AntiVir for
UNIX software.

/usr/lib/AntiVir/avupdater restart
/usr/lib/AntiVir/avguard restart



========
 Output
========

AntiVir for UNIX can generate scan output in several ways.
Currently these are through syslog, mail, and a specified log file.
These options can be specified during the configuration process or
manually in the /etc/avguard.conf or /etc/avguard.conf files.

- syslog
  All output from AntiVir is always generated through syslog.
  By default, messages are generated with the following
  facility and priority:

    user.notice

  You will need to refer to your syslog.conf settings to see which
  files these messages will be stored in. You may change the
  facility and/or priority during the configuration process or
  manually in the /etc/avupdater.conf or /etc/avguard.conf files.

- mail
  You can specify to have alerts or update notifications
  sent via email to a
  specific address.  For manual configurations this is
  the EmailTo directive in the /etc/avupdater.conf or
  /etc/avguard.conf files.

- specified logfile
  You may have AntiVir log output directly to a specified
  file. The output has the same content as the output to syslog.
  This has the advantage of placing all AntiVir-related activity
  into a single log file. For manual configurations this is
  done using the LogFile directive in the /etc/avupdater.conf or
  /etc/avguard.conf files.



===================
 Supported Kernels
===================

In order to use AvGuard you will need Dazuko. The
Dazuko Project is a free software project that is
developing a device driver to provide 3rd-party
file access control. At the moment Dazuko only works
for Linux and FreeBSD kernels. However, efforts will
soon be underway to port Dazuko to other operating
systems such as OpenBSD. Once Dazuko has been
ported to these other UNIX variants, AvGuard will
also be available.

Dazuko currently supports all 2.2.x, 2.4.x, 2.6.x
Linux kernels and FreeBSD 4, 5 and 6. You will need to
compile Dazuko yourself in order to make use of
AvGuard, unless your distributor already shipped a module
with the kernel. Information on how to build a modul can
be found at the Dazuko Project website:

http://www.dazuko.org/howto-install.shtml



======================
 Command Line Scanner
======================

The command line scanner can be run with the command:

antivir

For a list of available options, use the --help flag.
Important options include:

--help      print help
--version   print version information
--quiet     quiet mode
-s          recursive scan
--scan-in-archive, --scan-in-mbox
            scan within compressed files or mailbox folders
-e          repair concerning files (if possible)
--scan-mode=all
            scan all files (instead of just program files)
--update    check for a newer version of AntiVir or the
            data files

The command line scanner was designed such that it could
be used with scripts by returning useful exit codes. This
allows users to write their own scripts and/or create
cron jobs with AntiVir. Using --help will show the list
of exit codes.

If --update is used while root, then the full path should
be given for the command (i.e. /usr/lib/AntiVir/antivir
and not ./antivir). When --update is given as root, then
this command will also properly (and safely)
reload any AvGuard, SAVAPI, and AvMailGate (version 2.0)
daemons that are running if a new version is installed.
If an update is done when the process is NOT root, then
any running daemons must be manually restarted.

Keep in mind that if you are using AvGuard (i.e. you are
already scanning files as they are opened, closed, and/or
executed) then using the command line scanner could cause
the files to be scanned twice. The file would first be
scanned by AvGuard as the command line scanner tries to
open the file. Then the command line scanner would scan
the file. Concerning files with alerts will first be
handled by AvGuard which means that the command line scanner
may not be able to access and scan these files.

If a key is not found or has expired, the AntiVir software
will run in DEMO mode. This is described above.



==================
 Internet Updates
==================

Internet updates are done using HTTP. If your machine is
running behind an HTTP proxy server, you need to configure
AntiVir to use the proxy (and other updater options) by
running:

     /usr/lib/AntiVir/configantivir

or manually by editing the /etc/avupdater.conf file. Updates
can be handled in two different ways.

1) Automatic Internet Updater
   During installation you had the option of installing
   the Automatic Internet Updater. This is a very simple
   daemon that runs in the background. It sleeps until
   a certain time, calls 'antivir --update' and then
   goes back to sleep. This program was designed for
   people who do not want to worry about configuring
   scripts or cron jobs in order to have updates or who
   cannot use cronjobs due to the system's permissions. You
   can manually start, stop, and see the status of the
   updater daemon with:

   /usr/lib/AntiVir/avupdater start
   /usr/lib/AntiVir/avupdater stop
   /usr/lib/AntiVir/avupdater status

2) Manual Updates (or cron jobs)
   Another way of doing updates is manually using
   'antivir --update'. This command will give you visual
   feedback so you can see what the update is doing.
   However, you can also automate it by putting the
   command in a cron job or within a script. A typical
   cron job entry (in /etc/crontab) would look like this:

   45 6 * * * root /usr/lib/AntiVir/antivir --update -q

   This would cause AntiVir to check for updates every
   day at 6:45 (the -q is so that it runs in quiet mode,
   without any output). You could also write your own
   scripts, which look at the exit code to know if an
   update was successful. Here is a simple script to
   demonstrate this:

------------------ BEGIN SCRIPT -------------------
#!/bin/sh

/usr/lib/AntiVir/antivir --update -q
case $? in
  0)
    echo "AntiVir is up-to-date"
    ;;
  1)
    echo "AntiVir has updated itself"
    ;;
  *)
    echo "AntiVir had an error trying to update"
    ;;
esac
------------------- END SCRIPT --------------------

   If the updater is run as root, then it will do
   more than simply download updated software. It will
   also safely and securely reload any AvGuard, SAVAPI,
   or AvMailGate (version 2.0) processes. This is
   important because although you may have the latest
   AntiVir files, it is important that your
   AntiVir daemons are RUNNING the newest versions.

   You COULD manually restart AvGuard, AvMailGate, and
   SAVAPI, but this would leave a small window in time
   where files would not be scanned. By running the
   AntiVir updater as root, all daemons are updated
   WITHOUT ANY FILES GOING UNSCANNED.

   Note: When running --update as root, it is best to
         give the full path for the command. For example,
         you should call:

             /usr/lib/AntiVir/antivir --update

         and NOT:

             antivir --update

         If you do not include the full path, you
         may get a warning from AntiVir that it could
         not determine the true path of AntiVir and
         it will assume /usr/lib/AntiVir is the
         true path.

   If you do not want the process to always run as
   root, you could use the --check option as a
   regular user (to check for updates):

   /usr/lib/AntiVir/antivir --check --update

   Then if an update is available, you could log in
   as root and manually run the updater:

   /usr/lib/AntiVir/antivir --update

   Whenever AntiVir makes an update, it logs this
   information using syslog. If you have specified a
   custom log file, it is also logged into this
   file. Furthermore, if you have specified email
   notifications, it will send an email message
   each time an update was successful or if there
   was an error (email messages are not sent if an
   update was not needed).



==========================
 Testing AntiVir for UNIX
==========================

In order to test your AntiVir installation and configuration,
you can download a test virus. The test virus can be downloaded
from EICAR, an organization formed to unite efforts against the
proliferation of malicious code.

http://www.eicar.com

You can test your AvGuard by copying the test virus and seeing
if it successfully detected the event.

example: cp eicar.com eicar2.com

This example would work as long as your AccessMask directive
is set to detect opening and/or closing files. The current
path must also be included as a path that AvGuard will watch.



==============================
 Known and potential problems
==============================

For an online version of frequently asked questions see
http://www.avira.com/faq

- AvGuard uses a kernel module (Dazuko) to allow on-access
  scanning. Dazuko must be compiled for the specific
  kernel that is running on the system. Be aware that if
  you do a system upgrade, you may also have a new kernel.
  This means that the Dazuko module must be re-compiled
  for this new kernel. Otherwise AvGuard will no longer
  function after the system upgrade.

- If you are running AvMailGate and AvGuard, it is critical
  that AvGuard does NOT watch AvMailGate's SpoolDir and
  TemporaryDir. If AvGuard watches the SpoolDir, then it will
  block access to all concerning files that AvMailGate
  temporarily unpacks from attachments. AvMailGate will
  then be unable to scan the attachments and allow the
  mail to pass through. You can solve this problem by setting
  your AvMailGate SpoolDir and TemporaryDir to a directory
  that is NOT watched by AvGuard.

- It is possible that AvGuard can hang your system during
  shutdown. This occurs if AvGuard is watching system
  directories AND you do not properly shutdown AvGuard
  using the avguard script. When shutting down, Linux usually
  issues a SIG_STOP to all processes. This will freeze all the
  AvGuard daemons, thus not permitting them to do scanning.
  However, the kernel module (Dazuko) is not aware that
  the daemons are stopped and will wait forever (hang) until a
  daemon becomes available. In short, always use the avguard
  script to properly shutdown AvGuard before doing a system
  shutdown. This is a problem with Dazuko that will hopefully
  be resolved soon.

  NOTE: The installation program will ask if you want AvGuard
        to run automatically at startup. If you choose "yes"
        then you should not have to worry about this problem.

- Using multiple kernel modules that intercept file system
  calls can be very dangerous. It is highly recommended that
  AvGuard is NOT used in conjunction with other kernel
  modules that intercept filesystem calls.



============
 Contact us
============

Technical support is available at:
   support@avira.com

Please do not hesitate to contact us if you have
discovered any problems or have any suggestions.



==================
 Acknowledgments
==================

This product includes code developed by the
Apache Software Foundation (http://www.apache.org/).
Specifically, the base64 encoding function is used
in proxy authentication. See legal/LICENSE.apache
for Apache licensing information.

This product includes code that was derived from the
RSA Data Security, Inc. MD5 Message-Digest Algorithm.
Specifically, the algorithm is used to partially verify
downloaded files and as a name-hashing algorithm.

This product includes code developed by the PCRE project
(http://www.pcre.org/).  See legal/LICENSE.pcre for
licensing information.

The OpenBSD a.out version of this product is a statically
linked binary, meaning that the functionality of the
following libraries has been incorporated into this
product:
   libc.so.29.0
See legal/LICENSE.bsd for licensing information.

The Linux (glibc 2.2) and Solaris versions of this
product contain a statically linked gSoap 2.7 library.
See legal/LICENSE.gsoap for licensing information.

This product includes code copyright
Avira GmbH. Specifically, the interface for the
Dazuko device driver and for Solaris, the device
driver itself. See legal/LICENSE.dazuko for
licensing information.

