AVFILTER(8)

avfilter - Anti Virus filter, ClamAV for Courier  

filterctl ("start" | "stop") avfilter

/usr/lib/courier/filters/avfilter OPTION

The second form can be used for testing and scripting. 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.  

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, for reformime or to send false positives to clamav.net, the preheader has to be removed, e.g. using sed -n '0,/^$/!p' avf-File....  

-f config-file

Specify an alternative configuration file.

--config

Check and display the values of the configuration file. All values are shown along with their current and default values. In addition, directories are checked for suitable access. 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 | /usr/lib/courier/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.

 

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 some 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/etc/path/filters/avfilter.conf

/usr/lib/courier/filters/avfilter

/var/run/courier/avfilter.pid

/var/run/courier/avfilter_sig.pipe

/var/lib/courier/allfilters/avfilter (see note)

/var/lib/courier/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)