Installation instructions for samba-vscan
*****************************************

Copyright (C) by Rainer Link, 2001-2002
	      OpenAntiVirus.org <rainer@openantivirus.org>

This software is licensed under the GNU General Public License (GPL)
See COPYING file or http://www.gnu.org/copyleft/gpl.html


Contents
========

Instructions for Samba 2.2.0 to 2.2.3
Instructions for Samba >= 2.2.4 or Samba 3.0
Troubleshooting: popt-Library
Antivirus product-specific information
Check the license of your antivirus product



Instructions for Samba 2.2.0 to 2.2.3
-------------------------------------

VFS support is broken in these Samba releases. I would suggest to use the
latest 2.2.x release (as the time of this writing Samba 2.2.6). To get VFS
working, you have to apply the provided samba-<version>-vfs.dif, re-
configure Samba (./configure --enable-vfs) and re-compile Samba.

Copy recursively the directory of the antivirus program you would like to use
to <samba-source>/examples/VFS and make then this directory your working 
directory. Assumed, you would like to use the OpenAntiVirus ScannerDaemon, #
it could be 
cp -ra openantivirus/ /usr/local/src/samba/examples/VFS
cd /usr/local/src/samba/examples/VFS/openantivirus

Open vscan-<product>.h (i.e. vscan-oav.h) and set 
SAMBA_VERSION_MINOR to the following values
0 - for Samba 2.2.0
1 - for Samba 2.2.1
2 - for Samba 2.2.2 _and_ 2.2.3 (!)

As the parsing for the "vfs option" parameter is broken in these Samba 
releases, you must use the compile-time settings and can not use a run-time
configuration file per share. Once again, please consider to use the latest
2.2.x release.

The following compile time settings are available in vscan-<product>.h, i.e.
vscan-oav.h:
 
* VSCAN_SCAN_ON_OPEN: if it's set to True (default), files will be scanned on
  open
* VSCAN_SCAN_ON_CLOSE: if it's set to False (default), files will be scanned
  on close
* VSCAN_MAX_SIZE:  scanning a (very) large file may slow down performance 
  (too much). Therefore, you can specify if a file is larger than x bytes, 
  it shouldn't be scanned. Please set it for your needs. If it's set to 0,
  all files, regardless of their file size, will be scanned.  
* VSCAN_DENY_ACCESS_ON_ERROR:  if communication to the virus scanning daemon 
  fails, you may either deny access to file(s) or not. You can change this 
  behaviour via the VSCAN_DENY_ACCESS_ON_ERROR setting. If it's set to 
  True (default), access will be _denied_.

To compile the module, simply type "make". After compilation has finished,
copy the vscan-<product>.so (i.e. vscan-oav.so) to /usr/local/samba/lib
(this is the default location of Samba - depending on your vendor/distribution,
the location may vary).

