MIMEDEFANG(8)

NAME
mimedefang - Sendmail MIME mail filter

SYNOPSIS
mimedefang -p connection [-n max_filters]

DESCRIPTION
mimedefang is a filter built around Sendmail 8.11's milter API for mail filters. It collects each incoming message and runs a Perl filter on the message. This is useful for deleting attachments which may be a security risk on poorly-designed systems like Microsoft Windows.

OPTIONS

-U user
    Runs mimedefang as user rather than root. All filters are run as user, not root as well.

-p connection
    The -p switch is required and specifies the milter connection type. Typically, you should run mimedefang on the same computer as sendmail. Therefore, you should use a UNIX-domain socket for the connection type. The suggested value for the -p switch is /var/spool/MIMEDefang/mimedefang.sock.

-n max_filters
    Because each incoming e-mail message forks a new Perl process, you can limit the number of concurrent processes to max_filters using the -n option. The default limit is 10 to prevent your mail server from being overwhelmed if a flood of e-mail messages is sent.

-m pathname
    Instead of executing the Perl filter directly, communicate over a socket to mimedefang-multiplexor(8). The pathname specifies the path of the UNIX-domain socket. See mimedefang-multiplexor(8) for details. Use of the -m option overrides the -n and -f options; these options are controlled by mimedefang-multiplexor.

-d  The -d switch causes mimedefang not to delete the temporary spool files it creates for incoming messages. This is for debugging purposes only and should never be used on a production mail server.

-f filter_path
    Normally, mimedefang executes a Perl filter script called mimedefang.pl to scan the e-mail. However, you can have it execute any program you like by specifying the full path to the program with the -f option. This program must obey the protocol documented in mimedefang-protocol(7); see that manual page for details. Note that the -f option does not specify the "filter" to use with mimedefang.pl; instead, it specifies the program for mimedefang to execute. You almost certainly should not use this option unless you wish to replace mimedefang.pl with your own program.

-F rules_path
    Specifies the path to the filter rules. By default, /usr/local/etc/mimedefang/mimedefang-filter is used. If you use the -F option, its value is passed to the underlying Perl filter program using -f. If you are using mimedefang-multiplexor, this option is ignored; you should use the multiplexor's -F option in its place.

-r  Causes mimedefang to perform a relay check before processing the message body. It calls into a user-supplied Perl function called filter_relay with the IP address and host name of the sending relay. (See mimedefang-filter(5) for details.) This flag only takes effect if the -m flag is used also.

-s  Causes mimedefang to perform a sender check before processing the message body. It calls into a user-supplied Perl function called filter_sender with the envelope address of the sender. (See mimedefang-filter(5) for details.) This flag only takes effect if the -m flag is used also.

-t  Causes mimedefang to perform recipient checks before processing the message body. It calls into a user-supplied Perl function called filter_recipient with the envelope address of each recipient. (See mimedefang-filter(5) for details.) This flag only takes effect if the -m flag is used also.

-k  Causes mimedefang not to delete working directories if a filter fails. This lets you obtain the message which caused the filter to fail and determine what went wrong. mimedefang logs the directory containing the failed message using syslog.

-P fileName
    Causes mimedefang to write its process-ID (after becoming a daemon) to the specified file.

-h  Print usage information and exit.

OPERATION
When mimedefang starts, it connects to sendmail using the milter API. (See the Sendmail 8.11 documentation.) For each incoming message, mimedefang creates a temporary directory and saves information in the directory. When the end of message is received, mimedefang executes the following command:

    /usr/bin/perl /usr/local/bin/mimedefang.pl dir

(Substitute the appropriate paths on your system for perl and mimedefang.pl.) The single argument dir is the temporary directory in which the message information has been saved.

When the Perl script is started, the temporary directory contains the following files:

INPUTMSG
    The input message including mail headers.

HEADERS
    Just the mail headers from the message.

RECIPIENTS
    All the envelope recipients, one recipient to a line

SENDER
    The sender (a single-line).

UNFINISHED
    An empty file. The Perl script must delete this file to indicate successful completion.

The Perl script runs and takes information from these four files. After it has finished, it should delete UNFINISHED and communicate results back to mimedefang as follows:

o   If the file BOUNCE exists in dir, then it should contain a single-line error message. This error message is returned to the MTA which initiated the SMTP connection with an SMTP code of 554 and a DSN code of 5.7.1. If BOUNCE exists, the message is bounced and is never seen by any of the intended recipients.

o   If the file DISCARD exists in dir, then the message is silently discarded. It is never seen by any of the intended recipients, nor is the sender notified that it was discarded.

o   If the file CHANGED exists in dir, then the entire body of the mail message (but not the headers) is replaced with the contents of the file NEWBODY (which should obviously exist in dir.)

o   If CHANGED does not exist, the message is allowed through to its intended recipients unchanged. If UNFINISHED still exists, a warning header is added, but the message is still allowed through. This means that syntax errors in the Perl script allow mail through without filtering. This was considered more polite than bouncing or dropping the messages.

WARNINGS
mimedefang does violence to the flow of e-mail. The Perl filter is quite picky and assumes that MIME e-mail messages are well-formed. While I have tried to make the script safe, I take no responsibility for lost or mangled e-mail messages or any security holes this script may introduce.

Spawning a Perl process for each incoming piece of SMTP mail is expensive. mimedefang may overload a busy mail server.

mimedefang uses a "for future release" feature of Sendmail 8.11. The milter API may change in the future, necessitating a rewrite of mimedefang.

AUTHOR
mimedefang was written by David F. Skoll <dfs@roaringpenguin.com>. The mimedefang home page is http://www.roaringpenguin.com/mimedefang/.

SEE ALSO
mimedefang.pl(8), mimedefang-filter(5), mimedefang-multiplexor(8), mimedefang-protocol(7)