AVFILTER.CONF(5)

avfilter.conf - avfilter configuration file  

logic line = [ "#" comment ] | name [ "=" ] [ value ]

The file consists of zero or more lines.

Names are case sensitive; valid ones are shown below, divided into categories. The format of values depends on the type associated with their name.

Leading and trailing spaces, as well as spaces around "=" are removed. Backslashes ("\") can be used to wrap multiple physical lines into a single logical one, even comments.  

The value and type of each option can be displayed using the --config command line option of avfilter. Types are as follows:

array

A collection of space-separated strings. Except for pua, that is for pass_recipient, pass, reject, and drop, they are patterns. A pattern can have "*" or "?" wildchars, much like in shell glob expansion, except that slashes have no special meaning. It is case sensitive.

New definitions of an already defined array append new values to the existing ones. For example, the following forms are equivalent:

        reject Virus.Name.A \
                Virus.Name.B \
                Virus.Name.C 

and

        reject Virus.Name.A
        reject Virus.Name.B
        reject Virus.Name.C 

bool

Booleans values accept "Y", "T", and 1 for true, "N" and 0 for false (case insensitively). By default, all bool values are false, but if the value is not specified it defaults to true. That is to say, setting just the name suffices to enable a bool option.

directory

Trailing slashes are removed. An attempt is done to create directories immediately below /tmp.

int

Regular numbers. Currently, they all happen to be non-negative.

size

Like "int", but "K" and "M" trailing multipliers are accepted (case insensitively). This is the same as clamscan.

string

Generic type, also used for choices among three or more predefined values (documented as a slash-separated list).

 

These options are used directly by avfilter.

all_mode (bool)

This option determines where avfilter creates the socket to serve requests. If this is false, recipients have a chance to whitelist a message using the maildrop filtering API; see courierfilter.

Although the default is false, the default avfilter.conf.dist sets it to true. The latter file is copied to avfilter.conf unless one exists.

NOTE: Changing this parameters has no effect on running processes. It is necessary to restart the master filter to change mode of operations.

action_default (pass/reject/drop)

This establishes the default action. If not set, the action is set to "reject".

always_pass (array)

This is a (white) list of user-id patterns, as resulting from an authentication module after successful authentication. A matching entry forces "pass" action at the last, final step of action determination.

pass_recipient (array)

This is a list of recipients patterns that can force a "pass" at step 3 in the action determination. If even one recipient does not match, the candidate action remains unchanged.

pass, reject, and drop (array)

These are arrays of virus name patterns. They are checked as the first step in the action determination, to find virus-specific actions.

save_virus (directory)

Setting this directory enables quarantine, by saving any message that is going to be dropped. Sender and recipients are also saved, so as to allow a simplified form of resubmit. However, no other envelop field is saved.

save_only_if_drop (bool)

If true, this restricts quarantine to dropped messages only. Those are the ones that is cool to resend if they turn out to be false positives.

save_missed (directory)

Messages are saved here if LibClamAV returns an unexpected error code.

piddir (directory)

Where to save avfilter's pid file, avfilter.pid.

verbose (int)

A one-digit verbosity selector. Runtime errors are logged anyway. Most useful messages, such as "virus found" are logged at verbose 1. Verbose 2 can give some more details; it also passes through debug messages from libclamav (if enabled by LIBCLAMAV_DEBUG=1). The higher the value of verbose, the more copious the logging.

virus_header (string)

This is the name of an RFC 5322 header field that will be used to store virus name(s) in the message, if viruses are found. That is done when the action is "pass".

If this option is set, avfilter renames any existing field having the same name by prepending "Old-". That way, downstream filters can reliably learn if a message is infected by checking for this field existence.

 

These options are passed to LibClamAV as-is. Their names are similar to those used by clamscan, except for using underscore instead of minus. We refer to that documentation for their meaning, but explain their use.

These options are divided into three categories, "engine", "load", and "scan". Scan options make up a flag which is passed to LibClamAV on every message scan request, so it is enough to reload avfilter configuration to enable new behavior --but mind the WARNING below. Engine and load options are used during the initialization, so a full reload of avfilter data is necessary for a change to be effective.

WARNING: ClamAV suggest some default values for the options tagged "load" and "scan". If no "scan" option is set, then the suggested default set is applied. Likewise for "load". Thus, if you want to alter just one of the options, you need to first fill avfilter.conf with all the default values, and then tweak the one you're after. For example, the first time you enable a "scan" option, say "allmatch", do:

        /local/libexec/usr/path/filters/avfilter --config |\
        grep 'bool, scan, default 1' |\
        awk '{print $1;}' >> /local/courier/etc/path/filters/avfilter.conf 

and then

        echo allmatch >> /local/courier/etc/path/filters/avfilter.conf
        avfilter_sig reload config 

engine

bytecode_mode, bytecode_statistics, bytecode_timeout, dev_ac_depth, dev_ac_only, force_to_disk, leave_temps, max_embeddedpe, max_files, max_filesize, max_htmlnormalize, max_htmlnotags, max_recursion, max_scansize, max_scriptnormalize, max_ziptypercg, pua, structured_cc_count, structured_ssn_count, tempdir.

load

bytecode, bytecode_unsigned, database, detect_pua, exclude_pua, include_pua, official_db_only, phishing_scan_urls, phishing_sigs.

scan

heuristic_alerts, allmatch, alert_encrypted, alert_encrypted_archive, alert_encrypted_doc, alert_broken, alert_broken_media, detect_structured, dev_performance, heuristic_scan_precedence, alert_phishing_cloak, alert_phishing_ssl, alert_exceeds_max, alert_macros, alert_partition_intersection, scan_archive, scan_elf, scan_html, scan_mail, scan_ole2, scan_pdf, scan_pe, scan_swf.

NOTE: at least "scan_mail" must be set, or avfilter won't run.

NOTE2: some names have changed since previous version of both ClamAV and avfilter. See either package's release notes.

 

/local/courier/etc/path/filters/avfilter.conf  

Alessandro Vesely <vesely@tana.it>  

avfilter(8), courierfilter(8) clamscan(1)