Avira AntiVir Guard (Monitor) Applet


This package contains the files necessary to compile and set up the
Avira AntiVir Guard (Monitor) Applet for Gnome. The applet is
distributed under the GNU General Public License (see LICENSE).

The applet displays the Avira logo as an opened umbrella when the
on-access scanner (Guard) is running and as a closed umbrella when it
is not. The applet also generates pop-up windows with alert
information when the Guard has blocked access to malware or other
unwanted software.


==============
 REQUIREMENTS
==============

- Avira AntiVir UNIX Workstation 2.1.11 or higher
- GNOME development packages
- GTK version 2.6 or higher
- GNOME desktop environment


==============
 INSTALLATION (applet)
==============

To get the applet running, it should be sufficient to call:

# make
# make install

After successfully running these commands, it should be possible to
add the Avira AntiVir Guard (Monitor) applet to your Gnome Panel. The
Avira logo should appear as a closed umbrella.


===============
 CONFIGURATION
===============

It is assumed that the Avira AntiVir UNIX Workstation product is
already installed and the on-access scanner (Guard) is working
correctly.

You will need to modify the /etc/avguard.conf configuration file and
set the "ActiveLockFile" directive. In the "extra" directory of this
package you will find a sample avguard.conf configuration file.

IMPORTANT: The value of the ActiveLockFile directive must match the
           value that is defined in "avira-guard-applet.c". The sample
           configuration file already contains the matching value.

To provide pop-ups, a helper script is also used. It is called
"popup_message.sh" and is located in the "extra" directory of this
package. This script must be made available on the machine and will be
used with ExternalProgram directive.


=========
 TESTING
=========

Once the applet has been installed (and added to your Gnome panel) and
avguard has been updated with "ActiveLockFile" and "ExternalProgram"
you can start the Guard:

# /usr/lib/AntiVir/avguard start

You should see the Avira logo change to an open umbrella. By stopping
the Guard, you should see the logo change back to a closed umbrella:

# /usr/lib/AntiVir/avguard stop

If malware or other unwanted software is accessed by the user (and
blocked by the Guard), you should see a popup window with information
about the alert. (You can control what type of information is shown
using the ExternalProgram macros).


=========
 CONCEPT
=========

The applet provides monitoring for two types of events. The first type
is the active status of the Guard. If the Guard is running an open
umbrella will be shown. Otherwise, a closed umbrella will be
shown. The second type is related to alerts. Each time malware or
other unwanted software is detected by the Guard, the applet will
create a pop-up window showing various information about the alert.

These two types of events are implemented using different mechanisms
within the Guard. For this reason, they will be described separately
here.


--------------------------
 ACTIVE STATUS MONITORING
--------------------------

The active status of the Guard is monitored using the "ActiveLockFile"
feature. This feature is activated by specifying:

ActiveLockFile <lockfile>

in the Guard configuration file "/etc/avguard.conf". When activated,
the Guard will acquire a file lock on the specified lockfile. The
Guard will maintain the lock as long as it is performing on-access
scanning.

An external application can then identify if the Guard is active by
testing if it can acquire an exclusive file lock on the lockfile. If
yes, then the Guard is not running. If no, then it is assumed the
Guard is active.

NOTE: If the Guard is unable to acquire the file lock (because another
      application already has it or because the lockfile does not
      exist), the Guard will start anyway. It will then routinely try
      to acquire the lock.

The applet works by creating a thread that tries to acquire a lock on
the lockfile at regular intervals. As long as it is unsuccessful, it
is assumed that the Guard has the lock and an opened umbrella is
displayed. If it is successful, the closed umbrella is displayed and
the lock is again released.

File locks were chosen as the mechanism for monitoring active status
because it is reliable. If for any reason the Guard would disappear
(killed or crash), the lock will be automatically freed.

IMPORTANT: Ideally only the Guard "antivir" processes and the applet
           should have access to the lockfile. Depending on the
           security policy used, this can be controlled differently.


------------------
 ALERT MONITORING
------------------

Alerts generated by the Guard are monitored using two
mechanisms. First, the "ExternalProgram" feature is used to call a
script for each alert. Secondly, the called script will create a
temporary file in a directory that the applet is monitoring. When a
file appears in that directory, the applet displays the contents in a
pop-up window and deletes the file.

In order for this to work correctly, both the Guard and the applet
must have read/write access to the directory monitored by the
applet. (This directory is specified in the "popup_message.sh" script
and within the applet source code.)

IMPORTANT: Ideally only the Guard "antivir" processes and the applet
           should have read/write access to the directory monitored by
           the applet. Depending on the security policy used, this can
           be controlled differently.


=========
 CONTACT
=========

Please submit any problems regarding the applet to:
<support@avira.com>

We also appreciate patches for the "avira-guard-applet.c" file if
improvements or bugfixes have been made.

