home
documentation:avfilter avfilter_sig avfilter.conf
version 3.4; page generated 2017-01-12

AVFILTER(8)

 

NAME

avfilter - Anti Virus filter, ClamAV for Courier  

SYNOPSIS

filterctl ("start" | "stop") avfilter

/local/libexec/usr/path/filters/avfilter OPTION

The second form can be used for scripting and testing. See COMMAND LINE OPTIONS below.  

DESCRIPTION

avfilter is a global filter, in the sense that it works for all users. The master process listens for scan requests and forks a child to serve each of them. The master process must be started and stopped using courierfilter.

LibClamAV is used to scan mail. One of four possible actions is taken when one or more viruses are found. Actions can be configures based on virus names, recipients, or authorized senders.  

POSSIBLE ACTIONS

pass
It is possible to add a custom header field reporting the name of the virus(es). That way a downstream filter can still reject the mail message, or a maildrop recipe can discard it.
reject
Bouncing infected messages is the default behavior. It is the officially recommended way to refuse an SMTP message.
drop
Drop, also known as discard or quarantine, consists of issuing a positive reply to the remote client, but then failing to deliver the message. This behavior makes sense when the false-positive rate is very very low, especially if the bounce address is likely to be spoofed.
defer
Runtime errors that are likely transient result in a 451 reply. This action cannot be configured.
 

HOW ACTION IS DETERMINED

There are various configuration items that allow to configure the desired behavior. They are applied in the following order:
1 virus-specific actions
The pass, reject, and drop arrays (see avfilter.conf(5)) are searched. If a match is found, the corresponding action becomes the candidate action. If multiple matches are found, the most severe action wins; that is, "reject" overrides "pass", and "drop" overrides any of the other two.

If option allmatch is configured, there may be multiple virus names, all of which are searched.

2 default action
If any virus was found, but no action was determined at step 1, action_default becomes the candidate action. If this is not configured, then "reject".
3 whitelisted recipients
If all recipients match an entry in pass_recipient, then "pass" becomes the candidate action.

For example, one can set

        pass_recipient = abuse@* 

Keep in mind that both incoming and outgoing messages are filtered, thus that example is also enabling users to send virus samples to any abuse desk.

4 whitelisted senders
If the sender is authenticated, and the id matches an always_pass entry, the candidate action becomes "pass". This is meant for users who wittingly send virus samples as part of their job. Those users are expected to be savvy enough to not have their password stolen, ever.

Unless runtime errors occur, the last candidate action becomes the final one. At "verbose=2" and above, each step is logged.  

QUARANTINE

It is possible to save a copy of infected messages by configuring a suitable directory in save_virus (see avfilter.conf(5)). Files can be restricted by enabling save_only_if_drop. Some envelope information is also saved by inserting a "preheader". The resulting format is as follows:

        envelope sender on the first line (possibly empty)
        envelope recipient(s), one per line
        <empty line>
        Received: and normal header fields (unchanged)
        <empty line>
        Mail body (unchanged) 

If a dropped message turns out to be a false positive, it is possible to use the envelope information to resend it. Example scripts for doing so are in the distribution (etc/resend-with-preheader.{pl,sh}). Messages which were rejected or delivered should not be resent this way.

If the preheader isn't abnormally long, clamscan seems to be still able to recognize a Mail file, and then parse and scan it, ignoring the preheader. However, other tools, such as reformime, don't read it, so it's necessary to remove the preheader, e.g. using tail -n +4 avf-File....

The preheader has to be removed before sending a false positive report to www.clamav.net. Spoofed domain false positive can also be treated by creating a local.wdb ClamAV database and whitelisting targets which may look suspicious, as explained in phishsigs_howto.pdf.  

COMMAND LINE OPTIONS

-f config-file
Specify an alternative configuration file.
--config
Check and display the values from the configuration file. All values are shown along with their current and default values. See example in avfilter.conf(5).

If -t is also given, only check is done, no display.

--check-action
Read virus names from stdin and match each against pass, reject, drop as described "1 virus-specific actions" above. For example:

        sigtool -l | /local/libexec/usr/path/filters/avfilter --check-action 
--help
Display command line options summary and exit.
--version
Display version string and exit.
-t file...
Scan arguments as mail file(s), using dummy hardcoded recipients.

When used with --config (without arguments), skip displaying values.

--batch-test
Enter batch test mode.
 

SIGNALS

avfilter_sig sends signals to the master avfilter process to have it reload its data:
USR1
reload config
USR2
reload virus
HUP
reload both

On receiving one of these signals, avfilter tries to open a pipe for writing to avfilter_sig, which presumably sent the signal. Normally, events are reported on stderr, which is read by courierlogger. If the pipe can be opened, it will be used instead of stderr.

Reloading ClamAV databases can take quite a few seconds, so a child is forked to listen for new requests meanwhile. When that child is done, the master process resumes serving requests, and new children will use new data.  

FILES

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

/local/libexec/usr/path/filters/avfilter

/local/courier/var/path/tmp/avfilter.pid

/local/courier/var/path/tmp/avfilter_sig.pipe

/local/courier/var/path/allfilters/avfilter (see note)

/local/courier/var/path/filters/avfilter (see note)

Note: The request socket is created in either one or the other directory depending on the configured value of all_mode. The socket's name may depend on the link name in /local/courier/etc/path/filters/active.  

ENVIRONMENT VARIABLE

LIBCLAMAV_DEBUG enables debug messages from libclamav, an output similar to that of clamscan --debug. Its value can be a positive integer to enable, 0 to disable (the default). The value of verbose has to be 2 or higher for enabled debug messages to actually pass through.  

AUTHOR

Alessandro Vesely <vesely@tana.it>  

SEE ALSO

avfilter.conf(5), courier(8), courierfilter(8), avfilter_sig(8), sigtool(1)

Copyright © 2014-2017 Alessandro Vesely