SMTP-VILTER(8)

NAME
smtp-vilter - content filter for sendmail based MTAs

SYNOPSIS
smtp-vilter [-vmV] [-p port] [-d tmpdir] [-T tmpfile-opt] [-b backend] [-e logfile] [-s statfile] [-i interval] [-n msgfile] [-o pattern] [-C configfile] [-t chrootdir] [-u user] [-g group] [-f maxfiles] [-a spam-subject-prefix] [-H header-options]

DESCRIPTION
smtp-vilter is a high performance content filter for sendmail to detect e-mail viruses, spam, and otherwise unwanted content. smtp-vilter decides whether to pass, discard or simply mark an e-mail message based on the results of a content scan and user defined strategies.

smtp-vilter does not do the scanning by itself, it relies on third-party software like ClamAV, or SpamAssassin for this purpose. smtp-vilter uses the milter API to communicate with sendmail and one or more backends to communicate with the actual virus or spam scanning engines. The backends can be chained to perform a series of checks on one message in one run.

The software is highly configurable and provides mechanisms for secure operation.

The backends included in the distribution provide support for the Clam AntiVirus Daemon (vilter-clamd), the SpamAssassin Daemon (vilter-spamd), and a backend for ICAP scanners (vilter-icap). There is a stand-alone backend to scan for unwanted attachments (vilter-attachment). The backends are realised as shared libraries that are loaded dynamically when smtp-vilter starts. All backends have their own configuration file.

The command line options are as follows:

-v  Start in verbose mode. smtp-vilter will run in foreground and some diagnostic messages are displayed on the console. Watch the system log for additional messages.

-vv Enable a few additional messages relating to SASL authentication, and display data sent to and from backend sockets.

-m  Mark all messages with “X-SMTP-Vilter” headers.

-V  Show the version number and exit.

-p port
    Specify the port for communication with sendmail.

-d tmpdir
    Specify a temporary directory.

-T tmpfile-opt
    Specify a temporary file option. This flag can be used more than once. Possible values are:

    g+r
    Make temp files group readable.

    setgrp
    Set the group ownership of temp files.

-b backend
    Specify the name of a backend to do the actual virus scanning.

-e logfile
    Specify a file for extended logging.

-s statfile
    Specify a file to write statistics to.

-i interval
    Specify an interval for automatic dumping of statistics.

-n msgfile
    Specify a file containing a notification message if the strategy is set to notify-recipients.

-o pattern
    If the strategy is set to notify-recipients only those recipients that contain pattern in their E-Mail address are sent a notification message.

-C configfile
    Specify the path to the configuration file.

-t chrootdir
    Specify the directory to which the program will chroot after start.

-u user
    Specify a user name under which the program is to be run.

-g group
    Specify a group name under which the program is to be run.

-f maxfiles
    Use setrlimit(2) to set a maximum number of open file descriptors.

-a spam-subject-prefix
    Specify a prefix that will be put in from of the Subject-line if a message is considered spam.

-H header-options
    Control various features of the internally generated header used to forward messages to a spam detection backend (see "Header Options" below).

Configuring Sendmail
Add the following lines to your sendmail .mc configuration (assuming the socket file is in /var/run):

    INPUT_MAIL_FILTER(`smtp-vilter', `S=unix:/var/run/smtp-vilter.sock, F=T, T=S:10s;R:120s')
    define(`confINPUT_MAIL_FILTERS', `smtp-vilter')

Configure your timeouts to sane values. If you use Spamassassin make them long enough. Remember you have to set timeouts not only in the smtp-vilter and backend config files, but in your sendmail .mc config file a s well as shown in the example above which configures a sending timeout of 10 seconds and a receiving timeout of 120 seconds.

Using Postfix
smtp-vilter can be used with recent versions of Postfix that include milter support. Postfix needs access to smtp-vilter.sock by making it a member of the owning group and setting umask 002 before running smtp-vilter

Postfix does not automatically set the _ macro, this must be added to main.cf manually:

    milter_connect_macros = j {daemon_name} v _

Header Options
As smtp-vilter receives messages directly via the milter interface, it doesn't have access to headers that are added downstream by the MTA. So in order pass a message to a spam detection backend smtp-vilter must generate and add its own artificial header. Note that this header is entirely internal and is NOT visible to the MTA or the end recipent.

The <header-options> parameter provides control over various features of this header.

At present there is only one option, which is to indicate the sender's SASL authentication status as reported by the MTA:

header-options=0
    ignore SASL authentication status (default)

header-options=1
    if the sender successfully signed in then insert a tag of the form "(Authenticated sender: user@domain)" in the received header.

The latter behaviour emulates Postfix's "smtpd_sasl_authenticated_header" option. It enables a (suitably configured) spam detection backend to apply different rules for trusted senders.

FILES

/etc/smtp-vilter/smtp-vilter.conf
    Default location of the smtp-vilter configuration file.

/tmp/vilter.XXXXXXXXXX
    Naming pattern of temporary files.

/var/run/smtp-vilter.sock
    Default location of the local socket to communicate with sendmail.

/etc/mail/sendmail.cf
    Default location of the sendmail configuration file.

/etc/hosts
    Host name database.

SEE ALSO
smtp-vilter.conf(5)

HISTORY
smtp-vilter was developed on OpenBSD 3.3.

AUTHORS
smtp-vilter was written by Marc Balmer <marc@msys.ch>

CAVEATS

  Security Considerations
smtp-vilter must not be run as the root user. It may, however, be started by the root user in which case it will drop its privileges during startup by changing its user id and optionally its group id to a user defined value. To further enhance security smtp-vilter can chroot to a user defined directory.

  Things to remember when running as non-root
smtp-vilter creates a socket and a file containing its process id at startup. Make sure the corresponding user definable paths point to a location where the user smtp-vilter runs as has write permission. smtp-vilter creates a temporary file for each message which is handed over to the virus scanning engine by a backend. In a situation where the backend merely instructs the scan engine to scan the temporary file it must be made sure that the scan engine has read access to the file, e.g. by having both smtp-vilter and the virus scan engine run as the same user or at least use the same group id and enable the .Dq group readable temp file feature.

  Things to remember when running in a chroot environment
When smtp-vilter runs chrooted it will probably access temporary files under a different path that your virus scanning backend. If the scan engine accesses the files to scan with their real path, set the option “chroot-scanrealpath” in the backends config file (if appropriate). Note that you can not chroot smtp-vilter to directory A and the scan engine to directory B and use filesystem based scanning. If both smtp-vilter and the scan engine are chrooted to different directories, they must communicate using TCP/IP sockets.