<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<refentry id="vfs_virusfilter.8">

<refmeta>
	<refentrytitle>vfs_virusfilter</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo class="source">Samba</refmiscinfo>
	<refmiscinfo class="manual">System Administration tools</refmiscinfo>
	<refmiscinfo class="version">4.8</refmiscinfo>
</refmeta>


<refnamediv>
	<refname>vfs_virusfilter</refname>
	<refpurpose>On access virus scanner</refpurpose>
</refnamediv>

<refsynopsisdiv>
	<cmdsynopsis>
		<command>vfs objects = virusfilter</command>
	</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
	<title>DESCRIPTION</title>

	<para>This is a set of various Samba VFS modules to scan and filter
	virus files on Samba file services with an anti-virus scanner.</para>

	<para>This module is stackable.</para>

</refsect1>

<refsect1>
	<title>OPTIONS</title>

	<variablelist>

		<varlistentry>
		<term>virusfilter:scanner</term>
		<listitem>
		<para>The antivirus scan-engine.</para>
		<itemizedlist>
		  <listitem><para><emphasis>sophos</emphasis>, the Sophos AV
		  scanner</para></listitem>
		  <listitem><para><emphasis>fsav</emphasis>, the F-Secure AV
		  scanner</para></listitem>
		  <listitem><para><emphasis>clamav</emphasis>, the ClamAV
		  scanner</para></listitem>
		</itemizedlist>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:socket path = PATH</term>
		<listitem>
		<para>Path of local socket for the virus scanner.
		</para>
		<para>If this option is not set, the default path depends on the
		configured AV scanning engine.
		</para>
		<para>For the <emphasis>sophos</emphasis>backend the default is
		<emphasis>/var/run/savdi/sssp.sock</emphasis>.</para>
		<para>For the <emphasis>fsav</emphasis> backend the default is
		<emphasis>/tmp/.fsav-0</emphasis>.</para>
		<para>For the <emphasis>fsav</emphasis> backend the default is
		<emphasis>/var/run/clamav/clamd.ctl</emphasis>.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:connect timeout = 30000</term>
		<listitem>
		<para>Controls how long to wait on connecting to the virus
		scanning process before timing out. Value is in milliseconds.
		</para>
		<para>If this option is not set, the default is 30000.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:io timeout = 60000</term>
		<listitem>
		<para>Controls how long to wait on communications with the virus
		scanning process before timing out. Value is in milliseconds.
		</para>
		<para>If this option is not set, the default is 60000.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan on open = yes</term>
		<listitem>
		<para>This option controls whether files are scanned on open.
		</para>
		<para>If this option is not set, the default is yes.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan on close = no</term>
		<listitem>
		<para>This option controls whether files are scanned on close.
		</para>
		<para>If this option is not set, the default is no.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:max file size = 100000000</term>
		<listitem>
		<para>This is the largest sized file, in bytes, which will be scanned.
		</para>
		<para>If this option is not set, the default is 100MB.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:min file size = 10</term>
		<listitem>
		<para>This is the smallest sized file, in bytes, which will be scanned.
		</para>
		<para>If this option is not set, the default is 10.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:infected file action = nothing</term>
		<listitem>
		<para>What to do with an infected file. The options are
		nothing, quarantine, rename, delete.</para>
		<para>If this option is not set, the default is nothing.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:infected file errno on open = EACCES</term>
		<listitem>
		<para>What errno to return on open if the file is infected.
		</para>
		<para>If this option is not set, the default is EACCES.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:infected file errno on close = 0</term>
		<listitem>
		<para>What errno to return on close if the file is infected.
		</para>
		<para>If this option is not set, the default is 0.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:quarantine directory = PATH</term>
		<listitem>
		<para>Where to move infected files. This path must be an
		absolute path.</para>
		<para>If this option is not set, the default is ".quarantine"
		relative to the share path. </para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:quarantine prefix = virusfilter.</term>
		<listitem>
		<para>Prefix for quarantined files.</para>
		<para>If this option is not set, the default is "virusfilter.".</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:quarantine suffix = .infected</term>
		<listitem>
		<para>Suffix for quarantined files.
		This option is only used if keep name is true. Otherwise it is ignored.</para>
		<para>If this option is not set, the default is ".infected".</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:rename prefix = virusfilter.</term>
		<listitem>
		<para>Prefix for infected files.</para>
		<para>If this option is not set, the default is "virusfilter.".</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:rename suffix = .infected</term>
		<listitem>
		<para>Suffix for infected files.</para>
		<para>If this option is not set, the default is ".infected".</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:quarantine keep tree = yes</term>
		<listitem>
		<para>If keep tree is set, the directory structure relative
		to the share is maintained in the quarantine directory.
		</para>
		<para>If this option is not set, the default is yes.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:quarantine keep name = yes</term>
		<listitem>
		<para>Should the file name be left unmodified other than adding a suffix
		and/or prefix and a random suffix name as defined in virusfilter:rename prefix
		and virusfilter:rename suffix.</para>
		<para>If this option is not set, the default is yes.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:infected file command = @SAMBA_DATADIR@/bin/virusfilter-notify --mail-to virusmaster@example.com --cc "%U@example.com" --from samba@example.com --subject-prefix "Samba: Infected File: "</term>
		<listitem>
		<para>External command to run on an infected file is found.</para>
		<para>If this option is not set, the default is none.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan archive = true</term>
		<listitem>
		<para>This defines whether or not to scan archives.</para>
		<para>Sophos and F-Secure support this and it defaults to false.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:max nested scan archive = 1</term>
		<listitem>
		<para>This defines the maximum depth to search nested archives.</para>
		<para>The Sophos and F-Secure support this and it defaults to 1.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan mime = true</term>
		<listitem>
		<para>This defines whether or not to scan mime files.</para>
		<para>Only the <emphasis>fsav</emphasis>scanner supports this
		option and defaults to false.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan error command = @SAMBA_DATADIR@/bin/virusfilter-notify --mail-to virusmaster@example.com --from samba@example.com --subject-prefix "Samba: Scan Error: "</term>
		<listitem>
		<para>External command to run on scan error.</para>
		<para>If this option is not set, the default is none.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:exclude files = empty</term>
		<listitem>
		<para>Files to exclude from scanning.</para>
		<para>If this option is not set, the default is empty.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:block access on error = false</term>
		<listitem>
		<para>Controls whether or not access should be blocked on
		a scanning error.</para>
		<para>If this option is not set, the default is false.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan error errno on open = EACCES</term>
		<listitem>
		<para>What errno to return on open if there is an error in
		scanning the file and block access on error is true.
		</para>
		<para>If this option is not set, the default is EACCES.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:scan error errno on close = 0</term>
		<listitem>
		<para>What errno to return on close if there is an error in
		scanning the file and block access on error is true.
		</para>
		<para>If this option is not set, the default is 0.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:cache entry limit = 100</term>
		<listitem>
		<para>The maximum number of entries in the scanning results
		cache. Due to how Samba's memcache works, this is approximate.</para>
		<para>If this option is not set, the default is 100.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:cache time limit = 10</term>
		<listitem>
		<para>The maximum number of seconds that a scanning result
		will stay in the results cache. -1 disables the limit.
		0 disables caching.</para>
		<para>If this option is not set, the default is 10.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:quarantine directory mode = 0755</term>
		<listitem>
		<para>This is the octet mode for the quarantine directory and
		its sub-directories as they are created.</para>
		<para>If this option is not set, the default is 0755 or
		S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH |
		S_IXOTH.</para>
		<para>Permissions must be such that all users can read and
		search. I.E. don't mess with this unless you really know what
		you are doing.</para>
		</listitem>
		</varlistentry>

		<varlistentry>
		<term>virusfilter:block suspected file = false</term>
		<listitem>
		<para>With this option on, suspected malware will be blocked as
		well. Only the <emphasis>fsav</emphasis>scanner supports this
		option.</para>
		<para>If this option is not set, the default is false.</para>
		</listitem>
		</varlistentry>

	</variablelist>
</refsect1>

<refsect1>
	<title>NOTES</title>

	<para>This module can scan other than default streams, if the
	alternative datastreams are each backed as separate files, such as with
	the vfs module streams_depot.</para>

	<para>For proper operation the streams support module must be before
	the virusfilter module in your vfs objects list (i.e. streams_depot
	must be called before virusfilter module).</para>

	<para>This module is intended for security in depth by providing
	virus scanning capability on the server. It is not intended to be used
	in lieu of proper client based security. Other modules for security may
	exist and may be desirable for security in depth on the server.</para>
</refsect1>

<refsect1>
	<title>AUTHOR</title>

	<para>The original Samba software and related utilities
	were created by Andrew Tridgell. Samba is now developed
	by the Samba Team as an Open Source project similar
	to the way the Linux kernel is developed.</para>

</refsect1>

</refentry>