Edit /etc/smb.conf and add the following entry (that's only an example):
  [vscan]
                comment = virus-protected /tmp directory
                path = /tmp
                vfs object = /usr/lib/samba/vfs/vscan-oav.so
                writeable = yes
                browseable = yes
                guest ok = yes


So, basically you have to add a vfs object line to _all_ of your shares
which should be virus-protected by this module

Restart Samba (i.e. killall -HUP smbd)

If you want to test, if everything works well, simply do the following steps
copy eicar.com to /tmp
smbclient //localhost/vscan
  At the smbclient command line try to retrieve eicar.com
  - get eicar.com
    -> access should be denied!!!
everything should be logged via syslog


Installation instructions for Samba >= 2.2.4 or Samba 3.0
---------------------------------------------------------

VFS support works out-of-the-box in these Samba releases. As for compiling this
module the config.h file of Samba is needed, you have to run ./configure in
<samba-source>/source.

Copy recursively the directory of the antivirus program you would like to use
to <samba-source>/examples/VFS and make then this directory your working 
directory. Assumed, you would like to use the OpenAntiVirus ScannerDaemon, 
it could be 
cp -ra openantivirus/ /usr/local/src/samba/examples/VFS
cd /usr/local/src/samba/examples/VFS/openantivirus

Open vscan-<product>.h (i.e. vscan-oav.h) and set 

SAMBA_VERSION_MINOR to the following value
4 - for Samba 2.2.4 and later 

OR

SAMBA_VERSION_MAJOR to
3 - for Samba 3.0 (SAMBA_VERSION_MINOR is ignored in this case then)


In Samba 2.2.4 and better (or Samba 3.0), the "vfs option" parsing works
correctly, so you can use the run-time configuration file on a per share
basis, if you like. Of course, the compile time settings are still useable
(and can be overwritten by the run-time configuration file)

The following compile time settings are available in vscan-<product>.h, i.e.
vscan-oav.h
 
* VSCAN_SCAN_ON_OPEN: if it's set to True (default), files will be scanned on
  open
* VSCAN_SCAN_ON_CLOSE: if it's set to False (default), files will be scanned
  on close
* VSCAN_MAX_SIZE:  scanning a (very) large file may slow down performance 
  (too much). Therefore, you can specify if a file is larger than x bytes, 
  it shouldn't be scanned. Please set it for your needs. If it's set to 0,
  all files, regardless of their file size, will be scanned.  
* VSCAN_DENY_ACCESS_ON_ERROR: if communication to the virus scanning daemon 
  fails, you may either deny access to file(s) or not. You can change this 
  behaviour via the VSCAN_DENY_ACCESS_ON_ERROR setting. If it's set to 
  True (default), access will be _denied_.

To compile the module, simply type "make". After compilation has finished,
copy the vscan-<product>.so (i.e. vscan-oav.so) to /usr/local/samba/lib
(this is the default location of Samba - depending on your vendor/distribution,
the location may vary).

Edit /etc/smb.conf and add the following entry (that's only an example):
  [vscan]
                comment = virus-protected /tmp directory
                path = /tmp
                vfs object = /usr/lib/samba/vfs/vscan-oav.so
		vfs option = /etc/samba/vscan-oav.conf
                writeable = yes
                browseable = yes
                guest ok = yes


So, basically you have to add a vfs object line to _all_ of your shares
which should be virus-protected by this module. If you'd like to use the
run-time configuration file, simply add the vfs options = /path/config-file
(different settings for several shares can be achived by using a different
name of the configuration file for each share).


The following options are available in the samba-style run-time configuration 
file for each anti-virus product (some additional settings are available, 
please refer to the corresponding configuration file):

* max file size = <value>
  This setting can be used to exclude (very) large files from scanning. <value>
  is an integer value (bytes). If set to 0 (default), all files will be scanned.

* verbose file logging = <boolean>
  Specifies whether every scan of a file should be logged (therefore, clean 
  files will be logged, too). If set to yes (or True or 1), everything will 
  be logged.
  If set to no (or False or 0), only access to infected files will be logged
  (this is the default)

* scan on open = <boolean>
  If set to yes (or True or 1), a file will be scanned while opening it. Default
  is yes.

* scan on close = <boolean>
  If set to yes (or True or 1), a file will be scanned while closing. Default
  is no.

* deny access on error = <bolean>
  If set to yes (or True or 1), access to file will be denied if communication
  to the virus scanning daemon has failed (and therefore could not be scanned).
  Default is yes.


Restart Samba (i.e. killall -HUP smbd)

If you want to test, if everything works well, simply do the following steps
copy eicar.com to /tmp
smbclient //localhost/vscan
  At the smbclient command line try to retrieve eicar.com
  - get eicar.com
    -> access should be denied!!!
everything should be logged via syslog



Troubleshooting: popt-Libary
----------------------------

The Makefile for each module assumes that the popt libarary is installed on 
your system. If compilation failes because of a missing popt.h file, either
install the popt library (i.e. on SuSE Linux: rpm -Uvh popt.rpm) or use
the popt as shipped within the Samba sources. To achieve this, you have to
change the Makfile as mentioned below

- add POPT_SRC right after the SMBWRD_SRC entry:
POPT_SRC = ../../../source/popt

- add -I$(POPT_SRC) to the CFLAGS setting (that's a one-liner!)
CFLAGS = -I$(SAMBA_SRC) -I$(SAMBA_INCL) -I$(UBIQX_SRC) -I$(SMBWR_SRC)
-I$(POPT_SRC) -Wall -g - D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64

And then simply compile it.


Antivirus product-specific information
**************************************

- F-Prot
  A running F-Prot daemon is required, which runs on localhost (127.0.0.1), 
  port 10200. The port number can be changed via VSCAN_FPROTD_PORT in
  vscan-fprotd.h or the fprot port = <integer> setting in the run-time
  configuration file
  The arguments passed to the daemon (i.e. to scan inside of archive files) can 
  be set via VSCAN_FPROTD_ARGS in vscan-fprotd.h or fprotd args = <string>
  in the run-time configuration file (default is -dumb%20-archive); remember
  to encode space as %20

  
- Kaspersky Anti Virus
  Install kavplinux linux from Kaspersky.
  You can download a version from www.kaspersky.com
  Install the version according to the docs and make sure that 
  kavdaemon is running. Also make sure that kavpdamen does scan the 
  samba shared directorys!!!! Please do check the [object] section
  in defUnix.prf and sure you add something like:
  Names=*/samba_shares
  where samba_shaes is a samba share!
  Please do check if kavdaemon really can scan that directory!
  You can do this by copying a eicar.test file to on of the shares and run:
  $AVPBASEDIR/DaemonClients/Sample/AvpDaemonClient /samba_shares/eicar.com
  The AvpDaemonClient software should now return that a virus was found!

  Then compile the KAV C library. Change into 
  <AVPDIR>/DaemonClients/SampleLibs/C and type
  make
  make install

  This installs kavdclib.so into /usr/lib

  Per default, the daemon socket file is /var/run/AvpCtl. If this isn't true
  on your system, please set either AVPCTL in vscan-kavp.h or 
  avp socket file = <string> in the run-time configuration file accordingly.

  If compiling of the vscan-kavp module fails, please try
  make -f Makefile.KAV4 

  
- OpenAntiVirus ScannerDaemon
  A running ScannerDaemon on the same host as your Samba Server is needed. Per
  default, localhost (127.0.0.1) and port 8127 is assumed. The port can be
  changed via VSCAN_OAV_PORT in vscan-oav.h or via the oav port = <int>
  setting in the run-time configuration file.


- Sophos Sweep via Sophie / Trend via Trophie
  You need Sophie or Trophie from http://www.vanja.com/tools/. As socket name
  /var/run/sophie (/var/run/trophie) is assumed. You can modify this via
  SOPHIE_SOCKET_NAME (TROPHIE_SOCKET_NAME) in vscan-sophos.h (vscan-trend.h) or
  via sophie socket name = <string> (trophie socket name = <string>) in the
  run-time configuration file.



Check the license of your antivirus product
-------------------------------------------

Before using samba-vscan together with your anti-virus product, please check
if your current license allows this, i.e. are you allowed to use it on a
server? Are you allowed to use it for your (maximum) number of users connected
to your Samba Server? Contains the license some other stuff, which won't
permit it to use within samba-vscan? If in doubt, please contact your
vendor/dealer and buy the correct license. Thank you very much for your
co-operation.


