.\" $Id: mimedefang.8.in,v 1.22 2005/10/14 16:16:54 dfs Exp $ .\"" .TH MIMEDEFANG 8 "8 February 2005" .UC 4 .SH NAME mimedefang \- Sendmail MIME mail filter .SH SYNOPSIS .B mimedefang \fR-p \fIconnection\fR -m \fImx_socket_name\fR -U \fIuser\fR [\fIoptions\fR] .SH DESCRIPTION \fBmimedefang\fR is a filter built around Sendmail 8.11's \fImilter\fR API for mail filters. It collects each incoming message and runs a filter on the message. This is useful for deleting attachments which may be a security risk on poorly-designed systems like Microsoft Windows. \fBmimedefang\fR does not actually run the Perl filter; instead, it communicates with \fBmimedefang-multiplexor\fR(8), which manages a pool of persistent Perl processes. See the \fBmimedefang-multiplexor\fR man page for additional information. .SH OPTIONS .TP .B \-U \fIuser\fR Runs \fBmimedefang\fR as \fIuser\fR rather than \fIroot\fR. The \fIuser\fR argument must match the argument to \fBmimedefang-multiplexor\fR's \fB\-U\fR option as well. .TP .B \-z \fIspooldir\fR Set the spool directory to \fIspooldir\fR. If this option is omitted, the spool directory defaults to @SPOOLDIR@. .TP .B \-p \fIconnection\fR The \fB\-p\fR switch is required and specifies the \fImilter\fR connection type. Typically, you should run \fBmimedefang\fR on the same computer as \fBsendmail\fR. Therefore, you should use a UNIX-domain socket for the connection type. The suggested value for the \fB\-p\fR switch is \fBmimedefang.sock\fR under the spool directory. .TP .B \-m \fImx_socket_name\fR Specifies the socket for communicating with \fBmimedefang-multiplexor\fR(8). The \fImx_socket_name\fR specifies the path of the UNIX-domain socket. See \fBmimedefang-multiplexor\fR(8) for details. .TP .B \-b \fIbacklog\fR Sets the "backlog" argument to the \fBlisten\fR(2) system call to \fIbacklog\fR. If this option is omitted, then the operating-system default backlog is used. .TP .B \-d The \fB\-d\fR switch causes \fBmimedefang\fR \fInot\fR to delete the temporary spool files it creates for incoming messages. This is for debugging purposes only and should \fInever\fR be used on a production mail server. .TP .B \-r Causes \fBmimedefang\fR to perform a relay check before processing the message body. It calls into a user-supplied Perl function called \fBfilter_relay\fR with the IP address and host name of the sending relay. (See \fBmimedefang-filter\fR(5) for details.) This flag \fIonly takes effect if the \-m flag is used also\fR. .TP .B \-s Causes \fBmimedefang\fR to perform a sender check before processing the message body. It calls into a user-supplied Perl function called \fBfilter_sender\fR with the envelope address of the sender. (See \fBmimedefang-filter\fR(5) for details.) This flag \fIonly takes effect if the \-m flag is used also\fR. .TP .B \-t Causes \fBmimedefang\fR to perform recipient checks before processing the message body. It calls into a user-supplied Perl function called \fBfilter_recipient\fR with the envelope address of each recipient. (See \fBmimedefang-filter\fR(5) for details.) This flag \fIonly takes effect if the \-m flag is used also\fR. .TP .B \-q Permits the multiplexor to queue new connections. See the section QUEUEING REQUESTS in the mimedefang-multiplexor man page. .TP .B \-k Causes \fBmimedefang\fR \fInot\fR 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. \fBmimedefang\fR logs the directory containing the failed message using syslog. .TP .B \-P \fIfileName\fR Causes \fBmimedefang\fR to write its process-ID (after becoming a daemon) to the specified file. .TP .B \-C Conserve file descriptors by opening and closing disk files more often. (Disk files are never held open across Milter callbacks.) While this shortens the length of time a file descriptor is open, it also leaves more opportunities for the open to fail. We do not recommend the use of this flag except on very busy systems that exhibit failures due to a shortage of file descriptors. .TP .B \-T Causes \fBmimedefang\fR to log the run-time of the Perl filter using syslog. .TP .B \-x \fIstring\fR Add \fIstring\fR as the content of the X-Scanned-By: header. If you set \fIstring\fR to the empty string (i.e. \-x ""), then no X-Scanned-By: header will be added. .TP .B \-X Do not add an X-Scanned-By: header. Specifying \-X is equivalent to specifying \-x "". .TP .B \-D Do not fork into the background and become a daemon. Instead, stay in the foreground. Useful mainly for debugging or if you have a supervisory process managing \fBmimedefang\fR. .TP .B \-M When \fBmimedefang\fR processes a message, it creates a temporary working directory. On some architectures, you might have to protect this action with a "mutex" to stop different threads from interfering with each other. This should not normally be necessary, but if you see many logs that \fBmimedefang\fR is unable to create the working directory, use the \-M flag. .TP \-S \fIfacility\fR Specifies the syslog facility for log messages. The default is \fImail\fR. See \fBopenlog\fR(3) for a list of valid facilities. You can use either the short name ("mail") or long name ("LOG_MAIL") for the facility name. .TP \-a \fImacro\fR Pass the value of the specified Sendmail macro through to the Perl filter. You can repeat the \-a option to write more macros than the built-in defaults. Note that in addition to asking \fBmimedefang\fR to pass the macro value to the filter, you must configure Sendmail to pass the macro through to \fBmimedefang\fR using the confMILTER_MACROS_ENVFROM definition in Sendmail's m4 configuration file. .TP .B \-h Print usage information and exit. .SH OPERATION When \fBmimedefang\fR starts, it connects to \fBsendmail\fR using the \fImilter\fR API. (See the Sendmail 8.11 documentation.) For each incoming message, \fBmimedefang\fR creates a temporary directory and saves information in the directory. When the end of message is received, \fBmimedefang\fR executes the following command: .P /usr/bin/perl /usr/local/bin/mimedefang.pl \fIdir\fR .P (Substitute the appropriate paths on your system for \fBperl\fR and \fBmimedefang.pl\fR.) The single argument \fIdir\fR is the temporary directory in which the message information has been saved. (If you are using \fBmimedefang-multiplexor\fR, the multiplexor manages a pool of persistent Perl processes, and \fBmimedefang\fR itself does not start a Perl interpreter.) .P When the Perl script is started, the temporary directory contains certain files; details of the communication protocol between \fBmimedefang\fR and the Perl script are in \fBmimedefang-protocol\fR(7). .SH WARNINGS \fBmimedefang\fR 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 \fIno responsibility\fR for lost or mangled e-mail messages or any security holes this script may introduce. .P Spawning a Perl process for each incoming piece of SMTP mail is expensive. \fBmimedefang\fR may overload a busy mail server unless you use the multiplexor. .SH AUTHOR \fBmimedefang\fR was written by David F. Skoll . The \fBmimedefang\fR home page is \fIhttp://www.mimedefang.org/\fR. .SH SEE ALSO mimedefang.pl(8), mimedefang-filter(5), mimedefang-multiplexor(8), mimedefang-protocol(7)