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




avfilter - Anti Virus filter, ClamAV for Courier  


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.  


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.  


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.
Bouncing infected messages is the default behavior. It is the officially recommended way to refuse an SMTP message.
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.
Runtime errors that are likely transient result in a 451 reply. This action cannot be configured.


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.  


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.  


-f config-file
Specify an alternative configuration file.
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.

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 
Display command line options summary and exit.
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.

Enter batch test mode.


avfilter_sig sends signals to the master avfilter process to have it reload its data:
reload config
reload virus
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.  






/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.  


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.  


Alessandro Vesely <vesely@tana.it>  


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

Copyright © 2014-2017 Alessandro Vesely